Skip to content

xinetzone/SpecWeave / .agents/skills/shared-index-atomic-extension

shared-index-atomic-extension

Verified

共享索引下的原子化增量拓展与门禁自洽。当用户说『给这个知识包加一篇文档』『新增一章后要不要改索引』『toctree 里要不要登记』『总索引计数对不上』『提交前门禁红了』『并行会话把我的索引改了』『只提交我这一束行不行』『check-bundles-index 报计数漂移』『新增文档不可达』『shared index 冲突』,或任何在 Sphinx / Docusaurus / GitBook 等带机械门禁与共享目录索引的仓库里增量添加内容、改计数、做提交时,必须使用此技能。核心能力:动笔前枚举全部索引投影面,用现跑脚本而非摘要取计数,把新文档登记进最近一级 toctree 保证可达,用定点精确替换避免覆盖并行会话内容,并把提交批次取为让全部门禁同时自洽的最小文件集合。不适用于纯内容写作、命名合规审计、导出格式转换,以及无机械门禁或无共享索引的单写者仓库。

共享索引下的原子化增量拓展

萃取自 2026-11-06 里程碑复盘:一次公开文章被转化为 OKF 知识包,随后经历跨仓指针闭环与两份进阶算例的拓展接线。 本技能把「文件写好了」与「内容入库了」之间的差距固化成可执行流程。

来源模式与去重声明(2026-11-06 模式沉淀复核):本 Skill 的名称 shared-index-atomic-extension 保留,但不再作为独立模式库条目。同日复核发现,其六步工作流覆盖的洞察分别落在既有 L2 / L1.5 模式内:导航登记事务性同步属 生成-登记同步法(bp-nav-co-registration)、共享索引五面耦合与并批裁决属 共享索引计数耦合与同批判决、状态审计与现跑取证属 Context 恢复协议重执行。本 Skill 是这些模式在「带机械门禁的 Sphinx 知识包增量拓展」这一具体仓库形态下的执行层投影,负责把方法落到九个投影面、取数命令与安全检查清单,不新增模式库条目。完整裁决见 模式沉淀复核裁定报告。

1. Skill ID

shared-index-atomic-extension

2. 这个技能解决什么

在「共享索引 + 机械门禁 + 并行写入」的仓库里,增量内容的原子单位不是文件,而是能让全部门禁同时自洽的最小投影集合。

三个典型失效:

失效症状门禁视角
只落盘不接线新文档内容完整、frontmatter 齐备、互链无误导航 BFS 判为不可达,等同于不存在
照抄旧计数沿用上一轮摘要里的 total_bundles目录树对账门报计数漂移
按单功能提交只提交自己新增的那一束共享索引还承载其他在途束的投影,三套门同时失去自洽

为什么把「投影集合」而不是「文件」当作原子单位? 因为机械门读的是索引与目录树的关系,不是单个文件的内容。一个文件可以完全正确却让门变红,也可以内容平平却让门全绿;验收面在图结构,不在文件质量。

为什么必须先枚举投影面再动笔? 增量改动的成本几乎全在收尾:写正文是一次性的,而目录 index 表格、toctree、阅读顺序、上级计数、上位互链、根级 description、README badge 是七个会各自漂移的面。事后补接线要靠回忆,事前列表靠枚举,后者不会漏。

3. 何时使用本技能

  • 向既有知识包 / 文档站 / 生成型清单增量添加内容文档;
  • 新增或修改后需要判断「哪些索引要跟着改」「计数要不要动」;
  • 导航门报不可达、计数门报漂移、资产基线门报规模数字矛盾;
  • 工作区存在并行会话或多人写入,共享索引文件可能被他人改动;
  • 提交前需要判断「这一批该包含哪些文件」。

不适用:纯内容写作与润色;命名合规审计(用 knowledge-bundle-naming-audit);导出与格式转换(用 okf-bundle-to-pdf);门禁自身的设计审查(用 gate-baseline-write-invariants 模式);无机械门禁、无共享索引的单写者仓库。

为什么声明「不适用」比多列触发词更重要? 虚假通用性比不触发更贵:在没有 BFS 可达性门的仓库里强行套「必须登记 toctree」,会输出一堆无意义动作。先确认适用,再执行。

