@ckanner/flywheel 0.30.2 → 0.31.1

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

@@ -0,0 +1,123 @@
+# 模型、推理等级与账号
+
+[文档目录](../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 预算及显式切换上限内前进实验顺序；这条确定性规则
+不证明后一个模型更好。渠道错误使用单独声明的后备，两种机制都不能选择未声明
+的模型或费用渠道。
+
+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,11 @@ Go 将事件与原调用身份核对后，先原子保存并 `fsync` 检查点
 
 若 supervisor 保存了回执，但 Go 尚未来得及记录原候选，则可恢复可信用量，业务仍保持阻断。只有物理事实证明未派发、清理完成且候选与原 guard 完全未变的拒绝，才允许按已知未执行处理。独立 Review/Judge 的原契约与候选检查继续适用。
 
-## 4. 计量与预算
+### 共享目录并行
+
+共享目录并行的 Execute 回执使用已声明写入范围的候选指纹，并把该范围绑定到会话身份；其他任务的独立变更不会导致本调用无故丢失归属。自己的范围变化仍拒绝旧回执。L1、独立 Review 与批次提交始终核对完整共同候选；范围回执不能证明整组完成，也不能绕过未知派发、结果或清理。
+
+## 计量与预算
 
 已消费的调用不再次计数，不重发模型请求。原调用曾因丢失回执计为 unknown、后又找回可信 usage 时，Go 按同一调用记一条可审计 correction；保留原 provider、原日桶和 lifetime 归属。已过保留窗口的日桶不会因为恢复而重新出现。
 
@@ -52,9 +73,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,13 +89,28 @@ 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. 保存和排障
+## 保存和排障
 
 上游恢复目录与文件使用私有权限、独占创建、身份/摘要检查和原子持久化；已存在目录不会触发二次执行。它们属于任务审计证据，可能含模型输出与诊断。按任务一起保存、备份和控制访问，不复制凭证，也不因安装升级而删除未知调用的证据。
 

package/docs/zh-CN/workflow.md

@@ -0,0 +1,270 @@
+# 工作流：从需求到 Pull Request
+
+[文档首页](../README.zh-CN.md) · [English](../en/workflow.md) · 简体中文
+
+Flywheel 将经过审阅的任务契约转化为经过验证的本地 Git 变更。宿主助手负责准备任务，
+Go 引擎负责调度、验证、恢复和交付。流程控制台还支持在明确授权后创建和合并远端 PR。
+
+本文适用于已有仓库。安装及独立的首次运行示例见[快速开始](getting-started.md)。
+
+## 0. 常规入口：描述目标并启动
+
+在 DSH 对话中使用任务技能描述需求：
+
+```text
+/flywheel-task 修复已定位的问题，补齐回归测试并完成验证。mode=auto
+```
+
+宿主研究代码，选择或复用任务执行目录，准备 Spec、packet、可执行验收与工作流依据，
+再在已授权范围内调用 `flywheel_launch`。插件将真实任务关联到当前会话。
+加载技能或收到方案并不代表引擎已启动，应核对启动回执和任务状态。
+
+| 模式 | 选择与执行 |
+|---|---|
+| Auto，默认 | Go 根据已记录的资格事实选择 Quick；依据不足则选择 Full |
+| Quick，控制台也标为 ultraWork | 一个里程碑、一个 packet；Execute、必需验证、独立最终 Review、Git 交付 |
+| Full | Plan、packet 执行与评审、集成 L2/L3、Judge |
+
+Quick 要求范围明确、实现模式已知、全部需求有验收映射，最终评审可以判断整个任务。
+缺失 L2/L3 时需要明确的不适用理由。鉴权、权限、支付、迁移、并发或未决设计风险应走
+Full；显式选择 Quick 也不能跳过资格检查，文件数量不能代替风险判断。
+
+正常首次成功的 Quick 有 Execute 与最终 Review 两次阶段 Agent 调用。宿主准备、
+内部工具轮次、重试和升级另计。必需测试、覆盖率、适用 L2/L3、缺陷抽检、预算及进程
+收尾仍保留；Plan／Judge 标为不适用并记录原因。发现新风险或验收缺口后，Go 先保存
+单向 Quick → Full 升级，再继续完整流程，保留成果和累计预算。
+
+只准备方案时用 `/flywheel-new <需求>`；运行已有任务时用
+`/flywheel-run <绝对任务目录>`。Kimi 对应使用 `/skill:flywheel-task` 等 `/skill:` 名称。
+
+## 0.1 调查与专用入口
+
+Task 可以直接接收“先排查，告诉我原因”，自动准备并进入 Go 受管调查；无需先手动 New。
+只排查到报告结束；已授权“排查并修好”时，证据支持结论后在原范围内继续实现。
+新[调查指南](investigation.md)说明契约、证据、JEV 与恢复。原 New → 审阅 → Run 仍适合
+明确要求先审方案的复杂任务，Plan / Exec / Verify / Review / Status / Stop 均保留。
+
+Full 复用已确认且持久化的有效 Plan 检查点；显式 Plan、verification-gap、契约变化或
+不可信基线仍重规划。执行者先跑针对性检查，Go 完整门禁与独立 Review 继续负责完成。
+模型绑定默认不变；允许集合和可信增量上下文是独立 opt-in，见[配置](configuration.md)。
+
+## 1. 选择准备阶段的模型
+
+`flywheel-task` 与 `flywheel-new` 使用宿主当前对话的模型。`loops.plan` 只控制
+**引擎启动之后**的规划，不会切换宿主对话模型。
+
+| 准备任务 | 建议的 DSH provider／模型 | 思考等级 |
+|---|---|---|
+| 架构、协议、生命周期或不明确的验收 | `chatgpt`／`gpt-6-astra` | `high` |
+| 有既定实现模式的边界明确功能 | `chatgpt`／`gpt-6.1-sol` | `high` |
+| 明确的小修复或文档调整 | `deepseek-account`／`deepseek-flash` | `high` |
+
+这些是工程起点，不是本项目的 benchmark 结论。先在实际账号中核对精确模型 ID 和
+支持的 effort。提高思考等级不能修复缺失需求或错误验收依据。运行期默认分配与账号
+渠道见[模型策略](model-policy.md)和[配置指南](configuration.md)。
+
+## 2. 选择任务执行目录
+
+区分以下位置：
+
+| 位置 | 用途 |
+|---|---|
+| 项目工作区 | Provider Session 的稳定仓库归属，通常为原始 checkout |
+| 任务集成目录 | 准备契约、集成已验证 packet 的 checkout 和分支 |
+| 任务文件目录 | 该 checkout 内的 `docs/<slug>`，保存 Spec、packet、状态与报告 |
+| packet 执行目录 | Execute、验证、Review 使用的候选目录，通常是引擎管理的 worktree |
+
+项目工作区可以与实际执行目录不同。Session 归属项目不代表文件操作在项目根执行；
+提示词和证据明确绑定实际执行目录。后端不能表示选定的分离式 `workspace-write`
+沙箱时，会在派发前拒绝该组合。
+
+使用默认 worktree 策略时，准备前先创建或明确复用任务分支和独立 worktree。先检查
+已有改动，使用未占用的名称，并替换成仓库真实的基分支：
+
+```sh
+git status --short
+git fetch origin
+git worktree add -b task/my-feature ../repo-my-feature origin/main
+cd ../repo-my-feature
+git branch --show-current
+```
+
+任务文件放在所选 checkout 的 `docs/my-feature`。集成分支就是传入 `cwd` 中当前
+检出的分支，并非硬编码的 `main`。不要把一个 checkout 的任务目录与另一个 checkout
+的 `cwd` 配对，也不要在运行中切换该分支。
+
+`worktree.enabled` 只控制引擎对 **packet** worktree 的自动管理，与并行调度独立。
+关闭后可共享所选任务 checkout，也可在实现前登记外部 worktree。外部目录仍须通过
+基线、分支、干净状态和归属校验，详见[串行与并行](flow-console.md#串行与并行)。
+
+### 隔离与失败行为
+
+Worktree 隔离工作目录和索引，不是安全沙箱。旧串行路径在 worktree 创建失败时可以
+记录原因并退回原地执行；开启自动 worktree 管理的并行路径要求独立目录，创建失败
+就停止。显式关闭自动管理后允许共享 checkout，但采用相应的批次验证和交付规则。
+
+需要独立目录时，应检查实际记录的工作区模式，在意外回退时停止。保留已有成果并
+解决失败原因，不要通过修改 `state.json` 或强制重置分支伪造隔离状态。
+
+## 3. 准备并审阅契约
+
+在任务集成目录调用准备技能，或查看内嵌模板：
+
+```sh
+flywheel template --list
+flywheel skills read flywheel-new
+```
+
+```text
+/flywheel-new 为这个需求准备 docs/my-feature。研究实际代码，定义有边界的 packet 与可执行验收，运行基线检查，再展示契约供审阅。
+```
+
+无需先填写控制台表单。准备结果应给出真实任务执行根和任务文件路径，同时保留原
+项目归属。一个仓库可包含多个任务，仓库路径本身不能唯一指定任务。
+
+可运行任务需要已审阅的 `spec.md` 和至少一个合法 `task-packet-*.md`。应明确需求 ID、
+排除范围、路由、可写与保护路径、L1 命令、里程碑 L2/L3 命令和实际基线结果。
+冻结验收与普通实现测试分开：执行者可补普通单测和回归测试，不能削弱受保护验收来
+换取通过。
+
+Spec 的 `workflow` 保存资格事实、风险和检查不适用理由。并行 packet 还须显式声明
+`schedule.after` 与 `schedule.writes`，字段示例见[工作流策略](configuration.md#工作流策略与恢复)
+和[调度与-worktree](configuration.md#调度与-worktree)。缺少工作流字段的契约继续按
+Full 处理；未声明独立性的 packet 保持串行。
+
+审阅后提交真实契约，使 packet worktree 能从 Git 取得它们。先检查索引中没有无关
+暂存改动：
+
+```sh
+git diff -- docs/my-feature
+git diff --cached --stat
+git add -- docs/my-feature
+git diff --cached
+git commit -m "docs: prepare my-feature contracts"
+```
+
+额外验收文件也须分别审阅再暂存。`state.json` 由引擎创建和维护，准备技能与模型不写它。
+
+## 4. 按需建立任务级 Draft PR
+
+初始契约提交后，Draft PR 可以作为固定的审阅入口。已获授权的宿主或用户可在执行前
+创建：
+
+```sh
+git push -u origin task/my-feature
+gh pr create --draft --base main --head task/my-feature
+```
+
+描述问题、预期结果、验收与未完成工作。通常一个可独立交付的需求或里程碑对应一个
+PR；packet 是内部执行单元，不会自动各建一个 PR。提前创建 Draft PR 不代表批准合并。
+控制台后续 PR 操作会在 push 后重新查询已有 PR，避免重复创建。
+
+## 5. 从同一个任务执行目录启动
+
+已有任务准备完成后，在其集成 checkout 运行：
+
+```sh
+flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --json
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --probe --json
+flywheel control launch --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --mode auto
+flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+```
+
+预检不发送推理 prompt，也不运行验收命令。正式启动才调用所配置的模型。
+控制回执的 `ok` 表示本次操作结果，整体完成看 `state.status`。
+
+`launch` 默认 Auto；`start` 与前台 `run` 接受 `--mode auto|quick|full`，省略时沿用
+契约或持久化选择。status／stop 不切换模式，重启或请求 Auto 不能将已确立的 Full 降级。
+
+DSH 对应使用 `/flywheel-run <绝对任务目录>` 和 `/flywheel-status <同一路径>`。
+启动与只读状态关联会使任务出现在控制台。控制台选择已登记任务，不再提供可编辑的
+任务／项目路径框。带 DSH host ID 的终端运行可归属对应会话，其他运行仍能从最近任务
+选择；发现过程不扫描目录。
+
+### 各阶段的执行目录
+
+| 阶段 | 实际执行目录 |
+|---|---|
+| 准备、Full Plan、获准的契约修订 | 任务集成 checkout |
+| Execute、L1、独立 Review | 当前 packet 候选目录 |
+| Quick 适用的 L2/L3 | 最终 Review 前的同一 packet 候选目录 |
+| Full L2/L3、Judge | packet 交付后的任务集成 checkout |
+| Intake、Garden | 所选任务执行根 |
+| Status、Stop | 原任务文件与执行根，无需新分支或 worktree |
+
+上表是执行位置，Provider Session 仍保留单独记录的项目工作区。任务 checkout 跨越整个
+交付过程，packet 目录跨越实现、检查、评审和交付；每个 loop 不需要新建 worktree，
+也不需要一个持续运行的父模型监督。
+
+### 调度与角色历史
+
+新安装默认配置使用 `scheduler.mode=parallel`，最大并发为 2。已有完整配置没有 `scheduler`
+时仍为串行，显式 serial 也保持不变。只有依赖已满足、显式声明依赖和互不重叠写入范围
+的 packet 才有并行资格。独立 worktree 可并发 Execute／L1；共享 checkout 批次并发
+Execute，再验证和评审完整共同候选。Review、集成与终验保持串行。hard 预算在前一调用
+完成持久化计量前只允许一个模型调用在飞，详见[控制台指南](flow-console.md#串行与并行)。
+
+`scoped` 历史可在资格满足时复用同 packet Executor Session 返修。Review 使用独立
+历史，每次仍检查完整当前候选；Plan 按任务／里程碑划分，Judge 和第二意见分别独立。
+旧配置省略 `sessions` 时继续 fresh。两种模式都有调用安全记录，派发、结果或清理未知
+都会阻断。[恢复指南](session-recovery.md)说明可信回执、持久化检查点和有界上下文重建。
+
+### 单阶段操作与权限
+
+`flywheel-verify` 只运行确定性验收，不调用 Review／Judge 或执行 Git 交付。
+`--only execute` 是有界 Execute／L1 循环。Quick 的 `--only review` 执行最终评审但不
+交付，必要时保存 Full 升级而不跨阶段启动 Plan；`--only plan` 要求 Full。继续完整流程
+才会处理剩余阶段与交付。控制台的受管阶段操作还会检查状态 revision。
+
+模型权限由有效全局策略及逐绑定覆盖决定。完全权限不会取消冻结边界或评审候选检查，
+Kimi print 不提供 OS 沙箱保证。技能还会在开发前检查任务位置；直接 CLI／GUI 调用
+不会执行 `SKILL.md`，也不会创建外层任务分支。只读状态与停止保持独立可用。
+
+## 6. 理解本地完成，再合并 PR
+
+本地交付要求当前候选具备有效验证、独立 Review 和可核实的 Git 持久化。packet
+worktree 的成果集成到任务 checkout；交付失败保留成果。共享 checkout 批次只有在
+全部成员对共同候选通过且整批状态持久化后才完成。Full 还需集成 L2/L3 与 Judge；
+Quick 的最终 Review 须覆盖全部需求、验收充分性及持续资格。
+
+远端交付是独立操作。可以手动检查并推送任务分支：
+
+```sh
+git status --short
+git log -5 --oneline
+git push origin task/my-feature
+gh pr ready
+gh pr checks
+```
+
+也可明确授权仓库、源 HEAD、任务分支和目标分支后使用控制台 PR／Merge 节点。
+这些操作需要正常的 GitHub CLI 登录和仍有效的本地验收。合并会重新检查 PR、head、
+base 与 checks，并绑定获准的源提交，不使用 admin 绕过，也不擅自开启 auto-merge。
+合并队列接收请求不等于已经合并，详见[远端 PR 与 Merge](flow-console.md#远端-pr-与-merge)。
+
+合并前检查当前差异、必需 CI 和最新基分支。绿灯后的变更可能要求重验；无法运行的
+检查如实记录，并按仓库授权流程处理。发布或部署有独立验证，不因点击 Merge 自动开始。
+
+## 7. 停止与恢复，保留原有证据
+
+```sh
+flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+```
+
+核对停止回执和真实失败原因后，再从原路径使用 `control start` 或 `/flywheel-run`
+恢复。启动就绪超时或请求断连需要核对，不能据此重复启动；关闭页面不会停止引擎。
+
+两种会话模式都会在派发、模型结果或清理未知时阻断。进程退出本身不能证明模型结果
+已知。Go 必须将可信回执与原身份、原证据核对；切 fresh、换后端或重置状态不能绕过
+未解决调用。
+
+交付冲突时保留 worktree 和报告，处理实际 Git 冲突后由引擎重验。配置变更需重启
+引擎。对已有合格会话进行受管人工交互，见[同一 Provider Session 接管](flow-console.md#在同一-provider-session-中接管)。
+
+## 相关指南
+
+- [配置](configuration.md)：模型绑定、权限、预算与策略。
+- [流程控制台](flow-console.md)：任务、阶段、会话、运行对比与远端交付。
+- [恢复与上下文质量](session-recovery.md)：中断核对与安全续用。
+- [JEV 影子评估](jev-shadow.md)：可选且默认关闭，不改变实际工作流选择。
+- [系统设计](../design.md)：权威实现契约。

package/npm/install.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
+// Copyright (c) 2026 ckanner. SPDX-License-Identifier: MIT
 "use strict";
 
 const fs = require("node:fs");