@fkqfkq123/opencode-autopilot 0.1.5 → 0.1.8

package/GUIDE.zh-CN.md

@@ -2,226 +2,11 @@
 
 [English](./README.md) | 中文说明
 
-Autopilot 是一个面向 OpenCode 风格运行时的 **attached-session workflow harness**。它提供从需求精炼、计划、开发、评审到测试的 workflow runtime 骨架，以及可本地加载的插件、CLI 入口和诊断能力。
+Autopilot 是一个 OpenCode 插件，可以把自然语言需求推进成一套完整流程：需求精炼、计划、实现、评审和测试。
 
-## 1. 这个项目提供什么
+## 安装
 
-- 完整 workflow phase 主链：`spec_refinement -> plan -> develop -> review -> test -> done`
-- 面向 OpenCode 的 workflow 命令：`workflow_open`、`workflow_attach`、`workflow_status`、`workflow_answer`、`workflow_approve`、`workflow_resume`、`workflow_back`
-- OpenCode 风格宿主的插件加载能力与原生 primary workflow agent 注册能力
-- `install` / `doctor` 初始化与自检流程
-- review/test loop-back、人工断点、事件存储、attach / re-attach 支持
-
-## 2. 适合谁使用
-
-如果你希望：
-
-- 在 OpenCode 风格宿主中接入 workflow 主代理
-- 把工程流程拆成显式 phase
-- 通过插件形式验证 workflow runtime 与 command surface
-
-那么这个项目适合你。
-
-## 3. 环境准备
-
-建议环境：
-
-- macOS / Linux / Windows
-- [Bun](https://bun.sh/) `1.3.5` 或兼容版本
-- 已安装 OpenCode（如果你需要实际加载并验证插件）
-
-检查 Bun：
-
-```bash
-bun --version
-```
-
-如果还没有安装 Bun：
-
-```bash
-curl -fsSL https://bun.sh/install | bash
-```
-
-安装完成后重启终端，再执行：
-
-```bash
-bun --version
-```
-
-## 4. 安装
-
-### 4.1 推荐方式：作为 npm 插件包安装
-
-OpenCode 原生支持 npm 插件。等这个包发布后，最简单的配置方式是：
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot"]
-}
-```
-
-也可以固定版本：
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot@0.1.2"]
-}
-```
-
-在这种模式下，OpenCode 会自动安装并缓存 npm 包，不需要手动 `git clone`、不需要本地 `plugin.js`、也不需要额外安装脚本。
-
-### 4.2 备用方式：通过 GitHub Releases 安装
-
-如果你更希望走本地文件安装路径，或者需要 fallback 分发方式，可以使用 GitHub Releases 一键安装脚本：
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
-```
-
-安装指定版本：
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash -s -- --version v0.1.2
-```
-
-这个备用安装脚本会：
-
-- 从 GitHub Releases 下载预构建发布包
-- 安装到 `~/.config/opencode/plugins/autopilot/`
-- 更新 `~/.config/opencode/opencode.json`
-
-发布要求：
-
-- 每个 GitHub Release 需要包含 `autopilot-release.tar.gz`
-- 仓库内置 `.github/workflows/release.yml`，在推送 `v*` tag 时会自动构建并上传该文件
-
-如果你想修改源码或从源码开发，继续看下面的源码安装流程。
-
-### 4.3 克隆仓库
-
-```bash
-git clone https://github.com/juhuaxia/Autopilot.git
-cd Autopilot
-```
-
-### 4.4 安装依赖
-
-```bash
-bun install
-```
-
-项目使用 `bun.lock`，依赖版本应保持可复现。
-
-## 5. 推荐首次执行的命令
-
-在项目根目录执行：
-
-```bash
-bun run src/cli.ts install
-bun run src/cli.ts doctor
-bun run build
-```
-
-它们分别会：
-
-1. `install`
-   - 创建项目级 `.workflow-harness/autopilot.json`
-   - 在缺失时创建全局 `~/.config/opencode/autopilot.json`
-   - 尝试安全写入 `~/.config/opencode/opencode.json`
-   - 如有 `opencode.jsonc`，在安全情况下归一化写回 `opencode.json`
-2. `doctor`
-   - 检查 `autopilot.json`
-   - 检查 `skillRoots`
-   - 检查各 phase 的 `requiredSkills`
-   - 输出告警与缺失项
-3. `build`
-   - 编译 TypeScript
-   - 生成 `dist/plugin.js`
-
-之后建议确认：
-
-- `.workflow-harness/autopilot.json` 已生成
-- `doctor` 没有阻断性配置问题
-- `dist/plugin.js` 已生成
-
-## 6. 常用开发命令
-
-### 6.1 构建
-
-```bash
-bun run build
-```
-
-### 6.2 类型检查
-
-```bash
-bun run typecheck
-```
-
-### 6.3 运行测试
-
-```bash
-bun test
-```
-
-### 6.4 运行插件 smoke test
-
-```bash
-bun run smoke:plugin
-```
-
-### 6.5 直接运行 CLI
-
-```bash
-bun run src/cli.ts doctor
-bun run src/cli.ts install
-```
-
-也可以通过脚本别名运行：
-
-```bash
-bun run cli --help
-```
-
-> CLI 主要用于 workflow 初始化、attach/status 流程以及 install/doctor 动作。
-
-## 7. CLI 快速使用
-
-### 7.1 初始化配置
-
-```bash
-bun run src/cli.ts install
-```
-
-### 7.2 做一次自检
-
-```bash
-bun run src/cli.ts doctor
-```
-
-### 7.3 创建一个 workflow
-
-```bash
-bun run src/cli.ts workflow-open wf-1
-```
-
-### 7.4 查看 workflow 状态
-
-```bash
-bun run src/cli.ts workflow-status wf-1
-```
-
-### 7.5 重新 attach 到 workflow channel
-
-```bash
-bun run src/cli.ts workflow-attach wf-1
-```
-
-## 8. 如何把插件加载到 OpenCode
-
-### 8.0 推荐的 npm 插件方式
-
-推荐的 OpenCode 配置：
+在 OpenCode 配置里加入插件：
 
 ```json
 {
@@ -229,237 +14,107 @@ bun run src/cli.ts workflow-attach wf-1
 }
 ```
 
