dsh-thesis 1.0.0 → 2.0.1

package/docs/release.md

@@ -0,0 +1,126 @@
+# 发布
+
+发版由 GitHub Actions 完成（[`.github/workflows/publish.yml`](../.github/workflows/publish.yml)）。
+**打 tag 即发布**，本地不需要 `npm login`，也不需要任何 npm token。
+
+认证走 **Trusted Publishing（OIDC 可信发布）**：npm 只接受「这个仓库的这个 workflow」发来的包，
+凭据是每次运行临时签发的，不落盘、不过期、也没有 2FA 输 OTP 的问题；provenance 由 npm 自动附上。
+
+## 一次性设置（只做一次）
+
+1. 打开 <https://www.npmjs.com/package/dsh-thesis/access> → **Trusted Publishers** →
+   **Select publisher: GitHub Actions**，填四个字段：
+
+   | 字段 | 填什么 |
+   |---|---|
+   | Organization or user | `booondenz` |
+   | Repository | `dsh-thesis` |
+   | Workflow filename | `publish.yml`（只写文件名，不带路径）|
+   | Environment name | **留空**（除非 workflow 里写了 `environment:`）|
+
+2. 确认仓库是 **public**：私有仓库发不出 provenance。
+3. 不需要 `NPM_TOKEN`，**之前建过的话建议在 Settings → Secrets 里删掉**，免得以后误用。
+
+> 配置要先「验证」过一次才算生效：2026-10 起，长期没成功发布过的可信发布配置会自动过期。
+> 所以配完就立刻发一次版。
+
+## 备选：用 token（不推荐）
+
+如果哪天可信发布不可用，也可以在 npm 建 **Classic → Automation** 类型的 token
+（Granular token 在开了 2FA 的账号上会报 `EOTP`，除非它明确允许绕过 2FA），
+存成仓库 secret `NPM_TOKEN`，然后在 workflow 的 publish 步骤加回：
+
+```yaml
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+并把 `setup-node` 的 `with:` 里加回 `registry-url: https://registry.npmjs.org`。
+Automation token 专为 CI 设计，不受 2FA 影响。
+
+## 发一次版
+
+```bash
+npm version patch --no-git-tag-version   # 或 minor / major，或手动改 package.json
+git add package.json package-lock.json
+git commit -m "chore: release v2.0.1"
+git tag v2.0.1
+git push origin main --tags
+```
+
+Action 会依次做：
+
+| 步骤 | 失败就停 |
+|---|---|
+| `npm ci` | 锁文件与 package.json 不同步会在这里红 |
+| tag 与 `package.json` 版本一致 | 防止「tag 写 v2.0.1、包里是 2.0.0」|
+| 该版本是否已存在于 npm | 已存在则**跳过发布**（不会红，也不会覆盖）|
+| `npm pack --dry-run` | 发布内容一目了然（日志里能看到文件清单）|
+| `npm publish` | 内部触发 `prepublishOnly` 守卫：构建 + 类型 + 单测 + 审计 + 端到端；provenance 由可信发布自动附带 |
+| 建 GitHub Release | 标题用 tag，正文自动生成 |
+
+发布成功后 npm 页面会带一个 **Provenance** 徽章，点进去能看到是哪次 commit、哪次 workflow 构建的。
+
+## 在网页上发版（完全不碰命令行）
+
+1. 打开 <https://github.com/booondenz/dsh-thesis/releases/new>；
+2. **Choose a tag** 里输入 `v2.0.1`，点下拉第一条 **Create new tag: v2.0.1 on publish**；
+3. **Target** 选 `main`，并确认它指向 bump 版本的那个 commit（否则 tag 会打在别的提交上，
+   workflow 第一步的版本比对就会红）；
+4. 标题写 `v2.0.1`，正文可以留空——workflow 里是 `gh release view || gh release create`，
+   发现 Release 已存在会跳过；
+5. **Publish release**。
+
+创建 tag 本身就是一次 `push`，所以 `publish.yml` 会被触发。两条路等价：也可以先
+`git push origin v2.0.1` 再建 Release，或者只推 tag 不建 Release（workflow 会替你建）。
+
+## 确认发成功了
+
+| 看哪 | 期望 |
+|---|---|
+| Actions → **publish** | 这次 run 是绿的；Summary 里有一行 `https://www.npmjs.com/package/dsh-thesis/v/2.0.1` |
+| `npm view dsh-thesis version` | `2.0.1`（registry 立刻生效，网页可能还要一分钟）|
+| `npm view dsh-thesis dist-tags` | `{ latest: '2.0.1' }` |
+| <https://www.npmjs.com/package/dsh-thesis> | 版本号旁出现 **Provenance** 徽章 |
+| 仓库 **Releases** | 多了一条 `v2.0.1` |
+
+Actions 里**根本没出现 publish 这个 run**，说明 tag 没推上去（或名字不是 `v` 开头）；
+出现 run 但红在第一步，通常是 tag 与 `package.json` 版本对不上。
+
+## 发完之后：让 DSH 用上新版
+
+profile 把版本钉在 `~/.dsh/profiles/<profile>/package.json` 里（例如 `"dsh-thesis": "1.0.1"`），
+所以 npm 上发了新版**不会自动生效**。到插件管理器里移除再装一次（会取 `latest`），或者把那条依赖
+改成 `"^2.0.1"` 后重装，然后**重启 DSH**——2.0 删掉了全部斜杠命令，不是热更新能覆盖的。
+
+## 手动触发
+
+Actions → publish → Run workflow：只做打包预览，**不会发布**。用来确认「这次发出去的包里到底有什么」。
+想真发版，还是打 tag。
+
+## 失败排查
+
+| 现象 | 原因 |
+|---|---|
+| `EOTP` / `This operation requires a one-time password` | 用的是需要 OTP 的 token（2FA 账号的 Granular / Publish token）。CI 里没人能输 OTP：改用可信发布，或换 Classic → Automation token |
+| `401 Unauthorized` | token 过期（Automation token 有 90/180 天寿命），或可信发布配置里 workflow 文件名写错 |
+| `npm ci … not in sync` | 改了 `package.json` 的依赖/peer 却没跑 `npm install --package-lock-only` |
+| `403 … cannot publish over previously published version` | 版本号没升；这条在 workflow 里已被「已存在则跳过」挡住，手动发版时要注意 |
+| 守卫里 `单元/契约测试` 红 | 本地 `npm test` 先复现；守卫跑的就是它 |
+| 守卫警告「未找到 DSH 安装」 | CI 里正常（没有宿主）；**发版前请在本地跑一次 `npm run test:host-load` 与 `npm run test:host`** |
+
+## 撤回与补救
+
+- **已发布的版本不能改**，只能 `npm deprecate dsh-thesis@2.0.1 "原因与替代版本"`。
+- 72 小时内理论上可以 `npm unpublish`，但那会让依赖它的人突然装不上，**不要用**。
+- 发错了就立刻发一个 patch：`2.0.2`。
+
+## 仍然可以本地发布
+
+```bash
+npm login
+npm publish --access public          # 会跑同一个 prepublishOnly 守卫，会交互式要 OTP
+```
+
+本地发布用的是你登录后的凭据（可以输 OTP），不需要 token，也不需要可信发布配置。
+CI 只是把「构建 → 校验 → 发布」串起来，判据完全一样。

