@ckanner/flywheel 0.32.0 → 0.33.0

package/plugins/dsh/README.en.md

@@ -0,0 +1,4 @@
+# Flywheel for DSH documentation
+
+The English documentation is now the default [README](README.md).
+For Chinese, see [简体中文](README.zh-CN.md).

package/plugins/dsh/README.md

@@ -0,0 +1,342 @@
+# Flywheel for DSH
+
+English · [简体中文](README.zh-CN.md) · [Project overview](https://github.com/ckanner/flywheel/blob/main/README.md) · [Documentation](https://github.com/ckanner/flywheel/blob/main/docs/README.md)
+
+`@ckanner/flywheel` connects DeepSeek Harness (DSH) to Flywheel's
+Go orchestration engine. It adds a native workflow view, command and model-tool
+controls, and the workers used by selected backends. The engine owns task state,
+verification, budgets, process lifecycles, and Git delivery.
+
+Use the complete Flywheel installer for normal setup. Installing this package
+alone provides the plugin and workers, not the Go engine and skills.
+
+## Install
+
+Requirements are **Node.js 22.18.0 or later**, npm, and a compatible DSH desktop
+with its desktop-supplied `dsh` command. This package declares DSH
+**`>=0.2.1-rc.5 <0.3.0-0`** and the corresponding Cordis 4.0/4.1 interfaces.
+DSH includes prereleases when checking this range: later 0.2 rc/patch releases do
+not need an exact-version exemption or a new Flywheel release. The next minor,
+including 0.3 alpha/beta/rc releases, remains outside this contract.
+The selected host may have a higher Node requirement; use its supported runtime.
+
+The range is an API compatibility policy, not evidence that every future host
+has been tested. Locked integration fixtures cover the legacy 0.2.1-rc.5 host
+and the current 0.2.2-rc.3 host/SDK. Required services, session identity,
+permission receipts and process cleanup remain checked at runtime. A missing
+service or invalid receipt still fails visibly before unconfirmed work is accepted.
+DSH peers stay optional and are supplied by the host; their npm ranges also
+include the two existing prerelease lines, without pinning individual rc releases.
+
+```sh
+npx -y @ckanner/flywheel@latest install
+```
+
+The installer installs one matching version of the CLI, platform binary,
+workers, embedded skills, and desktop plugin. It registers the plugin through
+the desktop's plugin management interface and creates a managed launcher.
+Reload or restart DSH when requested by the host. Go packages support macOS and
+Linux on arm64 and x64; Linux package availability does not establish Mac
+desktop or Seatbelt behavior.
+
+| Option or command | Use |
+|---|---|
+| `--dsh-bin /absolute/path/to/dsh` | Use the desktop CLI when it is not on PATH |
+| `--prefix "$HOME/.local"` | Select a writable npm prefix; add its `bin` directory to PATH |
+| `--no-dsh` | Explicitly skip desktop registration |
+| `flywheel setup --no-global` | Finish or refresh setup for an existing persistent installation |
+| `--json` | Return the installation report for automation |
+
+The standalone npm DSH CLI cannot manage the reserved `desktop` profile.
+Plain `npm install --global @ckanner/flywheel` installs package files only;
+there is no postinstall hook that changes a profile, skills, or credentials.
+In an installation report, `ok: true` means installation succeeded;
+`ready: false` can still identify missing native CLIs or local prerequisites.
+See [Getting started](https://github.com/ckanner/flywheel/blob/main/docs/en/getting-started.md) for setup and removal.
+
+## Prepare the selected backends
+
+The DSH worker uses an independent `sdk` profile by default. Standard desktop
+and SDK profiles under the same `DSH_HOME` can reuse the DeepSeek account
+credential store. A custom profile must load the selected account service,
+provider, and tools. The reserved `desktop` profile cannot be used as a worker.
+
+| Backend | Setup and execution path |
+|---|---|
+| DeepSeek Flash | DSH `deepseek-account` and explicit `deepseek-flash`; no additional API key is required for the standard shared account store |
+| DSH ChatGPT | Install and authorize the selected ChatGPT adapter in the SDK profile; changing the desktop chat model does not configure a worker |
+| Codex Pro | The worker imports `dsh-subagent-codex-pro/machine` from the pinned 0.9.0 package and uses the installed Codex CLI/login |
+| Kimi | Go invokes the native Kimi CLI with its own login; no ACP or parent-model delegation |
+| Claude Code Pro | Optional 0.4.0 peer and installed Claude CLI/login; no default loop selects it; follow the [adapter guide](https://github.com/ckanner/flywheel/blob/main/docs/en/claude-code-pro.md) |
+
+One documented ChatGPT adapter compatibility example is:
+
+```sh
+dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
+```
+
+That versioned example does not establish current account entitlements.
+Authentication and live model availability must be checked through each
+backend's supported flow. Flywheel does not install native model CLIs, copy
+credentials, or provide subscription access.
+
+The default Flash route does not fall back to `deepseek-official` after an
+account failure. That API-key provider is an explicit alternative. The default
+hard route uses `codex-pro`, not a DSH provider called `subagent_codex_pro`, and
+does not silently fall back to `codex exec`. See
+[Configuration](https://github.com/ckanner/flywheel/blob/main/docs/en/configuration.md) and
+[Models and reasoning effort](https://github.com/ckanner/flywheel/blob/main/docs/en/model-policy.md).
+
+### Executable and environment overrides
+
+| Variable | Meaning |
+|---|---|
+| `FLYWHEEL_DSH_BIN` | DSH executable used by the worker |
+| `FLYWHEEL_DSH_PROFILE` | Independent SDK profile; default `sdk` |
+| `DSH_HOME` | DSH configuration, account, and session root |
+| `FLYWHEEL_DSH_WORKER` | Explicit DSH worker override |
+| `FLYWHEEL_CODEX_PRO_WORKER` | Explicit Codex Pro worker override |
+| `FLYWHEEL_CLAUDE_CODE_PRO_WORKER` | Explicit optional Claude worker override |
+| `FLYWHEEL_CODEX_BIN` / `CODEX_HOME` | Native Codex executable and existing configuration/login root |
+| `FLYWHEEL_CLAUDE_BIN` / `CLAUDE_CONFIG_DIR` | Native Claude executable and existing configuration/login root |
+| `FLYWHEEL_KIMI_BIN` | Native Kimi executable; default `kimi` |
+
+The npm launcher normally resolves workers from its own installed package.
+Executables and environment settings must be visible to the process that starts
+the engine; a shell export does not update an already running desktop.
+
+## Start a task and use the workbench
+
+In DSH's composer, enter `/flywheel-task <goal>`. The host assistant prepares
+and checks the task contracts, then calls `flywheel_launch`. Preparation uses
+the conversation model; execution stages use Flywheel's configured bindings.
+Use `/flywheel-new` to prepare a proposal without starting, and `/flywheel-run`
+to continue an existing task. An explicit request to review a proposal first
+remains part of the task's authorization.
+
+Open **Flywheel** alongside the built-in conversation views, or in their overflow
+menu. The workbench has three pages:
+
+| Page | What it provides |
+|---|---|
+| Workflow canvas | Current session task, current stage, evidence, stage run/retry, role-session history, and managed intervention |
+| Run history | Registered runs, known usage/cost, missing metrics, and comparisons with their conditions |
+| Configuration | Automatically loaded global/project settings, grouped editing, source display, and protected unsaved drafts |
+
+The view automatically follows the current conversation's explicit task association,
+then its latest registered host-session run. There is no task selector or path form;
+foreign and ownerless runs stay out of this view. Use `flywheel_control status` in the
+intended conversation to associate a prepared task. Locations and action groups are
+shown directly. A successful single-stage Review is not whole-task completion.
+
+Automatic refresh and other reads use a session-scoped read-only Remote and do not
+append JSON command records to chat. Explicit mutations and unknown-result recovery
+keep durable command receipts. Settings has fixed navigation and save controls, inline role-session overrides and an optional usage budget. Environment checks live in Advanced and diagnostics; raw diagnostic responses do not fill the normal workflow view.
+
+Preparation-only tasks display a bounded investigation panel with observations,
+budgets, original-receipt reconciliation, Stop, and the evidence report. Approved
+diagnostic commands and HTTP queries show exit/status codes, cancellation and copy
+cleanup. Commands use explicitly granted host-process authority in copied inputs;
+the copy is not an OS sandbox. A report does not imply code delivery. See the
+[investigation guide](https://github.com/ckanner/flywheel/blob/main/docs/en/investigation.md).
+
+Under **Settings → JEV**, **Enable JEV** is the only JEV switch and is off by
+default. Choose the global or project scope, turn it on to reveal the connection
+fields, and fill or confirm the System One endpoint, pinned model and API-key
+environment variable name. Select **Save changes** to apply the setting. The switch
+edits a draft; editing and saving do not test service connectivity. When disabled,
+existing execution paths run without JEV requests or shadow capture. New
+investigations prepared through Task or New inherit the policy automatically;
+Run continues that frozen policy. Enabled JEV can choose the next approved evidence action, defer
+redundant actions on cited evidence, or end evidence collection early for a report.
+During implementation it can choose a legal next step after confirmed failure:
+local repair, an approved feedback check, bounded replanning or an allowed execution
+binding. Investigation and implementation share the task's call allowance. A
+feedback check never removes complete final acceptance.
+
+Turning JEV off also blocks subsequent JEV calls and adoption in an existing
+task, while retaining its receipts and budget. Turning it on does not
+rewrite a preparation created while disabled. The panel distinguishes configured
+JEV settings from the investigation's recorded status, calls, adopted actions and
+evidence-backed effects. Task and node details distinguish applied control decisions,
+settled feedback, unresolved actions and the original baseline. They show actual
+feedback results and before/after model bindings with the switch reason; applying a
+configuration does not claim a new session has already run or final acceptance passed.
+Advanced request limits, confidence thresholds and data categories share the same
+switch; there is no separate shadow or adoption toggle.
+Legacy shadow configuration does not automatically opt into live decisions. See
+[JEV decisions](https://github.com/ckanner/flywheel/blob/main/docs/en/jev.md).
+
+
+Visible canvases refresh task discovery; running tasks refresh status. Opening
+the view starts no task or diagnostic probe. Failed reads retain the previous
+confirmed snapshot and its timestamp. A missing or timed-out launch/start/stop
+reply is **unconfirmed**, so further mutations stay blocked until status for
+that same task reconciles it. The view never automatically retries a mutation.
+Hiding the view, closing DSH, or removing the plugin does not stop the independent
+Go task; request Stop and await engine confirmation.
+
+### Commands and model tools
+
+| Entry | Scope |
+|---|---|
+| `/flywheel` | Human command accepting a JSON control request |
+| `flywheel_launch` | Model tool to launch a prepared task, Auto by default |
+| `flywheel_control` | Model tool for launch/start/status/stop/investigate/config/doctor |
+| Workbench controls | Additional revision-bound stages, configuration editing, managed handoff, and explicit delivery operations |
+
+A manual launch example is:
+
+```text
+/flywheel {"action":"launch","taskDir":"/repo/docs/my-task","cwd":"/repo","mode":"auto"}
+```
+
+Equivalent CLI operations are:
+
+```sh
+flywheel control launch --cwd /repo --task-dir /repo/docs/my-task --mode auto
+flywheel control status --cwd /repo --task-dir /repo/docs/my-task
+flywheel control stop --cwd /repo --task-dir /repo/docs/my-task
+flywheel control start --cwd /repo --task-dir /repo/docs/my-task
+```
+
+Paths above are explicit command arguments, not UI fields. An omitted `cwd`
+uses the session's public current-directory service. Launch/start/stop require
+an explicit absolute `cwd` if the session has no recorded project directory.
+Input is validated and passed as argv, not interpolated into a shell command.
+`ok: true` reports the control operation; completion comes from task state.
+
+The host prepares the outer task worktree. The engine independently manages
+packet scheduling and execution directories. New templates enable declared
+parallel scheduling and automatic worktree management; existing configurations
+that omit the scheduler retain serial behavior. Ordinary run performs local
+Git delivery. Remote PR creation and merge require explicit delivery operations
+and their candidate/authorization checks. See the
+[workflow guide](https://github.com/ckanner/flywheel/blob/main/docs/en/workflow.md) and
+[console guide](https://github.com/ckanner/flywheel/blob/main/docs/en/flow-console.md) for these operations.
+
+## Diagnose without model inference
+
+```sh
+flywheel config inspect --cwd /repo --json
+flywheel doctor --cwd /repo --json
+flywheel doctor --cwd /repo --probe --json
+flywheel-codex-pro-worker --doctor
+```
+
+Add `--task-dir /repo/docs/my-task` to inspect one prepared task's configuration.
+Ordinary doctor checks local configuration and prerequisites. `--probe`
+initializes a temporary DSH SDK session, verifies directory and permission
+behavior, then closes it. It uses temporary persistence for the probe; it sends
+no inference prompt and runs no task acceptance commands. Provider
+initialization can still query a model catalog.
+
+Successful diagnostics do not prove live account authorization, quota, or model
+responses. Preserve `warn`, `unknown`, and `skipped` as separate outcomes.
+Diagnostics and installation do not write task state or start worktrees.
+
+## Runtime boundaries
+
+### Project membership and history
+
+The stable project workspace identifies the repository. Task integration and
+packet worktree directories identify where work actually happens. DSH creates a
+session under the project and switches its execution directory through the
+public working-directory service. Only the desktop host registers workspace
+membership; independent SDK workers do not concurrently rewrite desktop
+storage. Existing session headers and unresolved receipts retain their original
+identities. Unsupported combinations of project, execution directory, and
+restricted sandbox fail before dispatch; permissions are not silently widened.
+
+Scoped history can continue within the same task, role, and scope. Executor,
+Reviewer, Judge, and second-opinion histories stay separate. A Reviewer must
+inspect the complete current candidate even when reusing its own history.
+New templates explicitly select scoped mode; old configurations that omit it
+retain fresh behavior. The explicit Plan `resident-session:false` opt-out
+continues to apply.
+
+Both modes retain invocation safety records. Unknown dispatch, outcome, or
+cleanup blocks new execution. Codex/Claude public APIs add durable Go ACKs,
+supervisor journals, and exact read-only receipt recovery; DSH/Kimi retain their
+own supported paths. Quality rebuild thresholds default to disabled. See
+[Recovery](https://github.com/ckanner/flywheel/blob/main/docs/en/session-recovery.md) and
+[Paired evaluation](https://github.com/ckanner/flywheel/blob/main/docs/en/session-evaluation.md).
+
+### Permissions and worker lifecycle
+
+Optional `scheduler.prewarm:true` uses the DSH worker's two-phase `--prewarm`
+protocol to initialize one SDK during verification, without creating a Session
+or sending a prompt until the formal invocation is admitted. It defaults to
+false; other backends retain their existing startup paths. The same bounded
+shutdown and process-group proof apply to unused workers. See the
+[worker protocol](PROTOCOL.md#dsh-sdk-一次性预热) for expiry, cancellation and recovery.
+
+The DSH worker supports read-only, workspace-write, and explicit full access,
+with approvals set to never. New subscription presets request full access;
+existing files without a permission setting retain role-based behavior.
+Actual policy is checked before prompting. Full access does not establish an
+OS sandbox or remove host static denials, account restrictions, or OS permissions.
+A Git worktree is also not a security sandbox.
+
+The temporary SDK overlay applies only to the independent worker. It disables
+recursive delegation, workflow drivers, automatic titles/compaction, scheduled
+input, and the entire web-tool package, including search and fetch. Full access
+does not restore these auxiliary-model/tool capabilities. Restoring them needs
+separate accounting, cancellation, and directory-ownership support. The overlay
+does not remove desktop tools or edit reminder storage.
+
+Main-task Codex calls check the complete actual sandbox policy at `thread-ready`
+before Go acknowledges dispatch, then check the terminal receipt again.
+Legacy/advisory paths retain their terminal checks. Claude's native init arrives
+after its prompt and cannot provide the same pre-dispatch observation. Kimi
+print mode does not provide an OS sandbox that this adapter can promise.
+
+A successful result requires a trustworthy terminal receipt and confirmed
+process cleanup. An outer worker exit does not prove SDK or guardian cleanup.
+Graceful SDK shutdown allows two seconds for persistence/disposal before bounded
+TERM/KILL cleanup. Lost outcomes preserve evidence and block automatic replay.
+Missing usage and subscription dollar cost remain unknown, not zero. Complete
+worker histories are not automatically merged into the parent's DSH trajectory;
+images and attachments are not supported by these worker inputs.
+
+## Maintain and develop
+
+The explicit plugin setting `flywheelBinary` takes precedence over the managed
+installation record. Without it, the plugin uses the validated launcher recorded
+under `~/.config/flywheel/`. Without a record, the installed package uses its own
+`bin/flywheel.js`; only the private source harness retains the legacy PATH fallback.
+A damaged record or changed launcher fails visibly. `controlTimeoutMs` defaults
+to 60,000 and controls the desktop control request, not the task's total budget.
+
+An existing managed launcher must match the installed package version. After updating
+only the DSH copy, run setup for that version to refresh the managed installation;
+a stale record is reported instead of mixing a newer view with an older engine.
+
+After upgrading, moving the npm prefix, changing Node, or adding native CLIs,
+run `flywheel setup --no-global` with the intended prefix and desktop CLI
+options, then reload DSH as needed. Existing configuration and modified skills
+are preserved. Adopt changed defaults through the explicit configuration
+migration, not by deleting ownership records.
+
+For a source checkout:
+
+```sh
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+```
+
+See [Contributing](https://github.com/ckanner/flywheel/blob/main/docs/en/contributing.md) for bridge and release checks.
+Offline renderer/SDK tests establish the exercised contracts, not physical Mac
+window geometry, real-account inference, or measured quality gains.
+
+| Reference | Purpose |
+|---|---|
+| [Worker protocol](PROTOCOL.md) | Detailed wire, permission, lifecycle, and error contracts (Chinese) |
+| [Vendored package provenance](vendor/README.md) | Codex source identity, tarball hashes, and optional Claude source evidence |
+| [JEV decisions](https://github.com/ckanner/flywheel/blob/main/docs/en/jev.md) | One master switch for actual bounded decisions, with offline replay and explicit evaluation |
+| [Release guide](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md) | Build, install, and publish the same checked artifacts |
+
+## License
+
+[MIT](LICENSE). Adapted DeepSeek UI portions and bundled dependencies retain
+their own notices; see [Third-party notices](THIRD_PARTY_NOTICES.md).

package/plugins/dsh/README.zh-CN.md

@@ -0,0 +1,279 @@
+# Flywheel DSH 插件
+
+[English](README.md) · 简体中文 · [项目介绍](https://github.com/ckanner/flywheel/blob/main/README.zh-CN.md) · [文档目录](https://github.com/ckanner/flywheel/blob/main/docs/README.zh-CN.md)
+
+`@ckanner/flywheel` 将 DeepSeek Harness（DSH）连接到 Flywheel 的
+Go 编排引擎，提供原生工作流视图、命令与模型工具入口，以及所选后端需要的 worker。
+任务状态、验收、预算、进程生命周期和 Git 交付由引擎管理。
+
+日常使用应通过完整 Flywheel 安装器安装。单独安装本插件只能得到插件和 worker，
+不包含 Go 引擎和 skills。
+
+## 安装
+
+需要 **Node.js 22.18.0 或更高版本**、npm，以及兼容的 DSH 桌面和桌面提供的
+`dsh` 命令。此包声明支持 **`>=0.2.1-rc.5 <0.3.0-0`** 及相应 Cordis 4.0/4.1 接口。
+DSH 的范围判断包含预发布版本：0.2 系列内后续 rc／补丁升级无需精确版本豁免或
+重新发布 Flywheel；0.3 系列及其 alpha／beta／rc 仍在边界之外。宿主可能有更高的
+Node 要求，请使用其支持的运行时。
+
+范围是公开 API 兼容策略，不代表所有未来宿主均已实测。锁定的集成夹具覆盖旧版
+0.2.1-rc.5 Host 和当前 0.2.2-rc.3 Host／SDK；运行时继续检查必需服务、会话身份、
+权限回执与进程清理，服务缺失或回执无效仍明确失败。DSH peer 依赖由宿主提供且
+保持 optional，npm 范围覆盖两个既有预发布系列，不再逐个锁定 rc 版本。
+
+```sh
+npx -y @ckanner/flywheel@latest install
+```
+
+安装器安装同一版本的 CLI、平台二进制、worker、内嵌 skills 和桌面插件，通过
+桌面插件管理接口完成注册并创建受管启动器。根据宿主提示重新加载或重启 DSH。
+Go 包提供 macOS／Linux 的 arm64 与 x64 版本；Linux 包可用不代表已经验证
+Mac 桌面或 Seatbelt 行为。
+
+| 选项或命令 | 用途 |
+|---|---|
+| `--dsh-bin /absolute/path/to/dsh` | 桌面 CLI 不在 PATH 时明确指定 |
+| `--prefix "$HOME/.local"` | 选择可写 npm 前缀，并将其 `bin` 加入 PATH |
+| `--no-dsh` | 明确跳过桌面插件注册 |
+| `flywheel setup --no-global` | 为已有持久安装补全或刷新配置 |
+| `--json` | 返回可供自动化处理的安装报告 |
+
+独立 npm DSH CLI 不能管理保留的 `desktop` profile。普通
+`npm install --global @ckanner/flywheel` 只放置包文件，没有修改 profile、skills
+或凭证的 postinstall。安装报告中 `ok: true` 只表示安装成功，`ready: false`
+仍可能报告缺少原生 CLI 等本地前置条件。完整安装与卸载说明见[快速开始](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/getting-started.md)。
+
+## 准备所选后端
+
+DSH worker 默认使用独立 `sdk` profile。标准桌面与 SDK 在同一 `DSH_HOME` 下
+可以复用 DeepSeek 账号授权存储；自定义 profile 需要加载所选账号服务、provider
+和工具。保留的 `desktop` profile 不能作为 worker profile。
+
+| 后端 | 准备与执行方式 |
+|---|---|
+| DeepSeek Flash | DSH `deepseek-account`，明确指定 `deepseek-flash`；标准共享账号存储不需要额外 API key |
+| DSH ChatGPT | 在 SDK profile 安装并授权所选 ChatGPT 适配器；桌面对话模型不决定 worker 配置 |
+| Codex Pro | worker 导入固定 0.9.0 包的 `dsh-subagent-codex-pro/machine`，使用已安装 Codex CLI 和登录 |
+| Kimi | Go 调用原生 Kimi CLI 及其登录；不使用 ACP 或父模型二次委派 |
+| Claude Code Pro | 可选 0.4.0 peer 和已安装 Claude CLI／登录；默认无阶段选它，详见[接入指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/claude-code-pro.md) |
+
+一个已经记录的 ChatGPT 适配器兼容示例：
+
+```sh
+dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
+```
+
+此固定版本示例不代表当前账号拥有某模型权限。认证和真实模型可用性需要通过
+各后端支持的流程检查。Flywheel 不安装原生模型 CLI、不复制凭证，也不提供订阅额度。
+
+默认 Flash 路由不会在账号失败后回退到 `deepseek-official`；后者是需要明确选择
+的 API-key provider。默认 hard 使用 `codex-pro`，不是名为 `subagent_codex_pro`
+的 DSH provider，也不静默回退到 `codex exec`。详细说明见
+[配置指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/configuration.md)和[模型与推理等级](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/model-policy.md)。
+
+### 可执行文件与环境变量
+
+| 环境变量 | 含义 |
+|---|---|
+| `FLYWHEEL_DSH_BIN` | worker 使用的 DSH 可执行文件 |
+| `FLYWHEEL_DSH_PROFILE` | 独立 SDK profile，默认 `sdk` |
+| `DSH_HOME` | DSH 配置、账号与会话根目录 |
+| `FLYWHEEL_DSH_WORKER` | 显式覆盖 DSH worker |
+| `FLYWHEEL_CODEX_PRO_WORKER` | 显式覆盖 Codex Pro worker |
+| `FLYWHEEL_CLAUDE_CODE_PRO_WORKER` | 显式覆盖可选 Claude worker |
+| `FLYWHEEL_CODEX_BIN` / `CODEX_HOME` | 原生 Codex 可执行文件及已有配置／登录根目录 |
+| `FLYWHEEL_CLAUDE_BIN` / `CLAUDE_CONFIG_DIR` | 原生 Claude 可执行文件及已有配置／登录根目录 |
+| `FLYWHEEL_KIMI_BIN` | 原生 Kimi 可执行文件，默认 `kimi` |
+
+npm 启动器直接解析当前完整包内的 worker。启动引擎的进程必须能看到相关
+可执行文件与环境设置；终端 export 不会更新已经启动的桌面进程。
+
+## 启动任务与使用工作台
+
+在 DSH 输入框输入 `/flywheel-task <目标>`。宿主助手先准备并检查任务契约，
+再调用 `flywheel_launch`。准备阶段使用当前对话模型，执行阶段使用 Flywheel
+配置中的绑定。`/flywheel-new` 只准备方案，`/flywheel-run` 继续已有任务。
+用户明确要求先审阅方案时，这仍是任务授权的一部分。
+
+在内置会话视图旁或其溢出菜单中打开 **Flywheel**。工作台分为三个页面：
+
+| 页面 | 内容 |
+|---|---|
+| 流程画布 | 当前会话任务、当前阶段、证据、阶段执行／重试、角色历史与受管人工介入 |
+| 运行记录 | 已登记运行、已知用量／费用、缺失指标及带条件的运行比较 |
+| 配置 | 自动读取全局／项目配置，分组编辑、显示来源并保护未保存草稿 |
+
+视图自动跟随当前会话的显式任务关联；没有投影时读取精确匹配会话 ID 的最新运行。
+没有任务选择器或路径输入框，其他会话与无归属记录不可见。准备任务使用当前会话的
+`flywheel_control status` 显式关联。位置和操作分组直接显示；单阶段 Review 成功不代表整个任务完成。
+
+自动刷新和其他读取使用会话作用域的只读 Remote，不向对话追加 JSON 命令记录。
+显式修改与未知结果核对仍保留持久命令回执。设置使用固定导航与保存区，直接展示角色会话覆盖和可选用量预算；环境检查归入高级与诊断，原始诊断回执
+不占用日常流程画布。
+
+只有准备记录的任务显示有界调查面板，包含观察、预算、原回执核对、停止与证据报告。
+批准的诊断命令和 HTTP 查询显示实际退出码／状态码、取消与副本收尾。命令需要明确
+host-process 授权，在批准输入的副本运行；副本不是操作系统沙箱。调查报告不代表
+代码交付。详见[调查指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/investigation.md)。
+
+在**设置 → JEV**中，**启用 JEV** 是唯一总开关，默认关闭。选择全局或项目范围，
+打开开关以显示连接字段，填写或确认 System One 地址、固定模型版本与密钥环境
+变量名，再点击**保存修改**。开关先修改草稿，保存后才应用；编辑和保存都不测试
+服务连通性。关闭时沿用原路径，不请求 JEV，也不采集影子快照。
+Task、New 创建的新调查自动继承策略，Run 继续该冻结策略。开启后，JEV 可以选择
+下一项已批准的取证动作、依据已引用的证据跳过
+冗余动作，或提前结束取证进入报告。实施阶段在确认失败后，可以选择合法的局部
+修复、反馈检查、受限重规划或批准的执行绑定。调查与实施共享任务调用额度；反馈
+检查不能代替完整最终验收。
+
+关闭也会禁止已有任务的后续 JEV 调用与采用，同时保留回执和预算；重新开启不会
+改写此前关闭时创建的准备记录。面板分别展示配置状态、本次调查记录的状态、请求、
+已采用动作与有证据依据的效果。任务与节点详情区分已应用的控制决策、已收尾反馈、
+未确认动作和原有基线，保留实际反馈结果、模型绑定前后值和切换原因；配置应用不等于
+新会话已经运行或最终验收通过。高级调用上限、概率阈值与数据类别共用这个总开关，
+没有独立的影子或采用开关。旧影子配置不会自动开启在线决策。
+详见[JEV 决策](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/jev.md)。
+
+
+可见画布会刷新任务发现，运行中的任务会刷新状态。打开视图不启动任务或诊断。
+读取失败时保留最后确认的快照及时间。launch/start/stop 回复丢失或超时表示
+**结果未确认**；同一任务状态完成核对前，后续修改操作保持阻断，界面不会自动重试。
+隐藏视图、关闭 DSH 或移除插件都不会停止独立 Go 任务；应明确停止并等待引擎确认。
+
+### 命令与模型工具
+
+| 入口 | 范围 |
+|---|---|
+| `/flywheel` | 接收 JSON 控制请求的人工命令 |
+| `flywheel_launch` | 启动已准备任务的模型工具，默认 Auto |
+| `flywheel_control` | launch/start/status/stop/investigate/config/doctor 模型工具 |
+| 工作台控件 | 另外提供绑定 revision 的单阶段操作、配置编辑、受管接管及显式交付操作 |
+
+人工启动示例：
+
+```text
+/flywheel {"action":"launch","taskDir":"/repo/docs/my-task","cwd":"/repo","mode":"auto"}
+```
+
+对应 CLI 操作：
+
+```sh
+flywheel control launch --cwd /repo --task-dir /repo/docs/my-task --mode auto
+flywheel control status --cwd /repo --task-dir /repo/docs/my-task
+flywheel control stop --cwd /repo --task-dir /repo/docs/my-task
+flywheel control start --cwd /repo --task-dir /repo/docs/my-task
+```
+
+上述路径是明确的命令参数，不是界面输入框。省略 `cwd` 时使用会话公开的当前目录
+服务；若会话没有记录项目目录，launch/start/stop 必须明确提供绝对 `cwd`。
+输入经过校验后作为 argv 传递，不拼接成 shell 字符串。`ok: true` 表示控制操作
+成功，任务是否完成以状态为准。
+
+宿主准备外层任务 worktree，引擎独立管理 packet 调度和执行目录。新模板开启
+基于声明的并行调度及自动 worktree 管理；已有完整配置省略 scheduler 时仍串行。
+普通 run 负责本地 Git 交付；远端创建和合并 PR 需要显式交付操作，以及候选和授权
+检查。完整说明见[工作流指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/workflow.md)和
+[控制台指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/flow-console.md)。
+
+## 无模型推理的诊断
+
+```sh
+flywheel config inspect --cwd /repo --json
+flywheel doctor --cwd /repo --json
+flywheel doctor --cwd /repo --probe --json
+flywheel-codex-pro-worker --doctor
+```
+
+加上 `--task-dir /repo/docs/my-task` 可检查具体任务的配置。普通 doctor 检查本地
+配置和前置条件；`--probe` 初始化临时 DSH SDK 会话，核对目录与权限后关闭。
+探测使用临时持久化目录，不发送推理 prompt，也不运行任务验收命令；provider
+初始化仍可能查询模型目录。
+
+诊断成功不证明真实账号授权、额度或模型响应。`warn`、`unknown`、`skipped`
+应分别保留，不能视为 pass。诊断和安装不写任务状态，也不创建任务 worktree。
+
+## 运行边界
+
+### 项目归属与历史
+
+稳定的项目工作区用于标识仓库；任务集成目录与 packet worktree 用于实际执行。
+DSH 在项目下建立 Session，再通过公开工作目录服务切换执行目录。只有桌面 Host
+登记工作区归属；独立 SDK worker 不并发改写桌面存储。已有 Session header 与
+未解决回执保留原身份。项目、执行目录和受限沙箱的组合不受支持时，派发前明确
+失败，不静默扩大权限。
+
+scoped 历史可以在同任务、同角色、同范围内续用。Executor、Reviewer、Judge
+与第二意见的历史保持隔离；Reviewer 即使续用自己历史，也必须检查完整当前候选。
+新模板明确选择 scoped，旧配置省略时保留 fresh；Plan 显式
+`resident-session:false` 继续禁止该角色续用。
+
+两种模式都保存调用安全记录。派发、结果或清理未知时阻断新执行。
+Codex／Claude 的公开接口另外提供 Go 持久化 ACK、supervisor journal 和精确
+只读回执恢复；DSH／Kimi 保留自身支持的路径。质量重建阈值默认关闭。
+详见[恢复指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/session-recovery.md)及
+[配对评估](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/session-evaluation.md)。
+
+### 权限与 worker 生命周期
+
+可选 `scheduler.prewarm:true` 使用 DSH worker 的两阶段 `--prewarm` 协议，在验证期间
+初始化一个 SDK；正式调用获准前不创建 Session、不发送 prompt。默认关闭，其他后端
+沿用原启动路径。未使用的 worker 同样必须有界关闭并证明进程组已清理；过期、取消和
+恢复规则见[worker 协议](PROTOCOL.md#dsh-sdk-一次性预热)。
+
+DSH worker 支持 read-only、workspace-write 和显式完全权限，审批设为 never。
+新订阅预设请求完全权限；已有文件缺少权限设置时保留按角色权限。实际策略在
+prompt 前检查。完全权限不代表 OS 沙箱，也不取消宿主静态拒绝、账号限制或
+操作系统权限；Git worktree 同样不是安全沙箱。
+
+临时 SDK overlay 只作用于独立 worker，关闭递归委派、workflow 驱动、自动标题／
+压缩、定时输入及整个 web-tool 包（搜索和抓取）。完全权限不会恢复这些额外模型／
+工具能力；恢复它们需要另外支持计量、取消和目录归属。overlay 不移除桌面工具，
+也不改写提醒存储。
+
+主任务 Codex 调用在 `thread-ready` 时核对完整实际沙箱策略，Go 确认后才继续
+派发；终态回执再次检查。旧版／建议调用保留终态检查。Claude 的原生 init 在
+prompt 之后，不能提供相同的预派发观察；Kimi print 模式也没有本适配器可承诺
+的 OS 沙箱。
+
+成功结果需要可信终态回执和清理确认。外层 worker 退出不能证明 SDK 或 guardian
+已清理。SDK 正常关闭保留两秒用于历史落盘和释放，再进入有界 TERM/KILL 收尾。
+结果丢失时保留证据并阻断自动重放。缺失用量与订阅美元成本保持 unknown，不填零。
+完整 worker 历史不会自动并入父会话轨迹；这些 worker 输入不支持图片和附件。
+
+## 维护与开发
+
+插件显式 `flywheelBinary` 优先于受管安装记录。未设置时，使用
+`~/.config/flywheel/` 中经过验证的启动器；记录不存在时使用本包 `bin/flywheel.js`，
+仅 private 源码测试区保留旧 PATH 后备。
+记录损坏或启动器改变会明确失败。`controlTimeoutMs` 默认 60,000，限制的是桌面
+控制请求，不是整个任务预算。
+
+已有受管启动记录必须与当前包同版。单独更新 DSH 副本后，应运行该版本的 setup
+刷新受管安装；旧记录会明确报错，不把新版界面与旧引擎混用。
+
+升级、移动 npm 前缀、更换 Node 或补充原生 CLI 后，携带所需前缀和桌面 CLI
+选项运行 `flywheel setup --no-global`，再按需重载 DSH。已有配置与修改过的
+skills 会保留。采用新默认值应走显式配置迁移，不通过删除归属记录强行覆盖。
+
+在源码 checkout 中：
+
+```sh
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+```
+
+跨进程与发布检查见[贡献指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/contributing.md)。离线 renderer／SDK
+测试证明被测协议，不证明真实 Mac 窗口几何、账号推理或模型质量收益。
+
+| 参考资料 | 用途 |
+|---|---|
+| [Worker 协议](PROTOCOL.md) | 详细通信、权限、生命周期与错误契约 |
+| [依赖来源](vendor/README.md) | Codex 源码身份、tarball 摘要及可选 Claude 的源码依据 |
+| [JEV 决策](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/jev.md) | 一个总开关控制实际有界决策，保留离线回放与显式评估 |
+| [发布指南](https://github.com/ckanner/flywheel/blob/main/docs/zh-CN/releasing.md) | 构建、安装和发布同一批已验证产物 |
+
+## 许可证
+
+[MIT](LICENSE)。借鉴的 DeepSeek UI 部分及打包依赖保留原声明，见
+[第三方声明](THIRD_PARTY_NOTICES.md)。