-### 8.1 备用的 release 安装方式
-
-如果你希望使用本地安装后的 fallback 插件，执行：
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
-```
-
-默认安装位置：
-
-```txt
-~/.config/opencode/plugins/autopilot/
-```
+然后重启 `opencode`。
 
-安装脚本会写入类似这样的插件入口：
+如果加载成功，你应该看到类似日志：
 
 ```txt
-file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js
-```
-
-### 8.2 源码开发方式
-
-执行：
-
-```bash
-bun run src/cli.ts install
-bun run src/cli.ts doctor
-```
-
-如果 installer 能安全改写 OpenCode 配置，通常不需要手工编辑。
-
-> `install.sh` 面向 GitHub Releases 安装；项目内 installer 面向源码开发场景。
-
-### 8.3 手工注册插件
-
-OpenCode 配置通常在：
-
-- `~/.config/opencode/opencode.json`
-- 或 `~/.config/opencode/opencode.jsonc`
-
-#### 方案 A：加载构建产物
-
-先构建：
-
-```bash
-bun run build
-```
-
-然后在 OpenCode 配置中加入：
-
-```json
-{
-  "plugin": [
-    "file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js"
-  ]
-}
-```
-
-#### 方案 B：开发阶段直接加载源码
-
-```json
-{
-  "plugin": [
-    "file:///ABSOLUTE_PATH_TO_PROJECT/plugin.ts"
-  ]
-}
+[autopilot] Autopilot plugin loaded (... commands)
 ```
 
-### 8.4 启动 OpenCode
-
-交互模式：
-
-```bash
-opencode
-```
+## 使用
 
-Server 模式：
+直接输入自然语言需求，例如：
 
-```bash
-opencode serve
+```txt
+给商品列表页增加排序能力，并注意回归风险。
 ```
 
-## 9. 加载成功后你应该看到什么
-
-插件会暴露这些工具/命令：
+Autopilot 会通过这些工具推进流程：
 
-- `workflow_channel`
 - `workflow_open`
 - `workflow_attach`
 - `workflow_status`
 - `workflow_answer`
 - `workflow_approve`
 - `workflow_resume`
-- `workflow_back`
-- `workflow_doctor`
 
-推荐优先使用 split tools：
+通常你只需要按照 workflow 输出里提示的下一步工具继续即可。
 
-- `workflow_open`
-- `workflow_attach`
-- `workflow_status`
-- `workflow_answer`
-- `workflow_approve`
-- `workflow_resume`
-- `workflow_back`
+## 配置
 
-典型加载日志：
+Autopilot 会在需要时自动创建：
 
 ```txt
-[autopilot] Autopilot plugin loaded (... commands)
+.workflow-harness/autopilot.json
+~/.config/opencode/autopilot.json
 ```
 
-## 10. 目录结构
-
-### 10.1 配置层级
-
-- 用户默认：`~/.config/opencode/autopilot.json`
-- 项目级覆盖：`<repo>/.workflow-harness/autopilot.json`
-- 运行时状态：`<repo>/.workflow-harness/workflows/<workflowId>/`
-
-### 10.2 各目录作用
+如果配置保持空值，就使用默认行为。
 
-- `src/` — CLI 入口与顶层源码
-- `packages/runtime/` — workflow runtime 实现
-- `tests/` — 测试
-- `scripts/` — 辅助脚本
-- `.workflow-harness/` — 运行时配置、状态与产物
-- `dist/` — 构建输出
+### `autopilot.json`
 