package/docs/tools.md

@@ -0,0 +1,76 @@
+# 工具与技能
+
+工具名、命令面、技能名都是**对外契约**：改名就是破坏性变更。`npm run audit` 会把这三样
+都核对一遍（21 个工具 / 0 条斜杠命令 / 11 个技能 + 命名与 BOM 检查）。
+
+## 命名空间
+
+| 前缀 | 管什么 |
+|---|---|
+| `thesis_*` | 论文工作区里的东西（材料、要求、章节、检查、构建、答辩素材、幻灯） |
+| `defense_code_*` | 答辩层的代码演练（把系统拆成讲得清的模块） |
+| `fact_*` | 跨会话事实（学校规范、导师要求、写作偏好） |
+
+## `thesis_*`（15 个）
+
+| 工具 | 一句话 | 关键约束 |
+|---|---|---|
+| `thesis_ingest` | 把材料读成文本与结构摘要 | docx/xlsx/pptx/pdf/md/csv/bib + 源码目录；源码只给结构，不贴正文；已存在的摘要不覆盖 |
+| `thesis_intake` | 一次问一个要求问题，问成《意图规格》 | 必答项不齐拒绝 `done`；材料里能读出来的不重复问 |
+| `thesis_init` | 建论文工作区 | 空目录才能建；九阶段目录 + 台账 + 七章模板 + 技能包 + git |
+| `thesis_progress` | 看进度 / 过 G1-G4 | 关卡是**拒绝**不是提醒；关联任务未完成不许过关 |
+| `thesis_decide` | 记一条关键决定 | 内容/理由/备选三段，写进决定日志 |
+| `thesis_lit_search` | 真实检索文献 | Semantic Scholar → DBLP → arXiv → Crossref 降级；写检索缓存与审计记录 |
+| `thesis_lit_save` | 收录进 `refs.bib` | **只接受检索缓存里的 id**（零假文献的落点）；DOI 重复自动跳过 |
+| `thesis_lit_note` | 生成阅读笔记骨架 | 五节模板；已存在不覆盖 |
+| `thesis_review` | 单章六项评审 | 字数区间 / 大纲小节 / 引用编号 / 图表编号 / 未完成标记 / G2 清单 |
+| `thesis_check` | 全文五项检查 | 引用双向一致、字数、图表编号、术语定义顺序、学校模板探测 |
+| `thesis_stylecheck` | 六条 AI 味启发式 | 模板套话、空洞结论、自我暴露、翻译腔、句式单一、无锚点长段落 |
+| `thesis_build` | 出 `论文.docx` | 有 pandoc 用 pandoc + 学校模板，没有用内置零依赖生成器（显式标注） |
+| `thesis_originality` | 本地降重度量 | scan / verify / report；**不接收费查重**，报告里是本地估算 |
+| `thesis_defense` | 答辩素材 + 六类问题库 | 每个问题带证据锚点（哪个文件哪一行） |
+| `thesis_slides` | 答辩幻灯 | Marp 兼容 Markdown；outline / convert / check / guide；pptx 依赖外部引擎 |
+
+## `defense_code_*`（3 个）
+
+| 工具 | 一句话 |
+|---|---|
+| `defense_code_status` | 我的系统我讲得清吗（阶段、里程碑、验证门、未过的问题） |
+| `defense_code_next` | 下一个该弄懂的模块（todo + 评分要点） |
+| `defense_code_update` | 登记 / 推进 / 评分 / 重试（每次改动立即落盘） |
+
+语言矩阵内置 Go / TS / Python / Rust；其它语言在配置里补 `codeWalkthrough.gates`。
+
+## `fact_*`（3 个）
+
+| 工具 | 一句话 |
+|---|---|
+| `fact_search` | 上次记下的学校规范还在吗（key/value 子串检索） |
+| `fact_remember` | 记住一条跨会话仍成立的稳定事实 |
+| `fact_context` | 把这个课题已知的稳定事实一次性拉回来 |
+
+只记**跨会话仍然成立**的东西（学校规范、导师偏好、课题稳定事实）；进度、临时任务、一次性
+实验数字不进记忆，那些在台账与实验记录里。
+
+## 技能（11 个）
+
+随插件发布，`thesis_init` 把它们复制进论文仓库 `.dsh/skills/`，跟着论文一起 git 版本化。
+
+| 技能 | 解决什么 |
+|---|---|
+| `thesis-pipeline` | 全流程总纲：阶段、关卡、工具地图、会话入口顺序 |
+| `thesis-opener` | 选题与开题（课题怎么定、开题报告怎么写） |
+| `thesis-literature` | 文献调研：检索策略、阅读笔记、综述组织 |
+| `thesis-eng-design` | 需求 / 设计 / 选型论证的写法 |
+| `thesis-writing` | 逐章写作规范与验收标准 |
+| `thesis-citation` | GB/T 7714 引用格式（只解决「格式对不对」） |
+| `thesis-defense` | 答辩素材、问题库、幻灯与讲稿 |
+| `code-walkthrough` | 把系统拆成答辩讲得清的模块（配 `defense_code_*`） |
+| `paper-intake` | 材料到手后的追问方法论（怎么问出可证伪的要求） |
+| `paper-dedup` | 原创性与降重：本地度量、改写处方、复测 |
+| `thesis-inquiry` | 写作要求被质疑、导师口径模糊时怎么问清 |
+
+## 没有斜杠命令
+
+`ctx.commands` 一次都不注册。入口是自动驾驶（[autopilot.md](./autopilot.md)），
+或者直接跟模型说话让它调工具。

