relay-kit

relay-kit

relay-kit 是一个 Skills-first、CLI-assisted 的 AI 编程工作流工具包。它把 Advisor Strategy 固化为可复用流程：小模型 / Executor 负责执行，聪明模型 / Advisor 负责规划、指点和 Review，人类 Owner 负责方向、验收和最终提交。

它不是自动写代码工具，也不是多 Agent 框架。它只负责初始化规则、安装项目级 Skills、生成 handoff 文件、收集受限上下文，并帮助你在真实项目里把任务交给 OpenCode、Claude Code、Codex 或其他执行工具。

OpenSpec 管“做什么”
relay-kit 管“怎么交给小模型、卡住怎么求助、完成怎么 Review”
OpenCode / Claude Code / Codex 等工具负责实际执行

安装

从 npm 安装：

npm install -g relay-kit
relay --help

从当前仓库本地试用：

pnpm install
pnpm build
npm link
relay --help

使用打包产物试用：

pnpm build
npm pack
npm install -g ./relay-kit-0.1.0.tgz
relay --help

本地 npm link 会写入全局 npm link 状态。试用结束后可以清理：

npm unlink -g relay-kit

快速开始：simple 模式

适合没有 OpenSpec 的项目。

cd your-project
relay init --mode simple
relay start --title "实现登录错误提示" --scope "src/**" --blocked-scope "不要修改数据库 schema"
relay ask
relay review
relay doctor

执行后会生成项目级配置、Skills 和 handoff 文件：

.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 的恢复提示：

relay resume

快速开始：OpenSpec 模式

适合已经有 openspec/ 的项目。relay-kit 会读取 change 文档并生成交接材料，但不会替代 /opsx:apply，也不会自动执行 OpenSpec change。

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，可以只显示引导说明：

relay init --with-openspec

这个命令不会静默创建 openspec/。

命令说明

relay init

初始化当前项目：

relay init
relay init --mode simple
relay init --mode openspec
relay init --with-openspec
relay init --force

init 会写入 .relay/config.json、.relay/state.json、.relayignore、AGENTS.md advisor 规则、项目级 Skills 和 docs/agent-handoffs/runs/。

relay start

开始一次 handoff run，生成 EXECUTOR_TASK.md：

relay start --title "实现登录错误提示" --scope "src/**" --blocked-scope "不要修改数据库 schema"
relay start --change add-example-feature --title "执行 add-example-feature"
relay start --copy

start 只生成交接文件，不调用模型、不执行构建、不提交 git。

relay ask

Executor 卡住时生成 ASK_ADVISOR.md：

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：

relay resume
relay resume --from ./ADVISOR_DECISION.md
relay resume --copy

默认从当前 run/lane 的 ADVISOR_DECISION.md 读取决策。

relay review

完成实现后生成 REVIEW_REQUEST.md：

relay review
relay review --copy

review 会收集当前任务、OpenSpec 上下文和受限 git diff，交给 Advisor 做审查。

relay doctor

检查当前项目接入状态：

relay doctor

它会检查配置、状态、AGENTS.md 注入块、Skills 目录、handoff 目录、OpenSpec 状态和 package scripts。

relay sync --skills

把 .relay/skills 中的 advisor Skills 同步到工具目录：

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

默认只同步到当前项目配置启用的项目级目录，不会写入用户级 Skills。发生冲突时默认跳过并报告；确认要覆盖时再使用 --force。

Skills 安装目录

relay init 默认安装项目级 Skills：

.relay/skills   relay-kit 管理副本，必选
.claude/skills        Claude Code 项目级 Skills
.agents/skills        Codex 项目级 Skills

用户级目录只在显式同步时使用：

~/.claude/skills
~/.agents/skills

Codex 项目级目录使用 .agents/skills，不会使用 .codex/skills。详细规则见 docs/SKILLS_INSTALLATION.md。

上下文安全

relay init 会生成默认 .relayignore。relay ask 和 relay review 收集上下文时会同时应用默认忽略规则、.relayignore 和基础脱敏规则，避免把环境变量、密钥文件、日志、构建产物或无关大目录写入 handoff 文档。

默认忽略：

.env
.env.*
node_modules/
dist/
build/
coverage/
.git/
*.pem
*.key
*.crt
*.p12
*.log

基础脱敏会处理常见 API key、token、secret、password、bearer token 和 private key block。它是防止常见泄露的保护层，不是完整安全扫描器。

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。