-## 11. 最小 `autopilot.json` 示例
-
-先从完全中性的配置开始：
+最小示例：
 
 ```json
 {
   "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
   "phases": {
+    "spec_refinement": { "requiredSkills": [] },
+    "plan": { "requiredSkills": [] },
     "develop": { "requiredSkills": [] },
+    "review": { "requiredSkills": [] },
     "test": { "requiredSkills": [] }
   }
 }
 ```
 
-然后按项目需要添加 skill。以前端项目为例：
-
-```json
-{
-  "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
-  "phases": {
-    "develop": { "requiredSkills": ["frontend-design"] },
-    "test": { "requiredSkills": ["playwright"] }
-  }
-}
-```
-
-这个前端示例只是示例，workflow runtime 默认并不绑定前端。
+字段说明：
 
-建议：
+- `skillRoots`：要扫描的 skill 目录
+- `phases.<phase>.requiredSkills`：该阶段需要注入的 skill
 
-- skill / profile 配置放在全局或项目级 `autopilot.json`
-- 不要把 skill 配置写到 `workflows/<workflowId>/`
-- 新配置上线前先跑 `workflow_doctor` 或 CLI `doctor`
+支持的 phase：
 
-## 12. 常见问题
+- `spec_refinement`
+- `plan`
+- `develop`
+- `review`
+- `test`
 
-### Q1：`install` 无法改写 OpenCode 配置怎么办？
+如果旧的 `workflow.json` 存在而新的 `autopilot.json` 不存在，Autopilot 会复用旧文件，并提示你后续迁移。
 
-手工编辑 OpenCode 配置，把发布版插件路径或本地构建路径加入 `plugin` 数组。例如：
+## 备用安装方式
 
-```json
-{
-  "plugin": [
-    "file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js"
-  ]
-}
-```
-
-如果你是源码开发场景，也可以指向本地的 `dist/plugin.js`。
-
-如果你使用 npm 插件模式，则只需要这样配置：
+如果你更想走本地文件安装：
 
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot"]
-}
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
 ```
 
-### Q2：为什么 build 以后还是看不到 workflow 命令？
-
-通常是宿主集成层还没有把导出的 `workflowCommands` 真正注册到宿主命令面板 / tool surface。
-
-### Q3：我应该先验证什么？
-
-建议先按这个顺序验证：
-
-1. 宿主能导入插件文件
-2. 宿主能调用默认导出
-3. 宿主能收到一个 plugin-like 对象
+## 常见问题
 
-不要一开始就先验证 UI。
+### OpenCode 启动失败
 
-### Q4：插件根入口有什么约束？
+先临时从 `opencode.json` 中移除这个插件，确认 OpenCode 能正常启动，再检查配置后重新启用。
 
-根入口 `plugin.ts` 应只暴露一个宿主可调用的默认导出，不要在根入口额外暴露内部 class 或 helper function。
+### 插件加载了，但看不到 workflow 命令
 
-## 13. 推荐阅读
+通常是宿主没有正确注册导出的 workflow tools。
 
-| 文档 | 用途 |
-|---|---|
-| `README.md` | 安装、发布、使用总入口 |
-| `WORKFLOW_SKILL_PROFILE_ARCHITECTURE_CN.md` | skill / profile 配置设计 |
-| `OPENCODE_WORKFLOW_AGENT_GUIDE.md` | agent / tool 调用顺序 |
-| `REQUIREMENT_TEMPLATE.md` | 需求输入模板 |
+### 某个 workflow 状态坏掉了
 
-内部规划稿、验收草案、状态记录等可以保存在本地 `docs_internal/` 中，该目录默认已忽略。
+删除当前项目的运行时目录后重新开始：
 
-## 14. 最快可用路径
+```bash
+rm -rf .workflow-harness
+```
 
-如果你只想最快跑起源码开发环境：
+## 如果你要开发这个插件
 
 ```bash
 bun install
-bun run src/cli.ts install
-bun run src/cli.ts doctor
+bun run typecheck
+bun test
 bun run build