package/docs/troubleshooting.md

@@ -0,0 +1,88 @@
+# 排查
+
+## 装了但没反应 / 工具看不见
+
+宿主在装载前会校验 `package.json` 里 `@deepseek-ai/dsh*` 的 `peerDependencies`，
+**不满足就把这一行静默 `disabled`**（stderr 只有一句 `dsh: disabling profile plugin row …`）。
+本插件声明：
+
+```
+@deepseek-ai/dsh-tools: >=0.2.0-rc.2 <0.3.0-0
+```
+
+排查顺序：
+
+1. 确认 dsh 版本：`dsh --version`。跨小版本（0.3+）时这条 range 就要放宽，不能硬装。
+2. 跑 `npm run test:host-load`：它用**宿主自己的预检函数**判断真实副本会不会被停用。
+3. 跑 `npm run test:host`：真实 cordis 装配 + 真实工具注册表。
+4. 装了插件管理器却报 `installation rejected`：多半是旧版本缓存。`dsh plugin add dsh-thesis@<确切版本>` 钉住版本，
+   或 `pnpm cache delete dsh-thesis` 后再装。
+
+## 重启后还是旧行为
+
+- `dsh plugin add` 装的是 **npm 上的那一版**，改了源码不重装不会生效；本地开发用
+  `node scripts/install-into-profile.ts --profile web`（把 profile 指到本仓库，重启生效）。
+- DSH 没有 TS 加载器：**必须先 `npm run build`**（产出 `lib/`），直接指向源码不会工作。
+- 确认改到的是同一个 profile：`--profile web` 要和实际启动参数一致。
+
+## 说了话但没弹那道选择题
+
+自动驾驶只在「**论文工作区** + **主 agent** + **还没有意图规格**」时问。看会话日志：
+
+| 日志 | 含义 |
+|---|---|
+| `已有意图规格` | `00-管理/意图规格.md` 已存在，不再重复问（删掉它或换工作区可重新选）|
+| `意图选择题没有拿到答案` | UI 不接受非工具调用的问题卡片，或你取消了 |
+| `宿主没有 userQuestions 服务` | 这套组合没有问答面 |
+| `宿主没有 goals 服务` | 只会跑一轮，不自动续轮 |
+
+前三行都意味着：插件有意**不猜**你的意图。直接说话即可，工具都在。
+
+## 关卡没问就过了
+
+`autopilot.gateApproval` 被设成了 `false`。改成 `true` 就恢复「过人卡必须由人拍板」。
+
+## PDF 读不出文字
+
+扫描版（没有文本层）、加密 PDF、只有 CID 字体且无 ToUnicode 映射的 PDF 抽不出内容。
+工具会**如实说明原因**，不会编造。处理办法：先用 OCR 或另存一份带文本层的 PDF 再摄取。
+
+## `.pptx` 没生成
+
+幻灯的真相是 Markdown（`07-答辩/PPT.md`），`.pptx` 交给外部工具：
+
+```bash
+npx -y @marp-team/marp-cli 07-答辩/PPT.md --pptx
+# 或
+pandoc 07-答辩/PPT.md -o 07-答辩/PPT.pptx
+```
+
+两者都没有时，`thesis_slides convert` 会写一份 `07-答辩/PPT转换说明.md`（探测结果 + 确切命令 + 退出码），
+**绝不假装成功**。装了 marp 之后重跑即可。
+
+## 旧格式打不开
+
+`.doc` / `.xls` / `.ppt` 不支持，先另存为 `.docx` / `.xlsx` / `.pptx`。
+
+## 工具写到别的目录去了？
+
+不会，但会**报错**：配了 `workspace` 却找不到 `00-管理/进度台账.md` 时，工具直接失败而不是退回 cwd 探测。
+这正是防「写错地方」的设计。要么改 `workspace`，要么先在工作区跑 `thesis_init`。
+
+## 读文件失败 vs 文件不存在
+
+两者严格区分：读失败（权限 / IO）会抛错并保持原文件不动，绝不会用默认值覆盖。
+「读不出来 ≠ 不存在」是整个仓库的硬约束。
+
+## 中文乱码
+
+工作区里的文件统一 UTF-8（无 BOM）。Windows 上用 PowerShell 查看时加 `-Encoding utf8`：
+
+```powershell
+Get-Content 00-管理\进度台账.md -Encoding utf8
+```
+
+## 代价与限速
+
+- 自动续跑每一轮都是一次完整模型调用，`autopilot.maxGoalRounds` 是唯一刹车；调小它比事后心疼便宜。
+- 外部命令（pandoc / marp / git）走 `spawnSync`：有超时，**没有信号传递**（按下停止不会杀掉子进程）。

