教练模式 slimeball2026/DSH-Coach-mode

教练模式 · Coach Mode

这是一个由 slimeball 与 deepseek v4.1flash 以及 deepseek v4.1flash1017 共同开发的项目。

让 AI 带你自己动手学会一个工具，而不是替你做完。

「教练模式」是 DeepSeek Harness 的一个 agent preset（插件包）。装好后新建会话时，模式列表里会多出一个「教练模式」。

它和普通助手的区别不在提示词写得多好，而在状态机长在代码里：一次只给一步、必须核查、不许代做、进度和证据都落在会话日志里。模型想跳到下一步，得先让插件校验通过。

demo

目录

- 它解决什么问题
- 它怎么工作
- 功能
- 安装
- 快速开始
- 用户看到的固定格式
- 仓库结构
- 开发
- 版本
- 设计与文档
- 已知限制
- 许可

它解决什么问题

提示词能覆盖的部分，实测早就不错了；但有两个窟窿改提示词补不上：

- 硬核查不会自发触发：模型可以一直「讲得很好」，却从没读过用户的文件、没跑过一条命令。
- 软核查判定会漂移：同一情形，这次判「无法判断」，下次判「通过」。

所以这个项目的做法是：把能写成 if 的都写成 if——阶段、前置条件、证据失效、失败阈值、检索预算，全部由插件持有；提示词只负责「怎么说话」。

它怎么工作

INIT ──coach_plan──▶ (确认环境) ──▶ PLAN ──受理──▶ WAIT_FEEDBACK / INSTALL_TOOL │ ┌────────────────────────┤ ▼ ▼ coach_check（只读取证） coach_research（联网补全） │ ▼ coach_verify（落盘结论）──▶ 通过 ──▶ coach_advance ──▶ 下一步 / COMPLETE │ 不通过 ──▶ 本步失败 +1 └── 无法判断 ──▶ DEGRADED

它管得住的三件事：

1. 一次只给一步：计划建立后，状态块只暴露当前步骤。
2. 核查必须落盘：结论只能通过工具提交；只在正文里写「通过了」不算，状态不会变。
3. 不代做：write / edit 在工作区里会被确定性拒绝。

它还管这些：安装分支（工具没装时把「装好并跑通」当成临时目标）、同会话回退、暂停/恢复、检索缓存、进度摘要、按表现调整讲解详细度、检索与状态块的预算。

功能

| 能力 | 说明 |
| 强制核查 | file / command 类证据必须先取证再判定；重复核查必须引用新证据 |
| 安装分支 | 工具不可用时先走「安装并跑通」，完成后自动回到原目标；发现其实装好了可以一步早退 |
| 联网检索 | coach_research 自动脱敏检索词，来源写进缓存；失败不自动降级 |
| 同会话回退 | 回到更早的步骤重做；回退之前的结论/证据/跳过一律作废 |
| 暂停 / 恢复 | 「先停一下」有明确暂停点；关掉再打开同一会话仍是暂停，恢复不作废旧证据 |
| 进度摘要 | 已完成/跳过/剩余、当前板块、本步失败、检索次数 |
| 脚手架递减 | 按板块表现给出 1–3 级讲解详细度（放手 / 给要点 / 手把手），核查标准不随之放宽 |
| 成本控制 | 每步检索上限、状态块字符预算、检索正文上限，以及每轮的 【用量】 |
| 跳过与出口 | 多次失败后给出明确出口：跳过 / 暂停 / 换目标；跳过必须说出口 |

安装

从本仓库安装

用任何带 plugin_manager 工具的会话，发一条：

请用 plugin_manager 安装这个本地目录： <本仓库绝对路径>\coach-mode-bundle

安装会弹一次审批。返回 applied 即成功；之后完全退出 DSH 再重新打开，新建会话时选「教练模式」。

从 .tgz 安装

plugin_manager action: install_bundle
target: <某个目录>\local-coach-mode-0.4.2.tgz

注意事项

- 安装/覆盖之后必须重启 DSH：只重启不重装可能跑旧模块代，只重装不重启不会加载新代码。
- profile 里是 link: 安装时，改代码只需重启；install_bundle 返回 already-installed 属正常。
- 目录方式安装后不要移动或删除那个目录（profile 直接指向它）。

快速开始

新建一个「教练模式」会话，发：

我想学 Git，但我不太会。

