relay-kit 0.2.0 → 0.3.1

package/README.md

@@ -1,236 +1,248 @@
-# relay-kit
-
-`relay-kit` 是一个 **Skills-first、CLI-assisted** 的 AI 编程工作流工具包。它把 Advisor Strategy 固化为可复用流程：小模型 / Executor 负责执行，聪明模型 / Advisor 负责规划、指点和 Review，人类 Owner 负责方向、验收和最终提交。
-
-它不是自动写代码工具，也不是多 Agent 框架。它只负责初始化规则、安装项目级 Skills、生成 handoff 文件、收集受限上下文，并帮助你在真实项目里把任务交给 OpenCode、Claude Code、Codex 或其他执行工具。
-
-```text
-OpenSpec 管“做什么”
-relay-kit 管“怎么交给小模型、卡住怎么求助、完成怎么 Review”
-OpenCode / Claude Code / Codex 等工具负责实际执行
-```
-
-## 安装
-
-从 npm 安装：
+<p align="center">
+  <img src="https://img.shields.io/npm/v/relay-kit.svg" alt="npm version">
+  <img src="https://img.shields.io/node/v/relay-kit.svg" alt="node version">
+  <img src="https://img.shields.io/npm/l/relay-kit.svg" alt="license">
+</p>
+
+# relay-kit 🔄
+
+> **Skills-first、CLI-assisted 的 AI 编程接力工作流工具包**
+>
+> 把 AI 编程拆成「规划 → 委派 → 执行 → 求助 → 审查」的接力赛。
+> 内置 OpenSpec，零外部依赖。
+
+```
+                  ┌──────────────────────────────────────┐
+                  │              人类 Owner               │
+                  │          方向 · 验收 · 提交            │
+                  └────┬──────────┬──────────┬───────────┘
+                       │ 规划      │ 求助     │ 审查
+                       ▼           ▼          ▼
+  ┌─────────────────────────────────────────────────────────────┐
+  │                    relay-kit 工作流                          │
+  │                                                             │
+  │   /relay:plan         relay ask         /relay:review       │
+  │   规划顾问 ──────────► ASK_ADVISOR ────► 审查顾问            │
+  │      │                     ▲                │               │
+  │      │ 委派                │ 升级           │ 裁决          │
+  │      ▼                     │                ▼               │
+  │   relay start          /relay:run        ADVISOR_DECISION   │
+  │   EXECUTOR_TASK ──────► 执行者 ──────────► REPLAN / FIX     │
+  │                                                             │
+  │   内置 OpenSpec (relay openspec)                              │
+  │   new-change → status → instructions → archive              │
+  └─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 为什么 relay-kit？
+
+|              | 裸用 AI 工具                  | 多 Agent 框架              | **relay-kit**                   |
+| ------------ | ---------------------------- | ------------------------- | ------------------------------- |
+| **定位**     | 聊天式编程                   | 自动化 Agent 协作         | **人工主导的接力工作流**        |
+| **角色分工** | 无                           | Agent 自行协商            | **Owner / Advisor / Executor**  |
+| **任务交接** | 粘贴对话                     | 框架内部传递              | **结构化的 handoff 文件**       |
+| **卡住处理** | 手动问                       | 自动重试或失败            | **ASK_ADVISOR 升级 → 人工决策** |
+| **代码审查** | 肉眼 diff                    | 无                        | **REVIEW_REQUEST → 裁决报告**   |
+| **规范驱动** | 无                           | 取决于框架                | **内置 spec-driven OpenSpec**   |
+| **依赖**     | 零                           | 重                        | **零外部依赖（CLI 仅 commander）** |
+
+relay-kit 不是「自动写代码」工具，也不是「多 Agent 框架」。它是**把真实团队的工作流（PM 规划 → 工程师执行 → 卡住求助 → 代码审查）固化为 AI 可复用的流程**。
+
+---
+
+## 快速开始
+
+### 安装
 
 ```bash
 npm install -g relay-kit
 relay --help
 ```
 
-从当前仓库本地试用：
-
-```bash
-pnpm install
-pnpm build
-npm link
-relay --help
-```
-
-使用打包产物试用：
-
-```bash
-pnpm build
-npm pack
-npm install -g ./relay-kit-0.1.0.tgz
-relay --help
-```
-
-本地 `npm link` 会写入全局 npm link 状态。试用结束后可以清理：
-
-```bash
-npm unlink -g relay-kit
-```
-
-## 快速开始：simple 模式
-
-适合没有 OpenSpec 的项目。
+### 初始化项目
 
 ```bash
 cd your-project
