mikasa-servent/dsh-research-check

dsh-research-check

在交论文、交文档、交数据之前，先让它替你检查一遍。

它专门抓那种"明明检查过、却还是被抓出来"的低级错误：数字前后不一致、改了标题忘了改正文、
文档属性里藏着你的名字和学校、少交了一个文件、页数超了一页。

适用于任何"有要求、要交付"的活儿：论文投稿、软件交付验收、数据交付、标书申报、技术文档。
它不是写手，是校对员——不帮你写内容，只帮你把该对的地方对上。

dsh plugin --profile web add dsh-research-check      # 装进 DeepSeek Harness

也支持 MCP：Claude Code、Codex、Cursor 等任何支持 MCP 的工具都能用（见 第 3 步）。

目录

- 它能帮你什么（先看这个）
- 三步用起来
- 四个工具的用法
- 支持哪些交付物
- 它不会做什么
- 规格文件与台账
- 验证与开发
- 常见问题

它能帮你什么（先看这个）

下面每一条，都是真实发生过、并且被这个工具抓出来的问题：

| 你可能犯的错 | 具体长这样 | 后果 |
|---|---|---|
| 数字改了正文没改 | 图表里写 4761，正文还写着 4883 | 评审一眼看出你没核对 |
| 两个口径混用 | 一张表用"计划量"算，另一张用"实际量"算，两个总数对不上 | 被认为数据不可信 |
| 比率说错 | 写"两个方案都只有 1/565"，其实一个 565、一个 583 | 严谨性打折 |
| 旧版本残留 | 摘要写 1536.4，定稿是 1521.6（改稿时漏了摘要） | 摘要与正文矛盾 |
| 文档属性泄露身份 | 你的 Excel/Word 里存着账号名、学校名（肉眼看不见） | 匿名评审直接违规 |
| 页数超限 | 要求正文 ≤30 页，你交了 31 页 | 可能直接被拒 |
| 清单对不上 | 论文附录列 11 个文件，压缩包里实际 12 个 | 被视为材料不实 |
| 交付物里有报错 | 交付日志里留着 Traceback、ERROR: | 显得没测过 |
| 数据不合规 | 交付数据里混进了手机号字段 | 合规风险 |
| 占位符没删 | 对外文档里留着 TODO、待补充 | 非常尴尬 |

核心价值一句话：这些错误自己很难查（尤其是元数据里的身份信息——你根本看不见），
但被发现一次，代价往往是一整轮返工甚至取消资格。让工具在交之前替你过一遍。

三步用起来

第 1 步：把"要求"喂给它（只做一次）

你手上一定有一份要求文件：赛会格式规范、期刊投稿须知、甲方验收标准、导师给的模板。
把这个文件交给它，它会变成一份能自动核对的清单：

python python/spec_build.py --requirements 格式规范.doc --out specs/我的要求.json \
--profile academic --name "竞赛论文格式规范"

它会告诉你提取出了多少条规则，每条规则都带出处（引用要求文件里的原话），例如：

{
"id": "doc.body_pages",
"title": "正文页数上限",
"check": "max_pages",
"severity": "hard",
"params": { "limit": 30 },
"source": "…论文从第四页开始是正文内容（不要目录，不超过30页）…"
}

⚠️ 然后花两分钟人工看一眼：确认数字对不对（30 页？20 MB？）。
有些规则需要你填参数（比如"必须提交哪些文件"），空着的规则它会如实报"没检查"——不会假装通过。

第 2 步：交之前，一句命令自查

python python/check_spec.py --spec specs/我的要求.json --root . \
--pdf 我的论文.pdf --files 交付文件1.xlsx 交付文件2.docx --archive 材料.zip

输出是中文表格，通过的打 ✓，违反的标 ✗ 并告诉你为什么（引用要求原文）：

[ok  ] hard  正文页数上限          正文 30 页 / 上限 30 页
[FAIL] hard  文档属性不得含身份信息   属性命中：{'creator': '张三'}
[ok  ] soft  图表必须被引用          全部被引用

第 3 步：用其他 AI 工具（Claude Code / Codex / Cursor）

