SuperAPI AI 工具集

llp-maintain

写作与研究

查看项目

更新于 11-05 17:11

技能介绍

用途

llp-maintain 是一个“维护引擎”技能,用于让 LLP 文档语料与代码持续共同演进,避免活文档因代码变化而变成误导性指引。它的职责是发现代码与文档之间的漂移,并给出修复建议,而不直接改动任何内容。

主要能力

调用方式为 /llp-maintain --intent <pre-pr | audit | reconcile | retire-proposal | curate>,每种意图都有合理的默认作用范围:

  • pre-pr(默认作用于工作树):生成“代码/文档共同演进检查清单”(如“更新文档或代码”“修复引用”“考虑添加注解”)以及建议的状态变更,但不应用。
  • audit(作用于整个语料):输出发现列表,包括漂移、失效引用、过时状态。
  • reconcile(作用于差异范围或分支):给出逐文档的核对建议,或指出“是代码漂移而非文档”。
  • retire-proposal(针对单个指定文档):起草 Superseded/Tombstoned 提案及理由(仅修改头部状态,文件不移动)。
  • curate(作用于叠加层与 foundation 对比代码):按 LLP 0011.000 输出 PROMOTE / ARCHIVE / REALIGN 检查清单,包括待增删的链接、折叠、状态修正,以及 foundation 现在要求的代码变更。

检查项

  • 对范围内的 @ref:目标或锚点损坏(错误,并列出实际存在的锚点);目标已墓碑化或被取代(警告,注明替代项);释义过时(提示);注解所附结构已消失(孤立注解,警告)。
  • 对带来源标签的文档:Accepted/Active 中出现 [inferred](错误);[observed] 未注明位置,或 [confirmed] 缺少名称与日期(标记给作者)。
  • 对已安装技能:source: 固定版本落后于上游发布(网络允许时提示)。
  • 机械检查之外:行为已与所引用章节不符的代码;实现了文档化 LLP 却缺少 @ref 的新文件;与差异相矛盾的 LLP 章节。

使用约束

  • 必须只提议、绝不应用:没有确认就不做编辑、引用修复或状态变更;输出是可审阅的清单或差异,绝不进行大规模重写。
  • 不得静默归类未标记的理由性论断,必须标记给作者,由其标注 [observed]/[confirmed]/[inferred]。
  • curate 必须按 promote、archive、realign 的顺序执行三个动作,且只能对 llp/foundation/ 做代码对齐,绝不能对整份语料执行。提升提案必须应用 LLP 0000 的准入测试(可从集合重建设计、集合级、过小则不合格),而非依据重要性。
  • 不得声称自己是 CI 关卡;确定性的、阻断合并的检查由 ref-check 负责,本技能是交互式、带判断的补充。

适用场景

提交 PR 之前(pre-pr)、定期或在存疑时(audit)、拉取之后或针对某分支(reconcile)、判断某文档“已完成/已过时”(retire-proposal)、设计工作落地后、发布前或按节奏执行(curate)。

交接

核对过程中若实质上是新的设计决策,交给 llp-review;llp-orient 暴露的失效引用在此生成修复提案;audit 发现的过时 source: 固定版本,在获批差异后由 /llp-adopt update 应用(本技能从不应用);确定性 CI 执行交由 ref-check。