@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/zh-CN/jev.md

@@ -0,0 +1,192 @@
+# JEV 决策
+
+[文档目录](../README.zh-CN.md) · [English](../en/jev.md) · 简体中文
+
+Flywheel 只有一个 JEV 开关：**启用 JEV**（`jev.enabled`），默认关闭。
+开启后，所有已支持的 JEV 决策点自动参与流程，不再分别设置影子、建议、采用或
+分功能开关。
+
+## 配置一次，继续使用原来的入口
+
+桌面进入 **Flywheel → 设置 → JEV**，选择需要的全局或项目范围。打开**启用 JEV**
+以显示连接字段，填写或确认 System One 地址、固定模型版本和密钥环境变量名，
+再点击**保存修改**。开关先修改草稿，保存后才启用；编辑和保存都不测试服务
+连通性。后续任务不为同一设置重复询问。
+
+执行 Flywheel 的进程需要继承该环境变量；配置只保存变量名称，不保存密钥值。
+高级字段限定超时、调用次数、阈值和发送数据类别。
+
+`key-env` 接受 1–120 位 ASCII 字母、数字和下划线，首位须为字母或下划线。
+大写、小写和混合大小写名称均可使用；调查冻结配置与重新读取状态时保留原始拼写。
+
+等价配置片段：
+
+```json
+{
+  "jev": {
+    "enabled": true,
+    "endpoint": "https://your-service.example/v1/systemone",
+    "model": "jev-1.14.0",
+    "key-env": "MEROUTER_API_KEY",
+    "timeout-ms": 5000,
+    "max-calls": 8,
+    "min-applicability": 0.8,
+    "min-choice": 0.6,
+    "allowed-data": ["task-summary", "diagnostic-facts", "source"]
+  }
+}
+```
+
+把示例地址替换为实际服务地址。模型必须固定为 `jev-x.y.z`，并与响应版本匹配。
+分发模板的地址为空、开关关闭；开启但目标配置非法时，配置校验失败。运行时缺少
+凭据则继续原有确定性路径；已形成的决策／请求记录保留实际跳过或失败原因。
+实施任务可能在建立首个运行时决策账本前就不满足前提，不承诺每次前置跳过都有回执。
+
+配置按**任务 → 项目 → 全局 → 内嵌表选择一份完整文件**，不跨文件深合并。项目
+配置中的关闭会覆盖全局开启。通过 `config inspect --cwd <项目> --task-dir <任务>
+--json` 查看实际配置来源；详见[配置参考](configuration.md)。
+
+配置好以后照常使用：
+
+- **Task**：从目标准备并运行已授权的调查或实施。Go 自动解析 JEV 策略，宿主不再手写决策模式。
+- **New**：准备调查契约或实现方案后停下，等待用户要求运行。
+- **Run**：在原目录启动或恢复已准备的调查或实现任务。
+- **Auto、Quick、Full**：仍是实现工作流策略；适用资格、验收和 review 由 Go 执行。
+
+## 一个开关控制哪些路径
+
+| 决策点 | 开启 JEV | 关闭 JEV |
+| --- | --- | --- |
+| 下一项取证动作 | 有不确定性时，在已批准的读取、搜索、目录列举、诊断命令与 HTTP 查询中选择 | 原有确定性顺序 |
+| 重复取证 | 通过绑定实际观察的控制选项，跳过已经取证的假设所对应的冗余动作 | 保留原动作集 |
+| 是否进入报告 | 满足引擎证据前提时，可以提前结束收集 | 按原动作、时间、输出预算结束 |
+| 已确认失败后的下一步 | 在合法的局部修复、反馈检查、重新规划候选中选择 | 原有有界返修与升级规则 |
+| 模型／推理等级选择 | 在已批准的完整执行绑定候选中选择，并记录实际切换 | 原有固定绑定与确定性升级／渠道后备 |
+| 反馈检查优先级 | 优先选择一个已批准的检查补充事实，再继续有界执行 | 原有反馈与验收顺序 |
+| 显式在线评估 | 服从同一总开关、目标和配置边界 | 在创建评估账本或请求前拒绝 |
+| 已有记录的离线回放 | 本地读取和解析，不调用模型 | 仍可查看，不调用模型 |
+
+开启所有已支持的决策点，不等于每个任务都增加一次 JEV 调用。单一合法动作和
+确定性选择直接执行。数据范围不允许、硬预算无法可靠约束单次消耗、次数耗尽、
+适用性不足、服务错误或响应非法时，继续基线路径；已形成的决策／请求记录保留
+实际原因，记录前的前置条件不足不代表会新建跳过回执。Auto 仍按 Go 的契约
+资格选择 Quick／Full；不为每次入口增加一次 JEV 分类请求。
+
+提前结束和跳过动作只决定如何收集证据，不证明根因成立。Go 保存决策、观察和
+动作的具体绑定；分析者仍须提交覆盖全部假设的报告，引用真实观察并说明不确定性。
+没有结论仍是 inconclusive。后续修复须沿用原来的授权范围，完成实现、review 和
+验证流程。详见[调查指南](investigation.md)。
+
+## 失败后的下一步与模型选择
+
+引擎先确认上一轮调用已结束、结果已消费、候选与失败证据可核对，并检查剩余尝试
+次数和预算，再生成候选。JEV 返回具体 action ID；Go 复核身份和当前开关后，原子
+保存选择与效果。现有失败上限、Quick → Full 单向升级、完整验收和独立 Review
+仍然成立；JEV 不能把未知执行结果解释成失败后重新调用。
+
+| 动作 | 实际效果 | 前提 |
+| --- | --- | --- |
+| `repair` | 在原 packet 范围内继续局部修复 | 还有合法的执行尝试与预算 |
+| `feedback-N` | 执行契约 `feedback-checks` 中的一项短反馈检查，把物理结果交给下一轮 | 检查已明确批准并有 `purpose` 用途说明；不能由模型新建或修改命令 |
+| `recheck-N` | 重新执行一项已经失败且结果完整的 L1 检查，取得最新反馈 | 检查来自冻结验收集合，已有失败已确认 |
+| `replan` | 进入现有受限规划／流程升级路径 | 当前任务允许规划，保留范围、修订次数与历史 |
+| `model-N` | 选择允许集合中的具体执行配置 | 已配置 `execution-policy`，完整绑定与切换次数符合规则 |
+
+`N` 是冻结候选集合的索引，不是模型名称或自定义命令。模型候选解析成实际
+绑定 ID、harness、Provider、账号渠道、模型、effort、权限与会话
+策略；没有批准候选时不猜测模型名称，也不增加付费渠道。模型／effort 改变继续
+使用已有冷启动规则，不把执行者会话交给 Reviewer。AUTH／QUOTA 等渠道问题仍走
+对应后备规则，不被当成模型推理能力不足。允许集配置见[配置参考](configuration.md)。
+
+短反馈检查的 `purpose` 是 1–160 字符的非空白用途说明；JEV 候选发送该说明，
+不附加 `cmd`／`script` 文本。说明本身也不要填写密钥、原日志或命令文本。
+没有 `purpose` 的条目仍可供 Executor 参考，但不进入 JEV
+定向选择候选。`purpose` 仅属于 `feedback-checks`，不会扩展验收字段或授权范围。
+
+反馈检查只为下一次行动提供证据。即使某项检查已经通过，最终仍在当前候选上运行
+全部必需验收；不能以这一次选择删除检查。桌面在任务与节点中显示决策请求、采用
+或基线原因、反馈检查和实际效果。`applied` 表示控制决策已经应用，后续修复、
+规划或新模型会话仍以节点记录为准；`completed` 表示该次控制动作已经收尾，
+不代表整个任务已交付。`feedback-completed` 也只是反馈检查收尾。
+`pending` 需要核对请求；`feedback-running`、`feedback-unknown` 需要核对原执行，
+不能自动重放。`feedback-stale` 表示反馈改变了候选或验证输入，流程已阻断。
+`replan-running` 表示重规划尚未收尾，恢复时须核对原 Plan 会话，不能再次派发来
+猜测前一次的结果。
+已采用的模型切换另列实际绑定前后值、尝试次数、原因和时间；不能从 `model-N`
+猜测实际模型，也不能把配置切换当成新会话已经成功运行。
+
+## 数据、预算与恢复
+
+调查创建准备记录时，Go 冻结有效 JEV 目标、数据类别、阈值和调用预算。任务输入中
+旧的 `decision` 模式不能绕过关闭的总开关。启用后的默认数据集合允许任务摘要、
+诊断假设、结构化命令／HTTP 结果，以及已批准文件取证的有界片段；可通过
+`allowed-data` 缩小范围。原命令／HTTP 输出只有明确允许 `logs` 时才附加，否则
+标记原内容缺失并使用结构化事实。数据范围不等同自动脱敏：若其余快照仍包含
+未授权类别，请求整体跳过，不能借摘要绕过原有数据权限。
+
+运行中关闭总开关，会停止后续 JEV 请求及建议采用，包括开关关闭后才返回的结果。
+已经派发的请求仍按原身份核对，保留已知或未知用量，未知请求不重发。结果未知的
+**实际动作**仍阻断执行，不能借切换开关绕过。
+
+创建时关闭的调查准备记录继续基线路径，后续开启不会改写这份准备记录；新准备
+记录才可冻结新开启的策略。
+
+实施阶段在已启用的运行中，首次符合条件的失败处冻结自己的运行时决策策略。
+如果当前进程启动时 JEV 关闭，且尚无运行时决策账本，仅保存开启设置不会立即
+启用该进程；须启动或恢复任务，读取已开启的配置。已有运行时决策账本时，关闭
+再开启仍保留冻结目标、记录和剩余额度，包括调查导入的次数。修改目标或收紧
+权限、限制，使当前配置与冻结策略不再相容时，停止后续可选决策，不偷偷重写策略。
+查看界面中的 JEV 状态和原因，不复制账本、重置预算来重新派发。
+
+`max-calls` 是每项任务的调用上限，包括已派发但结果未知的请求。调查移交实施时，
+已使用的次数计入实施额度；多个 packet、模型切换、重规划和恢复不能重新获得完整
+额度。这个限制不等于 token 或金额上限。配置了硬预算而服务无法强制单次消耗上限
+时，跳过 JEV。请求记录服务实际返回的用量，缺失保持 unknown。
+
+实施阶段的 `runtime-decisions` 位于 `state.json`，记录冻结策略、已用次数、
+调查导入次数和逐项请求／选择／效果，沿用已有 state 提交与交付规则。私有且排除
+自动交付的是 `.investigation/runtime-decisions` 请求 journal；这个排除规则不
+覆盖 `state.json` 中的决策信息副本。
+
+桌面只展示有界摘要，投影移除原始快照和目标配置；这只限制桌面输出，不构成 Git
+交付脱敏。批准的目标、事实、绑定和反馈输出仍与已有失败反馈一样，遵守不记录
+凭据的规则。请求或动作尚未完成时，从原任务恢复核对，不能用新账本或切换模型
+绕过未知结果。
+
+## 离线回放与显式评估
+
+正常任务在私有决策账本中保存冻结的 `*.input.json` 和回执。离线回放也接受历史
+`*.snapshot.json`：
+
+```bash
+flywheel decision replay --input frozen.input.json --response native-response.json \
+  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
+```
+
+离线回放不读取密钥、不发请求、不写账本或任务状态。裸 Snapshot 需要
+`--policy reviewed-policy.json`；显式策略完整替换原策略，不继承省略的数据权限。
+
+需要实际在线评估时，先在相应范围开启 JEV：
+
+```bash
+flywheel decision evaluate --cwd "$repo_dir" --input frozen.input.json \
+  --directory ./decision-evaluation --max-calls 5
+```
+
+目标、固定模型和密钥变量取自同一配置；旧的显式目标参数必须与配置一致。评估
+命令强制只建议，不执行动作、不改任务状态；其次数、超时、阈值和数据范围不能
+放宽配置边界。同一输入和账本只读取原回执，未知请求不会重发。
+
+两种工具都输出 `adopted: false`。在线错误或未知返回退出码 3，输入／配置错误
+为 1，取消为 143。离线 fixture 通过不能证明真实模型成功率或任务加速。
+
+## 从影子功能迁移
+
+旧自动观察器和独立影子请求客户端已经移除。旧 `jev-shadow` 配置仍可读取并迁移
+连接信息，但旧开启值不会自动启用在线决策。明确的新 `jev` 配置优先。编辑器保存
+统一配置并移除旧 key，保留原来的备份和 revision 检查。旧 `shadow` 命令只提示
+迁移方式，不再执行实验；历史记录及其 schema 保留作证据。
+
+评估实际价值时，对比开关关闭与开启的完整任务：获得有效证据的时间、执行／跳过
+动作数、总耗时、实际与未知用量、最终质量。只改变顺序或通过离线 fixture，均不能
+单独证明加速。