如果你不用 DeepSeek Harness，可以用 MCP 接入——在工具的 MCP 配置里加一段：

{
"transport": "stdio",
"serverName": "research-check",
"command": "node",
"args": ["/mcp/server.mjs"]
}

之后你的 AI 就能调用 spec_build / spec_check / audit / numbers / ledger 五个能力。

📖 想跟着做一遍？ 完整教程（从零开始、每步都有命令与预期输出）：
中文 · English

四个工具的用法

装好之后，你用大白话让 AI 去用就行，不用背命令：

| 你可以这样说 | 实际调用的工具 | 它会做什么 |
|---|---|---|
| "帮我按格式要求检查一下论文" | research_spec | 按要求清单逐条核对 |
| "检查我的论文和压缩包，交之前看一眼" | research_audit | 查页数、空白页、图表引用、身份信息、清单一致性 |
| "我改了结果，帮我核对论文里的数字有没有漏改" | research_numbers | 找出前后矛盾的数字 |
| "把这个数字和它的来源记下来，以后好核对" | research_ledger | 建立"数字—出处"台账 |

推荐的工作流（顺序很重要）：

① 先建台账，记下关键数字和它们的来源
② 跑程序，刷新台账里的数值
③ 改正文和图表（两个地方都要改！）
④ 核对：台账里的数字在正文里还找得到吗？
⑤ 交之前跑一遍格式检查

命令行直接用法：

建台账：从文稿里自动找出带单位的数字，登记成候选
node lib/ledger-cli.js teach --ledger paper-ledger.json --paper 论文.tex \
--unit-filter 万元 --min-abs 100

手动登记一条（把"这个数字从哪来"钉住）
node lib/ledger-cli.js add --ledger paper-ledger.json \
--key q3.total_cost --value 1521.6 --unit 万元 \
--source code/q3.py --anchor 全年费用

核对：台账里的值还在文稿里吗？（--near 会额外提示"同位置的相似数值"）
node lib/ledger-cli.js verify --ledger paper-ledger.json --paper 论文.pdf --near

体检：页数、摘要、空白页、身份信息、压缩包清单
python python/audit_paper.py --paper 论文.pdf --archives 材料.zip

支持哪些交付物

同一个工具，换一份要求文件，就能用在完全不同的场景。--profile 决定用哪套规则：

| 场景 | --profile | 它重点查什么 |
|---|---|---|
| 论文 / 学位论文 / 期刊投稿 | academic | 页数、摘要单页、图表引用、页边距、行距字号 |
| 软件交付 / 项目验收 / 发版 | software | 必备文件、LICENSE、变更记录、日志里的报错 |
| 数据交付 / 数据集 | dataset | 字段齐备、样本量、隐私字段、数据字典 |
| 说明书 / 技术文档 / 手册 | docs | 段落长度、版本号、联系方式、TODO 残留 |
| 标书 / 申报书 | tender | 章节齐备、逐条响应 |
| 任何交付物 | generic | 体积、命名、身份信息、清单一致性、占位符 |

共 37 个可判定的检查项。查看每类的规则数：

python python/spec_build.py --list-profiles

跨场景实测（python tests/test_generality.py，自动化跑，每次发布前都会验证）：

| 交付物 | 干净版本 | 故意做坏的版本 → 被抓住的问题 |
|---|---|---|
| 软件包 | 0 错误 | 缺 README.md；日志里有 Traceback |
| 数据集 | 0 错误 | 缺字段；样本量不足；混入手机号 |
| 技术文档 | 0 错误 | 段落超长；TODO 没删；Word 属性里有作者名 |

它不会做什么

先说清楚，免得你误会：

- ❌ 不帮你写内容——它只核对，不生成
- ❌ 不判断两个数字谁对——它会告诉你"这里有两个互相矛盾的数"以及它们在哪，
由你来决定改哪个（只有你知道哪个是新的）
- ❌ 不重新推导公式——数字是"比对"而不是"重算"。如果程序算错了、正文照抄了这个错值，
两边一致就会通过。所以对结论起决定作用的数字，仍然要自己独立复算
- ❌ 不评价方法好坏、不做法律意见

