@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/zh-CN/workflow.md

@@ -0,0 +1,284 @@
+# 工作流：从需求到 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)。
+
+已授权调查可使用输入副本中的确切复现命令及明确 GET／HEAD 请求，执行权限边界、
+deadline、输出上限和回执写入调查契约。开启 JEV 后，确认结束的实施失败也可在
+返修、已批准反馈检查、重规划或已有允许执行绑定中选择；流程资格和最终完整门禁
+仍由 Go 负责。一次反馈实验成功不等于实现完成。
+
+## 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#串行与并行)。
+
+可选 `scheduler.dispatch="ready-queue"` 在自动管理 Worktree 的 Full 任务中，为
+已就绪的独立 packet 补充空闲 Execute／L1 槽位；Review、Plan 修订和集成仍等待
+已启动 worker 停稳。`scheduler.prewarm=true` 可以在串行 packet 的确定性检查
+期间准备一个 DSH Review runtime，不提前发送模型 prompt。并行执行 lane 和共享
+候选不预热；独立并行组停稳后，串行 Review 路径才可开始准备。主要重叠机会是
+串行 Execute 后的 L1 和适用 Quick 检查。默认仍为 batch 调度且不预热；
+Task／New／Run 和 Auto／Quick／Full 的职责保持，详见
+[配置与限制](configuration.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.md)：一个默认关闭的总开关控制调查及有界失败决策，Go 保留工作流资格与验收规则。
+- [系统设计](../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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
@@ -23,36 +23,23 @@
     "type": "git",
     "url": "git+https://github.com/ckanner/flywheel.git"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "files": [
     "bin",
     "npm/*.js",
     "README.md",
+    "README.zh-CN.md",
     "README.en.md",
     "CHANGELOG.md",
-    "docs/getting-started.md",
-    "docs/configuration.md",
-    "docs/model-policy.md",
-    "docs/workflow.md",
-    "docs/flow-console.md",
-    "docs/en/getting-started.md",
-    "docs/en/configuration.md",
-    "docs/en/model-policy.md",
-    "docs/en/workflow.md",
-    "docs/en/flow-console.md",
-    "docs/examples/create-first-task.sh",
-    "docs/claude-code-pro.md",
-    "docs/en/claude-code-pro.md",
-    "docs/session-recovery.md",
-    "docs/en/session-recovery.md",
-    "docs/session-evaluation.md",
-    "docs/en/session-evaluation.md"
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "docs"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.31.0",
-    "@ckanner/flywheel-darwin-amd64": "0.31.0",
-    "@ckanner/flywheel-linux-arm64": "0.31.0",
-    "@ckanner/flywheel-linux-amd64": "0.31.0"
+    "@ckanner/flywheel-darwin-arm64": "0.32.0",
+    "@ckanner/flywheel-darwin-amd64": "0.32.0",
+    "@ckanner/flywheel-linux-arm64": "0.32.0",
+    "@ckanner/flywheel-linux-amd64": "0.32.0"
   },
   "scripts": {
     "release:check": "node scripts/release-preflight.js",
@@ -60,10 +47,10 @@
     "test": "node --test npm/test/*.test.js",
     "test:install": "node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.31.0 dist-npm",
+    "build:npm": "bash scripts/build-npm.sh 0.32.0 dist-npm",
     "test:sessions": "node scripts/test-session-evaluation.js"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.31.0"
+    "@ckanner/dsh-plugin-flywheel": "0.32.0"
   }
 }

package/docs/flow-console.md

