clonedeps

Clonedeps 技能

帮助用户将少量重要的依赖源代码仓库克隆到本地，以便 OpenCode 可以读取。

这是一项工作流技能，不是命令包装器。不要使用辅助脚本进行依赖检测、引用验证、克隆、状态检查或清理。编排器和 @librarian 负责特定仓库的分析；编排器直接执行已获批准的文件系统和 git 操作。

工作流

步骤 1：检查现有状态

首先检查 .slim/clonedeps.json 是否存在。

如果存在：

1. 在询问 librarian 制定新计划之前，先读取该文件。
2. 检查其中列出的每个 path 是否存在于 .slim/clonedeps/repos/ 下。
3. 如果现有克隆仓库已能满足用户的任务，则重复使用。
4. 只有在现有清单缺失、已过时或无法满足当前任务时，才请 librarian 提供新的建议。

如果清单中已有可用条目，不要从头重新扫描或规划。

步骤 2：请 Librarian 制定克隆计划

将依赖发现和源代码解析委托给 @librarian。

使用以下提示词：

Understand this project first, then recommend remote source repos that would
help a developer work on it.

Read enough of the current repo to understand:
- what the project does
- its main architecture
- the important integration points
- what external systems or libraries it depends on in practice

Think like a developer trying to debug or extend this project.

Which remote repositories, if cloned locally, would actually help understand the
codebase or solve likely implementation/debugging tasks?

Do not make a dependency dump. Most dependencies are not worth cloning.
Recommend a repo only when its source code would be more useful than docs or the
current repo alone.

For each recommendation, include:
- repo name
- repo URL
- suggested ref/tag/commit if known
- why cloning this source would help
- when it would be useful
- caveats

Also include:
- current-repo files/folders to inspect first
- repos/dependencies you considered but would not clone

Keep it small. Prefer 0–3 strong recommendations over 5 weak ones. If nothing
clearly needs cloning, say so.

Librarian 应返回一份精简计划，包含：

• 依赖名称；
• 可查明时提供当前版本或版本范围；
• 官方源代码仓库 URL；
• 要检出的标签、提交或引用；
• 如果源代码位于单体仓库中，提供包所在的子目录；
• 本地源代码有帮助的原因；
• 注意事项，例如仓库过大、缺少标签或版本映射不确定。

核心依赖优先控制在 3-5 个以内。包括用户提及的依赖和核心框架、SDK、ORM、运行时或插件 API，或构建与运行时工具。除非与当前任务直接相关，否则不要克隆小型工具、传递依赖或仅用于开发的工具。

步骤 3：验证并确认计划

最终审批由编排器负责。克隆前：

1. 尽可能使用 git ls-remote 手动验证引用。
2. 优先使用固定标签或提交 SHA。如果没有完全匹配的标签，请 librarian 查找正确的模块专用标签或提交，或说明备用方案。
3. 默认只使用 HTTPS GitHub/GitLab 风格的仓库 URL。拒绝 file://、SSH URL、本地路径、嵌入凭据的 URL，以及私有或需要身份验证的仓库，除非用户明确批准这种情况。
4. 向用户展示计划，包含依赖、仓库 URL、引用、原因和注意事项。
5. 除非用户明确要求立即克隆，否则在通过网络克隆前先征求确认。

步骤 4：更新忽略文件

在克隆文件或清理已克隆依赖之前，检查现有的 .gitignore 和 .ignore。如果存在托管区块，则在原处更新；否则追加。只添加以下缺少的准确行，绝不重复条目或修改无关规则。这些区块可确保克隆的文件仅保留在本地 Git 工作区，而 .ignore 允许列表则确保 OpenCode 可以读取这些文件。

.gitignore：

# BEGIN oh-my-opencode-slim clonedeps
.slim/clonedeps/repos/
# END oh-my-opencode-slim clonedeps

.ignore：