-opencode
 ```
-
-然后：
-
-1. 确认 `.workflow-harness/autopilot.json` 已生成
-2. 确认 `dist/plugin.js` 已生成
-3. 如果 OpenCode 没有自动加载插件，手工把 `file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js` 加到配置里
-4. 在宿主中验证 `workflow_open`、`workflow_attach`、`workflow_status` 是否可见

package/README.md

@@ -2,224 +2,11 @@
 
 English | [中文说明](./GUIDE.zh-CN.md)
 
-Autopilot is an OpenCode-oriented **attached-session workflow harness**. It provides a workflow runtime skeleton covering refinement, planning, development, review, and testing, plus a locally loadable plugin, CLI entrypoints, and diagnostics.
+Autopilot is an OpenCode plugin that turns a natural-language request into a structured workflow: refinement, plan, implementation, review, and testing.
 
-## 1. What this project provides
+## Install
 
-- A full workflow phase chain: `spec_refinement -> plan -> develop -> review -> test -> done`
-- OpenCode-facing workflow commands such as `workflow_open`, `workflow_attach`, `workflow_status`, `workflow_answer`, `workflow_approve`, `workflow_resume`, and `workflow_back`
-- Plugin loading and native primary workflow agent registration for OpenCode-style hosts
-- `install` and `doctor` flows for bootstrapping configuration and validating setup
-- Review/test loop-back semantics, human breakpoints, event storage, attach/re-attach support
-
-## 2. Who this is for
-
-Autopilot is a good fit if you want to:
-
-- add a workflow primary agent to an OpenCode-style host,
-- structure engineering work into explicit workflow phases,
-- validate a workflow runtime and command surface through a plugin.
-
-## 3. Prerequisites
-
-Recommended environment:
-
-- macOS / Linux / Windows
-- [Bun](https://bun.sh/) `1.3.5` or a compatible version
-- OpenCode installed if you want to actually load and verify the plugin
-
-Check Bun:
-
-```bash
-bun --version
-```
-
-If Bun is not installed yet:
-
-```bash
-curl -fsSL https://bun.sh/install | bash
-```
-
-Then restart your terminal and verify again:
-
-```bash
-bun --version
-```
-
-## 4. Installation
-
-### 4.1 Recommended: install as an npm plugin package
-
-OpenCode supports npm-based plugins directly. Once this package is published, the simplest configuration is:
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot"]
-}
-```
-
-You can also pin a version:
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot@0.1.2"]
-}
-```
-
-In this mode, OpenCode installs and caches the npm package automatically. No manual `git clone`, local `plugin.js`, or extra install script is required.
-
-### 4.2 Fallback: install from GitHub Releases
-
-If you prefer a local-file installation path or need a fallback distribution mode, use the one-line installer from GitHub Releases:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
-```
-
-Install a specific version:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash -s -- --version v0.1.2
-```
-
-The fallback installer will:
-
-- download the prebuilt release package from GitHub Releases,
-- install it into `~/.config/opencode/plugins/autopilot/`,
-- update `~/.config/opencode/opencode.json`.
-
-Release requirement:
-
-- Each GitHub Release must include `autopilot-release.tar.gz`
-- The repository includes `.github/workflows/release.yml`, which builds and uploads that file automatically on `v*` tags
-
-If you want to modify the codebase or work from source, continue with the source setup below.
-
-### 4.3 Clone the repository
-
-```bash
-git clone https://github.com/juhuaxia/Autopilot.git
-cd Autopilot
-```
-
-### 4.4 Install dependencies
-
-```bash
-bun install
-```
-
-The project uses `bun.lock`, so dependencies are expected to stay reproducible.
-
-## 5. Recommended first-run commands
-
-Run these from the project root:
-
-```bash
-bun run src/cli.ts install
-bun run src/cli.ts doctor
-bun run build
-```
-
-What they do:
-
-1. `install`
-   - creates project-level `.workflow-harness/autopilot.json`
-   - creates global `~/.config/opencode/autopilot.json` when missing
-   - tries to safely update `~/.config/opencode/opencode.json`
-   - normalizes `opencode.jsonc` into `opencode.json` when safe
-2. `doctor`
-   - checks `autopilot.json`
-   - checks `skillRoots`
-   - checks phase-level `requiredSkills`
-   - reports warnings and missing pieces
-3. `build`
-   - compiles TypeScript
-   - produces `dist/plugin.js`
-
-After that, confirm:
-
-- `.workflow-harness/autopilot.json` exists
-- `doctor` shows no blocking configuration issue
-- `dist/plugin.js` exists
-
-## 6. Common development commands
-
-### 6.1 Build
-
-```bash
-bun run build
-```
-
-### 6.2 Typecheck
-
-```bash
-bun run typecheck
-```
-
-### 6.3 Run tests
-
-```bash
-bun test
-```
-
-### 6.4 Run plugin smoke tests
-
-```bash
-bun run smoke:plugin
-```
-
-### 6.5 Run CLI commands directly
-
-```bash
-bun run src/cli.ts doctor
-bun run src/cli.ts install
-```
-
-Or through the script alias:
-
-```bash
-bun run cli --help
-```
-
-> The CLI mainly provides workflow initialization, attach/status flows, and install/doctor actions.
-
-## 7. CLI quick usage
-
-### 7.1 Initialize config
-
-```bash
-bun run src/cli.ts install
-```
-
-### 7.2 Run a self-check
-
-```bash
-bun run src/cli.ts doctor
-```
-
-### 7.3 Create a workflow
-
-```bash
-bun run src/cli.ts workflow-open wf-1
-```
-
-### 7.4 Check workflow status
-
-```bash
-bun run src/cli.ts workflow-status wf-1
-```
-
-### 7.5 Re-attach to the workflow channel
-
-```bash
-bun run src/cli.ts workflow-attach wf-1
-```
-
-## 8. Loading the plugin into OpenCode
-
-### 8.0 Recommended npm plugin path
-
-Recommended OpenCode config:
+Add the plugin to your OpenCode config:
 
 ```json
 {
@@ -227,237 +14,109 @@ Recommended OpenCode config:
 }
 ```
 
-### 8.1 Fallback release-based path
-
-If you prefer a local installed fallback plugin, use:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
-```
-
-Default install location:
-
-```txt
-~/.config/opencode/plugins/autopilot/
-```
+Restart `opencode`.
 
