1实现原理 · 为什么它能做到
这是纯指令型 skill（零脚本）：全部机制写在 SKILL.md 正文，价值是一套『文档为什么会烂』的分类学与对应处置流程，执行者是 agent 本身。
daymade-docs/docs-cleaner/SKILL.md
They trace to one root cause: **a fact was written down in more places than it was defined.** Everything below follows from fixing that.
目录仅 SKILL.md + references/value_analysis_template.md，无 scripts/。文档操作（rg/git/lychee/文件改写）全部由 agent 按文中命令在宿主内执行。
核心判别器是 Drift Test 三问（按序停在首个命中）：值能否由已记录细节算出→derived 不写；不能算但别处有权威定义→copy 改链；否则若是『某时刻事实记录』→可写且不许当 drift 清掉。
daymade-docs/docs-cleaner/SKILL.md
ask these three questions **in order, and stop at the first hit**: **1. Can this be computed from details already recorded here or in the authoritative source?**
第 3 问（历史/审计记录优先）在文中被反复强调并给予反直觉的优先级：changelog/决策日志即使命中第 1/2 问也不得重算或链走。
Mode 1（变更后治理）按 7 步序执行，顺序即论点：先从变更枚举受影响事实→定 SSOT→处理实现与文档分歧→对每份文档定 disposition（更新或归档）→改之前全仓找每个事实的副本→顺路清理 derived 值→按固定结构汇报。
daymade-docs/docs-cleaner/SKILL.md
**2. Identify the authoritative source (SSOT) for each affected fact.** Which file *defines* this port / path / procedure — as opposed to mentioning it?
『先找副本再改』(step 5) 与『重编号事实族』的防漏搜索策略（正文计数词 rg 模式、别名清单、明说未覆盖面）是全文最工程化的部分。
删除被做成有纪律的仪式：归档=移出读者路径且保留历史（git mv 到 _archive/ 并重指所有入链），不许 status: deprecated 留在原地，不许对非本人文档未经确认就归档。
daymade-docs/docs-cleaner/SKILL.md
"Archive" means: out of the reader's path, still in history. Concretely: look for a convention the project already has (`_archive/`, `archive/`, `deprecated/`, or whatever it uses) and follow it; if there is none, create `_archive/` at the same level as the file. Either way move it with `git mv` so history follows
无人值守时禁止擅自删/归档：'leave the document untouched and report it as needing retirement'——把『无授权不删除』写成硬规则。
Mode 2（合并收敛）的防丢内容闸门：重写前先逐条产出『承重条目清单』（consequence 子句、症状→原因映射、顺序约束、作用域限定词、阈值必被单列），删除前的清单成为重写后校验的规格。
daymade-docs/docs-cleaner/SKILL.md
**The consequence clause.** "Roll back before retrying" is an instruction; "retrying on a half-applied migration corrupts the `events` table and there is nothing that repairs it automatically" is the reason anyone obeys it.
同节明言该清单防得住 recall 失败、防不住 judgment 失败（自评缺口被显式承认）；验证用 rg -U -F 逐条命中原句。
校验命令面有大量实测踩坑记录：rg 无路径会搜 stdin、-F/-U 才做字面与跨行、--no-ignore --hidden 与 -g '!.git' 的取舍、git grep 只看 tracked 文件、lychee '0 Total' 不算 pass。
daymade-docs/docs-cleaner/SKILL.md
`rg` skips VCS-ignored files *and* hidden ones by default, and `.github/` — full of documented commands — is hidden. A search without them is looking at a strict subset of the docs (measured: 4 files instead of 6).
每个断言都带 'measured:' 实测数字——本文档把『搜索工具的失败模式』当作一等知识资产维护。
功能边界内置：单文件过大的『分层压缩』归 claude-md-progressive-disclosurer（daymade-claude-code 套件），本 skill 只管真实性与去重。
daymade-docs/docs-cleaner/SKILL.md
That is what daymade-claude-code's `claude-md-progressive-disclosurer` skill is built for; prefer it when the problem is size and layering rather than truth or duplication.
这是 suite 生态内职责切分的显式记录，同一思想也见于 docx-creator/pdf-creator 的路由表。
2核心能力
01文档漂移三分类（derived value / copy / 历史记录）判别，先分类再决定处置
02变更后治理 Mode 1：SSOT 定位、文档 disposition（更新/归档）、改前全仓搜副本、重编号事实族防漏
03合并收敛 Mode 2：逐节价值分析（Keep/Condense/Delete/Archive）、Phase 3 计划先经人同意
04删除前承重条目清单 + 重写后逐条保真校验（Preservation check）
05入链/出链双向核查：入链用 rg 多形态搜索（.md/[[/ (/ 前缀），出链交给 lychee
067 点结构化汇报（不一致、SSOT 依据、改了什么、删了什么、搜索证据、修正后流程、未决事项）
07引用/模板资产：references/value_analysis_template.md 提供逐节分析表格式
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | ripgrep (rg) |
| cli | lychee（可选外链检查器，brew/cargo install） |
| cli | git（git grep / git mv / git show 归档与恢复） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: skill 自身无脚本；SKILL.md 指示 agent 在宿主执行 rg/git grep/lychee 等只读搜索与 git mv/文件改写
- 网络端点: 声明外部网络访问: 默认无；lychee 不带 --offline 时按文档会对文档内外部 URL 发请求（文档明示 'also checks external URLs
- 本地工作目录: 文件读写与工件输出: 按 Phase 3 计划修改/合并/删除文档文件；git mv 移入 _archive/ 归档；改写 CLAUDE.md/AGENTS.md 等同受治
审计说明： 。无网络外发、无凭证读取、无自带脚本执行；但运行会产生删除/归档/改写用户文档的破坏性写面（Mode 1 归档、Mode 2 删除源文件），skill 自身要求 Phase 3 计划先经用户同意、无人值守时停手——黄色主因是该写面需要人工门与 git 保护，非代码级危险。lychee 全量模式会外查 URL，默认推荐 --offline。
5第二遍独立确认
- [ok] 纯指令无脚本（资产面） — glob 全量文件：SKILL.md + references/value_analysis_template.md，无 scripts/ 目录。
- [ok] Drift Test 三问与顺序规则 — 原文 'in order, and stop at the first hit' 与 Q1/Q2/Q3 全在；第 3 问优先级说明亦逐字存在。
- [ok] Mode 1 七步与 SSOT 判定 — 步骤编号 1-7 与 SSOT 'defines vs mentioning' 判据原文在。
- [ok] 归档纪律（git mv + 不就地 deprecated） — 'out of the reader's path, still in history'、'git mv'、'do **not** settle for adding status: deprecated frontmatter' 均命中。
- [ok] 删除需人门 / 无人值守停手 — 'Present the Phase 3 plan and get agreement before step 3' 与 'Running unattended and cannot ask: leave the document untouched and report it' 存在。
- [ok] preservation check 防 recall 不防 judgment 的自评缺口 — 'It catches *recall* failures ... It cannot catch *judgment* failures' 原文在，未见自我拔高。
- [ok] 搜索命令面防坑（rg/lychee） — pathless-rg/stdin 陷阱、-F -U、--no-ignore --hidden、lychee '0 Total' 各段均在，附 measured 数字。
- [ok] 网络面仅 lychee 外链可选检查 — 代码零命中；唯一网络点是 SKILL 对 lychee 非 --offline 模式的说明，且推荐先 --offline。
6结论
适合： 适合代码/配置/流程变更后同步文档、或文档膨胀需要收敛的中大型仓库维护者；也适合把『文档一致性』纳入 CI/变更流程的团队。要求宿主模型强、目录在 git 下、用户愿意做 Phase 3 的人工确认。
不适合： 不适合无人值守自动化跑（skill 自己要求删除前有人）；不适合没有 git 历史保护的目录；单文件过大需分层的问题应交给 claude-md-progressive-disclosurer；不适合需要改代码而非文档的任务（Mode 1 明确禁止把文档任务变成实现项目）。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload docs-cleaner.tar.gz
sha256:
Option B · Copy Guide for Agent91fa2a6f6082c893…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.