dsh-plain-talk 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 0.1.1
+
+- README 重写：只保留用户需要的信息，删除 npm 发布与收录流程说明。
+- 输出对比改为左右并列表格，场景重排为 A / B / C。
+- 示例代号改为中性占位符（EXP-7、DEV-1K、run-3），规则与自检提示同步。
+- README 顶部加入 banner。
+
+# 0.1.0
+
+- 输入框「说人话」开关：按会话记录，状态写入 `$DSH_HOME/plain-talk.json`，重启后保留。
+- 系统提示词区段：结论先行、默认 ≤12 行 / 300 字、禁回指、引用必须贴原文、代号首现解释、语言跟随用户。
+- `plain_talk_check`：发送前自检，报回指、内部信息、只给指针的引用、未解释代号、长度与列表问题。
+- `plain_talk_vocab`：读取与维护用户词汇清单，分常识 / 专业 / 项目 / 内部代号 / 待归类五类。
+- 「调研 X」两阶段学习：第一次回复把 X 当作未知，回合结束后才写入词汇清单。
+- `PLAIN_TALK_DEFAULT=off` 可让新会话默认关闭，用于基准测试或按需开启的用法。
+- 不写 session 事件；只写两个 sidecar JSON 文件。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lizilong1993
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,147 @@
+# dsh-plain-talk
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lizilong1993/dsh-plain-talk/main/assets/banner.jpg" alt="dsh-plain-talk — 说人话" width="100%">
+</p>
+
+<p align="center">
+  <strong>English</strong> · <a href="README.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/dsh-plain-talk"><img alt="npm" src="https://img.shields.io/npm/v/dsh-plain-talk?style=flat-square"></a>
+  <img alt="dsh-plugin" src="https://img.shields.io/badge/dsh--plugin-ready-478CBF?style=flat-square&logo=deepseek&logoColor=white">
+</p>
+
+A reply-shaping plugin for DeepSeek Harness: one composer switch. When it is on, replies lead with the conclusion, stay under 12 lines by default, paste the text they cite, gloss an opaque code the first time it appears, and stop re-explaining words you already use.
+
+## What it does
+
+- **Conclusion first.** The first line is the answer or the verdict. No restating the question, no "let me take a look".
+- **Short by default.** ≤12 lines / 300 characters unless you ask for depth.
+- **Standalone.** No "as mentioned above" / "the previous step"; codes such as `EXP-7`, `DEV-1K`, `run-3` get a one-line gloss at first use.
+- **Citations you can read.** A `file:line` reference always comes with the quoted lines.
+- **User vocabulary.** Words you have used, project names and common terms count as known; "research X" still explains X on the first reply, then remembers it.
+
+## Results
+
+Environment: DeepSeek Harness `desktop` profile running headless, model `cmc/deepseek/deepseek-v4.1-flash` (high), 2026-11-04. Same prompt, same workspace, only the switch changes; the vocabulary is cleared before each arm.
+
+### Summary
+
+| Scenario | Metric | Off | On | Change |
+|---|---|---|---|---|
+| A. Completion task (4 files + verification) | final reply chars | 144 | 189 | +45 (adds a verdict and a self-check step) |
+| | output tokens | 2,333 | 1,344 | **−42%** |
+| | tool calls | 12 | 11 | −1 |
+| | elapsed | 131 s | 107 s | −24 s |
+| B. Explanation | final reply chars | 410 | 350 | **−15%** |
+| | output tokens | 732 | 326 | **−55%** |
+| | cross-turn references | 2 | 0 | **−2** |
+| C. Report rewrite (turn a draft into a user-facing report) | final reply chars | 558 | 496 | **−11%** |
+| | output tokens | 2,781 | 3,066 | +10% (one extra self-check round) |
+| | unexplained codes | 6 | 0 | **−6** |
+| | pointer-only citations | 1 | 0 | **−1** |
+
+The rules section costs about +589 input tokens per step (single-step, zero-tool B run: 260,351 → 260,940).
+
+### A. Completion task
+
+| Aspect | Off | On |
+|---|---|---|
+| First line | 任务完成，产物都在 `bench-demo/` 目录： | 已达标：`bench-demo` 下四个文件已就位，运行脚本输出 `ABC`。 |
+| Artifacts | `a.txt`, `b.txt`, `c.txt` hold A, B, C; `check.mjs` reads them in order and prints the joined result | Each file holds exactly one line; `check.mjs` reads, joins and prints, measured output `ABC` |
+| Reader check | Run `node check.mjs`; output `ABC`, exit code 0. | Run `node check.mjs` in `bench-demo`; expect one line `ABC`. |
+| Chars / output tokens | 144 / 2,333 | 189 / 1,344 |
+
+### B. Explanation
+
+| Aspect | Off | On |
+|---|---|---|
+| Paragraph 1 | 多数人以为这只是"上下文窗口不够长"，其实窗口够长也会忘。一是截断与压缩……二是注意力是软检索……三是位置编码在超长距离上外推能力下降。 | 简单说，模型没有"记忆"，它每次回答只能看到当前上下文窗口里的全部 token；窗口塞满后，早先的对话要么被截断、要么被压缩成摘要。 |
+| Paragraph 2 | 再往深一层，是训练目标没给"长期记忆"发工资。预训练是逐 token 预测，几乎不惩罚"忘了前面说过什么"…… | 另一层原因是训练时的分布。模型主要在短文本上学习长距离依赖，真到几万 token 的跨度，关联能力本来就弱…… |
+| Cross-turn references | 2 | 0 |
+| Chars / output tokens | 410 / 732 | 350 / 326 |
+
+### C. Report rewrite
+
+The draft contains codes, cross-turn wording and a pointer-only citation. Project codes are replaced with neutral placeholders in this example.
+
+| Aspect | Off | On |
+|---|---|---|
+| Verdict line | 结论：EXP-7（新加的实例校验模块）这次不合并。加了它的 CAND 定位精度 61.2% → 63.8%……没到 3 个点的门槛。 | 结论：EXP-7（给推理流程加"实例验证"一步的实验）没达到合并门槛，不合并。 |
+| Codes | EXP-7 and CAND glossed; AUROC, pp, round-2 left bare | EXP-7, DEV-1K, run-3, BASE, CAND, round-2 all glossed in place |
+| Citation | "see reports/exp7/summary.md:42", no quoted content | says the file is not in the repository and drops the citation |
+| Next step | several options in one paragraph | one action |
+| Chars / output tokens | 558 / 2,781 | 496 / 3,066 |
+
+## Install
+
+Requires a DeepSeek Harness build with the `conversation.input.left` slot (0.2.x line).
+
+```sh
+dsh plugin --profile desktop add dsh-plain-talk
+dsh plugin --profile desktop add github:lizilong1993/dsh-plain-talk
+dsh plugin --profile desktop add ./dsh-plain-talk
+```
+
+Restart DSH afterwards.
+
+## Use
+
+1. Open any session: a speech-bubble icon appears next to the permission selector in the composer.
+2. It starts on (blue). Click it to turn it off (grey) for that session only.
+3. State lives in `$DSH_HOME/plain-talk.json` and survives restarts.
+4. Want new sessions to start off? Set `PLAIN_TALK_DEFAULT=off` where DSH launches.
+
+## Vocabulary
+
+`$DSH_HOME/plain-talk-vocab.json`, shared across sessions.
+
+| Category | Meaning | Examples |
+|---|---|---|
+| common | built in, never explained | arXiv, DOI, API, GPU |
+| domain | field terms you have used | diffusion model, AUROC |
+| project | repositories, products, workspace names | AcmeService_V2, DataHub_V3 |
+| internal | experiment/task/commit codes | EXP-7, DEV-1K, run-3 |
+| unclassified | recorded, not classified yet | other detected codes |
+
+"Research X" is two-phase: X is marked pending, the first reply still explains it, and the turn end records it. Common terms such as arXiv are unaffected.
+
+Maintain it with `plain_talk_vocab` (`list` / `add` / `remove` / `classify`) or by editing the JSON.
+
+## Self-check tool
+
+`plain_talk_check` takes a draft and reports:
+
+- errors: cross-turn wording, session/subagent/tool names, pointer-only citations;
+- warnings: unexplained codes, over 12 lines / 300 characters, lists over 5, preamble, closing offer, English-only reply to a Chinese user.
+
+The section asks the model to run it for completion reports and replies over 12 lines.
+
+## How it works
+
+- Host (`dsh/index.js`) registers one `systemPrompt` section (`plain-talk`, order 55) whose text function returns the rules only while that session's switch is on.
+- Browser half (`lib/client.js`) registers into `conversation.input.left` and renders a 24×24 button.
+- The switch is read and written over the loopback route `/plain-talk/state` (127.0.0.1 / ::1 only, 8 KB body limit).
+- Switch and vocabulary are atomic JSON sidecar files; no session events are written.
+
+## Data
+
+Only `$DSH_HOME/plain-talk.json` and `$DSH_HOME/plain-talk-vocab.json` are written. No network, no upload, no credential access. A corrupt state file reads as "no choice recorded".
+
+## Configuration
+
+Environment variable `PLAIN_TALK_DEFAULT` (`on` / `off`, default `on`).
+
+## Notes
+
+- The button position depends on `conversation.input.left`; a host redesign may move it beside other left-side controls.
+- Rules are prompt constraints; `plain_talk_check` warns but never blocks a send.
+- Vocabulary is shared per user, not per project; code detection is heuristic.
+- With the mode on, each request carries about 590 extra input tokens.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-plain-talk（说人话）
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lizilong1993/dsh-plain-talk/main/assets/banner.jpg" alt="dsh-plain-talk — 说人话" width="100%">
+</p>
+
+<p align="center">
+  <a href="README.en.md">English</a> · <strong>中文</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/dsh-plain-talk"><img alt="npm" src="https://img.shields.io/npm/v/dsh-plain-talk?style=flat-square"></a>
+  <img alt="dsh-plugin" src="https://img.shields.io/badge/dsh--plugin-ready-478CBF?style=flat-square&logo=deepseek&logoColor=white">
+</p>
+
+DeepSeek Harness 的回复优化插件：输入框里一个「说人话」开关。打开后，回复先给结论、默认不超过 12 行、引用直接贴原文、代号第一次出现时用一句人话解释，并记住你已经认识的词。
+
+## 它做什么
+
+- **结论先行**：第一行就是答案或判定，不复述问题，不写"我来看看"。
+- **默认短**：≤12 行 / 300 字；你要求展开时才放开深度。
+- **自包含**：不用"上述 / 前面 / 上一轮"；代号（EXP-7、DEV-1K、run-3）第一次出现写成 `EXP-7（一句话说明）`。
+- **引用可读**：给 `文件:行号` 的同时贴出那几行原文。
+- **词汇清单**：你说过的词、项目名、常见术语默认已知；"调研 X"的第一轮仍会解释 X，回复交付后才记住。
+
+## 效果
+
+测试环境：DeepSeek Harness `desktop` profile、headless 运行、模型 `cmc/deepseek/deepseek-v4.1-flash`（high），2026-11-04。同一提示词、同一工作区，只切换开关；两侧开始前都清空词汇清单。
+
+### 汇总
+
+| 场景 | 指标 | 关闭 | 开启 | 变化 |
+|---|---|---|---|---|
+| A 完成类任务（建 4 个文件并验证） | 最终回复字数 | 144 | 189 | +45（多"达标"和"你自己确认"） |
+| | 输出 token | 2,333 | 1,344 | **−42%** |
+| | 工具调用 | 12 | 11 | −1 |
+| | 耗时 | 131 s | 107 s | −24 s |
+| B 解释类（为什么模型会忘事） | 最终回复字数 | 410 | 350 | **−15%** |
+| | 输出 token | 732 | 326 | **−55%** |
+| | 回指次数 | 2 | 0 | **−2** |
+| C 报告整理（把草稿改成给用户的汇报） | 最终回复字数 | 558 | 496 | **−11%** |
+| | 输出 token | 2,781 | 3,066 | +10%（多一次自检） |
+| | 未解释代号 | 6 | 0 | **−6** |
+| | 只给指针的引用 | 1 | 0 | **−1** |
+
+规则段每步约 +589 input token（C 组单步、零工具：260,351 → 260,940）。
+
+### A 完成类：同一任务，两侧输出
+
+| 对比点 | 关闭 | 开启 |
+|---|---|---|
+| 首行 | 任务完成，产物都在 `bench-demo/` 目录： | 已达标：`bench-demo` 下四个文件已就位，运行脚本输出 `ABC`。 |
+| 产物说明 | `a.txt`、`b.txt`、`c.txt` 内容分别是 A、B、C；`check.mjs` 按 a→b→c 顺序读取，去掉换行后拼接输出 | `a.txt`、`b.txt`、`c.txt` 各只有一行 `A`、`B`、`C`；`check.mjs` 按 a → b → c 读取、拼接并打印，实测输出：`ABC` |
+| 读者确认 | 运行 `node check.mjs`，输出 `ABC`，退出码 0。 | 你自己确认：在 `bench-demo` 目录执行 `node check.mjs`，应看到一行 `ABC`。 |
+| 字数 / 输出 token | 144 / 2,333 | 189 / 1,344 |
+
+### B 解释类：同一问题，两侧输出
+
+| 对比点 | 关闭 | 开启 |
+|---|---|---|
+| 第一段 | 多数人以为这只是"上下文窗口不够长"，其实窗口够长也会忘。一是截断与压缩……二是注意力是软检索……三是位置编码在超长距离上外推能力下降。 | 简单说，模型没有"记忆"，它每次回答只能看到当前上下文窗口里的全部 token；窗口塞满后，早先的对话要么被截断、要么被压缩成摘要。 |
+| 第二段 | 再往深一层，是训练目标没给"长期记忆"发工资。预训练是逐 token 预测，几乎不惩罚"忘了前面说过什么"…… | 另一层原因是训练时的分布。模型主要在短文本上学习长距离依赖，真到几万 token 的跨度，关联能力本来就弱…… |
+| 回指 | 2 处（"前面说过"等） | 0 |
+| 字数 / 输出 token | 410 / 732 | 350 / 326 |
+
+### C 报告整理：同一份草稿，两侧整理结果
+
+草稿里放了代号、回指和只给指针的引用。示例中的项目代号已替换为中性占位符。
+
+| 对比点 | 关闭 | 开启 |
+|---|---|---|
+| 结论句 | 结论：EXP-7（新加的实例校验模块）这次不合并。加了它的 CAND 定位精度 61.2% → 63.8%，涨 2.6 个百分点，没到 3 个点的门槛。 | 结论：EXP-7（给推理流程加"实例验证"一步的实验）没达到合并门槛，不合并。 |
+| 代号处理 | EXP-7、CAND 有解释；AUROC、pp、round-2 仍是裸代号 | EXP-7、DEV-1K、run-3、BASE、CAND、round-2 全部就地解释 |
+| 引用 | 只写"见 reports/exp7/summary.md:42"，没有原文 | 说明该文件不在仓库里，这条不引用 |
+| 下一步 | 一段话里给了多个选项 | 只给一个动作 |
+| 字数 / 输出 token | 558 / 2,781 | 496 / 3,066 |
+
+## 安装
+
+需要带 `conversation.input.left` 插槽的 DeepSeek Harness（0.2.x 线）。
+
+```sh
+# npm（推荐，预构建）
+dsh plugin --profile desktop add dsh-plain-talk
+
+# GitHub
+dsh plugin --profile desktop add github:lizilong1993/dsh-plain-talk
+
+# 本地目录
+dsh plugin --profile desktop add ./dsh-plain-talk
+```
+
+装完重启 DSH。
+
+## 使用
+
+1. 打开任意会话，输入框权限选择器右侧会多一个气泡图标。
+2. 默认开启（蓝色）；点一下变灰，只关掉当前会话。
+3. 状态写在 `$DSH_HOME/plain-talk.json`，重启后保持。
+4. 想让新会话默认关闭：启动环境里设 `PLAIN_TALK_DEFAULT=off`。
+
+## 词汇清单
+
+`$DSH_HOME/plain-talk-vocab.json`，跨会话共享。
+
+| 类别 | 含义 | 例子 |
+|---|---|---|
+| 常识词汇 | 内置，不解释 | arXiv、DOI、API、GPU |
+| 专业词汇 | 你用过的领域词 | 扩散模型、AUROC |
+| 项目 / 产品名 | 仓库、产品、工作区名 | AcmeService_V2、DataHub_V3 |
+| 内部代号 | 实验号、任务号、提交号 | EXP-7、DEV-1K、run-3 |
+| 待归类 | 已记录、未分类 | 其他识别到的代号 |
+
+"调研 X"分两步：X 先记为待确认，第一轮回复照常解释；回复交付后写入词表。常识词（如 arXiv）不受影响。
+
+维护用 `plain_talk_vocab`：`list` / `add` / `remove` / `classify`；也可以直接改 JSON。
+
+## 自检工具
+
+`plain_talk_check` 接收一条草稿，返回问题清单：
+
+- 必须改：回指词、会话号 / 子代理 / 工具名、只给指针没有原文。
+- 建议改：未解释代号、超过 12 行 / 300 字、列表超过 5 条、开头寒暄、结尾征询、中文用户却整段英文。
+
+规则区段要求模型在完成类回复或超过 12 行的回复发送前调用它。
+
+## 工作原理
+
+- 宿主端（`dsh/index.js`）注册一个系统提示词段落（`plain-talk`，order 55），只有当前会话开关打开时返回规则正文。
+- 浏览器端（`lib/client.js`）注册进 `conversation.input.left`，渲染 24×24 气泡按钮。
+- 开关经 loopback 路由 `/plain-talk/state` 读写（仅 127.0.0.1 / ::1，body ≤8 KB）。
+- 状态与词表都是 JSON sidecar，原子写；不写 session 事件。
+
+## 数据与权限
+
+只写 `$DSH_HOME/plain-talk.json` 和 `$DSH_HOME/plain-talk-vocab.json`。不联网、不上传、不读凭据；状态文件损坏时按"无记录"处理。
+
+## 配置
+
+只有环境变量 `PLAIN_TALK_DEFAULT`（`on` / `off`，默认 `on`）。
+
+## 注意
+
+- 按钮位置依赖 `conversation.input.left`，宿主改版后可能移到其它左侧控件旁。
+- 规则是提示词约束，`plain_talk_check` 只提醒、不拦截发送。
+- 词表按用户共享，不按项目隔离；代号识别是启发式判断。
+- 默认开启时每个请求多约 590 input token。
+
+## 许可
+
+MIT —— 见 [LICENSE](./LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-plain-talk bundle patch: one host row. The browser half is declared by
+# package.json `dsh.client` and served by the Harness, so it needs no row here.
+- insert:
+    - id: plain-talk
+      name: dsh-plain-talk

package/dsh/check.js

@@ -0,0 +1,250 @@
+// Reply checker for dsh-plain-talk.
+//
+// This is deliberately a checker, not a gate: it reports what a reader would
+// stumble on, with the exact replacement form. The model decides what to keep.
+//
+// Three principles learned from real sessions in this workspace:
+//  - Common terms and project names are not errors. Only opaque codes the
+//    reader has never seen (EXP-7, DEV-1K, run-3) need a first-use gloss.
+//  - A pointer is not a citation: `file.py:42` alone sends the reader away.
+//  - Cross-turn wording ("上述", "上一轮") is the main reason a report cannot
+//    be read on its own.
+
+const ALLOW = new Set([
+  'api', 'json', 'jsonl', 'yaml', 'yml', 'html', 'css', 'http', 'https', 'url', 'uri',
+  'cli', 'ui', 'ux', 'gpu', 'cpu', 'ram', 'ssd', 'hdd', 'ai', 'llm', 'sdk', 'ide',
+  'csv', 'tsv', 'ts', 'js', 'py', 'sh', 'md', 'txt', 'png', 'jpg', 'jpeg', 'svg',
+  'gif', 'webp', 'sql', 'xml', 'toml', 'npm', 'pnpm', 'git', 'ssh', 'dns', 'tcp',
+  'udp', 'tls', 'ssl', 'jwt', 'oauth', 'cors', 'orm', 'crud', 'rest', 'grpc',
+  'wasm', 'dom', 'smtp', 'imap', 'vpn', 'utf8', 'utf-8', 'utf16', 'utf-16',
+  'sha1', 'sha256', 'sha-256', 'sha512', 'sha-512', 'md5', 'x86', 'x64', 'arm64',
+  'mp3', 'mp4', 'pdf', 'h264', 'hevc', 'ipv4', 'ipv6', 'k8s', 'i18n', 'l10n',
+  '2d', '3d', '4k', 'v1', 'v2', 'v3', 'v4', 'ci', 'pr', 'id', 'ok', 'vs', 'iso',
+  'doi', 'arxiv', 'p50', 'p95', 'p99', '2x', '4x', '8x', '16x', 'gpt', 'llm',
+  'linux', 'windows', 'macos', 'node', 'react', 'github', 'python', 'javascript',
+  'typescript', 'docker', 'sqlite', 'postgres', 'redis',
+])
+
+const MODEL_FAMILY = /^(?:gpt|claude|gemini|llama|qwen|deepseek|mistral|phi|o1|o3|o4|glm|kimi|mimo|hy)\d*[-.]?\d*/i
+
+const BACKREF_ZH = [
+  '上述', '上面', '前述', '前文', '前面提到', '前面说', '之前提到', '之前说',
+  '此前', '上一步', '上一轮', '前一轮', '刚才', '该方案', '该项', '该任务',
+  '前者', '后者', '如上', '见上文', '先前', '那次', '前面', '之前',
+]
+const BACKREF_EN = [
+  'as mentioned', 'aforementioned', 'as discussed', 'the above', 'previous step',
+  'earlier', 'previously', 'the former', 'the latter',
+]
+
+const PLUMBING = [
+  /\bsession[-_][0-9a-z-]{6,}/i,
+  /子代理|子会话|父代理|父会话|\bsubagent\b|\bparent agent\b|report sent to/i,
+  /\b(?:plain_talk_check|run_code|ops_bash|ops_grep|todo_write)\b/,
+]
+
+const PREAMBLE = /^(好的|好|当然|没问题|收到|明白|我来|让我|让我先|我们先|首先，我|先看一[下看])/
+const CLOSER = /(需要我|要不要|如果你愿意|希望(这|以上)|随时告诉我|还需要我|要我继续)/
+
+const FILE_EXT = 'py|js|mjs|cjs|ts|tsx|json|jsonl|md|ya?ml|toml|sh|ps1|bat|csv|tsv|txt|ipynb|log|html|css|tex|bib|pdf|zip|sql|db|pt|pth|ckpt|npy|npz|parquet|docx|xlsx|pptx'
+
+const IDENT_PATTERNS = [
+  ['file', new RegExp(`(?:[A-Za-z]:[\\\\/]|\\/)?[A-Za-z0-9_.-]+(?:[\\\\/][A-Za-z0-9_.-]+)*\\.(?:${FILE_EXT})\\b`, 'gi')],
+  ['hash', /\b[0-9a-f]{7,40}\b/gi],
+  ['snake', /\b[A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+\b/g],
+  ['camel', /\b[a-z]+[A-Z][A-Za-z0-9]*\b|\b(?:[A-Z][a-z0-9]+){2,}[A-Za-z0-9]*\b|\b[A-Z][a-z]+[A-Z]{2,}[A-Za-z0-9]*\b/g],
+  ['acronym', /\b[A-Z]{2,8}\b/g],
+  ['code', /\b[A-Za-z]{1,10}[-_.]?\d{1,6}[A-Za-z]?\b|\b\d{1,4}[A-Za-z]{1,6}\b/g],
+]
+
+export const LIMITS = {
+  boxChars: 300,
+  boxLines: 12,
+  listRun: 5,
+  identifierWarns: 8,
+}
+
+const cjkCount = (s) => (s.match(/[\u4e00-\u9fff]/g) ?? []).length
+const latinCount = (s) => (s.match(/[A-Za-z]/g) ?? []).length
+const len = (s) => [...s].length
+
+function stripCode(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ')
+}
+
+export function isCommonTerm(term) {
+  const text = String(term ?? '').trim()
+  if (!text) return false
+  return ALLOW.has(text.toLowerCase()) || MODEL_FAMILY.test(text)
+}
+
+export function scanIdentifiers(input) {  const text = stripCode(String(input ?? ''))
+  const found = []
+  for (const [kind, re] of IDENT_PATTERNS) {
+    re.lastIndex = 0
+    let m
+    while ((m = re.exec(text))) {
+      const raw = m[0].replace(/[.,;:]+$/, '')
+      if (!raw) continue
+      found.push({ kind, token: raw, start: m.index, end: m.index + raw.length })
+    }
+  }
+  found.sort((a, b) => a.start - b.start || (b.end - b.start) - (a.end - a.start))
+  const accepted = []
+  for (const item of found) {
+    if (accepted.some((a) => item.start < a.end && item.end > a.start)) continue
+    accepted.push(item)
+  }
+  return accepted
+}
+
+function isAllowed(token, known) {
+  const lower = token.toLowerCase()
+  if (ALLOW.has(lower)) return true
+  if (MODEL_FAMILY.test(token)) return true
+  // Durations and multipliers ("10m", "3s", "4x") are measurements, not names.
+  if (/^\d+(?:ms|s|m|h|d|w|k|m|b|x)$/i.test(token)) return true
+  // Product-style names (AcmeService_V2, DataHub_V3) are project vocabulary the
+  // reader already holds; a lower-case internal key (tier_reaudit) is not.
+  if (/^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)+$/.test(token) && (token.match(/[A-Z]/g) ?? []).length >= 2) return true
+  if (known && (known.has(token) || known.has(lower))) return true
+  return false
+}
+
+function explainedAfter(text, end) {
+  const after = text.slice(end, end + 60)
+  const m = /^\s*[（(]([^）)]{4,})[）)]/.exec(after)
+  if (!m) return false
+  return cjkCount(m[1]) >= 3 || latinCount(m[1]) >= 8
+}
+
+function knownFrom(text, known) {
+  return { text, known }
+}
+
+/**
+ * Analyze one reply draft.
+ *
+ * @param draft - the reply text the model is about to send.
+ * @param options - `knownTokens` (project/user vocabulary) and `language`
+ *                  (`zh` when the user writes Chinese).
+ * @returns issues plus the measurements the README benchmark reports.
+ */
+export function analyze(draft, options = {}) {
+  const text = String(draft ?? '')
+  const known = new Set((options.knownTokens ?? []).map((t) => String(t)))
+  const knownLower = new Set([...known].map((t) => t.toLowerCase()))
+  const language = options.language ?? 'unknown'
+  const issues = []
+
+  const add = (severity, rule, message, fix) => issues.push({ severity, rule, message, fix })
+
+  const narrative = stripCode(text)
+
+  // 1. Cross-turn wording.
+  const backrefs = [
+    ...BACKREF_ZH.filter((w) => narrative.includes(w)),
+    ...BACKREF_EN.filter((w) => narrative.toLowerCase().includes(w)),
+  ]
+  if (backrefs.length) {
+    add('error', 'backref', `出现回指词：${backrefs.slice(0, 5).join('、')}。`, '把指代的东西重新写一遍，读者没有前文可翻。')
+  }
+
+  // 2. Internal plumbing.
+  const plumbing = PLUMBING.find((re) => re.test(narrative))
+  if (plumbing) {
+    add('error', 'internal', '出现会话号、子代理或工具名等内部信息。', '删掉；只写用户能看见的对象。')
+  }
+
+  // 3. Pointer-only citations.
+  const pointers = []
+  const pointerRe = new RegExp(`(?:[A-Za-z]:[\\\\/]|/)?[\\w.-]+(?:[\\\\/][\\w.-]+)*\\.(?:${FILE_EXT}):\\d+`, 'gi')
+  pointerRe.lastIndex = 0
+  let pm
+  while ((pm = pointerRe.exec(text))) pointers.push(pm[0])
+  if (pointers.length) {
+    const unquoted = pointers.filter((pointer) => {
+      const at = text.indexOf(pointer)
+      const window = text.slice(Math.max(0, at - 220), at + pointer.length + 220)
+      return !/「[^」]{4,}」|"[^"]{4,}"|『[^』]{4,}』|`[^`]{4,}`|```/.test(window)
+    })
+    if (unquoted.length) {
+      add('error', 'citation', `只有位置没有原文：${unquoted.slice(0, 3).join('、')}。`, '把那几行原文贴出来，再标位置。')
+    }
+  }
+
+  // 4. Unexplained opaque identifiers.
+  const seen = new Set()
+  const unknown = []
+  for (const token of scanIdentifiers(narrative)) {
+    if (seen.has(token.token)) continue
+    seen.add(token.token)
+    if (isAllowed(token.token, known) || isAllowed(token.token, knownLower)) continue
+    if (explainedAfter(narrative, token.end)) continue
+    unknown.push(token.token)
+  }
+  if (unknown.length) {
+    add(
+      'warn',
+      'identifier',
+      `有 ${unknown.length} 个代号没有说明：${unknown.slice(0, 6).join('、')}${unknown.length > 6 ? ' 等' : ''}。`,
+      '第一次出现写成「EXP-7（一句话说明它是什么）」；用户在本对话用过的词和项目名不用解释。',
+    )
+  }
+
+  // 5. Shape.
+  const lines = text.split('\n').filter((l) => l.trim())
+  const cjk = cjkCount(narrative)
+  if (cjk > LIMITS.boxChars || lines.length > LIMITS.boxLines) {
+    add('warn', 'length', `回复有 ${cjk} 个汉字、${lines.length} 行，超过默认的 ${LIMITS.boxChars} 字 / ${LIMITS.boxLines} 行。`, '删掉读者不决策所需的内容；用户要细节时再展开。')
+  }
+
+  let run = 0
+  let maxRun = 0
+  for (const line of text.split('\n')) {
+    if (/^\s*(?:[-*+]|\d+[.)])\s+/.test(line)) { run++; maxRun = Math.max(maxRun, run) } else if (!line.trim()) { run = 0 }
+  }
+  if (maxRun > LIMITS.listRun) {
+    add('warn', 'list', `有一段列表 ${maxRun} 条，超过 5 条。`, '合并或只留最要紧的五条。')
+  }
+
+  const first = lines[0] ?? ''
+  if (PREAMBLE.test(first)) {
+    add('warn', 'preamble', `开头是「${first.slice(0, 20)}」，属于寒暄或过程宣告。`, '第一行直接给结论。')
+  }
+  const tail = text.slice(-180)
+  const closer = CLOSER.exec(tail)
+  if (closer) {
+    add('warn', 'closer', `结尾出现「${closer[0]}」，在征求额外任务。`, '删掉；需要下一步就只给一个具体动作。')
+  }
+
+  // 6. Language mismatch.
+  const total = cjk + latinCount(narrative)
+  const cjkRatio = total === 0 ? 0 : cjk / total
+  if (language === 'zh' && cjkRatio < 0.2 && latinCount(narrative) > 40) {
+    add('warn', 'language', '用户用中文提问，但这条回复几乎全是英文。', '用中文写；命令、路径、报错原文保持原样。')
+  }
+  const hasNext = /下一步|接下来要|接下来请|你可以先|建议你先|Next step/i.test(text)
+  if (!hasNext && (cjk > 200 || lines.length > 10)) {
+    add('warn', 'next', '回复较长，但没有给出一个明确的下一步。', '结尾补一个用户现在就能做的事；没有就写"没有待办"。')
+  }
+
+  return {
+    ok: !issues.some((i) => i.severity === 'error'),
+    issues,
+    stats: {
+      chars: text.length,
+      cjk,
+      lines: lines.length,
+      cjkRatio: Number(cjkRatio.toFixed(3)),
+      identifiers: unknown.length,
+      backrefs: backrefs.length,
+      maxListRun: maxRun,
+      hasNext,
+    },
+  }
+}
+
+export { cjkCount, latinCount, len }