diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b6690f1..6adc783 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -24,12 +24,16 @@ src/ │ ├── config.ts # 配置加载 │ ├── scanner.ts # 状态扫描 │ ├── assembler.ts # 提示词拼装 -│ └── task-parser.ts # 任务解析 +│ ├── task-parser.ts # 任务解析 +│ └── pm.ts # 包管理器检测与命令前缀 ├── adapters/ │ ├── opencode.ts # OpenCode 适配器 -│ └── claude-code.ts # Claude Code 适配器（占位） -└── defaults/ - └── config.ts # 内置默认配置 +│ ├── claude-code.ts # Claude Code 适配器 +│ └── utils.ts # 适配器工具函数 +├── defaults/ +│ └── config.ts # 内置默认配置 +scripts/ +└── release.ts # 发布脚本 tests/ # 测试目录（镜像 src 结构） ``` @@ -98,7 +102,7 @@ CLI 通过子命令提供帮助和版本信息，不使用 `--help`/`--version` - **discuss**：不持久化讨论结果，完全依赖 AI 会话上下文传递；不设强制门控，通过提示词引导。讨论结束时引导用户运行 `rune create` 创建变更目录 - **plan**：命令只输出提示词，不写入文件；AI 负责根据提示词生成文档内容并写入。新变更时引导用户先运行 `rune create` 创建目录。重复调用同一文档的 plan 会追加已有内容用于增量修订。依赖未满足时有友好提示（非报错） - **build**：按 task.md 的 checkbox 顺序执行；任务间无结构化依赖；可多次执行直到全部完成 -- **archive**：归档前命令行校验 task 完成状态，未完成时在提示词中注入警告并引导 AI 询问用户 +- **archive**：输出归档提示词（含未完成任务的警告），引导 AI 汇总变更并确认。`finish` 命令执行实际的目录移动 **create**：CLI 辅助命令（非独立阶段），在 `.rune/changes/` 下创建变更目录。adapter 不为 create 生成独立的 skill/command 文件，使用引导嵌入在 discuss 和 plan 的 skill/command 内容中。 @@ -116,6 +120,7 @@ CLI 通过子命令提供帮助和版本信息，不使用 `--help`/`--version` - 无并发锁，同一变更可被多个 agent 同时操作 - 无需变更废弃命令，手动删除目录即可 - 同一变更名同天多次归档不处理冲突（日期+名称去重） +- archive 与 finish 分离：archive 只输出提示词，finish 执行实际的目录移动。分离原因是提示词阶段需要 AI 参与确认，而文件操作是确定性的 - plan skill 应引导 AI 先通过 `rune status` 获取文档列表 ## 测试策略 diff --git a/README.md b/README.md index 0dbb215..8474aa5 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ 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 询问用户是否确认归档。 +4. **归档阶段** — `/rune-archive <变更名>`：输出归档阶段提示词，引导 AI 汇总变更内容并确认归档。归档前自动检查 task.md 的完成状态，如有未完成任务会注入警告提示词，引导 AI 询问用户是否确认。确认后执行 `rune finish <变更名>` 将变更目录移动到 `archive/`。 > **辅助命令**：`rune create <变更名>` 用于在 `.rune/changes/` 下创建变更目录。它不是 SDD 阶段，而是在 discuss 结束后或 plan 开始前通过 CLI 运行的辅助命令。discuss 和 plan 的编辑器命令中已内嵌 create 的使用引导。 @@ -63,16 +63,17 @@ bunx @lanyuanxiaoyao/rune help # 显示指定命令的详细帮 bunx @lanyuanxiaoyao/rune version # 显示版本号 ``` -| 命令 | 说明 | -| -------------------------------------------------- | ----------------------------------------------- | -| `bunx @lanyuanxiaoyao/rune init ` | 初始化项目，注入编辑器配置 | -| `bunx @lanyuanxiaoyao/rune update ` | 更新编辑器的命令和 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 [变更名]` | 显示变更状态和下一步建议 | +| 命令 | 说明 | +| -------------------------------------------------- | ---------------------------------------------- | +| `bunx @lanyuanxiaoyao/rune init ` | 初始化项目，注入编辑器配置 | +| `bunx @lanyuanxiaoyao/rune update ` | 更新编辑器的命令和 skill 文件 | +| `bunx @lanyuanxiaoyao/rune discuss` | 输出讨论阶段提示词 | +| `bunx @lanyuanxiaoyao/rune create <变更名>` | 创建变更目录（discuss 和 plan 之间的辅助命令） | +| `bunx @lanyuanxiaoyao/rune plan <变更名> <文档名>` | 输出规划阶段提示词 | +| `bunx @lanyuanxiaoyao/rune build <变更名>` | 输出构建阶段提示词 | +| `bunx @lanyuanxiaoyao/rune archive <变更名>` | 输出归档阶段提示词 | +| `bunx @lanyuanxiaoyao/rune finish <变更名>` | 归档变更（将变更目录移动到 archive/） | +| `bunx @lanyuanxiaoyao/rune status [变更名]` | 显示变更状态和下一步建议 | ### 自定义配置 diff --git a/src/cli.ts b/src/cli.ts index 745dc2d..fa09c00 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -3,7 +3,7 @@ import { cac } from "cac"; import { join } from "node:path"; import { mkdir, rename } from "node:fs/promises"; import { readFileSync, existsSync } from "node:fs"; -import { runInit } from "./commands/init.ts"; +import { runInit, ensureMetadataCommand } from "./commands/init.ts"; import { findProjectRoot, loadConfig, getChangeDir, getArchiveDir } from "./core/config.ts"; import { assembleDiscussPrompt, @@ -131,8 +131,12 @@ cli.command("help [command]", "显示帮助信息").action(async (command?: stri }); cli.command("version", "显示版本号").action(() => { - const pkg = JSON.parse(readFileSync(join(import.meta.dir, "../package.json"), "utf-8")); - console.log(`rune v${pkg.version}`); + try { + const pkg = JSON.parse(readFileSync(join(import.meta.dir, "../package.json"), "utf-8")); + console.log(`rune v${pkg.version}`); + } catch { + console.log("rune (未知版本)"); + } }); cli.command("init [...tools]", "初始化 Rune 并注入工具配置").action(async (tools: string[]) => { @@ -178,16 +182,10 @@ cli.command("update [...tools]", "更新已注入的工具配置").action(async if (!config?.metadata?.command) { const detected = await detectCommandPrefix(); if (detected) { - const { readFile, appendFile } = await import("node:fs/promises"); - const yaml = await import("yaml"); const { join: joinPath } = await import("node:path"); const configPath = joinPath(root, ".rune", "config.yaml"); try { - const content = await readFile(configPath, "utf-8"); - const parsed = yaml.parse(content) as { metadata?: { command?: string } } | null; - if (!parsed?.metadata?.command) { - await appendFile(configPath, `\nmetadata:\n command: "${detected}"\n`); - } + await ensureMetadataCommand(configPath, detected); } catch {} } } @@ -229,7 +227,7 @@ cli const config = await loadConfig(root); const planDocs = config.stages.plan?.documents; if (!planDocs || !planDocs.find((d) => d.name === documentName)) { - throw new CommandError(`文档 "${documentName}" 不在配置的 plan.documents 中`, { + throw new CommandError(`文档"${documentName}"不在配置的规划阶段文档列表中`, { hint: `可用文档：${planDocs?.map((d) => d.name).join(", ") ?? "无"}`, }); } @@ -237,7 +235,7 @@ cli const changeDir = getChangeDir(root, changeName); if (!existsSync(changeDir)) { const prefix = getPmPrefix(config); - throw new CommandError(`变更 '${changeName}' 不存在`, { + throw new CommandError(`变更"${changeName}"不存在`, { hint: `请先运行 ${prefix} create ${changeName} 创建变更`, }); } @@ -247,7 +245,7 @@ cli const missing = doc.depend.filter((dep) => !existsSync(join(changeDir, `${dep}.md`))); if (missing.length > 0) { throw new CommandError( - `文档 "${documentName}" 的前置依赖未满足：${missing.map((d) => `${d}.md`).join("、")} 尚未完成`, + `文档"${documentName}"的前置依赖未满足：${missing.map((d) => `${d}.md`).join("、")} 尚未完成`, { hint: `请先完成依赖文档：${getPmPrefix(config)} plan ${changeName} ${missing[0]}`, }, @@ -265,7 +263,7 @@ cli.command("build ", "构建阶段").action(async (changeName: str const changeDir = getChangeDir(root, changeName); if (!existsSync(changeDir)) { const prefix = getPmPrefix(); - throw new CommandError(`变更 '${changeName}' 不存在`, { + throw new CommandError(`变更"${changeName}"不存在`, { hint: `请先运行 ${prefix} create ${changeName} 创建变更`, }); } @@ -280,7 +278,7 @@ cli.command("archive ", "归档阶段").action(async (changeName: s const changeDir = getChangeDir(root, changeName); if (!existsSync(changeDir)) { const prefix = getPmPrefix(); - throw new CommandError(`变更 '${changeName}' 不存在`, { + throw new CommandError(`变更"${changeName}"不存在`, { hint: `请先运行 ${prefix} create ${changeName} 创建变更`, }); } @@ -295,7 +293,7 @@ cli.command("finish ", "归档变更").action(async (changeName: st const changeDir = getChangeDir(root, changeName); if (!existsSync(changeDir)) { const prefix = getPmPrefix(); - throw new CommandError(`变更 '${changeName}' 不存在`, { + throw new CommandError(`变更"${changeName}"不存在`, { hint: `请先运行 ${prefix} create ${changeName} 创建变更`, }); } @@ -344,7 +342,7 @@ export function mapError(e: unknown): CliError { const err = mapCacError(e); if (err) return err; } - return new InternalError(); + return new InternalError(e); } function mapCacError(e: Error): CliError | null { @@ -373,7 +371,7 @@ function mapCacError(e: Error): CliError | null { if (e.message.includes("missing required args")) { const match = e.message.match(/command `(\w+)/); const cmd = match ? match[1] : "未知命令"; - return new UsageError(`命令 '${cmd}' 缺少必填参数`, { + return new UsageError(`命令"${cmd}"缺少必填参数`, { usage: `${prefix} ${cmd} `, hint: `运行 ${prefix} help ${cmd} 查看用法`, }); diff --git a/src/cli/errors.ts b/src/cli/errors.ts index f39e8d9..54fe256 100644 --- a/src/cli/errors.ts +++ b/src/cli/errors.ts @@ -17,7 +17,18 @@ export class ConfigError extends CliError {} export class CommandError extends CliError {} export class InternalError extends CliError { - constructor() { - super("发生了未预期的错误"); + readonly cause?: Error; + + constructor(originalError?: unknown) { + const message = + originalError instanceof Error + ? `发生了未预期的错误：${originalError.message}` + : "发生了未预期的错误"; + const hint = + originalError instanceof Error + ? `错误类型：${originalError.constructor.name}\n调用栈：${originalError.stack ?? "无"}` + : undefined; + super(message, { hint }); + this.cause = originalError instanceof Error ? originalError : undefined; } } diff --git a/src/commands/init.ts b/src/commands/init.ts index fd2a9a8..cd0acce 100644 --- a/src/commands/init.ts +++ b/src/commands/init.ts @@ -50,7 +50,7 @@ export const SUPPORTED_TOOLS: Record "claude-code": injectClaudeCode, }; -async function ensureMetadataCommand(configPath: string, command: string): Promise { +export async function ensureMetadataCommand(configPath: string, command: string): Promise { const content = await readFile(configPath, "utf-8"); const parsed = parseYaml(content) as { metadata?: { command?: string } } | null; if (parsed?.metadata?.command) return; diff --git a/src/core/assembler.ts b/src/core/assembler.ts index 5d82a02..623ba89 100644 --- a/src/core/assembler.ts +++ b/src/core/assembler.ts @@ -30,7 +30,7 @@ export async function assemblePlanPrompt( const doc = plan.documents.find((d) => d.name === documentName); if (!doc) { - throw new CommandError(`文档 "${documentName}" 不在配置的 plan.documents 中`, { + throw new CommandError(`文档"${documentName}"不在配置的规划阶段文档列表中`, { hint: `可用文档：${plan.documents.map((d) => d.name).join(", ")}`, }); } @@ -95,7 +95,7 @@ export async function assembleBuildPrompt( taskContent = await readFile(taskPath, "utf-8"); } catch { const prefix = getPmPrefix(config); - throw new CommandError(`变更 "${changeName}" 尚未完成规划，task.md 不存在`, { + throw new CommandError(`变更"${changeName}"尚未完成规划，task.md 不存在`, { hint: `请先完成规划阶段：${prefix} plan ${changeName} task 生成任务文档`, }); } @@ -161,8 +161,11 @@ export async function assembleArchivePrompt( parts.push("如用户确认，则继续执行归档操作；否则中止并返回构建阶段。"); parts.push(""); } - } catch { - // task.md 读取失败时不追加警告 + } catch (e) { + const code = (e as NodeJS.ErrnoException)?.code; + if (code !== "ENOENT" && code !== "ENOTDIR") { + throw e; + } } } } diff --git a/src/core/config.ts b/src/core/config.ts index 5a429dd..478c528 100644 --- a/src/core/config.ts +++ b/src/core/config.ts @@ -4,6 +4,7 @@ import { join, dirname } from "node:path"; import { parse as parseYaml } from "yaml"; import { defaultConfig } from "../defaults/config.ts"; import { ConfigError } from "../cli/errors.ts"; +import { getPmPrefix } from "./pm.ts"; import type { RuneConfig } from "../types.ts"; import { RUNE_DIR, CONFIG_FILE, CHANGES_DIR, ARCHIVE_DIR } from "../types.ts"; @@ -26,8 +27,15 @@ export async function loadConfig(projectRoot: string): Promise { const content = await readFile(configPath, "utf-8"); const userConfig = parseYaml(content) as Partial | null; merged = mergeConfig(userConfig ?? {}); - } catch { - merged = mergeConfig({}); + } catch (e) { + const code = (e as NodeJS.ErrnoException)?.code; + if (code === "ENOENT" || code === "ENOTDIR") { + merged = mergeConfig({}); + } else { + throw new ConfigError(`配置文件加载失败：${configPath}\n${(e as Error).message}`, { + hint: `请检查 .rune/config.yaml 的格式是否正确。常见问题：\n - YAML 缩进必须使用空格，不能用 Tab\n - 字符串包含特殊字符时需要引号包裹\n - 运行 ${getPmPrefix()} init 重新生成默认配置`, + }); + } } validateConfig(merged); return merged; @@ -37,10 +45,15 @@ export function validateConfig(config: RuneConfig): void { const plan = config.stages.plan; if (!plan) return; - if (config.metadata?.tracked && plan) { + if (config.metadata?.tracked) { const hasTaskDoc = plan.documents.some((d) => d.name === "task"); if (!hasTaskDoc) { - throw new ConfigError('tracked 开启时 plan.documents 必须包含 name 为 "task" 的文档'); + throw new ConfigError( + "配置校验失败：开启了任务追踪（metadata.tracked）但规划阶段的文档列表中没有 task 文档", + { + hint: `请在 .rune/config.yaml 的 stages.plan.documents 中添加 task 文档：\n - name: task\n prompt: 生成任务清单\n depend: [design]`, + }, + ); } } @@ -51,10 +64,14 @@ export function validateConfig(config: RuneConfig): void { for (const dep of doc.depend) { if (dep === doc.name) { - throw new ConfigError(`文档 "${doc.name}" 不能依赖自身`); + throw new ConfigError(`文档"${doc.name}"不能依赖自身`, { + hint: `请从文档"${doc.name}"的 depend 列表中移除自身引用`, + }); } if (!docNames.has(dep)) { - throw new ConfigError(`文档 "${doc.name}" 依赖 "${dep}" 不存在于 plan.documents 中`); + throw new ConfigError(`文档"${doc.name}"依赖的"${dep}"不存在于规划阶段的文档列表中`, { + hint: `请在 stages.plan.documents 中添加文档"${dep}"，或从文档"${doc.name}"的 depend 列表中移除"${dep}"`, + }); } } } @@ -84,7 +101,9 @@ export function validateConfig(config: RuneConfig): void { for (const doc of plan.documents) { path.length = 0; if (hasCycle(doc.name)) { - throw new ConfigError(`文档间存在循环依赖：${path.join(" → ")}`); + throw new ConfigError(`文档间存在循环依赖：${path.join(" → ")}`, { + hint: "请检查文档的 depend 配置，移除形成环路的依赖关系", + }); } } } diff --git a/src/core/pm.ts b/src/core/pm.ts index bf32cc8..0fb53a3 100644 --- a/src/core/pm.ts +++ b/src/core/pm.ts @@ -8,6 +8,7 @@ export function inferFromEnvironment( ): string | null { if (execPath.includes("bun")) return "bunx @lanyuanxiaoyao/rune"; if (userAgent?.includes("pnpm")) return "pnpx @lanyuanxiaoyao/rune"; + if (userAgent?.includes("yarn")) return "yarn dlx @lanyuanxiaoyao/rune"; if (userAgent?.includes("npm")) return "npx @lanyuanxiaoyao/rune"; return null; } diff --git a/src/core/scanner.ts b/src/core/scanner.ts index e15e211..3db7877 100644 --- a/src/core/scanner.ts +++ b/src/core/scanner.ts @@ -64,7 +64,12 @@ export async function scanChanges( taskProgress, }); } - } catch {} + } catch (e) { + const code = (e as NodeJS.ErrnoException)?.code; + if (code !== "ENOENT" && code !== "ENOTDIR") { + throw e; + } + } return results; } diff --git a/src/core/task-parser.ts b/src/core/task-parser.ts index b3cc9ae..9ec7938 100644 --- a/src/core/task-parser.ts +++ b/src/core/task-parser.ts @@ -1,4 +1,5 @@ import type { TaskItem } from "../types.ts"; +import { CommandError } from "../cli/errors.ts"; export function parseTasks(content: string): TaskItem[] { const tasks: TaskItem[] = []; @@ -15,7 +16,7 @@ export function parseTasks(content: string): TaskItem[] { return tasks; } -export class TaskFormatError extends Error { +export class TaskFormatError extends CommandError { constructor(message: string) { super(message); this.name = this.constructor.name; diff --git a/tests/cli/map-error.test.ts b/tests/cli/map-error.test.ts index 9518f59..48c84a1 100644 --- a/tests/cli/map-error.test.ts +++ b/tests/cli/map-error.test.ts @@ -38,7 +38,7 @@ describe("mapError", () => { const err = new Error("missing required args for command `plan`"); const result = mapError(err); expect(result).toBeInstanceOf(UsageError); - expect(result.message).toBe("命令 'plan' 缺少必填参数"); + expect(result.message).toBe(`命令"plan"缺少必填参数`); expect(result.usage).toBe(`${DEFAULT_PREFIX} plan `); expect(result.hint).toContain(`${DEFAULT_PREFIX} help plan`); }); @@ -47,7 +47,8 @@ describe("mapError", () => { const err = new Error("something unexpected"); const result = mapError(err); expect(result).toBeInstanceOf(InternalError); - expect(result.message).toBe("发生了未预期的错误"); + expect(result.message).toContain("发生了未预期的错误"); + expect(result.message).toContain("something unexpected"); }); it("非 Error 类型转为 InternalError", () => { diff --git a/tests/core/config.test.ts b/tests/core/config.test.ts index 8571951..9a18d9c 100644 --- a/tests/core/config.test.ts +++ b/tests/core/config.test.ts @@ -90,12 +90,11 @@ stages: expect(config.stages.archive).toBeDefined(); }); - it("YAML 解析错误时返回默认配置", async () => { + it("YAML 解析错误时抛出 ConfigError", async () => { const runeDir = join(TMP_DIR, ".rune"); await mkdir(runeDir, { recursive: true }); await writeFile(join(runeDir, "config.yaml"), `stages: [invalid yaml {{{`); - const config = await loadConfig(TMP_DIR); - expect(config.stages.discuss).toBeDefined(); + expect(loadConfig(TMP_DIR)).rejects.toThrow(ConfigError); }); });