谷雨AI实验室
网站导航
← 返回资料库

Agent 工具太多记不住？一张注册表自动同步

用插件触发加脚本同步维护 Agent/Skill 工具注册表，md5 对比判断条目「新增」、「变更」、「废弃」状态，且用户改动的内容不被脚本同步所覆盖

#Agent
发布于 下载 Markdown下载资源包
目录

用「插件触发 + 脚本同步」，让 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 项目，对构建流程标准化有要求的个人或团队知识库。

注册表效果预览

二、操作步骤

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

(一) 资源包构成

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

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 强制登记注册表

调用关系

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 天未更新则输出提醒；

相关文章