Rune-Spec/DEVELOPMENT.md

Rune 开发文档

技术栈

• 运行时：Bun
• 语言：TypeScript
• CLI 框架：cac
• YAML 解析：yaml
• 测试：bun:test

项目结构

src/
├── cli.ts              # CLI 入口
├── cli/
│   ├── errors.ts       # CLI 错误定义（CliError 层级）
│   ├── output.ts       # 格式化输出（错误/用法/提示）
│   └── help.ts         # 帮助文本生成
├── types.ts            # 类型定义
├── commands/
│   └── init.ts         # init 命令
├── core/
│   ├── config.ts       # 配置加载
│   ├── scanner.ts      # 状态扫描
│   ├── assembler.ts    # 提示词拼装
│   └── task-parser.ts  # 任务解析
├── adapters/
│   ├── opencode.ts     # OpenCode 适配器
│   └── claude-code.ts  # Claude Code 适配器（占位）
└── defaults/
    └── config.ts       # 内置默认配置

tests/                   # 测试目录（镜像 src 结构）

开发命令

bun test                  # 运行单元/集成测试（排除 agent e2e 测试）
bun run test:e2e          # 运行 agent 端到端测试（Tier 1 + 2，< 5s）
bun run test:e2e:llm      # 运行 LLM-as-Judge 测试（Tier 3，需设置环境变量）
bun test tests/core/      # 运行指定目录测试
bun run release           # 发布新版本（交互式递增版本号、测试门禁、git commit+tag、npm publish）
bun src/cli.ts init opencode  # 测试 init 命令
bun src/cli.ts plan <变更名> <文档名>  # 测试 plan 命令
bun src/cli.ts status [变更名]        # 测试 status 命令
bun src/cli.ts help       # 查看全局帮助
bun src/cli.ts help init  # 查看 init 命令帮助
bun src/cli.ts version    # 查看版本号

Tier 3 LLM-as-Judge 环境变量

export RUNE_E2E_LLM_API_KEY="your-api-key"     # 必填
export RUNE_E2E_LLM_PROVIDER="openai"          # 可选，默认 openai
export RUNE_E2E_LLM_MODEL="gpt-4o-mini"        # 可选，默认 gpt-4o-mini
export RUNE_E2E_LLM_BASE_URL="https://..."     # 可选，自定义 endpoint
bun run test:e2e:llm

代码质量

项目使用 oxlint 进行静态分析，oxfmt 进行代码格式化，提交时通过 husky + lint-staged 自动检查。

bun lint           # 静态分析所有文件
bun format         # 格式化所有文件（写回）
bun format:check   # 检查格式不写回（CI 用）
bun check          # 一键 lint + 格式检查

配置文件：

• .oxlintrc.json — oxlint 规则配置（correctness + suspicious 全开，style 选开）
• .oxfmtrc.json — oxfmt 格式设置（双引号、分号、尾逗号、2 空格缩进、100 行宽、LF 换行）

pre-commit hook： 提交时自动对 staged 文件运行 lint 和格式化，lint 失败会阻止提交。

CLI 交互架构

子命令

CLI 通过子命令提供帮助和版本信息，不使用 --help/--version 标志：

• rune help — 显示全局帮助（可用命令列表）
• rune help <command> — 显示指定命令的详细用法
• rune version — 显示版本号

错误处理

错误消息采用结构化格式，相关代码位于：

• src/cli/errors.ts — CliError 错误层级（未知命令、缺少参数等）
• src/cli/output.ts — 格式化输出（错误:、用法:、提示: 三段式）
• src/cli/help.ts — 帮助文本生成

设计决策

阶段与配置

• 四阶段固定：discuss → plan → build → archive，不可自定义增删
• 配置覆盖策略：阶段级别全量覆盖，不支持字段级合并。自定义 plan 时需完整重写所有 documents
• 配置文件名：.rune/config.yaml，不是 rune.yml
• 模板变量：仅支持 {{change-name}}，不需要其他变量（信息已在上下文中）

各阶段行为

• discuss：不持久化讨论结果，完全依赖 AI 会话上下文传递；不设强制门控，通过提示词引导
• plan：命令只输出提示词，不写入文件；AI 负责根据提示词生成文档内容并写入。重复调用同一文档的 plan 会追加已有内容用于增量修订。依赖未满足时有友好提示（非报错）
• build：按 task.md 的 checkbox 顺序执行；任务间无结构化依赖；可多次执行直到全部完成
• archive：归档前命令行校验 task 完成状态，未完成时在提示词中注入警告并引导 AI 询问用户

变更名校验

变更名仅支持中文、英文、短横线（-），不支持空格、下划线等其他符号。

update 命令

rune update <tool> 对比已注入的命令/skill 文件内容与内置版本，不一致则覆盖，不存在则新建。用于升级 Rune 后更新编辑器配置。

其他决策

• 无跨变更依赖，变更之间完全独立
• 无并发锁，同一变更可被多个 agent 同时操作
• 无需变更废弃命令，手动删除目录即可
• 同一变更名同天多次归档不处理冲突（日期+名称去重）
• plan skill 应引导 AI 先通过 rune status 获取文档列表

测试策略

单元/集成测试（bun test）

在临时目录执行完整流程，验证文件创建、目录结构、提示词输出。覆盖 src/core/、src/cli/、src/adapters/、tests/integration/。

Agent 端到端测试（bun run test:e2e）

位于 tests/agent/，灰度盒测试互补现有白盒测试，三层架构：

Tier	说明	触发
1 命令级 mock	每命令预设行为，CI 快速门禁	bun run test:e2e
2 场景级 mock	行为重写，覆盖边界和错误恢复	bun run test:e2e
3 LLM-as-Judge	调用 LLM API 验证提示词质量	bun run test:e2e:llm（手动）

运行策略：

• bun test（pre-commit 用）：Tier 1 + 2 不参与，仅跑单元/集成
• bun run test:e2e：Tier 1 + 2（< 5s）
• bun run test:e2e:llm：Tier 3（手动触发，需 RUNE_E2E_LLM_API_KEY）

发布流程

bun run release 交互式发布新版本到 npm：

1. 版本递增：选择 major/minor/patch，确认后写回 package.json
2. 测试门禁：执行 bun test，失败则终止
3. Git 操作：确认后执行 git add + commit + tag（仅本地，不推送）
4. npm 发布：bun publish --dry-run 预览，确认后 bun publish --access public

发布前确保已通过 npm login 登录 npm，且 npm 账号有 @lanyuanxiaoyao scope 的发布权限。