@ckanner/flywheel 0.31.1 → 0.32.1

package/docs/zh-CN/flow-console.md

@@ -2,16 +2,14 @@
 
 [文档首页](../README.zh-CN.md) · [English](../en/flow-console.md) · 简体中文
 
-DSH 的 Flywheel 视图集中提供任务选择、流程阶段、配置、会话交互与交付。
+DSH 的 Flywheel 视图集中提供当前任务、流程阶段、配置、会话交互与交付。
 CLI、平台包和 DSH 插件应保持同一版本。安装步骤见[快速开始](getting-started.md)。
 
 ## 找到任务，不必填写路径
 
-画布先显示任务选择。当前 DSH 会话只有一个已登记任务时自动打开；有多个任务时选择其一。通过终端运行的任务在存在 DSH 会话 ID 时也会登记该标识；该标识只用于发现，不能授予控制权限。页面读取运行索引后再请求 Go 状态，不把索引当成仍在运行或已经完成的证明。
+视图自动跟随当前会话，没有任务选择器，也不要求填写路径。当前会话的显式工具关联优先；没有投影时，打开精确匹配会话 ID 的最新运行。其他会话与无归属记录不显示。索引仅提供身份，进度以 Go 状态为准；未确认操作仍锁定原目标。
 
-旧版本记录没有会话 ID 时，从“本机最近任务”选择即可；选择会发送只读状态查询，并保存到当前会话关联。刷新任务列表不会启动、重试或切换你手动选中的任务。读取失败保留已打开画布；未确认的操作仍先核对原任务。
-
-界面不再提供任务路径／项目路径输入框。助手与引擎提供实际位置；有值后显示为只读信息。项目工作区是原仓库的稳定归属，实际执行目录可以是任务集成目录或独立 Worktree，两者分开显示。任务文件夹保存说明、验收清单和进度。准备但尚未运行的任务由助手通过只读 status 关联，随后也能在列表中选择。
+项目工作区、任务记录、实际执行目录和分支有值后直接显示。准备中任务或独立终端任务需要在目标会话通过 `flywheel_control status` 显式关联。旧版 UI 自动生成的 status 命令记录不能建立新的关联。
 
 DSH Session 的原始项目目录保留为原仓库，运行时通过公开接口切换当前执行目录。桌面 Host 定期把 Flywheel SDK 会话登记到已有的匹配项目；读取实际任务状态时也会确保原项目已登记。不会把每个 packet Worktree 创建成新的桌面工作区，不修改旧 Session 的历史头部；旧会话只能按其真实目录归属。探测会话写入临时存储，退出后清理，不再污染用户会话列表。原生 Provider 在项目目录开会话，任务提示词明确列出实际执行目录；每次 shell／文件操作必须显式使用它。当前后端不能分离 `workspace-write` 沙箱根时，在派发前明确拒绝该组合，不自动扩大权限；完全权限及支持的只读模式保持其真实含义。
 
@@ -20,21 +18,21 @@ Skill 已加载不代表引擎已经启动。`flywheel-task` 准备适合的契
 | 对话入口 | 引擎是否启动 | UI 如何找到任务 |
 |---|---|---|
 | `/flywheel-new <需求>` | 只准备契约，等待审阅 | 助手在交付方案前调用只读 `status` 登记候选；未初始化时显示任务与位置，不显示执行进度 |
-| `/flywheel-run <任务目录>` | 启动或恢复已有任务 | 使用原任务路径启动并查询状态，关联当前会话；多个候选时选择对应任务 |
-| `/flywheel-task <需求>` | 准备后启动 | 通过 `flywheel_launch` 启动并关联，再核对状态 |
+| `/flywheel-run <任务目录>` | 启动或恢复已有任务 | 使用原任务路径启动并查询状态，关联当前会话；画布自动跟随显式关联 |
+| `/flywheel-task <需求>` | 准备后启动 | 调查使用受管调查控制，实现使用 `flywheel_launch`，随后查询状态关联 |
 
 `new → run` 与 `task` 使用同一个引擎，画布不专属于某个 Skill。仅写任务文件不会
 登记视图；关联查询失败也不能改用 launch 来“补出”画布。工具不可用时报告关联未确认；
-通过独立终端实际运行过的任务可从“本机最近任务”选择。
+无会话 ID 的独立终端任务需要在目标会话显式关联。
 
 画布可见时，每五秒刷新已登记任务；已观察为运行中的任务每两秒刷新状态，失败后
-延长到十秒。页面隐藏时跳过这些请求。刷新只读，不重放结果未确认的操作。
+延长到十秒。页面隐藏时跳过这些请求。刷新使用只读 Remote，不执行对话命令，也不新增聊天事件或 JSON。显式修改与未知结果核对仍保留持久命令回执；既有聊天历史保持原样。
 
 ## 本次阶段与完整流程
 
 `run.kind` 与 `control.kind` 一致的单阶段任务优先显示“本次运行”和真实回执。仅运行 Review 时，默认画布为 **L1 → Review**，并显示记录结论、评分及“整体交付尚未完成”；其它未运行阶段不会盖过这次评审结果。可切换“完整流程”查看全貌。
 
-“继续整个流程”移入明确的展开项；单阶段通过不自动启动后续阶段，也不把任务改为 completed。失败、取消和结果未知不会沿用旧绿色裁决。Run ID、HEAD 和配置摘要收在“运行记录与文件位置”，需要排查时再展开。
+“继续整个流程”在适用时直接显示；新任务启动选项只在尚无引擎状态时显示。阶段通过不会自动启动后续阶段或标记整个任务完成。失败、取消和结果未知不会沿用旧绿色裁决。Run ID、HEAD 和配置摘要在节点详情的“运行记录与文件位置”直接显示。
 
 ## 实施前的调查
 
