@ckanner/flywheel 0.27.3 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## Unreleased
+
+## 0.28.1
+
+- 将 DSH 桌面控制界面迁入顶部原生 `conversation.view` 的 Flywheel 标签，移除遮挡对话和输入框的底部大浮层。按外部 plain-JS 插件规范只加载 React，控件、样式和快照由插件持有，通过公开 StoreHandle 与槽位接入宿主会话生命周期；使用宿主 locale 与语义颜色。配置按可换行卡片展示，桌面对话、轨迹、输入框和原生侧栏继续由 DSH 管理。
+- 补齐界面异常恢复：单会话单个在途请求、启动／停止时锁定目标、忽略旧路径的迟到响应，显示最近确认时间；确定未派发的错误可修正后重试，执行结果未知则查询原目标确认后才允许新的变更。界面开关不自动启动、停止或探测任务。独立 SDK worker 的能力边界与桌面 UI 分开说明。
+
+- 新增仓库内 `release:local` 交互发布入口。维护者可从已固定的 release tag 在本机构建六包，再依次完成候选安装测试、远端 tag／源码／完整性复核、候选上传、registry 安装及 `latest` 提升，无需下载外部候选归档或人工复制发布适配器。新入口位于维护工具 checkout，支持独立的已打 tag 源码 worktree；保留既有标签与 CI 流程，失败时复用原候选。
+
+## 0.28.0
+
+Codex Pro 默认接入。安装和迁移见 [配置指南](docs/configuration.md#codex-pro-默认与旧配置迁移)；源码、测试、CI 和 registry 发布证据分别记录，不用离线通过代替用户 Mac 实测。
+
+- 新增 `codex-pro` Go driver 与独立 Node worker，直接使用 `dsh-subagent-codex-pro@0.8.0` 的公开 machine API。默认 hard 路由使用此插件；DSH Flash 默认执行、Kimi CLI 规划／前端、DSH 原生 GPT 评审保持原角色。旧 `codex` CLI 仅作为用户显式配置的兼容入口。
+- 完整传递模型、effort、目录、权限、取消与 deadline。每次使用 ephemeral 新会话；结果必须同时满足外层 worker 和插件终态／清理要求，正常 app-server 主动终止不冒充调用方取消。
+- 指标保存完整 `codex-pro-receipt`；usage 只有 complete 才进入已知预算，partial/unknown 与美元未知成本保持可见。effort accepted 不伪造为已证实实际强度，不用账号 channel 冒充实际 provider。
+- npm 自动安装精确插件依赖并解析同版本 worker，保持 hoisted dependency、GUI 启动入口、用户配置与 skills 保护；统一六包版本 0.28.0，Node 最低 22.18.0。
+- 本地 doctor 验证插件公开 API、精确版本、Node 和 Codex 命令，不调用模型。配置错误、缺依赖与版本不符明确失败，不自动改走旧 CLI。
+- worker 意外退出或清理回执缺失时明确记录清理未知；所有模型循环保存升级诊断、保留工作区并停止本次运行，禁止自动重试／降级与 Plan 冷启动，避免 guardian 清理期间出现重叠执行。正常错误且清理已确认时仍可重试。
+- 明确 0.8.0 权限边界：插件在运行前验证模型／cwd／权限模式，完整 sandboxPolicy 由 Flywheel 在运行后核对；事后拒绝交付不能阻止自定义 Codex 配置已允许的访问。需运行前完整策略 guard 的环境仍待上游能力。
+- 更新设计、安装／迁移教程、协议和相关技能按钮，增加协议、计量、生命周期、真实 npm 安装与跨进程回归。
+- 补齐 10 个内置 skills 的任务 worktree、分支与绝对路径约定，区分任务集成目录和 packet 候选目录；恢复复用原任务，状态查询／停止保持可用，PR 合并仍由获授权宿主处理。
+- 新增英文 README、入门／配置／工作流、DSH 插件说明、贡献和发行指南，并将英文用户文档纳入 npm 包。补充 CI 不可用时经维护者授权的手动发行流程，沿用精确源码、同一候选、六包 integrity 与 registry 安装门禁。
+
 ## 0.27.3
 
 当前统一 npm 发行目标。本节记录修复内容，不代表本版门禁、registry 发布、latest 提升或用户 Mac 实机验收已完成。0.27.0／0.27.1 未上传 npm 包；0.27.2 的发行在验证阶段主动取消，未上传包，旧 tag 均保留不移动。

package/README.en.md

@@ -0,0 +1,135 @@
+# Flywheel
+
+English | [简体中文](README.md)
+
+Flywheel turns reviewed software requirements into bounded coding tasks with explicit acceptance criteria. A deterministic Go engine runs Plan, Execute, Review, and verification loops. Models propose plans, implement changes, and review candidates; the engine owns state, retries, budgets, workspaces, verification, local Git delivery, and stopping.
+
+This documentation describes the **0.28.1 implementation**. The desktop integration targets the interfaces checked against **DSH Mac 0.2.1-rc.5**. Source changes and GitHub releases do not establish npm availability: check the registry before installing a version. Offline test results also do not establish that a user's Mac, desktop permissions, account, or selected model works.
+
+## Install
+
+You need **Node.js 22.18.0 or later**, npm, Git with a commit identity, and DSH Mac with its desktop-supplied `dsh` command. The default configuration also needs an authenticated Kimi CLI, a Codex installation and login for the hard route, and configured DeepSeek and ChatGPT providers in the DSH SDK profile. Go is needed for source builds and the Go example, but not for npm binary installation.
+
+First check the published version:
+
+```sh
+npm view @ckanner/flywheel version
+```
+
+Once the version you intend to use is available:
+
+```sh
+npx -y @ckanner/flywheel@latest install
+```
+
+Add `--json` for a structured installation result. The installer selects one exact version for the CLI, platform binary, workers, and DSH plugin; installs the ten bundled skills; preserves existing configuration and modified skills; and records a managed desktop launcher. Binary packages cover macOS and Linux on arm64 and amd64.
+
+`ok:true` means installation succeeded. `ready:false` means local diagnostics still found a blocker; these values can occur together. The installer does not install or log in to Kimi/Codex, configure API credentials, or prove model access. Plain `npm install --global @ckanner/flywheel` only installs package files; run `flywheel setup --no-global` afterward to perform explicit user setup.
+
+Follow [Getting started](docs/en/getting-started.md) for prerequisites, desktop versus SDK setup, a runnable first task, and recovery. Use `--prefix "$HOME/.local"` if you need a user-owned npm prefix.
+
+## Default model routes
+
+These bindings are editable starting points, not a model ranking or a performance guarantee. Availability depends on the actual account, adapter, and model catalog.
+
+| Stage or route | Harness | Provider or channel | Model | Requested thinking |
+|---|---|---|---|---|
+| Plan | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
+| Execute: `default` | DSH SDK | `deepseek-official` | `deepseek-flash` | `high` |
+| Execute: `frontend` | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
+| Execute: `hard` | Codex Pro machine API | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
+| Review | DSH SDK | `chatgpt` | `gpt-6.1-sol` | `high`, read-only |
+| Judge | DSH SDK | `chatgpt` | `gpt-6-astra` | `high`, read-only |
+| Intake, optional | DSH SDK | `deepseek-official` | `deepseek-flash` | `low` |
+| Garden, optional | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
+
+Initial requirement preparation is separate: `flywheel-new` runs in the host's current conversation and uses its selected model. Changing `loops.plan` does not change that conversation. The [workflow guide](docs/en/workflow.md) explains preparation model choices and the later engine loops.
+
+The default configuration has no automatic paid fallback across channels and no second judge. Flash's checked DSH effort values are `off`, `low`, `high`, and `max`; there is no `medium` in that adapter baseline. There is no default multimodal route: the current bridge has a text contract, so a model's vision capability alone does not establish attachment support.
+
+## Codex Pro uses the actual plugin runtime
+
+The hard route uses `harness: "codex-pro"`. Its worker directly imports the public `dsh-subagent-codex-pro/machine` API from the exact dependency **`dsh-subagent-codex-pro@0.8.0`**, using protocol 1. The plugin runs Codex app-server with the user's existing Codex installation and login. No parent DSH model is required to delegate the task again.
+
+`subagent_codex_pro` is an external tool name, not a DSH LLM provider. Native DSH GPT calls use the `chatgpt` provider and have a different execution backend. The older `harness: "codex"` driver remains an explicit compatibility choice; the new route does not silently fall back to `codex exec`.
+
+Existing configuration is preserved during upgrades. To adopt the new route, inspect the effective configuration and update the hard route or its model profile explicitly. See [Configuration](docs/en/configuration.md#codex-pro-and-migration).
+
+## From a requirement to a pull request
+
+Use one task integration branch and worktree for a deliverable. Create it **before** preparing contracts with `flywheel-new`; keep the task directory inside that same worktree. The host or user creates this outer worktree. Flywheel then manages the inner packet workspaces.
+
+A normal workflow is:
+
+1. Prepare and review the Spec, task packets, frozen acceptance tests, and actual dry-run evidence in the task worktree.
+2. Commit the substantive contract files. Push the task branch and open a task-level Draft PR through the host or GitHub CLI.
+3. Start Flywheel with the task worktree as `cwd` and its own task directory as `taskDir`.
+4. Let the engine run bounded execution, L1 acceptance, and independent review for each packet; then run milestone L2/L3 and Judge.
+5. Push the completed result, verify the current PR head, review it, and merge under the repository's chosen policy.
+
+For example, from an already prepared task worktree:
+
+```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 start --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+flywheel control status --cwd "$PWD" --task-dir "$PWD/docs/my-feature"
+```
+
+Packet delivery is a **local Git operation**. After evidence matches the current candidate, the engine commits the packet and fast-forwards it into the branch checked out at `cwd`. With the recommended layout, that is the task integration branch. Flywheel does not itself push, create GitHub PRs, wait for remote CI, merge remote PRs, or publish releases. Those operations belong to the authorized host or user. See [Workflow](docs/en/workflow.md) for commands, directory ownership, and merge timing.
+
+### Desktop task controls
+
+From `0.28.1`, the native **Flywheel** conversation view appears alongside Chat and Trajectory, preserving DSH's composer, model selector, and right sidebar. Version `0.28.0` uses the old composer popup; upgrade the CLI and desktop plugin to the same new version. Select a prepared task directory and its repository to inspect progress, intervention, effective models, and diagnostics, or explicitly start, refresh, or stop it.
+
+The view retains session-scoped drafts while the host retains the session binding and shows snapshots with their refresh time. It does not discover tasks or poll automatically. An unconfirmed start/stop outcome requires a successful refresh of the same task before further mutations; closing or switching the view does not stop the independent engine. DSH's trajectory keeps its parent-session records, without automatically merging independent worker history. Desktop capabilities and SDK worker policy have separate scopes; see the [plugin guide](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md#use-the-desktop-controls).
+
+## Verification and operating boundaries
+
+L1 validates a packet; L2/L3 validate integration and user paths at milestone scope. Review examines the actual candidate and acceptance evidence independently of the executor transcript. Candidate or contract changes invalidate prior evidence. Completion requires verified Git delivery and persisted state; an agent's claim that it finished is insufficient.
+
+Keep these boundaries in mind:
+
+- **Worktrees isolate Git work, not process permissions.** Packet worktree creation can currently fall back to in-place execution. There is no engine option requiring isolation in every case. Skills check the recommended task location; direct CLI/GUI use does not execute those skill checks.
+- **Permissions depend on the harness.** DSH and Codex paths request explicit permissions. Kimi's current CLI integration does not provide an OS-level read-only or workspace sandbox guarantee.
+- **Codex Pro's complete policy check is after the run.** The plugin checks model, directory, approval, and sandbox mode before a turn. Flywheel validates the full returned policy afterward, allowing the workspace and standard Codex temporary directories. Additional external write roots, enabled network access, or unconfirmed policy prevent acceptance. This check cannot prevent access already allowed by custom Codex configuration.
+- **Cleanup needs evidence.** A worker exiting does not prove that the plugin's separate app-server or guardian processes stopped. An unconfirmed cleanup result escalates and stops the run; inspect and resolve it before resuming.
+- **Unknown usage remains unknown.** Missing usage or monetary cost is not zero. Soft budgets report uncertainty; hard budgets stop when unknown usage makes the limit unverifiable.
+- **Preflight is not a model smoke test.** `doctor --probe` initializes supported SDK sessions without an inference prompt. Codex Pro checks import/version/protocol and local commands, leaving actual model, authorization, and full runtime policy unverified.
+
+The engine alone writes `state.json`, atomically with revision checks. Do not edit it to force progress or delete retained work to make a retry look clean.
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [Getting started](docs/en/getting-started.md) | Install, configure, diagnose, run a small task, stop, and recover |
+| [Workflow](docs/en/workflow.md) | Preparation models, task and packet worktrees, Draft PRs, completion, and merge policy |
+| [Configuration](docs/en/configuration.md) | File precedence, profiles, providers, channels, Codex Pro, and diagnostics |
+| [Chinese documentation](README.md) | Default language and additional implementation detail |
+| [System design](https://github.com/ckanner/flywheel/blob/main/docs/design.md) (Chinese) | Authoritative design and invariants |
+| [DSH plugin](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md) / [protocol](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md) (protocol in Chinese) | Desktop control surface, workers, permissions, and lifecycle |
+| [Release guide](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md) | Candidate artifacts, registry verification, and release recovery |
+| [Contributing](https://github.com/ckanner/flywheel/blob/main/docs/contributing.md) | Development workflow, validation, and contribution boundaries |
+
+The English guides cover current operation. Historical design and validation ledgers remain in their original language. Source and design links are intended for browsing the repository; the npm package contains selected runtime and user documentation rather than the entire repository.
+
+## Development
+
+Read [AGENTS.md](https://github.com/ckanner/flywheel/blob/main/AGENTS.md) and the [design](https://github.com/ckanner/flywheel/blob/main/docs/design.md) before changing the engine. Source development needs Go 1.27 or later and Node.js 22.18.0 or later. Relevant local gates include:
+
+```sh
+make quality-gate
+npm --prefix plugins/dsh ci --ignore-scripts
+npm --prefix plugins/dsh run check
+FLYWHEEL_TEST_NODE_BRIDGE=1 go test ./internal/drivers -run '^Test(DSH|CodexPro)NodeWorkerOfflineBridge$' -count=1
+npm test
+```
+
+These commands cover local code and protocol behavior. Real desktop UI, macOS permissions, account access, and model inference require separate, recorded testing in the intended environment.
+
+Maintainers can build the six packages from a tagged source checkout and use the repository's `npm run release:local` command for interactive publication. No prebuilt archive is required. The command runs candidate and registry installation checks before promoting `latest`; see [local publication from source](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md#local-build-and-publication-from-source) for the exact worktree and authentication steps.
+
+## License status
+
+The package currently declares **`UNLICENSED`**. An open-source license has not been selected; these English documents do not change the repository's visibility or licensing status.

package/README.md

@@ -1,24 +1,26 @@
 # Flywheel（飞轮）
 
+[English](README.en.md) · 简体中文
+
 Flywheel 用确定性 Go 引擎驱动 Plan、Execute、Review 和分层验收，把已经明确的需求变成有边界、可验证、可持久化的软件交付。模型负责规划、实现和评审；引擎负责状态、重试、预算、工作区、验收、提交与停止。
 
-当前 **v0.27.3 实施版**以 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务可走独立 Codex CLI。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
+当前 **v0.28.1 实施版**以 DSH Mac 桌面为入口：Kimi CLI 规划，DSH 原生 DeepSeek Flash 执行，DSH 原生 GPT 评审，较难的执行任务默认走 Codex Pro 插件的公开 machine API。DSH 插件提供控制面板、配置查看和安装预检；具名 model profiles 可复用于不同阶段，Go 仍是唯一状态所有者。设计依据见 [docs/design.md](docs/design.md)，仓库约束见 [AGENTS.md](AGENTS.md)。
 
-**本教程适用于 0.27.3 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
+**本教程适用于 0.28.0 及以后的完整 npm 发行版。** 安装前用 `npm view @ckanner/flywheel version` 确认 registry 的 latest 已更新到所需版本；源码合并或 GitHub Release 不代表 npm 已发行。旧 0.22.1 没有本教程使用的安装与 DSH 接口，当前发行状态见[发行记录](docs/releasing.md#3-失败恢复)。
 
-测试结果与实机边界见[验证记录](docs/validation/2026-11-01-npm-installation.md)。旧版本的选型、维护机环境与演练记录保存在[历史设计](docs/design-history-v0.24.md)，不代表当前默认值或用户机器状态。
+本轮插件接入测试与实机边界见[验证记录](docs/validation/2026-11-03-codex-pro-default.md)，既有 npm 发行证据见[安装验证](docs/validation/2026-11-01-npm-installation.md)。旧版本的选型、维护机环境与演练记录保存在[历史设计](docs/design-history-v0.24.md)，不代表当前默认值或用户机器状态。
 
 首次使用请按 [Mac 安装与首个任务教程](docs/getting-started.md) 完成安装、配置、无推理检查和小任务验收。本文保留各接口与设计边界的速查。
 
 ## 1. 一条命令安装
 
-已有 **Node.js 22 或更高、npm 和 DSH Mac 桌面及其 `dsh` 命令**后，在终端运行：
+已有 **Node.js 22.18.0 或更高、npm 和 DSH Mac 桌面及其 `dsh` 命令**后，在终端运行：
 
 ```sh
 npx -y @ckanner/flywheel@latest install
 ```
 
-Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制和 DSH worker 装到 npm 全局目录，安装 10 个内嵌 skills，再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
+Agent 可在同一命令后加 `--json`，读取一个结构化结果。安装器把本次解析到的**精确版本**的 CLI、对应平台 Go 二进制、DSH worker 和 Codex Pro worker（含精确版本的插件依赖）装到 npm 全局目录，安装 10 个内嵌 skills，再将同版本 DSH 插件注册到桌面 profile 并核对版本。无需下载压缩包、克隆源码或自行编译 Go。
 
 安装完成会显示每个步骤和本地预检结果。`ok:true` 表示软件安装成功；`ready:false` 表示当前配置仍有运行阻断项，例如缺少 Kimi／Codex CLI，二者可以同时出现。安装器不替换现有 DSH，也不安装或代登录 Kimi／Codex，不代配 DeepSeek API 凭证。运行真实任务前需完成所选渠道的准备。
 
@@ -44,7 +46,7 @@ npx -y @ckanner/flywheel@latest install --prefix "$HOME/.local"
 dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 ```
 
-这是已核对的 adapter 版本示例；采用其他版本前按其文档检查兼容性。按 provider 自身的正常流程完成授权，保持所选 `DSH_HOME` 与配置来源一致。安装 adapter 不会自动迁移桌面凭证，也不证明账号可以调用默认表里的所有模型。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider；Flywheel 的 `hard` 路由使用独立 Codex CLI。
+这是已核对的 adapter 版本示例；采用其他版本前按其文档检查兼容性。按 provider 自身的正常流程完成授权，保持所选 `DSH_HOME` 与配置来源一致。安装 adapter 不会自动迁移桌面凭证，也不证明账号可以调用默认表里的所有模型。`subagent_codex_pro` 是外部 agent 工具，不是这个 SDK 入口的 LLM provider。Flywheel 的 `hard` 路由通过独立 worker 直接导入 `dsh-subagent-codex-pro@0.8.0` 的公开 `./machine` 入口，复用插件运行时；它不创建 DSH 父模型再次委派。插件内部仍运行 Codex app-server，并使用用户已有的 Codex 登录。
 
 ### worker 入口配置
 
@@ -55,8 +57,11 @@ dsh plugin --profile sdk add dsh-plugin-chatgpt@0.1.17
 | `FLYWHEEL_DSH_PROFILE` | `sdk`；必须是 SDK profile，不能是 `desktop` |
 | `DSH_HOME` | 交给 DSH 的自定义配置根；不设置时沿用 DSH 自己的默认行为 |
 | `FLYWHEEL_KIMI_BIN` | PATH 中的 `kimi`；可指定 Kimi CLI 的绝对路径 |
+| `FLYWHEEL_CODEX_PRO_WORKER` | npm 启动器解析同版本包的 Codex Pro worker；独立 Go 二进制默认查找 `flywheel-codex-pro-worker` |
+| `FLYWHEEL_CODEX_BIN` | 插件内部使用的 Codex 可执行路径；默认 `codex` |
+| `CODEX_HOME` | 可选的 Codex 配置／登录目录，交给插件使用；不复制账号凭证 |
 
-Codex CLI 通过 PATH 中的 `codex` 启动。所有选定 CLI、Node 与账户配置必须对**启动 Go 引擎的进程环境**可见。
+旧 `harness: "codex"` 仍是显式兼容路径，使用 PATH 中的 `codex exec`；新默认不会自动退回它。所有选定 CLI、Node 与账户配置必须对**启动 Go 引擎的进程环境**可见。
 
 安装器自动生成 `~/.config/flywheel/npm-launcher` 和 `installation.json`：记录绝对 Node／CLI 路径、已核对的 DSH 入口及安装时可见的工具 PATH。桌面插件未显式配置 `flywheelBinary` 时，读取这份安装记录，校验 launcher 是普通可执行文件且 SHA-256 匹配后使用。**无需手写 GUI 启动脚本或修改 profile 配置。**
 
@@ -87,7 +92,7 @@ flywheel doctor --cwd "$PWD" --probe --json
 | Plan | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high`，匹配身份后可恢复会话 |
 | Execute `default` | DSH SDK | `deepseek-official` | `deepseek-flash` | `high` |
 | Execute `frontend` | Kimi CLI | `kimi-subscription` | `kimi-code/k3.1-pro` | `high` |
-| Execute `hard` | Codex CLI | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
+| Execute `hard` | Codex Pro machine API | `chatgpt-subscription` | `gpt-6.1-sol` | `high` |
 | Review | DSH SDK | `chatgpt` | `gpt-6.1-sol` | `high`，只读 |
 | Judge | DSH SDK | `chatgpt` | `gpt-6-astra` | `high`，里程碑终验 |
 | Intake | DSH SDK | `deepseek-official` | `deepseek-flash` | `low` |
@@ -95,7 +100,7 @@ flywheel doctor --cwd "$PWD" --probe --json
 
 这些是可编辑的初始绑定，并非模型排名或性能承诺。DeepSeek 只用 Flash；当前 Mac rc.5 的合法 effort 为 `off/low/high/max`，没有 `medium`。双 judge 默认关闭，也不默认跨渠道付费降级。`multimodal` 暂无默认绑定：当前 bridge 只有文本契约，模型名称或目录里的 vision 标记不能证明附件已正确传递。
 
-Kimi 使用原生 CLI print/stream-json，不使用 ACP；恢复的是会话历史，不是常驻后台进程。该模式不提供本适配器可宣称的 OS 级只读／工作区沙箱，worktree 只是代码隔离。DSH/Codex 使用明确的 workspace-write 或 read-only 与禁止扩权策略。具体账号的可用模型、额度和使用授权需要由所选服务确认。
+Kimi 使用原生 CLI print/stream-json，不使用 ACP；恢复的是会话历史，不是常驻后台进程。该模式不提供本适配器可宣称的 OS 级只读／工作区沙箱，worktree 只是代码隔离。DSH/Codex 使用明确的 workspace-write 或 read-only 与 never 审批策略。Codex Pro 在运行前核对模型、目录和沙箱模式，Flywheel 在结果返回后检查完整策略；工作区写入允许 Codex 标准临时目录，额外工作区外 roots 或启用网络的策略不能通过交付资格检查。这是事后校验，不能阻止自定义 Codex 配置已允许的访问；要求运行前完整策略阻止的环境需等待上游公开 guard。具体账号的可用模型、额度和使用授权需要由所选服务确认。
 
 usage 或美元成本未上报时保留 unknown，不能把订阅调用记成免费。默认 soft token budget 会报告未知量；hard budget 无法证明未知用量未超额时停止。汇总数字是已知量下限。
 
@@ -103,6 +108,8 @@ usage 或美元成本未上报时保留 unknown，不能把订阅调用记成免
 
 配置按**第一个存在的完整文件**选择，不逐字段合并：任务目录 → 项目根 → 全局 `~/.config/flywheel/flywheel.config.json` → 二进制内嵌模板；`FLYWHEEL_CONFIG` 可指定全局配置路径。已有文件不会因升级自动改写。
 
+从 0.27.x 升级要采用插件路径时，在实际生效配置中将 `routes.hard.harness` 从 `codex` 改为 `codex-pro`；具名 profile 则修改对应定义。保留 `model`、`thinking` 和 `channel`，不要把 `subagent_codex_pro` 填入 provider。安装依赖不自动迁移已有配置，也不会默默替换旧后端。
+
 可用新二进制查看模板，再审阅并迁移自己的配置：
 
 ```sh
@@ -115,9 +122,13 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/my-task --json
 
 ## 4. 创建、运行和观察任务
 
+业务仓库建议先建立任务集成分支与独立 worktree；准备契约、Draft PR 和人工合并的完整流程见[从需求准备到 PR 合并](docs/workflow.md)。引擎的单元合并目标是启动 checkout 当前所在分支，GitHub PR 操作由使用者或获授权的宿主执行。
+
+准备阶段由当前 DSH 对话模型生成需求契约，`loops.plan` 只控制引擎启动后的规划／修订。复杂需求建议先用已授权的 `gpt-6-astra`、`high` 生成可审阅草稿；简单明确的任务可沿用 Flash，避免每个 packet 都重复调用昂贵规划模型。
+
 先在目标 Git 仓库准备并审阅 `docs/<slug>/` 中的 Spec、packet 与配置：需求编号、L1/L2/L3 命令、禁止修改的验收路径和失败出口都应明确。模板可通过 `flywheel template` 查看；可选的 `flywheel-new` skill 用于辅助生成，最终仍由人确认契约。不要把 DSH 面板当成需求生成器。
 
-桌面面板位于会话输入区底部的 **Flywheel** 按钮。输入仓库路径后可查看配置、检查环境或执行 SDK 无推理探测；启动、刷新和停止还需绝对任务路径。面板展示实际阶段绑定、检查项、完整 packet 列表与未知用量，原始 JSON 可按需展开。也可使用人工命令：
+从 `0.28.1` 开始，桌面控制面接入顶部“对话／轨迹”旁的原生 **Flywheel** 会话视图，保留 DSH 输入区、模型选择器和右侧栏。`0.28.0` 仍是旧底部弹层，需把 CLI 与桌面插件同版升级。输入仓库路径后可查看配置、检查环境或执行 SDK 无推理探测；启动、刷新和停止还需绝对任务路径。视图展示最近刷新的任务结果、完整 packet 列表与未知用量，模型配置和诊断按需查看，原始 JSON 默认折叠。也可使用人工命令：
 
 ```text
 /flywheel {"action":"status","taskDir":"/repo/docs/my-task","cwd":"/repo"}
@@ -137,6 +148,8 @@ flywheel control doctor --task-dir /repo/docs/my-task --cwd /repo --probe
 
 控制接口始终返回一个 protocol 1 JSON；`ok` 表示控制操作成功，任务是否完成应看 `state.status`。`config` 返回 `configuration`，`doctor` 返回 `diagnostic`；诊断有阻断项时保留完整报告并返回退出码 1，不能当成空白传输错误。若启动就绪超时，后台引擎可能仍在加载：先刷新状态和查看日志，不要另起重复任务。
 
+视图草稿按 DSH 会话保留，展示的是带刷新时间的快照；不自动发现任务或轮询。启动／停止结果未确认时，先刷新同一任务再恢复操作。原生轨迹保留父会话已有记录，独立 worker 历史不会自动合并。桌面原生能力与 SDK worker 的临时策略属于不同范围，详见[桌面视图与运行边界](plugins/dsh/README.md)。
+
 原有前台／单步 CLI 仍可使用；这些命令应在目标仓库根目录运行：
 
 ```sh
@@ -196,11 +209,11 @@ DSH 检查包括离线 worker 生命周期、事件与 usage 折叠、控制入
 
 React DOM 与安装协议桩不代替 Mac 桌面验证。当前 Linux 环境没有可用的完整原生沙箱，SDK probe 在 prompt 前正确拒绝；这项结果证明拒绝路径，不能冒充 Mac Seatbelt 成功。
 
-**尚需在用户 Mac 验证**：桌面安装与 UI 渲染、Seatbelt 探针、GUI 环境中的 CLI／凭证可见性、真实 Flash/GPT/Kimi/Codex 响应，以及真实机器重启后的恢复。当前不支持 DSH worker resume、附件传输、外部 Codex Pro adapter 消费或自动多 agent Teams 调度。
+**尚需在用户 Mac 验证**：桌面安装与 UI 渲染、Seatbelt 探针、GUI 环境中的 CLI／凭证可见性、真实 Flash/GPT/Kimi/Codex 响应，以及真实机器重启后的恢复。当前不支持 DSH worker resume、附件传输或自动多 agent Teams 调度。Codex Pro 已通过公开 API 接入，完整策略的事后检查边界见配置指南。
 
 ## 7. 开发与备用构建
 
-普通用户使用上面的 npm 安装流程。开发者需要 Go 1.27 或更高、Node.js 22 或更高及 Git，在仓库根构建：
+普通用户使用上面的 npm 安装流程。开发者需要 Go 1.27 或更高、Node.js 22.18.0 或更高及 Git，在仓库根构建：
 
 ```sh
 go build -o ./bin/flywheel ./cmd/flywheel
@@ -211,13 +224,18 @@ npm run build:npm
 
 `build:npm` 先构建 worker，再在隔离目录打包 meta、四个平台包和 DSH 插件，输出到 `dist-npm/`。六个包版本必须一致；本地 tarball 和 Actions artifact 用于开发、验证或备用分发，不是日常用户的安装入口，也不等于已签名的 Mac 安装程序。源码构建及开发模式 skills 说明见[教程末节](docs/getting-started.md#9-开发与备用构建)。
 
+维护者可以直接拉取源码，在本机构建后运行仓库内的 `npm run release:local` 完成交互发布，无需下载预构建归档。工具会运行候选和 registry 安装测试，再按六包依赖顺序提升 `latest`；已存在 release tag 的具体步骤见[从源码本地发布](https://github.com/ckanner/flywheel/blob/main/docs/releasing.md#5-从源码本地构建并发布)。
+
 ## 文档与代码入口
 
+英文用户文档包括 [入门](docs/en/getting-started.md)、[配置](docs/en/configuration.md)、[工作流](docs/en/workflow.md) 和 [DSH 插件说明](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.en.md)。贡献者从 [Contributing](https://github.com/ckanner/flywheel/blob/main/docs/contributing.md) 开始，发行维护者见 [Releasing](https://github.com/ckanner/flywheel/blob/main/docs/en/releasing.md)。
+
 | 路径 | 内容 |
 |---|---|
 | [docs/getting-started.md](docs/getting-started.md) | Mac 安装、首个任务、配置迁移与排错 |
 | [docs/design.md](docs/design.md) | 权威设计、不变量、闭环与边界 |
 | [docs/configuration.md](docs/configuration.md) | profiles、阶段覆盖、provider／channel 与预检语义 |
+| [docs/plans/2026-11-03-codex-pro-default.md](docs/plans/2026-11-03-codex-pro-default.md) | 默认插件接入与验收计划 |
 | [docs/plans/2026-11-01-dsh-integration.md](docs/plans/2026-11-01-dsh-integration.md) | 本轮实施和验收记录 |
 | [docs/plans/2026-11-01-model-profiles-preflight.md](docs/plans/2026-11-01-model-profiles-preflight.md) | 配置、预检与面板后续实施计划 |
 | [docs/plans/2026-11-01-npm-installation.md](docs/plans/2026-11-01-npm-installation.md) | npm 安装、GUI 入口与发行验证计划 |
@@ -228,3 +246,7 @@ npm run build:npm
 | [internal/drivers/](internal/drivers/) | DSH／Kimi／Codex 与保留的兼容 driver |
 | [internal/verify/](internal/verify/) | 确定性验收、边界、Git 持久化与工作区 |
 | [docs/design-history-v0.24.md](docs/design-history-v0.24.md) | 历史设计与当时的研究、环境记录 |
+
+## 许可证
+
+当前源码与 Flywheel npm 包标记为 `UNLICENSED`，尚未授予开源许可证。英文文档和公开 npm 分发不改变这一状态；正式开源时需由维护者选择许可证，并同步源码声明与全部包的 metadata。第三方依赖遵循各自许可证。

package/bin/flywheel-codex-pro-worker.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
+"use strict";
+
+const { loadCodexProWorkerPath, runChild } = require("./runtime.js");
+
+async function main() {
+  return runChild(process.execPath, [loadCodexProWorkerPath(), ...process.argv.slice(2)], {
+    label: "flywheel-codex-pro-worker",
+  });
+}
+
+main().then(code => { process.exitCode = code; }).catch(error => {
+  console.error(`flywheel-codex-pro-worker: ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/flywheel.js

@@ -2,13 +2,14 @@
 // Copyright (c) 2026 ckanner. SPDX-License-Identifier: UNLICENSED
 "use strict";
 
-const { loadNativePath, loadWorkerPath, runChild } = require("./runtime.js");
+const { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild } = require("./runtime.js");
 
 async function main() {
   const args = process.argv.slice(2);
   if (args[0] === "install" || args[0] === "setup") {
     return require("../npm/install.js").main(args.slice(1));
   }
+  assertSupportedNode();
 
   const env = { ...process.env };
   // An npm dependency's bin is not necessarily on a desktop application's
@@ -17,6 +18,9 @@ async function main() {
   if (env.FLYWHEEL_DSH_WORKER === undefined) {
     env.FLYWHEEL_DSH_WORKER = loadWorkerPath();
   }
+  if (env.FLYWHEEL_CODEX_PRO_WORKER === undefined) {
+    env.FLYWHEEL_CODEX_PRO_WORKER = loadCodexProWorkerPath();
+  }
   return runChild(loadNativePath(), args, { env });
 }
 

package/bin/runtime.js

@@ -47,6 +47,19 @@ function loadWorkerPath() {
     "the matching @ckanner/dsh-plugin-flywheel worker is missing; reinstall @ckanner/flywheel");
 }
 
+function loadCodexProWorkerPath() {
+  const name = "@ckanner/dsh-plugin-flywheel";
+  return packageEntry(name, "codex-pro-worker", ownPackage.dependencies?.[name],
+    "the matching @ckanner/dsh-plugin-flywheel Codex Pro worker is missing; reinstall @ckanner/flywheel");
+}
+
+function assertSupportedNode(version = process.versions.node) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:$|-)/.exec(version);
+  if (!match || Number(match[1]) < 22 || (Number(match[1]) === 22 && Number(match[2]) < 18)) {
+    throw new Error("Node.js 22.18.0 or newer is required");
+  }
+}
+
 function signalExitCode(signal) {
   return constants.signals[signal] ? 128 + constants.signals[signal] : 1;
 }
@@ -84,4 +97,4 @@ function runChild(command, args, { env = process.env, cwd, label = "flywheel" }
   });
 }
 
-module.exports = { loadNativePath, loadWorkerPath, runChild };
+module.exports = { loadNativePath, loadWorkerPath, loadCodexProWorkerPath, assertSupportedNode, runChild };

package/docs/configuration.md

@@ -1,5 +1,7 @@
 # 模型 profiles、阶段绑定与预检
 
+[English](en/configuration.md) · 简体中文
+
 Flywheel 在启动时加载一份完整配置，再把模型 profile 展开成每个阶段的实际绑定。模型选择是显式配置，不由另一个模型替你决定；修改配置后需要重新启动引擎。
 
 ## 1. 配置来源
@@ -20,14 +22,41 @@ flywheel config inspect --cwd /repo --task-dir /repo/docs/task --json
 
 | 字段 | 含义 | 示例 |
 |---|---|---|
-| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex` |
+| `harness` | 实际工具循环与进程后端 | `dsh`、`kimi`、`codex-pro`；`codex` 为显式旧 CLI 路径 |
 | `provider` | DSH SDK 已注册的 LLM adapter ID；仅 DSH 使用 | `deepseek-official`、`chatgpt` |
 | `channel` | 配置中的凭证／后备／计量渠道名称 | `deepseek-sdk`、`chatgpt-sdk`、`kimi-subscription` |
 | `profile` | 当前 Flywheel 配置内的一组模型字段引用 | `flash`、`gpt-review`、`kimi` |
 
 Flywheel 的 model profile 与 DSH 的 `sdk`／`desktop` profile 是两件事。前者复用模型定义，后者决定宿主实际加载的插件和授权配置。channel 别名本身不会切换 DSH 账号；给同一个 provider 起两个 channel 名称不等于拥有两份独立订阅或额度。
 
-DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider` → 旧 `channel` 名解析。前两者都明确配置而不相等时拒绝加载。兼容旧内联配置的最后一项只适用于 DSH；Codex 和 Kimi 使用自己的 CLI 登录状态，不接受一个会被静默忽略的 provider。
+DSH 的实际 provider 按 `binding.provider` → `channels[channel].provider` → 旧 `channel` 名解析。前两者都明确配置而不相等时拒绝加载。兼容旧内联配置的最后一项只适用于 DSH；Codex Pro／旧 Codex CLI 和 Kimi 使用自己的登录状态，不接受一个会被静默忽略的 provider。
+
+### Codex Pro 默认与旧配置迁移
+
+0.28.0 的内嵌 hard 路由使用插件路径。下面是需放入自己完整配置的绑定片段，不是可替换全部配置的文件：
+
+```json
+{
+  "routes": {
+    "hard": {
+      "harness": "codex-pro",
+      "model": "gpt-6.1-sol",
+      "channel": "chatgpt-subscription",
+      "thinking": "high"
+    }
+  }
+}
+```
+
+完整 profiles 模板使用 `profiles.codex-pro`，hard 路由引用它。插件依赖 `dsh-subagent-codex-pro@0.8.0` 由 npm 安装；worker 直接导入其公开 `dsh-subagent-codex-pro/machine` API，内部仍使用 Codex app-server 和用户已有登录。它不是 DSH LLM provider，也不需要父模型调用 `subagent_codex_pro`。缺少插件或回执不符会失败，不自动回退 `codex exec`。
+
+已有配置不自动改写。要从旧路径迁移，在 `config inspect` 显示的有效文件中修改 inline harness 或其 profile，保留所选 model／thinking／channel，然后重启引擎。保留 `harness: "codex"` 则明确继续使用旧 CLI。`codex-pro` 必须提供 model 和 channel，不沿用旧 Codex driver 的隐式模型；`resident-session: true` 会在加载时拒绝。执行／评审每次创建 ephemeral 新会话，thinking 省略时为 high。
+
+`FLYWHEEL_CODEX_PRO_WORKER` 可显式指定 worker；通常由 npm 启动器解析同版本依赖。`FLYWHEEL_CODEX_BIN` 指定插件内部的 Codex 程序，默认 PATH 中的 `codex`；`CODEX_HOME` 可选择既有配置与登录目录。自定义环境需对启动引擎的进程可见，安装器不会复制凭证。
+
+插件在运行前确认模型、cwd、approval 和沙箱模式；Flywheel 在完整结果返回后检查实际策略及进程终态。workspace-write 允许工作区及 Codex 标准临时目录；额外的工作区外 writable roots、网络启用或不能确认的策略不能进入成功验收。**该完整策略检查发生在运行后，不能阻止自定义 Codex 配置已允许的访问。** 要求完整策略在任务前被拒绝的环境，应等待上游公开 pre-turn guard；doctor 会持续提示这一边界。
+
+指标的 `codex-pro-receipt` 保存完整 machine receipt，包含请求、实际配置、thread/turn、进程、清理、usage 和失败事实。effort 的 `accepted: true` 不等于服务器证明了实际推理强度，`effectiveEffort` 保留 null。仅 `usage.status: "complete"` 的本次增量进入已知预算；partial/unknown 原样留在回执并计入未知调用。插件不提供实际美元成本，原始 cost 保持 unknown；Flywheel 只有在用户显式配置 pricing 且 usage 完整时才能另行估算，估算不等于订阅账单。
 
 ## 3. 从完整示例开始
 
@@ -113,6 +142,8 @@ flywheel doctor --cwd /repo --task-dir /repo/docs/task --probe --json
 
 本地检查确认命令可用、版本响应可靠，以及声明的环境变量存在且非空，不显示变量值。`--probe` 才启动 DSH worker 验证 adapter 接受配置、cwd、完整沙箱、approval policy 和 SDK 正常关闭。相同 provider、channel、model、effort、cwd 和权限的探测去重；不同账号别名或读写权限不能相互代替。整体验证预算 40 秒，另留进程清理窗口。
 
+Codex Pro 本地检查额外实际导入公开 machine API，核对精确 0.8.0／协议 1、Node >=22.18.0 以及 Codex 命令版本；同一 worker 只查一次。`--probe` 不为此路径发送任务，实际模型、effort 与完整权限保持 unknown；它不会把成功导入插件当成账号、沙箱或推理能力已经验证。
+
 | 状态 | 解释 |
 |---|---|
 | `pass` | 本项已取得对应证据；只对该项有效 |