# BEGIN oh-my-opencode-slim clonedeps
!.slim/
!.slim/clonedeps.json
!.slim/clonedeps/
!.slim/clonedeps/repos/
!.slim/clonedeps/repos/**
.slim/clonedeps/repos/**/.git/
.slim/clonedeps/repos/**/.git/**
# END oh-my-opencode-slim clonedeps

步骤 5：手动克隆源代码

在以下路径下为每个源代码仓库创建一个文件夹：

.slim/clonedeps/repos/<safe-repo-name>/

根据仓库所有者/名称生成安全名称，而不是根据包名称生成。 例如，https://github.com/opencode-ai/opencode.git 应转换为 opencode-ai__opencode。将 / 替换为 __，去掉常见的 .git 后缀， 并将其他不安全的路径字符替换为 _。

如果多个包来自同一个 monorepo，只克隆一次仓库，并让各清单条目指向同一个仓库路径，按需使用不同的 packagePath 值。不要创建生态系统文件夹、每个包单独的克隆文件夹或每个版本单独的文件夹。如果两个不同的源代码仓库规范化后得到相同的安全名称，请手动区分，并在 .slim/clonedeps.json 中记录所选路径。

使用常规 git 命令进行克隆/获取。对于现有克隆，先确认 git remote get-url origin 与获批的仓库 URL 相符。如果不符，请停止并询问是否清理后重新克隆。

安全的手动 git 操作模式：

1. 在可行时，使用 git ls-remote <repoUrl> <ref> 验证引用。
2. 克隆时不要使用子模块/递归行为。
3. 在可行时，优先使用浅克隆/浅获取。
4. 克隆到 .slim/clonedeps/repos/ 下的临时目录，检出成功后再将其移至最终的安全名称路径。
5. 删除失败的临时克隆。

不要运行克隆的仓库中的依赖安装/构建/测试脚本。

步骤 6：写入本地状态

写入 .slim/clonedeps.json，以便未来的 Agent 了解已有内容：

{
  "version": "1.0.0",
  "updatedAt": "2026-05-12T00:00:00.000Z",
  "dependencies": [
    {
      "name": "@opencode-ai/plugin",
      "resolvedVersion": "1.3.17",
      "repoUrl": "https://github.com/opencode-ai/opencode.git",
      "ref": "v1.3.17",
      "path": ".slim/clonedeps/repos/opencode-ai__opencode",
      "packagePath": "packages/plugin",
      "reason": "Plugin API source used by the project"
    },
    {
      "name": "@opencode-ai/sdk",
      "resolvedVersion": "1.3.17",
      "repoUrl": "https://github.com/opencode-ai/opencode.git",
      "ref": "v1.3.17",
      "path": ".slim/clonedeps/repos/opencode-ai__opencode",
      "packagePath": "packages/sdk/js",
      "reason": "Core SDK source used to inspect runtime behavior"
    }
  ]
}

如果某次克隆失败，但之前已有克隆成功，仍要为成功的克隆写入状态，避免误导未来的检查。

不要将 .slim/clonedeps.json 添加到 .gitignore。这是体积小、便于审查的项目元数据，可以提交。只应忽略 .slim/clonedeps/repos/ 下克隆的仓库内容。

步骤 7：在 AGENTS.md 中登记依赖源

克隆成功后，更新仓库根目录下的 AGENTS.md，让未来的 Agent 知道依赖源存在的原因以及查看位置。

如果 AGENTS.md 中已有 ## Cloned Dependency Source 部分，请更新该部分。否则，追加以下部分：

使用此格式并直接列出实际仓库。每项只写一个简短句子，以便未来的 Agent 无需额外阅读就能了解其中内容：

## Cloned Dependency Source

Read-only dependency source repositories are available under
`.slim/clonedeps/repos/` for inspection. Do not edit these clones.

- `.slim/clonedeps/repos/<safe-name>/` - `<repo>` at `<ref>`; <one sentence on
  why this source is useful>.
- `.slim/clonedeps/repos/<safe-name-2>/` - `<repo>` at `<ref>`; <one sentence on
  why this source is useful>.

同时保持 .slim/clonedeps.json 作为结构化清单同步更新，但不要要求 Agent 为了了解基本仓库列表而阅读它。

清理

用户要求清理克隆的依赖时，请删除：

• .slim/clonedeps/repos/
• .gitignore 和 .ignore 中由工具管理的 clonedeps 标记块

删除 .slim/clonedeps.json 或 AGENTS.md 中的部分之前，请先询问，因为它们可能是有意保留的项目元数据。