coalledger

CoalLedger 是一款面向 AI 编程代理的文档质量工具，其作者将其描述为“文档领域的 CoalMine”。它是 TheColliery 系列小型插件套件（包括 CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash）的一部分，该系列遵循零依赖钩子、单源配置模式、经同意才支出以及无自动编辑的原则。CoalLedger 可以独立安装，也可以与其他套件协同使用。 该工具的前提是：代码拥有 Linter、测试和 CI，而文档大多只能靠“运气”——与代码脱节的 README、不再匹配的翻译、失效的安装链接或过时的版本徽章都是读者仍会信任的静默失败。CoalLedger 可以扫描任何文档（README、规范、报告、翻译），并将渲染结果与其声明的内容进行对比。 它设有七个金丝雀检测项，每项对应一种失败模式： 1. doc-grounding（文档溯源）——捕捉与事实来源（代码、数据、原文、现实）不符的声明；通过多个来源实时验证，离线时降级为“未验证”。 2. doc-standard（文档标准）——捕捉相对于该类文档标准的不完整性，包括缺失的必要章节和未记录的公共接口。 3. doc-rot（文档腐烂）——捕捉陈旧的版本、日期和徽章，以及失效的 TODO 和被取代的指令。 4. doc-consistency（文档一致性）——捕捉文档间的矛盾、术语漂移和跨语言漂移。 5. doc-structure（文档结构）——捕捉损坏的链接、锚点、标题、表格、引用和图像替代文本。 6. doc-quality（文档质量）——捕捉冗余、晦涩的措辞以及拼写、语法等语言机制问题。 7. doc-leak（文档泄密，需配置开启）——标记面向公众文档中的文本级敏感内容；令牌形状的密钥由其他工具处理，仅报告疑似发现。 扫描分为两个层级。“快速（Quick）”层级涵盖确定性且几乎免费的机械层，仅提供报告。“完整（Full）”层级增加语义层，使用模型判断，需付费且必须获得单独同意。其中四个金丝雀结合了机械层和语义层；doc-consistency 和 doc-leak 仅为语义层。内置的零依赖 CommonMark+GFM AST 引擎驱动结构检查，确保渲染正确的内容不会被标记；作者明确指出其保真度上限是规范级别，而非像素级还原 GitHub 渲染，宿主环境的特性将被报告为限制而非猜测。 严重程度始终根据上下文而非机械地判定：存档中的损坏链接为低风险，而安装步骤中的相同链接则为关键风险。确认的发现与疑似发现分开报告。修复绝不会自动执行；每份报告末尾都提供一个菜单，供用户选择安全修复、自定义修复或仅报告。机械层在设计上与语言无关——它们基于结构、位置和含义而非英语关键词——而语义层则在文档自身的语言中运行。 一个单独的、可选的功能是文档内存漂移（memory-drift）提醒。它不扫描也不报告任何内容。如果文档文件（.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org）被编辑但 MEMORY.md 在该会话中未更新，且项目使用了 MEMORY.md 约定，CoalLedger 会在代理完成响应时发出一条安静的系统消息，并在 MEMORY.md 更新后保持沉默。该功能可禁用。这与 CoalMine 针对代码编辑的类似提醒相辅相成，两者监控不同的文件扩展名。 兼容性基于能力而非平台列表：具有生命周期钩子的平台拥有会话启动导体，可在正确的时间提供正确的金丝雀；没有钩子的平台则采用尽力而为的代理驱动调用；在所有情况下，金丝雀都可以通过名称手动调用。作者诚实地标注了支持层级——Claude Code 被描述为通过实时插件和内部测试验证，而所有其他平台（Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai）则标记为“可用（works with）”：即为之构建但尚未经过端到端验证。Antigravity 的配置文档包含一项警告，即 hooks.json 的位置在更新后发生了变化，应从 Antigravity 自身的文档中重新推导；配置在失效路径上是惰性的且无害。 Claude Code 的安装通过两个命令完成（市场添加和插件安装），这同时配置了导体和内存漂移提醒。其他代理则复制自包含的技能文件夹（AST 引擎位于 doc-structure 文件夹内）。建议 claude.ai 用户不要手动压缩技能包，因为前置元数据描述超过了该平台的列表上限；相反，发布在 Releases 页面上的每个金丝雀的 ZIP 包带有精简的描述和 SHA256 校验和。 命令包括每个金丝雀的专属命令，以及 /coalledger:stats（会话本地扫描和发现统计）和 /coalledger:update（版本检查和更新处理）。配置支持全局文件和基于多个已知代理目录解析的每项目文件，且仍读取旧版根路径。配置项涵盖：开关模式、报告语言、禁用的金丝雀、严重程度阈值、全扫描覆盖、快速与完整默认层级、doc-leak 门控、面向公众文档标志、内存漂移提醒、可选的 em-dash 排版规则以及更新检查行为。项目可以被完全关闭，从而停止加载该技能。 权限声明非常严格：它仅读取指定的文档及其链接指向的文件，仅写入自己的临时文件和更新时间戳，最多运行三个本地项（只读 AST 引擎、修复前的 git stash 检查点，以及在同意情况下运行文档声称有效的示例），绝不会擅自编辑文档。网络使用为可选：付费的 Full 层级来源验证和自我更新检查分别需要单独同意；钩子和引擎永不联网。无需 API 密钥或 npm install。 在基准测试方面，该项目态度诚实：它选择在未经过基准测试的情况下发布，而非捏造数字。机械层在仓库中通过验证脚本进行固定测试（发现植入缺陷，对干净样本保持静默），并计划在首次有日期、有版本的运行中，按金丝雀逐项填充关于种子文档缺陷召回率的结果摘要。 采用 Apache 2.0 许可证。