114 lines
5.6 KiB
Markdown
114 lines
5.6 KiB
Markdown
# Rune
|
||
|
||
基于 SDD（Spec-Driven Development）的命令行工具，通过向 AI 开发工具注入 command 和 skill，驱动结构化编码流程。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
bunx @lanyuanxiaoyao/rune init opencode
|
||
```
|
||
|
||
如果没有安装 bun，可使用 `pnpx @lanyuanxiaoyao/rune` 或 `npx @lanyuanxiaoyao/rune` 替代。
|
||
|
||
## 使用
|
||
|
||
### 初始化
|
||
|
||
```bash
|
||
bunx @lanyuanxiaoyao/rune init opencode # OpenCode 编辑器
|
||
bunx @lanyuanxiaoyao/rune init claude-code # Claude Code 编辑器
|
||
```
|
||
|
||
会在项目中创建：
|
||
|
||
- `.rune/` 目录（配置、变更文档、归档）
|
||
- 编辑器对应的 command 和 skill 文件（如 `.opencode/commands/`、`.opencode/skills/`）
|
||
|
||
### 更新编辑器配置
|
||
|
||
当 Rune 版本升级后，需要更新已注入的命令和 skill 文件：
|
||
|
||
```bash
|
||
bunx @lanyuanxiaoyao/rune update opencode # 更新 OpenCode 的命令和 skill
|
||
bunx @lanyuanxiaoyao/rune update claude-code # 更新 Claude Code 的命令
|
||
```
|
||
|
||
更新策略：对比文件内容，不一致则用内置版本覆盖；不存在则新建。
|
||
|
||
### SDD 流程
|
||
|
||
SDD 工作流包含固定的四个阶段，不可自定义增删：
|
||
|
||
1. **讨论阶段** — `/rune-discuss`：与 AI 自由讨论需求和方案。讨论结果保留在 AI 会话上下文中传递到后续阶段，不持久化到文件。结束前会引导是否进入规划阶段。
|
||
2. **规划阶段** — `/rune-plan <变更名> <文档名>`：按配置的文档模板生成规划文档。变更名仅支持中文、英文和短横线（`-`）。默认包含 `design`（设计文档）和 `task`（任务清单，依赖 design）两个文档。文档间支持 `depend` 字段声明前置依赖，依赖未满足时有友好提示。plan 命令自身不写入文件，只输出提示词供 AI 消费。
|
||
3. **构建阶段** — `/rune-build <变更名>`：按 task.md 中的任务顺序逐个实现。每个任务完成后更新对应的 checkbox 为 `[x]`。可多次执行直到所有任务完成。
|
||
4. **归档阶段** — `/rune-archive <变更名>`：将变更目录移至 `archive/`。归档前自动检查 task.md 的完成状态，如有未完成任务会注入警告提示词，引导 AI 询问用户是否确认归档。
|
||
|
||
> **辅助命令**：`rune create <变更名>` 用于在 `.rune/changes/` 下创建变更目录。它不是 SDD 阶段，而是在 discuss 结束后或 plan 开始前通过 CLI 运行的辅助命令。discuss 和 plan 的编辑器命令中已内嵌 create 的使用引导。
|
||
|
||
### 状态查看
|
||
|
||
```bash
|
||
bunx @lanyuanxiaoyao/rune status # 查看所有变更（含各阶段文档完成状态、下一步建议）
|
||
bunx @lanyuanxiaoyao/rune status <变更名> # 查看指定变更的详细状态
|
||
```
|
||
|
||
规划阶段应引导 AI 先通过 `bunx @lanyuanxiaoyao/rune status` 获取当前有哪些文档需要编写。
|
||
|
||
### 命令参考
|
||
|
||
```bash
|
||
bunx @lanyuanxiaoyao/rune help # 显示全局帮助
|
||
bunx @lanyuanxiaoyao/rune help <command> # 显示指定命令的详细帮助
|
||
bunx @lanyuanxiaoyao/rune version # 显示版本号
|
||
```
|
||
|
||
| 命令 | 说明 |
|
||
| -------------------------------------------------- | ----------------------------------------------- |
|
||
| `bunx @lanyuanxiaoyao/rune init <tool>` | 初始化项目，注入编辑器配置 |
|
||
| `bunx @lanyuanxiaoyao/rune update <tool>` | 更新编辑器的命令和 skill 文件 |
|
||
| `bunx @lanyuanxiaoyao/rune discuss` | 输出讨论阶段提示词 |
|
||
| `bunx @lanyuanxiaoyao/rune create <变更名>` | 创建变更目录（discuss 和 plan 之间的辅助命令） |
|
||
| `bunx @lanyuanxiaoyao/rune plan <变更名> <文档名>` | 输出规划阶段提示词 |
|
||
| `bunx @lanyuanxiaoyao/rune build <变更名>` | 输出构建阶段提示词 |
|
||
| `bunx @lanyuanxiaoyao/rune archive <变更名>` | 输出归档阶段提示词，同时移动变更目录到 archive/ |
|
||
| `bunx @lanyuanxiaoyao/rune status [变更名]` | 显示变更状态和下一步建议 |
|
||
|
||
### 自定义配置
|
||
|
||
编辑 `.rune/config.yaml` 自定义各阶段的提示词和文档模板。配置合并采用阶段级别全量覆盖策略：自定义某个阶段时需完整重写该阶段的配置，未配置的阶段使用内置默认配置。
|
||
|
||
规划阶段的文档支持 `depend` 字段声明前置依赖，如 `task` 依赖 `design`：
|
||
|
||
```yaml
|
||
stages:
|
||
plan:
|
||
documents:
|
||
- name: design
|
||
prompt: 生成设计文档，包含背景、目标、方案、接口和注意事项
|
||
- name: task
|
||
prompt: 生成任务清单，将设计拆分为可独立执行的小任务
|
||
depend: [design]
|
||
```
|
||
|
||
计划阶段文档模板支持 `{{change-name}}` 变量，运行时会替换为实际变更名。
|
||
|
||
## 设计决策
|
||
|
||
- **四阶段固定**：discuss → plan → build → archive 不可自定义增删
|
||
- **配置覆盖策略**：阶段级别全量覆盖，不支持字段级合并
|
||
- **讨论结果不持久化**：完全依赖 AI 会话上下文传递
|
||
- **plan 不写文件**：plan 命令只输出提示词，由 AI 负责写入文档
|
||
- **变更名限制**：仅支持中文、英文、短横线（`-`）
|
||
- **同一变更名同天多次归档**：依靠日期+变更名去重，不做冲突处理
|
||
- **无跨变更依赖**：变更之间完全独立
|
||
- **无并发锁**：同一变更可被多个 AI agent 同时操作
|
||
- **无变更废弃命令**：用户手动删除 `.rune/changes/<变更名>/` 目录即可
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
bun test # 运行测试
|
||
bun src/cli.ts # 运行 CLI
|
||
```
|