163 lines
6.5 KiB
Markdown
163 lines
6.5 KiB
Markdown
# 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 # 运行单元/集成测试（排除 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 环境变量
|
||
|
||
```bash
|
||
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 自动检查。
|
||
|
||
```bash
|
||
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 的发布权限。
|