@ckanner/flywheel 0.31.0 → 0.32.0

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,213 @@
+# 有界调查与反馈驱动工作流
+
+[文档首页](../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 个名字 |
+| `run_command` | 在批准输入的临时副本中运行精确 argv，收集复现或诊断结果 | 显式 `host-process` 授权、独立时限、受控环境、进程组取消与收尾 |
+| `http_read` | 对明确 URL 发出 GET 或 HEAD 查询 | HTTPS（loopback 测试可 HTTP）、无重定向／环境代理、固定响应与输出上限 |
+
+文件路径必须是干净的仓库相对路径，文件动作必须引用允许路径；所有动作都引用已有
+假设。打开的文件还须与检查时的 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 与桌面控制
+
+准备实际目录后，提交一个包含完整契约的请求文件：
+
+```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` 请求，会关联当前会话视图；不需要手填路径。视图显示预算、
+观察、截断、命令退出码／HTTP 状态、取消与副本收尾、决策回执及报告，提供继续、
+核对回执、停止和刷新。
+
+```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。这样去掉固定重复的全量验收要求，而不是缓存或省略最终门禁。
+Packet 可用与验收命令相同的 `cmd`／`expect` 结构声明最多八项已批准的短
+`feedback-checks`，帮助局部复现，不改动最终验收。JEV 开启后，引擎可选择一项
+这样的检查，或在已确认失败后重新执行对应 L1 检查。供 JEV 选择的短检查还须填写
+1–160 字符的非空白 `purpose` 用途说明；没有用途说明的条目仅供 Executor 参考。
+JEV 候选发送用途说明，不附加 `cmd`／`script` 文本；说明本身也不要含密钥或原日志。
+
+反馈保留固定 check ID、期望和实际终态、候选／检查集／环境摘要、完整失败输出摘要，
+以及有界的头尾片段。`observationComplete` 只说明命令结果完整，不说明测试枚举完整。
+同一候选、同一检查与环境反复得到相同失败才可判 stalled；候选改变而缺乏可信 oracle
+时记 unknown，仍受总尝试次数约束。不会仅凭同一文件名判空转，或从文本推断“10→1”。
+
+Full 首次 Plan 后，只有已确认终态、合法重载契约、成功持久化并同步的检查点才可复用。
+普通返修保留该检查点；契约／验证／调度策略改变、未知外部 HEAD、旧任务没有证明、
+显式 Plan 或 verification-gap 都重新规划。Plan 的价值是消除真实不确定性，速度快
+不构成删除规划或降低质量门禁的理由。
+
+## JEV 决策
+
+使用 [JEV 指南](jev.md) 中唯一的 `jev.enabled` 设置。Start 自动解析配置并冻结
+策略，Task／New／Run 不再各自维护决策模式。默认关闭时沿用原动作顺序和收集
+限制；开启后可选择下一项动作、跳过冗余取证，或在满足 Go 证据前提后提前转入报告。
+
+跳过动作和提前结束收集均保存决策及观察引用，不会把假设自动标成已证明或已反驳。
+分析者仍要形成有证据的报告；修复仍须遵守原范围及普通验证、review 流程。
+`awaiting-report` 后重复 Run 不会重新开始收集。
+
+调查移交实施后，同一个开关还控制失败后的下一步：继续修复、运行已批准的反馈
+检查、请求重新规划，以及在允许的执行绑定中选择模型／effort。它们共用任务决策
+额度，保留调查已经消耗的次数，不因换 packet、重规划或恢复而清零。反馈检查是
+补充事实，不能代替后续完整验收。具体候选与状态语义见 [JEV 指南](jev.md)。
+
+目标、模型、数据类别、阈值和预算在创建准备记录时冻结。当前关闭、目标不再相容
+或收紧策略会停止后续可选决策；请求返回后、采用前仍要复核。已知／未知回执继续
+核对，不重发。创建时关闭的准备记录保留原基线路径，新准备记录才采用新开启的
+策略；桌面对持久状态明确标注“最近观察到的状态”。
+
+离线回放和显式在线评估见 [JEV 指南](jev.md#离线回放与显式评估)。关闭 JEV 仍可
+本地回放；在线评估必须服从同一已启用的总开关和配置目标，其数据与次数限制不能
+放宽配置。两种工具均不执行动作、不修改任务状态。
+
+## 度量与当前边界
+
+`metrics.jsonl` 的调用记录以外新增 `phase-start` / `phase-end`。`control metrics`
+的 timeline 同时给累计区间时长和已闭合区间的并集；并行区间不能相加冒充墙钟时间。
+缺少结束、时钟倒退、无法关联的旧调用单列，Provider 内部排队／模型／工具细分保持
+unknown。调查动作和调查运行使用同一阶段接口，宿主准备对话的不可观察时间不补零。
+
+本实现没有基于这些离线测试宣布更少 token、更低成本或最终质量相同。JEV 仍默认
+关闭，明确开启总开关才参与已支持的决策；默认模型和并发设置不变。
+[就绪队列与有界 DSH 运行时准备](configuration.md#就绪队列与运行时准备)已可通过
+scheduler 显式配置，缺省仍为 batch／不预热。真实收益和是否调整默认值继续等待
+测量。长期驻留 worker、通用外部补丁导入仍是独立工作；已有受管 Session 接管／
+交回路径继续遵守原恢复、候选复验和持久化要求。

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

@@ -0,0 +1,5 @@
+# JEV 指南已迁移
+
+[English](../en/jev-shadow.md) · [简体中文](../zh-CN/jev-shadow.md)
+
+当前行为见 [JEV 决策指南](jev.md)：统一 `jev.enabled` 总开关、实际调查采用、依据证据调整取证和评估工具。旧的自动影子观察器与独立请求客户端已经移除。历史结果保留在[原验收记录](../validation/2026-11-10-jev-shadow.md)。