@ljwei-stak/dsh-model-route-bot 0.65.0 → 0.66.0

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -0,0 +1,293 @@
+# 模型路由工作台：配置、规划与实际执行
+
+适用版本：`@ljwei-stak/dsh-model-router@0.25.4`。声明兼容 DeepSeek Harness Desktop `0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2 / 0.2.1-rc.3`。源码构建使用固定的 0.2.1-rc.3 SDK；兼容验证与边界见[0.25.1 验收记录](releases/0.25.1-validation.md)。安装与开发见[中文 README](../README.zh.md)，旧包迁移见[迁移说明](archive/MIGRATION.md)。
+
+0.22.0 新增“按算法推荐分配 / 手动调整分配”：生成任务建议后，可为每个工作包选择模型 API 或官方工具；修改后重新预览费用与渠道，再确认执行。任务依赖与重跑目标保留。手动混合执行当前只读，官方工具使用自身默认模型；编辑文件继续选择官方工具协作。详见[手动分配说明](MANUAL_TASK_ASSIGNMENT.zh.md)。Hermes 自定义程序目录、原配置/登录/历史位置，以及工具页顶部终端的行为继续保留。
+
+0.21.0 新增 Hermes Agent 与 Pi 的安装更新、版本检测及交互终端，OpenCode npm/pnpm 切换至官方 V2 包。Hermes 与 Pi 的登录由各自 CLI 完成，暂不提供经过验证的托管执行器。
+
+0.20.0 在工作台增加**官方工具协作**和明确的执行环境选择。默认保留 CLI 自身配置的模型，分别记录推荐、请求和实际回报模型。Windows Claude 单包执行及 Claude → MiniMax 依赖交接、实际文件整合已通过；具体入口、费用和未验证范围见[验收记录](releases/0.20.0-validation.md)。
+
+0.15.0 新增四页布局、规划后直接展示路由建议、执行输入变化时丢弃旧预览，以及历史裁剪和重试后的费用累计保留。源码中的独立 UI 预览使用模拟数据，用于组件检查，不代表真实账号调用或桌面端到端验收。
+
+0.16.0 加入可选动态公开能力/价格快照，以及分任务类型的持续反馈学习。公开数据默认关闭；反馈只调整本地主观效用，不改公共能力评分或质量门槛。本版发布验证见[更新记录](../CHANGELOG.md)，不把模拟数据测试视作真实付费调用或桌面端到端验证。
+
+工作台分成四页：**任务与执行、模型配置、官方工具、预算与安全**。顶部概览显示模型路线、工具检测与今日已记录 API 费用。切换页面保留面板状态；已有安装任务和终端会话不会因切页重新创建。
+
+## 第一次使用
+
+1. 在 Harness 官方**模型**页添加供应商、模型和凭据。
+2. 打开工作台的**模型配置**，点击目录的**刷新**，确认有准确的 `provider/model`。
+3. 到**官方工具**查看体检。安装、可信入口、登录、模型权限是不同状态；可先不安装 CLI，通过已配置的模型 API 执行。
+4. 按需要在**预算与安全**设置路由方案、每日/月度预算与订阅失败策略。
+5. 返回**任务与执行**，先生成本地计划，再决定是否预览、确认真实执行。
+
+目录数量不是可用账号数量。模型目录不会在这里新增模型，也不显示或接收 API Key。
+
+## 模型配置：给路由器可靠资料
+
+在**逐模型价格与能力**选择准确路线，逐条配置后点击**保存此模型**。配置只覆盖已经在官方目录中登记的路线。
+
+| 字段 | 含义与填写规则 |
+| --- | --- |
+| 质量评分 | `0–100` 的自报估值，不是官方排名；没有依据可留空。 |
+| 输入/输出单价 | 两项同时填写，单位 **USD / 百万 token**；未知留空，零表示确实按零价估算。 |
+| 缓存价 | 可选缓存读取/写入单价；应与相应供应商计费口径一致。 |
+| 擅长方向 | 英文小写标签，逗号分隔，例如 `code, reasoning`。 |
+| 官方 CLI 模型名 | 留空保留 CLI 自身配置的模型；仅显式填写厂商 CLI 已验证接受的名称才切换，不自动传 Harness 模型 ID。ZCode 不支持逐次换模型。 |
+| LiveBench 准确模型名称 | 可选的显式基准映射，须确认模型版本与推理档位一致；不自动猜测别名，也不证明实际执行参数。 |
+| 执行方式 | `auto`、`official` 优先适用的官方工具；`api` 只走模型目录 API。 |
+| 计费方式 | 默认 `subscription-first`；也可指定 `api-only` 或 `subscription-only`。 |
+| 订阅来源 | 自动识别，或显式 `cli-login`、`plan-key`、`none`。 |
+| API 回退路线 | 仅套餐 Key 路线可指定，必须是另一个准确、已配置的 `provider/model`。 |
+
+套餐 Key、供应商地址和凭据在 Harness 官方设置中配置。模型档案不接受密钥、任意命令或自定义安装包。保存档案后旧计划失效，需要重新生成。
+
+## 任务与执行：先规划
+
+写清目标、交付物、约束与验收。复合任务按编号分别写，可明确指出依赖；大量背景文字可能被当作需求，过多执行项可能被合并。
+
+```text
+目标：审阅仓库并形成可实施的改进清单。
+1. 梳理主要入口、状态流转与 UI 页面。
+2. 检查宽屏、窄屏和长内容下的布局。
+3. 基于第 1、2 步，设计改动顺序和验收清单。
+4. 独立核查执行、权限和成本提示是否准确。
+验收：每项列出位置、问题、改动建议和检查方法。
+```
+
+| 规划模式 | 行为 |
+| --- | --- |
+| **单任务** | 推荐一条合适路线；不等于已经调用该模型。 |
+| **团队分工** | 对足够复杂的请求拆出带依赖的工作包；简单任务可能仍只有一个包。 |
+| **指定模型** | 为整项任务选择一个准确路线，跳过其他模型比较。 |
+
+**本次估算预算（USD）** 是规划目标：`0` 表示不限制本次估算，`10` 表示 10 美元目标，不是账号扣费上限。
+
+点击**生成路由建议**。建议直接显示在规划卡片之后，不需要先越过模型档案。这一步在本机完成，不读取工作区文件、启动 CLI 或向模型发送任务。
+
+启用动态公共数据后，生成前读取 Host 的当前账本/快照；到达检查间隔时会请求公开源，但不把任务、回答或用户反馈发送给该源。公开源开关关闭时不进行这些远程刷新。
+
+查看推荐路线、复杂度、估算成本、路由方案与执行渠道；团队结果还包括目标、依赖、难度、费用和验收清单。**价格待配置**表示缺少可靠单价；质量约束放宽或图像包无法分配时应先检查资料。**官方 CLI**是计划的渠道提示，不代表该账号一定有调用权限；**模型目录 API**也不代表该路线能进入 CLI 团队执行器。
+
+修改任务、模式、预算、档案、目录或学习/数据设置后重新生成建议。数据或反馈版本变化会使旧建议失效；陈旧异步回包不会替换新的输入。路由算法的实现与假设见 [README](../README.zh.md#路由算法从输入到分配)。
+
+## 在工作台执行：预览后确认
+
+**在工作台执行**沿用任务文本和规划模式，允许选择执行方式、路由方案并填写工作区。
+
+| 执行方式 | 适用范围 |
+| --- | --- |
+| **模型路由（只读）** | 支持单任务、团队分工和指定模型；沿用路由 CLI/API 及订阅失败策略，保持只读。 |
+| **官方工具协作** | 先在上方选择**团队分工**；仅用当前模式已就绪的官方 CLI 顺序执行工作包，不自动回退 API。可选**只读检查**或**编辑文件**。 |
+
+1. 输入已经存在的工作区绝对路径，例如 `F:\projects\demo`；留空沿用上次运行的路径。
+2. 选择执行方式；官方协作还需选择任务权限。点击**预览执行计划**。模型路由沿用 `model_router_execute` 的决策；官方协作与 `model_router_team_execute` 共用团队规划和执行逻辑，按所选权限筛选已配置路线、已安装且就绪的 CLI，因此可能与本地建议不同。
+3. 核对预估费用、每包路线、读写权限和全部确认项。**编辑文件**要求干净 Git 仓库与审批，先在独立工作树执行；全部步骤成功后，原仓库仍干净且基线匹配时才整合源码补丁。Git 忽略产物另行核查；整合失败会保留工作树供检查。
+
+Windows 独立工作树保存在用户私有临时目录中，按原仓库路径分别存储；避免原工程所在盘只有普通修改权限、无法初始化 Harness ACL 的情况。源工程权限不因该操作改变。失败后可从运行记录查看独立路径；系统清理临时目录后可能无法续跑，重要成果应及时审阅和归档。
+
+编辑权限下还需选择**执行环境**。默认 **Harness 受限环境**保留进程沙箱，但 Windows 后端会限制状态写入及部分子进程管道；登录成功不能消除这些限制。**厂商 CLI 正常环境**保留原登录、配置、技能和 MCP，以当前用户权限运行，启动与续跑均须额外确认；工具可访问工作树外当前用户有权访问的资源，Git 工作树只负责改动回收。失败不会自动切换环境。运行记录会标明实际环境。
+
+**只读检查**使用各 CLI 的受限工具集。Claude 此模式禁用 shell、技能和既有 MCP，并忽略用户设置；需要正常工具协作时选择**编辑文件**，在隔离工作树执行。
+4. 明确确认执行后才调用模型/CLI。期间状态变化可能导致宿主拒绝旧确认，需重新审阅。
+5. 在下方**执行记录与子任务**看结果、状态、实际渠道、原始失败原因和费用。实际运行可能计费。
+
+执行期间会显示当前工作包、逐包状态、已处理数量和已耗时。点击**取消执行**后，先显示**正在取消**；后台收到请求后停止当前调用，等待进程或模型流收尾，再保存已完成结果、已报告用量和最终状态。取消不会撤销已经产生的费用；可编辑团队尚未整合时会保留独立工作树，取消后不开始新的整合步骤，已经完成的整合无法通过取消撤回。
+
+状态读取失败时保留当前任务并提示重试，不自动再次启动执行。关闭工作台仅停止界面读取；同一浏览器会话重新打开时可恢复仍在 Host 内存中的任务。Host 重启或任务快照被清理后，界面会提示查看执行记录，不能恢复尚未保存的运行过程。浏览器只保存任务 ID，不保存任务正文、回答或凭据。
+
+修改任务、规划模式、执行方式、任务权限、路由方案或工作区等输入后，正在请求或已经返回的旧预览会被丢弃。重新预览并核对当前请求后才能确认执行。官方协作不代替缺失的 CLI，不支持当前权限的工具也不会进入该模式的计划。
+
+**预览不会启动模型，确认会启动。** 模型 API 将任务文本发给供应商；CLI 可能读取工作区或其他其权限允许的文件。只读不等于所有 CLI 只能读取工作区，先看**预算与安全 → 安全边界**。
+
+工作台不自动控制 Blender、剪辑软件或图像引擎。它可以规划和委派文字/代码任务；真实图片、音频或视频交付仍需相应工具制作和验收。
+
+## 执行记录、失败处理与质量
+
+记录展示分配模型、执行渠道、费用、步骤依赖和错误。任务/回答摘录会本地保存，因此分享日志或截图前先脱敏。
+
+CLI 记录分别保留 Harness 推荐模型、显式请求 CLI 模型和 CLI 回报的实际模型，同时保留可用的入口、沙箱、用量及金额证据。无显式 CLI 映射时使用厂商自身配置；参数中的请求名称不等于实际模型证明。单工具 `cliModel` 可覆盖档案映射；团队 `cliModelsJson` 优先按工作包 ID，其次工具 ID，最后采用档案映射。没有实际回报时请核对厂商运行记录。
+
+- **只读路由/团队失败**：重跑失败步骤及依赖它的未完成步骤；已完成结果作为上下文保留。允许时可改派另一条已配置路线。
+- **可编辑团队失败**：符合条件时在新独立工作树中套用此前改动后续跑；要求原仓库干净且仍在原基线。已经整合或等待人工整合的运行不能任意单步重跑。
+- **单工具调用失败**：重新执行原调用，生成关联的新运行；可编辑模式仍需审批。
+- **订阅普通失败**：默认显示**等待确认**，可选择**改用 API 重试、重试订阅、取消**。API 重试会需要确认，登录问题可先重新登录再重试。
+- **评价**：成功结果上的 👍/👎 是你的明确评价，再点已选按钮可撤回；按准确路线、任务类型和结果完成时间形成衰减、向零收缩的主观偏好效用。默认最大调整 ±0.04，可配置到不超过 ±0.1；不改变客观质量分或公共质量门槛。重跑替换结果后旧评价清除，旧页面上的评价请求会被拒绝，需刷新。
+- **复核**：强模型抽查由预算页的质量回路控制，会产生额外真实调用；复核分不作为人工反馈。通过官方会话的 `model_router_rate` 保存评价需要用户审批，Agent 不能给自己评分；来源标记是审计信息，不是独立的人类身份认证。
+
+保存的任务文本最多 20,000 字符，单个回答最多 4,000 字符；历史不是完整交付文件的替代，重跑可能使用截断后的上下文。
+
+重跑完成后以新的步骤状态、回答和时间为准；已成功的步骤不应继续显示上次失败原因。记录中的只读/可编辑模式对应实际执行权限，不能从“官方 CLI”渠道名称单独推断。
+
+## 官方工具：体检、安装与登录
+
+当前注册表包括 Kimi、Claude、Codex、MiniMax、MiMo、Grok、Gemini、OpenCode、Step Code 和 ZCode。点**重新体检**查看实际安装、版本、入口及账号状态；最新版查询失败时保持未知，不表示已无更新。
+
+版本检测与 CLI 登录状态命令绑定所选安装副本的实际入口。该副本缺失或入口不可用时，不使用 PATH 中另一份同名工具代替；对应登录状态保持未知。已安装、入口就绪、已登录和模型权限仍是四项独立检查。
+
+1. 未安装时可从卡片固定官方来源安装；npm 工具安装厂商 `@latest`。新厂商版本没有自动通过本项目测试。
+2. 安装中可查看日志或取消；取消后重新体检确认状态。
+3. 有更新时可更新；已安装版本比查询结果更高时不会降级。
+4. 已安装但未就绪时点**一键修复**，用同一条固定命令重新安装一遍。
+5. 不再需要时点**一键卸载**。包管理器安装走同一个管理器；脚本安装只移除登记的命令入口，可能保留厂商版本目录。配置、登录信息和历史记录保留。不支持安全卸载的方式会说明原因。
+6. ZCode CLI 与其他工具使用相同的安装、更新、修复和卸载操作；安装方式默认保留 `github-release`（GitHub Release · SHA256），也可在该行下拉框选择 `npm`，需要 Node 24.14.0 或更新的 Node 24。它使用 [Alice-Marx/zcode-cli](https://github.com/Alice-Marx/zcode-cli) 社区独立发行版，不依赖桌面版，也不是 Z.AI 官方发行版。
+7. 按**去登录**提示，在对应 CLI/终端完成厂商授权，然后用小任务验证权限。
+
+### 统一安装设置
+
+卡片顶部**统一安装设置**一次设定所有工具的安装地址，修改后点击**保存安装设置**；保存及命令刷新完成后，下一次安装、更新、修复、卸载使用已保存配置。未保存的输入可以**放弃更改**。插件设置页里有同样的字段。方式保存与命令预览独立于工具体检，体检较慢时也能继续选择方式；命令预览确认前暂不能执行安装操作。
+
+| 设置 | 作用 | 限制 |
+| --- | --- | --- |
+| 统一安装根目录 | npm/pnpm 使用该根；可配置厂商脚本使用各工具子目录 | 必须是绝对路径，不能是磁盘或共享根目录；留空=各厂商默认位置 |
+| npm 源地址 | npm / pnpm 方式的下载源 | 必须 https，可填国内镜像 |
+| 安装脚本源覆盖 | 按工具 ID 指定厂商安装脚本的镜像 | JSON，键是官方工具 ID，值是 https 链接 |
+| 允许 curl / irm 安装脚本 | 是否允许执行厂商安装脚本 | 关闭后只剩 npm / pnpm |
+
+0.18.2 起，以 `D:/AI/tools` 为根时，Step 脚本安装到 `D:/AI/tools/stepcode`，MiniMax 脚本安装到 `D:/AI/tools/minimax-code`，其他可配置脚本同样使用专属子目录。厂商脚本可能替换整个运行资源目录，不能直接交给共享 npm 根。旧共享目录中的文件仅供识别并保留，不用于新脚本更新；可重新安装到独立目录。升级并重启 Host 后再操作 Step。
+
+几个容易踩的点：
+
+- **不同工具对"自定义目录"的支持不一样。** npm 使用 `--prefix`；pnpm 使用自身的全局包目录、命令目录和存储目录参数。阶跃的安装脚本接受 `--install-dir`（Windows 上是 `-InstallDir`），也生效。OpenCode 的官方脚本把路径写死成 `~/.opencode/bin`，**无法**接受自定义目录——如果设置里填了目录，它的行内会明确写出将装到哪里。
+- **脚本方式不是把远程内容直接交给解释器。** 插件会先下载脚本、核对它仍然是该厂商的官方安装脚本，再执行本地副本；HTML 报错页和其他厂商的脚本都会被拒绝执行。镜像可以重新托管同一个脚本，不能替换成别的程序。阶跃的脚本源覆盖还会同时改写它下载二进制与校验和的地址，所以镜像需要提供完整的发布文件。
+- **每行可以单独选安装方式。** 下拉框里列出该工具声明的全部方式；当前系统不支持的方式会写明原因，而不是悄悄换成别的。选中某个工具的方式会保存成该工具的默认，`/tools` 和 Agent 工具也会照此执行。
+- **命令是可见的。** 每行上方显示已保存设置下的命令与实际目录，点击前就能核对。排队任务保留点击时的配置；后续修改设置不会改变已经开始的任务。更新完成后核验所选目录里的版本。
+- **统一目录留空时，任务会确定默认目标。** 普通体检从 PATH 发现所选管理器的包；安装、更新、修复和卸载会先读取 npm 的 prefix 或 pnpm 的全局命令/包目录，将其固定为本次目标。无法安全解析时会提示先保存统一目录。
+
+MiniMax 官方 Windows 脚本的 `<# ... #>` 是 PowerShell 帮助注释。0.18.0 已修复将其当成 HTML 的误判；仍拒绝 HTML 错误页及缺少厂商标记的内容。
+
+### 厂商安装渠道
+
+| 工具 | npm / pnpm | curl（Linux / macOS） | irm（Windows） | 统一目录支持 |
+| --- | --- | --- | --- | --- |
+| Kimi Code | ✓ | bash | PowerShell | 脚本使用根目录/kimi-code/bin |
+| Claude Code | ✓ | bash | PowerShell | 包管理器支持；脚本固定在 ~/.local/bin |
+| Codex | ✓ | sh | PowerShell | 支持；Windows 脚本使用统一目录/codex/bin，避免把共享目录变成目录联接 |
+| MiniMax Code | ✓ | bash | PowerShell | 脚本使用根目录/minimax-code |
+| MiMo Code | ✓ | bash | PowerShell | 包管理器与 Windows 脚本支持；Unix 脚本固定 ~/.mimocode/bin |
+| Grok Build | ✓ | bash | PowerShell | 脚本使用根目录/grok-build |
+| Gemini CLI | ✓ | — | — | 支持 |
+| OpenCode | ✓ | bash | — | 包管理器支持；脚本固定 ~/.opencode/bin |
+| Step Code | — | bash | PowerShell | 脚本使用根目录/stepcode |
+| Hermes Agent | — | bash | PowerShell | 源码放统一根/hermes-agent；配置和数据仍保留原位置 |
+| Pi | npm/pnpm | — | — | `@earendil-works/pi-coding-agent`；Node.js ≥22.19，安装带 `--ignore-scripts` |
+| ZCode CLI | npm：`@ljwei-stak/zcode-cli` | — | — | npm 使用统一 prefix；GitHub Release 使用统一根/zcode-cli，留空 ~/.zcode/runtime |
+
+“—”表示插件未使用相应渠道。ZCode CLI 默认通过 `github-release` 下载固定仓库最新发行包，并核对同一发行版的 SHA-256；启动前检查已安装文件摘要。也可选择 `npm` 安装固定的 `@ljwei-stak/zcode-cli@latest`，使用已保存的 npm 源与 prefix。该 npm 包包含完整 TUI、Web 和 Agent 运行资源，安装时不另行从 GitHub 下载。每个工具的安装方式下拉框保留所有声明方式，并说明本机不适用的原因。MiniMax 官方脚本只接受官方 npm 源或 npmmirror；其他 npm 镜像请选 npm/pnpm 方式。
+
+安装成功只表示所选目录的命令入口和版本已确认，不代表工具支持受限执行。Gemini 使用核验后的 npm/pnpm 包入口无界面执行；OpenCode、Step 当前可安装和在终端中使用，尚不支持受限任务。缺少这类能力不再报安装失败。Kimi、MiMo、Grok 的独立原生脚本安装目前没有插件需要的 npm 文件摘要证明，会显示执行入口未就绪；模型路由可按策略使用 API，官方工具协作则不选用该入口且不自动回退。npm/pnpm 安装保留可核验的执行路径。Windows Codex 脚本使用目录联接，插件不提供通用文件删除卸载；请按官方方式移除原生安装。
+
+### 安装方式的会话与 Agent 等价物
+
+| 工作台操作 | 会话命令 | Agent 工具 |
+| --- | --- | --- |
+| 一键安装 / 更新 | `/tools install <工具id> [安装方式]` | `model_router_tool_install` |
+| 一键修复 | `/tools repair <工具id> [安装方式]` | `model_router_tool_repair` |
+| 一键卸载 | `/tools uninstall <工具id> [安装方式]` | `model_router_tool_uninstall` |
+| 查看可用方式 | `/tools method <工具id>` | `model_router_tools` 的 `installMethods` |
+
+安装目录与下载源只来自你自己的插件设置，不会由客户端或 Agent 传入；任何一条调用都无法把安装指向自定义包名或任意地址。安装和卸载都需要 Harness 审批。
+
+注册表 ID 和托管模式如下：
+
+| 工具 ID | 单工具/团队执行支持 |
+| --- | --- |
+| `claude-code`、`mimo-code`、`grok-build` | 只读，以及经审批的可编辑执行。 |
+| `codex` | Windows 托管只读；暂不支持可编辑执行，也不进入可编辑团队计划。 |
+| `kimi-code`、`minimax-code`、`zcode` | 经审批的可编辑执行。 |
+| `gemini` | 路由无界面适配器，不进入单工具/团队托管执行器。 |
+| `opencode`、`stepcode`、`hermes`、`pi` | 尚未核验受限执行入口；插件负责安装、检测与登录指引，执行请在终端中直接进行。 |
+
+### 交互终端
+
+在**官方工具终端**选择系统终端或已安装的 CLI，填写存在的绝对目录；支持时可选登录方式。启动确认显示命令、目录与权限范围。
+
+终端清单现覆盖全部十二个注册表工具，包含 Hermes Agent、Pi、OpenCode、Step Code 和 独立 ZCode CLI TUI。“刷新”重新检测安装状态；启动沿用已保存的安装方式与目录，选定副本不存在时会提示，不改用 PATH 上的其他副本。
+
+Hermes 安装后运行 `hermes auth`；Pi 启动后输入 `/login`，没有独立的 `pi login` 命令。两者的登录状态显示为未知，插件不读取凭据。Hermes 的 Windows 命令目录默认为 `%LOCALAPPDATA%/hermes/bin`（配置 `HERMES_HOME` 时使用其 `bin` 子目录），POSIX 使用 `~/.local/bin`；未设置统一目录时沿用这些厂商命令目录；设置后，源码安装到统一根/hermes-agent，插件绑定其中的 `.hermes/bin` 入口，不迁移现有配置与历史。卸载 Hermes 源码安装请在终端使用 `hermes uninstall`，桌面/MSIX 版使用系统应用管理。
+
+ZCode CLI 的默认 GitHub Release 方式在统一根目录下使用 `zcode-cli` 子目录，留空使用 `~/.zcode/runtime`；选择 npm 方式时，与其他 npm 工具共用已保存的 npm 源和 prefix。可在工具行选择 `npm`，也可运行 `/tools method zcode npm` 后安装，或直接运行 `npm install --global @ljwei-stak/zcode-cli@latest --registry=https://registry.npmjs.org/`。核验成功后在官方工具终端选择 **ZCode CLI** 启动独立 TUI，或选择登录模式。`zcode login` 登录 Z.AI，`zcode login bigmodel` 登录 Coding Plan；登录、模型和插件由用户自行配置。工具行显示独立 CLI 的发行版版本，更新与修复使用当前选择方式的最新版本。GitHub Release 方式只卸载插件管理的运行目录；npm 方式使用相同包管理器卸载固定包；插件在 `<DSH_HOME>/model-router/zcode-npm/cache` 中准备的已核验运行缓存可能保留。切换方式不会迁移或移除另一份副本，保留配置、登录和会话历史。旧的桌面安装目录设置不再影响 CLI。
+
+如果旧桌面版启动脚本占用 npm 目标目录，插件会先备份识别出的 `zcode`、`zcode.cmd` 和 `zcode.ps1`，并把备份位置写入安装日志；失败时尝试安全恢复。其他同名文件保持原样并报告冲突，不使用 `--force`，保留桌面程序资源、账号配置和会话历史。
+
+终端**不经过 Harness 沙箱**，保留用户登录环境、代理和 API Key 变量；输入的命令可按用户权限修改文件。它与上面的只读路由执行分别处理，不共享“只读”的承诺。
+
+PTY 加载失败时卡片显示**管道模式**：全屏界面、箭头键、尺寸同步可能不可用。最多四个并发会话，无人读取约两分钟或达到六小时上限会结束。切换工作台页面保留会话；关闭整个工作台会终止。完成后点**结束会话**。输入/输出不持久化，只记录工具、目录、时间及退出状态。
+
+## 预算与安全
+
+**API 费用、预算与路由方案**支持省钱优先、均衡、效果优先，以及 API 每日/月度金额预算、超预算动作、订阅普通失败策略和质量回路。API 预算包含已发生费用和其他任务的 API 预占；指定模型跳过路线比较。已确认的订阅通道不占 API 预算，不会仅因 API 预算满或单价缺失而被阻止。
+
+**订阅与 API Key**显示供应商计费方式、订阅来源、状态/恢复时间及 API 回退是否可用。检测到额度用尽或限流后，路由执行可按策略转 API 并记录原因；其他订阅错误默认暂停确认。单工具/团队托管执行不会自动转 API。
+
+**订阅用量**独立显示今日/本月调用次数、厂商已报告的输入/输出/缓存 token，以及未知或不完整用量次数，并按供应商、工具和模型分组。部分已报告字段保留，未报告字段显示“未报告”，不会当零。旧参考美元数据可以保留，但不用于现行订阅金额统计，也无法据此还原缺失 token。
+
+API 按金额核算并计入预算，订阅按用量核对；订阅 token 不是厂商总配额、剩余额度或已用百分比，插件不据此猜测厂商限额。预算/费用是本地估算和核算，不替代账单。订阅回退到 API 前，会按实际 API 路线重估、取得必要确认并原子预占；未通过时不发起 API 请求。混合执行记录同时保留订阅用量收据与 API 费用。
+
+对 API 计费，CLI 有效自报金额优先，包括 `0`。CLI 使用 API Key 时仍走 API 费用核算。只有完整 token 用量与回报实际模型可核对到已配置模型或其显式 CLI 映射时，才按相应单价折算。缺失或不匹配的实际模型、不完整用量都保留未知费用；Harness 推荐模型的价格不能证明该 CLI 实际成本。预览仍可使用推荐路线作规划估算，须与实际核算区分。
+
+裁剪详细历史和替换重试结果时，API 费用和订阅用量分别保留累计，避免超过 200 条详细记录或重跑步骤后漏算/重算。旧版已经丢弃的费用与缺失 token 无法恢复。状态结构 v3 从可读的 v1/v2 状态迁移，保留旧费用和预占；升级前完全退出 Harness（包括托盘和所有 Host），降级前保留状态备份，旧插件无法读取 v3。
+
+### 持续反馈与本地偏好
+
+在**预算与安全 → API 费用、预算与路由方案 → 持续反馈与本地偏好**设置**启用用户反馈学习**、半衰期（默认30天）、收缩强度（默认3）和最大偏好效用调整（默认0.04，允许0–0.1）。较旧结果权重更低，少量评价被收缩到接近零；没有评价不等于失败或满意，执行成功也不自动计为好评。查看有效反馈数、有效权重和策略版本后重新规划。
+
+学习限定在同一个本地 **DSH_HOME 工作室共享**、最近 **200 次运行**，不按账号隔离，也不无限保存学习记忆；未核验实际模型的 CLI 默认结果不会训练推荐模型。启停不删除评价。“从现在重新学习”会先请求确认，再将学习起点移到当前时间；此前结果不再参与调整，但执行历史和费用累计保留。本版不为学习自动探索或增加付费模型调用。
+
+### 动态公共数据
+
+在相邻的**动态公共数据**区域明确启用开关。默认关闭；启用后按**公共快照检查间隔**（默认1440分钟）在打开/刷新账本及执行前检查公开源。LiveBench 默认官方站点；自定义 JSON 镜像必须明确 `scoreScale: 1` 或 `100`，准确模型身份与分值须通过校验，不能用高推理档位成绩冒充其他动作。
+
+**价格快照公开源**可留空。配置时只接受不含认证、查询参数或片段的公开 HTTPS 地址；该数据是按官方文档策展、带来源与时间版本的严格 JSON，不是通用厂商价目表抓取器。当前仅支持准确 `provider/model` 的 USD/百万 token 固定输入/输出及可选缓存价；复杂阶梯、时段或非 token 计费不支持此格式。填写来源链接不代表插件已认证价目内容。人工配置单价优先，缺价仍保持未知。
+
+查看 LiveBench / 价格快照的状态、版本与校验时间；更新失败保留最近有效数据并标记状态，过期数据不能当作最新价格。清空价格源或关闭公开数据开关会停止使用对应动态数据，而不删除可恢复的历史快照。执行记录保存当次实际采用的费率和数据/策略版本，新价格不会回算旧费用。公开源不接收任务和反馈；真实执行仍会发送所选任务给相应模型/CLI。
+
+推导、快照协议与机制实验见[动态数据与持续反馈说明](ROUTING_ADAPTIVE_LEARNING.zh.md)。这些机制实验没有证明实际质量—成本收益，也没有验证所有模型的实际推理档位。
+
+**安全边界**显示各路线可读/写范围与沙箱。模型 API 没有本地进程文件访问；可编辑 CLI 要求 Harness 沙箱和独立 Git 工作树。缺少沙箱时可编辑托管执行被拒绝。交互终端始终在沙箱外运行。
+
+Windows Codex 在 Harness 环境仅支持只读：其原 `CODEX_HOME` 状态仍可更新，内层保持 `--sandbox read-only`。在明确确认的厂商 CLI 正常环境中支持可编辑工作包，使用 Codex 自身 workspace-write 策略。本批真实 Codex 连接未通过，不能以安装或登录状态推断网络调用成功。
+
+## 从官方会话启动任务
+
+在 Harness 选择正确工作区，使用自然语言明确要求调用插件工具。以下 JSON 是核对工具调用详情的示例，不需要粘贴到工作台任务框。
+
+只生成计划：
+
+```json
+{"task":"检查项目架构和 UI，给出分工及验收方法","mode":"team","budgetUsd":10}
+```
+
+对应 `model_router_plan`。真正调用一个 CLI：
+
+```json
+{"tool":"codex","task":"只读检查当前仓库并列出 UI 问题；不要改文件","mode":"read-only"}
+```
+
+对应 `model_router_tool_run`。按当前可执行 CLI 分工：
+
+```json
+{"task":"检查布局、接口和测试，逐包给出可核对的问题清单","mode":"read-only","budgetUsd":10}
+```
+
+对应 `model_router_team_execute`。要编辑文件，改为 `workspace-write`，并使用干净 Git 仓库、可编辑官方会话和宿主审批。团队会按当前已就绪且支持模式的 CLI 重新规划，因此可能与本地建议不同。
+
+其他常用工具为 `model_router_execute`（按路由或明确模型只读执行）、`model_router_consult`（模型 API 意见）、`model_router_health`、`model_router_rerun_step` 与 `model_router_rate`。完整列表见 [README](../README.zh.md#官方会话工具)。
+
+## 常见情况
+
+| 情况 | 处理 |
+| --- | --- |
+| 规划按钮不可用 | 等目录/工具检测完成；在模型配置刷新，必要时先配置官方模型页。 |
+| 找不到建议 | 返回任务与执行页；结果就在规划后方。输入变化后需重新生成。 |
+| 推荐路线不符合预期 | 核对质量、单价、专长、方案和任务描述；目录路线不代表账号权限。 |
+| 预览与旧建议不同 | 当前目录、登录、额度或预算可能已变化，以新预览核对。 |
+| CLI 卡片正常但执行失败 | 看原始错误、登录/模型权限、网络、平台支持、会话工作区及审批。 |
+| 提示后台版本旧 | 完全退出 Harness（包括托盘进程），再启动。 |
+| 终端 TUI 不显示 | 检查 PTY/管道模式；管道只能保证较简单命令行交互。 |
+| 工具名在会话中不可用 | 确认插件启用，重新开始会话；记录宿主/插件版本与脱敏错误。 |
+
+问题反馈请附宿主/插件版本、执行模式、工具状态及脱敏错误，勿提供密钥。源码、安装和资料入口见[中文 README](../README.zh.md)。
+
+执行恢复：预览、进度与取消请求等待超过15秒会终止该次网络等待；进度会重试同一任务，取消未确认可手动重试，任务不会自动重新启动。历史步骤重跑前，API 预算按目标及未成功下游中的 API 部分合计；订阅部分单列预估 token。API 部分超限时先确认再运行，改派按实际计费渠道重估，缺失 API 价格不视为免费。

package/docs/archive/MIGRATION.md

@@ -0,0 +1,53 @@
+# 迁移到独立模型路由与 GAL 插件
+
+从模型路由 **0.12.0** 开始，原合并插件拆成两份，均面向官方 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2**。
+
+| 插件 | 安装输入 | 所属项目 |
+| --- | --- | --- |
+| 模型路由 | `@ljwei-stak/dsh-model-router@0.14.0`（0.12.0 起独立；0.13.0 起改名） | [路由仓库](https://github.com/Alice-Marx/dsh-model-router)；旧包名 `@ljwei-stak/model-router-galgame` 最后版本为 0.13.0（与新包 0.13.0 内容相同），之后不再更新。 |
+| GAL | `@ljwei-stak/dsh-galgame@0.1.0` | [新 GAL 仓库](https://github.com/Alice-Marx/deepseek-harness-galgame)；独立安装与更新。 |
+
+路由 0.12.0 只注册**模型路由**侧边栏入口。剧情引擎、角色美术、音乐、存档与自由模式全部归独立 GAL；两个插件互不依赖。
+
+## 0.13.0 包名变更
+
+0.13.0 起 npm 包名由 `@ljwei-stak/model-router-galgame` 改为 **`@ljwei-stak/dsh-model-router`**。旧包名的最后版本是 0.13.0（`next`；`latest` 仍为 0.4.32），内容与新包 `@ljwei-stak/dsh-model-router@0.13.3` 相同；旧包名之后不再更新，但不会被弃用或删除。已装旧包 0.13.0 的用户功能不缺，但应按下面步骤换到新包名以获得后续更新。
+
+- 插件管理器把两者视为不同的包，不能原地“更新”：先卸载旧包（保留 profile 与应用数据），再添加新包。
+- 不要同时安装：二者使用同一个 profile 条目 id `model-router-galgame` 和相同的 `model_router_*` 工具名。
+- 保留的标识：profile 条目 id、侧边栏面板 id、设置命名空间与 Cordis 插件名仍为 `model-router-galgame`，执行记录仍在 `~/.dsh/model-router/state.json`，因此已保存的路由设置和执行记录继续生效。
+- 改变的标识：npm 包名、`cordis.patch.yml` 中被加载的模块名、插件管理器设置卡识别的包名、宿主 Remote（typert）包键和更新检查查询的包名。
+
+## 从合并版 0.11.x 迁移
+
+1. **升级前备份**：旧 GAL 播放器导出需要保留的进度 JSON，并备份 Harness profile。JSON 保存当前剧情状态，不包含全部槽位、设置、已读记录或音乐；重要手动槽可依次读取后导出。
+2. 在**同一个 Harness profile**安装 `@ljwei-stak/dsh-galgame@0.1.0`。
+3. 在官方插件管理器卸载原包 `@ljwei-stak/model-router-galgame`，再添加 `@ljwei-stak/dsh-model-router@0.14.0`。完成两项安装后再打开剧情，避免并行使用旧合并 GAL 与新 GAL 入口。
+4. 核对只有一个**模型路由**和一个**Gal 模块**入口。打开独立 GAL 检查当前进度、三槽及设置；同 profile 继续使用原 localStorage 键。
+5. 若使用不同 profile 或没有读到进度，在 GAL 选择匹配剧目，再导入保存的 JSON。导入上限 **2 MB**，确认后替换当前剧情进度。
+
+独立 GAL 保留 `model-router:gal-story:v1` 等既有存档命名空间，不因包名改变而主动清理旧数据。旧城迁移篇保留历史基础键，正篇使用其独立剧目键；其他已分出的故事存档字节不清理，但不能在仅有两部核心剧目的新播放器里运行。旧版所有故事的代码与专属素材保存在源代码归档。
+
+两部核心剧目是**《回声之城·正篇》**和**《旧城迁移篇：未写完的约定》**。需要继续扩展正篇时只更新 GAL，路由功能调整只更新路由。只用路由无需安装 GAL。
+
+## 从旧桌面适配迁移到官方 Harness
+
+历史 **0.8.0** 声明 0.1.7-rc.2 依赖，当前官方桌面会拒绝它。历史 **0.10.1** 只接受 0.2.0-rc.1；rc.2 用户应安装上表精确版本，不修改 `app.asar` 或绕过版本检查。
+
+1. 备份原 profile 与需要的故事状态。在官方插件管理器按升级流程替换重复旧实例，不清理应用数据。
+2. 在 Harness 官方**模型**页核对供应商、模型与凭据。旧插件凭据不由本插件迁移或保存。
+3. 打开**模型路由**核对模型目录、档案、建议、官方工具卡和设置。需要 GAL 时再单独安装其插件。
+4. 真实模型意见使用 `model_router_consult`；单 CLI 任务使用 `model_router_tool_run`；依赖工作包使用 `model_router_team_execute`。可编辑执行需要干净 Git 仓库与官方工具审批。
+
+## 功能归属与差异
+
+| 功能 | 独立插件的行为 |
+| --- | --- |
+| 模型配置 | 在宿主官方“模型”页完成，两个插件都不保存 API Key。 |
+| 路由规划 | 路由插件从官方目录与用户档案估算难度、质量、费用和工作包。 |
+| 官方工具 | 路由插件维护七家固定来源安装与执行入口；ZCode 原厂安装器由用户选目录。 |
+| 执行团队 | 路由插件的 CLI 团队执行器按依赖顺序运行；官方 Harness Agent Teams 的成员、消息与生命周期由宿主管理。 |
+| 剧情与自由对话 | 独立 GAL 管理故事、立绘、音乐、设置和存档；自由模式经宿主模型服务调用，可能计费。 |
+| 更新 | 通过官方插件管理器分别安装各自的新版本；路由正式版发布在 npm `latest`（预发布版在 `next`），推荐精确版本。 |
+
+登录、厂商实际模型和账单仍由账号持有人验收。完整步骤与安装后的检查见 [INSTALLATION_GUIDE.zh.md](../INSTALLATION_GUIDE.zh.md)，GAL 播放器教程见[独立仓库](https://github.com/Alice-Marx/deepseek-harness-galgame#readme)。

package/docs/archive/README.md

@@ -0,0 +1,21 @@
+# Archived root notes
+
+These files used to live at the repository root. They are historical reports, work logs, and task instructions. Current usage docs stay beside this folder and in the repository README.
+
+| File | Contents |
+| --- | --- |
+| [MIGRATION.md](MIGRATION.md) | Split of the combined plugin into the independent router and GAL packages. The README still links here. |
+| [COMPREHENSIVE_TEST_INSTRUCTION.md](COMPREHENSIVE_TEST_INSTRUCTION.md) | GAL view test-and-fix instructions. |
+| [EXPERIMENT_PLUGIN_INSTRUCTION.md](EXPERIMENT_PLUGIN_INSTRUCTION.md) | Instructions for the routing-experiment plugin. |
+| [FINAL_REPORT.md](FINAL_REPORT.md) | DeepSeek adaptation completion report. |
+| [MULTIMODAL_ENHANCEMENT_INSTRUCTION.md](MULTIMODAL_ENHANCEMENT_INSTRUCTION.md) | Multimodal enhancement task instructions. |
+| [SUMMARY.md](SUMMARY.md) | Short summary of the DeepSeek adaptation work. |
+| [TASK_COMPLETION_REPORT.md](TASK_COMPLETION_REPORT.md) | ModLens integration and experiment-plugin completion report. |
+| [WORK_LOG_2026-09-01.md](WORK_LOG_2026-09-01.md) | Work log for 2026-09-01. |
+| [RESEARCH_PAPER_FRAMEWORK.md](RESEARCH_PAPER_FRAMEWORK.md) | Research framework for routing-optimization experiments. |
+
+Related documents that were also moved out of the root, but not into this archive:
+
+- Guides: [INSTALLATION_GUIDE.zh.md](../INSTALLATION_GUIDE.zh.md), [QUICK_START.zh.md](../QUICK_START.zh.md)
+- Model and ModLens notes: [MODEL-file/](../../MODEL-file/)
+- Dated project task reports: [PROJECT-TASK-REPORT-file/](../../PROJECT-TASK-REPORT-file/)

package/docs/assets/candidate-pruning.svg

@@ -0,0 +1,80 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1240 660" role="img" aria-labelledby="title description">
+  <title id="title">质量门槛与 Pareto 候选剪枝示意</title>
+  <desc id="description">横轴为估算成本，越左越低；纵轴为质量，越上越高。低于工作包质量门槛的模型先排除，再排除更贵且质量更低的被支配模型。剩余候选继续参加多维评分和组合搜索。所有点均为示意，并非真实模型价格或评测数据。</desc>
+  <defs>
+    <linearGradient id="background" x2="1" y2="1">
+      <stop offset="0" stop-color="#f8fbff"/>
+      <stop offset="1" stop-color="#f0f8f5"/>
+    </linearGradient>
+    <marker id="axis-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M1 1 L9 5 L1 9" fill="none" stroke="#526780" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+    <style>
+      text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; fill: #20344e; }
+      .title { font-size: 32px; font-weight: 730; }
+      .subtitle { font-size: 18px; fill: #5c7088; }
+      .axis { font-size: 19px; fill: #526780; }
+      .label { font-size: 19px; font-weight: 700; }
+      .caption { font-size: 17px; fill: #5b7189; }
+      .step { font-size: 20px; font-weight: 700; }
+    </style>
+  </defs>
+
+  <rect width="1240" height="660" rx="24" fill="url(#background)"/>
+  <text x="43" y="60" class="title">先保证质量，再筛掉明显不划算的候选</text>
+  <text x="43" y="94" class="subtitle">示意图：点位仅用于解释算法，不代表真实模型价格或评测结果</text>
+
+  <rect x="109" y="119" width="758" height="410" rx="15" fill="#fff" stroke="#d9e4ef" stroke-width="2"/>
+  <path d="M143 494 H835" fill="none" stroke="#617791" stroke-width="3" marker-end="url(#axis-arrow)"/>
+  <path d="M143 494 V147" fill="none" stroke="#617791" stroke-width="3" marker-end="url(#axis-arrow)"/>
+  <text x="454" y="525" class="axis">估算成本 → 越右越高</text>
+  <text x="169" y="158" class="axis">质量 ↑</text>
+
+  <path d="M143 370 H833" fill="none" stroke="#df9c41" stroke-width="3" stroke-dasharray="10 7"/>
+  <rect x="605" y="343" width="209" height="27" rx="6" fill="#fff6e8"/>
+  <text x="613" y="363" class="caption" fill="#a76b20">工作包质量门槛</text>
+
+  <path d="M321 320 L512 255 L752 189" fill="none" stroke="#258e77" stroke-width="4" stroke-dasharray="8 7"/>
+  <circle cx="189" cy="436" r="12" fill="#9daabd"/>
+  <text x="205" y="430" class="label">A</text>
+  <text x="205" y="454" class="caption">低于门槛</text>
+
+  <circle cx="321" cy="320" r="13" fill="#239477" stroke="#fff" stroke-width="3"/>
+  <text x="337" y="312" class="label">B</text>
+  <text x="337" y="338" class="caption">低价可用</text>
+
+  <circle cx="512" cy="255" r="13" fill="#239477" stroke="#fff" stroke-width="3"/>
+  <text x="528" y="248" class="label">C</text>
+  <text x="528" y="273" class="caption">中价高质</text>
+
+  <circle cx="638" cy="321" r="12" fill="#9daabd"/>
+  <text x="655" y="313" class="label">D</text>
+  <text x="655" y="338" class="caption">被 C 支配</text>
+  <path d="M623 305 Q573 283 535 269" fill="none" stroke="#95a4b8" stroke-width="2" marker-end="url(#axis-arrow)"/>
+
+  <circle cx="752" cy="189" r="13" fill="#239477" stroke="#fff" stroke-width="3"/>
+  <text x="770" y="182" class="label">E</text>
+  <text x="770" y="208" class="caption">高价高质</text>
+
+  <rect x="901" y="120" width="298" height="409" rx="16" fill="#fff" stroke="#d9e4ef" stroke-width="2"/>
+  <text x="928" y="164" class="step">候选集如何缩小</text>
+  <circle cx="940" cy="207" r="15" fill="#5477cf"/>
+  <text x="940" y="213" text-anchor="middle" font-size="16" font-weight="700" fill="#fff">1</text>
+  <text x="967" y="211" class="label">质量门槛</text>
+  <text x="928" y="242" class="caption">A 的质量不足，先排除。</text>
+
+  <circle cx="940" cy="294" r="15" fill="#5477cf"/>
+  <text x="940" y="300" text-anchor="middle" font-size="16" font-weight="700" fill="#fff">2</text>
+  <text x="967" y="298" class="label">Pareto 剪枝</text>
+  <text x="928" y="329" class="caption">二维示意中，C 更便宜</text>
+  <text x="928" y="355" class="caption">且质量更高，D 被支配。</text>
+
+  <circle cx="940" cy="408" r="15" fill="#5477cf"/>
+  <text x="940" y="414" text-anchor="middle" font-size="16" font-weight="700" fill="#fff">3</text>
+  <text x="967" y="412" class="label">有界组合搜索</text>
+  <text x="928" y="443" class="caption">B、C、E 继续按任务专长、</text>
+  <text x="928" y="469" class="caption">推理、延迟、风险与预算分配。</text>
+
+  <text x="44" y="581" class="subtitle">实际剪枝还比较延迟、专长、推理匹配与风险等维度；图中只画了“质量 × 成本”两个维度。</text>
+  <text x="44" y="614" class="subtitle">未提供可信单价时，不会把该路线显示为零费用，也不会据此承诺节省金额。</text>
+</svg>

package/docs/assets/routing-workflow.svg

@@ -0,0 +1,96 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 835" role="img" aria-labelledby="title description">
+  <title id="title">Model Router Galgame 的任务规划与执行流程</title>
+  <desc id="description">插件读取用户任务、DeepSeek Harness 已配置的模型目录和用户填写的模型画像，在本地识别复杂度、拆分工作包、按质量约束与 Pareto 候选筛选，最后使用有界组合搜索生成建议。官方工具执行需要在会话中另行触发。</desc>
+  <defs>
+    <linearGradient id="background" x2="1" y2="1">
+      <stop offset="0" stop-color="#f5f8ff"/>
+      <stop offset="1" stop-color="#eef6f5"/>
+    </linearGradient>
+    <linearGradient id="plan" x2="1" y2="0">
+      <stop offset="0" stop-color="#e4edff"/>
+      <stop offset="1" stop-color="#e5f4ef"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M1 1 L9 5 L1 9" fill="none" stroke="#6385aa" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+    <style>
+      text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; fill: #1e314d; }
+      .heading { font-size: 35px; font-weight: 730; }
+      .subheading { font-size: 19px; fill: #59718d; }
+      .eyebrow { font-size: 17px; font-weight: 700; fill: #355da7; letter-spacing: 2px; }
+      .card-title { font-size: 24px; font-weight: 700; }
+      .card-copy { font-size: 19px; fill: #53667f; }
+      .small { font-size: 17px; fill: #5a6f86; }
+      .stage-number { font-size: 18px; font-weight: 750; fill: #fff; }
+      .link { fill: none; stroke: #7c9bb9; stroke-width: 3; marker-end: url(#arrow); }
+      .divider { fill: none; stroke: #bdccdc; stroke-width: 2; }
+    </style>
+  </defs>
+
+  <rect width="1440" height="835" rx="24" fill="url(#background)"/>
+  <text x="52" y="66" class="heading">一个任务如何变成可执行工作包</text>
+  <text x="52" y="103" class="subheading">0.9.0 实现路径 · 规划在本地完成 · 执行须在官方会话中显式调用</text>
+
+  <text x="53" y="154" class="eyebrow">输入</text>
+  <rect x="51" y="174" width="425" height="105" rx="17" fill="#fff" stroke="#d7e3ef" stroke-width="2"/>
+  <circle cx="83" cy="210" r="10" fill="#5e7fda"/>
+  <text x="108" y="218" class="card-title">用户任务</text>
+  <text x="83" y="252" class="card-copy">问题描述、显式步骤、建议预算</text>
+
+  <rect x="507" y="174" width="425" height="105" rx="17" fill="#fff" stroke="#d7e3ef" stroke-width="2"/>
+  <circle cx="539" cy="210" r="10" fill="#38a993"/>
+  <text x="564" y="218" class="card-title">官方模型目录</text>
+  <text x="539" y="252" class="card-copy">已配置的 provider / model 路线</text>
+
+  <rect x="963" y="174" width="425" height="105" rx="17" fill="#fff" stroke="#d7e3ef" stroke-width="2"/>
+  <circle cx="995" cy="210" r="10" fill="#e0a047"/>
+  <text x="1020" y="218" class="card-title">用户提供的模型画像</text>
+  <text x="995" y="252" class="card-copy">质量、单价、专长、CLI 模型名</text>
+
+  <path d="M263 279 V303 H720 M720 279 V303 M1176 279 V303 H720 V329" class="divider"/>
+  <text x="52" y="351" class="eyebrow">本地规划</text>
+
+  <rect x="51" y="372" width="313" height="134" rx="17" fill="#fff" stroke="#cdddee" stroke-width="2"/>
+  <circle cx="84" cy="406" r="18" fill="#5477cf"/>
+  <text x="84" y="412" class="stage-number" text-anchor="middle">1</text>
+  <text x="113" y="414" class="card-title">识别难度</text>
+  <text x="77" y="453" class="card-copy">任务类型与复杂度分级</text>
+  <text x="77" y="481" class="small">简单 / 中等 / 复杂</text>
+
+  <path d="M366 439 H390" class="link"/>
+  <rect x="392" y="372" width="313" height="134" rx="17" fill="#fff" stroke="#cdddee" stroke-width="2"/>
+  <circle cx="425" cy="406" r="18" fill="#5477cf"/>
+  <text x="425" y="412" class="stage-number" text-anchor="middle">2</text>
+  <text x="454" y="414" class="card-title">拆分工作包</text>
+  <text x="418" y="453" class="card-copy">目标、难度与依赖关系</text>
+  <text x="418" y="481" class="small">分析 → 执行 → 校验与整合</text>
+
+  <path d="M707 439 H731" class="link"/>
+  <rect x="733" y="372" width="313" height="134" rx="17" fill="#fff" stroke="#cdddee" stroke-width="2"/>
+  <circle cx="766" cy="406" r="18" fill="#5477cf"/>
+  <text x="766" y="412" class="stage-number" text-anchor="middle">3</text>
+  <text x="795" y="414" class="card-title">筛选模型</text>
+  <text x="759" y="453" class="card-copy">质量门槛、任务能力</text>
+  <text x="759" y="481" class="small">Pareto 候选剪枝</text>
+
+  <path d="M1048 439 H1072" class="link"/>
+  <rect x="1074" y="372" width="313" height="134" rx="17" fill="#fff" stroke="#cdddee" stroke-width="2"/>
+  <circle cx="1107" cy="406" r="18" fill="#5477cf"/>
+  <text x="1107" y="412" class="stage-number" text-anchor="middle">4</text>
+  <text x="1136" y="414" class="card-title">全局分配</text>
+  <text x="1100" y="453" class="card-copy">预算与交接代价约束</text>
+  <text x="1100" y="481" class="small">有界组合搜索</text>
+
+  <path d="M1230 506 V528 H720 V548" class="link"/>
+  <rect x="51" y="551" width="1336" height="91" rx="17" fill="url(#plan)" stroke="#8daccd" stroke-width="2"/>
+  <text x="77" y="587" class="card-title">路由计划</text>
+  <text x="77" y="619" class="card-copy">每包推荐模型、推理等级、估算成本、依赖和验收项；缺失单价或质量证据时明确提示</text>
+
+  <path d="M720 642 V680" class="link" stroke-dasharray="8 6"/>
+  <text x="749" y="671" class="small">会话中显式触发</text>
+  <rect x="51" y="685" width="1336" height="88" rx="17" fill="#fff" stroke="#83b9a8" stroke-width="2" stroke-dasharray="8 6"/>
+  <text x="77" y="721" class="card-title">可选：调用官方工具执行</text>
+  <text x="77" y="753" class="card-copy">Host 审批 → 已核验的官方 CLI → 独立 Git 工作区 → 按依赖顺序整合结果</text>
+
+  <text x="53" y="812" class="small">预算只影响规划建议，不是实际扣费上限；实际调用模型需核对厂商记录。</text>
+</svg>