package/docs/usage.md

@@ -0,0 +1,87 @@
+# 使用手册
+
+> 只想知道怎么装：见 [README](../README.md)。这里讲**用起来是什么样**。
+
+## 前置条件
+
+- DSH 里装好 `dsh-thesis`，重启后可见 `thesis_*` / `fact_*` / `defense_code_*` 三组工具。
+- **把会话开在论文目录里**最省事：多数工具从会话 cwd 向上探测 `00-管理/进度台账.md` 来定位工作区。
+- 也可以显式指定：`config: { workspace: /path/to/你的论文 }`。配了它就**只认它**，路径写错会直接报错，
+  绝不会写到别的目录去。
+
+工作区可以是空的（还没有论文），`thesis_init` 会把九阶段目录、台账、决定日志、七章模板和技能包一次性建好。
+
+## 第一次会话
+
+把材料丢进工作区（或告诉它绝对路径），说一句：
+
+```
+这是我的论文材料，帮我做毕业设计
+```
+
+插件接管后是这样走的：
+
+1. **弹一道选择题**（只有一次）：从零走到答辩 / 只补合规与答辩 / 只做答辩准备 / 先别自动跑。
+   细节见 [autopilot.md](./autopilot.md)。
+2. 选定后建目标、自动一轮轮跑：材料摄取 → 逐题追问 → 文献 → 设计 → 实现 → 测试 → 论文 → 合规 → 答辩。
+3. 只在 **G1-G4 人工关卡**停下来，让你在审批界面点「允许」或「拒绝」。
+
+没有材料也能用：「我要做毕业设计，还没定题」→ 走选题工作坊，先定课题再进流水线。
+
+## 九阶段与关卡
+
+| 阶段 | 产出物 | 验收标准 | 人工关卡 |
+|---|---|---|---|
+| 1 选题 | 选题确认书 | 课题明确、工作量合理、答辩友好 | **G1** |
+| 2 开题 | 开题报告 + 任务书 | 导师认可；结构与规范达标 | **G3** |
+| 3 文献调研 | 文献库 + 笔记 + 综述素材 | 15-30 篇真实文献；每篇有笔记 | — |
+| 4 系统设计 | 需求/设计/选型文档 | 方案可落地；选型有论证 | — |
+| 5 系统实现 | 可运行系统 + git 提交 | 功能真实可跑 | — |
+| 6 系统测试 | 测试报告 + 真实结果 | 结果可复现；零伪造 | — |
+| 7 论文撰写 | 七章正文 | 逐章人工验收 | **G2**（每章一次） |
+| 8 定稿与合规 | 论文.docx + 检查报告 | 格式/引用/自查全部通过 | **G4** |
+| 9 答辩 | 幻灯 + 演练记录 | 能讲清设计与实现 | — |
+
+关卡由 `thesis_progress` 在工具层强制：未过该阶段的入口关卡时，任务推进会被**拒绝**（不是提醒）。
+
+## 材料与追问
+
+- `thesis_ingest <绝对路径>`：docx / xlsx / pptx / pdf / md / csv / bib，以及源码目录（只给文件、行数、
+  声明与技术栈，**不贴源码正文**）。产出 `00-管理/材料清单.md` 与逐文件摘要；已存在的摘要绝不覆盖。
+- `thesis_intake`：一次只问一个问题，每问都带「为什么问 / 影响哪个产出 / 合格答案形态」。
+  材料里能读出来的不重复问；必答项不齐时拒绝 `done`。答案落盘成 `00-管理/意图规格.md`（唯一真相）。
+- 断点续问：状态在 `.paper/intake.json`（相对工作区根），换会话接着问，不重复。
+
+## 常见动作
+
+| 想做的事 | 怎么说 / 调什么 |
+|---|---|
+| 换学校模板 | 把模板放进 `06-论文/assets/学校模板/`，再跑 `thesis_check`（探测到就用，探测不到显式标注「非学校模板」）|
+| 只改某一章 | 直接说「改第三章的方法部分」，改完 `thesis_review 03-设计` |
+| 回填学校查重结果 | `thesis_originality action=report detected_rate=12 detected_system=知网` |
+| 出 Word | `thesis_build`（有 pandoc 用 pandoc + 模板，没有就用内置零依赖生成器）|
+| 只做答辩 | `thesis_defense` → `thesis_slides` → 代码演练 `defense_code_*` |
+| 记住学校规范 | `fact_remember key=school.dedup.system value="知网，查重阈值 20%"` |
+| 看进度 | `thesis_progress action=report` |
+
+## 产出物
+
+| 产物 | 位置 |
+|---|---|
+| 意图规格（唯一真相） | `00-管理/意图规格.md` |
+| 材料清单 + 逐文件摘要 | `00-管理/材料清单.md`、`00-管理/材料/*.md` |
+| 进度台账 / 决定日志 / 时间线 | `00-管理/` |
+| 文献库与检索审计 | `02-文献/refs.bib`、`检索记录.md`、`笔记/` |
+| 章节与 Word | `06-论文/章节/*.md`、`06-论文/产出/论文.docx` |
+| 答辩素材 / 幻灯 / 问题库 | `07-答辩/` |
+| 检查报告（引用 / 格式 / AI 味 / 降重） | `08-合规/` |
+
+## 中断与续跑
+
+会话断了不要紧：进度、决定、追问状态、检索缓存全在工作区文件里。重开一个会话说一句
+「接着做」即可——`thesis_progress action=report` 会把当前阶段、未过的关卡与下一步报出来。
+
+## 多条流水线同时进行
+
+一个工作区 = 一个课题。不同课题就不同目录，各开各的会话；跨会话的稳定事实（学校规范、
+导师偏好）走 `fact_*`，那是全局共享的。

