用「插件触发 + 脚本同步」，让 opencode 项目里的 agent、skill、command 清单永远跟 `.opencode/` 目录下的真实配置保持一致：新增自动登记、变更自动更新、删除自动标记废弃，且用户改动的内容不被脚本同步所覆盖。

---

## 一、功能与效果

**解决的问题**

  1. agent/skill 缺少统一索引：agent/skill 越建越多，想不起来有哪些、各自干什么、怎么触发；
  2. 漏登记：新建的 agent、skill、command 缺少固定流程，建完就忘；
  3. agent/skill与脚本关系不透明：command 到 agent、agent 到 script 的调用链靠人脑记忆难以理解。

**处理逻辑**

* 插件内置监视器捕获 `.opencode/` 下配置变更并触发同步脚本，脚本以 md5 对比区分新增、更新、废弃三条路径后重写注册表。

**产出形态 & 适用范围**

一张自动维护的注册表，含全部 agent/skill/command 条目的大表格与调用关系说明，新增条目默认状态为试用，经人工确认后转活跃，条目编号排序按该类型（A/S/C）现有最大编号+1递增。适用于agent、skill、command 数量超过 5 个且会持续新增的 opencode 项目，对构建流程标准化有要求的个人或团队知识库。

![注册表效果预览](assets/registry-table.png)

## 二、操作步骤

> 请先下载文章开始链接中的`agent-registry-sync.zip`资源包，并将包内的子文件提取到相应文件目录。

### (一) 资源包构成

> 解压后对照本节逐项放置。单个压缩包不超过 25MB，超出时将拆分分卷或将大文件移至网盘并在正文中给出链接。顶层以 `agent-registry-sync` 命名，内部即目标相对路径，解压后原样复制到库根目录。

```text
agent-registry-sync/
└── .opencode/
    ├── plugins/
    │   └── registry-sync.ts             # 插件：内置fs.watch，递归监视.opencode/{agents,commands,skill}变更
    ├── scripts/
    │   └── registry_sync.py             # 同步脚本：扫描配置 → md5 对比 → 新增/更新/废弃标记 → 重写注册表
    ├── commands/
    │   └── registry-update.md           # 手动兜底：使用 /registry-update 命令随时触发一遍同步
    └── skill/
        └── build-agent-skill/           
            └── SKILL.md                 # Skill：构建流程标准化文档
```

### (二) 前置条件

- opencode 版本支持 `.opencode/plugins/` 目录自动加载（2026 版插件机制，详见官方插件文档）；
- 系统可用 `python3`；
- 项目为 git 仓库（可选但推荐，便于回滚注册表）；
- 无需开启任何实验开关或设置环境变量：插件内置 `fs.watch` 直接监视目标目录，不依赖 opencode 默认的文件监视范围。

### (三) 操作步骤/功能验证

**验证同步脚本「新增」、「变更」、「废弃」文件功能加幂等测试**

1. **新增文件**：在 `.opencode/agents/` 新建测试文件后使用`/registry-update`跑脚本，输出「新增 1」，注册表出现该行，其中`编号`为A*，自动填写表格内所有属性（`名称`、`类型`、`功能描述`等）`使用范围`为待补充，`状态`为试用）。
2. **变更文件**：修改测试文件 `description` 后跑脚本，输出「更新 1」，注册表该行`功能描述`与`最近更新`内容刷新，`使用范围`、`执行频率`与`状态`列保留用户自定义数值，不随脚本刷新。
3. **删除文件**：删除测试文件后跑脚本，输出「废弃 1」，注册表该行状态变为`已废弃`，记录保留。
4. **幂等**：连续跑两次脚本，第二次输出注册表已是最新、无变更。

### (四) 常见问题

* **插件生效时机**：插件在 opencode 启动时加载，改完插件必须重启会话；重启前自动维护不生效，靠 `/registry-update` 手动兜底；插件启动时会自动补一次同步，所以服务器离线期间的改动在下次启动时会被补上；
* **状态（试用→活跃）**：新增条目默认「试用」，逼用户在确认可用后手动转正，防止未验证的工具混入活跃清单；
* **使用范围/执行频率**是语义信息，脚本无依据推断故永不覆盖；描述/触发/关联可从配置推导故自动维护；

### (五) 架构解析

**文件职责**

| 文件                           | 职责          | 关键操作                                                            |
| ---------------------------- | ----------- | --------------------------------------------------------------- |
| 注册表文件（自动生成）                  | 唯一数据源加人阅读索引 | 表格行按文件路径列索引，frontmatter 的 `_sync` 存各 agent/skill/comamnd 配置 md5 |
| `registry-sync.ts`           | 事件触发器       | 递归监视三类目录，`.md` 过滤，2 秒防抖，启动补同步，只调脚本不直接写注册表                       |
| `registry_sync.py`           | 同步脚本        | 扫描、解析、md5 对比、三分支处理（新增/变更/废弃）、重写注册表                              |
| `registry-update.md`         | 手动兜底入口      | 说明文加引导用户确认自定义新条目                                                |
| `build-agent-skill/SKILL.md` | 构建流程标准化     | 构建新 Agent/Skill/Command 的标准流程，STEP 5 强制登记注册表                    |

**调用关系**

```text
fs.watch 递归监视 .opencode/{agents,commands,skill}
        │  (node:fs watch，插件内置，不依赖 opencode 实验开关)
        ▼
registry-sync.ts（插件：.md 过滤 + 2s 防抖 + 启动补同步）
        │  python3 调用
        ▼
registry_sync.py（同步脚本：md5 对比 + 三分支）◀── 调用 ── /registry-update（手动命令）
        │  读写                              ◀── 调用 ── build-agent-skill（构建流程 STEP 5）
        ▼
_AGENT-SKILL-REGISTRY.md（注册表）
```

## 三、参考与进阶

**其他进阶功能**（问询让AI直接帮你实现）

* 新增一种资产类型（如 scripts/plugins等）加入到注册表；
* 改变表格的列结构；
* 换触发源（定时触发脚本）；
* 按 `执行频率` 字段驱动提醒，例如读「执行频率=每周」的条目，超过 7 天未更新则输出提醒；