本指南说明如何把闭源或工具专属的 agent 工作流转成 OpenCode 原生组件。
若你只想从零装好本套件，请直接看 install-from-scratch.zh-CN.md——产物已经适配好，不必先跑旧工具。
| 源概念 | OpenCode 目标 | 迁移立场 |
|---|---|---|
| Slash command | ~/.config/opencode/commands/*.md |
复制或改写为 OpenCode markdown 命令。 |
| Agent persona | ~/.config/opencode/agents/*.md |
只保留共用行为，去掉私有假设。 |
| Skill | ~/.agents/skills/<name>/SKILL.md |
通过语法与 transport 兼容检查后，复制进共享 skill 目录。 |
| 项目规则 | AGENTS.md（仓库 / 包 / vault 根） |
仅 OpenCode 原生；不要保留其它旧规则文件名。 |
| MCP server | opencode mcp add <name> |
通过 OpenCode 配置，不要发布 live JSON。 |
| Plugin | TUI /plugin 流程 |
原生安装并文档化所需设置。 |
| Provider / 模型路由 | OMOS 配置 | 发布占位与理由，不发布 live 路由文件。 |
- 盘点源 commands、agents、skills、plugins、MCP。
- 把工具专属语法与命名换成 OpenCode 兼容表述。
- 把项目规则统一到
AGENTS.md（见下）。 - 把打包产物拆进小型、有文档的仓库（上游适配 + RAFA 内部件）。
- 生成的运行时配置保持私有。
- 每次公开发布前做安全扫描。
OpenCode 规范的项目规则文件名是 AGENTS.md。
本套件不再文档化或维护其它旧工具的规则文件名。配套仓库中的 commands / skills / docs 假定：
| 层 | 规范路径 |
|---|---|
| 全局默认 | ~/.config/opencode/AGENTS.md |
| 项目 / 包 / vault | ./AGENTS.md（以及嵌套包的 AGENTS.md） |
| 个人覆盖 | ./.agents.local.md（gitignore） |
- command-kit（
/agents-md-improver、/agents-md-revise、review/architect 等）：只发现并编辑AGENTS.md/.agents.local.md。 - wiki-skills：vault 脚手架与跨项目路由模板只生成 / 引用
AGENTS.md。 - 命名：对模型或运行时称 Agent（或 OpenCode agent），不用厂商产品名当身份。
- compat lint：拒绝不应出现在 OpenCode 产物中的旧 CLI 名、旧规则文件名与厂商产品称呼。
- 在仓库根与嵌套包中查找旧规则文件。
- 若同一目录既有
AGENTS.md又有旧规则文件：把独特内容合并进AGENTS.md，再删除旧文件。 - 若只有旧规则文件：改名为或复制为
AGENTS.md，再删除旧文件。 - 更新仍引用旧文件名的文档、CI、脚本。
- 在 prompts / skill 文本中改用 Agent / OpenCode 表述。
/agents-md-improver— 审计并改进现有AGENTS.md。/agents-md-revise— 把会话学到的约定写入AGENTS.md（或个人用的.agents.local.md）。
除非明确标为历史案例材料并配有迁到 AGENTS.md 的步骤，否则不要把过时工具名、私有 hook、个人路径、provider 专属模型名或旧项目规则文件名带进公开产物。