@ckanner/flywheel 0.22.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.22.0 (2026-09-12)
+
+三厂商 harness 定稿 + 完全自包含分发（安装用法人人一致，无需源码仓库）。
+
+- **Harness 矩阵（DESIGN v0.22）**：Execute default/multimodal/Intake = zcode（app-server 协议，按会话指定模型与思考档）；Review + Judge 复核面板 = Codex（GPT-6-Astra）；Plan/frontend/hard/Judge 主判/Garden = kimi code + K3。跨厂商制衡升级（GLM 执行 ↔ OpenAI 评审）。
+- **自包含分发**：契约 schema、skills 快照、§13 法定配置表全部内嵌二进制；`flywheel install-skills` 默认从内嵌快照物化（`--link` 为开发机源码树软链专用）；`flywheel template` 打印内嵌模板。
+- **配置四级发现链**：任务目录 → 项目根 → 全局 `~/.config/flywheel/flywheel.config.json`（首装自动物化，可直接编辑）→ 内嵌法定表兜底。
+- watchdog 交互钩子（协议驱动）、multimodal 执行路由、`FLYWHEEL_CONFIG` 覆盖。
+
+更早历史见 docs/design.md 变更记录。

package/README.md

@@ -0,0 +1,162 @@
+# Flywheel（飞轮）
+
+Loop Engineering 系统：外部编排器进程（不是 agent）驱动多个 agent loop（规划/执行/评审/终验），接收已冻结的需求，自动完成软件任务的规划、实现、评审与分层验证，全程可无人值守，异常时升级给人。
+
+- 编排器 = 确定性 Go 代码（机械状态转移，设计铁律 1）
+- 角色与知识 = Agent Skills（本仓库 `skills/`，只是"按钮"）
+- 契约 = `docs/<slug>/` 下的静态文件（spec.md + task-packet + state.json，全部进 git）
+
+权威设计文档：**[docs/design.md](docs/design.md)**（v0.22，变更记录在文件头）。仓库工作宪法：[AGENTS.md](AGENTS.md)。
+
+## 安装（npm，平台二进制包模式）
+
+```bash
+npm i -g @ckanner/flywheel     # 平台二进制经 optionalDependencies 自动就位，无 postinstall 下载
+flywheel install-skills        # skills 物化 + 全局配置 ~/.config/flywheel/flywheel.config.json 一次就位
+```
+
+- 安装完全自包含：契约 schema、skills 快照、§13 法定配置表全部内嵌二进制，**无需 clone 本仓库**；维护者与分用户用法完全一致。
+- 支持平台：darwin/linux × amd64/arm64（`os`/`cpu` 字段自动选取，`--no-optional` 会导致平台包缺失）。
+- 非 npm 渠道：[GitHub Releases](https://github.com/ckanner/flywheel/releases) 下载平台 tar.gz（`shasum -a 256 -c checksums.txt` 校验）。
+- 开发机源码运行：`go install ./cmd/flywheel`；`flywheel install-skills --link` 可选软链源码树（仅维护者便利，非安装路径）。
+
+## 本机环境事实（维护机，v0.22）
+
+- macOS arm64；Go 工具链经 mise 管理（go@1.27.0）——shell PATH 可能残留旧版路径，新会话先 `go version` 核对。
+- **zcode**：driver 默认 `node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs app-server`（app 内置 runtime，随桌面自动更新；`FLY_ZCODE_SERVER_BIN` 覆盖 launcher，`FLY_ZCODE_BIN` 只管桌面注册二进制——v0.22 语义拆分）。Z.AI Coding Plan 凭证在 `~/.zcode/cli/config.json`（provider zai）；app-server 协议 live 冒烟 2026-09-10 通过（8.2s 全闭环）；协议无公开文档——桌面大版本更新后跑协议探针（design.md §10-5）。
+- **codex**：CLI 已升 0.154.0（gpt-6-astra 硬门槛 ≥0.154 npm / ≥0.153 app 内置）；chatgpt 订阅 OAuth 已登录。注意：代理经 HKG 节点偶发 403，重试即过。
+- **kimi code**：订阅 OAuth 登录在；stream-json 无 usage 暴露——Plan 的 token 不可观测（接受现状，看门狗兜底）。
+- **omp（B 通道）**：已装、`zhipu-coding-plan` provider 配好（智谱国内计划）——zcode 协议漂移时的应急通道。
+
+## 安装 skills 到 kimi code / pi
+
+kimi code、pi、Warp 均实现 Agent Skills 标准并扫描共享安装点 `~/.agents/skills/`：
+
+```bash
+# 默认：软链（仓库即唯一信源，改了即生效；幂等，重复运行报告"已安装，跳过"）
+flywheel install-skills
+
+# 替换已存在的条目
+flywheel install-skills --force
+
+# 复制快照（用于发布，而不是软链）
+flywheel install-skills --copy
+
+# 安装到某个项目根的 .agents/skills/（项目级）
+flywheel install-skills --project /path/to/project
+```
+
+> 调用形态按 harness 而异：kimi code 与 pi 为 `/skill:<name>`；Warp 为 `/<name>`；
+> Claude Code 经 Skill 工具加载。`whenToUse`/`arguments` 是 kimi code 定义的字段
+> （自动调用依据），不在 agentskills.io 标准内，其他 harness 会无害忽略。
+
+装完后在 kimi code 或 pi 里用 `/skill:<name>` 调用，例如 `/skill:flywheel-run`。安装时会在 skills 安装点写入锚文件 `flywheel-home.txt`，skill 用它定位本仓库根。
+
+## skills 一览（都只是按钮，不含 loop 逻辑）
+
+| 调用 | 作用 |
+|---|---|
+| `/skill:flywheel-new` | 对话式任务生成器：调研仓库 → 问意图 → 生成契约 → 逐条试跑验收命令留证 → 停下等人审 |
+| `/skill:flywheel-run` | 以独立进程拉起编排器（触发全部 loop）；可选 `pause=review` 监督冻结点 |
+| `/skill:flywheel-plan` | 只触发 Plan Loop 单步 |
+| `/skill:flywheel-exec` | 只触发 Execute Loop（可指定 packet） |
+| `/skill:flywheel-review` | 只触发 Review Loop（可指定 unit） |
+| `/skill:flywheel-verify` | 只触发确定性验证闸门 L1/L2/L3（无模型） |
+| `/skill:flywheel-status` | 只读进度（state.json/指标/缓存命中率/inbox；推进超时→停滞提示） |
+| `/skill:flywheel-stop` | 停止编排器进程，状态定格 |
+| `/skill:flywheel-intake` | 外挂：扫任务源 → triage-inbox → LLM 分诊建议（不冻结需求） |
+| `/skill:flywheel-garden` | 外挂：retro 失败模式 + 知识资产腐烂 → 提案（需人审） |
+
+内置 skill 目录也可用 CLI 直接查看：`flywheel skills list` / `flywheel skills read <name>`（go:embed 内嵌，无需源码树）。
+
+## 使用全流程（最小示例，详见 [docs/design.md](docs/design.md) §12）
+
+```bash
+# 1. 在 harness（kimi code 或 pi）里生成任务契约
+/skill:flywheel-new 把"给网关加 /health 端点"做成 flywheel 任务
+#    → 生成 docs/<slug>/{spec.md, task-packet-*.md, state.json, flywheel.config.json}
+#    → skill 会把契约 git add + commit，然后停下
+
+# 2. 人审契约（关键 checkpoint，不可省）：需求编号、验收命令、边界、试跑证据
+#    （生成器已逐条试跑 L1 命令并把退出码/输出记入 spec 附表——审它别跳过）
+
+# 3. 启动（在 harness 里扣扳机；编排器是独立进程，关窗不影响运行）
+/skill:flywheel-run docs/<slug>            # 全自动
+/skill:flywheel-run docs/<slug> review     # 监督模式：Review 前冻结，等你看完再续
+
+#    单步玩法：--only execute / verify / review（与 pause-before 互斥）
+
+# 4. 观察与干预（在哪都行，全是文件操作）
+flywheel status docs/<slug>
+flywheel stop docs/<slug>
+
+# 5. 交付：分支/PR 留给人最终确认合并（外层循环归人）
+```
+
+单 loop 手动触发（旁路常开）：`flywheel run docs/<slug> --only execute --packet M02-T03`、`--pause-before review` 逐步监督。
+
+## 目录结构
+
+```
+cmd/flywheel/            # main() 单行桩（os.Exit(cli.Execute())）
+internal/
+  cli/                   # cobra 命令树：run/status/stop/intake/garden/install-skills/skills
+  machine/               # 状态机（DESIGN §6 刻意做薄）：runTask/runSingleStep/steps
+  contract/              # 契约解析 + JSON Schema 校验单一信源（templates/*.schema.json）
+  state/                 # state.json CAS 账本（tmp+rename 原子写）
+  donereport/            # done-report 解析与格式校验
+  exitcontract/          # 出口契约三正交量判定
+  verify/                # L1/L2/L3 闸门 + git diff 边界 + worktree 隔离 + 单元提交
+  watchdog/              # 双计时看门狗（流 idle + wall-clock；进程组 kill + quiescence）
+  errs/                  # 错误分类/退避/降级集（RE2 等价改写）
+  fallback/              # 渠道降级链（绑定表改写）
+  circuitbreaker/        # 预算熔断（off|soft|hard）+ DC4 空转检测
+  defectinjection/       # 缺陷注入抽检（DC3）
+  metrics/               # JSONL 指标（模型/token/成本/缓存命中/prompt 哈希）
+  prompts/               # 提示词构建（§8 缓存纪律：稳定前置/易变尾部）+ 裁决解析
+  drivers/               # mock（测试）/ pi / omp（B 通道）/ zcode（app-server）/ codex / kimi（长驻会话）
+  config/                # 法定配置表加载与校验
+  childenv/              # 子进程环境白名单（凭证卫生 §9）
+  ledger/                # 账本区路径分类（边界判定的单一信源）
+  modules/               # 外挂：intake/garden/install-skills/module 共享上下文
+  skillsembed/           # go:embed skills 数据层（skills list/read + 规范门禁测试）
+templates/               # 契约模板与 schema（task-packet / spec / state 示例）
+skills/                  # 10 个 SKILL.md（Agent Skills 标准）+ embed.go
+scripts/                 # npm 分发安装器（lark-cli 模式）
+drills/                  # 实证演练记录（403 降级、缺陷注入）
+```
+
+## 任务目录（docs/<slug>/，目标仓库内，全部进 git）
+
+生成时（/skill:flywheel-new）：`spec.md`（编号需求）+ `task-packet-*.md`（契约）+ `state.json`（初始状态）+ `flywheel.config.json`（法定配置表）。
+
+运行后逐渐多出：
+
+```
+reports/<packet-id>.done.json   # 每个单元的 done-report（executor 自报，三级证据之一）
+metrics.jsonl                   # 每次 spawn 一条：模型/harness/token/成本/缓存命中/耗时/错误码
+retro.md                        # 单元完成行 + 里程碑汇总（§5.3 字段）
+inbox.md                        # 升级叫人的入口（正常应为空）
+triage-inbox.md                 # intake 候选（跑了 flywheel intake 才有）
+garden-proposals.md             # garden 提案（跑了 flywheel garden 才有）
+approvals/<packet-id>.json      # live 凭证任务的人工批准文件（需要时）
+orchestrator.pid / orchestrator.log   # 运行中的进程文件与日志
+```
+
+## 测试
+
+```bash
+make test            # go test ./... 全部包
+make coverage        # 覆盖率门禁（cmd 桩除外，逐函数 100%）
+make quality-gate    # vet + fmt-check + coverage（CI 同款）
+```
+
+单元测试覆盖率 100% 是硬门禁（用户确立的设计纪律：反向驱动松耦合与可注入性）；
+v0.18 起按**逐函数**检查——任何函数 <100% 直接失败，不再只看总数。mock 驱动覆盖全部编排逻辑，
+可在无凭证环境完整运行；verify/watchdog 用真实 git 与真实子进程组测试。
+
+## 文档入口
+
+- [docs/design.md](docs/design.md) — 权威设计文档（§2 设计铁律是最高约束）
+- [AGENTS.md](AGENTS.md) — 仓库工作宪法（构建/闸门/硬契约）
+- [drills/](drills/README.md) — 实证演练记录与环境事实基线

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ckanner/flywheel",
+  "version": "0.22.0",
+  "description": "Flywheel — Loop Engineering orchestrator (Go). Deterministic orchestrator driving Plan/Execute/Review agent loops from frozen on-disk contracts. Platform binaries ride optionalDependencies (@ckanner/flywheel-<os>-<arch>).",
+  "bin": {
+    "flywheel": "bin/flywheel.js"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ckanner/flywheel.git"
+  },
+  "license": "UNLICENSED",
+  "files": [
+    "bin/flywheel.js",
+    "CHANGELOG.md"
+  ],
+  "optionalDependencies": {
+    "@ckanner/flywheel-darwin-arm64": "0.22.0",
+    "@ckanner/flywheel-darwin-amd64": "0.22.0",
+    "@ckanner/flywheel-linux-arm64": "0.22.0",
+    "@ckanner/flywheel-linux-amd64": "0.22.0"
+  },
+  "scripts": {
+    "release:check": "node scripts/release-preflight.js"
+  }
+}