4. 方案选择(决策树)

这次改动的形状是什么?
├─ 新建整个 bundle / 新建目录 → 走「全量注册」:域索引 + 分组索引 + 总索引 + 首页 + 根 badge
├─ 在既有 bundle 内加文档 → 走「增量接线」:本技能主路径(§5)
│   ├─ 只是加内容文档,bundle 数不变 → 只改「文件数」类投影,不动 total_bundles / 域束数 / 分组束数
│   └─ 顺带改了分组归属 → 按新建处理,回到全量注册
├─ 只改既有文档正文、不增删文件 → 不触发本技能,正常编辑 + 跑一次门禁即可
└─ 导出 / 转换 / 审计 → 转对应专用技能,不在此处理

写操作默认走 dry-run:先输出「投影清单 + 待改文件 + 预期计数」的预览,确认后再写盘。

为什么 dry-run 是最重要的一道防线? 写操作一旦落到共享索引就可能抹掉并行会话的内容,且 Git 之外没有撤销入口。预览在不产生任何文件变更的情况下把冲突面暴露出来,成本最低。无内置预览能力时,先给 diff 并取得明确确认。

5. 六步工作流

步动作完成判据
1枚举投影面:按 §6 清单逐项标「需改 / 无需改」清单无空项
2取地面真值:现跑计数门与导航门,记录日期与命令所有计数来自本次输出,不来自摘要、日志或上一轮结论
3落盘内容文档:保持 frontmatter 与同目录一致文件存在、编码合法、相对链接无断链
4接线:登记最近一级 {toctree},同步目录表格 / 阅读顺序 / 使用边界 / 上级计数 / 上位互链 / 根 description每个「需改」面都有对应 diff
5复跑门禁:导航门、计数门、编码门、资产基线门 + 各自 --self-test记录精确退出码,不只写「通过」
6判定提交批次:取让全部门禁自洽的最小文件集合,再单独请求提交授权批次说明能解释为什么包含看似无关的文件

步骤6:提交前验证——复跑门禁、列出完整待提交文件清单、确认 gitlink 与子项目 HEAD 关系、取得用户明确授权后才提交;未获授权即停在第 6 步之前。

为什么第 2 步不允许引用上一轮的结论? 摘要与日志是叙述,目录树与现跑脚本才是事实。并行会话会持续推进共享索引,越是需要精确的数字,越不能从叙述里取。实测中同一残差在一次会话内从 +299491 变为 +302365,计数基线从 714 变为 718。

为什么第 6 步的批次可以跨越多个功能改动? 共享索引同时承载多个 bundle 的计数投影。只提交单束会让计数门、导航门、资产基线门同时不自洽;此时「原子提交」的正确单位是自洽集合,而不是功能边界。

6. 投影面清单与接线完成判据

完整九面枚举表、逐面判定问题与真实案例见 投影面清单。

最小判据(缺一即视为未入库):

  • 新内容文档出现在最近一级 {toctree} 的条目集合中;
  • 导航门输出「所有内容文档均可达」且退出码 0;
  • 目录 index.md 的表格行数与目录实际内容文档数一致;
  • 上级索引中的「文件数」类计数与本束实际 .md 数一致;
  • 未新增 bundle 时,total_bundles、域束数、分组束数保持不动。

为什么「不新增 bundle 就不动总索引」要单独写一条? 因为最容易犯的错不是漏改,而是多改:把文件数变化误当成 bundle 数变化,去动 total_bundles,反而制造计数漂移。共享索引尤其不该在没有必要时去碰。

7. 门禁取数、残差归属与提交批次

取数命令、计数漂移处理、共享文件精确替换、残差归属定量方法、并行会话纪律见 门禁取数手册。

三条硬规则:

  1. 精确替换:未持有文件完整最新内容时,禁止整文件覆盖共享索引;用定点替换。已重读全文并确认无误时,整文件写入同样可行——Edit 是降低冲突面的手段,不是唯一正解。
  2. 残差归属定量:门禁红项先量化本轮改动字节与残差量级,再判断是否自己引入;不代修他方在途内容。基线门若要求「先提交或 stash 再复跑」,照做而不是改数字。
  3. 不刷新基线让门变绿:计数漂移只通过同步索引解决,不通过改写基线数字解决。