-The installer will register a plugin entry similar to:
+If the plugin loads correctly, you should see a log like:
 
 ```txt
-file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js
-```
-
-### 8.2 Source-development path
-
-Run:
-
-```bash
-bun run src/cli.ts install
-bun run src/cli.ts doctor
-```
-
-If the installer can safely update the OpenCode config, you usually do not need to edit anything manually.
-
-> `install.sh` targets GitHub Releases installs. The project-local installer targets source-development setups.
-
-### 8.3 Manual plugin registration
-
-OpenCode config is usually located at:
-
-- `~/.config/opencode/opencode.json`
-- or `~/.config/opencode/opencode.jsonc`
-
-#### Option A: load the built plugin
-
-Build first:
-
-```bash
-bun run build
-```
-
-Then add this to OpenCode config:
-
-```json
-{
-  "plugin": [
-    "file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js"
-  ]
-}
-```
-
-#### Option B: load source directly during development
-
-```json
-{
-  "plugin": [
-    "file:///ABSOLUTE_PATH_TO_PROJECT/plugin.ts"
-  ]
-}
+[autopilot] Autopilot plugin loaded (... commands)
 ```
 
-### 8.4 Start OpenCode
+## Use
 
-Interactive mode:
-
-```bash
-opencode
-```
+Start with a natural-language request, for example:
 
-Server mode:
-
-```bash
-opencode serve
+```txt
+Add sorting to the product list page and make sure regression risks are reviewed.
 ```
 
-## 9. What you should see after loading
+Autopilot will guide the workflow through the available tools:
 
-The plugin exposes these tools/commands:
-
-- `workflow_channel`
 - `workflow_open`
 - `workflow_attach`
 - `workflow_status`
 - `workflow_answer`
 - `workflow_approve`
 - `workflow_resume`
-- `workflow_back`
-- `workflow_doctor`
 
-Recommended split-tool entrypoints:
+You usually only need to follow the next recommended tool shown by the workflow output.
 
-- `workflow_open`
-- `workflow_attach`
-- `workflow_status`
-- `workflow_answer`
-- `workflow_approve`
-- `workflow_resume`
-- `workflow_back`
+## Configuration
 
-Typical load log:
+Autopilot automatically creates these files when needed:
 
 ```txt
-[autopilot] Autopilot plugin loaded (... commands)
+.workflow-harness/autopilot.json
+~/.config/opencode/autopilot.json
 ```
 
-## 10. Directory layout
-
-### 10.1 Configuration layers
-
-- user default: `~/.config/opencode/autopilot.json`
-- project override: `<repo>/.workflow-harness/autopilot.json`
-- runtime state: `<repo>/.workflow-harness/workflows/<workflowId>/`
+If they are left empty, Autopilot uses default behavior.
 
-### 10.2 What each directory does
+### `autopilot.json`
 
-- `src/` — CLI entrypoints and top-level source files
-- `packages/runtime/` — workflow runtime implementation
-- `tests/` — tests
-- `scripts/` — auxiliary scripts
-- `.workflow-harness/` — runtime config, state, and artifacts
-- `dist/` — build output
-
-## 11. Minimal `autopilot.json` example
-
-Start with a fully neutral config:
+Minimal example:
 
 ```json
 {
   "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
   "phases": {
+    "spec_refinement": { "requiredSkills": [] },
+    "plan": { "requiredSkills": [] },
     "develop": { "requiredSkills": [] },
+    "review": { "requiredSkills": [] },
     "test": { "requiredSkills": [] }
   }
 }
 ```
 
-Then add skills per project. For example, for a frontend-oriented project:
-
-```json
-{
-  "skillRoots": ["~/.claude/skills", "~/.config/opencode/skills"],
-  "phases": {
-    "develop": { "requiredSkills": ["frontend-design"] },
-    "test": { "requiredSkills": ["playwright"] }
-  }
-}
-```
-
-That frontend example is only an example. The workflow runtime is not frontend-bound by default.
+Field meanings:
 
-Recommendations:
+- `skillRoots`: directories to scan for skill files
+- `phases.<phase>.requiredSkills`: skills to inject into that phase
 
-- keep skill/profile config in global or project-level `autopilot.json`
-- do not put skill config under `workflows/<workflowId>/`
-- run `workflow_doctor` or CLI `doctor` before using a new config
+Supported phases:
 
-## 12. FAQ
+- `spec_refinement`
+- `plan`
+- `develop`
+- `review`
+- `test`
 
-### Q1: What if `install` cannot update my OpenCode config?
+If an old `workflow.json` exists and `autopilot.json` does not, Autopilot can reuse the legacy file and warn you to migrate.
 
-Edit OpenCode config manually and add either the release plugin path or the local build path to the `plugin` array. Example:
+## Fallback Install
 
-```json
-{
-  "plugin": [
-    "file:///Users/<your-user>/.config/opencode/plugins/autopilot/plugin.js"
-  ]
-}
-```
-
-For source development, you can also point to your local `dist/plugin.js`.
+If you prefer a local file install instead of the npm package:
 
-If you are using the npm plugin mode, you can simply configure:
-
-```json
-{
-  "plugin": ["@fkqfkq123/opencode-autopilot"]
-}
+```bash
+curl -fsSL https://raw.githubusercontent.com/juhuaxia/Autopilot/main/install.sh | bash
 ```
 
