AI 上下文清理 WJDdidi-1/ai-context-doctor

AI Context Doctor

English README

AI 编程助手会一个文件一个文件地读你的仓库。其中有些文件其实没用——构建产物、日志、lockfile、一个 40 MB 的数据文件。这个工具几秒钟就能把它们找出来，告诉你哪些该挡在 AI 之外。

npx ai-context-doctor

不用安装、不用登录、不需要 API key、不上传任何东西。它只看文件名和大小。

跑起来是什么样

下面是本项目自带的 demo 仓库的真实输出：

AI Context Doctor

Repo: demo-ai-context-noise-repo
Scanned: 8 files, 1.50 MB

AI Context Health: 22/100
Status: Too much noise for an AI coding agent

Context noise estimate:
78% likely noise
22% likely useful source context

Top context waste:
1. data/export.json 1.00 MB large file
2. dist/ 106.9 KB generated build output
3. package-lock.json 35.2 KB lockfile
4. logs/dev.log 18.4 KB local log file
5. coverage/ 16.7 KB test coverage output

Review before sharing:
- .env.example environment template (usually safe to share)
- scripts/deploy.sh deployment script

Suggested .aiignore:
coverage/
dist/
.log
package-lock.json

Next step:
Run this before asking your coding agent to inspect a larger repo.

输出正文目前是英文，命令行参数也一样；本文件解释每一行是什么意思。

这份报告怎么读

| 这一行 | 意思 |
| Scanned: 8 files, 1.50 MB | 实际扫了多少内容。.git/ 和 node_modules/ 不扫。 |
| AI Context Health: 22/100 | 100 减去「命中了噪音规则的文件」占的体积比例。22 分表示 AI 要读的东西里大部分是噪音。 |
| Status: | 把分数翻译成一句话：85 分以上干净，60–84 有噪音，60 分以下噪音太多。 |
| Top context waste | 体积最大的五个噪音来源，以及各自被标出来的原因。 |
| Review before sharing | 看起来像凭证或部署脚本的文件。工具没有说它们一定是密钥，只是提醒你：把这个仓库贴进聊天窗口之前先看一眼。 |
| Suggested .aiignore | 可以直接复制进忽略文件的行。工具不会替你写。 |

拿它能干什么

- 在让 AI 读一个大仓库之前：先跑一遍，把建议的行贴进 .aiignore（或你所用助手的忽略配置），再跑一遍，看分数有没有变高。
- 刚 clone 下一个项目时：先看看里面有多少是自动生成的产物，免得 AI 一上来就读这些。
- CI 里：用 --json 拿到稳定的结构化结果，上下文健康度掉下去就让构建失败。
- 自己的工具里：require('ai-context-doctor') 可以直接调用同一套扫描。
- 在 DeepSeek Harness 里：装上 dsh-aiignore，会话打开工作区时会自动提醒 AI 哪些文件会浪费上下文，你不用记着去跑任何东西。

安装

零安装直接跑：

npx ai-context-doctor

或者装一次：

npm install -g ai-context-doctor

需要 Node.js 18 或更新版本。

用法

ai-context-doctor # 扫描当前目录 ai-context-doctor ../some-repo # 扫描另一个仓库 ai-context-doctor --json # 机器可读输出 ai-context-doctor --help ai-context-doctor --version

JSON 输出

npx ai-context-doctor ./some-repo --json

返回 repo、healthScore、status、noisePercent、usefulPercent、scannedBytes、scannedFiles、topNoise、review、suggestedAiignore；触发扫描上限时还会带 truncated: true。

如果传入的路径不是可读目录，--json 只会输出一个 JSON 对象（不会先打印横幅），并以退出码 1 结束，CI 可以直接解析失败原因：

{
"error": "not-a-readable-directory",
"message": "/path/you/passed is not a readable directory.",
"target": "/path/you/passed"
}

在代码里调用

const { scanRepository } = require('ai-context-doctor');

const report = scanRepository(process.cwd());
console.log(report.healthScore, report.topNoise);

scanRepository(root, { maxFiles, maxBytes }) 是同步的，没有任何依赖。传上限可以低成本扫超大目录，此时报告会带 truncated: true。

DeepSeek Harness 插件

dsh-aiignore 把同一套扫描封装成 Host 插件：会话打开工作区时，AI 会收到一条简短提示，说明哪些文件会浪费它的上下文；工作区干净时它什么都不说。

dsh plugin --profile web add dsh-aiignore

它声明了 engines.dsh: ">=0.2.0"，Harness 会在安装前检查这个范围。源码、配置项与限制见 plugin/README.md。

什么算噪音

- 目录：dist/、build/、coverage/、.next/、.turbo/
- Lockfile：package-lock.json、pnpm-lock.yaml、yarn.lock
- 日志：.log
- 大文件：超过 1 MB、且没有被更具体的规则命中的单个文件
- 需要检查：看起来像凭证的文件名（.env、secrets.env、credentials.json、.pem、.key）以及路径里带 deploy 的文件。.env.example 会被识别成模板，标记为通常可以分享。
- 不遍历：.git/、node_modules/、.venv/、venv/、__pycache__/、vendor/

它不做什么

- 不调用任何 AI 服务，不需要 API key，不上传文件。
- 不修改你的仓库——不会写 .aiignore，也不会写别的文件。
- 不是 gitignore 检查器：它看的是「AI 会读到什么」，不是「git 跟踪什么」，所以被 git 忽略的文件照样会出现。
- 不是密钥扫描器。Review 列表基于文件名，没有扩展名的 id_rsa、粘在 config.js 里的密钥都会漏掉。
- 不统计 token，也不解析代码。分数是体积启发式：可以当真信号，不能当测量结果。
- 没有配置文件。上限只能通过 API 和 Harness 插件设置。

为什么建议 .aiignore 而不是 .gitignore

因为这是两个不同的问题。dist/ 在大多数项目里都被 git 忽略了，但一个不看 git 规则的助手照样会去读它。这个工具报告的是「AI 会读进去多少字节」，跟 git 怎么想无关。

隐私

全部在本地运行。工具只读取目录项和文件大小，不读文件内容，不建立网络连接，不存储任何东西。唯一会发到外面的数据，是你用 npm 安装它时 npm 自己发的。

开发

git clone https://github.com/WJDdidi-1/ai-context-doctor.git
cd ai-context-doctor
npm test # 单元测试与 CLI 测试
node bin/ai-context-doctor.js ./demo-ai-context-noise-repo

demo-ai-context-noise-repo/ 是一个故意做得很乱的仓库，随源码分发（不在 npm 包里），方便你直接试输出效果。

维护者：发布前看发布 checklist。发布在 CI 里通过 npm trusted publishing 完成，推 v tag 即触发，prepublishOnly 会先跑测试，坏包发不出去。

后续计划

- 未知参数给出明确报错，而不是当成目录名。
- 根据真实用户反馈改进噪音规则。
- 可选的 --fix：写出建议的忽略条目，但要你先看过 diff 再决定。

许可证

MIT