-relay init --mode simple
-relay start --title "实现登录错误提示" --scope "src/**" --blocked-scope "不要修改数据库 schema"
-relay ask
-relay review
-relay doctor
-```
-
-执行后会生成项目级配置、Skills 和 handoff 文件：
-
-```text
-.relay/config.json
-.relay/state.json
-.relay/skills/
-.claude/skills/
-.agents/skills/
-docs/agent-handoffs/runs/<run-id>/lanes/main/EXECUTOR_TASK.md
-docs/agent-handoffs/runs/<run-id>/lanes/main/ASK_ADVISOR.md
-docs/agent-handoffs/runs/<run-id>/lanes/main/REVIEW_REQUEST.md
-AGENTS.md
-```
-
-如果 Advisor 已经把决策写入 `ADVISOR_DECISION.md`，可以继续生成给 Executor 的恢复提示：
-
-```bash
-relay resume
+relay init
 ```
 
-## 快速开始：OpenSpec 模式
-
-适合已经有 `openspec/` 的项目。relay-kit 会读取 change 文档并生成交接材料，但不会替代 `/opsx:apply`，也不会自动执行 OpenSpec change。
+无 `openspec/` 时会弹出交互菜单：
 
-```bash
-cd your-openspec-project
-relay init --mode openspec
-relay start --change add-example-feature --title "执行 add-example-feature"
-relay ask
-relay review
-relay doctor
 ```
-
-如果项目还没有 OpenSpec，可以只显示引导说明：
-
-```bash
-relay init --with-openspec
+Select initialization mode:
+  1. Simple mode  — relay-kit standalone (no OpenSpec)
+  2. OpenSpec mode — integrated with OpenSpec for spec-driven development (recommended)
+Choose mode (1/2, default 2):
 ```
 
-这个命令不会静默创建 `openspec/`。
-
-## 命令说明
+选择 OpenSpec 模式后自动创建 `openspec/` 结构并安装全套命令和 Skills。如果系统已安装过外部 `openspec` CLI，会提示选择使用内置还是外部版本。
 
-### relay init
-
-初始化当前项目：
+也可以跳过交互直接指定：
 
 ```bash
-relay init
-relay init --mode simple
-relay init --mode openspec
-relay init --with-openspec
-relay init --force
+relay init --mode openspec --yes
 ```
 
-`init` 会写入 `.relay/config.json`、`.relay/state.json`、`.relayignore`、`AGENTS.md` advisor 规则、项目级 Skills 和 `docs/agent-handoffs/runs/`。
-
-### relay start
-
-开始一次 handoff run，生成 `EXECUTOR_TASK.md`：
+### 规划 → 执行 → 审查
 
 ```bash
-relay start --title "实现登录错误提示" --scope "src/**" --blocked-scope "不要修改数据库 schema"
-relay start --change add-example-feature --title "执行 add-example-feature"
-relay start --copy
-```
+# 1. 创建 OpenSpec change
+relay openspec new-change add-login
 
-`start` 只生成交接文件，不调用模型、不执行构建、不提交 git。
+# 2. 让 Advisor 规划并生成制品（在 AI 工具中运行）
+# /opsx:propose add-login
 
-### relay ask
+# 3. 生成执行任务
+relay start --change add-login --title "实现登录功能"
 
-Executor 卡住时生成 `ASK_ADVISOR.md`：
+# 4. 交给 Executor 执行（在 AI 工具中运行）
+# /relay:run
 
-```bash
+# 5. 卡住时生成求助包
 relay ask
-relay ask --run build
-relay ask --run test
-relay ask --copy
-```
-
-默认只收集现有上下文。只有显式传入 `--run build` 或 `--run test` 时，才会执行项目配置中的 build/test 命令，并把命令、退出码和截断日志写入求助包。
-
-### relay resume
-
-读取 Advisor 决策并生成 `RESUME_PROMPT.md`：
-
-```bash
-relay resume
-relay resume --from ./ADVISOR_DECISION.md
-relay resume --copy
-```
-
-默认从当前 run/lane 的 `ADVISOR_DECISION.md` 读取决策。
-
-### relay review
 
-完成实现后生成 `REVIEW_REQUEST.md`：
-
-```bash
+# 6. Advisor 审查
 relay review
-relay review --copy
 ```
 
-`review` 会收集当前任务、OpenSpec 上下文和受限 git diff，交给 Advisor 做审查。
-
-### relay doctor
-
-检查当前项目接入状态：
-
-```bash
-relay doctor
-```
-
-它会检查配置、状态、`AGENTS.md` 注入块、Skills 目录、handoff 目录、OpenSpec 状态和 package scripts。
-
-### relay sync --skills
+---
+
+## 命令参考
+
+### relay-kit 核心命令
+
+| 命令 | 说明 |
+|------|------|
+| `relay init` | 初始化项目（交互式选择 simple / openspec 模式） |
+| `relay start` | 生成 EXECUTOR_TASK.md，开始一次 handoff run |
+| `relay ask` | Executor 卡住时生成 ASK_ADVISOR.md 求助包 |
+| `relay resume` | 读取 ADVISOR_DECISION.md，生成 RESUME_PROMPT.md 继续执行 |
+| `relay review` | 完成实现后生成 REVIEW_REQUEST.md，交给 Advisor 审查 |
+| `relay doctor` | 诊断当前项目接入状态 |
+| `relay sync` | 同步 Skills 和 OpenSpec 文件到目标工具目录 |
+
+### relay openspec 子命令（内置 OpenSpec CLI）
+
+| 命令 | 说明 |
+|------|------|
+| `relay openspec new-change <name>` | 创建新的 OpenSpec change |
+| `relay openspec status --change <name>` | 查看 artifact 完成状态 |
+| `relay openspec list` | 列出所有活跃 changes |
+| `relay openspec instructions <id> --change <name>` | 获取 artifact 创建指引（模板 + 规则） |
+| `relay openspec apply-instructions --change <name>` | 获取 apply 执行指引和任务进度 |
+| `relay openspec archive <name>` | 归档已完成的 change |
+| `relay openspec schemas` | 列出可用 workflow schema |
+
+### relay sync 选项
+
+| 选项 | 说明 |
+|------|------|
+| `relay sync --skills` | 同步 relay Skills 到项目工具目录 |
+| `relay sync --openspec` | 同步 OpenSpec 命令/Skill 文件 |
+| `relay sync --all` | 同步所有（Skills + OpenSpec 文件） |
+| `--target claude \| codex \| all` | 指定同步目标工具 |
+| `--scope project \| user` | 项目级或用户级（默认 project） |
+| `--dry-run` | 预览同步计划，不写入文件 |
+| `--force` | 覆盖冲突的目标文件 |
+
+---
+
+## 工作流
+
+```
+/relay:plan                 /opsx:propose              relay start
+规划顾问 ───► PLAN_REPORT ───► proposal.md ───► EXECUTOR_TASK.md
+(Advisor)                     design.md                 (handoff 文件)
+                              tasks.md
+                                 │
+                    ┌────────────┘
+                    ▼
+              /relay:run
+              执行者 ───► 修改代码 ───► [x] 完成任务
+              (Executor)
+                    │
+          ┌─────────┴─────────┐
+          ▼                   ▼
+      成功完成            卡住 / 失败
+          │                   │
+          ▼                   ▼
+    relay review          relay ask
+    REVIEW_REQUEST.md     ASK_ADVISOR.md
+          │                   │
+          ▼                   ▼
+    /relay:review         Advisor 决策
+    审查顾问 ───►           │
+    APPROVE /            ┌──┴──────────────┐
+    NEEDS_CHANGES /      ▼                 ▼
+    REPLAN_REQUIRED   CONTINUE          REPLAN / FIX
+                       │                 │
+                       ▼                 ▼
+                  relay resume      重新规划
+                  RESUME_PROMPT.md   或 DIRECT_FIX
+```
+
+---
+
+## 安装与目录结构
+
+`relay init` 后项目下生成：
+
+```
+your-project/
+├── .relay/
+│   ├── config.json          # 项目配置
+│   ├── state.json           # 运行时状态
+│   └── skills/              # relay Skills 管理副本
+├── .relayignore             # 上下文收集忽略规则
+├── .opencode/               # OpenCode 的 OpenSpec 命令/Skill
+├── .claude/
+│   ├── commands/opsx/       # Claude Code 的 OpenSpec 命令
+│   └── skills/              # relay + OpenSpec Skills
+├── .codex/
+│   └── skills/              # Codex 的 OpenSpec Skills
+├── .agents/
+│   └── skills/              # Codex 的 relay Skills
+├── openspec/                # OpenSpec 规范目录
+│   ├── changes/             # 活跃 changes
+│   ├── specs/               # 全局 spec
+│   └── changes/archive/     # 已归档 changes
+├── docs/agent-handoffs/runs/  # handoff 文件
+└── AGENTS.md                # relay-kit 执行规则注入
+```
+
+---
 
-把 `.relay/skills` 中的 advisor Skills 同步到工具目录：
+## 上下文安全
 
-```bash
-relay sync --skills
-relay sync --skills --target claude
-relay sync --skills --target codex
-relay sync --skills --target all --scope project
-relay sync --skills --target all --scope user
-relay sync --skills --dry-run
-relay sync --skills --force
-```
+`relay ask` 和 `relay review` 收集上下文时会应用**三层防护**：
 
-默认只同步到当前项目配置启用的项目级目录，不会写入用户级 Skills。发生冲突时默认跳过并报告；确认要覆盖时再使用 `--force`。
+1. **默认忽略** — `.env`, `node_modules/`, `dist/`, `build/`, `*.pem`, `*.key` 等
+2. **`.relayignore`** — 项目自定义忽略规则，默认包含常见敏感路径
+3. **基础脱敏** — API key, token, secret, password, bearer token, private key block
 
-## Skills 安装目录
+它不是完整安全扫描器，而是**防止常见泄露的保护层**。
 
-`relay init` 默认安装项目级 Skills：
+---
 
-```text
-.relay/skills   relay-kit 管理副本，必选
-.claude/skills        Claude Code 项目级 Skills
-.agents/skills        Codex 项目级 Skills
-```
+## 从已有 OpenSpec 项目迁移
 
-用户级目录只在显式同步时使用：
+如果项目已经通过外部 `openspec` CLI（`@fission-ai/openspec`）初始化过：
 
-```text
-~/.claude/skills
-~/.agents/skills
+```bash
+relay init --mode openspec --force    # 覆盖为 relay-kit 内置实现
+relay sync --all                      # 更新全部 Skills 和 OpenSpec 文件
 ```
 
-Codex 项目级目录使用 `.agents/skills`，不会使用 `.codex/skills`。详细规则见 `docs/SKILLS_INSTALLATION.md`。
-
-## 上下文安全
+relay-kit 的 OpenSpec 实现完全兼容已有文件格式，`proposal.md` / `design.md` / `tasks.md` / delta spec 等无需任何修改。只有 `.opencode/`、`.claude/commands/opsx/`、`.codex/skills/openspec-*/` 中的命令/Skill 文件会被更新为调用内置 `relay openspec`。
 
-`relay init` 会生成默认 `.relayignore`。`relay ask` 和 `relay review` 收集上下文时会同时应用默认忽略规则、`.relayignore` 和基础脱敏规则，避免把环境变量、密钥文件、日志、构建产物或无关大目录写入 handoff 文档。
-
-默认忽略：
-
-```text
-.env
-.env.*
-node_modules/
-dist/
-build/
-coverage/
-.git/
-*.pem
-*.key
-*.crt
-*.p12
-*.log
-```
+## 致谢
 
-基础脱敏会处理常见 API key、token、secret、password、bearer token 和 private key block。它是防止常见泄露的保护层，不是完整安全扫描器。
+OpenSpec 规范源自 [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)。relay-kit 内置了独立实现的 OpenSpec CLI，保持格式兼容。
 
-MVP 不会自动调用模型 API、不会自动执行 OpenCode / Claude Code / Codex、不会自动提交 git，也不会替代 `/opsx:apply`。
+---
 
-## v0.1 alpha 状态
+## 许可
 
-v0.1 alpha 面向本地安装和真实项目试用。发布前检查流程见 `docs/SMOKE_TESTS.md` 和 `docs/V0_1_ALPHA_RELEASE.md`。
+[MIT](LICENSE)