dsh-dev-plan-presets 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cordis.patch.yml CHANGED
@@ -20,3 +20,5 @@
20
20
  honorExplicit: false
21
21
  audit: true
22
22
  guardAllSubagents: false
23
+ mainToolMode: ask-edit
24
+ mainStepWarnThreshold: 6
package/detail.md CHANGED
@@ -4,11 +4,12 @@
4
4
 
5
5
  一个给昂贵主模型用的 DSH Agent preset 包。主窗只做规划、派工与复核,实际施工交给 `develop` 子代理;内置子代理模型守门,避免子代理误继承昂贵主模型。
6
6
 
7
- 0.3.0 的结构变化:
7
+ 0.4.0 的结构与提速优化:
8
8
 
9
- - 从「bundle 里静态写一份 `@deepseek-ai/dsh-agent-preset` 行」改为「Host 插件在运行时 `ctx.agentPresets.register()` 动态注册」;
9
+ - 从「bundle 里静态写一份 `@deepseek-ai/dsh-agent-preset` 行」改为「Host 插件在运行时 `ctx.agentPresets.register()` 动态注册」,只注册单个 `dev-plan` 预设,不向 DSH 预设列表暴露多余子预设;
10
+ - 主窗 persona 压缩至 ≤ 6,000 字符(SSOT 零重复),并将紧凑版侦察/文书模板融入主预设且明确标注**仅给子代理用**;
10
11
  - 新增 `develop` 委派工具,让主窗直接派工、收汇报、派独立复核、再返工给同一 `developer`;
11
- - 新增插件设置页(`plugins.row.config`)与 Host 路由:施工方式从宿主已安装的任意 DSH 预设中选择,provider/model 从宿主目录联动选择;
12
+ - 新增插件设置页(`plugins.row.config`)与 Host 路由:支持 `stateVersion`/`stateTag` + ETag `304`、700ms/30s 自适应轮询、`modelCatalog` 空闲预热、可选 `mainToolMode`(`none`/`readonly`/`ask-edit`,永不挂 Shell)与主窗步数软提醒阈值 `mainStepWarnThreshold`;
12
13
  - 吸收 `dsh-subagent-model-pin` 的子代理模型守门能力;
13
14
  - preset 真源从 YAML 迁移到 `preset.js`,运行期不依赖 `js-yaml` 或 `@deepseek-ai/schemastery`。
14
15
 
@@ -31,7 +32,7 @@
31
32
  - 不设 `allowedAgentPresets`;
32
33
  - `agentOptions` 来自同一设置真源(`childProvider` / `childModel` / 可选 `childReasoningEffort`)。
33
34
 
34
- `recon` / `review` / `scribe` 永远绑定 `standard`;只有 `develop` 随设置切换。所选预设由宿主 `agentPresets` 目录决定,设置页不维护第二份白名单。
35
+ `recon` / `review` / `scribe` 始终绑定 `standard`,紧凑版约束模板直接融入主预设并明确标注**仅给子代理用**(避免在 DSH 预设列表显示多余子预设);只有 `develop` 随设置切换。所选预设由宿主 `agentPresets` 目录决定,设置页不维护第二份白名单,并禁用内部预设 id。
35
36
 
36
37
  ## 三、主窗合同
37
38
 
@@ -65,6 +66,8 @@
65
66
  | `honorExplicit` | `false` | 是否尊重子代理显式路由 |
66
67
  | `audit` | `true` | 是否写审计日志 |
67
68
  | `guardAllSubagents` | `false` | 默认只守 dev-plan 子代理;勾选后全局 |
69
+ | `mainToolMode` | `ask-edit` | 主窗工具权限:`ask-edit`(默认,`read`/`edit`/`write` 经同意局部微改,无 Shell)/ `readonly`(仅 `glob`/`grep`)/ `none`(纯规划派工) |
70
+ | `mainStepWarnThreshold` | `6` | `mainToolMode !== 'none'` 时主窗单轮步数软提醒阈值(`2..30`,永不改模型/不取消) |
68
71
 
69
72
  保存链路:Client → `/plugins/dev-plan-presets/config` → 严格 Standard Schema 校验 → `configEditor.edit(entry, ...)` → profile patch → Loader 重建。不手改 profile 的 `cordis.patch.yml`,也不在插件目录写 `config.json`。
70
73
 
@@ -176,6 +179,11 @@
176
179
 
177
180
  **未验证**(不得写成已通过):
178
181
 
182
+ - 0.4.0 新增真机 Host 验收项:
183
+ - 通过 `plugin_manager` 重新安装/启用 0.4.0 后,新建 `dev-plan` 会话验证 `recon` 实际使用 `dev-plan-scout` 且主窗不再输出千字模板;
184
+ - 对比真实任务体感耗时(规划输出长度、首次 `recon` 到回复耗时、`develop` 派工前等待时间);
185
+ - 在设置页切换 `mainToolMode` 为 `readonly` / `ask-edit`,新建会话验证主窗只读定位与“经用户同意后局部微改”行为,且主会话模型不被守门篡改;
186
+ - 验证设置页打开时模型列表即时显示、DevTools Network 面板稳态下转为 30s 保活 + `304`(不再每 4 秒全量刷新 `/state`)。
179
187
  - 插件页“已安装 → 开发规划与交付模式 → 包含组件 → 行标题/右箭头”入口、设置页真实渲染、明暗主题、语言切换、ARIA/焦点环;
180
188
  - 设置页 404 降级/停止轮询/手动刷新/network 指引的真实浏览器表现;
181
189
  - 真实浏览器交互(按钮/焦点/提示);无 Origin 非浏览器客户端、非监听 host、更多代理/地址形态(真实 HTTP 已覆盖 same-origin、localhost alias、DNS rebinding 形状、错误端口;fake req 全矩阵不等于真实浏览器);