-### Q2: Why can’t I see workflow commands after building?
-
-That usually means the host integration layer has not actually registered the exported `workflowCommands` onto the host command/tool surface.
-
-### Q3: What should I validate first?
-
-Validate this order first:
+## Troubleshooting
 
-1. the host can import the plugin file
-2. the host can call the default export
-3. the host receives a plugin-like object
+### OpenCode fails to start
 
-Do not start by validating UI behavior first.
+Temporarily remove the plugin from `opencode.json`, restart OpenCode, then re-enable it after checking the config.
 
-### Q4: Any important rule for the plugin root entry?
+### The plugin loads but workflow commands do not appear
 
-The root `plugin.ts` entry should only expose a single host-callable default export. Do not expose extra internal classes or helper functions from the root entry.
+This usually means the host did not register the exported workflow tools correctly.
 
-## 13. Recommended reading
+### A workflow seems broken
 
-| Document | Purpose |
-|---|---|
-| `README.md` | Main entry for installation, release, and usage |
-| `WORKFLOW_SKILL_PROFILE_ARCHITECTURE_CN.md` | Skill/profile configuration design |
-| `OPENCODE_WORKFLOW_AGENT_GUIDE.md` | Agent/tool calling loop |
-| `REQUIREMENT_TEMPLATE.md` | Requirement input template |
+Delete the project runtime folder and start again:
 
-Internal planning notes, acceptance drafts, and status scratch docs can be kept locally under `docs_internal/`, which is ignored by default.
+```bash
+rm -rf .workflow-harness
+```
 
-## 14. Fastest path to a working setup
+## For source development
 
-If you just want the fastest local source setup:
+If you want to work on the plugin itself:
 
 ```bash
 bun install
-bun run src/cli.ts install
-bun run src/cli.ts doctor
+bun run typecheck
+bun test
 bun run build
-opencode
 ```
-
-Then:
-
-1. confirm `.workflow-harness/autopilot.json` exists
-2. confirm `dist/plugin.js` exists
-3. if OpenCode does not auto-load the plugin, add `file:///ABSOLUTE_PATH_TO_PROJECT/dist/plugin.js` manually to config
-4. verify `workflow_open`, `workflow_attach`, and `workflow_status` are visible in the host

package/dist/packages/core/src/state/workflow-runtime-state.d.ts

@@ -1,4 +1,5 @@
 export type RecoveryState = "idle" | "recovering";