为什么不代修他方在途内容? 并行会话的工作区状态是他人的未完成事实;代修会同时制造内容冲突与责任不清。正确做法是定量说明归属、记录限制、把复跑条件写清楚。

8. 安全检查清单(逐项确认)

  • 已确认目标仓库确实存在机械门禁与共享索引,且判定为本技能适用场景
  • 已完成 dry-run 预览并取得明确确认,未持有全文时未整文件覆盖共享索引
  • 已验证幂等性:重复执行不会产生重复 toctree 条目或重复计数行
  • 已核对所有计数来自现跑脚本,并记录了取数日期与命令
  • 已确认新文档在最近一级 toctree 中登记,导航门退出码为 0
  • 已检查相对链接与 frontmatter 路径字段,无断链、无绝对路径泄漏
  • 已验证未新增 bundle 时 total_bundles 与各域束数保持不变
  • 已完成收尾验证:四个门禁精确退出码与各自 --self-test 均已记录
  • 已明确红项归属,未代修他方在途内容、未刷新基线数字让门变绿
  • 已确认提交批次是全部门禁自洽的最小集合,且提交已单独取得授权
  • 已确认未执行未授权的提交、推送或登记

为什么单列「不可撤销操作」警告? 提交与推送会改变他人可见的历史,且本技能默认不执行。把它们从常规步骤里分离出来、要求单独授权,才能避免「跑完流程顺手 commit」。

9. Gotchas(陷阱与反直觉行为)

  1. 内容合格 ≠ 入库:BFS 可达性门只认 toctree 边,不认文件质量。一份完美但孤立的文档在门禁视角下等于不存在。
  2. 日志里的数字会过期:同一会话内基线可多次变化;旧日志是历史记录,不是当前事实。
  3. + 前缀的 dirty 不一定是本轮引入:资产基线红项要先做字节量级对比,再谈归属。
  4. 少改比多改更安全:增量加文档不改 total_bundles;去动共享总索引反而制造漂移。
  5. 门禁全绿不等于提交正确:还需确认 gitlink 与子项目 HEAD 的关系,父仓只记录指针,不记录子模块工作区内容。
  6. 「通过」要带退出码:脚本输出可能"校验失败"但包装层退出 0(管道取到的是 tail 的码);记录时分开设取,别用 cmd | tail 后的 $? 当脚本退出码。
  7. 能力扩展要配等强度边界:在 flagged 单源材料上新增推导能力时,必须同步写禁用条款与证伪条件,否则等于把预测包装成建议。
  8. 不新增违规 ≠ 门禁转绿:归类门历史基线可能本来就红;如实记录「未恶化」,不要宣称「已通过」。

10. 验证命令与预期结果

cd <subproject>
python scripts/check-toctrees.py
python scripts/check-bundles-index.py
python scripts/check-utf8.py
python scripts/check-asset-baseline.py
python scripts/check-toctrees.py --self-test        # 其余三个同参
cd <workspace>
python .agents/scripts/check-skill-quality.py --path .agents/skills/shared-index-atomic-extension --score --threshold 100
python .agents/scripts/check-links.py --path .agents/skills/shared-index-atomic-extension --check-frontmatter-paths

预期:导航门 / 计数门 / 编码门退出码 0;四个 --self-test 退出码 0;质量门 100 分且退出码 0;链接门 0 断链。 已知限制:本机 vendor skill-creator 仅提供 SKILL.md,官方 aggregate_benchmark 与 eval-viewer 不可用,benchmark 未运行;pytest / sphinx 未安装,红线门与构建未执行;跨项目验证未完成。以上均按「未验证」登记,不宣称通过。

11. Changelog

版本日期变更
1.0.02026-11-06首次萃取:六步工作流、九面投影清单、门禁取数手册、6 条对抗审查修正(含 V-2 证据降级与 V-3 规则收窄)
1.0.12026-11-06按同日模式沉淀复核补「来源模式与去重声明」,撤销独立模式入库声称、重定位为既有 L2/L1.5 模式的执行投影;frontmatter source 同步改写。六步工作流、九面清单、安全检查清单与质量门结果不变

12. 参考

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall