SuperAPI AI 工具集

vault-sync

写作与研究

查看项目

更新于 10-15 20:09

技能介绍

用途:让 OKF 知识库随代码演进保持真实。知识库是系统的地图,该技能检测地图与实地之间的漂移,仅重新生成受影响的概念,并记录同步。

适用时机:合并重大变更(schema、公共接口、CI 工作流、智能体或技能配置)后;到期进行陈旧性审查时(stale-concepts Base 即队列);用户要求同步、刷新或更新知识库时;怀疑某概念有误时。

关键文件:<vault>/_meta/vault-config.json(机器可读约定)、CONVENTIONS.md(人类可读规则)、manifest.json(ID 注册表、反向索引、baseline_sha 漂移水位)、templates/(各类型骨架)、log.md(带日期变更日志)、knowledge-vault/scripts/validate-vault.mjs(校验门)。

流程:1) 检测漂移:读取 baseline 并与 HEAD 在 watch-list 上做 diff,概念陈旧当且仅当变更路径匹配其 resource 或 sources 条目;先查 manifest,再 grep frontmatter 作后备。2) 检测清单变化:重新枚举源 glob 并与 manifest 对比;新源无概念则先加 manifest 条目再创建概念;源被删除则将概念 status 设为 deprecated,不删文件,入站链接需在后续变更中先清理。3) 重新生成:少量概念就地更新,大量则按区域分批由生成智能体展开;每个生成提示必须携带类型模板、同类型黄金示例、CONVENTIONS.md 硬规则、manifest ID 注册表;每个被触及概念更新 timestamp 与 verified_against;必须从源文件重新推导事实。4) 校验:运行 node knowledge-vault/scripts/validate-vault.mjs --vault <vault>,必须退出 0,Markdown lint 必须通过。5) 记录:在 log.md 前插带日期条目,说明变更、原因(工单)与源 SHA,然后更新 manifest 的 baseline_sha 与 generated。

不变量:概念间链接不得离开 bundle;仅用相对 Markdown 链接;只链接 manifest 中的 ID;每文件一个概念;H2 章节严格按类型模板顺序;stub 类型引用其真源文档而不复述;引用不等于重新验证。

反模式:仅文档遍历时更新 timestamp;源消失时删除概念;漂移时重新生成整个知识库;不读代码就修补文字;因“只是文档”跳过校验器。

限制:该技能使用 {{PLACEHOLDER}} 模板令牌,使用前需替换为项目值;watch-list 等需按项目配置。