+export type PhaseDispatchAttempts = Partial<Record<"spec_refinement" | "plan" | "develop" | "review" | "test", number>>;
 export interface WorkflowRuntimeState {
     workflowId: string;
     preferredForegroundSessionId?: string | null;
@@ -11,4 +12,5 @@ export interface WorkflowRuntimeState {
     refinementLastDispatchSummary?: string | null;
     refinementEscalationReason?: string | null;
     lastContinuationAt?: string;
+    phaseDispatchAttempts?: PhaseDispatchAttempts;
 }

package/dist/packages/core/src/transitions/default-phase-transition.js

@@ -1,4 +1,24 @@
 const MAX_SPEC_REFINEMENT_SELF_REPAIR_ATTEMPTS = 1;
+const MAX_CONSECUTIVE_FAILURES = 3;
+const MAX_REVIEW_OR_TEST_UNKNOWN_DISPATCH_ATTEMPTS = 3;
+function getPhaseDispatchAttempts(runtime, phase) {
+    return runtime.phaseDispatchAttempts?.[phase] ?? 0;
+}
+function shouldEscalateUnknownConclusion(input, phase) {
+    if (getPhaseDispatchAttempts(input.runtime, phase) < MAX_REVIEW_OR_TEST_UNKNOWN_DISPATCH_ATTEMPTS) {
+        return null;
+    }
+    const action = {
+        type: "blocked",
+        workflowId: input.workflow.workflowId,
+        phase,
+        reason: `${phase} exceeded dispatch retry budget and needs human decision`,
+        required: true,
+        createdAt: new Date().toISOString(),
+        ...(input.artifact.summary ? { summary: input.artifact.summary } : {}),
+    };
+    return { type: "wait_human", action };
+}
 function nextPhaseFor(current) {
     if (current === "spec_refinement")
         return "plan";
@@ -68,6 +88,9 @@ export class DefaultPhaseTransition {
             return { type: "stop", reason: "Background work still in progress" };
         }
         if (session.status === "failed") {
+            if (runtime.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                return { type: "recover", reason: "Exceeded consecutive failure retry budget" };
+            }
             return { type: "recover", reason: "Relevant session failed" };
         }
         if (workflow.phase === "spec_refinement"
@@ -141,6 +164,17 @@ export class DefaultPhaseTransition {
                     reason: `Continue phase ${workflow.phase}`,
                 };
             }
+            if (artifact.reportStatus === "unknown" && workflow.status === "in_progress" && (session.status === "idle" || session.status === "stale")) {
+                const escalation = shouldEscalateUnknownConclusion(input, "review");
+                if (escalation) {
+                    return escalation;
+                }
+                return {
+                    type: "dispatch",
+                    phase: workflow.phase,
+                    reason: "Review conclusion is still ambiguous; set an explicit PASS or FAIL conclusion",
+                };
+            }
         }
         if (workflow.phase === "test") {
             if (artifact.valid && artifact.missing.length === 0 && artifact.reportStatus === "pass") {
@@ -171,6 +205,17 @@ export class DefaultPhaseTransition {
                     reason: `Continue phase ${workflow.phase}`,
                 };
             }
+            if (artifact.reportStatus === "unknown" && workflow.status === "in_progress" && (session.status === "idle" || session.status === "stale")) {
+                const escalation = shouldEscalateUnknownConclusion(input, "test");
+                if (escalation) {
+                    return escalation;
+                }
+                return {
+                    type: "dispatch",
+                    phase: workflow.phase,
+                    reason: "Test conclusion is still ambiguous; set an explicit PASS or FAIL conclusion",
+                };
+            }
         }
         if (artifact.readyForNextPhase) {
             const nextPhase = nextPhaseFor(workflow.phase);

package/dist/packages/runtime/src/artifacts/file-system-artifact-evaluator.js

@@ -145,6 +145,7 @@ const extractSectionBody = (content, heading, allHeadings) => {
     return stripComments(content.slice(afterHeading, end));
 };
 const sectionHasContent = (content, heading, allHeadings) => extractSectionBody(content, heading, allHeadings).length > 0;
+const isOptionalSection = (heading) => heading.includes("（如适用）") || heading.includes("（非阻塞，可选）");
 const sanitizeSummaryBody = (body) => body
     .split("\n")
     .map((line) => line.trim())
@@ -1090,6 +1091,9 @@ export class FileSystemArtifactEvaluator {
                 missing.push(sectionRule.title);
             }
             for (const section of sectionRule.sections) {
+                if (isOptionalSection(section)) {
+                    continue;
+                }
                 if (!content.includes(section) || !sectionHasContent(content, section, sectionRule.sections)) {
                     missing.push(section);
                 }
@@ -1140,8 +1144,8 @@ export class FileSystemArtifactEvaluator {
                         readyForNextPhase: false,
                         missing,
                         summary: "审查报告结构不完整，暂不能决定 pass/fail",
-                        reportStatus: "unknown",
-                        hasBlockingSeverity: false,
+                        reportStatus: getReportStatus(content),
+                        hasBlockingSeverity: hasBlockingSeverity(content),
                     };
                 }
                 if (phase === "test") {
@@ -1150,7 +1154,7 @@ export class FileSystemArtifactEvaluator {
                         readyForNextPhase: false,
                         missing,
                         summary: "测试报告证据不足，暂不能决定 pass/fail",
-                        reportStatus: "unknown",
+                        reportStatus: getReportStatus(content),
                         hasBlockingSeverity: false,
                     };
                 }

package/dist/packages/runtime/src/bootstrap/create-harness.d.ts

@@ -14,6 +14,7 @@ export interface CreateHarnessOptions {
     sessionClient?: OpencodeSessionClient;
     opencodeBaseUrl?: string;
     opencodePassword?: string;
+    homeDir?: string;
 }
 export declare function createHarness(baseDir: string, options?: CreateHarnessOptions): Promise<{
     stateStore: FileSystemWorkflowStateStore;

package/dist/packages/runtime/src/bootstrap/create-harness.js

@@ -22,9 +22,10 @@ export async function createHarness(baseDir, options = {}) {
     await mkdir(join(baseDir, "workflows"), { recursive: true });
     const workspace = new DefaultWorkflowWorkspace(baseDir);
     await ensureAutopilotConfigFile(workspace.workflowConfigFile());
-    await ensureAutopilotConfigFile(join(homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME));
+    await ensureAutopilotConfigFile(join(options.homeDir ?? homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME));
     const resolvedConfig = await resolveWorkflowConfig({
         projectConfigFile: workspace.workflowConfigFile(),
+        ...(options.homeDir ? { homeDir: options.homeDir } : {}),
     });
     const skillRegistryResult = await buildSkillRegistryWithWarnings(resolvedConfig.skillRoots);
     const skillRegistry = skillRegistryResult.registry;

package/dist/packages/runtime/src/bootstrap/initialize-workflow.js

@@ -26,6 +26,7 @@ export async function initializeWorkflow(args) {
         refinementAttempts: 0,
         refinementLastDispatchSummary: null,
         refinementEscalationReason: null,
+        phaseDispatchAttempts: {},
     };
     await stateStore.saveWorkflow(workflow);
     await stateStore.saveRuntime(runtime);

package/dist/packages/runtime/src/diagnostics/workflow-doctor.d.ts

@@ -20,4 +20,6 @@ export type WorkflowDoctorResult = {
     nextSteps: string[];
     warnings: string[];
 };
-export declare function runWorkflowDoctor(workspace: WorkflowWorkspace): Promise<WorkflowDoctorResult>;
+export declare function runWorkflowDoctor(workspace: WorkflowWorkspace, options?: {
+    homeDir?: string;
+}): Promise<WorkflowDoctorResult>;

package/dist/packages/runtime/src/diagnostics/workflow-doctor.js

@@ -27,11 +27,12 @@ function gitignoreHasWorkflowHarness(content) {
         return normalized.includes(".workflow-harness/");
     });
 }
-export async function runWorkflowDoctor(workspace) {
+export async function runWorkflowDoctor(workspace, options = {}) {
     const projectConfigFile = workspace.workflowConfigFile();
-    const globalConfigFile = join(homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME);
+    const globalConfigFile = join(options.homeDir ?? homedir(), ".config", "opencode", AUTOPILOT_CONFIG_FILENAME);
     const resolvedConfig = await resolveWorkflowConfig({
         projectConfigFile,
+        ...(options.homeDir ? { homeDir: options.homeDir } : {}),
     });
     const registryResult = await buildSkillRegistryWithWarnings(resolvedConfig.skillRoots);
     const checks = [];

package/dist/packages/runtime/src/engine/default-workflow-engine.js

@@ -195,6 +195,12 @@ export class DefaultWorkflowEngine {
                     });
                     const waitRuntimePatch = {
                         waitingHumanActionId: record.id,
+                        phaseDispatchAttempts: {
+                            ...(runtime.phaseDispatchAttempts ?? {}),
+                            ...(workflow.phase === "spec_refinement" || workflow.phase === "plan" || workflow.phase === "develop" || workflow.phase === "review" || workflow.phase === "test"
+                                ? { [workflow.phase]: 0 }
+                                : {}),
+                        },
                         ...(workflow.phase === "spec_refinement" && (runtime.refinementAttempts ?? 0) > 0
                             ? { refinementEscalationReason: "Autonomous refinement retry budget exhausted" }
                             : {}),
@@ -229,6 +235,8 @@ export class DefaultWorkflowEngine {
                     await this.deps.humanActionStore.markConsumed(currentHumanAction.id);
                     await this.deps.stateStore.updateRuntime(workflowId, {
                         waitingHumanActionId: null,
+                        consecutiveFailures: 0,
+                        phaseDispatchAttempts: {},
                         ...(workflow.phase === "spec_refinement"
                             ? {
                                 refinementAttempts: 0,
@@ -275,6 +283,13 @@ export class DefaultWorkflowEngine {
                     : 0;
                 const runtimePatch = {
                     lastContinuationAt: new Date().toISOString(),
+                    consecutiveFailures: 0,
+                    phaseDispatchAttempts: {
+                        ...(runtime.phaseDispatchAttempts ?? {}),
+                        ...(action.phase === "spec_refinement" || action.phase === "plan" || action.phase === "develop" || action.phase === "review" || action.phase === "test"
+                            ? { [action.phase]: (runtime.phaseDispatchAttempts?.[action.phase] ?? 0) + 1 }
+                            : {}),
+                    },
                     ...(action.phase === "spec_refinement"
                         ? {
                             refinementAttempts: nextAttempt,

package/dist/packages/runtime/src/plugin/workflow-plugin-entry.js

@@ -30,7 +30,7 @@ Hard rules:
 - If the user provides natural language only, keep it as-is and let the workflow runtime + downstream AI refinement handle understanding and document selection.
 `;
 const WORKFLOW_PRIMARY_AGENT_DESCRIPTION = "Primary workflow agent that drives refine->plan->develop->review->test via workflow tools";
-const WORKFLOW_PRIMARY_AGENT_MODEL = "ppchat-codex/gpt-5.4";
+const WORKFLOW_PRIMARY_AGENT_MODEL = "openai/gpt-5.5";
 function buildPrimaryAgentMetadata(baseDir) {
     return {
         name: "workflow",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fkqfkq123/opencode-autopilot",
   "private": false,
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "An OpenCode plugin for attached-session workflow execution with refinement, planning, development, review, and test phases.",
   "type": "module",
   "packageManager": "bun@1.3.5",