@@ -50,34 +48,65 @@ Skill 已加载不代表引擎已经启动。`flywheel-task` 准备适合的契
 
 ## 配置
 
-在已进入对话视图的 DSH 会话中，Flywheel 排在“统计”之后；新会话的空白首页尚未显示这排会话视图。内部导航为“流程”“运行记录”“配置”。全局配置可在没有任务目录时编辑；项目配置写入所选 Git 项目根。任务配置仍具有最高优先级，取首个完整文件，不做字段深度合并。
+在已进入对话视图的 DSH 会话中，Flywheel 排在“统计”之后；新会话的空白首页尚未显示这排会话视图。主导航为“流程”“记录”，“设置”独立进入。全局配置可在没有任务目录时编辑；项目配置写入所选 Git 项目根。任务配置仍具有最高优先级，取首个完整文件，不做字段深度合并。
 
-打开“配置”后自动读取所选范围，不必先点击读取按钮。按“工作方式／模型分配／预算与重试／JEV 影子建议”编辑；有修改才出现相邻的“保存修改／放弃修改”。普通保存一次点击，首次开启 JEV 说明本地捕获与后续显式评估的发送边界。串行模式不显示并发数量；超时以分钟或秒编辑，并精确换算成引擎毫秒字段。
+打开“设置”后自动读取所选范围。分类为运行方式、模型与会话、预算与重试、JEV、高级与诊断；保存、撤销和恢复默认固定在底部，没有修改时禁用保存。保存一次点击，包括 JEV 唯一总开关；表单直接说明支持的决策能力与配置的数据范围。串行模式不显示并发数量；超时以分钟或秒编辑，并精确换算成引擎毫秒字段。
 