正常节奏是：先确认你电脑上能不能用 Git → 问你的水平和目标 → 拆成几个板块 → 一次给你一步 → 你做完反馈 → 它核查 → 下一步。

它不是万能的：不会替你点软件，不会改你的文件，也不跨会话记进度。

用户看到的固定格式

每一步（字段之间会空行）：

【当前板块】【本步目标】【请执行】【预期结果】【请反馈】截图 / 文件 / 报错 / 文字描述【合格标准】

每次核查后：

【核查结果】通过 / 不通过 / 无法判断【原因】【建议】【下一步】

仓库结构

coach-mode-bundle/ ← 插件本体（安装目标） index.js 宿主插件入口：状态块 + 守卫 + 8 个工具 cordis.patch.yml 唯一的声明文件（preset + persona） config.js 配置默认值与归一化（不导出 schema） projection.js 按需折叠会话日志 → CoachState inject.js 每轮状态块注入 guard.js write / edit 的确定性拒绝 core/ 纯核心：零宿主 import、零 IO、零时间、零随机 tools/ 8 个教练工具 + 本地 defineTool test/ 零依赖单测（149 个用例） README.md 行为、Config、已知限制（改动前先读）

SPEC-档2-教练模式.md 施工图：Q1–Q7 决策、状态机、各版本实现与验收 coach-mode-档1-验收报告.md 档 1 的验收证据（会话 id + 事件 seq）

prompt_and_work-document/ 按阅读顺序编排的设计/交接文档（00–13） _ref/ 验收与回放工具（冒烟、日志回放、会话转写、取证） _verify-20261018/ 0.4.1 / 0.4.2 的验收结论（原始会话日志未入库）

开发

要求：Node 24.x（实测 24.21.0）、DeepSeek Harness 0.2.1-rc.1。
powershell

单测（在 coach-mode-bundle 目录内；不要传 test/）

node --test --test-isolation=none

装配冒烟（零宿主依赖，覆盖真磁盘 fs、守卫、检索与预算）

node ../_ref/smoke-coach.mjs

用当前代码重折一条真实会话日志，看每个状态块"应该"长什么样

node ../_ref/replay-check.mjs <session.v4.jsonl.zstd>

两条硬约束（test/decoupling.test.js 会拦）：

1. 整包禁止 import '@deepseek-ai/'。宿主包装在 app.asar 里，profile 装的 bundle 解析不到，一行 import 就会让整个 preset 显示「加载失败」。需要的能力走 ctx.，工具定义用本地的 tools/define-tool.js。
2. core/ 零 Node 内置模块、零时间、零随机。状态全部从会话日志折叠，所以重启、恢复、fork 之后都能重算；改折叠语义必须递增 stateVersion。

改完：install_bundle 覆盖安装 → 重启 DSH → 新会话验证。

版本

当前 0.4.2（2026-10-18）。完整版本记录见 CHANGELOG.md。

- stateVersion 9、8 个教练工具、11 个相位、单测 149
- 验收：A1–A15（A8–A15 有实机记录，见 SPEC-档2-教练模式.md 与 _verify-20261018/）

设计与文档

- 施工图：SPEC-档2-教练模式.md——决策台账（Q1–Q7、D1–D11、R1–R16）、状态机、每个版本的设计与实机结论。
- 行为与配置：coach-mode-bundle/README.md——工具、状态块、Config、已知限制、排版坑。
- 设计史：prompt_and_work-document/——按"接手的人该读的顺序"编排的 14 份文档（从 00. 阅读顺序.md 开始）。

这些历史文档里的本机路径已统一替换为 C:\Users\<user>；文档编号与内容保持原样。

已知限制

- 没有 UI / slash 命令：全部通过对话完成，模式切换在建会话时。
- 只做同会话：暂停、回退、进度都跟当前会话绑定，不跨会话续接。
- pwsh / bash 不加守卫："不代做"在命令行这一项上仍靠提示词；文件编辑是物理拒绝的。
- Config 没有 schema / 表单：字段只能手改 cordis.patch.yml，写错会静默回落默认值。
- 支撑等级是软约束：它改变"讲多细"，但计划里的 【请执行】 原文不变，模型仍可能讲得太细。
- 检索正文上限在本机不触发：宿主的 web.search 目前只返回来源、不返回正文。
- 依赖 DSH 插件 API：客户端版本变化可能导致加载失败；升级后先跑单测与冒烟。

许可

尚未指定开源许可。在添加 LICENSE 之前，默认保留所有权利。