@ckanner/flywheel 0.30.2 → 0.31.1

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

@@ -0,0 +1,352 @@
+# 快速开始
+
+[文档首页](../README.zh-CN.md) · [English](../en/getting-started.md) · 简体中文
+
+先安装 Flywheel，配置实际要使用的后端，再运行一个小任务。本文对应当前仓库，安装时
+应核对所选 npm 版本与本机版本；源码合并不会更新已有安装。CLI、平台包和 DSH 插件
+须保持同一版本。
+
+任务分支、契约与 PR 审阅的完整流程见[工作流指南](workflow.md)。
+
+## 1. 准备运行环境
+
+| 依赖 | 用途 |
+|---|---|
+| Git，已配置提交身份 | Worktree 与本地交付提交 |
+| Node.js 22.18.0 或更高，npm | 安装器、启动器及 JavaScript worker |
+| DSH Mac 及桌面附带的 `dsh` 命令 | 桌面插件管理与 DSH SDK 执行 |
+| 已登录的 Kimi CLI | 默认 Full Plan、frontend 执行及可选 Garden |
+| Codex 程序及已有登录 | hard 执行路由通过 Codex Pro 运行 Codex app-server |
+| 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
+或更高，应使用官方桌面附带的 CLI。安装前核对实际命令位置与版本：
+
+```sh
+git --version
+node --version
+npm --version
+command -v dsh
+dsh --version
+kimi --version
+codex --version
+```
+
+各后端沿用自己的安装和登录流程。Flywheel 不替用户登录、复制凭证或替换桌面程序。
+Full 需要所配置的 Plan／Execute／Review／Judge 后端；合格 Quick 需要实际执行路由
+和独立最终 Review，升级为 Full 后才需要额外阶段。未使用的执行路由不成为该任务的
+运行前提。
+
+Claude 为可选后端。选择 `claude-code-pro` 时，还需在 worker 能解析的依赖树中安装
+匹配的 0.4.0 配套包，并准备已登录的 Claude CLI，详见[Claude Code Pro](claude-code-pro.md)。
+
+## 2. 安装
+
+在能找到桌面 `dsh` 的终端执行：
+
+```sh
+npm view @ckanner/flywheel version
+npx -y @ckanner/flywheel@latest install
+flywheel version
+```
+
+固定安装时，把 `@latest` 换成已发布的精确版本。Agent 需要单个结构化结果时，在安装
+命令后加 `--json`。安装器依次完成：
+
+1. 全局安装本次精确版本，解析同版本平台二进制与 workers。
+2. 安装内嵌 skills；仅在全局配置不存在时创建它。
+3. 保存绝对路径 GUI 启动器与安装时工具路径。
+4. 在所选 DSH profile 中注册同版本 Flywheel 插件。
+5. 运行本地诊断，报告已完成步骤和阻断项。
+
+`ok:true` 表示安装完成，`ready:true` 表示本次本地诊断没有阻断。缺少工具可以产生
+`ok:true, ready:false`，具体原因见 `diagnostic.checks`；两者都不能证明账号或真实
+推理通过。安装失败会保留部分结果，供定位原因后重试。
+
+### 安装参数
+
+| 参数 | 作用 |
+|---|---|
+| `--prefix PATH` | 选择 npm 全局安装 prefix |
+| `--project PATH` | 将项目 skills 安装到已有项目的 `.agents/skills` 并诊断该项目；CLI 仍全局安装 |
+| `--dsh-bin PATH` | 选择已核实的桌面 DSH 命令 |
+| `--profile NAME` | 桌面插件目标 profile，默认 `desktop`，与 worker SDK profile 分开 |
+| `--no-dsh` | 跳过桌面插件注册 |
+| `--no-global` | 配置已有持久安装，不再次全局安装 |
+| `--timeout-ms N` | 单步骤超时，默认 600000 毫秒，范围 100–1800000 |
+| `--json` | 输出一个结构化安装结果 |
+
+使用用户可写的 prefix：
+
+```sh
+npx -y @ckanner/flywheel@latest install --prefix "$HOME/.local"
+export PATH="$HOME/.local/bin:$PATH"
+flywheel version
+```
+
+把实际 prefix 的 `bin` 写入 shell 配置。必要时传入
+`--dsh-bin /absolute/path/to/dsh`，先核实路径，不猜测 app bundle 内的位置。
+普通 `npm install --global @ckanner/flywheel` 只放置包文件，之后须显式运行
+`flywheel setup --no-global`。不要用 `--no-global` 把临时 npx 缓存当成永久 GUI 入口。
+
+## 3. 配置桌面与 SDK 后端
+
+按 DSH 要求重新载入，进入已有会话，在内置视图旁选择 **Flywheel**。它排在“统计”
+之后，必要时检查更多菜单；新会话的空白首页不展示会话视图。控制台提供画布、配置
+和运行记录，DSH 继续保留对话、轨迹、输入区与侧栏。
+
+桌面插件注册默认使用桌面附带的命令和 `desktop` profile。独立 npm 安装的 DSH CLI
+不能管理该保留 profile。Worker 通常运行在独立的 **`sdk` profile**，不会继承对话
+当前模型或全部桌面插件。
+
+### 账号选择
+
+默认 DeepSeek 路由明确选择 `deepseek-account`／`deepseek-flash`。标准 SDK `base`
+包含账号 adapter；标准桌面与 SDK 使用相同 `DSH_HOME` 时共享已有账号授权存储。
+自定义 home、profile 或凭证存储须另外核对。`deepseek-official` 是显式配置的 API Key
+替代路径，账号预设没有通往它的自动付费后备。
+
+原生 GPT Review／Judge 需要 SDK profile 中的 ChatGPT adapter。仓库核对过的兼容
+基线可这样安装：
+
+```sh
+dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
+```
+
+这是兼容基线，不代表当前最新版本。按该 adapter 的正常授权流程操作，保持 `DSH_HOME`
+一致，不把凭证放进任务文件或 Git。
+
+hard 路由直接导入精确锁定的 Codex Pro 0.9.0 公开 machine API，需要本机 Codex 程序
+与登录，不需要父模型通过 `subagent_codex_pro` 工具二次委派。可选 Claude 有独立的
+依赖与登录。
+
+DSH worker 只在子进程内应用权限与工具策略，禁用委派、辅助模型压缩以及当前的完整
+web 工具。原生会话视图不会恢复这些 worker 能力，也不会把完整 worker 历史合入父会话
+轨迹。生命周期与能力边界见[插件文档](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.zh-CN.md)。
+
+### 桌面启动器
+
+Setup 写入 `~/.config/flywheel/npm-launcher` 和安装记录，保存绝对 Node／CLI 路径
+及已核实的 DSH 入口。显式 `flywheelBinary` 优先于托管启动器；记录缺失可使用旧 PATH
+查找，记录损坏或 launcher 被改动则明确失败。
+
+移动 Node／npm prefix，或安装原先缺失的工具后，在能找到它们的终端中保留原参数，
+重跑 `flywheel setup --no-global`。处理冲突前先保留定制 launcher。终端 export 不会
+更新已经运行的桌面进程。
+
+## 4. 选择配置与 skills
+
+配置按任务、项目、全局、内嵌默认的顺序选择首个完整文件，不逐字段合并。先查看真实
+来源：
+
+```sh
+flywheel config inspect --cwd /absolute/path/to/repo --json
+flywheel template flywheel.config.example.json
+flywheel template flywheel.profiles.example.json
+```
+
+升级保留已有模型、权限、历史和调度设置。采用订阅模型预设时先预览，确认账号与完全
+权限策略符合预期后再应用：
+
+```sh
+flywheel config migrate --preset subscriptions --cwd /absolute/path/to/repo --json
+flywheel config migrate --preset subscriptions --cwd /absolute/path/to/repo --apply --json
+```
+
+任务级配置需加 `--task-dir`。迁移先备份所选文件，保留无关设置，不会自动让旧配置
+启用 scoped 历史或并行调度。完整采用安装版本模板时，在全局／项目配置编辑器载入
+默认值、审阅并保存。优先级、权限和迁移规则见[配置指南](configuration.md)。
+
+当前源码内嵌 11 个 skills，作为可选宿主入口；CLI 和控制台也能独立使用。查看或补装
+项目 skills：
+
+```sh
+flywheel skills list
+flywheel skills read flywheel-task
+flywheel install-skills --project /absolute/path/to/repo --json
+```
+
+沿用宿主的技能发现规则。安装器拥有且未修改的快照可更新，修改过或不属于安装器的
+文件会保留并报告冲突。DSH 使用 `/flywheel-task <目标>` 准备并启动，
+`/flywheel-new <目标>` 只准备方案，`/flywheel-run <任务路径>` 运行已有任务；Kimi
+对应使用 `/skill:` 前缀。
+
+## 5. 运行无推理预检
+
+在目标仓库中执行：
+
+```sh
+flywheel doctor --cwd "$PWD" --json
+flywheel doctor --cwd "$PWD" --probe --json
+```
+
+本地检查覆盖配置、目录、命令／版本及声明的环境变量。`--probe` 会初始化 DSH SDK
+会话，核对接受的配置、目录、权限和关闭结果，不发送推理 prompt，也不运行验收命令。
+Provider 初始化可能查询目录或写缓存，探测会话使用临时存储，不进入用户会话列表。
+
+Codex Pro 诊断导入锁定 API，检查 lifecycle／recovery 导出及本机命令，不证明模型
+授权、某条已保存历史的恢复或实际推理强度。正式 Codex 调用另外在 `thread-ready`
+核对完整策略，再由 Go ACK 放行；这不使无推理诊断等同于真实账号验收。
+
+结果分为 `pass`、`fail`、`warn`、`unknown`、`skipped`，fail 退出码为 1。
+按任务预检会读取 Spec 或持久化策略，仅检查适用绑定，不提前应用随后启动时的
+`--mode` 覆盖：
+
+```sh
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/my-feature" --probe --json
+```
+
+预检不创建 Flywheel 状态或 worktree。桌面 PATH／profile／环境不同时，再从桌面核对。
+这些诊断适合安装后或配置变化时使用，不是每个任务必须逐项点击的按钮。
+
+## 6. 准备任务
+
+### 已有仓库
+
+在 DSH 对话中输入：
+
+```text
+/flywheel-task 修复已定位的问题，补齐回归测试并验证结果。mode=auto
+```
+
+助手研究仓库，按照有效 worktree 策略选择或复用任务集成目录，准备契约与基线证据，
+再在授权范围内启动。只想准备时用 `/flywheel-new`，无需先填写控制台表单。
+
+区分**项目工作区**、**任务执行根**与**任务文件目录**：项目是稳定仓库归属，执行可
+位于 linked worktree，其契约放在 `docs/<slug>`。准备结果应报告真实路径。后续
+packet 执行目录由引擎管理或登记，`state.json` 也由引擎维护，详见
+[选择任务执行目录](workflow.md#2-选择任务执行目录)。
+
+### 独立的首次运行示例
+
+内嵌脚本创建一个独立 Go 加法任务，故意提供错误实现和受保护的验收测试。需要
+Go 1.27 或更高及尚未使用的目标目录。该示例没有 workflow 评估字段，因此走 Full；
+仅改模式参数不能使它具备 Quick 资格。
+
+```sh
+FLYWHEEL_PACKAGE="$(npm root --global)/@ckanner/flywheel"
+bash "$FLYWHEEL_PACKAGE/docs/examples/create-first-task.sh" "$HOME/flywheel-demo"
+cd "$HOME/flywheel-demo"
+git init -b main
+```
+
+使用自定义 prefix 时，通过 `npm root --global --prefix "$HOME/.local"` 找到包。
+CLI 不在 PATH 时，调用脚本前以 `FLYWHEEL_BIN` 指定其绝对路径。脚本仅写文件并读取
+模板，不调用模型或提交。
+
+运行生成 packet 中的全部验收命令，示例自带检查为：
+
+```sh
+go test ./...
+go test -coverprofile=coverage.out . &&
+  go tool cover -func=coverage.out |
+  awk '$NF != "100.0%" && $NF != "100%" { bad=1 } END { exit bad }'
+```
+
+首次失败符合预期。把实际结果写入 Spec，审阅冻结边界，再提交示例并创建任务分支：
+
+```sh
+git add go.mod sum.go acceptance .gitignore flywheel.config.json docs/add
+git diff --cached
+git commit -m "docs: prepare first flywheel task"
+git worktree add -b task/add ../flywheel-demo-add
+cd ../flywheel-demo-add
+```
+
+此独立示例先生成契约再创建任务 worktree；已有仓库按[工作流指南](workflow.md)的顺序
+准备。
+
+## 7. 启动、观察、停止与恢复
+
+以下命令调用已配置的真实后端。在示例任务 checkout 中运行，或替换实际任务名称：
+
+```sh
+flywheel config inspect --cwd "$PWD" --task-dir "$PWD/docs/add" --json
+flywheel doctor --cwd "$PWD" --task-dir "$PWD/docs/add" --probe --json
+flywheel control start --cwd "$PWD" --task-dir "$PWD/docs/add"
+flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/add"
+```
+
+DSH 对应入口为 `/flywheel-run <绝对任务路径>` 和 `/flywheel-status <同一路径>`。
+启动和只读状态关联使任务可在控制台选择。控制台读取登记任务，不扫描文件夹；已知
+项目／执行／任务文件位置显示为只读详情。当前会话唯一任务可以自动打开，多个或
+未归属任务需要选择。
+
+界面区分本阶段结果和整体交付，自动刷新运行状态与登记任务。超时或断连可能留下
+未确认操作：保留原路径，先核对原任务再提交新变更。旧快照、关闭页面或切换会话
+不能证明引擎已停止。宿主明确证明控制进程启动前拒绝，与结果未知是不同状态。
+
+需要在 Review 前暂停的前台运行时，使用下面命令**替代**后台启动：
+
+```sh
+flywheel run docs/add --pause-before review
+```
+
+`control launch`／`start` 不接受 `--pause-before`，该参数也不能与 `--only` 合用。
+单环命令不等于整任务完成，详见[单阶段操作](workflow.md#单阶段操作与权限)。
+
+查看与停止：
+
+```sh
+flywheel status docs/add
+tail -n 80 docs/add/orchestrator.log
+flywheel control stop --cwd "$PWD" --task-dir "$PWD/docs/add"
+```
+
+核对先前运行并解决真实错误后，才从原路径恢复，保留状态、报告和 worktree。
+派发、结果或清理未知时，切换 fresh 历史或另一个后端不能绕过，详见[恢复指南](session-recovery.md)。
+
+首次实机运行应检查 completed、全部需求覆盖、冻结验收未变、独立 Review、报告及
+本地 Git 交付。真实模型、延迟与用量是独立于预检的观测。创建／合并 PR 是另行授权的
+[控制台操作](flow-console.md#远端-pr-与-merge)。
+
+## 8. 升级、排错与卸载
+
+### 升级与修复
+
+先停止活动任务并核对状态，保留配置和定制内容，再用原有 prefix／项目／DSH 参数
+重复安装。核对 `flywheel version`、安装报告和桌面插件版本，并按 DSH 要求重载。
+`flywheel setup --no-global` 用于修复当前已安装版本。
+
+在 Flywheel 自身源码目录外执行 npx，避免 npm 用本地同名包满足请求。必要时显式
+全局安装所选已发布版本，再从同一 prefix 运行 setup。已有配置继续保留，判断项目／
+全局修改是否生效前，先检查更高优先级任务文件。
+
+### 常见问题
+
+| 现象 | 先检查什么 |
+|---|---|
+| 缺少命令或新布局 | 已安装 CLI／插件版本、PATH 和显式 `flywheelBinary` |
+| 视图栏没有 Flywheel | 已有会话、更多菜单、插件启用与宿主重载 |
+| 安装后 `ok:true, ready:false` | `diagnostic.checks` 中具体阻断 |
+| 全局 prefix 不可写 | 使用用户可写的 `--prefix` 及其 `bin` |
+| desktop profile 被拒绝 | 使用桌面附带的 DSH 命令，而非独立 npm CLI |
+| 终端可用、桌面不可用 | 托管 launcher、工具路径、SDK profile 与 `DSH_HOME`；工具变化后重跑 setup |
+| Provider 未注册或未授权 | Worker 的 SDK profile 和对应 provider 正常登录流程 |
+| 模型修改未生效 | 实际配置来源及引擎重启 |
+| 改渠道名没切账号 | Channel 是配置／计量标签，真实授权由后端决定 |
+| Doctor 显示 unknown 或 skipped | 阅读具体原因，两者都不代表真实推理通过 |
+| 费用缺失 | 渠道未报告 usage／cost，unknown 不是零 |
+| 验收 exit 0 仍失败 | 候选漂移、超时、取消、输出截断或清理错误 |
+| 隔离目录不可用 | 实际执行模式；并行自动管理 worktree 时创建失败即停止，不回退 |
+| 启动／停止／清理未确认 | 重试前核对原任务状态、日志、所属进程与可信回执 |
+| Git 交付失败 | 保留的 worktree、hook 与差异，处理原因而不强制清理 |
+| Skill 或 launcher 归属冲突 | 备份具体定制并对照，不改写完整性清单 |
+
+安装不是跨 npm、DSH 和 skills 的单个事务。修正报告中的原因后重试，不删除无关
+用户文件。验收命令需要额外工具变量时，用 `verify.env-allowlist` 显式列出变量名，
+不要把全部模型凭证注入测试。
+
+### 卸载
+
+停止并核对活动任务，通过 DSH 正式插件管理入口移除桌面 Flywheel 插件，然后使用
+同一个 prefix 卸载全局 CLI：
+
+```sh
+npm uninstall --global @ckanner/flywheel
+```
+
+配置、任务账本、skills、安装记录和 worktree 保留，需另行决定如何处理。卸载不会移除
+DSH／Kimi／Codex 或账号凭证。源码构建与贡献检查见[贡献指南](contributing.md)，
+维护者发布见[发行指南](releasing.md)。

package/docs/zh-CN/investigation.md

@@ -0,0 +1,182 @@
+# 有界调查与反馈驱动工作流
+
+[文档首页](../README.zh-CN.md) · [English](../en/investigation.md) · [工作流](workflow.md)
+
+Task 是推荐的目标入口。它先区分交付终点，再准备适合的契约；Auto 在合法实现契约
+上选择 Quick 或 Full。调查是实现前可独立交付的工作，不是第三种完成模式。
+
+| 日常需求 | 推荐入口 | 引擎行为与终点 |
+| --- | --- | --- |
+| “先排查，告诉我原因” | `/flywheel-task` | 受管读取／搜索、证据报告；不实施修改 |
+| “排查并在原范围内修好” | `/flywheel-task` | 调查有支持结论后准备 Spec，继承来源、用量和范围，再 Auto |
+| “问题已定位，快速修复” | Task Auto 或显式 Quick | 资格成立才走紧凑流程；必需验证、独立最终 Review、Git 交付保留 |
+| “复杂任务先出方案，我们审阅” | `/flywheel-new` | 准备方案后停止；获得后续实施授权再 Run Full |
+| “继续这个已有任务” | `/flywheel-run` | 恢复原准备或实现记录；不新建任务、不重置预算 |
+| “只运行一个阶段” | Plan / Exec / Verify / Review | 保留直接控制；阶段通过不代表任务完成 |
+
+Kimi 使用对应 `/skill:flywheel-*` 名称。Status、Stop 均可用于调查和实现。用户已明确
+要求“排查并修好”时，不重复要求同一授权；新范围或未解决的产品取舍仍需单独决定。
+
+## 调查契约
+
+宿主助手从当前需求与仓库事实生成输入，Go 校验并写 `preparation.json`。不要求用户
+手工填写表单，不允许宿主直接修改准备状态或 `state.json`。可读取已安装二进制的
+`preparation.schema.json`、`preparation-state.schema.json` 和 `preparation.example.json`。
+
+契约 v1 包含目标、预期、环境、时间窗口、已知证据、可证伪假设、精确读取路径、具体
+动作与预算。`intent` 为 `investigate` 或 `investigate-and-fix`；后者需要非空的
+`implementation-scope`，前者不允许带实施授权。只存在准备记录时，尚不需要 Spec。
+
+首个可采用动作族由 Go 直接实现：
+
+| kind | 参数与能力 | 限制 |
+| --- | --- | --- |
+| `read_file` | 读取一个已授权 UTF-8 文件 | 拒绝符号链接、特殊文件与超限输入 |
+| `search_text` | 在一个已授权文件中查找字面量，返回行号 | 非正则，无命令拼接 |
+| `list_files` | 列出一个已授权目录的名字 | 不递归读取内容；最多 4096 个名字 |
+
+路径必须是干净的仓库相对路径，动作必须引用允许路径和已有假设。打开的文件还须与
+检查时的 inode 一致；`os.Root` 限制目录穿越。目录授权只授予名字读取。首版没有
+任意 shell、外部查询、生产重启、清缓存、数据回填或可写 Agent 调查动作。现有
+full-access 配置不改变这些 Go 动作的能力。更广实验需要独立增加处理器、契约和验证。
+
+`limits` 冻结动作次数、总时限、单文件字节和总输出字节；恢复不重置。总时限以首次
+准备的 deadline 为准，暂停时间也会消耗这个时限。只保留有界 UTF-8 输出，另存内容
+摘要；`truncated` 表示展示不完整，不能把片段当成完整日志或完整测试集合。
+
+## CLI 与桌面控制
+
+准备实际目录后，提交一个包含完整契约的请求文件：
+
+```bash
+flywheel control investigate --task-dir "$task_dir" --cwd "$repo_dir" < start-request.json
+```
+
+```json
+{"action":"start","contract":{"version":1,"id":"replace-with-a-complete-contract"}}
+```
+
+上面的 JSON 仅展示请求外层；`contract` 必须替换为完整 schema 合法输入，不能直接
+执行这个缩写示例。`start` 保存 ready 准备记录，不执行动作。需要运行时提交：
+
+```json
+{"action":"run","revision":1}
+```
+
+`revision` 必须取实际回执。Go 按原任务运行 lease 启动后台调查，复用已有就绪与
+token 绑定的停止协议。DSH 使用 `flywheel_control` 的 `action: investigate` 和
+嵌套 `investigation` 请求，会关联当前会话视图；不需要手填路径。视图显示预算、
+观察、截断、决策回执及报告，提供继续、核对回执、停止和刷新。
+
+```bash
+flywheel control status --task-dir "$task_dir" --cwd "$repo_dir"
+flywheel status "$task_dir"
+flywheel stop "$task_dir"
+```
+
+控制响应 `ok:true` 只确认控制请求；`running` 根据运行锁判断。只有调查时响应是
+`preparation`，不会伪造实现 `state`。未知结果须从原目录核对，不能重复启动来试运气。
+
+## 证据报告与修复交接
+
+动作结束后状态为 `awaiting-report`。当前宿主模型根据观察提交一次分析报告，Go
+校验字段、假设覆盖和观察引用。报告必须区分事实与推断，逐项说明 supported /
+contradicted / unknown，包含反例检查、局限、推荐方案、回归检查和回退条件。
+引用使用真实 `invocation.id`；失败或不存在的观察不能作为成功取证。
+
+通过 `control investigate` 提交 `action: report`、实际 `revision` 与 `report`。
+终态为 `supported`、`inconclusive`、`access-blocked`，或取消产生的 `cancelled`。
+`supported` 表示分析者给出的结论有结构合法的观察引用；Go 不替代语义核查，也不
+声称这个状态证明因果。没有支持结论时交付局限，不自动扩大调查或实现授权。
+
+原请求授权修复、调查已 supported 且全部回执已解决时，可在同一工作区与任务目录
+准备 Spec／packets，再走常规 launch。Go 把来源身份、报告摘要、原实施范围、动作
+次数与耗时写入 `preparation-source`；JEV 已知用量按原派发日一次计入任务总账，
+缺失用量与费用仍记 unknown。恢复不会重复记账。实际实现 diff 仍受原范围约束，
+Quick → Full 或允许模型升级不会增加权限。
+
+准备状态、原始观察与决策 journal 属于本地私有运行账本，自动 Git 交付排除这些文件。
+不能把日志中的凭据或源码片段自动带进 PR；如需发布调查结论，按用户目标另写经过
+检查的文档。已进入实现后不得删除或改写原准备来源来绕过范围和预算。
+
+## 快反馈、Plan 与进展
+
+执行提示词鼓励先跑相关的小检查；Go 仍在当前候选上执行冻结的完整验收，之后才
+独立 Review。这样去掉固定重复的全量验收要求，而不是缓存或省略最终门禁。
+
+反馈保留固定 check ID、期望和实际终态、候选／检查集／环境摘要、完整失败输出摘要，
+以及有界的头尾片段。`observationComplete` 只说明命令结果完整，不说明测试枚举完整。
+同一候选、同一检查与环境反复得到相同失败才可判 stalled；候选改变而缺乏可信 oracle
+时记 unknown，仍受总尝试次数约束。不会仅凭同一文件名判空转，或从文本推断“10→1”。
+
+Full 首次 Plan 后，只有已确认终态、合法重载契约、成功持久化并同步的检查点才可复用。
+普通返修保留该检查点；契约／验证／调度策略改变、未知外部 HEAD、旧任务没有证明、
+显式 Plan 或 verification-gap 都重新规划。Plan 的价值是消除真实不确定性，速度快
+不构成删除规划或降低质量门禁的理由。
+
+## 可选 JEV
+
+新 `decision` 配置与旧 `jev-shadow` 完全独立，省略时不发送请求。具体配置字段由
+准备 schema 定义，包含固定 `jev-x.y.z` 模型、显式 endpoint、密钥环境变量名、超时、
+策略版本、模式、数据允许集合、阈值与最大调用数。凭据值不写契约。
+
+- Off／offline 不联网；shadow 只保存可审查快照；advisory 只留建议；adopt 才允许选择
+  一个已批准的诊断动作。自动采用仍需独立实验政策，阈值不是本项目准确率保证。
+- 至少两个合法选项与真实语义不确定性才值得调用；单个请求配对 Noul 适用性与 Choice，
+  保留完整概率。没有适用选项、模型版本不符、证据字段未授权、预算不足或未知执行都弃权。
+- 采用前重新检查任务／run／revision、契约、候选、观察及动作绑定；将回执消费和唯一
+  action invocation 在同一 CAS 中保存后派发。JEV 不能生成命令、减少验收或宣布完成。
+- 可选请求未知时不重发，保留未知用量，转合法确定性基线。实际动作回执未知则 blocked。
+  结束、取消或 deadline 到期仍只读核对可选请求，不能留下无法结束的 pending 记录。
+- 最大调用数包括 unknown。硬预算没有可实施的单次消耗上限时跳过 JEV；不会用字符数
+  估计冒充可靠预留。shadow 研究与在线采用的费用和作用不同。
+
+旧工作流影子开关仅捕获本地有界摘要，后续显式 `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
+```
+
+即使来源策略为 `adopt`，`evaluate` 也强制 `advisory`。密钥环境变量名、固定目标、
+独立私有账本和累计调用上限都须明确指定。来源策略的数据类别权限必须覆盖快照；
+不会借旧 shadow 开关扩大权限。`--hard-budget` 因原生 API 不能强制请求用量上限而
+跳过调用。同一账本和快照只读取原回执；未知请求计入上限且不重发。命令不执行动作、
+不改变任务状态。
+
+两种命令都输出基线、实际策略、概率和回执，并明确 `adopted: false`。真实调用错误
+或未知返回退出码 3 和回执；输入／配置错误为 1，发送前取消为 143。离线重放通过只
+证明解析与 fixture 行为，不证明模型实际成功率。任务中有限采用仍须独立准备策略、
+数据 opt-in、冻结的 Go 具体动作和上述当前状态校验。
+
+## 度量与当前边界
+
+`metrics.jsonl` 的调用记录以外新增 `phase-start` / `phase-end`。`control metrics`
+的 timeline 同时给累计区间时长和已闭合区间的并集；并行区间不能相加冒充墙钟时间。
+缺少结束、时钟倒退、无法关联的旧调用单列，Provider 内部排队／模型／工具细分保持
+unknown。调查动作和调查运行使用同一阶段接口，宿主准备对话的不可观察时间不补零。
+
+本实现没有基于这些离线测试宣布 token、更低成本或最终质量相同，也没有开启新默认
+模型、JEV、预热或更高并发。ready queue、持久 worker、已有候选导入等继续按测量结果
+决定；现有取消、共同候选复验和持久化规则保持有效。

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

@@ -0,0 +1,79 @@
+# 可选 JEV 影子评估
+
+[文档目录](../README.zh-CN.md) · [English](../en/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 路由开关。独立的有界诊断决策政策不能继承本实验的权限或阈值。