package/lib/autopilot/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 自动驾驶：插件在后台把流程推起来，人只在两处出现——**开头选一次意图**、**过关卡时拍一次板**。
+ *
+ * 为什么不让人敲命令：命令是给人操作 CLI 的入口，而这里真正的主角是模型与流水线。
+ * 插件要做的不是再提供一套动词，而是：
+ *
+ * 1. `agent/pre-step`：认出「这是论文工作区、用户还没定过意图」→ 问一道选择题
+ *    （`ctx.userQuestions.ask`，三四档常见起点）→ 把答案写进决定日志 →
+ *    `ctx.goals.create` 建目标（宿主的 goal-round-driver 此后自动续轮）→
+ *    注入一条 operating contract（怎么推进、怎么并行、哪里必须停）。
+ * 2. `tools/pre-execute`：模型要过 G1-G4 时拦一次 `ask`，由人在审批界面拍板。
+ *
+ * 两条铁律：**只对主 agent 生效**（子 agent 委派深度 > 0 一律跳过）、
+ * **只对论文工作区生效**（找不到台账就完全不介入，别的项目里装了这个插件也不受干扰）。
+ *
+ * @module dsh-thesis/autopilot
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AutopilotOptions } from '../config.ts';
+import type { AutopilotAnswerItem, AutopilotAgent } from './types.ts';
+/** 一个 agent 的委派深度：与宿主 `delegationDepthOf` 同一条规则（头里的深度只增不减）。 */
+export declare function agentDepth(agent: AutopilotAgent): number;
+/** 从结构化答案里取出被选中的标签（兼容多选与自定义输入）。 */
+export declare function selectedLabel(answer: {
+    readonly answers?: readonly AutopilotAnswerItem[];
+} | undefined): string | undefined;
+/** 装配参数：配置里的自动驾驶块 + 意图规格落盘位置（与 intake 共用同一份配置）。 */
+export interface AutopilotInstallOptions extends AutopilotOptions {
+    /** 意图规格文件相对论文工作区根的位置。 */
+    readonly specRel: string;
+}
+/**
+ * 装上自动驾驶的两处监听。
+ *
+ * 顺序关键：`agent/pre-step` 先 `await next()` 再注入（与写作意图闸门同一约定），
+ * 任何异常都吞成「不介入」，绝不把错误抛进 agent 循环。
+ */
+export declare function installAutopilot(ctx: Context, options: AutopilotInstallOptions): void;

