# 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 结构）
```

## 开发命令

```bash
bun test                      # 运行全部测试
bun test tests/core/          # 运行指定目录测试
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        # 查看版本号
```

## 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` 获取文档列表

## 测试策略

### Level 1 — 纯单元/集成测试（当前）

在临时目录执行完整流程，验证文件创建、目录结构、提示词输出。

### Level 2 — 提示词快照测试（后续增强）

对每个阶段捕获提示词输出，与预期快照对比。

### Level 3 — mock-agent 端到端（后续增强）

编排完整闭环：rune 输出 → mock-agent 处理 → rune 继续下一阶段。

### Level 4 — 真实 AI 工具集成（CI 可选）

调用 LLM API 验证输出格式可被解析。