-“更多配置操作”提供重新读取和恢复安装版本默认配置。切换范围或重新读取会先提示未保存草稿；重置先载入待保存修改，保存时才替换文件。保存失败保留草稿，结果未知时先重新读取核对。Go 核对文件 revision、备份旧文件并原子写入。正在运行的引擎保留原快照，新配置在后续启动时加载。配置页显示真实文件与来源：文件按任务 → 项目 → 全局 → 安装默认选择，不逐字段叠加；尚未存在的配置文件以安装模板创建。
+重新读取、完整 JSON 编辑和环境检查位于“高级与诊断”。设置导航与内容分别约束高度，窄窗口导航 54px、按钮 36px（触控指针为 44px），内容变短也不会拉伸。离开设置、切换范围或重新读取会先提示未保存草稿；重置先载入待保存修改，保存时才替换文件。保存失败保留草稿，结果未知时先重新读取核对。Go 核对文件 revision、备份旧文件并原子写入。实现运行保留原配置快照，新模型配置在后续启动时加载；JEV 另在决策边界重核当前启用值和更严格权限，见 [JEV 恢复规则](jev.md#数据预算与恢复)。配置页显示真实文件与来源：文件按任务 → 项目 → 全局 → 安装默认选择，不逐字段叠加；尚未存在的配置文件以安装模板创建。
 
 支持的资源入口包括 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 也保留调用安全账本。
 
-可选的[JEV 影子评估](jev-shadow.md)默认关闭。启用后只捕获本地任务摘要，显式
-`shadow run` 才发送评估；建议不参与工作流策略选择。调查中的决策使用独立、显式
-的策略，见[有界调查指南](investigation.md)。
+[JEV 决策](jev.md) 只有一个默认关闭的总开关，开启后自动参与已支持的调查与失败后决策，包括批准的执行模型选择。
+配置检查只读展示配置状态，不再提供第二个开关。调查视图展示最近观察到的 JEV
+状态、已采用／基线动作，以及引用证据的跳过或提前报告记录；历史状态标签不冒充
+实时读取配置。这些取证效果不代表根因已被证明或代码已经完成。
+
+### 开关与调度策略
+
+JEV 使用唯一总开关；“运行方式”中，自动管理任务 Worktree 和提前准备 DSH 评审
+运行环境各有独立开关。每个开关都有对应标签、可见的开启／关闭文字，以及原生
+checkbox 的键盘行为。切换先修改草稿，点击“保存修改”后才写入所选范围；不再有
+第二个 JEV 确认或逐任务启用入口。
+
+并行派发仍是两项策略选择：“整批处理”等当前批次完成，“就绪队列”在 Execute／L1
+空位出现时补入另一个满足条件的独立任务。表单保留所选策略，并解释尚未满足的配置
+条件；不会声称未来任务一定是 Full 或已有独立工作。就绪队列要求 Full、并行、
+并发上限大于 1 且自动管理 Worktree。提前准备独立于 JEV，只初始化支持的 DSH
+Review SDK，正式准入前不创建 Session、不发送模型 prompt。默认仍为整批处理、
+预热关闭，详见[调度与 Worktree](configuration.md#调度与-worktree)。
+
+自动管理 Worktree 表示引擎管理任务目录；关闭不会删除已有目录，也不禁止外部
+管理的 Worktree。JEV 数据边界及关闭对当前任务的影响放在字段旁说明。关闭 JEV 或切为串行
+会放弃因此隐藏的无效输入草稿，保留最后有效值；其他分组的错误仍须修正。高级
+JSON 中检测到的非法字段保留在原编辑器中，需要修正后才能保存；完整配置仍由
+Go 最终校验。合法连接、
+Provider 并发额度、显式空数据许可、角色策略和预算不会随无关开关一起重置。
+草稿、过期 revision 和保存结果未知继续受原有保护。
+
+### 会话默认与阶段覆盖
+
+运行方式设置默认 fresh/scoped；模型与会话表允许各角色继承或独立覆盖。Execute 路由共用角色策略，每个子任务仍有独立会话。Kimi Plan 的旧历史开关在显式选择时同步，继承时保留原值。节点显示真实 Session ID、动作与原因，不用配置值推测是否实际续接。
+
+### 可选用量预算
+
+预算分关闭、仅提醒、达到后停止三档。关闭后不显示 Token 门限，继续记录用量；仅提醒不会因此停机，严格预算在达到额度或用量无法确认时阻止新调用。额度按单个任务、UTC 日期统计，留空不设限。运行保护独立设置超时与传输重试，Provider 自身额度不受该开关改变。界面展示实际配置，不自动把既有 soft 改为 off。
 
 ## 横向画布与节点操作
 
-主线从左到右展示 Plan／拆分、调度、任务分支、汇总与终验、PR 与 Merge。点击节点打开视图内详情，按“进展／会话／本次配置”查看，不挤到画布下方。点击“展开任务画布”进入 Execute、L1、Review、Git 交付子图；汇总和远端交付也可展开阶段。状态配合颜色和文字，运行与节点详情使用真实项目／worktree、分支、HEAD、run ID、调用绑定和失败证据。
+主线从左到右展示 Plan／拆分、调度、任务分支、汇总与终验、PR 与 Merge。点击节点打开视图内详情，结果、处理按钮、配置快照和角色会话直接显示，不挤到画布下方。原始证据与人工会话交互各有明确入口。点击“查看任务流程”进入 Execute、L1、Review、Git 交付子图；汇总可进入阶段流程，PR 与 Merge 分开显示。状态配合颜色和文字，运行与节点详情使用真实项目／worktree、分支、HEAD、run ID、调用绑定和失败证据。
 
 画布占满插件可用宽度，支持双向拖动、缩放、适合宽度、定位当前步骤、分页与列表切换。新快照保留视角与选择；定位可跳到当前执行任务所在分页。大任务使用有界诊断摘要；“读取完整节点证据”按需加载选中节点，revision 与同一时刻的画布状态一起刷新。摘要不会改写原始账本。
 
 “专注画布”在插件拥有的原生对话框中扩大画布，退出或按 Escape 回到原视图，不启动或停止任务。它不修改 DSH 的全局布局或宿主输入区；操作结果未知时退出专注视图，显示原调用的核对入口。
 
-运行节点前显示作用范围，确认绑定已观察的状态版本；状态变化后旧确认不可提交。失败任务的“重试一次”需要填写原因，已完成任务显示“重新执行”并说明证据失效范围。独立 Review 在当前 L1 未通过时不可运行。PR 尚未查询、已关闭、已合并分别显示，不把关闭的 PR 当作合并成功。
+普通节点操作一次点击提交当前状态版本。失败任务的“修复并重试”记录控制台手动请求，仅追加一次执行与 L1；不生成虚构的失败原因。已完成任务的“重新执行”仍要求填写原因并确认下游证据失效范围；确认期间状态变化后旧确认不可提交。独立 Review 在当前 L1 未通过时不可运行。PR 尚未查询、已关闭、已合并分别显示，不把关闭的 PR 当作合并成功。
 
 | 操作 | 含义 |
 |---|---|
 | 运行此阶段 | 提交已观察的 revision；Go 在任务租约内重新检查前置条件 |
-| 人工继续一次 | 填写原因，追加一次 Execute／L1 尝试；保留累计失败和预算 |
+| 修复并重试 | 记录显式点击来源，追加一次 Execute／L1 尝试；保留累计失败和预算 |
 | 已完成单元重跑 | 归档旧证据和提交回执，使当前与后续单元的候选证据失效 |
 | Git 交付 | 只在当前 L1 与独立 Review 通过后持久化当前单元 |
 | 终验 | 已集成单元的 L2／L3 与独立 Judge；不重新调用 Plan 或启动未完成单元 |
@@ -95,7 +124,7 @@ Quick 在 UI 中显示为 ultraWork／Quick；它仍要求确定性验证和独
 配置入口为 `scheduler`，字段和边界以 `flywheel template scheduler-policy.schema.json` 为准。例如：
 
 ```json
-{"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1}}}
+{"scheduler":{"mode":"parallel","max-parallel":2,"providers":{"deepseek-account":1},"dispatch":"batch","prewarm":false}}
 ```
 
 `providers` 的键是实际配置渠道名。示例使用内联模板的 `deepseek-account`；绑定使用 `deepseek-account-sdk` 时应改用后者。并行资格来自冻结 packet 的声明，而不是模型临时口头建议：
@@ -108,6 +137,21 @@ schedule:
 
 依赖必须指向较早编号的已知 packet；写入范围是规范相对路径／目录前缀，不支持通配符或越出项目的路径。声明要覆盖实现、普通测试和必要配置，并考虑共享测试服务等真实依赖。未声明独立性、写入范围冲突或需要 live 凭证的单元保留串行。
 
+### 派发策略与运行时准备
+
+配置编辑器还提供 `scheduler.dispatch` 和 `scheduler.prewarm`，默认分别为
+`batch` 与 false。选择 `ready-queue` 后，自动管理 Worktree、并行上限大于 1 的
+Full 任务会在 Execute／L1 槽位释放时补入剩余独立 packet。Review、重规划和集成
+仍等待全部已派发 worker 停稳；共享 checkout 保持 batch 派发。
+
+预热会在串行 packet 的 Execute 后确定性检查期间，初始化一个 DSH Review
+runtime；正常 Review 准入前不发送模型 prompt。并行 Execute／L1 lane 和共享
+候选不预热，独立并行组停稳后的串行 Review 路径才可开始准备。其他 harness
+保持冷启动，未使用 runtime 也须完成有界清理。这两个设置不改变 JEV 总开关、
+任务资格或完成门禁，
+保存后在下次启动生效。适用条件、恢复约束和独立的真实性能验收见
+[配置指南](configuration.md#就绪队列与运行时准备)。
+
 ### 执行目录
 
 “配置 → 工作方式 → 自动管理任务 Worktree”默认开启，对应 `worktree.enabled`。它只控制引擎自动创建／管理目录，不是“允许使用 Worktree”开关，也不控制能否并行。新安装默认配置为 `scheduler.mode=parallel`、最大并发 2；已有完整配置缺少 `scheduler` 时仍串行，显式 serial 也保留。并行且自动管理时要求独立 worktree，创建失败即停止；旧串行路径可以记录原地执行回退。关闭自动管理后，可以在任务 checkout 并行，也可以由模型或用户自行选择 Worktree。共享目录没有文件隔离保证，写入范围冲突、候选变化和验收失败仍如实停止，不能把并发操作当作隔离证据。
@@ -137,13 +181,20 @@ flywheel session '/absolute/task-worktree/docs/task-slug' --key 'execute/M01-T01
 
 “验证并交回”重新运行 L1、适用的 Quick gate 和独立 Review；人工回复本身不是通过证据。Go 保存绑定当前候选的 `human-takeover` 来源，后续正常交付仍由引擎完成。“退出接管”不声称验收成功；结果或清理未知时也不能借此解除阻断。里程碑会话目前提供只读回复，交互接管以 packet 为单位。
 
-会话账本存储为 v2，新引擎兼容旧 v1；旧引擎会拒绝 v2，避免忽略接管标记。配置的 `sessions.policy-version` 仍是 1，worker／lifecycle 协议不因此改变。
+这个交回入口要求已有符合条件的受管 Session，不导入任务开始前任意写好的一版
+补丁；依次运行 Verify 和 Review 也不会补造来源证据。通用的已有候选接纳入口仍是
+独立工作。
+
+引擎支持会话账本存储版本 1、2、3。人工接管至少需要 v2；首次运行时预热记录 v3，
+让旧引擎拒绝无法理解的清理责任，后续接管不会降回 v2。配置的
+`sessions.policy-version` 仍是 1，worker／lifecycle 协议独立。
+[恢复指南](session-recovery.md#dsh-预热运行时的重启核对)说明中断准备后所需的原始清理回执。
 
 ## 发现运行与比较
 
 CLI 和桌面启动自动登记 run ID；会话投影保留多个已确认任务。登记位于全局配置旁的 `runs/`，可用绝对 `FLYWHEEL_RUNS_DIR` 覆盖。列表只读取明确登记，显示最近 100 项，不扫描整个磁盘；当前存活状态始终重新查询 Go。
 
-“运行记录”以列表选择运行，在相邻详情中查看操作种类、分支、HEAD、契约／配置条件、运行时长、新增尝试、失败尝试和交付。选择记录不启动任务，打开画布会重新读取当前状态。指标范围可选“仅此运行”或当前任务全部调用（包括早期记录）；对照运行仅用于比较条件，不会悄悄改变指标查询目标。指标先按 invocation／receipt 对账再汇总，迟到回执归属原调用，不重复计费。整组费用均缺失时显示“未报告”，不显示 $0。
+“运行记录”仅列出当前关联任务的运行，以列表选择具体运行，在相邻详情中查看操作种类、分支、HEAD、契约／配置条件、运行时长、新增尝试、失败尝试和交付。选择记录不启动任务，打开画布会重新读取当前状态。指标范围可选“仅此运行”或当前任务全部调用（包括早期记录）；对照运行仅用于比较条件，不会悄悄改变指标查询目标。指标先按 invocation／receipt 对账再汇总，迟到回执归属原调用，不重复计费。整组费用均缺失时显示“未报告”，不显示 $0。
 
 用量、费用和时延只表示已知量，缺失／部分数据单列，费用也可能来自配置单价估算。调用失败率不等于代码质量；条件不同的运行只并列展示，不伪称配对收益。完整的质量结论需要任务验收和独立 oracle。
 

package/docs/zh-CN/getting-started.md

@@ -20,7 +20,9 @@
 | DSH SDK profile 中的 DeepSeek 和 ChatGPT provider | 默认执行、独立 Review 与 Judge |
 | Go 1.27 或更高 | 仅本文 Go 示例与源码构建需要，npm 二进制安装不需要 |
 
-插件声明兼容 DSH `0.2.1-rc.5`、`0.2.2-rc.1` 和 `0.2.2-rc.2`。DSH 0.2.2 自身要求 Node 24.9
+插件使用 DSH `>=0.2.1-rc.5 <0.3.0-0` 范围，包含 0.2 系列内的后续预发布版本。
+常规 rc／补丁升级不再逐版本追加白名单；0.3 系列及其 alpha／beta／rc 需要重新核对兼容性。
+版本准入不会绕过必需的宿主服务或 SDK 权限／清理检查。DSH 0.2.2 自身要求 Node 24.9
 或更高，应使用官方桌面附带的 CLI。安装前核对实际命令位置与版本：
 
 ```sh

package/docs/zh-CN/investigation.md

@@ -7,7 +7,7 @@ Task 是推荐的目标入口。它先区分交付终点，再准备适合的契
 
 | 日常需求 | 推荐入口 | 引擎行为与终点 |
 | --- | --- | --- |
-| “先排查，告诉我原因” | `/flywheel-task` | 受管读取／搜索、证据报告；不实施修改 |
+| “先排查，告诉我原因” | `/flywheel-task` | 受管取证与已批准的诊断实验、证据报告；不实施修改 |
 | “排查并在原范围内修好” | `/flywheel-task` | 调查有支持结论后准备 Spec，继承来源、用量和范围，再 Auto |
 | “问题已定位，快速修复” | Task Auto 或显式 Quick | 资格成立才走紧凑流程；必需验证、独立最终 Review、Git 交付保留 |
 | “复杂任务先出方案，我们审阅” | `/flywheel-new` | 准备方案后停止；获得后续实施授权再 Run Full |
@@ -27,23 +27,77 @@ Kimi 使用对应 `/skill:flywheel-*` 名称。Status、Stop 均可用于调查
 动作与预算。`intent` 为 `investigate` 或 `investigate-and-fix`；后者需要非空的
 `implementation-scope`，前者不允许带实施授权。只存在准备记录时，尚不需要 Spec。
 
-首个可采用动作族由 Go 直接实现：
+取证动作由 Go 执行，模型只能选择契约中已经批准的候选：
 
 | kind | 参数与能力 | 限制 |
 | --- | --- | --- |
 | `read_file` | 读取一个已授权 UTF-8 文件 | 拒绝符号链接、特殊文件与超限输入 |
 | `search_text` | 在一个已授权文件中查找字面量，返回行号 | 非正则，无命令拼接 |
 | `list_files` | 列出一个已授权目录的名字 | 不递归读取内容；最多 4096 个名字 |
+| `run_command` | 在批准输入的临时副本中运行精确 argv，收集复现或诊断结果 | 显式 `host-process` 授权、独立时限、受控环境、进程组取消与收尾 |
+| `http_read` | 对明确 URL 发出 GET 或 HEAD 查询 | HTTPS（loopback 测试可 HTTP）、无重定向／环境代理、固定响应与输出上限 |
 
-路径必须是干净的仓库相对路径，动作必须引用允许路径和已有假设。打开的文件还须与
-检查时的 inode 一致；`os.Root` 限制目录穿越。目录授权只授予名字读取。首版没有
-任意 shell、外部查询、生产重启、清缓存、数据回填或可写 Agent 调查动作。现有
-full-access 配置不改变这些 Go 动作的能力。更广实验需要独立增加处理器、契约和验证。
+文件路径必须是干净的仓库相对路径，文件动作必须引用允许路径；所有动作都引用已有
+假设。打开的文件还须与检查时的 inode 一致；`os.Root` 限制目录穿越。目录授权只
+授予名字读取，不隐式授予其后代内容。命令和 HTTP 参数属于冻结契约，JEV 不能生成
+新的命令、URL 或凭据变量。
 
 `limits` 冻结动作次数、总时限、单文件字节和总输出字节；恢复不重置。总时限以首次
 准备的 deadline 为准，暂停时间也会消耗这个时限。只保留有界 UTF-8 输出，另存内容
 摘要；`truncated` 表示展示不完整，不能把片段当成完整日志或完整测试集合。
 
+### 复现测试与诊断命令
+
+`run_command` 使用 `command.argv`，不经过隐式 shell。`command.inputs` 是精确批准
+的普通文件列表，必须属于契约 `read-paths`；程序为每次调用复制这些输入，保留相对
+目录结构和执行位。输入最多 32 个 UTF-8 文件，仍受契约文件与输出上限限制；目录
+不会自动递归复制。这适合有界的小复现。命令在副本中运行，原文件不会由副本写入
+自动覆盖。示例动作片段如下，
+其中路径和假设 ID 应替换为当前契约实际批准的值：
+
+```json
+{
+  "id": "reproduce-timeout",
+  "kind": "run_command",
+  "purpose": "在隔离输入上复现已观察到的超时",
+  "hypotheses": ["timeout"],
+  "command": {
+    "argv": ["/usr/bin/python3", "tests/reproduce.py"],
+    "inputs": ["tests/reproduce.py", "src/settings.py"],
+    "env": [],
+    "timeout-ms": 30000,
+    "expect-exit": 1,
+    "execution-boundary": "host-process"
+  }
+}
+```
+
+`host-process` 明确表示进程以当前用户的真实主机权限执行。副本隔离保护正常相对
+写入不进入原工作区，**不提供操作系统沙箱或网络隔离**。应基于原任务授权批准具体
+程序和参数；现有 full-access 或 JEV 开关不能代替这项动作授权。`env` 只写需要传入
+的环境变量名，不把密钥值放进契约。命令可以记录预期的非零退出码，以便把已复现的
+失败作为证据；超时、取消、信号、输出截断和收尾错误不能冒充正常预期退出。
+预期非零退出虽可形成有效的复现观察，也不作为跳过剩余取证或提前结束的充分依据。
+
+观察中的 `execution` 记录实际退出／信号、超时、取消、输入摘要及副本清理状态。
+`removed` 表示副本已清理；`retained` 表示保留现场等待核对；`not-created` 表示没有
+创建副本。进程结果或清理未知时保持原调用 pending、阻断后续动作；恢复只读原回执，
+不会再执行一次命令猜测结果。
+
+### 明确批准的外部查询
+
+`http_read` 的 `http` 对象包含 `url`、`method`（GET／HEAD）、`headers-env`、
+`timeout-ms`、`max-bytes` 和 `expect-status`。例如一个已批准的健康检查可以使用
+`headers-env: {"Authorization": "INCIDENT_STATUS_AUTH"}`；变量提供完整头值，配置
+和回执不保存其秘密值。URL 必须是精确授权的地址；不跟随重定向、不使用环境代理，
+不允许 URL 内嵌凭据。Go 限制请求时长与读取字节，并记录实际 HTTP 状态和输出摘要。
+允许一个 GET／HEAD 不等于批准任意服务、生产重启、清缓存或数据修复。
+
+命令／HTTP 的退出码、状态、完整性等结构化结果属于 `diagnostic-facts`，默认允许
+用于决策。原输出只有在明确允许 `logs` 后才作为有界片段附加；未允许时记录内容
+缺失，JEV 仍可根据结构化事实选择。文件取证仍为 `source`。批准动作不自动增加
+发送原始日志的权限，数据类别允许也不能替代对秘密值的保护。
+
 ## CLI 与桌面控制
 
 准备实际目录后，提交一个包含完整契约的请求文件：
@@ -66,7 +120,8 @@ flywheel control investigate --task-dir "$task_dir" --cwd "$repo_dir" < start-re
 `revision` 必须取实际回执。Go 按原任务运行 lease 启动后台调查，复用已有就绪与
 token 绑定的停止协议。DSH 使用 `flywheel_control` 的 `action: investigate` 和
 嵌套 `investigation` 请求，会关联当前会话视图；不需要手填路径。视图显示预算、
-观察、截断、决策回执及报告，提供继续、核对回执、停止和刷新。
+观察、截断、命令退出码／HTTP 状态、取消与副本收尾、决策回执及报告，提供继续、
+核对回执、停止和刷新。
 
 ```bash
 flywheel control status --task-dir "$task_dir" --cwd "$repo_dir"
@@ -103,6 +158,11 @@ Quick → Full 或允许模型升级不会增加权限。
 
 执行提示词鼓励先跑相关的小检查；Go 仍在当前候选上执行冻结的完整验收，之后才
 独立 Review。这样去掉固定重复的全量验收要求，而不是缓存或省略最终门禁。
+Packet 可用与验收命令相同的 `cmd`／`expect` 结构声明最多八项已批准的短
+`feedback-checks`，帮助局部复现，不改动最终验收。JEV 开启后，引擎可选择一项
+这样的检查，或在已确认失败后重新执行对应 L1 检查。供 JEV 选择的短检查还须填写
+1–160 字符的非空白 `purpose` 用途说明；没有用途说明的条目仅供 Executor 参考。
+JEV 候选发送用途说明，不附加 `cmd`／`script` 文本；说明本身也不要含密钥或原日志。
 
 反馈保留固定 check ID、期望和实际终态、候选／检查集／环境摘要、完整失败输出摘要，
 以及有界的头尾片段。`observationComplete` 只说明命令结果完整，不说明测试枚举完整。
@@ -114,61 +174,29 @@ Full 首次 Plan 后，只有已确认终态、合法重载契约、成功持久
 显式 Plan 或 verification-gap 都重新规划。Plan 的价值是消除真实不确定性，速度快
 不构成删除规划或降低质量门禁的理由。
 
-## 可选 JEV
+## JEV 决策
 
-新 `decision` 配置与旧 `jev-shadow` 完全独立，省略时不发送请求。具体配置字段由
-准备 schema 定义，包含固定 `jev-x.y.z` 模型、显式 endpoint、密钥环境变量名、超时、
-策略版本、模式、数据允许集合、阈值与最大调用数。凭据值不写契约。
+使用 [JEV 指南](jev.md) 中唯一的 `jev.enabled` 设置。Start 自动解析配置并冻结
+策略，Task／New／Run 不再各自维护决策模式。默认关闭时沿用原动作顺序和收集
+限制；开启后可选择下一项动作、跳过冗余取证，或在满足 Go 证据前提后提前转入报告。
 
-- Off／offline 不联网；shadow 只保存可审查快照；advisory 只留建议；adopt 才允许选择
-  一个已批准的诊断动作。自动采用仍需独立实验政策，阈值不是本项目准确率保证。
-- 至少两个合法选项与真实语义不确定性才值得调用；单个请求配对 Noul 适用性与 Choice，
-  保留完整概率。没有适用选项、模型版本不符、证据字段未授权、预算不足或未知执行都弃权。
-- 采用前重新检查任务／run／revision、契约、候选、观察及动作绑定；将回执消费和唯一
-  action invocation 在同一 CAS 中保存后派发。JEV 不能生成命令、减少验收或宣布完成。
-- 可选请求未知时不重发，保留未知用量，转合法确定性基线。实际动作回执未知则 blocked。
-  结束、取消或 deadline 到期仍只读核对可选请求，不能留下无法结束的 pending 记录。
-- 最大调用数包括 unknown。硬预算没有可实施的单次消耗上限时跳过 JEV；不会用字符数
-  估计冒充可靠预留。shadow 研究与在线采用的费用和作用不同。
+跳过动作和提前结束收集均保存决策及观察引用，不会把假设自动标成已证明或已反驳。
+分析者仍要形成有证据的报告；修复仍须遵守原范围及普通验证、review 流程。
+`awaiting-report` 后重复 Run 不会重新开始收集。
 
-旧工作流影子开关仅捕获本地有界摘要，后续显式 `shadow run` 才请求服务；它不能采用
-动作，也不授权新增源码／日志发送。新动作族的离线和影子评估不能证明采用后更快。
-采用是否划算应比较既有基线、核心改进无 JEV、核心改进加单动作族三个版本的完整任务。
-
-### 离线重放与显式 advisory 评估
-
-通用决策的 `*.snapshot.json` 捕获文件包含冻结的 `snapshot`、`policy` 和来源
-`target-hash`，与旧工作流 shadow 数据集不同。真实评估前先审阅事实与数据权限。
-
-```bash
-flywheel decision replay --input frozen.snapshot.json --response native-response.json \
-  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
-```
-
-`replay` 接受已记录的原生 System One 响应或 fixture，强制 `offline`；不读取密钥、
-不发送 HTTP、不写账本或任务状态。endpoint 和相同的固定模型版本只标明评估目标，
-上面的版本是示例，必须与待评估响应相符。裸 Snapshot JSON 还须指定
-`--policy reviewed-policy.json`。捕获文件也可用该参数完整替换策略；替换策略省略的
-数据权限不会从原捕获策略继承。
-
-明确授权的真实评估使用独立命令：
-
-```bash
-flywheel decision evaluate --input frozen.snapshot.json --policy reviewed-policy.json \
-  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0 \
-  --directory ./decision-evaluation --key-env MEROUTER_API_KEY --max-calls 5
-```
+调查移交实施后，同一个开关还控制失败后的下一步：继续修复、运行已批准的反馈
+检查、请求重新规划，以及在允许的执行绑定中选择模型／effort。它们共用任务决策
+额度，保留调查已经消耗的次数，不因换 packet、重规划或恢复而清零。反馈检查是
+补充事实，不能代替后续完整验收。具体候选与状态语义见 [JEV 指南](jev.md)。
 
-即使来源策略为 `adopt`，`evaluate` 也强制 `advisory`。密钥环境变量名、固定目标、
-独立私有账本和累计调用上限都须明确指定。来源策略的数据类别权限必须覆盖快照；
-不会借旧 shadow 开关扩大权限。`--hard-budget` 因原生 API 不能强制请求用量上限而
-跳过调用。同一账本和快照只读取原回执；未知请求计入上限且不重发。命令不执行动作、
-不改变任务状态。
+目标、模型、数据类别、阈值和预算在创建准备记录时冻结。当前关闭、目标不再相容
+或收紧策略会停止后续可选决策；请求返回后、采用前仍要复核。已知／未知回执继续
+核对，不重发。创建时关闭的准备记录保留原基线路径，新准备记录才采用新开启的
+策略；桌面对持久状态明确标注“最近观察到的状态”。
 
-两种命令都输出基线、实际策略、概率和回执，并明确 `adopted: false`。真实调用错误
-或未知返回退出码 3 和回执；输入／配置错误为 1，发送前取消为 143。离线重放通过只
-证明解析与 fixture 行为，不证明模型实际成功率。任务中有限采用仍须独立准备策略、
-数据 opt-in、冻结的 Go 具体动作和上述当前状态校验。
+离线回放和显式在线评估见 [JEV 指南](jev.md#离线回放与显式评估)。关闭 JEV 仍可
+本地回放；在线评估必须服从同一已启用的总开关和配置目标，其数据与次数限制不能
+放宽配置。两种工具均不执行动作、不修改任务状态。
 
 ## 度量与当前边界
 
@@ -177,6 +205,9 @@ flywheel decision evaluate --input frozen.snapshot.json --policy reviewed-policy
 缺少结束、时钟倒退、无法关联的旧调用单列，Provider 内部排队／模型／工具细分保持
 unknown。调查动作和调查运行使用同一阶段接口，宿主准备对话的不可观察时间不补零。
 
-本实现没有基于这些离线测试宣布 token、更低成本或最终质量相同，也没有开启新默认
-模型、JEV、预热或更高并发。ready queue、持久 worker、已有候选导入等继续按测量结果
-决定；现有取消、共同候选复验和持久化规则保持有效。
+本实现没有基于这些离线测试宣布更少 token、更低成本或最终质量相同。JEV 仍默认
+关闭，明确开启总开关才参与已支持的决策；默认模型和并发设置不变。
+[就绪队列与有界 DSH 运行时准备](configuration.md#就绪队列与运行时准备)已可通过
+scheduler 显式配置，缺省仍为 batch／不预热。真实收益和是否调整默认值继续等待
+测量。长期驻留 worker、通用外部补丁导入仍是独立工作；已有受管 Session 接管／
+交回路径继续遵守原恢复、候选复验和持久化要求。

package/docs/zh-CN/jev-shadow.md

@@ -1,79 +1,5 @@
-# 可选 JEV 影子评估
+# JEV 指南已迁移
 
-[文档目录](../README.zh-CN.md) · [English](../en/jev-shadow.md) · 简体中文
+[English](../en/jev-shadow.md) · [简体中文](../zh-CN/jev-shadow.md)
 
-本页介绍可选的工作流影子实验：先在本地保存有界任务摘要，再由显式命令评估，不决定生产任务的实际模式。
-日常使用先阅读[工作流指南](workflow.md)；需要为配置的 endpoint 收集比较证据时，
-再启用影子评估。
-
-## 开关与行为
-
-JEV **默认关闭**。旧配置不含 `jev-shadow` 也等同关闭：不读 JEV 密钥、不发请求、不写影子记录，仍按原来的 Go 规则选 Quick／Full。它不是编排器必需的依赖。
-
-桌面进入 **Flywheel → 配置**，选择全局或项目范围，再打开 **JEV 影子建议**。
-配置会自动读取；核对 endpoint 后保存。也可将下面的片段合并到实际生效的完整
-`flywheel.config.json` 中：
-
-```json
-{
-  "jev-shadow": {
-    "enabled": false,
-    "endpoint": "https://merouter.play.one2x.ai/v1/systemone",
-    "model": "jev",
-    "expected-model": "jev-1.14.0",
-    "key-env": "MEROUTER_API_KEY",
-    "timeout-ms": 5000
-  }
-}
-```
-
-公用模板不预置某个组织的 endpoint。密钥只放在环境变量中，配置填变量**名称**。本地捕获不读取密钥；执行显式 `shadow run` 的进程必须能继承该变量。不要把密钥填进 endpoint 或模型字段。
-
-配置仍按任务 > 项目 > 全局 > 内置选择一个完整文件，不跨文件合并。`config inspect --json` 和桌面配置编辑器可检查所选文件。保存影响下次启动，不追改运行中的进程。可以随时关闭，已有实验记录保留。
-
-开启后，在私有目录保存新任务的目标、需求／验收描述和规划依据摘要，供后续审阅和标注；主任务不向 JEV 发请求。不会读取源码、diff、运行日志或 Provider 对话。会去除 URL 和常见用户目录前缀，并拒绝常见密钥模式；这不能保证任意业务文本无敏感信息，显式发送前仍需审阅。旧开关不授权新增数据类别，也不授权自动采用诊断建议。
-
-| 情况 | 行为 |
-|---|---|
-| 开关关闭／旧配置缺省 | 原流程，零 JEV 请求 |
-| 新任务首次普通 `run`／桌面启动 | 原模式先保存；仅持久化本地摘要和目标，不读密钥、不请求 HTTP、不启动后台 goroutine |
-| 恢复、重试、单阶段操作 | 不补写观察快照 |
-| endpoint 无效、摘要不合格、记录故障 | 提示跳过；主流程继续，实际模式不变 |
-| 显式 Full 或结构条件不允许 Quick | 摘要保留确定性阻断，后续显式实验也不调用模型放行 |
-| 硬预算任务 | 可保存本地摘要；自动捕获不产生 API 用量 |
-| 用户停止任务 | 跳过捕获，沿原规则停止任务，不能吞掉停止信号 |
-
-即使 JEV 建议 Quick，实际 Full 也不会降级。影子评估不改模型路由、权限、Session、验收、PR 或 Merge 门禁。每次请求的用量与耗时独立记录，不混入主任务预算，不把缺失用量当零，不承诺账单节省。
-
-## 实验与报告
-
-自动捕获保存到 `~/.config/flywheel/shadow/<目标摘要>/<输入摘要>/`，目录 0700，文件 0600。日志会给出具体目录。`cases.json` 为有界摘要；`target.json` 固定 endpoint、模型、问题和策略。尚未显式评估的案例在报告中为未运行；后续 `shadow run` 自己管理生命周期和独立调用预算，再追加原始概率、建议、实际基线、响应版本及用量。只有派发意图而没有终态时保持 unknown，同目录不会重发；更换目录意味着显式新实验。
-
-使用提供 `shadow prepare|run|report` 命令的 Flywheel 版本：独立实验是显式操作，即使自动开关关闭仍可使用；它不会启动或改动任务。
-
-```bash
-# 为尚未运行或已停止的任务准备摘要，先审阅文件内容。
-flywheel shadow prepare --task-dir docs/my-task > /tmp/jev-cases.json
-
-# 显式发送已审阅摘要；环境变量 MEROUTER_API_KEY 由你自己的环境提供。
-flywheel shadow run --input /tmp/jev-cases.json \
-  --directory /tmp/my-jev-experiment \
-  --endpoint https://merouter.play.one2x.ai/v1/systemone \
-  --max-calls 20 --timeout 5s
-
-# 离线报告；不需要密钥或网络。
-flywheel shadow report --input /tmp/jev-cases.json \
-  --directory /tmp/my-jev-experiment
-```
-
-自动捕获的报告把 `--input` 指向对应目录的 `cases.json`。要补标签，请复制摘要到另一个文件再编辑 `label`：`mode: quick|full`、`status: provisional|confirmed`、`author`、`reason`。标签不发送模型，也不改变预测缓存。别修改自动目录里的原始摘要。
-
-数据集最多 100 项、1 MiB；单请求最多 64 KiB；显式命令的 `--max-calls` 为 1–100，单次 `--timeout` 最多 30 秒。新请求超过上限时整批拒绝。HTTP 不重定向、不重试，不记录错误响应正文。输入错误退出 1；含失败、unknown 或未运行项退出 3；用户取消退出 143；成功报告退出 0。`prepare|run|report` 的 stdout 均为单份 JSON，错误写 stderr。
-
-## 如何解释结果
-
-第一版只使用 8 个有具体判断标准的 Noul 问题。正向概率都 ≥0.8、风险概率都 ≤0.2 才给 Quick 候选；任一风险 ≥0.8 给 Full；其余 abstain。问题、阈值和版本写入 manifest，不把 Noul 概率包装为“整体正确率”。响应版本必须符合 `expected-model`；MeRouter alias 升级时会弃权，需显式审查后改固定版本。
-
-这些阈值来自初步实验，**尚未生产校准**。报告将决策时快照、准备快照、旧任务回放、历史摘要和合成样本分别统计；旧任务当前模式不一定是最初的 Auto 决策。人工标签缺失或 provisional 时，不报告已校准误放率。现有 Auto 已使用准备阶段的契约事实，影子调用是新增费用，不能宣称省掉了一次原本不存在的分类调用。
-
-第一批[六个历史工作项](../evaluation/jev-historical-provisional.json)引用已完成提交，实际模式均标 unknown，人工标签为 provisional。它适合验证接口和找反例，不能证明生产收益。升级为真正自动工作流路由前，需要独立确认的决策时样本、误放率与弃权率评估；当前没有 JEV Quick／Full 路由开关。独立的有界诊断决策政策不能继承本实验的权限或阈值。
+当前行为见 [JEV 决策指南](jev.md)：统一 `jev.enabled` 总开关、实际调查采用、依据证据调整取证和评估工具。旧的自动影子观察器与独立请求客户端已经移除。历史结果保留在[原验收记录](../validation/2026-11-10-jev-shadow.md)。