package/lib/autopilot/index.js

@@ -0,0 +1,159 @@
+/**
+ * 自动驾驶：插件在后台把流程推起来，人只在两处出现——**开头选一次意图**、**过关卡时拍一次板**。
+ *
+ * 为什么不让人敲命令：命令是给人操作 CLI 的入口，而这里真正的主角是模型与流水线。
+ * 插件要做的不是再提供一套动词，而是：
+ *
+ * 1. `agent/pre-step`：认出「这是论文工作区、用户还没定过意图」→ 问一道选择题
+ *    （`ctx.userQuestions.ask`，三四档常见起点）→ 把答案写进决定日志 →
+ *    `ctx.goals.create` 建目标（宿主的 goal-round-driver 此后自动续轮）→
+ *    注入一条 operating contract（怎么推进、怎么并行、哪里必须停）。
+ * 2. `tools/pre-execute`：模型要过 G1-G4 时拦一次 `ask`，由人在审批界面拍板。
+ *
+ * 两条铁律：**只对主 agent 生效**（子 agent 委派深度 > 0 一律跳过）、
+ * **只对论文工作区生效**（找不到台账就完全不介入，别的项目里装了这个插件也不受干扰）。
+ *
+ * @module dsh-thesis/autopilot
+ */
+import { findThesisRoot } from "../paper/lib/project.js";
+import { runDecision } from "../paper/tools/decision.js";
+import { choiceOfLabel, INTENT_QUESTION_ID, intentQuestion } from "./intent.js";
+import { gateApprovalReason, makeAutopilotMessage } from "./messages.js";
+/** 一个 agent 的委派深度：与宿主 `delegationDepthOf` 同一条规则（头里的深度只增不减）。 */
+export function agentDepth(agent) {
+    const fromHeader = agent.session?.header?.subagentDepth ?? 0;
+    const fromOptions = agent.options?.subagentDepth ?? 0;
+    return Math.max(fromHeader, fromOptions);
+}
+/** 从结构化答案里取出被选中的标签（兼容多选与自定义输入）。 */
+export function selectedLabel(answer) {
+    const item = answer?.answers?.find(entry => entry.id === INTENT_QUESTION_ID) ?? answer?.answers?.[0];
+    if (item === undefined)
+        return undefined;
+    const picked = item.selected?.[0];
+    if (typeof picked === 'string' && picked.trim() !== '')
+        return picked;
+    if (typeof item.custom === 'string' && item.custom.trim() !== '')
+        return item.custom;
+    return undefined;
+}
+/** 意图规格是否已经存在（存在就不再打扰：用户已经定过要求，或已经跑过一轮）。 */
+async function specExists(ctx, root, specRel, signal) {
+    try {
+        await ctx.fs.readText(await ctx.fs.resolve(`${root}/${specRel}`, { signal }), signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 装上自动驾驶的两处监听。
+ *
+ * 顺序关键：`agent/pre-step` 先 `await next()` 再注入（与写作意图闸门同一约定），
+ * 任何异常都吞成「不介入」，绝不把错误抛进 agent 循环。
+ */
+export function installAutopilot(ctx, options) {
+    if (!options.enabled)
+        return;
+    const started = new Set();
+    ctx.on('agent/pre-step', async (payload, next) => {
+        const downstream = await next();
+        if (downstream.kind !== 'enter')
+            return downstream;
+        const agent = payload.agent;
+        if (agent === undefined)
+            return downstream;
+        if (agentDepth(agent) > 0)
+            return downstream;
+        const key = agent.id ?? 'anonymous';
+        if (started.has(key))
+            return downstream;
+        let root = null;
+        try {
+            root = await findThesisRoot(ctx.fs, agent.session?.header?.cwd, payload.signal);
+        }
+        catch {
+            // 配置的 workspace 写错、台账读不出来：都不属于「自动驾驶」该处理的场景。
+            return downstream;
+        }
+        if (root === null)
+            return downstream;
+        started.add(key);
+        if (await specExists(ctx, root, options.specRel, payload.signal)) {
+            ctx.logger.info('dsh-thesis: 已有意图规格，自动驾驶不再重复询问，按现有规格推进。');
+            return downstream;
+        }
+        const choice = await askIntent(ctx, agent, payload.signal);
+        if (choice === undefined)
+            return downstream;
+        try {
+            await runDecision(ctx.fs, { content: `自动驾驶启动：本次意图 = 「${choice.label}」（用户在启动选择题里确认；目标上限 ${options.maxGoalRounds} 轮）` }, root, payload.signal);
+        }
+        catch (error) {
+            ctx.logger.warn(`dsh-thesis: 自动驾驶意图写进决定日志失败：${error instanceof Error ? error.message : String(error)}`);
+        }
+        armGoal(ctx, agent, choice, options.maxGoalRounds);
+        return { kind: 'enter', messages: [...downstream.messages, makeAutopilotMessage(choice, options.maxGoalRounds)] };
+    });
+    if (options.gateApproval)
+        installGateApproval(ctx);
+}
+/** 问那一道选择题；拿不到答案（没有答题面 / 用户取消 / 选了「先别自动跑」）时返回 undefined。 */
+async function askIntent(ctx, agent, signal) {
+    const service = ctx.get('userQuestions');
+    if (service === undefined || typeof service.ask !== 'function') {
+        ctx.logger.info('dsh-thesis: 宿主没有 userQuestions 服务，自动驾驶跳过意图询问（改为按现有上下文推进）。');
+        return undefined;
+    }
+    try {
+        const answer = await service.ask({ questions: [intentQuestion()], agent, ...(signal === undefined ? {} : { signal }) });
+        const label = selectedLabel(answer);
+        if (label === undefined)
+            return undefined;
+        const choice = choiceOfLabel(label);
+        // 认不出的标签（例如用户自己输入了别的）按「关掉自动驾驶」处理，绝不猜。
+        if (choice === undefined || choice.objective === '') {
+            ctx.logger.info(`dsh-thesis: 用户没有选择自动推进（${label}）。`);
+            return undefined;
+        }
+        return choice;
+    }
+    catch (error) {
+        ctx.logger.info(`dsh-thesis: 意图选择题没有拿到答案（${error instanceof Error ? error.message : String(error)}），本次不自动推进。`);
+        return undefined;
+    }
+}
+/** 建目标：宿主的目标轮驱动器会按它自动续轮，直到完成或轮数用尽。 */
+function armGoal(ctx, agent, choice, maxGoalRounds) {
+    const goals = ctx.get('goals');
+    if (goals === undefined || typeof goals.create !== 'function') {
+        ctx.logger.info('dsh-thesis: 宿主没有 goals 服务，自动驾驶只推进当前一轮（不会自动续轮）。');
+        return;
+    }
+    try {
+        goals.create(agent, { objective: choice.objective, maxGoalRounds });
+    }
+    catch (error) {
+        ctx.logger.warn(`dsh-thesis: 建目标失败，本轮流完就停：${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** 人工关卡拦截：模型要过 G1-G4 时，先让人在审批界面拍一次板。 */
+function installGateApproval(ctx) {
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        if (exec.agent === undefined)
+            return next();
+        if (exec.name !== 'thesis_progress')
+            return next();
+        const args = exec.arguments;
+        if (args === undefined || args.action !== 'gate' || args.pass !== true)
+            return next();
+        const gate = typeof args.gate === 'string' ? args.gate.toUpperCase() : '关卡';
+        const chapter = typeof args.chapter === 'string' ? args.chapter : undefined;
+        const note = typeof args.note === 'string' ? args.note : undefined;
+        return {
+            kind: 'ask',
+            reason: gateApprovalReason({ gate, ...(chapter === undefined ? {} : { chapter }), ...(note === undefined ? {} : { note }) }),
+        };
+    });
+}

package/lib/autopilot/intent.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 自动驾驶的文案与意图选项：**一次只问一个问题**，答案决定接下来跑到哪一步。
+ *
+ * 这里的文本是插件直接呈现给用户的（不是给模型的），所以用词要能让人一眼选：
+ * 三档常见起点 + 一个「先别自动跑」。选完就不再打断，直到撞上人工关卡。
+ *
+ * @module dsh-thesis/autopilot
+ */
+/** 意图选择题的问题 id（宿主按 id 把答案回传）。 */
+export declare const INTENT_QUESTION_ID = "dsh-thesis.intent";
+/** 一档意图：选项文案 + 目标 + 启动指令里要向模型交代的边界。 */
+export interface IntentChoice {
+    /** 选项标签（用户看到的那一行）。 */
+    readonly label: string;
+    /** 选项说明（UI 可渲染在标签下方）。 */
+    readonly description: string;
+    /** 写进 goal 的目标（宿主按它渲染续跑提示）。 */
+    readonly objective: string;
+    /** 注入给模型的第一条指令正文；空串表示「用户不要自动跑」。 */
+    readonly instruction: string;
+}
+/** 「先别自动跑」的选项标签：回答它等于关掉本次自动驾驶。 */
+export declare const HANDS_OFF_LABEL = "\u5148\u522B\u81EA\u52A8\u8DD1\uFF0C\u6211\u81EA\u5DF1\u6765";
+/** 三档起点 + 一个关闭项（顺序即 UI 顺序）。 */
+export declare const INTENT_CHOICES: readonly IntentChoice[];
+/** 把用户选的标签映射回一档意图；认不出来时返回 undefined（按「关掉」处理）。 */
+export declare function choiceOfLabel(label: string): IntentChoice | undefined;
+/** 构造那一道选择题。 */
+export declare function intentQuestion(): {
+    readonly id: string;
+    readonly header: string;
+    readonly question: string;
+    readonly detail: string;
+    readonly options: readonly {
+        readonly label: string;
+        readonly description: string;
+    }[];
+};
+/** 启动指令消息的正文（含「这条不是用户需求」的免责声明）。 */
+export declare function autopilotInstruction(choice: IntentChoice, maxGoalRounds: number): string;