@@ -1,122 +0,0 @@
-# Flywheel 流程控制台
-
-本文描述当前源码中的控制台。源码、开发候选、本机安装与 npm 正式发行分别验收；不要仅凭本文判断 `@latest` 已包含这些功能。CLI、平台包和 DSH 插件必须同版。
-
-## 找到任务，不必填写路径
-
-新版画布先显示任务选择。当前 DSH 会话只有一个已登记任务时自动打开；有多个任务时选择其一。通过终端运行的任务也会使用 DSH 提供的会话 ID 登记；该标识只用于发现，不能授予控制权限。页面读取运行索引后再请求 Go 状态，不把索引当成仍在运行或已经完成的证明。
-
-旧版本记录没有会话 ID 时，从“本机最近任务”选择即可；选择会发送只读状态查询，并保存到当前会话关联。刷新任务列表不会启动、重试或切换你手动选中的任务。读取失败保留已打开画布；未确认的操作仍先核对原任务。
-
-界面不再提供任务路径／项目路径输入框。助手与引擎提供实际位置；有值后显示为只读信息。项目工作区是原仓库的稳定归属，实际执行目录可以是任务集成目录或独立 Worktree，两者分开显示。任务文件夹保存说明、验收清单和进度。准备但尚未运行的任务由助手通过只读 status 关联，随后也能在列表中选择。
-
-DSH Session 的原始项目目录保留为原仓库，运行时通过公开接口切换当前执行目录。桌面 Host 定期把 Flywheel SDK 会话登记到已有的匹配项目；读取实际任务状态时也会确保原项目已登记。不会把每个 packet Worktree 创建成新的桌面工作区，不修改旧 Session 的历史头部；旧会话只能按其真实目录归属。探测会话写入临时存储，退出后清理，不再污染用户会话列表。原生 Provider 在项目目录开会话，任务提示词明确列出实际执行目录；每次 shell／文件操作必须显式使用它。当前后端不能分离 `workspace-write` 沙箱根时，在派发前明确拒绝该组合，不自动扩大权限；完全权限及支持的只读模式保持其真实含义。
-
-Skill 已加载不代表引擎已经启动。`flywheel-task` 准备并通过 `flywheel_launch` 启动后才产生运行；只要求调研或方案时，助手应明确说明尚未启动。单阶段技能执行后通过 `flywheel_control status` 关联当前画布；没有该工具时明确给出路径，不能声称已关联。
-
-## 本次阶段与完整流程
-
-`run.kind` 与 `control.kind` 一致的单阶段任务优先显示“本次运行”和真实回执。仅运行 Review 时，默认画布为 **L1 → Review**，并显示记录结论、评分及“整体交付尚未完成”；其它未运行阶段不会盖过这次评审结果。可切换“完整流程”查看全貌。
-
-“继续整个流程”移入明确的展开项；单阶段通过不自动启动后续阶段，也不把任务改为 completed。失败、取消和结果未知不会沿用旧绿色裁决。Run ID、HEAD 和配置摘要收在“运行记录与文件位置”，需要排查时再展开。
-
-## 从配置开始
-
-在已进入对话视图的 DSH 会话中，Flywheel 排在“统计”之后；新会话的空白首页尚未显示这排会话视图。内部有“运行画布”“全局／项目配置”“运行与对比”。全局配置可在没有任务目录时编辑；项目配置写入所选 Git 项目根。任务配置仍具有最高优先级，取首个完整文件，不做字段深度合并。
-
-打开“配置”后自动读取所选范围，不必先点击读取按钮。按“工作方式／模型分配／预算与重试／JEV 影子建议”编辑；有修改才出现相邻的“保存修改／放弃修改”。普通保存一次点击，首次开启 JEV 先确认任务摘要发送边界。串行模式不显示并发数量；超时以分钟或秒编辑，并精确换算成引擎毫秒字段。
-
-“更多配置操作”提供重新读取和恢复安装版本默认配置。切换范围或重新读取会先提示未保存草稿；重置先载入待保存修改，保存时才替换文件。保存失败保留草稿，结果未知时先重新读取核对。Go 核对文件 revision、备份旧文件并原子写入。正在运行的引擎保留原快照，新配置在后续启动时加载。配置页显示真实文件与来源：文件按任务 → 项目 → 全局 → 安装默认选择，不逐字段叠加；尚未存在的配置文件以安装模板创建。
-
-支持的资源入口包括 ChatGPT · DSH、ChatGPT · Codex Pro、Kimi Code、DeepSeek Account（默认 Flash）及可选 Claude Code Pro。模型初值来自本版本模板，真实能力以 `config inspect`／`doctor` 为准。Claude 的可选适配器必须匹配公开 machine API；缺失或权限不支持会拒绝调用，不自动换后端。账号登录仍由各 Provider 自己完成。
-
-`permissions.bindings` 可以覆盖 `loops.<role>`、`routes.<route>` 和 `judge-panel`；未覆盖项使用全局策略。会话策略按角色覆盖：执行 routes 共用 execute 的策略，各 packet 的历史仍隔离。scoped 只续接相同任务、角色、目标和绑定下可恢复的历史；fresh 也保留调用安全账本。
-
-## 横向画布与节点操作
-
-主线从左到右展示 Plan／拆分、调度、任务分支、汇总与终验、PR 与 Merge。点击节点打开视图内详情，按“进展／会话／本次配置”查看，不挤到画布下方。点击“展开任务画布”进入 Execute、L1、Review、Git 交付子图；汇总和远端交付也可展开阶段。状态配合颜色和文字，运行与节点详情使用真实项目／worktree、分支、HEAD、run ID、调用绑定和失败证据。
-
-画布占满插件可用宽度，支持双向拖动、缩放、适合宽度、定位当前步骤、分页与列表切换。新快照保留视角与选择；定位可跳到当前执行任务所在分页。大任务使用有界诊断摘要；“读取完整节点证据”按需加载选中节点，revision 与同一时刻的画布状态一起刷新。摘要不会改写原始账本。
-
-“专注画布”在插件拥有的原生对话框中扩大画布，退出或按 Escape 回到原视图，不启动或停止任务。它不修改 DSH 的全局布局或宿主输入区；操作结果未知时退出专注视图，显示原调用的核对入口。
-
-运行节点前显示作用范围，确认绑定已观察的状态版本；状态变化后旧确认不可提交。失败任务的“重试一次”需要填写原因，已完成任务显示“重新执行”并说明证据失效范围。独立 Review 在当前 L1 未通过时不可运行。PR 尚未查询、已关闭、已合并分别显示，不把关闭的 PR 当作合并成功。
-
-| 操作 | 含义 |
-|---|---|
-| 运行此阶段 | 提交已观察的 revision；Go 在任务租约内重新检查前置条件 |
-| 人工继续一次 | 填写原因，追加一次 Execute／L1 尝试；保留累计失败和预算 |
-| 已完成单元重跑 | 归档旧证据和提交回执，使当前与后续单元的候选证据失效 |
-| Git 交付 | 只在当前 L1 与独立 Review 通过后持久化当前单元 |
-| 终验 | 已集成单元的 L2／L3 与独立 Judge；不重新调用 Plan 或启动未完成单元 |
-| 继续整个流程 | 由 Go 继续已保存的 Full 或 ultraWork／Quick 策略 |
-| 停止 | 请求 Go 收束在飞子进程；关闭页面不代表停止 |
-
-有显式调度声明且依赖已交付的独立 packet 可单独提前执行，仍使用隔离 worktree。合并后的候选变化会使旧验收失效，必须重新验证和 Review。每个异步节点操作保存 running／passed／failed／cancelled 回执，失败原因不会仅留在后台日志。
-
-Quick 在 UI 中显示为 ultraWork／Quick；它仍要求确定性验证和独立最终 Review。Plan／Judge 按持久化策略标为不适用，不伪造完成状态。
-
-## 串行与并行
-
-配置入口为 `scheduler`，字段和边界以 `flywheel template scheduler-policy.schema.json` 为准。例如：
-
-```json
-{"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}}
-```
-
-`providers` 的键是实际账号渠道名。并行资格来自冻结 packet 的声明，而不是模型临时口头建议：
-
-```yaml
-schedule:
-  after: [M01-T01]
-  writes: [src/search/, tests/search/]
-```
-
-依赖必须指向较早编号的已知 packet；写入范围是规范相对路径／目录前缀，不支持通配符或越出项目的路径。声明要覆盖实现、普通测试和必要配置，并考虑共享测试服务等真实依赖。未声明独立性、写入范围冲突或需要 live 凭证的单元保留串行。
-
-“配置 → 工作方式 → 自动管理任务 Worktree”默认开启，对应 `worktree.enabled`。它只控制引擎自动创建／管理目录，不是“允许使用 Worktree”开关，也不控制能否并行。新默认 `scheduler.mode=parallel`、最大并发 2；已有显式串行配置仍保留。关闭自动管理后，可以在任务 checkout 并行，也可以由模型或用户自行选择 Worktree。共享目录没有文件隔离保证，写入范围冲突、候选变化和验收失败仍如实停止，不能把并发操作当作隔离证据。
-
-自行选择其他 Worktree 时，执行者先创建或选好同仓库、相同任务基线、干净且未被本流程其他任务单元登记的目录（分支也不能被多个 Worktree 共享），在实现前仅返回 `{"flywheelExecutionDirectory":{"cwd":"/absolute/worktree","branch":"actual-branch"}}`。Go 校验后登记到本任务，下一次执行、测试、Review、提交均使用该目录；登记本身不算完成任务，费用仍计入预算。外部 Worktree 不自动删除。不能只在 prompt 中声明目录、修改状态文件，或在未登记的目录实现后让引擎猜测位置。
-
-独立 Worktree 中 Execute／L1 可以并发；共享目录只并发 Execute，随后统一、串行验收与评审。一个 Go 协调器串行 CAS 保存状态和用量。hard 预算只允许一个模型调用在飞，并在下一调用前确认前一笔计费。其他模式按最大并发与渠道限制接纳。停止会等待整批已启动工作收尾。
-
-Review、集成与里程碑 gate 保持串行。后续分支吸收已完成成果后，在合成候选上重新验收。执行重试耗尽仍走原有升级策略；集成冲突或门禁失败保留 worktree 和失败证据。`writes` 是调度／验收契约，完全权限本身不提供 OS 沙箱。
-
-## 在同一 Provider Session 中接管
-
-任务节点显示准确的 Provider session。读取最近回复只读取摘要校验过的原回执，不宣称它是后端的完整历史。
-
-已确认收尾、已消费结果、绑定匹配的 packet session 可“暂停并接管”。接管标记持久化后，普通 run／单阶段操作不能绕过它。桌面输入的人工 Prompt 和 `flywheel session` 都通过原适配器恢复那个准确 thread，并继续预算与计费；恢复失败或需要重建时不冷启动替代。
-
-```sh
-cd -- '/absolute/task-worktree'
-flywheel session '/absolute/task-worktree/docs/task-slug' --key 'execute/M01-T01'
-```
-
-终端每行是一条 Prompt；`/history` 查看最近回复，`/reconcile` 核对原调用，`/return` 验证交回，`/release` 退出接管并保持暂停，`/quit` 保留接管退出。多行 Prompt 可用桌面文本框。
-
-“验证并交回”重新运行 L1、适用的 Quick gate 和独立 Review；人工回复本身不是通过证据。Go 保存绑定当前候选的 `human-takeover` 来源，后续正常交付仍由引擎完成。“退出接管”不声称验收成功；结果或清理未知时也不能借此解除阻断。里程碑会话目前提供只读回复，交互接管以 packet 为单位。
-
-会话账本存储为 v2，新引擎兼容旧 v1；旧引擎会拒绝 v2，避免忽略接管标记。配置的 `sessions.policy-version` 仍是 1，worker／lifecycle 协议不因此改变。
-
-## 发现运行与比较
-
-CLI 和桌面启动自动登记 run ID；会话投影保留多个已确认任务。登记位于全局配置旁的 `runs/`，可用绝对 `FLYWHEEL_RUNS_DIR` 覆盖。列表只读取明确登记，显示最近 100 项，不扫描整个磁盘；当前存活状态始终重新查询 Go。
-
-“运行记录”以列表选择运行，在相邻详情中查看操作种类、分支、HEAD、契约／配置条件、运行时长、新增尝试、失败尝试和交付。选择记录不启动任务，打开画布会重新读取当前状态。指标范围可选“仅此运行”或当前任务全部调用（包括早期记录）；对照运行仅用于比较条件，不会悄悄改变指标查询目标。指标先按 invocation／receipt 对账再汇总，迟到回执归属原调用，不重复计费。整组费用均缺失时显示“未报告”，不显示 $0。
-
-用量、费用和时延只表示已知量，缺失／部分数据单列，费用也可能来自配置单价估算。调用失败率不等于代码质量；条件不同的运行只并列展示，不伪称配对收益。完整的质量结论需要任务验收和独立 oracle。
-
-## 远端 PR 与 Merge
-
-在 PR 节点先查询项目与远端状态。远端操作需要 GitHub CLI 的正常登录，以及当前本地任务完成、候选仍有有效验收、明确的仓库／HEAD／目标分支授权。已记录的项目远端发生变化会拒绝交付；fetch 与 push URL 必须指向同一仓库。
-
-推送使用已批准的 commit 和明确任务分支，不强推，不隐式跟随 tags 或推送 submodules。可选择独立的远端任务分支，不必切换本地 checkout。推送后重新查询已有 PR，避免把预先创建的 Draft PR 误当成需要重复创建。
-
-合并再次核对 PR、源 HEAD、base 和检查状态，并使用 GitHub CLI 的 `--match-head-commit`。不使用 admin 绕过，也不擅自开启 auto-merge。仓库要求 merge queue 时，“请求已接收”和“已合并”分别记录，以远端回执为准。接口语义见 [GitHub CLI 文档](https://cli.github.com/manual/gh_pr_merge)。
-
-已确认的创建／合并操作重跑时先核对已有结果。命令失败或回执丢失保留 unknown，不猜测远端成功。PR／Merge 状态与引擎的本地完成分开；发布应绑定实际 merge commit 和发布产物重新验收，不因点击 Merge 自动发布 npm 或部署。
-
-配置面板另提供默认关闭的 **JEV 影子评估（可选）**；开关、数据发送边界与失败回退见 [JEV 指南](jev-shadow.md)。此项需要 0.30.1 CLI／插件。
-
-关闭自动 Worktree 管理而直接共享同一 checkout 的批次，会先等所有执行调用收尾，再对完整共同候选运行各任务的 L1 和独立 Review。变更按声明范围投影，批次范围外与禁止路径仍拒绝；这不证明具体进程的文件归属。任一返修改变共同候选，旧证据须重验。全部通过后统一提交，并在一次状态 CAS 中完成整组；保存失败不乐观报告部分完成。混合批次先交付共享目录，再重新验证并集成外部 Worktree。手动集成／终验不能绕过批次屏障，需“继续完整流程”。画布显示批次成员和上次错误。