package/docs/zh-CN/model-policy.md

@@ -0,0 +1,128 @@
+# 模型、推理等级与账号
+
+[文档目录](../README.zh-CN.md) · [English](../en/model-policy.md) · 简体中文
+
+Flywheel 通过阶段或执行路由的绑定选择模型。[默认模板](https://github.com/ckanner/flywheel/blob/main/templates/flywheel.config.example.json)
+是新配置的依据；已有安装继续使用自己的配置。下面的默认值是可调整的初始基线，
+仓库尚未证明它是代表性任务上的最优组合，也没有证明提高推理等级能改善每次交付。
+
+## 默认绑定
+
+| 阶段或路由 | Harness | 模型 | 访问方式 | 推理等级 |
+|---|---|---|---|---|
+| Plan | `kimi` | `kimi-code/k3.1-pro` | 原生 CLI 使用 Kimi Code 订阅 | `high` |
+| Execute：default | `dsh` | `deepseek-flash` | DSH `deepseek-account` | `high` |
+| Execute：frontend | `kimi` | `kimi-code/k3.1-pro` | 原生 CLI 使用 Kimi Code 订阅 | `high` |
+| Execute：hard | `codex-pro` | `gpt-6.1-sol` | 公开 machine API 使用 Codex 登录 | `high` |
+| Review | `dsh` | `gpt-6.1-sol` | DSH `chatgpt` provider | `high` |
+| Judge | `dsh` | `gpt-6-astra` | DSH `chatgpt` provider | `high` |
+| Intake | `dsh` | `deepseek-flash` | DSH `deepseek-account` | `low` |
+| Garden | `kimi` | `kimi-code/k3.1-pro` | 原生 CLI 使用 Kimi Code 订阅 | `high` |
+
+Harness 负责智能体与工具循环；DSH 的 `provider` 选择原生 LLM 适配器；`channel`
+是配置中的账号或凭证渠道名称。`codex-pro` harness 不是名为 `subagent_codex_pro`
+的 DSH provider。Kimi 使用原生 CLI，不使用 ACP。Auto、Quick、Full 不会自动改变
+这些绑定或提高推理等级；具体配置方式见[配置指南](configuration.md)。
+
+Claude Code Pro 是[可选后端](claude-code-pro.md)，默认未分配任何阶段或路由。
+使用时明确指定原生模型与推理等级，不会隐式替换其他订阅渠道。
+
+## 账号选择
+
+默认配置和 `subscriptions` 预设使用 `deepseek-account` 与 `deepseek-flash`。
+标准 DSH 桌面与 SDK 在同一 DSH home 下可以共享账号授权，无需额外 API key。
+自定义 profile 仍须加载账号服务和适配器。独立 SDK 调用会明确传递 provider/model；
+修改桌面对话模型不会更新 Flywheel 的阶段绑定。
+
+`deepseek-official` 是单独的 API-key provider，需要明确配置。默认预设不会在
+认证失败或额度不足后更换付费渠道；用户自定义后备链继续遵循其配置。
+ChatGPT 与 Kimi 订阅同样需要相应适配器或 CLI，以及其支持的登录流程。
+
+升级会保留已有用户文件。采用订阅预设时，先检查实际生效的完整配置、预览迁移，
+再按[配置指南](configuration.md)显式应用。之后重新启动引擎；安装包或修改桌面
+对话模型都不会迁移运行中的任务。
+
+## 推理等级取决于后端
+
+下表是 **2026-11-05** 对所列集成的能力核对，属于相应快照的兼容性依据，
+不是当前服务端模型目录或账号权限检查。
+
+| 已核对的集成 | 可请求的值 | 说明 |
+|---|---|---|
+| GPT-6.1 Sol／Codex Pro 0.9.0 | `low`、`medium`、`high`、`xhigh`、`max` | machine API 传递指定 effort |
+| Sol、Astra／DSH ChatGPT provider | `low`、`medium`、`high`、`xhigh`、`max` | provider 序列化为 `reasoning.effort` |
+| Kimi K3.1 Pro／原生 CLI | `low`、`high`、`max` | 不能关闭 thinking；兼容别名 `xhigh`、`max`、`ultra` 都映射到原生 `max` |
+| DeepSeek Flash／已核对的 DSH adapter | `off`、`low`、`high`、`max` | 此适配器拒绝 `medium` 和 `xhigh` |
+
+不同 provider 的同名档位不是统一量尺。通用 API 的兼容映射也不能绕过 DSH
+适配器自身的参数校验。在这条路径比较 Flash 的更高档位时使用 `max`，不填
+`xhigh`。后端不支持某项选择时应明确拒绝，不能静默替换模型或推理等级。
+
+兼容性参考：[Kimi 模型文档](https://www.kimi.com/code/docs/en/kimi-code/models)、
+[DeepSeek thinking](https://api-docs.deepseek.com/guides/thinking_mode/)、
+[Sol 模型参考](https://developers.openai.com/api/docs/models/gpt-6.1-sol)、
+[Astra 模型参考](https://developers.openai.com/api/docs/models/gpt-6-astra)、
+[DSH DeepSeek 配置](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/config.ts)
+与[序列化校验](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/llm/llm-deepseek/src/serialize.ts)。
+ChatGPT provider 的核对快照为 0.1.17、`388868f91bcdc05795fb94d21b868ded6d7219c9`：
+[模型目录](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/models/served.ts)
+与[请求序列化](https://github.com/ckanner/dsh-plugin-chatgpt/blob/388868f91bcdc05795fb94d21b868ded6d7219c9/src/convert/request.ts)。
+
+## 选择并评估基线
+
+八个默认阶段／路由中七个使用 `high`，Intake 使用 `low`。稳定的初始设置方便
+把比较结果归因到具体阶段。以下比较方向来自阶段职责的工程判断，**不是已实测的
+Flywheel 质量结论**。
+
+| 阶段 | 可比较的设置 |
+|---|---|
+| Intake | 对有歧义的输入、合并或分类比较 `high` |
+| Plan | 对困难架构、依赖关系或验收设计比较 `max` |
+| Execute：default | 对困难实现或根因分析比较 Flash `max` |
+| Execute：frontend | 对复杂交互状态或跨组件一致性比较 Kimi `max` |
+| Execute：hard | 先比较 Sol `xhigh`，再在最难任务上评估 `max` |
+| Review | 对并发、一致性或权限审查比较 `xhigh` |
+| Judge | 对高影响里程碑终验比较 Astra `xhigh`，有依据时再评估 `max` |
+| Garden | 常规整理比较 `low`，困难跨任务归纳比较 `max` |
+
+在实际生效的完整配置中修改 `thinking`。例如，`routes.hard.thinking` 只影响
+hard 执行，`loops.judge.thinking` 只影响 Judge。阶段覆盖可以避免改变共享 profile
+的所有使用者。不要创建只包含这两个字段的不完整任务配置：配置发现选择一个文件，
+不会跨文件合并。
+
+固定模型、harness、上下文、任务、权限和验收条件，再比较交付成功率、首轮通过、
+漏检与误报、包含返工的总耗时，以及输入／输出／reasoning／缓存用量。可观察的
+订阅额度另记，缺失值保留 unknown。API 单价不能直接换算成订阅可完成任务数。
+[会话评估指南](session-evaluation.md)介绍仓库的配对实验工具；推理等级比较也需要
+明确自己的固定条件。
+
+## 有界模型与 effort 实验
+
+可选[执行策略](configuration.md#有界执行策略显式启用)逐路由声明完整允许绑定，
+包括账号、effort、权限和历史模式。Auto／Quick／Full 不会启用它。确认重复 L1
+空转后，可在原尝试／token 预算及显式切换上限内前进实验顺序；这条确定性规则
+不证明后一个模型更好。渠道错误使用单独声明的后备，两种机制都不能选择未声明
+的模型或费用渠道。
+
+开启唯一 [JEV 总开关](jev.md) 后，确认结束的失败也可把已有允许绑定作为决策
+候选。采用前核对冻结允许集、权限、剩余尝试与切换预算，不再设置 JEV 模型路由
+开关。没有合法备选时继续当前绑定。语义选择只记录为实际选择，不代表已经测得
+该模型更快或更好。
+
+effort 改变会冷启动角色，并记录完整前后绑定。对照必须计入重读、启动及实际
+已知／未知用量与成本。离线测试以受控 driver 结果运行真实引擎返修和恢复路径，
+不能证明实际模型质量或速度；改变默认值或宣称节省前仍须使用配对真实任务与
+冻结 oracle。
+
+## 解释配置证据与质量证据
+
+源码和离线协议测试能够证明字段传递与错误处理。SDK 或 machine API 接受请求，
+能够证明接口接纳。服务端实际采用的 effort 和交付质量提升，则需要后端证据或
+真实任务测量。
+
+DSH `initialize` 校验配置，但回复只包含 server 信息。Flywheel 的
+`ready.reasoningEffort` 是初始化成功后的请求回显，不是模型服务独立证明。
+Codex Pro 区分 `requestedEffort`、`accepted` 和未知的 `effectiveEffort:null`。
+依据见 [DSH SDK server](https://github.com/deepseek-ai/deepseek-harness/blob/b830ec950faba0a46dda564be3e2d854afed94f1/packages/sdk/server/src/server.ts)
+与 [Codex Pro machine 协议](https://github.com/ckanner/dsh-subagent-codex-pro/blob/37da3d75de32b809c4fb1a631ccc15191f3d87f9/docs/machine.md)。
+无推理 doctor 不能证明账号余额、真实调用或更高档位的收益。

package/docs/zh-CN/releasing.md

@@ -0,0 +1,120 @@
+# Flywheel 发行手册
+
+[文档目录](../README.zh-CN.md) · [English](../en/releasing.md) · 简体中文
+
+本文面向维护者，用户安装请看[快速开始](getting-started.md)。源码提交、GitHub Release 或 `npm pack` 成功，都不代表新版本已能从 npm 安装。实际发行结果和验收边界应保存在[验收记录](../validation/README.md)。
+
+## 1. 发行身份与前提
+
+一次发行包含六个精确同版本包，按以下顺序发布：
+
+| 顺序 | 包 | 内容 |
+| --- | --- | --- |
+| 1–4 | `@ckanner/flywheel-{darwin,linux}-{arm64,amd64}` | 四个平台的 Go 二进制 |
+| 5 | `@ckanner/dsh-plugin-flywheel` | 桌面插件和 worker |
+| 6 | `@ckanner/flywheel` | 用户入口 CLI、安装器和文档 |
+
+入口包精确固定其余五包版本。每个 Flywheel 包声明 MIT 并包含 `LICENSE`，插件保留第三方许可声明。Codex Pro 固定为 0.9.0，以[已记录来源的候选](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md)内置分发；Claude Code Pro 0.4.0 保持可选 peer，不是第七个 Flywheel 发行包。
+
+使用与仓库 workflow 一致的 Git、**Go 1.27、Node 24.22.1、npm 12.2.1**。用户安装的 Node 要求更低，发行工具链则固定版本。源码须经过审查、工作区干净、六包版本一致，且精确的 `vX.Y.Z` tag 指向 HEAD。不得移动已有发行 tag，也不得替换已发布版本的字节。
+
+`candidate.json` 保存源码 commit、tree、快照 SHA-256，以及每个 tarball 的 SHA-512 integrity。构建一次后，验证、测试和发布同一批 tarball。带 `source.dirty: true` 的候选只用于开发。
+
+## 2. 验证发行源码
+
+按[贡献指南](contributing.md)和当前 [CI workflow](https://github.com/ckanner/flywheel/blob/main/.github/workflows/ci.yml)执行门禁：
+
+| 范围 | 必须记录的证据 |
+| --- | --- |
+| Go | `make quality-gate` 和 workflow 中核心包的 race 检查 |
+| DSH 插件 | 锁文件依赖安装、构建和行为测试 |
+| 后端边界 | DSH、Codex Pro、Claude Code Pro 离线跨进程测试 |
+| npm | `npm test` 与六包候选的真实安装 |
+| 原生 CLI | 构建、版本／帮助和 JSON 配置检查 |
+| 会话策略 | 使用已构建原生二进制运行 `npm run test:sessions` |
+| 文档 | 链接、双语对应、包内指南和许可证 |
+
+按 workflow 固定的源码 SHA 准备可选 Claude tarball，并检查 SHA-256。插件／桥接测试阶段临时将它安装为开发依赖，随后恢复源码 manifests；候选安装测试前，通过 `export` 将 `FLYWHEEL_CLAUDE_CODE_PRO_TARBALL` 设置为该已核对 tarball 的绝对路径。缺少可选 peer 不代表 Claude 后端验证通过。
+
+这些门禁使用隔离 profile 和离线模型夹具，不证明真实账号、模型质量或实际桌面布局可用。记录真实执行的平台；交叉编译不能代替目标平台运行验收。
+
+## 3. 构建同一批候选
+
+从经过审查、工作区干净且位于发行 tag 的 checkout 执行，每步失败即停止：
+
+```sh
+FLYWHEEL_RELEASE_VERSION=$(node -p "require('./package.json').version")
+FLYWHEEL_RELEASE_SHA=$(git rev-parse HEAD)
+node scripts/release-preflight.js --version "$FLYWHEEL_RELEASE_VERSION" --tag "v$FLYWHEEL_RELEASE_VERSION" --json
+npm run build:npm
+node scripts/release-publish.js verify-candidate --directory dist-npm --source-sha "$FLYWHEEL_RELEASE_SHA"
+FLYWHEEL_NPM_PACKAGES_DIR=dist-npm npm run test:install
+```
+
+运行最后一条命令前，先设置上一节说明的 Claude tarball 环境变量。构建器在隔离源码快照中安装锁定的插件依赖、禁用 lifecycle scripts，再构建 worker 和四个平台 Go 二进制，不复用调用方的 `node_modules` 或 `dist`。无需在仓库根目录先执行 `npm install`。
+
+保存 `dist-npm/`、`candidate.json`、源码身份、工具链版本和验证结果。核对六包 MIT 许可证及根入口、插件的双语文档。尚未上传时源码变化，应从新审查源码重新准备候选；已有任何上传后，保留原候选并按失败恢复规则处理。
+
+## 4. 通过 GitHub Actions 发布
+
+推送经过审查的 tag 会触发 [publish.yml](https://github.com/ckanner/flywheel/blob/main/.github/workflows/publish.yml)，也可在手动运行入口提供一个已有 tag。Linux 和 macOS 验证同一个候选 artifact；发布 job 刷新远端引用，并要求 tag 仍指向已验证源码。
+
+GitHub 访问权和 npm 发布权是两项授权。六个包分别配置 trusted publisher：owner 为 `ckanner`、repository 为 `flywheel`、workflow 为 `publish.yml`；除非 workflow 改为使用 environment，否则该项留空。需要同时允许 **npm publish** 和 **npm dist-tag**。workflow 也支持已授权的 `NPM_TOKEN` 后备路径。
+
+首次新建包需要先完成 npm 的包创建授权，才能配置该包的 trusted publisher。使用正常授权流程，不得以不同占位内容提前占用发行版本。账号设置参考 npm 官方 [trusted publisher](https://docs.npmjs.com/trusted-publishers/) 和 [dist-tag](https://docs.npmjs.com/adding-dist-tags-to-packages/) 文档；`npm whoami` 只能说明登录身份，不能证明发布权限。
+
+发布必须明确仓库实际可见性：`public` 要求 provenance，`private` 关闭不支持的私有源码 provenance。发 npm 包不会改变仓库可见性，OIDC 身份认证与 provenance 也是不同能力。
+
+## 5. 从私有源码本地发布
+
+维护者可从普通 Git checkout 构建。按当前发行政策，公开仓库的新上传必须走第 4 节：发布器要求 provenance，而 npm 只能在支持的云 CI/CD 环境生成它，普通本地浏览器登录不能提供。详见 [npm provenance 前提](https://docs.npmjs.com/generating-provenance-statements/)。下面的本地上传示例仅适用于源码仓库实际为私有的情况，不得把公开仓库声明为私有来绕过要求。无需下载候选压缩包。先完成源码审查和上述门禁。Actions 无法运行时，记录维护者授权、本地真实结果和未执行检查，不能把不可用的 CI 写成通过。
+
+在相同的干净 tag 源码及其原候选目录执行：
+
+```sh
+npm login --auth-type=web --scope=@ckanner --registry=https://registry.npmjs.org/
+npm run release:local -- --repository-visibility private
+```
+
+在终端完成正常浏览器／2FA 提示；发布器要求 TTY，不要将输出通过管道传给 `tee`。
+
+`release:local` 按顺序执行：
+
+1. 核对干净源码、精确本地／远端 tag、tree、snapshot、候选清单和包完整性。
+2. 运行候选安装测试，再次确认源码和候选未变化。
+3. 按平台包 → 插件 → 入口包上传到 `candidate-X-Y-Z`。
+4. 从官方 npm registry 安装精确版本。
+5. 再次核对源码和远端 tag，按相同顺序提升 `latest`，验证六包标签和 integrity。
+
+该命令复用既有发行检查，仅让 npm publish 和 dist-tag 写操作继承终端 I/O；registry 查询保留严格 JSON 解析和有界超时。命令不负责登录、创建／移动 tag 或修改账号安全设置。
+
+已审查的旧发行若确实需要新工具，可通过 `--source-directory` 指向旧版精确 tag worktree，通过 `--directory` 指向原候选。源码默认是工具所在 checkout，候选默认是选定源码目录下的 `dist-npm/`；显式相对路径从调用目录解析。不要将新工具复制进旧发行源码，也不要重建已经发布的同版本。
+
+## 6. 可见性、标签提升与重试
+
+所有包先使用 candidate 标签。精确版本和 integrity 均可查询、registry 安装通过后，才提升 `latest`；顺序为平台包、插件、最后用户入口包。npm 不提供六包标签的原子事务。
+
+只有结构化 E404 表示所查询版本不存在。认证、网络、取消、异常输出和缺失 integrity 都应失败。查询接受已支持的标量或单元素数组，多结果拒绝。
+
+上传后每个包的可见性检查预算为 180 秒，E404 从 2 秒起步退避，最大 15 秒；每次读取上限为 30 秒及剩余预算中的较小值。标签提升后，用相同的有界方式复核 `latest` 与 integrity，只重复读取，不重复写入。发现更高的 `latest`、integrity 冲突或非法版本时拒绝继续。
+
+| 故障 | 恢复方法 |
+| --- | --- |
+| 认证或浏览器审批未完成 | 处理正常 npm 授权，保留候选。 |
+| 部分包已上传 | 重试原候选；已有版本必须与其 integrity 一致。 |
+| registry 可见性超时 | 保存 artifact，外部问题解决后重试。 |
+| 安装或标签提升失败 | 继续使用同一候选，不能回退更新的 `latest`。 |
+| 上传后需要修改源码 | 选择新的统一版本和经过审查的新 tag。 |
+| 原候选丢失 | 找回原候选，不能假定重建字节相同。 |
+
+Actions 使用原 artifact 重跑失败 job；本地使用保留的源码和候选重跑最后一条 `release:local` 命令。
+
+## 7. 记录完成状态
+
+只有六个精确版本和 integrity、registry 安装及最终 `latest` 复核全部通过，才能记录发行完成。源码审查、本地测试、CI 和桌面验收分别说明。需要额外检查精确版本安装时：
+
+```sh
+FLYWHEEL_NPM_VERSION=X.Y.Z npm run test:registry
+```
+
+将 `X.Y.Z` 替换为已发布版本。在带日期的验收记录和 release notes 中保存 source SHA、候选身份、实际平台、失败／重试和剩余限制。[0.30.2 发行记录](../validation/2026-11-11-release-0.30.2.md)是历史示例，只证明该次发行，不代表当前 registry 的实时状态。

package/docs/{session-evaluation.md → zh-CN/session-evaluation.md}

@@ -1,8 +1,10 @@
 # 会话质量策略与配对评估
 
-P4 提供两部分可执行能力：按已确认事实进行有界重建，以及对相同任务运行三种历史策略的配对评估。重建阈值默认关闭；评估程序保存原始条件和结果，不把缺失用量写成零，也不预设质量、缓存率或速度收益。
+[文档目录](../README.zh-CN.md) · [English](../en/session-evaluation.md) · 简体中文
 
-配置入口见 [配置文档](configuration.md)，中断恢复的生命周期和账本语义见 [恢复文档](session-recovery.md)。实现入口为 [质量策略](../internal/machine/session_quality.go)、[评估器](../scripts/evaluate-sessions.js) 与 [任务集生成器](../scripts/prepare-session-evaluation.js)。
+Flywheel 支持按已确认事实进行有界上下文重建，以及对相同任务运行三种历史策略的配对评估。重建阈值默认关闭；评估程序保存原始条件和结果，不把缺失用量写成零，也不预设质量、缓存率或速度收益。
+
+配置入口见 [配置文档](configuration.md)，中断恢复的生命周期和账本语义见 [恢复文档](session-recovery.md)。实现入口为 [质量策略](https://github.com/ckanner/flywheel/blob/main/internal/machine/session_quality.go)、[评估器](https://github.com/ckanner/flywheel/blob/main/scripts/evaluate-sessions.js) 与 [任务集生成器](https://github.com/ckanner/flywheel/blob/main/scripts/prepare-session-evaluation.js)。
 
 ## 有界重建
 

package/docs/{session-recovery.md → zh-CN/session-recovery.md}

@@ -1,8 +1,25 @@
 # 会话中断恢复与上下文质量
 
-本指南描述会话方案 P3/P4 的当前源码实现。P1/P2 的角色历史续用和已保存回执消费继续有效；新能力需要配套的 **Codex Pro 0.9.0** 或 **Claude Code Pro 0.4.0** 公开 machine API。源码、npm 发行、账号可用性和真实任务效果是不同的验收项。
+[文档目录](../README.zh-CN.md) · [English](../en/session-recovery.md) · 简体中文
 
-## 1. 谁拥有哪些事实
+Flywheel 分别处理角色对话历史续用和中断调用恢复。fresh 与 scoped 都保留调用安全
+检查。公开 journal 的持久化恢复要求 **Codex Pro 0.9.0** 或 **Claude Code Pro 0.4.0**；
+DSH 与 Kimi 继续使用各自支持的恢复路径。
+
+## 恢复已有任务
+
+使用原任务账本和集成目录，先查看状态，再通过正常引擎入口请求继续：
+
+```sh
+flywheel control status --cwd /repo --task-dir /repo/docs/my-task
+flywheel control start --cwd /repo --task-dir /repo/docs/my-task
+```
+
+引擎会先核对先前的调用，再决定能否发起新请求。`pending` 或 `unknown` 可能使任务
+保持阻断；应保留 journal 和诊断，不要删除状态或改成 fresh 会话来强行继续。
+状态回复描述当前事实，不代表可以重放尚未确认的调用。
+
+## 谁拥有哪些事实
 
 | 层 | 责任 |
 |---|---|
@@ -13,7 +30,7 @@
 
 外层 worker 协议为 3，插件请求和回执仍是 machine protocol 1，生命周期单独为 version 1。DSH 和 Kimi 继续使用其已实现的正常历史续用及 Go 回执恢复；不能从这两个新插件的能力推断它们也有同样的 P3 接口。
 
-## 2. 派发前必须有持久化确认
+## 派发前必须有持久化确认
 
 Go 准备任务的 `.sessions/` 父目录并保存调用意图，上游 API 再独占创建本次调用的恢复子目录。子目录以调用 ID 的摘要命名；不在用户的全局模型历史中搜索。
 
@@ -26,7 +43,7 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 
 上游 supervisor 与 worker 的生命周期分离，拥有原生 guardian。worker 断连时，它取消尚未确认的步骤并收束原生进程；终态回执在向 worker 通知终态之前已落盘。通知或最后 ACK 丢失不能把原本成功的完整回执改成“未执行”。
 
-## 3. 恢复只读，不会重发 prompt
+## 恢复只读，不会重发 prompt
 
 重新启动同一任务时，Go 根据原调用保存的 adapter 版本、request/run ID、任务目录与绑定，调用公开 `recoverMachine`。它只读取那个调用的 journal，不启动原生 CLI，不执行 `thread/resume`，不查询其他任务，不重新提交 prompt。
 
@@ -44,7 +61,40 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 
 若 supervisor 保存了回执，但 Go 尚未来得及记录原候选，则可恢复可信用量，业务仍保持阻断。只有物理事实证明未派发、清理完成且候选与原 guard 完全未变的拒绝，才允许按已知未执行处理。独立 Review/Judge 的原契约与候选检查继续适用。
 
-## 4. 计量与预算
+### 共享目录并行
+
+共享目录并行的 Execute 回执使用已声明写入范围的候选指纹，并把该范围绑定到会话身份；其他任务的独立变更不会导致本调用无故丢失归属。自己的范围变化仍拒绝旧回执。L1、独立 Review 与批次提交始终核对完整共同候选；范围回执不能证明整组完成，也不能绕过未知派发、结果或清理。
+
+### DSH 预热运行时的重启核对
+
+可选 `scheduler.prewarm` 在确定性检查期间准备 DSH Review runtime，不发送
+模型 prompt。Go 在启动前保存单个 `worker-prewarm` 清理责任，绑定准备 ID、
+角色／范围、配置身份和 run；终态回执私有保存在 `.control/prewarm/` 下。
+这份回执不是模型调用或 Review 通过证据。
+
+完整终态 JSON 在 UTF-8 序列化后最多 8 KiB，包含转义字符和末尾换行。过长的错误
+诊断会保留带截断标记的前缀，正常短错误以及全部身份、派发和清理字段保持完整。
+诊断截断不会放宽任何恢复检查，也不会把初始化失败变成允许冷启动回退的安全过期。
+
+引擎重启不会续用这个待用 worker。只有原身份匹配的回执证明没有提交 prompt、
+SDK 清理已确认，且记录的 worker 与其原进程组都已退出，才可解除原清理责任。
+发布回执时同步文件与目录；恢复时在清除状态前重新确认这两项持久化。实际从未
+启动进程时，可以使用明确记录的本地 no-process 回执；不能仅凭经过时间或缺失
+PID 推断。回执缺失、超限、损坏、身份不匹配、进程或进程组仍存活或无法确认退出、
+清理未知都会保持阻断；关闭预热也不能跳过核对。安全收束后，后续工作才按当前
+配置和正常调用检查继续。
+
+在同一个引擎运行中，待用实例安全过期、且尚未尝试任何正式派发时，可在同一
+已持久化 invocation 身份和剩余时限内冷启动一次。这不属于重启续用，不增加一次
+模型计费尝试，也不能绕过未知效果。取消、正式调用时限耗尽、清理不完整或输出
+不可信时都不能这样回退。
+
+首次创建预热记录会将 `state.sessions.version` 提升为 **3**，后续操作保持该
+版本。这个存储兼容标记使旧引擎拒绝无法理解的清理责任；新引擎仍支持版本 1、2。
+配置的 `sessions.policy-version` 仍为 1，worker 和 lifecycle 各自维持独立的
+协议版本。不要手改存储版本或删回执来强行降级。
+
+## 计量与预算
 
 已消费的调用不再次计数，不重发模型请求。原调用曾因丢失回执计为 unknown、后又找回可信 usage 时，Go 按同一调用记一条可审计 correction；保留原 provider、原日桶和 lifetime 归属。已过保留窗口的日桶不会因为恢复而重新出现。
 
@@ -52,9 +102,9 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 
 未知仍不是零。恢复中的质量重建、Quick → Full、角色模式变化和新 worker 都不重置预算、尝试次数或未知调用阻断。预算只约束新的派发，不妨碍消费已经执行完成且证据齐全的结果。
 
-## 5. 可解释的上下文重建
+## 可解释的上下文重建
 
-`sessions.roles` 可分别选择 Plan、Execute、Review、Judge 的 fresh/scoped；未覆盖的角色沿用总模式。具体配置见[会话策略](configuration.md#会话策略历史复用与调用安全)。
+`sessions.roles` 可分别选择 Plan、Execute、Review、Judge、judge-panel 的 fresh/scoped；未覆盖的角色沿用总模式。具体配置见[会话策略](configuration.md#会话策略历史复用与调用安全)。
 
 可选 `sessions.quality` 接受三个有界指标：
 
@@ -68,16 +118,29 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 
 重建保留明确原因与 generation，并用当前 Spec、packet、工作区、合法报告、验证与结构化反馈交接。它不读取另一个角色的私有 transcript，不以“压缩成功”伪造模型事实，也不另发未计量的模型压缩调用。Review 即使续用自己历史，仍须检查完整当前候选。
 
-## 6. P4 对照评估与证据边界
+### 可信的增量输入
+
+显式 `sessions.context:"verified-incremental"` 允许 Execute 复用可信同角色的
+稳定契约；Go 复核已消费回执明确证明 `dispatched` 且 `completed`，并检查提示词
+版本、当前契约及可读 context/cache 文件摘要。安全的启动拒绝或失败／取消调用
+可以保留原线程，但不证明本轮新准备的权威内容已送达；下一次仍须完整重发。
+新输入携带反馈、候选身份、尝试和引用。权威内容变化或不可用、旧任务缺
+检查点、上下文回执无效时回到完整输入，角色记录保存选择与原因。Review、Judge
+保持完整当前输入，不继承 Executor 私有历史。
+
+可选[执行策略](configuration.md#有界执行策略显式启用)可选择另一完整允许绑定。
+每次切换均新建历史代次，仅改变 effort 也不例外；显式会话模式同样进入绑定
+身份。unknown／pending 调用先对账，新上下文不能授权重放未知副作用。切换记录
+区分质量升级和渠道后备，保留原任务及 packet 预算。
+
+## 对照评估与证据边界
 
 仓库提供固定源码与独立 oracle 的评估工具，比较 fresh、仅 Execute scoped、各角色 scoped。覆盖一次成功、L1 返修、Review return、长上下文、停止恢复、配置改变；轮换策略顺序并要求重复运行。工具记录完成质量、漏项、回归、返修轮数、重复 findings、耗时、已知/未知 token 与缓存、重建原因和恢复失败。场景是否发生由实际状态证据判断，不靠名称。
 
-离线 native fixture 经过真实 Go、worker v3 和公开插件接口，验证评估工具及安全边界；它不是实际模型质量、缓存率或节省比例。真实账号的对照结果需要可用的原生 CLI、账号、权限与模型环境。未获得该结果前不自动启用阈值，不改变任何默认模型或 loop。操作步骤与实验产物说明见[配置指南](configuration.md)及 `scripts/prepare-session-evaluation.js`、`scripts/evaluate-sessions.js` 的帮助。
+离线 native fixture 经过真实 Go、worker v3 和公开插件接口，验证评估工具及安全边界；它不是实际模型质量、缓存率或节省比例。真实账号的对照结果需要可用的原生 CLI、账号、权限与模型环境。未获得该结果前不自动启用阈值，不改变任何默认模型或 loop。操作步骤与实验产物说明见[配对评估指南](session-evaluation.md)。
 
-## 7. 保存和排障
+## 保存和排障
 
 上游恢复目录与文件使用私有权限、独占创建、身份/摘要检查和原子持久化；已存在目录不会触发二次执行。它们属于任务审计证据，可能含模型输出与诊断。按任务一起保存、备份和控制访问，不复制凭证，也不因安装升级而删除未知调用的证据。
 
 当前没有自动删除这些恢复证据的保留计时器。确认任务完成或由人解决未知结果之后，才能按项目的任务归档流程处理；删除 journal 不是解除阻断的恢复方法。`control status`/doctor 是查看入口，模型与 skills 不修改 `state.json`。需要恢复时仍从原任务目录使用正常 Go 启动入口，由引擎核对并决定下一步。
-
-共享目录并行的 Execute 回执使用已声明写入范围的候选指纹，并把该范围绑定到会话身份；其他任务的独立变更不会导致本调用无故丢失归属。自己的范围变化仍拒绝旧回执。L1、独立 Review 与批次提交始终核对完整共同候选；范围回执不能证明整组完成，也不能绕过未知派发、结果或清理。