diff --git a/skills/gitlink-deps/SKILL.md b/skills/gitlink-deps/SKILL.md new file mode 100644 index 0000000..39072dc --- /dev/null +++ b/skills/gitlink-deps/SKILL.md @@ -0,0 +1,97 @@ +--- +name: gitlink-deps +version: 1.0.0 +description: "依赖追踪:扫描仓库的依赖声明文件(go.mod、package.json、requirements.txt、pom.xml、Cargo.toml 等),解析依赖清单、统计数量、识别技术栈、提示版本锁定与供应链风险,生成依赖报告。当用户提到「项目依赖」「用了哪些库」「依赖清单」「技术栈」「go.mod」「package.json」「依赖风险」「dependencies」时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + optional_bins: ["python"] + cliHelp: "gitlink-cli repo --help" +--- + +# gitlink-deps(项目依赖追踪) + +**CRITICAL — 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md),其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`(GitHub CLI)操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。** +**CRITICAL — 本技能全程只读,不修改任何远程数据。** + +> **前置条件:** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。 + +## 何时使用本技能 + +- 用户问「这个项目依赖了哪些库 / 用了什么技术栈」 +- 接手项目前想快速了解依赖规模与构成 +- 想检查依赖是否锁定版本、是否存在供应链风险 +- 需要一份依赖清单用于审计或文档 + +## 何时不使用 + +- 许可证合规 / 敏感信息扫描 → 用 `gitlink-compliance` / `gitlink-license-compliance` +- 仅查看仓库文件结构 → 用 `gitlink-repo` + +## 支持的依赖文件 + +| 文件 | 生态 | 是否解析 | +|------|------|:--------:| +| `go.mod` | Go | ✅ | +| `package.json` | Node.js | ✅ | +| `requirements.txt` | Python | ✅ | +| `Cargo.toml` | Rust | ✅ | +| `pom.xml` | Java (Maven) | ✅ | +| `pyproject.toml` / `Pipfile` / `build.gradle` / `composer.json` / `Gemfile` | 多语言 | 识别存在性 | + +## 工作流:扫描项目依赖 + +### 方式 A:用配套脚本(推荐) + +```bash +# 扫描并输出依赖报告(Markdown) +python scripts/deps.py --owner Gitlink --repo gitlink-cli + +# JSON 输出,供 Agent 进一步处理 +python scripts/deps.py --owner Gitlink --repo gitlink-cli --format json +``` + +参数说明: + +| 参数 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| `--owner` | string | 是* | 仓库所有者(*或用 `--slug`) | +| `--repo` | string | 是* | 仓库名称 | +| `--slug` | string | 否 | `owner/repo` 或完整 URL | +| `--ref` | string | 否 | 分支或标签,默认 master | +| `--format` | string | 否 | `markdown`(默认)或 `json` | +| `--output` | string | 否 | 报告输出文件 | + +### 方式 B:用 gitlink-cli 读取依赖文件 + +```bash +# 读取根目录文件列表,确认有哪些依赖清单 +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=&ref=master' --format json + +# 读取具体依赖文件内容(如 go.mod) +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=go.mod&ref=master' --format json +``` + +## 报告内容 + +- 技术栈识别(依据存在的清单文件) +- 依赖总数、直接/间接依赖区分 +- 直接依赖清单(名称 + 版本 + 生态) +- 风险提示:未锁定版本、依赖数量过多等 + +## API 注意事项 + +- 依赖文件内容通过 `sub_entries` 接口读取(单文件查询会在 `entries` 中返回明文 `content`)。 +- 仅扫描仓库根目录的依赖文件;子目录/多模块项目可能需指定具体路径。 +- 数据采集全程只读。 + +## 输出示例 + +参见 [`examples/`](examples/) 的真实依赖报告。 + +## References + +- [api-reference.md](references/api-reference.md) — 采集接口、字段与输出结构 +- [parsing.md](references/parsing.md) — 各生态解析规则与风险评估规则 +- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则 diff --git a/skills/gitlink-deps/references/api-reference.md b/skills/gitlink-deps/references/api-reference.md new file mode 100644 index 0000000..6891abc --- /dev/null +++ b/skills/gitlink-deps/references/api-reference.md @@ -0,0 +1,53 @@ +# gitlink-deps API 参考 + +> **前置条件:** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。 + +本技能扫描依赖文件所依赖的接口与字段。全程只读。 + +## 采集的接口 + +### 列根目录(发现依赖文件) + +``` +GET /:owner/:repo/sub_entries.json?filepath=&ref={ref} +``` + +从 `entries[].name` 中匹配已知的依赖声明文件名。 + +### 读取依赖文件内容 + +``` +GET /:owner/:repo/sub_entries.json?filepath={manifest}&ref={ref} +``` + +单文件查询时,`entries`(单对象)的 `content` 字段直接是**明文**文件内容。本技能据此读取 go.mod / package.json 等并解析。 + +> 注意:`raw/{path}` 接口对公开仓库可能返回 403,因此读取文件内容统一走 `sub_entries`。 + +## 识别的依赖文件 + +| 文件 | 生态 | 解析 | +|------|------|:----:| +| go.mod | Go | ✅ require 块 | +| package.json | Node.js | ✅ dependencies + devDependencies | +| requirements.txt | Python | ✅ 逐行 | +| Cargo.toml | Rust | ✅ [dependencies] | +| pom.xml | Java (Maven) | ✅ | +| pyproject.toml / Pipfile / build.gradle / composer.json / Gemfile | 多语言 | 识别存在性 | + +## 输出字段(JSON) + +```json +{ + "owner": "...", "repo": "...", + "ecosystems": ["Go"], + "manifests": [{"file": "go.mod", "ecosystem": "Go", "count": 22}], + "total_deps": 22, "direct_count": 7, "indirect_count": 15, + "dependencies": [{"name": "...", "version": "...", "indirect": false, "manifest": "go.mod", "ecosystem": "Go"}], + "risks": ["..."] +} +``` + +## 错误处理 + +沿用 gitlink-shared 错误码。依赖文件不存在或无法解析时跳过,不中断整体扫描。 diff --git a/skills/gitlink-deps/references/parsing.md b/skills/gitlink-deps/references/parsing.md new file mode 100644 index 0000000..7b76dff --- /dev/null +++ b/skills/gitlink-deps/references/parsing.md @@ -0,0 +1,46 @@ +# 依赖解析与风险规则 + +## 各生态解析规则 + +### Go(go.mod) + +解析 `require (...)` 块与单行 `require`。识别 `module path vX.Y.Z` 形式, +带 `// indirect` 标记的归为间接依赖。 + +### Node.js(package.json) + +解析 `dependencies`(直接)与 `devDependencies`(开发依赖,归为间接)。 + +### Python(requirements.txt) + +逐行解析 `pkg==1.0` / `pkg>=1.0` / `pkg` 形式;跳过注释行与 `-e`、`-r` 等选项行。 + +### Rust(Cargo.toml) + +解析 `[dependencies]` 段下的 `name = "version"` 与 `name = { version = "..." }`。 + +### Java(pom.xml) + +正则提取 `` 块的 `groupId:artifactId` 与 `version`。 + +## 风险评估规则 + +| 风险 | 触发条件 | 提示 | +|------|----------|------| +| 版本未锁定 | 依赖版本为 `*` / `latest` / 空,或以 `^` / `~` 开头 | 可能导致构建不可复现,建议锁定精确版本 | +| 直接依赖过多 | 直接依赖 > 50 | 建议定期审查,减少供应链攻击面 | +| 无依赖文件 | 未发现任何清单文件 | 可能是纯文档仓库,或依赖文件不在根目录 | + +无风险命中时输出"未发现明显的依赖风险,依赖声明较为规范"。 + +## 直接 vs 间接依赖 + +- **直接依赖**:项目显式声明、直接使用的依赖。 +- **间接依赖**:被直接依赖引入的传递依赖(go.mod 的 `// indirect`、package.json 的 `devDependencies` 在本工具中归类为非直接)。 + +区分二者有助于评估项目真正掌控的依赖规模。 + +## 局限 + +- 仅扫描仓库**根目录**的依赖文件;多模块 / monorepo 项目的子目录依赖需指定路径。 +- 不解析锁文件(go.sum / package-lock.json)的完整依赖图,聚焦于声明文件中的直接意图。