@ckanner/flywheel 0.27.3 → 0.28.0

package/docs/workflow.md

@@ -0,0 +1,199 @@
+# 从需求准备到 PR 合并
+
+[English](en/workflow.md) · 简体中文
+
+本文描述 **Flywheel 0.28.0**的推荐工作流。新默认 `hard` 路由使用
+Codex Pro 插件 machine API；源码存在不代表 npm `latest` 已更新，安装状态见
+[发行指南](releasing.md)。下列命令是操作示例，不会因阅读本文自动执行。
+
+建议先建立任务集成分支及独立 worktree，再准备契约、开 Draft PR、运行引擎。
+Flywheel 将通过验收的 packet 合入任务分支；整个需求通过终验和远端检查后，
+再由人或已获授权的宿主 Agent 合并 PR 到 `main`。
+
+## 1. 选择准备阶段的模型
+
+`flywheel-new` 使用当前 DSH 对话的模型。`loops.plan` 只控制引擎启动后的规划
+和修订，不会替准备阶段切换模型。建议按需求的不确定性选择：
+
+| 准备任务 | DSH Provider / 模型 | 思考等级 |
+|---|---|---|
+| 跨模块设计、协议与生命周期、复杂边界和验收设计 | `chatgpt` / `gpt-6-astra` | `high` |
+| 范围清楚、已有代码与模式可参考的普通功能 | `chatgpt` / `gpt-6.1-sol` | `high` |
+| 很明确的小修复、文档或重复模式的补充 | `deepseek-official` / `deepseek-flash` | `high` |
+
+这是工程起点，不是本项目完成的模型 benchmark。准备错误可能影响多个 packet，
+所以复杂需求值得在冻结契约前多检查一次；不必为每个小单元重复进行完整架构规划。
+先使用 `high`，遇到仍未解决的关键设计问题，再对那次分析选择模型支持的更高档位。
+[OpenAI reasoning 指南](https://developers.openai.com/api/docs/guides/reasoning)
+说明 effort 的速度、用量与推理投入取舍；它不能证明本项目的最优档位。
+
+开始前在 DSH 当前账号的模型目录核对 provider、精确模型 ID 和可选 effort。
+目录与实际请求支持也可能有差异，不能把配置示例当成账号可用性证明。
+`Codex Pro` 是插件名，不会自动选择 Pro 模型或最高思考档。
+默认的运行期 Plan 仍为 Kimi CLI `kimi-code/k3.1-pro / high`，详见
+[默认配置](../templates/flywheel.config.example.json)；Kimi 别名也须在本机可用。
+
+## 2. 先建立任务集成 worktree
+
+假设当前位于业务仓库根目录，远端为 `origin`、目标分支为 `main`。
+将示例任务名与目录名替换为本次需求；不同任务使用不同名称。
+
+```sh
+git status --short
+git fetch origin
+git worktree add -b task/my-feature ../repo-my-feature origin/main
+cd ../repo-my-feature
+git branch --show-current
+```
+
+最后应显示 `task/my-feature`。这组命令创建新分支和新目录，不切换或重置原
+checkout 的分支。若分支或目录已存在，先检查其用途，不用强制参数覆盖。
+在 DSH 中打开新目录 `repo-my-feature`，之后的契约、预检、启动和 PR 操作都以
+这个任务 worktree 为工作目录。运行中不要切换该目录的分支或混入别的任务。
+
+引擎中的“主 checkout”指传入的 `--cwd`，不固定指 `main`。单元通过后执行
+`git merge --ff-only` 合回这个 checkout 当前所在分支。因此从任务分支启动，
+内部 packet 就合入 `task/my-feature`；从 `main` 启动则会推进本地 `main`。
+实现依据见 [worktree 操作](../internal/verify/verify.go) 与
+[单元交付](../internal/machine/units.go)。
+
+worktree 隔离工作目录和 index，不是安全沙箱。当前引擎默认尝试创建 packet
+worktree，但创建失败时会记录原因并回退 `in-place`；它没有“必须隔离”的开关。
+出现 `worktree unavailable` 时检查日志和工作区状态；需要严格隔离的任务应停止，
+人工安排并核实隔离恢复。已经保存的 `in-place` 状态不会因修复目录或重新启动
+就自动变成独立 worktree；不要手改 `state.json`，也不能把默认开启理解成任何
+情况下都有独立工作区。
+
+## 3. 在任务 worktree 中准备并审阅契约
+
+确认当前目录仍是 `repo-my-feature`，读取准备 skill：
+
+```sh
+flywheel skills read flywheel-new
+```
+
+可向当前 DSH Agent 提出：
+
+> 按 flywheel-new 为本需求建立 docs/my-feature。先查真实代码，写清需求、
+> packet、路由、修改边界和可执行验收；试跑 L1 并记录结果，完成后供我审阅。
+
+审阅至少覆盖：需求与 packet 的对应、L1/L2/L3 命令、失败出口、冻结验收路径，
+以及模型和权限配置。100% 覆盖率如为任务要求，应有实际可执行的门禁命令。
+不要填未经运行的验收结果；环境缺失应标记 unverified。不要手工创建或修改
+`state.json`，它由引擎管理。完整要求见 [flywheel-new](../skills/flywheel-new/SKILL.md)。
+
+按已有 Git 授权保存审阅后的契约，仅选择本任务文件：
+
+```sh
+git diff -- docs/my-feature
+git add docs/my-feature
+git diff --cached
+git commit -m "docs(my-feature): add approved task contracts"
+```
+
+若冻结验收文件位于任务目录之外，审阅后显式补选那些路径。提交前确认暂存区
+没有无关文件或凭证，不使用全仓库的 `git add .` 代替范围检查。契约必须实质
+进入提交，packet worktree 才能从 Git 基线取得它；空提交不能替代这一步。
+
+## 4. 尽早建立任务级 Draft PR
+
+契约确认并提交后，就可以推送任务分支、建立 Draft PR，不必等全部实现结束。
+以下使用已登录且有仓库权限的 GitHub CLI；也可在 GitHub 页面完成同样操作：
+
+```sh
+git push -u origin task/my-feature
+gh pr create --draft --base main --head task/my-feature
+```
+
+按提示填写需求、范围、验收计划与当前状态。一个可独立交付的需求或里程碑通常
+对应一个 PR；packet 是引擎内部工作单元，不必逐个开 PR。很大的需求应先拆成
+可独立验证、回滚的里程碑。[Draft PR 无法合并](https://docs.github.com/en/pull-requests/reference/pull-requests)，
+适合保留进行中的差异、讨论和检查结果。CI 是否在 Draft 阶段运行取决于仓库配置。
+
+## 5. 从同一个任务 worktree 启动
+
+当前目录必须仍是 `repo-my-feature`，任务目录也应位于这个 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"
+```
+
+预检不发送模型推理，不能证明账号额度或真实模型调用已经通过。启动会实际调用
+所选模型。在 DSH 面板操作时，也填写任务 worktree 的绝对路径及其内部任务路径，
+不要把原 checkout 的 `docs/my-feature` 与新 worktree 的 `cwd` 混用。
+
+每个 packet 的实现、L1 与独立 Review 通过后，引擎提交并快进合入任务分支。
+所有 packet 完成后仍需里程碑 L2/L3 与 Judge；单元合并不代表整个需求已通过。
+合并冲突或验证失败时保留产物并处理记录，不强制清理。停止与恢复见
+[入门教程](getting-started.md#7-启动观察停止与恢复)。
+
+若报告 `cleanup-unconfirmed` 或 `process cleanup is unconfirmed`，引擎会将本次
+运行升级为 `escalated` 并停止自动执行，保留工作区和审计记录。先核对本次调用
+拥有的 worker、guardian 和 app-server 是否已退出，再按恢复流程继续；不能仅
+因外层 worker 已退出或已等待几秒，就假定内部进程不会再修改工作区。
+
+### 5.1 Skills 入口与各 Loop 的工作目录
+
+内置 skills 将任务 worktree 约定作为准备、启动、恢复和单环入口的检查步骤。
+`flywheel-new` 在生成契约前创建或复用任务 worktree；`flywheel-run` 以及单环
+skills 从实际任务目录解析同一 worktree 根，再调用 CLI。默认不从 `main`、
+`master` 或 detached HEAD 启动开发；已有明确工作区选择与授权不重复询问。
+恢复复用原任务路径及引擎保存的 packet 状态，不为恢复另建一份任务或复制 state。
+
+| 阶段／入口 | 实际工作目录 | 谁负责选择或创建 |
+|---|---|---|
+| `flywheel-new` 准备契约 | 任务集成 worktree | 宿主 Agent 按 skill 创建或复用 |
+| Plan | 任务集成 worktree，修订任务契约 | 引擎使用启动时的根目录 |
+| Execute、L1、Review | 当前 packet 候选工作区；正常模式为 packet worktree | 引擎创建、记录并复用 packet worktree |
+| L2/L3、Judge | 任务集成 worktree | 引擎验证已集成的需求与里程碑 |
+| Intake、Garden | 所选任务所属 worktree | 入口解析目录，Go 写建议结果；DSH／Codex 后端请求只读，默认 Kimi 无 OS 级只读保证 |
+| Status、Stop | 对应原任务路径与根目录 | 直接查询或停止，不要求为此新建 worktree、切分支或提交 |
+
+因此，每个 Loop 不会各自新建一份 worktree。任务 worktree 贯穿整个需求，
+packet worktree 贯穿该单元的执行、验收与评审；完成交付才由引擎处理本地合并
+与清理。恢复入口仍是 `flywheel-run`，没有另一个独立的 resume skill。
+`flywheel-verify` 只运行确定性验收：指定 packet 时只检查该单元 L1；未指定时
+检查未完成单元 L1 与当前里程碑 L2/L3。它不调用 Review／Judge，也不创建 worktree。
+
+Skill 的启动检查由宿主 Agent 遵守，CLI／GUI 直接调用不会自动执行这些 skill
+正文，也不会自动创建外层任务分支。直接使用控制接口时仍须显式选择正确的
+`cwd`／`taskDir`；引擎现有的 `in-place` 回退边界见第 2 节。只读查询和停止
+不受开发分支检查阻碍，便于处理异常任务。
+
+## 6. 完整终验后再合并 PR
+
+确认 `state.status` 为 `completed`，需求覆盖、验收报告、独立评审及本地提交
+都齐全，再核对工作区并推送任务分支。`control` 返回 `ok:true` 只代表控制操作成功。
+
+```sh
+git status --short
+git log -5 --oneline
+git push origin task/my-feature
+gh pr ready
+gh pr checks
+```
+
+由人或获授权的宿主检查 PR 最终差异、文档、剩余验证边界和当前 head 的远端 CI。
+独立审阅应基于契约、差异和测试证据；执行模型自报完成不是审阅通过。
+代码或 base 更新后，重新取得对应候选的检查与审阅，不能沿用旧提交的绿灯。
+所有条件满足后再人工合并；合并后检查 main CI。发布仍是另一个发行步骤。
+
+## 7. 自动合并与职责边界
+
+当前 Flywheel 引擎负责本地状态、验收、提交和 packet 合并，**不自动 push、
+创建 GitHub PR、等待远端 CI 或合并远端 PR**。本文的 GitHub 步骤由使用者或
+获授权的宿主 Agent 执行，不能据此宣称引擎已实现远端交付自动化。
+
+默认保留人工最终合并。若以后允许低风险任务自动合并，应先明确适用范围、
+required checks、审阅要求和授权，再按仓库策略启用；Agent 的 pass 不能绕过门禁。
+[GitHub auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request)
+用于等待既定要求满足后合并，不是取消要求。分支更新及过期审阅规则见
+[受保护分支](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)。
+
+更多依据：[Git worktree](https://git-scm.com/docs/git-worktree)、
+[Astra 模型与 effort](https://developers.openai.com/api/docs/models/gpt-6-astra)、
+[Kimi 模型配置](https://www.kimi.com/code/docs/en/kimi-code/models)、
+[Flywheel 设计](design.md)。

package/npm/install.js

@@ -20,7 +20,7 @@ const HELP = `Flywheel npm installation
   flywheel setup [options]
 
 Install this exact version of the CLI, worker, embedded skills and DSH plugin.
-No model inference or account login is performed. Node >=22 and the existing
+No model inference or account login is performed. Node >=22.18.0 and the existing
 DSH desktop command are prerequisites. Kimi/Codex availability is reported by
 the local preflight; this installer does not replace another harness.
 
@@ -89,7 +89,7 @@ function npmCommand(environment = process.env) {
   const script = environment.npm_execpath;
   if (script && path.isAbsolute(script) && fs.existsSync(script)) return [process.execPath, [script]];
   const binary = findExecutable("npm", environment);
-  if (!binary) throw new Error("npm is required; install Node.js 22 or newer, then rerun this command");
+  if (!binary) throw new Error("npm is required; install Node.js 22.18.0 or newer, then rerun this command");
   return [binary, []];
 }
 
@@ -227,7 +227,7 @@ function launcherContent({ cli, prefix, dshBin, environment = process.env }) {
   return lines.join("\n");
 }
 
-async function writeLauncher({ directory, previous, cli, prefix, worker, dshBin, environment }) {
+async function writeLauncher({ directory, previous, cli, prefix, worker, codexProWorker, adapter, dshBin, environment }) {
   await fsp.mkdir(directory, { recursive: true });
   const launcher = path.join(directory, "npm-launcher");
   const content = launcherContent({ cli, prefix, dshBin, environment });
@@ -240,7 +240,7 @@ async function writeLauncher({ directory, previous, cli, prefix, worker, dshBin,
     }
   } catch (error) { if (error.code !== "ENOENT") throw error; }
   await atomicWrite(launcher, content, 0o755);
-  const receipt = { protocol: 1, owner: OWNER, version: meta.version, prefix, cli, worker,
+  const receipt = { protocol: 1, owner: OWNER, version: meta.version, prefix, cli, worker, codexProWorker, adapter,
     node: process.execPath, launcher: { path: launcher, sha256: digest(content) } };
   await atomicWrite(path.join(directory, "installation.json"), JSON.stringify(receipt, null, 2) + "\n", 0o600);
   return receipt;
@@ -290,7 +290,7 @@ async function install(options, { environment = process.env, cwd = process.cwd()
   };
   try {
     if (!['darwin', 'linux'].includes(process.platform) || !['arm64', 'x64'].includes(process.arch)) throw new Error("unsupported installation platform");
-    if (Number(process.versions.node.split(".")[0]) < 22) throw new Error("Node.js 22 or newer is required");
+    require('../bin/runtime.js').assertSupportedNode();
     const home = environment.HOME;
     if (!home || !path.isAbsolute(home)) throw new Error("HOME must identify the user's absolute home directory");
     const directory = path.join(home, ".config", "flywheel");
@@ -314,7 +314,16 @@ async function install(options, { environment = process.env, cwd = process.cwd()
       if (installed.name !== OWNER || installed.version !== meta.version) throw new Error("installed package does not match this installer version");
       const installedRequire = createRequire(path.join(installedRoot, "package.json"));
       const runtime = installedRequire("./bin/runtime.js");
-      report.paths = { cli: path.join(installedRoot, "bin", "flywheel.js"), native: runtime.loadNativePath(), worker: runtime.loadWorkerPath() };
+      report.paths = { cli: path.join(installedRoot, "bin", "flywheel.js"), native: runtime.loadNativePath(), worker: runtime.loadWorkerPath(),
+        codexProWorker: runtime.loadCodexProWorkerPath() };
+      const probe = await run(process.execPath, [report.paths.codexProWorker, '--doctor']);
+      requireSuccess(probe, 'installed Codex Pro dependency');
+      const adapter = parseDocument(probe, 'installed Codex Pro dependency');
+      if (adapter.protocol !== 1 || adapter.type !== 'doctor' || adapter.package !== 'dsh-subagent-codex-pro' ||
+          adapter.version !== '0.8.0' || adapter.machineProtocol !== 1 || adapter.available !== true || adapter.inferenceTested !== false) {
+        throw new Error('installed Codex Pro dependency did not verify the exact public machine API');
+      }
+      report.adapter = { package: adapter.package, version: adapter.version, protocol: adapter.machineProtocol, inferenceTested: false };
       const version = requireSuccess(await run(process.execPath, [report.paths.cli, "version"]), "installed CLI version");
       if (!version.split(/\s+/).includes(meta.version)) throw new Error("native binary version does not match the npm package");
       item.version = version;
@@ -333,7 +342,8 @@ async function install(options, { environment = process.env, cwd = process.cwd()
     const requestedDsh = options.dshBin ?? environment.FLYWHEEL_DSH_BIN ?? "dsh";
     const dshBin = findExecutable(requestedDsh, environment);
     await step("desktop-launcher", async item => {
-      const receipt = await writeLauncher({ directory, previous, cli: report.paths.cli, prefix, worker: report.paths.worker, dshBin, environment });
+      const receipt = await writeLauncher({ directory, previous, cli: report.paths.cli, prefix, worker: report.paths.worker,
+        codexProWorker: report.paths.codexProWorker, adapter: report.adapter, dshBin, environment });
       report.paths.launcher = receipt.launcher.path;
       item.path = receipt.launcher.path;
     });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ckanner/flywheel",
-  "version": "0.27.3",
-  "description": "Flywheel: deterministic coding-agent loops, DSH controls, and one-command agent installation.",
+  "version": "0.28.0",
+  "description": "A deterministic Go orchestrator for coding-agent loops, with task contracts, verification gates, Git worktrees, and DSH desktop integration.",
   "bin": {
     "flywheel": "bin/flywheel.js",
-    "flywheel-dsh-worker": "bin/flywheel-dsh-worker.js"
+    "flywheel-dsh-worker": "bin/flywheel-dsh-worker.js",
+    "flywheel-codex-pro-worker": "bin/flywheel-codex-pro-worker.js"
   },
   "os": [
     "darwin",
@@ -15,7 +16,7 @@
     "arm64"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.18.0"
   },
   "repository": {
     "type": "git",
@@ -26,25 +27,30 @@
     "bin",
     "npm/*.js",
     "README.md",
+    "README.en.md",
     "CHANGELOG.md",
     "docs/getting-started.md",
     "docs/configuration.md",
+    "docs/workflow.md",
+    "docs/en/getting-started.md",
+    "docs/en/configuration.md",
+    "docs/en/workflow.md",
     "docs/examples/create-first-task.sh"
   ],
   "optionalDependencies": {
-    "@ckanner/flywheel-darwin-arm64": "0.27.3",
-    "@ckanner/flywheel-darwin-amd64": "0.27.3",
-    "@ckanner/flywheel-linux-arm64": "0.27.3",
-    "@ckanner/flywheel-linux-amd64": "0.27.3"
+    "@ckanner/flywheel-darwin-arm64": "0.28.0",
+    "@ckanner/flywheel-darwin-amd64": "0.28.0",
+    "@ckanner/flywheel-linux-arm64": "0.28.0",
+    "@ckanner/flywheel-linux-amd64": "0.28.0"
   },
   "scripts": {
     "release:check": "node scripts/release-preflight.js",
     "test": "node --test npm/test/*.test.js",
     "test:install": "node --test npm/test/install.integration.js",
     "test:registry": "node npm/test/registry-smoke.js",
-    "build:npm": "bash scripts/build-npm.sh 0.27.3 dist-npm"
+    "build:npm": "bash scripts/build-npm.sh 0.28.0 dist-npm"
   },
   "dependencies": {
-    "@ckanner/dsh-plugin-flywheel": "0.27.3"
+    "@ckanner/dsh-plugin-flywheel": "0.28.0"
   }
 }