# v0.3 参谋方向引擎 > 关键原则:**模型输出结构化数据,缩进树只是前端展示形式。** > 提示词树是视图,局势模型才是核心。 ## 为什么另开一版 v0.2 的产物是"一段可执行提示词";缩进树是它的附属展示,树里只有 label 和效果说明。 v0.3 把这个关系倒过来:**核心对象是局势模型**(意图 / 事实 / 推断 / 未知 / 关键矛盾 / 方向 / 推荐 / 待确认问题),缩进树是这份模型的分层视图,选中方向后再导出一段可执行提示词。 这样才能做到"用户补一句新信息 → 更新原树"而不是"重新生成一段漂亮长文"。 ## 数据流 ``` 用户一句话 ↓ 固定输入结构:意图 / 已知背景 / 当前约束 / 已有参谋状态 / 当前模式 / 已验证信息 意图识别(mode 可显式指定,否则按草稿推断) ↓ 事实 / 推断 / 假设 / 未知 分离 ↓ 局势建模 → 关键矛盾 → 战略方向(2–4) → 方向比较 → 推荐 or 暂不推荐 ↓ 第一行动 + 继续/转向/停止信号 ↓ 局势模型(JSON,核心对象) ↓ 缩进树 = 该模型的一个视图(每个节点带类型/来源/置信度/影响/状态) 会话态快照(按 sessionId 存)→ 下次带 resume=true 走"更新" ↓ 选中方向 → /enhance 导出可执行提示词 → 采纳写回输入框 ``` ## 已实现并验证 ### Host:`lib/advisor.js`(引擎核心) | 能力 | 导出 | |---|---| | 主系统提示词(定位/基本原则/八步流程/JSON 契约/树节点规则/增量更新规则) | `ADVISOR_SYSTEM_PROMPT` | | 审查提示词(手动触发) | `REVIEW_SYSTEM_PROMPT` | | 模式推断(按特异性排序:侦察 > 决策 > 复盘 > 执行 > 谋划) | `inferMode` | | 固定输入结构拼装(含 current_state 回填) | `buildAdvisorInput` | | 宽松 JSON:去围栏 / 取首对象 / **截断修复**(闭合未完成字符串 + 补括号) | `extractJsonObject` | | 树节点校验裁剪(type/source/confidence/impact/status 白名单 + 深度/数量上限) | `normalizeNode` | | 局势模型校验裁剪(方向 2–4、问题 ≤3、推荐 id 不存在则退回"暂不推荐") | `normalizeAdvisorModel` | | 结构化 / 纯文本降级双路径 | `parseAdvisorOutput` | | 审查结果规范化 | `normalizeReview` | | 缩进树文本渲染(根子节点顶格,非末尾分支带竖线) | `renderTreeText` | | 会话态快照(sessionId 键 + TTL + 容量上限,独立类便于换持久化) | `AdvisorStateStore` | 上限:方向 ≤4、问题 ≤3、每数组 ≤8 项、文本 ≤600 字、树深 ≤7、节点 ≤160、 子节点 ≤24。**上限存在的意义是"不再增加决策价值",不是"替模型决定输出长度"。** ### Host:路由(`lib/index.js`) | 路由 | 语义 | |---|---| | `POST /prompt-enhancer/advisor` | 生成或更新局势模型;`resume:true` 时带上本会话上一份模型 | | `POST /prompt-enhancer/review` | 手动复查(审查器提示词),不阻断 | | `POST /prompt-enhancer/enhance` | 把选定方向导出成可执行提示词(复用 v0.2 能力) | | `GET /prompt-enhancer/diag` | 只读诊断:分片统计、思维链长度、`finish` 原因 | `maxTokens` 传 `ADVISOR_MAX_TOKENS = 12000`,超时 `ADVISOR_TIMEOUT_MS = 240_000`。 (历史教训:2600 小于模型思考阶段本身,必然截断成空正文。) ### 测试 `test/advisor.mjs` —— 10 组契约测试,全部通过。编写过程中它抓出并修掉了 3 个真实缺陷: 1. **模式推断顺序敏感**:`调研规划` 被误判为 planning(应为 reconnaissance)→ 改为按特异性排序。 2. **截断修复吞数据**:回溯到最后一个逗号会把 `[1,2` 里完整的 `2` 丢掉 → 改为直接闭合未完成字符串。 3. **根节点分支前缀错误**:根的直接子节点不该带 `└──`(设计稿是顶格)。 ### 真实模型端到端 `POST /prompt-enhancer/advisor`(`tokenrhythm/deepseek-v4-flash-0731`,10.7s): ``` structured = true mode = decision finish = stop 思维链 = 0 intent.primary = 决策是否辞职独立开发 (confidence medium) key_tensions = ["稳定收入 vs 创业自由", "短期财务安全 vs 长期职业潜力"] directions = A:全职独立开发 | B:边工作边开发 | C:先观察后决策 recommendation = undetermined(信息不足,正确地没有硬拍板) questions = 3 个 tree = 17 节点 ``` ## 客户端接线(已完成) 参谋 UI 已**并入 `lib/client.js` 的同一个模块工厂**(该包只下发一个客户端模块: `dsh.client` 单条 + `ClientModuleRegistry` 扫描产物;多子模块的正规做法是一个模块内部装载)。 | 注册 | 插槽 | id | 顺序 | |---|---|---|---| | 🧭 参谋按钮 | `conversation.input.right` | `advisor-engine` | 18 | | ✨ 改写按钮 | `conversation.input.right` | `prompt-enhancer` | 20 | | 参谋面板 | `conversation.input.dock` | `advisor-engine` | 390 | | 改写面板 | `conversation.input.dock` | `prompt-enhancer` | 400 | 快捷键:`Ctrl+Shift+Enter` 改写、`Ctrl+Shift+J` 参谋。两套状态同处一个快照但各自读自己那段; 任一方关闭都会把对方面板一并收起,避免互相留在屏幕上。 参谋面板内容:模式条(自动/侦察/谋划/决策/执行/复盘)→ 用户意图 → 关键矛盾 → 事实/推断/假设/未知四色分组 → 战略方向卡(可逆性·信息增益·第一步,推荐带 ★)→ 方向详情(前提/收益/代价/风险/继续·转向·停止信号)→ 待确认问题 → 缩进树(带 类型·来源·置信度·状态徽标,已否决/已过时视觉降级)→ 推荐依据与「不选其它」→ 复查结果 → 导出结果;动作:重新分析 / 续研(带上当前局势)/ 复查 / 导出提示词 / 采纳。 `lib/advisor-client.js` 保留为可独立阅读的 v0.3 UI 参考实现(参谋样式的单一来源)。 ## 接线过程中被测试抓出的四个真实缺陷 1. **`requestJson is not defined`** —— 参谋代码用了自造助手,而 v0.2 只有内联 `fetch`。 已抽成统一助手,改写路径一并改用(`code/detail` 透传只有一处实现)。 2. **`ENHANCE_ROUTE is not defined`** —— 合并两套代码时沿用了不同常量名(v0.2 叫 `ROUTE`)。 3. **`advReview is not a function`** —— 组件作用域里函数名遮蔽了同名状态字段,点「复查」调到的是对象; 状态字段改名 `advReviewResult`。 4. **`reset()` 未清参谋态** —— 改写流程结束时参谋面板会留在屏幕上(两个状态机互相污染)。 另修三处测试自身问题:按注册顺序取组件(顺序一变就静默取错 → 改为按 id+插槽名取)、 `findByClass` 的第三个文字参数被静默忽略(现在真的参与匹配)、把 CSS `content` 生成的 "★推荐"当文本断言(改为断言 `data-rec` 属性)。 ## 测试 - `test/advisor.mjs` —— Host 引擎 10 组契约(模式推断 / 输入结构 / 宽松 JSON / 裁剪 / 树渲染 / 审查 / 快照 / 提示词约束) - `test/smoke.mjs` —— 客户端场景 9 覆盖参谋全链路: `/advisor` → 渲染意图·矛盾·事实推断未知·方向·推荐依据·树徽标 → 选方向 → `/review` → `/enhance` 导出 → 采纳写回输入框 → 面板关闭; 含 `data-rec`(推荐星标)与 `data-dead`(已否决节点降级)两个属性级契约。 ## 仍未做 - **真机浏览器验证**:在隔离宿主上跑无头浏览器,确认两个按钮同时出现在真实 GUI 里。 已知障碍:该路径缺少 GUI 会话 token(`/` 与 `/api/*` 都要求鉴权)。 - 参谋状态持久化(当前是进程内 `AdvisorStateStore`,重启即失效)。 - 把 `kimi-k3` 这类超时也纳入"失败即弹模型选择框"的第三类。 ## 与 v0.2 的关系 - v0.2 的 `/enhance`(改写 + 待定点 + 方向选项)**保留**,作为 v0.3 的"出口"。 - v0.3 新增 `/advisor`(局势模型)与 `/review`(审查)。 - 两者共用 `streamOnce`(正文/思维链/finish 分流统计)与 `buildUserMessage`。