Agent Skills
› BytePioneer-AI/codex-host
› codexhost-trim-cot-leakage
codexhost-trim-cot-leakage
GitHub审计并修正源码注释与文档中的推理过程泄漏,清理过时引用、变更叙述及评审辩解,确保内容基于当前代码状态。
触发场景
需要清理代码注释或文档中的历史遗留表述
审查文档是否存在脱离当前代码状态的引用
安装
npx skills add BytePioneer-AI/codex-host --skill codexhost-trim-cot-leakage -g -y
SKILL.md
Frontmatter
{
"name": "codexhost-trim-cot-leakage",
"description": "审计或修正读起来像“推理过程泄漏”的注释与文档:引用已不存在的设计会话、讲变更而不讲现状、面向评审者辩解、带“以前\/不再\/本次”等时间性叙述。用于清理 codexhost 的源码注释、JSDoc、docs 功能文档与提示词字符串。"
}
清理推理泄漏
“推理泄漏”指站在写作会话而不是仓库当前状态的视角写成的文字:引用只有当时会话才看得到的东西,叙述改动而非现状,或在向已经离开的评审者争辩。
唯一判据
对每处可疑文字问:一个没有任何会话记录、PR 讨论或未提交草稿的读者,在当前 HEAD 能否解析每个引用、验证每个论断?
- 不能:把仍成立的事实改写成站在当前状态的陈述,再删去外围;若没有事实内容(编号、控制流复述)则直接删除。
- 能:不是泄漏。但在“当前状态”文档(README、功能文档、JSDoc)里,可解析的变更故事仍属变更叙述,应放到变更说明、提交信息或 PR 描述。
类型
- 失效的设计会话引用:
(decision 7)、audit C2、方案 §4.7、阶段代号T4、“设计稿”。有已提交的归属就按名称与路径引用,否则删除引用并把事实独立写出。 - PR / 提交视角:“本 PR 新增”“上一个提交”“后续 PR 会”。改为描述已交付机制或扩展点;推迟的工作用
TODO或 issue 引用。 - 变更叙述与时间戳:“以前”“不再”“旧的 X”“本次”“目前”“现在”对照过去。改为现行行为;修复过的回归可写成现在时的反事实(“若没有 X,会出现 Y”)。
- 评审编排:“评审中被拒绝”“reviewer 确认”“第 5 版”。保留结论与理由,删掉是谁在何时说的。
- 面向评审者的辩解:“这里转换是安全的,因为……”。写出让代码安全的不变量,或在代码已自明时删除。
- 控制流复述与显而易见的推导:“首先……然后……”、测试步骤复述。只保留不显然的契约或不变量。
- 含糊与遗留计划:“暂时应该够用”“先这样”,没有标记。升级为
TODO/FIXME或写成实际边界。
不是泄漏(保留)
- issue 引用与
TODO(name):,在当前 HEAD 可解析。 - 抑制规则的理由:
eslint-disable … -- reason、#[allow(...)]旁的原因、空 catch 的说明。理由不实就改,不要删。 - 现在时的反事实回归钉:“如果没有 X,会发生 Y”。
- 实测边界:“(实测:512 层嵌套约 0.15s)”,“实测”本身承重。
- 运行时的新旧状态:“旧连接排空后新连接才接受请求”,这是生命周期而非变更史。
- 外部标准与外部来源:RFC 章节、上游项目链接。
- 项目口吻:“我们”,以及文档里合理的“备选方案”部分。
范围与排除
- 必须有明确范围;没有就询问,不推断为全仓库。
- 排除:
reference/、docs/archive/、.codexhost/、node_modules/、dist/、target/、生成物,以及录制的 fixtures 与快照(它们保留原始口吻)。 - 面向模型或用户可见的字符串,措辞即行为:不要静默改写,标出并按“有快照或测试支撑的变更”处理。
- 多语言文档配对(如
docs/project/README.zh-CN.md、README.ko.md):同步改对应语言版本。
流程
-
只读审计:用探针扫描范围,再判断每个命中,同时通读该范围内最稠密的注释与文档,探针只是召回手段而非定义:
rg -n --hidden -g '!reference/**' -g '!docs/archive/**' -g '!node_modules/**' -g '!dist/**' -g '!target/**' \ -e '\((decision|audit|plan) ' -e '§ ?[0-9]' -e '\bused to\b|\bno longer\b|\bthis (PR|cut|commit)\b' \ -e 'in review|reviewer|previous (PR|commit)|later PR' -e '以前|不再|本次|旧的|设计稿|评审(中|时)' <scope> -
自有者优先修复:先改生成物的来源,再重新生成;先改源码 JSDoc,再同步引用它的文档。
-
删除前列出命题:枚举每段文字的主体、动作、条件、时序、否定保证与后果,避免过度修正:不要把义务改成许可、把假设写成已交付、删掉仍为真的事实或丢掉来源。
-
验证:重新运行探针,只应剩下保留项;对触及的面运行
npm run lint、npm run format:check;涉及文档链接时核对docs/index.md。
版本历史
- a8adb78 当前 2026-10-18 17:44


