@ckanner/flywheel 0.31.0 → 0.31.1

package/docs/{configuration.md → zh-CN/configuration.md}

@@ -1,10 +1,20 @@
-# 模型 profiles、阶段绑定与预检
+# 配置指南
 
-[English](en/configuration.md) · 简体中文
+[文档首页](../README.zh-CN.md) · [English](../en/configuration.md) · 简体中文
 
-Flywheel 在启动时加载一份完整配置，再把模型 profile 展开成每个阶段的实际绑定。模型选择是显式配置，不由另一个模型替你决定；修改配置后需要重新启动引擎。
+Flywheel 启动时选择一份完整配置，展开模型 profiles，再解析阶段绑定。模型分配、
+工作流选择、权限、调度和会话历史是独立策略。安装保留已有文件，修改配置后需重启引擎。
 
-## 1. 配置来源
+编辑前先用 `config inspect` 查明生效文件。下文只展示部分字段的示例是需要并入完整
+配置的**片段**。
+
+- [配置来源](#配置来源)与[完整模板](#从完整模板开始)
+- [模型字段](#字段与身份)与[订阅预设迁移](#将已有配置迁移到订阅预设)
+- [权限](#完全权限与无需逐步确认)与[调度](#调度与-worktree)
+- [会话历史](#会话策略历史复用与调用安全)与[工作流策略](#工作流策略与恢复)
+- [后端接入](#codex-pro-与旧配置迁移)、[预算](#后备渠道与预算)和[预检](#无推理诊断)
+
+## 配置来源
 
 发现顺序为任务目录、项目 Git 根目录、全局文件、内嵌默认表，选择第一个存在的完整文件。全局默认路径为 `~/.config/flywheel/flywheel.config.json`；`FLYWHEEL_CONFIG` 可覆盖全局文件路径，但不能越过已经存在的任务／项目配置。当前不通过 `XDG_CONFIG_HOME` 改变该默认路径。
 
@@ -18,11 +28,117 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/task --json
 
 展示值包含 Flywheel 已确定的 driver 默认：DSH／Codex／Kimi 的空 thinking 为 high，pi／omp／zcode 为 max；Kimi／Codex／Zcode 的空 model 使用各自 driver 常量。pi／omp 未指定模型时仍留空，表示 Flywheel 不能从配置确定它。`residentSession` 只有 Plan＋Kimi＋明确启用时为 true，不把其他阶段忽略的请求显示为已生效。
 
-### 将旧配置切换到已有的三种资源
+### 在控制台编辑配置
+
+DSH 的「全局 / 项目配置」先读取显式作用域和文件 revision，再编辑模型绑定、角色会话策略、预算、超时、重试或全局权限。在表单旁审阅改动并保存。目标文件被其他编辑器修改时拒绝覆盖，保存结果未确认时先重新读取核对。新项目文件以当前版本默认模板创建完整配置，项目文件优先于全局，任务文件优先于项目，不按字段合并。
+
+高级调用通过 stdin 传入 JSON。读取示例使用 `flywheel control config-edit --cwd /absolute/repo`，输入为 `{"scope":"project"}`。保存使用 `control config-save`，输入包含 scope、读取返回的 revision，以及仅包含改动章节的 values。reset=true 从内嵌默认完整模板开始替换。配置保存创建备份并原子发布，下一次引擎启动时加载。
+
+## 字段与身份
+
+| 字段 | 含义 | 示例 |
+|---|---|---|
+| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex-pro`、`claude-code-pro`；`codex` 为显式旧 CLI 路径 |
+| `provider` | DSH SDK 已注册的 LLM adapter ID；仅 DSH 使用 | `deepseek-account`、`chatgpt` |
+| `channel` | 配置中的凭证／后备／计量渠道名称 | `deepseek-account-sdk`、`chatgpt-sdk`、`kimi-subscription` |
+| `model` | 传给后端的精确模型标识 | `deepseek-flash`、`kimi-code/k3.1-pro`、`gpt-6.1-sol` |
+| `thinking` | 请求的推理等级 | `high` |
+| `profile` | 当前 Flywheel 配置内的一组模型字段引用 | `flash`、`gpt-review`、`kimi` |
+
+Flywheel 的 model profile 与 DSH 的 `sdk`／`desktop` profile 是两件事。前者复用模型定义，后者决定宿主实际加载的插件和授权配置。channel 别名本身不会切换 DSH 账号；给同一个 provider 起两个 channel 名称不等于拥有两份独立订阅或额度。
+
+DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider` → 旧 `channel` 名解析。前两者都明确配置而不相等时拒绝加载。兼容旧内联配置的最后一项只适用于 DSH；Codex Pro／旧 Codex CLI 和 Kimi 使用自己的登录状态，不接受一个会被静默忽略的 provider。
+
+### DeepSeek 账号与 API Key 是两个 provider
+
+| 方式 | Provider | 凭证来源 | 选择方式 |
+|---|---|---|---|
+| DSH 已登录、已充值的 DeepSeek 账号 | `deepseek-account` | DSH 的 `deepseekAccount` 服务 | 当前源码默认；不要求 `DEEPSEEK_API_KEY` |
+| DeepSeek API Key | `deepseek-official` | DSH credentials／启动环境中的 API key，默认引用 `DEEPSEEK_API_KEY` | 仅在用户明确选择 API 路径时配置 |
+
+标准 SDK profile 叠加的 [base](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/bundle/base/cordis.patch.yml) 包含账号服务和这两种 adapter。标准桌面与 SDK 使用同一 `DSH_HOME` 时，默认共享该 home 下的[账号授权存储](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/credentials/credentials-local/src/index.ts)；profile 隔离插件配置，不要求把 token 复制到 `sdk` 或改用 `desktop` profile。自定义 home、凭证存储或 SDK 插件集时，须核对它们指向同一授权来源。这里不读取或展示凭证值。
+
+DSH 桌面在登录后且没有任何 provider API key 时，可以自动选择账号目录里的第一个模型。该桌面默认不决定独立 SDK 会话的 provider/model，且“第一个模型”不保证是 Flash。Flywheel 因此明确传入 `deepseek-account`／`deepseek-flash`；账号未登录、授权失效或额度不足时保留失败。默认预设没有 API Key 后备；用户显式配置的后备链仍按既有规则处理。已核对的[官方账号 adapter](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek-account/src/index.ts)、[API adapter](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek-api-key/src/index.ts)及[默认选择逻辑](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/api/session-controller/src/index.ts)是这一边界的依据。
+
+需要继续用 API Key 的自定义配置仍受支持：在完整配置的相关绑定及其 channel 中一致选择 `deepseek-official`，按 DSH API provider 的正常方式配置凭证。不要仅改 channel 名却保留冲突的显式 provider；也不必为账号路径额外添加 API key。
+
+## 从完整模板开始
+
+查看默认内联表或可复用 profiles 表：
+
+```sh
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+```
+
+确认目标没有需要保留的配置后，选择其中一份导出到项目根。已有配置先备份并审阅差异，避免 shell 重定向覆盖它。可以使用 Bash 的 noclobber 避免覆盖已有普通文件：
+
+```sh
+(set -C; flywheel template flywheel.profiles.example.json > flywheel.config.json)
+```
+
+不要只写几个 profiles 后期待继承另一个文件的内容。下面只是解释结构的片段；完整可用起点在第二份模板中：
+
+```json
+{
+  "profiles": {
+    "flash": {
+      "harness": "dsh",
+      "provider": "deepseek-account",
+      "channel": "deepseek-account-sdk",
+      "model": "deepseek-flash",
+      "thinking": "high"
+    },
+    "gpt": {
+      "harness": "dsh",
+      "provider": "chatgpt",
+      "channel": "chatgpt-sdk",
+      "model": "gpt-6.1-sol",
+      "thinking": "high"
+    }
+  },
+  "loops": {
+    "review": { "profile": "gpt" },
+    "judge": { "profile": "gpt", "model": "gpt-6-astra" },
+    "intake": { "profile": "flash", "thinking": "low" }
+  },
+  "routes": {
+    "default": { "profile": "flash" }
+  },
+  "channels": {
+    "deepseek-account-sdk": { "harness": "dsh", "provider": "deepseek-account", "env-key": null },
+    "chatgpt-sdk": { "harness": "dsh", "provider": "chatgpt", "env-key": null }
+  }
+}
+```
+
+这些模型名沿用本仓库的初始绑定，能否使用仍由实际账号和 adapter 决定。读取配置、看到模型名称、adapter 接受参数都不等于账号已获授权。DeepSeek 默认仅 Flash；profiles 不引入自动跨渠道付费回退。
+
+### 覆盖与错误规则
 
-当前源码的 `subscriptions` 预设只使用 ChatGPT 订阅、Kimi Code 订阅和 DSH 已登录并充值的 DeepSeek 账号（仅 Flash，`provider:deepseek-account`）。普通安装／升级仍保留已有配置；所以旧文件里的 Z.AI／GLM、Kimi K3、API provider 和旧 thinking 不会因升级 UI 自动消失。
+| 情况 | 行为 |
+|---|---|
+| 阶段省略某字段 | 继承所引用 profile 的字段 |
+| 阶段显式写 `model`／`channel`／`thinking` 等 | 只覆盖该阶段，不修改共享 profile 或其他阶段 |
+| `thinking: ""` | 使用对应 harness 的现有默认 effort，不重新继承 profile |
+| Plan `resident-session: false` | 明确关闭 Plan 历史复用；加载、profile 展开和配置导出均保留其显式存在 |
+| `judge-panel: null` | 关闭第二意见，保持默认行为 |
+| profile 定义缺 `harness/model/channel`，或这些字段为空／null／纯空白 | 加载失败 |
+| profile 不存在、未知字段、错拼阶段名、不支持的 harness | 加载失败，不静默回落 |
+| profile 再引用另一个 profile | 不支持继承链；加载失败 |
+| `_note`、`_note_*` | 允许配置对象中的说明文字，不进入执行绑定 |
 
-**发行边界：**迁移命令与 `permissions.mode` 已在 0.28.2 发行，但该版内嵌预设仍选择 `deepseek-official` API Key。账号默认修复从 0.28.3 开始提供。安装前核对 registry 版本。先通过 `flywheel template flywheel.config.example.json` 核对所用二进制包含 `deepseek-account`，再用下面的迁移命令；在旧 0.28.2 上重跑迁移不会得到账号默认。
+`resident-session` 是既有阶段选项，不能放进 profile。它继续控制旧 Kimi Plan 行为，
+其显式 false 在 scoped 下也保持 Plan 退出；其他角色的历史复用由顶层 `sessions`
+控制。恢复的是历史，不是要求一个模型进程永久存活。
+
+旧内联绑定保留原有缺省行为，不强制迁移。`env-key: null`、`retry.jitter: 0`、`worktree.enabled: false` 等已有合法零值继续支持。显式切换 harness 或 channel 时，要一起核对继承的 provider；必要时用 `provider: ""` 清除显式值，再按新 channel 解析，不能保留另一个 adapter 的 ID。
+
+## 将已有配置迁移到订阅预设
+
+当前的 `subscriptions` 预设只使用 ChatGPT 订阅、Kimi Code 订阅和 DSH 已登录并充值的 DeepSeek 账号（仅 Flash，`provider:deepseek-account`）。普通安装／升级仍保留已有配置；所以旧文件里的 Z.AI／GLM、Kimi K3、API provider 和旧 thinking 不会因升级 UI 自动消失。
+
+先用已安装的二进制执行 `flywheel template flywheel.config.example.json`，确认它实际包含所需预设。当前预设选择 `deepseek-account`；旧二进制可能仍包含旧默认值。版本变化见[变更日志](../../CHANGELOG.md)。
 
 在实际项目目录运行以下命令；若任务目录有单独配置，再加 `--task-dir /repo/docs/my-task`：
 
@@ -34,25 +150,88 @@ flywheel config inspect --cwd /repo --json
 
 第一条只预览。`--apply` 明确应用到当前实际命中的任务／项目／全局文件，并先备份原始字节。没有文件时写全局配置，不创建意外的项目覆盖。可以用 `--expect-sha256` 绑定之前预览的摘要；文件已经变化时拒绝陈旧应用。预算、worktree、验证、重试、价格和用户说明等非模型设置保留，Plan 明确设置的 `resident-session:false` 以及现有 `sessions` 策略或其缺省状态也保留；模型迁移不会让旧文件自动启用 scoped。配置损坏、额外自定义路由／阶段或不支持的文件身份会明确阻断，不猜测替代。
 
-迁移写入完整的阶段模型、thinking 和渠道，去掉被替换绑定的旧 profile 引用，清除所选渠道的旧 fallback／模型映射，使旧付费渠道不再自动可达；未引用的自定义 profiles／channels 仍保留。包括 0.28.2 留下的 API channel，也可以作为未引用配置保留，但不会成为账号路由的自动后备。默认关闭第二意见，并明确报告旧多模态路由被停用。默认分配仍是 Kimi K3.1 Pro high 负责 Plan／frontend／Garden，DeepSeek Flash high 负责普通执行、low 负责 Intake，GPT-6.1 Sol high 负责 hard／Review，GPT-6 Astra high 负责 Judge。hard 通过 Codex Pro 插件，Review／Judge 通过 DSH ChatGPT provider。Kimi 缺省模型为 `kimi-code/k3.1-pro`；显式写入的自选模型不会被仅修改 driver 缺省值覆盖。档位依据与尚未完成的对照评估见[推理等级与账号选择](model-policy.md)。
+迁移写入完整的阶段模型、thinking 和渠道，去掉被替换绑定的旧 profile 引用，清除所选渠道的旧 fallback／模型映射，使旧付费渠道不再自动可达；未引用的自定义 profiles／channels 仍保留。包括旧版留下的 API channel，也可以作为未引用配置保留，但不会成为账号路由的自动后备。默认关闭第二意见，并明确报告旧多模态路由被停用。默认分配仍是 Kimi K3.1 Pro high 负责 Plan／frontend／Garden，DeepSeek Flash high 负责普通执行、low 负责 Intake，GPT-6.1 Sol high 负责 hard／Review，GPT-6 Astra high 负责 Judge。hard 通过 Codex Pro 插件，Review／Judge 通过 DSH ChatGPT provider。Kimi 缺省模型为 `kimi-code/k3.1-pro`；显式写入的自选模型不会被仅修改 driver 缺省值覆盖。档位依据与尚未完成的对照评估见[推理等级与账号选择](model-policy.md)。
 
 迁移不登录账号，也不发模型请求。当前运行中的任务继续使用启动时已加载的配置；新配置在下一次启动生效。检查迁移后的 source／scope／bindings，再按需要停止和恢复任务。
 
 迁移期间不要同时编辑目标文件。迁移锁协调 Flywheel 迁移进程；写入前再次检查文件，再原子替换完整文件，不提供对任意外部编辑器的原子 CAS。报告以 `configurationStatus` 区分拟议配置 `proposed`、重读确认的实际配置 `effective` 和写入后尚未确认的 `unconfirmed`；备份／写入失败不能把新模型显示成已生效。
 
-### 完全权限与无需逐步确认
+## 完全权限与无需逐步确认
 
 ```json
 {"permissions":{"mode":"full-access"}}
 ```
 
-新安装模板和显式 `subscriptions` 迁移都写入这一设置。全部阶段使用完全权限：DSH／Codex 请求 `danger-full-access` 与 `approval=never`，Codex Pro 通过其公开 machine API 映射，Kimi print 沿用原生 auto。它表示这些 worker 可以访问当前操作系统用户本来能够访问的文件和命令，并不从 DSH 对话框的权限下拉菜单继承。
+新安装模板和显式 `subscriptions` 迁移都写入这一全局设置；已有逐绑定覆盖仍优先。未覆盖阶段使用完全权限：DSH／Codex 请求 `danger-full-access` 与 `approval=never`，Codex Pro 通过其公开 machine API 映射，Kimi print 沿用原生 auto。它表示这些 worker 可以访问当前操作系统用户本来能够访问的文件和命令，并不从 DSH 对话框的权限下拉菜单继承。
 
 旧文件没有 `permissions` 时保持 `role-based`：Plan／Execute 为项目内写入，Review／Judge 为只读。两种策略都不等待交互审批；只读／项目限制下的 `never` 可能直接拒绝动作，不能把它等同于完全权限。`permissions.mode` 的拼写、类型和枚举都会在启动前校验。
 
 完全权限不会关闭 Flywheel 的任务边界、冻结验收、验证和候选身份检查。评审职责仍是评价已有候选，修改候选或验收条件不能取得有效通过。需要受限权限时显式使用 `role-based`；工作区隔离本身不是 OS 沙箱。
 
-### 会话策略、历史复用与调用安全
+### 逐绑定权限覆盖
+
+`permissions.bindings` 按 `loops.<role>`、`routes.<route>` 或 `judge-panel` 覆盖
+全局策略，值为 `read-only`、`workspace-write` 或 `danger-full-access`；未覆盖绑定
+沿用全局设置。例如：
+
+```json
+{
+  "permissions": {
+    "mode": "full-access",
+    "bindings": {"loops.review": "read-only"}
+  }
+}
+```
+
+字段以[权限 schema](https://github.com/ckanner/flywheel/blob/main/templates/permission-policy.schema.json)为准。各后端必须
+支持选定能力；Claude Code Pro 要求完全权限，原生审批设置不提供 OS 只读沙箱。
+实际权限变化也会改变会话复用资格。
+
+## 调度与 Worktree
+
+新安装默认配置选择并行调度，最大并发为 2。已有完整配置没有 `scheduler` 时归一为
+**serial**，显式 serial 也保持不变。安装新版不会替换这些配置。
+[调度 schema](https://github.com/ckanner/flywheel/blob/main/templates/scheduler-policy.schema.json)将总并发与各渠道并发限制在 1–8。
+
+```json
+{
+  "scheduler": {
+    "mode": "parallel",
+    "max-parallel": 2,
+    "providers": {"deepseek-account": 1}
+  },
+  "worktree": {"enabled": true}
+}
+```
+
+虽然字段名为 `providers`，其键仍是**实际配置渠道名**，并非 DSH provider ID。
+内联模板使用 `deepseek-account`；如果绑定的 channel 是 `deepseek-account-sdk`，
+就应使用后者作为限制键。
+
+并行资格来自 packet 的冻结声明：
+
+```yaml
+schedule:
+  after: [M01-T01]
+  writes: [src/search/, tests/search/]
+```
+
+依赖须指向较早的已知 packet。写入范围是规范的相对路径或目录前缀，不支持通配符
+或越界。只有就绪且写入范围互不重叠的 packet 有并行资格；缺失声明、范围冲突或使用
+live 凭证的单元仍串行。hard 预算在前一调用持久化计量前只接纳一个模型调用。
+Review、集成与终验保持串行。
+
+`worktree.enabled` 默认 true，只控制 packet 目录的自动管理，与调度独立。并行且
+自动管理时要求独立 worktree，创建失败就停止；旧串行路径可记录原地执行回退。
+关闭自动管理后，执行者可共享任务 checkout，或在实现前登记合格的外部 worktree。
+共享批次等待 worker 收尾后验证完整共同候选，全部成员通过才可交付；外部 worktree
+会被保留。
+
+项目工作区归属与实际执行位置分别记录。原生后端无法独立设置 `workspace-write`
+沙箱根时，会在派发前拒绝不支持的目录分离组合，不扩大权限。登记与批次规则见
+[控制台指南](flow-console.md#串行与并行)。
+
+## 会话策略、历史复用与调用安全
 
 ```json
 {"sessions":{"mode":"scoped","policy-version":1}}
@@ -61,13 +240,13 @@ flywheel config inspect --cwd /repo --json
 新安装的两份配置模板显式选择 `scoped`。已有配置没有 `sessions` 时归一为
 `fresh`／版本 1，升级不会改写原文件。显式声明时两个字段均必填；未知模式、未来版本、
 null、错拼字段和不完整对象在模型启动前拒绝。字段信源为
-[会话策略 schema](../templates/session-policy.schema.json)。
+[会话策略 schema](https://github.com/ckanner/flywheel/blob/main/templates/session-policy.schema.json)。
 
 `sessions.mode` 控制历史复用，不关闭调用安全记录。Codex Pro、Claude Code Pro、DSH 和 Kimi 的主任务
 Plan／Execute／Review／Judge 调用在两种模式下都先记录调用意图，再保存可信终态回执。
 `fresh` 不复用通用的角色历史，保持后端原有的新调用方式，并保留既有 Kimi Plan
 `resident-session` 行为；`scoped` 在身份兼容且终态满足条件时延续同角色历史。
-其他适配器及 mock 仍使用原有调用路径；Intake／Garden 不在本轮角色会话策略内。
+其他适配器及 mock 仍使用原有调用路径；Intake／Garden 不在该角色会话策略内。
 
 | 角色 | 历史作用域与责任 |
 |---|---|
@@ -162,7 +341,86 @@ partial／unknown 用量不补零，也不能单凭缺失用量触发输入阈
 未来字段或不合法值在启动前失败。如何对真实任务进行三策略配对评估、选择阈值以及
 保留未确认结果，见[会话效果评估](session-evaluation.md)。
 
-### 工作流策略与恢复
+### 可信的执行者增量上下文
+
+可选 `sessions.context` 省略或为 `"full"` 时保留完整提示词；显式
+`"verified-incremental"` 开启仅针对 Execute 的优化。首轮与重建完整提供权威
+上下文；后续同角色续用只有在 Go 复核已消费终态回执、精确绑定、提示词版本、
+契约及全部 context/cache 文件内容摘要后，才可省略稳定契约。引用必须在当前
+执行目录内可读、为普通文件，每个文件最多 1 MiB。增量包含当前反馈、前后候选
+身份、尝试次数和权威引用。
+
+文件缺失或修订、契约变化、旧任务缺少检查点、上下文回执校验失败，均回到完整
+输入。模型、effort、权限或显式会话模式变化会重建历史。Plan、Review、Judge
+保持完整输入，Reviewer 每次仍检查完整当前候选与全部适用需求。
+`state.sessions.records[*].context` 保存模式、身份和原因。这是协议能力，不是
+已测得的 token 节省或模型等质量证据。
+
+## 有界执行策略（显式启用）
+
+`execution-policy` 版本 1 独立于 Auto／Quick／Full。省略时保持既有固定路由和
+渠道后备。[schema](https://github.com/ckanner/flywheel/blob/main/templates/execution-policy.schema.json)
+要求完整绑定及明确允许集合。核对账号和权限后，把以下章节加入实际命中的
+**完整配置文件**；不能将其独立放为局部 override 文件：
+
+```json
+{
+  "execution-policy": {
+    "version": 1,
+    "bindings": {
+      "flash-low": {
+        "harness": "dsh", "provider": "deepseek-account",
+        "channel": "deepseek-account", "model": "deepseek-flash",
+        "thinking": "low", "permission": "danger-full-access",
+        "session-mode": "scoped"
+      },
+      "flash-high": {
+        "harness": "dsh", "provider": "deepseek-account",
+        "channel": "deepseek-account", "model": "deepseek-flash",
+        "thinking": "high", "permission": "danger-full-access",
+        "session-mode": "scoped"
+      }
+    },
+    "routes": {
+      "default": {
+        "initial": "flash-low", "allowed": ["flash-low", "flash-high"],
+        "quality-order": ["flash-low", "flash-high"],
+        "after-stalled-attempts": 1, "max-switches": 1
+      }
+    }
+  }
+}
+```
+
+绑定必须完整声明 harness／provider／channel／model／thinking、permission 和
+session-mode，非 DSH 的 provider 写为 `""`。版本 1 支持已有持久调用记录的
+DSH、Kimi、Codex Pro、Claude Code Pro。每个绑定权限必须等于该路由已有授权，
+所以示例假设路由本来就使用 `danger-full-access`；后端仍须验证模型实际可用性
+及公开配置／权限能力。
+
+`quality-order` 是用户声明的实验顺序，不是模型能力排名。只有完整重复 L1
+观测确认候选、检查集合、已记录环境及失败均未变化，Go 才可前进一项。版本 1
+要求 `after-stalled-attempts:1`，在既有空转停止前考虑切换。AUTH、QUOTA、
+传输／协议错误和 unknown 不触发能力升级。原 packet 的 `max-retries` 和任务
+token 预算继续生效；切换不清零失败、不增加尝试、不削减最终门禁或 Review。
+
+可选 `channel-fallbacks` 将一个允许绑定 ID 映射到另一个，目标须匹配显式配置
+的渠道后备链、目标 harness 和路由模型映射。已有渠道链不能越出允许集合。
+每个 packet 的 `max-switches` 同时限制两种切换。Go 在派发前冻结策略身份；
+`state.packets[*].execution-policy.history` 分别保存 `quality-upgrade` 和
+`channel-fallback` 的完整前后绑定、尝试与原因。并行 packet 各自持有记录。
+
+`config inspect --json` 在 `execution-policy` 下展示完整声明，普通绑定表仍是
+配置基线，当前选择由 packet／session 状态记录。Doctor 既有绑定探测不证明每个
+允许的实验绑定均已通过接纳；实际派发仍须通过适配器配置与权限检查。
+
+每次切换均冷启动 Execute，仅改变 effort 也不例外；effort 保留在会话身份中。
+unknown 或未消费调用先对账。恢复时删除或改变冻结策略会被拒绝：恢复原配置，
+或者用新任务运行新实验。会话／适配器回执保留请求值与可得接口接纳事实；无法
+确认的 effective effort、用量和订阅成本保持 unknown。工作流、Review／Judge
+及交付授权仍是独立边界。
+
+## 工作流策略与恢复
 
 工作流决定运行哪些阶段；模型 profiles、loops、routes 和 `permissions.mode` 仍决定
 各阶段使用什么后端与权限。**工作流写在 Spec 的 YAML frontmatter，不写进
@@ -214,42 +472,12 @@ flywheel control status --task-dir /repo/docs/task --cwd /repo
 Quick 复用现有 Execute 与 Review 绑定，不自动改变 thinking、账户、后备渠道或
 全访问设置。全部必需验证仍运行，适用 L2/L3 必须在实际候选中、最终 Review 前完成。
 完整最终 Review 逐项核对需求，正常首次成功只调用 Execute 与最终 Review 两个阶段。
-字段信源为 [Spec schema](../templates/spec.schema.json) 与
-[state schema](../templates/state.schema.json)，运行流程见[工作流指南](workflow.md)。
-
-### 可选 Claude Code Pro
-
-新增 `harness:claude-code-pro` 与未绑定的 `claude-sonnet` profile，可用于任意已配置 loop 或 Execute route。模型、thinking、optional peer 安装、full-access-only 权限及正常续接边界见 [Claude Code Pro 指南](claude-code-pro.md)。`provider` 仍只用于 DSH 原生 adapter；默认阶段分配不变。
-
-## 2. 四个概念各负责什么
-
-| 字段 | 含义 | 示例 |
-|---|---|---|
-| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex-pro`、`claude-code-pro`；`codex` 为显式旧 CLI 路径 |
-| `provider` | DSH SDK 已注册的 LLM adapter ID；仅 DSH 使用 | `deepseek-account`、`chatgpt` |
-| `channel` | 配置中的凭证／后备／计量渠道名称 | `deepseek-account-sdk`、`chatgpt-sdk`、`kimi-subscription` |
-| `profile` | 当前 Flywheel 配置内的一组模型字段引用 | `flash`、`gpt-review`、`kimi` |
+字段信源为 [Spec schema](https://github.com/ckanner/flywheel/blob/main/templates/spec.schema.json) 与
+[state schema](https://github.com/ckanner/flywheel/blob/main/templates/state.schema.json)，运行流程见[工作流指南](workflow.md)。
 
-Flywheel 的 model profile 与 DSH 的 `sdk`／`desktop` profile 是两件事。前者复用模型定义，后者决定宿主实际加载的插件和授权配置。channel 别名本身不会切换 DSH 账号；给同一个 provider 起两个 channel 名称不等于拥有两份独立订阅或额度。
+## Codex Pro 与旧配置迁移
 
-DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider` → 旧 `channel` 名解析。前两者都明确配置而不相等时拒绝加载。兼容旧内联配置的最后一项只适用于 DSH；Codex Pro／旧 Codex CLI 和 Kimi 使用自己的登录状态，不接受一个会被静默忽略的 provider。
-
-### DeepSeek 账号与 API Key 是两个 provider
-
-| 方式 | Provider | 凭证来源 | 选择方式 |
-|---|---|---|---|
-| DSH 已登录、已充值的 DeepSeek 账号 | `deepseek-account` | DSH 的 `deepseekAccount` 服务 | 当前源码默认；不要求 `DEEPSEEK_API_KEY` |
-| DeepSeek API Key | `deepseek-official` | DSH credentials／启动环境中的 API key，默认引用 `DEEPSEEK_API_KEY` | 仅在用户明确选择 API 路径时配置 |
-
-标准 SDK profile 叠加的 [base](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/bundle/base/cordis.patch.yml) 包含账号服务和这两种 adapter。标准桌面与 SDK 使用同一 `DSH_HOME` 时，默认共享该 home 下的[账号授权存储](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/credentials/credentials-local/src/index.ts)；profile 隔离插件配置，不要求把 token 复制到 `sdk` 或改用 `desktop` profile。自定义 home、凭证存储或 SDK 插件集时，须核对它们指向同一授权来源。这里不读取或展示凭证值。
-
-DSH 桌面在登录后且没有任何 provider API key 时，可以自动选择账号目录里的第一个模型。该桌面默认不决定独立 SDK 会话的 provider/model，且“第一个模型”不保证是 Flash。Flywheel 因此明确传入 `deepseek-account`／`deepseek-flash`；账号未登录、授权失效或额度不足时保留失败。默认预设没有 API Key 后备；用户显式配置的后备链仍按既有规则处理。已核对的[官方账号 adapter](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek-account/src/index.ts)、[API adapter](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek-api-key/src/index.ts)及[默认选择逻辑](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/api/session-controller/src/index.ts)是这一边界的依据。
-
-需要继续用 API Key 的自定义配置仍受支持：在完整配置的相关绑定及其 channel 中一致选择 `deepseek-official`，按 DSH API provider 的正常方式配置凭证。不要仅改 channel 名却保留冲突的显式 provider；也不必为账号路径额外添加 API key。
-
-### Codex Pro 默认与旧配置迁移
-
-0.28.0 的内嵌 hard 路由使用插件路径。下面是需放入自己完整配置的绑定片段，不是可替换全部配置的文件：
+内嵌 hard 路由使用插件路径。下面是需放入自己完整配置的绑定片段，不是可替换全部配置的文件：
 
 ```json
 {
@@ -266,8 +494,8 @@ DSH 桌面在登录后且没有任何 provider API key 时，可以自动选择
 
 完整 profiles 模板使用 `profiles.codex-pro`，hard 路由引用它。插件精确消费
 `dsh-subagent-codex-pro@0.9.0` 的公开 `dsh-subagent-codex-pro/machine` API。
-当前候选将已审查源码生成的真实公开包一并打入插件，不能据此推断 0.9.0 已在 registry
-发行。内部仍使用 Codex app-server 和用户已有登录，不需要父模型二次委派；缺包、
+精确依赖由插件 package 和 lockfile 锁定；生命周期开发时使用的源码包见
+[vendor 来源记录](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md)。内部仍使用 Codex app-server 和用户已有登录，不需要父模型二次委派；缺包、
 版本或回执不符会失败，不自动回退 `codex exec`。Claude 另为精确 `0.4.0` optional peer，
 未选择该后端时无需安装。
 
@@ -291,79 +519,52 @@ full-access 核对 `danger-full-access`／`dangerFullAccess`，不将其称为
 
 指标的 `codex-pro-receipt` 保存完整 machine receipt，包含请求、实际配置、thread/turn、进程、清理、usage 和失败事实。effort 的 `accepted: true` 不等于服务器证明了实际推理强度，`effectiveEffort` 保留 null。仅 `usage.status: "complete"` 的本次增量进入已知预算；partial/unknown 原样留在回执并计入未知调用。插件不提供实际美元成本，原始 cost 保持 unknown；Flywheel 只有在用户显式配置 pricing 且 usage 完整时才能另行估算，估算不等于订阅账单。
 
-## 3. 从完整示例开始
+### Worker 环境
 
-查看默认内联表或可复用 profiles 表：
+| 环境变量 | 用途 |
+|---|---|
+| `FLYWHEEL_DSH_WORKER` | 可选 DSH worker 路径；npm 启动器通常解析同版本依赖 |
+| `FLYWHEEL_DSH_BIN` | DSH 命令，默认 PATH 中的 `dsh` |
+| `FLYWHEEL_DSH_PROFILE` | SDK profile，默认 `sdk`，不能为 `desktop` |
+| `DSH_HOME` | DSH 自身解释的配置根目录 |
+| `FLYWHEEL_KIMI_BIN` | Kimi 命令，默认 PATH 中的 `kimi` |
+| `FLYWHEEL_CODEX_PRO_WORKER` | 可选 Codex Pro worker 路径，通常由 npm 解析 |
+| `FLYWHEEL_CODEX_BIN` | 插件使用的 Codex 程序，默认 PATH 中的 `codex` |
+| `CODEX_HOME` | Codex 自身解释的已有配置／登录目录 |
 
-```sh
-flywheel template flywheel.config.example.json
-flywheel template flywheel.profiles.example.json
-```
+这些设置须对启动引擎的进程可见，安装器不复制凭证。GUI 启动器记录安装时的工具
+路径；终端中的临时 export 不会改变已运行的桌面进程。
 
-确认目标没有需要保留的配置后，选择其中一份导出到项目根。已有配置先备份并审阅差异，避免 shell 重定向覆盖它。下面只是解释结构的片段；完整可用起点在第二份模板中：
+### 权限与清理边界
 
-```json
-{
-  "profiles": {
-    "flash": {
-      "harness": "dsh",
-      "provider": "deepseek-account",
-      "channel": "deepseek-account-sdk",
-      "model": "deepseek-flash",
-      "thinking": "high"
-    },
-    "gpt": {
-      "harness": "dsh",
-      "provider": "chatgpt",
-      "channel": "chatgpt-sdk",
-      "model": "gpt-6.1-sol",
-      "thinking": "high"
-    }
-  },
-  "loops": {
-    "review": { "profile": "gpt" },
-    "judge": { "profile": "gpt", "model": "gpt-6-astra" },
-    "intake": { "profile": "flash", "thinking": "low" }
-  },
-  "routes": {
-    "default": { "profile": "flash" }
-  },
-  "channels": {
-    "deepseek-account-sdk": { "harness": "dsh", "provider": "deepseek-account", "env-key": null },
-    "chatgpt-sdk": { "harness": "dsh", "provider": "chatgpt", "env-key": null }
-  }
-}
-```
-
-这些模型名沿用本仓库的初始绑定，能否使用仍由实际账号和 adapter 决定。读取配置、看到模型名称、adapter 接受参数都不等于账号已获授权。DeepSeek 默认仅 Flash；profiles 不引入自动跨渠道付费回退。
+Claude 原生 init 发生在 prompt 之后，不提供 Codex 同等的预派发 `thread-ready`
+保证。Claude 要求显式完全权限；Kimi CLI 同样不提供 OS 沙箱保证。须分别判断实际
+后端能力与生命周期证据。
 
-### 覆盖与错误规则
-
-| 情况 | 行为 |
-|---|---|
-| 阶段省略某字段 | 继承所引用 profile 的字段 |
-| 阶段显式写 `model`／`channel`／`thinking` 等 | 只覆盖该阶段，不修改共享 profile 或其他阶段 |
-| `thinking: ""` | 使用对应 harness 的现有默认 effort，不重新继承 profile |
-| Plan `resident-session: false` | 明确关闭 Plan 历史复用；加载、profile 展开和配置导出均保留其显式存在 |
-| `judge-panel: null` | 关闭第二意见，保持默认行为 |
-| profile 定义缺 `harness/model/channel`，或这些字段为空／null／纯空白 | 加载失败 |
-| profile 不存在、未知字段、错拼阶段名、不支持的 harness | 加载失败，不静默回落 |
-| profile 再引用另一个 profile | 不支持继承链；加载失败 |
-| `_note`、`_note_*` | 允许配置对象中的说明文字，不进入执行绑定 |
+worker 异常退出不能证明插件的独立管理进程已停止。启动后无法确认清理时，引擎记录
+证据并结束运行，不自动重试或换渠道。恢复前核对本任务的 app-server／guardian 进程，
+再由 Go 核对原调用结果，见[中断恢复](session-recovery.md)。
 
-`resident-session` 是既有阶段选项，不能放进 profile。它继续控制旧 Kimi Plan 行为，
-其显式 false 在 scoped 下也保持 Plan 退出；其他角色的历史复用由顶层 `sessions`
-控制。恢复的是历史，不是要求一个模型进程永久存活。
+## 可选 Claude Code Pro
 
-旧内联绑定保留原有缺省行为，不强制迁移。`env-key: null`、`retry.jitter: 0`、`worktree.enabled: false` 等已有合法零值继续支持。显式切换 harness 或 channel 时，要一起核对继承的 provider；必要时用 `provider: ""` 清除显式值，再按新 channel 解析，不能保留另一个 adapter 的 ID。
+新增 `harness:claude-code-pro` 与未绑定的 `claude-sonnet` profile，可用于任意已配置 loop 或 Execute route。模型、thinking、optional peer 安装、full-access-only 权限及正常续接边界见 [Claude Code Pro 指南](claude-code-pro.md)。`provider` 仍只用于 DSH 原生 adapter；默认阶段分配不变。
 
-## 4. 后备渠道与记录
+## 后备渠道与预算
 
 `channels[channel].fallback` 仍是人工配置的有界后备链，只有既有错误分类／重试策略允许时才使用。切换后依据新渠道重新选择 provider 和模型；不会继续沿用原渠道的 provider。后备渠道省略 harness 时继承当前 harness，不回到链起点的后端。
 
 指标分别保存 `harness`、`provider`、`channel`、`model`。provider 来自 driver 可确认的结果，未知时为 null；channel 继续描述配置渠道。usage 和美元成本未报告时保持 unknown，订阅不会被当成已知零成本。profiles 不改变计费规则，也不会绕过 hard budget。
 
-## 5. 预检范围和结果
+默认 token 预算为 soft，每日上限 2,000,000。soft 报告不确定用量，hard 在未知用量使
+预算无法核实时停止。关闭预算强制并不关闭计量，也不把 unknown 变成零。
+
+Codex Pro 只有本次调用完整用量进入已知 token 计量，partial／unknown 保留在回执中。
+插件不提供实际美元账单；显式 pricing 与完整 usage 可产生估算，但不等于订阅费用。
+
+验收命令使用受限环境。项目需要 `GOCACHE`、`GOPATH` 等额外工具变量时，把变量名加入
+`verify.env-allowlist` 并确保引擎环境已有该变量；不要将凭证值写入契约或提交的配置。
+
+## 无推理诊断
 
 ```sh
 flywheel doctor --cwd /repo --json
@@ -404,38 +605,21 @@ lifecycle／recovery 导出、Node >=22.18.0 与 Codex 命令版本；同一 wor
 | `unknown` | 未验证，例如账号授权、额度与真实模型服务能力 |
 | `skipped` | 非必需绑定、mock、重复探测或前置检查失败等 |
 
-任何 probe 都不发送 `session/prompt`、不运行 L1/L2/L3、不写 Flywheel 状态或创建工作树；SDK 初始化可能访问 provider 目录并产生自己的会话／缓存文件。只读指 Flywheel 配置与任务状态，不表示整个宿主文件系统绝对无写入。
+任何 probe 都不发送 `session/prompt`、不运行 L1/L2/L3、不写 Flywheel 状态或创建工作树；SDK 初始化可能访问 provider 目录并使用临时探测会话存储及自己的缓存文件。只读指 Flywheel 配置与任务状态，不表示整个宿主文件系统绝对无写入。
 
 桌面面板、`/flywheel` 和 `flywheel_control` 共用 `control config|doctor`，可省略 taskDir；只有 doctor 支持 `probe:true`。诊断阻断与传输失败分开显示。桌面使用的 PATH／profile／环境可能与终端不同，安装后应在面板里再检查一次。
 
-### 在流程控制台编辑配置
-
-DSH 的「全局 / 项目配置」先读取显式作用域和文件 revision，再编辑模型绑定、角色会话策略、预算、超时、重试或全局权限。保存前显示字段差异。目标文件被其他编辑器修改时拒绝覆盖，保存结果未确认时先重新读取核对。新项目文件以当前版本默认模板创建完整配置，项目文件优先于全局，任务文件优先于项目。
-
-高级调用通过 stdin 传入 JSON。读取示例使用 `flywheel control config-edit --cwd /absolute/repo`，输入为 `{"scope":"project"}`。保存使用 `control config-save`，输入包含 scope、读取返回的 revision，以及仅包含改动章节的 values。reset=true 从内嵌默认完整模板开始替换。配置保存创建备份并原子发布，下一次引擎启动时加载。
-
-### 控制台权限与调度
-
-`permissions.bindings` 在全局 `permissions.mode` 上按 `loops.<role>`、`routes.<route>`、`judge-panel` 覆盖实际宿主权限，值为 `read-only`、`workspace-write` 或 `danger-full-access`。语法以 `permission-policy.schema.json` 为准；后端仍须证明支持该权限，不会把 Claude 原生审批模式伪装成只读沙箱。
-
-`scheduler` 的字段以 `scheduler-policy.schema.json` 为准。新默认允许 parallel（最大并发 2），已有显式 serial 保留；parallel 只并发满足冻结 `schedule.after/writes` 的独立单元，`max-parallel` 控制任务并发，`providers` 按实际账号渠道限流。hard 预算在确认计费前只允许一个模型调用。声明缺失或写入冲突不会被解释为独立。
-
-`worktree.enabled` 默认 true，只控制引擎自动创建／管理 Worktree；关闭不禁止并行，也不禁止用户或模型自行创建。项目归属与实际执行目录分别记录，外部目录登记协议见[流程控制台](flow-console.md)。当前原生后端不能把 `workspace-write` 沙箱根和项目目录独立设置，不支持的分离组合会在派发前失败；不会扩大权限来掩盖问题。
-
-例如把 Review 固定为只读，并允许两个已声明独立的任务并行：
-
-```json
-{
-  "permissions": {
-    "mode": "full-access",
-    "bindings": {"loops.review":"read-only"}
-  },
-  "scheduler": {"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}
-}
-```
+## 可选 JEV 影子评估
 
-这是字段片段，不是可直接替代完整配置的文件。控制台按实际文件读取完整草稿并校验后保存。CLI 运行索引、受管 Session 交互、指标完整性和 PR／Merge 权限边界见[流程控制台](flow-console.md)。
+`jev-shadow.enabled` 默认 false，省略时也关闭。全局／项目编辑器提供开关。任务
+运行期间只捕获本地快照，不在任务关键路径发送 HTTP 请求；后续显式
+`flywheel shadow run` 才执行可选联网评估并单独记账。影子结果不能改变 Quick／Full
+或授权新动作。新的决策采用需独立显式 opt-in 与数据边界，既有影子开关不授予
+该权限。endpoint、版本、凭证、预算与恢复见[JEV 指南](jev-shadow.md)。
 
-## 可选 JEV 影子评估
+## 参考文件
 
-`jev-shadow.enabled` 默认 false，旧配置缺省同样关闭。全局／项目编辑器支持开关；开启只观察新任务，失败不阻断流程，不改变实际 Quick／Full。endpoint、固定响应版本、密钥变量名和时限详见 [JEV 指南](jev-shadow.md)。此功能需要 0.30.1 CLI／插件。
+- [内联默认配置](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.config.example.json)
+- [完整 profiles 示例](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.profiles.example.json)
+- [系统设计](../design.md)
+- [Worker 协议](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md)