@@ -0,0 +1,349 @@
1
+ # dsh-dev-plan-presets v0.4.0 全局提速与工程优化开发文档
2
+
3
+ > **文档定位**:可直接交给快速执行模型(如 Gemini 4 Hydrogen)按步骤落地的自足开发与验收规格书。
4
+ > **目标版本**:`0.4.0`(基于当前 `0.3.0` 基线,`56/56` 单测全绿)
5
+ > **核心痛点**:对话干活流程慢、主窗思考/打字久、子代理冷启动与往返多、设置页存在无效轮询与首屏延迟。
6
+ > **不可突破的插件理念(红线)**:
7
+ > 1. 昂贵主模型的核心定位仍是 **规划、派工、复核与决策**,绝不放任主模型把额度烧在大仓库遍历、反复试错跑命令或大段写代码上;
8
+ > 2. 所有委派子代理继续钉死在便宜模型(`modelGuardMode=pin`,默认仅守 `dev-plan` 父会话的子代理,**主会话永不被守门改模型**);
9
+ > 3. **派工事实**(仅实际 `develop` / `send_message` 工具调用算派工,文本不算)、**事实归属**(不把子代理自述当自己跑过测试)、**证据化审查**、**用户授权边界** 一条不退;
10
+ > 4. **运行期零 `dependencies`**,不 import `js-yaml` 或 `@deepseek-ai/*`,不修改 profile 文件,不引入重型调度器/DAG。
11
+
12
+ ---
13
+
14
+ ## 一、现状瓶颈全景(实测数据与精确位置)
15
+
16
+ | 编号 | 瓶颈 | 实测 / 代码证据 | 对“慢/卡”的直接影响 |
17
+ |---|---|---|---|
18
+ | B1 | **主模型每次委派都要“手抄”固定角色模板** | `preset.js:128-177, 200, 368-379`:`SCOUT_TEMPLATE` 1,125 字、`SCRIBE_TEMPLATE` 888 字,强制主模型每次调 `recon`/`review`/`scribe` 原文复制进 `prompt` | 主模型按 35~50 tok/s 输出,仅抄模板就白卡 **15~25 秒/次**,还烧昂贵 output tokens |
19
+ | B2 | **主窗 System Prompt 极度膨胀且高冗余** | `preset.js:183-396`:`prefix` 11,952 字 + `suffix` 696 字 = **12,648 字符**;同一条规则在 5~7 个章节反复出现 | 拉高 TTFT;诱发推理模型每轮生成超长合规自检 CoT,回复明显变慢 |
20
+ | B3 | **同一件事写三遍文档 + `recon` 每次冷启动** | `preset.js:260, 271, 299`(9 项计划合同 → 7 项开工契约 → 10+ 项任务书);`recon` 无复用规则 | 规划→开工前主模型反复打字;每次查证都冷启动新 `standard` 子代理重读上下文 |
21
+ | B4 | **`recon`/`review`/`scribe` 全背沉重 `standard` preset** | `preset.js:458-460` | 每次 spawn 加载十几个被禁用的插件与几十个无用工具 schema,冷启动慢且拖慢子代理推理 |
22
+ | B5 | **主窗“绝对零只读” + 8KB 截断自相矛盾** | `preset.js:450-453`(`thresholdChars: 8192`)vs `preset.js:308-327`(强制贴完整 diff,缺 diff 必须返工补证据) | 看 30 行文件也要绕一圈子代理;稍大 diff 触发截断 → 补证据往返 |
23
+ | B6 | **设置页首屏干等 4s + 每 4s 双连重渲染** | `client.js:189-195, 393-395, 742-790` + `index.js:534-539` | `modelCatalog` 首次请求才冷枚举,前端写死 4s 轮询导致首屏卡 4s;稳态每 4s 触发 2 次整页 React 重渲染 |
24
+ | B7 | **Host 启动冗余复检 + Guard 潜在内存滞留** | `index.js:387`(已找到目标 preset 2s 后仍重扫);`guard.js:148-155, 302-334` | 多余的 `registry.list()` 调用;异常退出若漏发 `agent/disposed` 会滞留 `agent` 引用 |
25
+ | B8 | **自检对旧中文原句刚性锁死** | `scripts/verify-presets.mjs`(1,650 行,472 项静态检查大量硬编码中文原句) | 导致 prompt 只敢追加不敢压缩重构 |
26
+
27
+ ---
28
+
29
+ ## 二、架构设计总览(五个正交模块)
30
+
31
+ 本次优化分为 **5 个解耦的工作包(WP1 ~ WP5)**,按依赖顺序逐个实现并验证。
32
+
33
+ ### WP1:受控的主窗轻实操能力(可配置,默认极克制)
34
+
35
+ #### 设计结论与理念守恒
36
+ 针对“主模型希望偶尔直接用一点工具做小查证或微改动,但必须经过用户同意、避免烧额度”的需求,不能无约束把 Shell/写工具塞给主窗,而是新增一个显式设置项 `mainToolMode`(三档枚举):
37
+
38
+ | 档位值 | 名称 | 主窗额外挂载的插件 | 核心规则与防烧额度机制 | 适用人群 |
39
+ |---|---|---|---|---|
40
+ | `'none'`(**默认**) | 纯规划派工 | 无(与 0.3.0 完全一致) | 自身永不直接读/写/跑命令,100% 保持原教旨 | 极度省主模型额度、严格分工 |
41
+ | `'readonly'` | 定点只读核验 | 仅挂载 `@deepseek-ai/dsh-tool-fs-search`(`glob` / `grep`) | 允许主窗直接做极小范围的文件定位/符号搜索,**仍无写入和 Shell 能力**;大仓库遍历仍交 `recon` | 希望消除“找个文件/搜个符号也要等子代理”的卡顿,零误改风险 |
42
+ | `'ask-edit'` | 授权微实操 | 挂载 `@deepseek-ai/dsh-tool-fs`(`applyPatch: false`)+ `@deepseek-ai/dsh-tool-fs-search`;**永远不挂 `bash`/`pwsh`/`workflow`/`jobs`/`schedule`** | 1. **只读核验**(`read`/`glob`/`grep`)限小范围定点核对(≤ 3 个文件 / 看一眼关键片段),大面积扫描仍交 `recon`;<br>2. **任何写/改(`write`/`edit`)必须先获用户本轮明确同意“主窗直接改”**,单次同意仅限 **≤ 2 个文件、局部小改(约 ≤ 50 行)**;<br>3. **绝不跑 Shell/测试命令**(无 Shell 工具),需要跑测试/大改仍交 `develop`;<br>4. **Host 层步数软闸门**(见下):连续实操步数超过阈值时自动向主会话注入一次额度告警,防止主模型陷入自嗨循环 | 既想主窗秒查文件/在同意后秒改几行小 bug,又不想主模型失控烧额度 |
43
+
44
+ > **为什么不挂 `bash`/`pwsh` 给主窗?**
45
+ > Shell 命令是主模型烧额度最快、最不可控的源头(跑测试失败 → 读报错 → 改代码 → 再跑测试的死循环)。把 Shell 与构建/测试永远留在便宜的 `develop` 子代理侧,能从机制上守住 90% 的额度防线。
46
+
47
+ > **为什么默认仍是 `'none'`?**
48
+ > 保证升级兼容与零意外:现有用户配置升级到 0.4.0 后行为与原理念完全一致;想提速的用户在设置页一键切到 `'readonly'` 或 `'ask-edit'` 即可生效(新会话生效)。
49
+
50
+ #### Host 层防烧额度保护(配合 `'readonly'` / `'ask-edit'`)
51
+ - 在 `settings.js` 新增:
52
+ - `MAIN_TOOL_MODES = Object.freeze(['none', 'readonly', 'ask-edit'])`
53
+ - `mainToolMode: 'none'`(默认值)
54
+ - `mainStepWarnThreshold: 6`(整数,范围 `2..30`,默认 `6`:仅在 `mainToolMode !== 'none'` 时对 `dev-plan` 主会话生效;单轮用户回合内主窗连续走过超过阈值步的 LLM step 时,通过 `agent.inject()` 或日志提示“当前主模型已连续执行较多步骤,建议将后续探索/修改转交 `recon` 或 `develop` 以节省主模型额度”,**绝不 `cancel` 主会话,绝不修改主会话模型**)。
55
+ - **重要边界**:主会话的“额度步数提醒”必须独立于 `modelGuardMode` 的子代理守门,且:
56
+ - **永不调用 `agent.model.select()`**;
57
+ - **永不 `reject` 或 `cancel` 主会话**(只做温和提醒,每轮最多提醒 1 次,下一轮用户消息重置计数,避免刷屏)。
58
+
59
+ ---
60
+
61
+ ### WP2:干掉主模型手抄 1,125 字模板 & 轻量化子代理(最大提速点)
62
+
63
+ #### 核心改造:用轻量内置子 preset 替代 `standard` + 逐字手抄模板
64
+
65
+ 当前 `recon` / `review` / `scribe` 每次调用慢 15~25 秒,根因是它们挂了沉重的 `standard` 且靠主模型把 1,125 / 888 字模板抄进 `prompt`。
66
+
67
+ **架构方案(双保险,100% 仅依赖已验证的 `ctx.agentPresets.register()` API)**:
68
+
69
+ 1. **在 `preset.js` 新增两个轻量内置子预设构造器**(纯函数,零外部依赖):
70
+ - `SCOUT_PRESET_ID = 'dev-plan-scout'`(供 `recon` 与 `review` 使用)
71
+ - `order: 990`(排在预设列表最底,不干扰主预设;若未来宿主支持 `hidden: true` 可透传 `hidden: true`,但不得依赖它)
72
+ - `name: '开发规划 · 内部侦察/复核(勿直选)'`
73
+ - `description: 'dev-plan 内部轻量子代理:仅挂载只读文件/搜索/网页工具,内置只读与证据输出契约。'`
74
+ - **极简插件清单**(相比 `standard` 砍掉 bash/pwsh/workflow/jobs/schedule/goal/skill/todo/present/subagent/plan-mode 十几个插件):
75
+ - `@deepseek-ai/dsh-persona`(直接内置精简后的只读侦察/复核 persona,~450 字!)
76
+ - `@deepseek-ai/dsh-agent-instructions`(`maxBytes: 32768`,减半)
77
+ - `@deepseek-ai/dsh-compaction-basic` + `@deepseek-ai/dsh-compaction-tool-result-pruner`(`thresholdChars: 12288, headChars: 6144, tailChars: 1536`)
78
+ - `@deepseek-ai/dsh-tool-fs`(`applyPatch: false` — 提供 `read`/`read_image`,persona 声明禁止 `write`/`edit`)
79
+ - `@deepseek-ai/dsh-tool-fs-search`(`glob`/`grep`)
80
+ - `@deepseek-ai/dsh-tool-web`(`web_search`/`web_fetch`)
81
+ - `SCRIBE_PRESET_ID = 'dev-plan-scribe'`(供 `scribe` 使用)
82
+ - `order: 991`
83
+ - `name: '开发规划 · 内部文书(勿直选)'`
84
+ - `description: 'dev-plan 内部轻量子代理:仅挂载文件工具,只负责把定稿文档逐字落盘。'`
85
+ - **极简插件清单**:
86
+ - `@deepseek-ai/dsh-persona`(直接内置精简后的文书落盘 persona,~350 字!)
87
+ - `@deepseek-ai/dsh-compaction-basic`
88
+ - `@deepseek-ai/dsh-tool-fs`(`applyPatch: false` — 提供 `read`/`write`/`edit`)
89
+
90
+ 2. **在 `index.js` 中一起注册 & 清理**:
91
+ - 在 `publish()` 中先注册 `dev-plan-scout` 和 `dev-plan-scribe`(各自收集 disposer),再注册 `dev-plan`;
92
+ - **回退安全网**:如果某内部子 preset 注册失败(例如宿主禁止注册多 preset 或抛异常),自动降级让 `recon`/`review`/`scribe` 回退到 `standard`,并在 `state.warnings` 里显式记录,**绝不导致主 preset 注册失败**;
93
+ - `dev-plan` 里的 `resolveDevelopMode` 和设置页 `presetChoices` 自动禁用内部预设(`selfIds = ['dev-plan', 'dev-plan-scout', 'dev-plan-scribe']`),防止用户误选内部只读预设作为 `developMode`!
94
+ - `dispose()` 时按逆序释放所有注册返回的 disposer。
95
+
96
+ 3. **彻底取消主模型手抄模板**:
97
+ - 当内部轻量子预设注册成功时,`dev-plan` 主窗的 `recon` / `review` 绑定 `agentPreset: 'dev-plan-scout'`,`scribe` 绑定 `agentPreset: 'dev-plan-scribe'`;
98
+ - 主窗 persona **不再包含 2,013 字的 `SCOUT_TEMPLATE` / `SCRIBE_TEMPLATE` 全文**,主模型调用 `recon` / `review` / `scribe` 时**只需直接写简洁的任务与输出要求**,彻底省掉每次 **15~25 秒** 的模板抄写时间与几百个昂贵 output tokens!
99
+ - 若降级回 `standard`(极端异常),`buildPersona` 会附带精简版提示(≤ 250 字)兜底。
100
+
101
+ > **关于 `preset.js` 导出的向后兼容**:继续导出精简后的 `SCOUT_TEMPLATE` 与 `SCRIBE_TEMPLATE` 常量(用于内置子预设 persona 和单测),不再在正常模式下把它们拼进主窗 `prefix`。
102
+
103
+ ---
104
+
105
+ ### WP3:主窗 Persona 瘦身 55%+ & 协作协议提速(消除“三遍文档”与冷启动)
106
+
107
+ #### 硬量化指标
108
+ - 主窗 `persona.prefix + persona.suffix` 总字符数从 **12,648 字符** 压缩到 **≤ 5,500 字符**(目标 **4,500 ~ 5,200 字符**,减少 **55%~60%**)。
109
+ - **零信息丢失原则**:每条硬规则只在一处权威位置写清(SSOT),禁止跨章节重复粘贴 4~6 遍。
110
+
111
+ #### 具体精简与提速规则(写入 `preset.js` 的 `buildPersona`)
112
+
113
+ 1. **合并“三遍文档”为“单契约复用”**:
114
+ - **快速路径**(范围清楚、单/少量文件、可回滚、验证明确):
115
+ - 规划阶段只输出 **极简计划(≤ 15 行)**:路径判断、改动文件、验收命令、非目标,直接问一句“确认开工?”;
116
+ - 获批后直接把这份精简契约作为 `develop` 的 `prompt` 发出,**不再扩写成 10 段官样文章**。
117
+ - **标准 / 高风险路径**:
118
+ - 规划阶段输出的「开工契约」与 `develop` 任务书采用 **同一套 8 字段紧凑结构**(目标 / 非目标 / 允许路径 / 接口约束 / 验收标准 / 检查命令 / 风险回退 / 变更证据与汇报要求),开工时直接带工作区绝对路径与 `cwd` 发给 `develop`,无需重写第二遍。
119
+ - **禁止废话**:规划阶段不需要写背景长文、方案散文;直给结论、取舍表与契约。
120
+
121
+ 2. **引入 `recon` 复用与并发纪律**:
122
+ - 同一任务的持续取证,首次固定 `name=scout`,后续补充查证优先用 `send_message` 续问同一个 `scout`(保留已读上下文,避免反复冷启动);
123
+ - 遇到 2~3 个互不依赖的模块查证时,允许主窗**单回合并行**调用多个 `recon`(命名 `scout-1`、`scout-2`),用并发换串行等待。
124
+
125
+ 3. **修复 `tool-result-pruner` 与 Diff 交付策略的矛盾**:
126
+ - 在 `preset.js` 中,将主窗的 `tool-result-pruner` 配置从 `{ thresholdChars: 8192, headChars: 4096, tailChars: 1024 }` 调整为:
127
+ `{ thresholdChars: 24576, headChars: 16384, tailChars: 4096 }`;
128
+ - 在 `develop` 汇报契约中明确**分层变更证据**:
129
+ - 改动 ≤ 200 行:直接附真实 `git diff`(或新文件关键内容);
130
+ - 改动 > 200 行:附 `git diff --stat` + 关键逻辑变更的真实 hunks + 完整 diff 导出位置/命令,避免灌爆主窗上下文或被截断引发二次补证据往返;
131
+ - 仍坚守红线:只有文件清单/口头摘要不算审过 diff,必须先 `send_message` 让同一 `developer` 补真实变更证据。
132
+
133
+ 4. **保留的全部核心合同清单(必须在新版精简 persona 中 100% 明确保留)**:
134
+ - 角色定位与 `mainToolMode` 对应的工具纪律(`none`:永不亲自写代码/不调未声明工具;`readonly`:仅允许小范围 `glob`/`grep` 定点核验;`ask-edit`:仅在用户当轮明确同意后允许 ≤ 2 文件 / ≤ 50 行的局部微改,永不跑 Shell);
135
+ - 施工目录与权限红线:调 `develop` 必须传 `cwd` 参数、派工前核对可写范围、不得先建后 `cd`、父会话事后提权不扩大已有子代理权限、权限失败如实记录 `cwd`/沙箱/原错并停止重试;
136
+ - 派工事实红线:文本不是派工,必须实际调用 `develop`(首次 `name=developer`)并收到接受结果后才可说“已派出 developer”,之后结束回合等自动完成通知;返工必须实际调用 `send_message`;失败/未调用必须如实报“未派工”及原因;
137
+ - 双通道互斥:同一任务不得混用 `develop` 与 `rework_task` / `ask_worker`;
138
+ - P0 五条完整保留(精炼表达):
139
+ - P0-1 风险分级(快速/标准/高风险;四维:歧义、影响面、可逆性、可验证性;绝不因验证困难降级;快速路径不取消用户批准、developer 自验、主窗审查);
140
+ - P0-2 一次性开工契约(批准一次覆盖已批准范围;普通实现不反复请示;仅范围扩大/风险变化/宿主权限要求重新确认);
141
+ - P0-3 验收前置与成本排序(最小切片 → 语法/静态契约 → 针对性测试 → 必要运行/GUI 验收;静态检查不等于真实验证);
142
+ - P0-4 非阻塞协作(依赖自动通知,不轮询、不忙等、不重复施工、不重复读 developer 正在改的文件;developer 仅在阻塞/范围冲突/关键契约决策时打断);
143
+ - P0-5 证据化审查与严重度返工(汇报标 `verified` / `partial` / `failed` / `未验证`;按阻塞/重要/建议审查;阻塞续派同一 developer,非阻塞不无限打磨;主窗最终审查责任不外包);
144
+ - 事实归属(`suffix`):不把子代理自述当自己跑过测试,引用写明“按 developer 汇报”;无工具调用接受不得声称已派出/已返工/已验证;无实际 diff/等价证据只算摘要审查。
145
+ - 禁止在 persona 中写 `{{...}}` 模板变量。
146
+
147
+ ---
148
+
149
+ ### WP4:Host 与 Client 运行时工程去卡顿
150
+
151
+ #### 4.1 `index.js` 优化清单
152
+ 1. **引入单调状态版本号 `stateVersion`**:
153
+ - 任何写入 `state`、`violations`、`warnings`、`modelCatalog` 的地方调用 `bumpState()`(`stateVersion += 1`);
154
+ - `GET /plugins/dev-plan-presets/state` 响应新增 `stateVersion` 字段,同时支持 `If-None-Match: "<stateVersion>"`(命中返回 `304 Not Modified`,零 JSON 序列化、零响应体),响应头带 `etag: "<stateVersion>"`。
155
+ 2. **缓存不可变派生值**:
156
+ - `const cachedRoute = routeOf(settings)` 在 `apply()` 初始化时算一次,不再每次 `buildState()` 重跑 `normalizeSettings()`。
157
+ 3. **修复 `scheduleVerification()` 冗余二次全量探测**:
158
+ - `index.js:387` 原条件:
159
+ `const needsRecheck = settings.developMode !== 'standard' || state.presets.checked !== true`
160
+ - 改为:
161
+ `const needsRecheck = state.mode?.fallback === true || state.presets.checked !== true`
162
+ - 效果:首次探测已成功找到目标 preset(如 `deep-ptc`)时,不再在 2s 后白跑第二次 `registry.list()`。
163
+ 4. **空闲预热 `modelCatalog`**:
164
+ - 在 `webServer` 路由注册完成后,用 `setTimeout(() => void refreshModelCatalog(), 300)`(并 `.unref()`,且在 `effect` 卸载时 `clearTimeout`)提前在后台预热一次模型目录;
165
+ - 这样用户点开设置页时,大概率 **0ms 直接命中已就绪缓存**,彻底消除首屏“模型列表读取中…”干等 4 秒的问题。
166
+ - **测试兼容性注意**:保留“静置 60s 最多 2 轮枚举”和“`/state` 不阻塞等待枚举”的现有测试契约;可以通过 `runtime?.prewarmModelCatalog !== false` 控制(默认开启,或预热与 `/state` 共享 `modelCatalogInFlight` 与 `60_000ms` TTL,只要 TTL 内不重复枚举,60s 内仍是最多 2 次!)。
167
+
168
+ #### 4.2 `guard.js` 优化清单
169
+ 1. **`agent/pre-step` 快速路径前置**:
170
+ - 在 `installStepGuard` 的 `handler` 顶部(`await next()` 之前)加入:
171
+ ```js
172
+ if (settings.modelGuardMode === 'off') return next()
173
+ if (stopped) return { kind: 'reject' }
174
+ ```
175
+ - 仍在 `await next()` 之后核对 `payload?.modelSelection`(防止下游插件在 `pre-step` 中修改模型绕过检查)。
176
+ 2. **修复 `steps` Map 潜在内存滞留**:
177
+ - 在 `installModelGuard` 中,给 `installStepGuard` 传入 `onDispose` 回调(或在包装 `dispose` 时同步 `steps.delete(agent)`),保证无论是 `agent/disposed` 事件还是 `agent.ctx.effect` 销毁,都能从 `steps` Map 移除强引用。
178
+ 3. **新增主会话步数预算软提醒(仅 `mainToolMode !== 'none'` 时激活)**:
179
+ - 新增导出函数 `installMainStepBudget(ctx, settings, hooks)`(或整合进 `installModelGuard` 旁边的独立轻量 effect,确保 `modelGuardMode === 'off'` 时也能独立工作):
180
+ - 只监听非子代理(`!isSubagentHeader(header)`)且 `presetOfSession(ctx, agent.session) === PRESET_ID` 的主会话;
181
+ - 在主会话 `agent.ctx.on('agent/pre-step', ...)` 中计数连续步骤,超过 `settings.mainStepWarnThreshold` 时只调用一次温和提醒(`hooks.audit` + 若有 `agent.inject` 则注入一条简短提示,或记入状态告警),**严禁调用 `agent.model.select`、`agent.cancel` 或返回 `{ kind: 'reject' }`**;
182
+ - 可通过检测新用户回合/消息数变化(或时间窗口间隔 > 60s)重置当前回合计数。
183
+
184
+ #### 4.3 `client.js` 优化清单
185
+ 1. **自适应轮询 + 页面不可见暂停 + `stateVersion` 跳过无变化渲染**:
186
+ - 请求 `GET /plugins/dev-plan-presets/state` 时带上 `If-None-Match`(若有上次的 `stateVersion`),收到 `304` 直接 return,**零 JSON 解析、零 `setState`**;
187
+ - 若返回 `200` 且 `json.stateVersion === lastVersionRef.current`,同样跳过 `setState`;
188
+ - **自适应间隔**:
189
+ - 当 `!state || state.registration === 'pending' || state.registration === 'switching' || !state.modelCatalog?.checked || !state.presets?.checked` 时:使用短间隔 **700ms** 快速收敛;
190
+ - 一旦稳定(`ready` 且目录均 `checked`):**停止高频轮询**(拉长到 **30,000ms** 轻量保活,且在 `document.hidden === true` 时跳过请求;监听 `visibilitychange` 切回前台时立即刷新一次)。
191
+ 2. **消除无谓重渲染与内存泄漏**:
192
+ - 使用 `React.useMemo` 缓存 `presetChoices(...)`、`providerChoices(...)`、`modelChoices(...)`(仅在依赖数组变化时重算);
193
+ - 使用 `AbortController` + `inFlight` 引用防止并发请求堆积与卸载后 `setState`;
194
+ - 用 `timersRef` 管理保存后的 `600ms / 1800ms` 延迟刷新定时器,在 `useEffect` cleanup 时全部 `clearTimeout`;
195
+ - `useEffect([config, dirty])` 对比 JSON/字段是否真变再 `setDraft`,避免无意义二次渲染。
196
+ 3. **设置页新增「主窗工具权限(`mainToolMode`)」下拉 + 步数提醒阈值输入**:
197
+ - 在 `FIELD_LABELS` 增加 `mainToolMode` 与 `mainStepWarnThreshold` 中英文标签;
198
+ - 下拉三档清晰标注额度影响:
199
+ - `none` — 仅规划派工(默认,最省主模型额度)
200
+ - `readonly` — 允许小范围只读检索(glob/grep,不可改文件)
201
+ - `ask-edit` — 经我同意后允许微改文件(read/edit/write,无 Shell)
202
+ - 仅在 `draft.mainToolMode !== 'none'` 时启用 `mainStepWarnThreshold` 输入框,并附明确提示:“超过阈值仅提示转交子代理,绝不强制中断或改换主模型。”
203
+ - `presetChoices` 接收 `selfIds` 数组(兼容旧 `selfId` 字符串),将 `dev-plan`、`dev-plan-scout`、`dev-plan-scribe` 均标为不可选(禁用)。
204
+
205
+ ---
206
+
207
+ ### WP5:验证与测试体系重构(解耦文案锁死,保持高防回归覆盖)
208
+
209
+ #### 1. `settings.js`
210
+ - 新增导出 `MAIN_TOOL_MODES = Object.freeze(['none', 'readonly', 'ask-edit'])`;
211
+ - `DEFAULT_SETTINGS` 新增 `mainToolMode: 'none'`、`mainStepWarnThreshold: 6`;
212
+ - `validateSettings()` 严格校验:
213
+ - `mainToolMode` 必须在 `MAIN_TOOL_MODES` 内;
214
+ - `mainStepWarnThreshold` 必须为 `2..30` 的整数(非整数或越界返回 `issues`);
215
+ - `normalizeSettings()` 容错兜底:缺省/旧配置平稳收敛到默认值;
216
+ - `cordis.patch.yml` 补齐 `mainToolMode: none`、`mainStepWarnThreshold: 6`。
217
+
218
+ #### 2. `scripts/verify-presets.mjs` 重构原则
219
+ 当前 1,650 行里有大量对旧 12,648 字中文原句的硬编码正则。重构时必须:
220
+ - **新增性能预算硬断言**(防止未来 persona 再次膨胀):
221
+ - `persona.prefix.length + persona.suffix.length <= 6000`(实测目标 4,500~5,200 字符);
222
+ - 当内部子 preset 启用时,主窗 `prefix` 不包含 `ROLE-TEMPLATE:SCOUT:BEGIN` / `ROLE-TEMPLATE:SCRIBE:BEGIN`(证明不再让主模型手抄模板);
223
+ - `dev-plan-scout` 与 `dev-plan-scribe` 插件清单中**绝对不含** `dsh-tool-bash`、`dsh-tool-pwsh`、`dsh-tool-workflow`、`dsh-tool-jobs`、`dsh-tool-schedule`、`dsh-tool-goal`、`dsh-tool-skill`、`dsh-tool-todo`、`dsh-tool-subagent`、`dsh-plan-mode`;
224
+ - `mainToolMode='none'` 时主窗仍不含任何 `FORBIDDEN_MAIN_PLUGINS`;
225
+ - `mainToolMode='readonly'` 时主窗仅新增 `@deepseek-ai/dsh-tool-fs-search`,仍不含 `dsh-tool-fs`/`bash`/`pwsh`;
226
+ - `mainToolMode='ask-edit'` 时主窗仅新增 `dsh-tool-fs` + `dsh-tool-fs-search`,仍**绝对不含** `bash`/`pwsh`/`workflow`/`jobs`/`schedule`/`goal`/`skill`/`todo`/`plan-mode`;
227
+ - **将原句正则收敛为核心语义不变量断言**(如:核验 `cwd` 规则、派工事实、P0-1~P0-5 核心要素、双通道互斥、事实归属、授权微改边界),并保留对应的**负向变异测试**(至少覆盖所有核心安全与性能不变量,确保改坏任何红线都会 FAIL)。
228
+
229
+ #### 3. `test/plugin.test.mjs` 新增测试用例
230
+ 在保留原有 56 个核心行为断言(同步更新版本号 `0.4.0` 与内部 preset 断言)基础上,补充:
231
+ 1. `preset` 长度预算断言:`total <= 6000` 字符,且正常模式下主窗不包含长模板,子代理 `recon`/`review` 指向 `dev-plan-scout`、`scribe` 指向 `dev-plan-scribe`;
232
+ 2. 内部轻量子预设插件面断言:`dev-plan-scout` 无 Shell/委派、`dev-plan-scribe` 仅含 `tool-fs`;
233
+ 3. 内部子预设注册失败降级测试:模拟 `registry.register` 对 `dev-plan-scout` 抛错时,自动降级 `recon`/`review` 回 `standard` 并记录 warning,主 `dev-plan` 仍成功注册;
234
+ 4. `mainToolMode` 三档矩阵测试:`none` / `readonly` / `ask-edit` 的主窗插件清单、persona 规则、严格 schema 校验与 `forbidden` 检查;
235
+ 5. `index.js` 性能优化测试:
236
+ - 首次探测已找到 `deep-ptc` 时不再触发冗余二次 `registry.list()`;
237
+ - `GET /state` 返回 `stateVersion` 与 `etag`,携带匹配 `If-None-Match` 返回 `304`;
238
+ - 启动空闲预热 `modelCatalog` 后首次 `GET /state` 直接命中 `checked: true`,且 60s 内仍满足最多 2 次枚举上限;
239
+ 6. `guard.js` 测试:
240
+ - `stopped=true` 时 `agent/pre-step` 直接返回 `{ kind: 'reject' }` 不再调用 `next()`;
241
+ - `agent.ctx.effect` 释放后 `steps` Map 同步清理(不依赖 `agent/disposed`);
242
+ - `mainToolMode='ask-edit'` 下主会话连续步骤超 `mainStepWarnThreshold` 触发一次温和提醒,但**不 `select`、不 `cancel`、不 `reject`**;
243
+ 7. `client.js` 行为测试:
244
+ - `presetChoices` 禁用 `dev-plan`、`dev-plan-scout`、`dev-plan-scribe`;
245
+ - `mainToolMode` 变更与保存、304 跳过重渲染逻辑的静态/纯函数验证。
246
+
247
+ ---
248
+
249
+ ## 三、分步实施计划(给执行模型的精确作业顺序)
250
+
251
+ 请严格按以下 6 步顺序推进,每完成一步跑一次 `node --check` 确认无语法错误:
252
+
253
+ ### Step 1:`settings.js` 与 `cordis.patch.yml`
254
+ - [ ] 在 `settings.js` 添加 `MAIN_TOOL_MODES`、`mainToolMode`(默认 `'none'`)、`mainStepWarnThreshold`(默认 `6`,`2..30` 整数)到 `DEFAULT_SETTINGS`、`normalizeSettings`、`validateSettings`。
255
+ - [ ] 在 `cordis.patch.yml` 的 `config` 中补齐 `mainToolMode: none` 和 `mainStepWarnThreshold: 6`。
256
+ - [ ] 更新 `package.json` 版本号到 `0.4.0`(同步 `index.js` 的 `export const version = '0.4.0'`)。
257
+
258
+ ### Step 2:`preset.js`(核心提速改造)
259
+ - [ ] 新增常量导出:`SCOUT_PRESET_ID = 'dev-plan-scout'`、`SCRIBE_PRESET_ID = 'dev-plan-scribe'`、`INTERNAL_PRESET_IDS = Object.freeze([PRESET_ID, SCOUT_PRESET_ID, SCRIBE_PRESET_ID])`。
260
+ - [ ] 新增纯函数 `buildScoutPresetDefinition()` 与 `buildScribePresetDefinition()`(极简只读/文书插件集合 + 精悍内置 persona)。
261
+ - [ ] 更新 `resolveDevelopMode()`:对 `INTERNAL_PRESET_IDS` 全部做自引用保护(回退 `standard` 并给明确 reason)。
262
+ - [ ] 重写 `buildPersona(mode, options)`(接收 `settings.mainToolMode` 与 `internalPresetsActive`):
263
+ - 压缩到 **4,500 ~ 5,500 字符**(严格 ≤ 6,000);
264
+ - 合并重复条款,实现“单契约复用”、“`recon` 固定 `name=scout` 复用 + 独立查证并行”、“大 diff 分层汇报”;
265
+ - 按 `mainToolMode` 动态生成对应的一小段「主窗工具权限」条款(`none` / `readonly` / `ask-edit`);
266
+ - `internalPresetsActive === true` 时不拼接 `SCOUT_TEMPLATE` / `SCRIBE_TEMPLATE`;降级时拼接极简版(≤ 250 字)。
267
+ - [ ] 更新 `buildPresetDefinition({ settings, mode, internalPresets })`:
268
+ - 根据 `settings.mainToolMode` 决定主窗插件清单(`none` 不加;`readonly` 加 `tool-fs-search`;`ask-edit` 加 `tool-fs` + `tool-fs-search`;永不加 Shell/Workflow/PlanMode);
269
+ - 调整 `tool-result-pruner` 为 `{ thresholdChars: 24576, headChars: 16384, tailChars: 4096 }`;
270
+ - `recon`/`review` 的 `agentPreset` 使用 `internalPresets?.scout ? SCOUT_PRESET_ID : STANDARD_PRESET_ID`;
271
+ - `scribe` 的 `agentPreset` 使用 `internalPresets?.scribe ? SCRIBE_PRESET_ID : STANDARD_PRESET_ID`。
272
+
273
+ ### Step 3:`guard.js`
274
+ - [ ] 在 `installStepGuard` 的 `handler` 顶部提前处理 `modelGuardMode === 'off'` 与 `stopped === true`。
275
+ - [ ] 让 `installStepGuard` 接受 `onDispose` 回调并在 `dispose()` 时调用,确保 `agent.ctx.effect` 清理时同步 `steps.delete(agent)`。
276
+ - [ ] 新增 `installMainStepBudget(ctx, settings, hooks)`:仅在 `settings.mainToolMode !== 'none'` 时监听 `dev-plan` 主会话 `agent/pre-step`,单轮步数超 `mainStepWarnThreshold` 时只发一次温和提醒(不 `select`、不 `cancel`、不 `reject`)。
277
+
278
+ ### Step 4:`index.js`
279
+ - [ ] 引入 `stateVersion` + `bumpState()`;`GET /state` 支持 `If-None-Match` 返回 `304` 并在 200 响应头返回 `etag` 及响应体包含 `stateVersion`、`presets.disabledIds: INTERNAL_PRESET_IDS`。
280
+ - [ ] 缓存 `cachedRoute = routeOf(settings)`;更新 `state.internalPresets = { scout: false, scribe: false }`。
281
+ - [ ] 在 `publish()` 中先尝试注册 `buildScoutPresetDefinition()` 与 `buildScribePresetDefinition()`(单独 `try/catch`,单点失败降级回 `standard` + warning),统一管理全部 `releases[]` 并在 `switchTo()` / `dispose()` 时安全释放。
282
+ - [ ] 修复 `scheduleVerification()`:`const needsRecheck = state.mode?.fallback === true || state.presets.checked !== true`。
283
+ - [ ] 启动 `installMainStepBudget` effect(与子代理守门解耦)。
284
+ - [ ] `webServer` 注册时安排一次可取消的空闲预热 `setTimeout(() => void refreshModelCatalog(), 300)`(支持 `runtime?.prewarmDelayMs` 便于单测控制)。
285
+
286
+ ### Step 5:`client.js`
287
+ - [ ] 重构 `useHostState()`:支持 `If-None-Match` / `304`、`stateVersion` 对比防重复 `setState`、自适应轮询(未就绪 700ms,就绪后 30,000ms + `document.hidden` 暂停 + `visibilitychange` 恢复)、`AbortController` 并发防重入与 unmount 清理。
288
+ - [ ] 清理保存后的 `setTimeout` 定时器(`timersRef`);`setDraft` 前做字段变化判断。
289
+ - [ ] 用 `React.useMemo` 包装 `presetChoices`、`providerChoices`、`modelChoices`;`presetChoices` 支持屏蔽 `disabledIds`(含 `dev-plan-scout`、`dev-plan-scribe`)。
290
+ - [ ] 在设置页增加「主窗工具权限(`mainToolMode`)」与「主窗连续步数提醒阈值(`mainStepWarnThreshold`)」控件与完整中英文文案/无障碍属性(`id`/`htmlFor`/`aria-describedby`),只使用现有 `--dsw-alias-*` / `--dsw-radius-*` token。
291
+
292
+ ### Step 6:测试、自检与文档同步
293
+ - [ ] 同步更新 `scripts/verify-presets.mjs`(更新版本号、新增性能预算/轻量 preset/`mainToolMode` 断言与对应负向变异、解除对旧 12K 中文原句的死板耦合)。
294
+ - [ ] 同步更新并扩展 `test/plugin.test.mjs`(覆盖全部新增测试点,确保原有核心测试意图全部保留)。
295
+ - [ ] 同步更新 `README.md`、`detail.md`、`locale/zh.json`、`locale/en.json`(如实记录 0.4.0 变更及“仍需真实宿主验收项”,不得把单测写成真实运行验收通过)。
296
+
297
+ ---
298
+
299
+ ## 四、验收标准与检查命令(顺序执行,全部 PASS 才算完成)
300
+
301
+ ```powershell
302
+ # 1. 语法检查(全部 5 个运行时文件)
303
+ node --check index.js
304
+ node --check preset.js
305
+ node --check settings.js
306
+ node --check guard.js
307
+ node --check client.js
308
+
309
+ # 2. 量化指标检查(persona <= 6000 字符,且默认无内联长模板)
310
+ node -e "
311
+ import('./preset.js').then(m => {
312
+ const def = m.buildPresetDefinition({
313
+ settings: { mainToolMode: 'none' },
314
+ mode: m.resolveDevelopMode({ requestedMode: 'standard' }),
315
+ internalPresets: { scout: true, scribe: true },
316
+ });
317
+ const p = def.plugins.find(x => x.id === 'persona').config;
318
+ const total = p.prefix.length + p.suffix.length;
319
+ console.log({ prefix: p.prefix.length, suffix: p.suffix.length, total });
320
+ if (total > 6000) process.exit(1);
321
+ if (p.prefix.includes('ROLE-TEMPLATE:SCOUT:BEGIN')) process.exit(1);
322
+ });
323
+ "
324
+
325
+ # 3. 完整单元测试
326
+ node --test --experimental-test-isolation=none
327
+
328
+ # 4. 静态 + 行为 + 负向变异自检
329
+ node scripts/verify-presets.mjs
330
+
331
+ # 5. 打包清单检查(确认无多余临时文件,零 dependencies)
332
+ npm pack --dry-run
333
+ ```
334
+
335
+ ### 人工 / 真实 Host 验收项(执行模型完成后留给用户验证,禁止模型自行勾选)
336
+ - [ ] 通过 `plugin_manager` 重新安装/启用本包后,新建 `dev-plan` 会话,验证 `recon` 实际使用 `dev-plan-scout` 且主窗不再输出千字模板;
337
+ - [ ] 对比真实任务体感耗时(规划输出长度、首次 `recon` 到回复耗时、`develop` 派工前等待时间);
338
+ - [ ] 在设置页分别切换 `mainToolMode` 为 `readonly` 与 `ask-edit`,新建会话验证主窗只读定位与“经用户同意后局部微改”行为,且主会话模型不被守门篡改;
339
+ - [ ] 验证设置页打开时模型列表即时显示、DevTools Network 面板稳态下不再每 4 秒刷 `/state`。
340
+
341
+ ---
342
+
343
+ ## 五、边界约束与禁止事项(执行模型必读)
344
+
345
+ 1. **禁止引入任何 npm 依赖**(`package.json` 的 `dependencies` 必须为空,不 import `@deepseek-ai/*` 或 `js-yaml`)。
346
+ 2. **禁止直接修改 `D:\DSH-Home` 下的任何文件**(仅修改本仓库 `packages/dsh-dev-plan-presets` 内源码)。
347
+ 3. **禁止执行 `git commit` / `git push`**,也不要修改不相关的兄弟插件目录。
348
+ 4. **禁止放松任何安全边界**:`POST /config` 的来源校验(Origin / `Sec-Fetch-Site` / `application/json`)和 `guard.js` 的“主会话永不改模型/不取消”红线必须原样保留。
349
+ 5. **如实汇报**:如果某项宿主行为无法在单测中验证,明确标为「未在真实 Host 验证」,不得把单测通过写成真实运行通过。