# cot-lint

[English](README.md) | 中文

**扫描仓库中的"思维链泄漏"——AI 助手留在文档、注释、JSDoc 里的会话残留。**

你的 coding agent 代码写得很好，但会把"思考过程"漏得到处都是：

```diff
- // This PR adds a retry loop (decision 7) so the diff stays reviewable.
- // The manager used to serialize writes itself; it no longer does after v1.
- // The cast is safe — it simply narrows the union. Probably fine for now.
+ // Retries transient provider failures up to 3 times with jittered backoff.
+ // The shared coordinator serializes writes per session.
+ // The cast narrows a union already validated at the loader boundary.
```

左边一列对代码的描述并没有错，错的是**读者设定**：它在和一个早已离开的评审者争论，引用一个谁都打不开的设计会话，叙述一次变更而不是陈述行为。

## 唯一测试

> 站在 HEAD 上的读者——没有任何会话记录、PR 讨论或未提交草稿——能否解析其中每一个引用、验证每一个断言？

不能，就是思维链泄漏。`cot-lint` 负责把它找出来。

## 快速开始

**DeepSeek Harness** —— 以插件形式装入 `cot-trim` 修复技能：

```sh
dsh plugin add cot-lint
```

**任何仓库 / CI** —— 零依赖，Node ≥ 20：

```sh
npx cot-lint                 # 扫描整个仓库（Markdown 等文本文件）
npx cot-lint --json          # 输出 JSON，供 CI 或 agent 消费
npx cot-lint --ext ts,py     # 同时逐行扫描源码文件
npx cot-lint --hidden        # 进入 .agents/ 等点开头目录
```

退出码：`0` 干净 · `1` 有发现 · `2` 用法错误——可直接接入 CI。

## 检测什么

| 类别 | 示例 |
| --- | --- |
| 死掉的设计会话引用 | `(decision 7)`、`design §4.7`、阶段代号 `W3`/`T4`、`设计稿` |
| PR/堆叠视角 | "this PR adds…"、"a later PR in this stack" |
| 变更叙述 / 版本印记 | "used to"、"no longer"、"the old X"、"the v1 refactor"、"today"、`旧版`/`不再` |
| 评审编排 | "Rejected in review:"、"the reviewer confirmed"、`上一轮评审` |
| 对评审者的辩解 | "the cast is safe — it simply…" |
| 控制流复述 | "first we X, then we Y"、"as you can see" |
| 含糊保留 | "probably fine for now"、"should be enough" |
| 母语滑移 | 另一种语言的行文里混入未翻译的工作语言碎片 |

中英两套检测电池内置。

## 刻意不标记什么

保留规则是这台工具的另一半。一个无差别处理的 linter 如果删掉 `RFC 9110 §10.1.5`、删掉承重的 `TODO(alice):`、或者删掉 "the old connection drains before the new one accepts"（运行时生命周期，不是变更历史），破坏比泄漏本身更大。所以 `cot-lint` 机械豁免：

- issue 引用和带标记的 `TODO`/`FIXME`/`XXX` 递延；
- 同一行引用了 RFC 等外部标准的 `§` 引用；
- 带 `cot-lint-ignore` 抑制标记的行——请把理由写在标记旁边。

**电池默认过度匹配。** 每条 finding 是候选而非判决；[保留规则与改写方法](skills/cot-trim/SKILL.md)决定什么能活下来。

## 不止发现，还要修复

仓库内置 [`cot-trim`](skills/cot-trim/SKILL.md) agent skill，与 CLI 配合使用：它运行 `cot-lint --json`，用"唯一测试"逐条判断，删除前先枚举段落里的全部命题，并按属主优先修复（生成文件改源头、模型可见字符串走所属快照）。

把它装进你的 agent 查找 skills 的位置：

- **DeepSeek Harness**：`dsh plugin add cot-lint`（或 `github:YuanyuanMa03/cot-lint`）——`cot-trim` skill 通过插件的 skill provider 加载。
- **Claude Code / 通用 agent**：把 `skills/cot-trim/` 复制进你的 agent skills 目录（`~/.claude/skills/`、`.agents/skills/` 或你的 agent 约定的位置）。

## 与"AI 文风检测器"的区别

文风检测器标记的是*听起来像 AI* 的散文（用词习惯、破折号癖好）。`cot-lint` 标记的是*视角属于作者会话*的散文——只有身临其境才说得通的引用和叙述。人写的文档也会泄漏（复制粘贴 PR 描述就会）；AI 写的文档也可以很干净。失败类别不同，工具不同。

## 来源

分类法、保留规则和电池方法提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（MIT）的工程规范——具体说是它针对 agent 写作仓库的散文卫生实践——在此泛化为任何仓库、任何 coding agent 可用。其[社区生态立场](https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.zh.md)见官方 CONTRIBUTING。

## 许可

[MIT](LICENSE)