规格文件与台账

规格（spec）：把要求变成清单

{
"id": "doc.body_pages",
"title": "正文页数上限",
"check": "max_pages",
"scope": "body",
"severity": "hard",
"params": { "limit": 30, "appendix_marker": ["附录"] },
"why": "页数是评委最先感知的硬约束",
"source": "…要求文件里的原话…"
}

- check：用哪个检查项，必须是 37 个之一，或 manual（人工清单）
- scope：document（整份）/ body（附录前）/ per-file / bundle
- severity：hard 违反即报错 / soft 只提醒 / info 只记录

三条纪律（决定了它不会变成"只会说通过"的花架子）：

1. 每条规则必须指定检查项，否则加载就报错。机器判断不了的（比如"测试是否覆盖需求"）
写成 manual，进入人工清单——绝不假装能查。
2. 没检查 = 没检查：缺输入、缺参数时如实报 skipped，绝不混进"通过"里。
3. 每条判定都带出处，你可以拿着它去答辩、回复审稿意见。

台账（ledger）：把数字和出处钉在一起

{
"entries": [
{
"key": "q3.total_cost",
"value": 1521.6,
"unit": "万元",
"source": "code/q3.py",
"anchor": "全年费用"
}
]
}

- key 用语义名（q3.total_cost），不要用数字本身当 key——程序重跑后只改 value，正文不用动
- unit 单独放，避免把「1.5 万元」和「15000 元」当成两件不同的事
- anchor 是正文里的固定短语，用来定位并检查"同一位置是否出现了量级相近的异值"

验证与开发

九段验证，全部可以在本地复现：

npm test                 # 语法 + 上架清单 + 打包清单 + 契约 + MCP + 规格 + 跨领域
npm run test:generality  # 跨场景（软件/数据/文档，含"故意做坏"的负例）
npm run test:pack        # 检查 npm 实际会打包什么
npm run mcp:smoke        # MCP 协议层（真实报文）
npm run boot             # 真启动一个临时实例，确认不会把 DSH 启动搞崩

关键设计：每个功能都配了"负例"——故意写错的东西必须被抓出来。
只会说"通过"的检查器是装饰品，所以每个功能都有对应的"必须抓住"测试。
在 CI（.github/workflows/verify.yml）上跑 Node 22/24 + Python 3.13。

常见问题

Q：装完没反应 / 工具不出现？
A：DSH 插件在启动时注册，需要重启 profile。MCP 方式则要重启你的 AI 工具。

Q：报 NO_PYTHON？
A：检查核心需要 Python 3.10+。装了还是报，就设环境变量 DSH_RESEARCH_PYTHON 指向解释器路径。

Q：报 skipped 是什么意思？
A：“这条我没查”——通常缺输入（比如没给 PDF、没给文件清单）或规则参数没填。
它不等于通过，请补齐输入或转人工确认。

Q：中文输出乱码？
A：1.4.1 起已修复（脚本强制 UTF-8 输出）。旧版本请升级。

Q：会不会把我的论文上传到什么地方？
A：不会。所有检查都在你本机命令行完成，插件不联网、不收集任何数据。

Q：能检查 Word 文档吗？
A：能。段落长度、身份元数据类规则直接读 .docx；页数、摘要、图表引用类规则需要 PDF
（Word 转 PDF 后即可）。

Q：我的要求文件格式很乱（表格、编号、中英混排）能识别吗？
A：能解析 .doc / .docx / .md / .txt。它用的是模板匹配而不是自由发挥——
只收录要求文件里明确出现、且机器能判定的条款，其余进入“需要人工确认”清单，不会瞎猜。

License

MIT

由来

最初是给一篇真实的竞赛论文写检查脚本，写着发现每一个检查都对应一个真实犯过的错，
而这类错误与学科无关——凡是“数据 → 图表 → 结论”的活儿都会犯。
于是把“要求”抽象成规格、把“数字”绑回台账、把检查项做成词汇表，
让它能用在论文、文档、软件、数据、标书五类交付上。