soia-dev-doc-sync

客户可读说明

这个技能可以做什么

把代码、版本元数据、发布记录等明确真源与 docs/、README、CHANGELOG、VERSION 等派生文档逐项对账，报告事实漂移并在授权范围内修复。

客户如何使用

提供目标仓库、待检查的文档范围，以及已知的真源（例如 manifest、版本文件、release note、API schema、测试或生成输出）。若真源优先级不明确，先确认，不用旧文档互相佐证。

涉及覆盖、删除、发布或远端状态时，先展示目标、影响和补丁预览并取得确认。普通单篇创作、纯翻译或不需要事实对账的文案不触发本技能。

依赖与安装

安装：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-doc-sync -y

强依赖：目标仓库及其真源文件的只读访问。可选使用项目已有的 lint、测试、生成器或链接检查器；缺少时如实报告未覆盖的验证面。

本技能无需私有配置。用户特定路径只在本次参数或环境中提供，不写入技能。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

私密信息与中间数据

• 真源、派生文档和 diff 可能包含未公开产品信息；只读取本次对账范围，不把全文复制到公共示例、临时报告或回执。
• 文档补丁和用户要求的交付物写回目标仓库或用户指定路径；本技能不建立独立的持久 state、cache 或影子文档库。
• 生成器、链接检查器等工具的中间文件服从目标仓库约定；否则放入操作系统临时目录，并在确认不属于项目产物后清理。
• Provider 凭据留在官方登录态或系统凭据库。普通 config.yml 只能保存非秘密路径或偏好，不能保存 API key、cookie、session 或文档正文。
• 回执只保存 finding 的最小证据、变更路径和验证摘要；需要引用敏感内容时先脱敏。

日志与完成回执

完成：<审计或同步的结果>。

真源与范围：<已核实的真源及派生文档范围>
发现：<类别、数量、证据摘要>
文件变化：<更新的文档类别；无改动则写“无”>
验证：<运行的检查及结果>
残余风险：<未验证真源、无法访问的输入或“无”>

触发条件

• 发布、版本升级、架构或 API 变更后需要回填文档；
• README、CHANGELOG、VERSION、架构说明或多语言页面可能处于不同事实时间切片；
• 用户要求“doc sync”“文档对账”“检查 docs 是否漂移”。

真源优先级

在开始前为本次任务写出真源表。推荐的默认顺序是：

1. 可执行或机器可读的事实：代码、schema、manifest、锁定版本、生成输出、测试结果；
2. 明确维护的发布事实：版本文件、签发的 release note、变更记录；
3. 已审阅的设计或决策记录；
4. README、指南、架构说明、导出页等派生叙述。

项目可以定义更高优先级的权威来源；遵守它。若两个同级真源冲突，停止自动回填，报告冲突的文件、字段和最小复核路径。绝不为了让文档一致而修改真源。

漂移分类

• status-drift：生命周期或支持状态不一致；
• coverage-gap：真源已有功能、版本或变更，派生文档漏记；
• version-drift：版本号、发布日期或兼容范围不一致；
• release-drift：release note、CHANGELOG 和版本时间线互相矛盾；
• structural-drift：模块、命令、接口、配置项或数量仍是旧事实；
• bilingual-drift：不同语言页面处于不同事实切片；
• historical-snapshot-gap：历史快照没有标示其时点和当前真源；
• link-or-reference-drift：引用目标已改名、删除或不再是权威来源。

每项 finding 都要记录：真源位置和摘录、派生位置和摘录、预期、观察到的值、建议动作。把“推断”与“已验证事实”分开写。

标准流程

1. 限定范围：列出本次要对账的文档、语言版本、版本窗口和不可改动边界。
2. 读取最小真源集合；先执行项目已有的生成、lint 或测试命令（只读/无副作用时）。
3. 建立事实表：每个事实都映射到一个权威来源和所有派生消费者。
4. 运行自动检查（若有），但逐项人工验证高影响 finding；工具返回 0 不是“没有漂移”的证据。
5. 按依赖顺序修复：真源冲突先解决；随后版本/发布事实；再摘要页、README、导出页和翻译页。派生层不得领先于上游事实。
6. 重跑相关检查，并从另一条路径复核关键数字、链接、版本和示例命令。
7. 输出回执；未验证的语言、生成物或外部页面必须明确列为残余风险。

写后验证契约

• 每个改动必须可追溯到本次真源或明确的用户决定；
• 版本号、日期、数量、命令和链接独立复核一次；
• 改一处漂移后，搜索同一术语、版本或旧标识在相邻文档中的其他实例；
• 只在实际运行过检查时报告通过；未运行则说明原因与可执行命令；
• 保持内容分层：事实更新、解释性文本和历史快照不能混成一个无来源的叙述。

安全边界

• 不将派生文档反向视为真源；
• 不虚构发布状态、测试结论、支持承诺或未验证的产品行为；
• 不在未获授权时发布、发送、覆盖远端文档或修改版本标签；
• 不把本机路径、账号、密钥、私有 workspace 或组织内部流程写进可复用文档。

验证

• 静态：运行目标仓已有文档、链接、格式或生成检查；
• 内容：抽样核对每类 finding 的真源—派生映射，并重新搜索旧值；
• 回归：确认改动没有让同语言或跨语言页面产生新的版本、链接或术语漂移。