task.md 任务跟踪（tracked 模式）设计

背景

当前 build 阶段始终读取 task.md 进行任务跟踪，archive 阶段也始终检查 task.md 完成状态。但用户可能不需要任务跟踪流程（例如自定义配置中不含 task 文档），此时 build/archive 强依赖 task.md 是不合理的。

需要一种机制让用户控制是否启用任务跟踪，同时保持内置默认配置的现有行为。

方案

在 metadata 配置下新增 tracked: boolean 字段，控制 plan/build/archive 三阶段的任务跟踪行为。

配置变更

metadata.tracked

metadata:
  command: "bunx @lanyuanxiaoyao/rune"
  tracked: true

类型：boolean，可选，不配置时默认 false
内置默认配置中 tracked: true（因为内置 plan 包含 task 文档）
放在 metadata 而非 build 阶段内，因为它影响 plan/build/archive 三阶段

类型变更

// types.ts
interface RuneConfig {
  stages: StagesConfig;
  metadata?: {
    command?: string;
    tracked?: boolean; // 新增
  };
}

BuildStage 类型不变，不新增字段。

各阶段行为变更

plan 阶段（config.ts validateConfig）

当 metadata.tracked === true 时，校验 plan.documents 中必须包含 name: "task" 的文档。不包含则抛出 ConfigError：

配置错误：tracked 开启时 plan.documents 必须包含 name 为 "task" 的文档

当 metadata.tracked !== true 时，不进行此校验。

build 阶段（assembler.ts assembleBuildPrompt）

tracked === true：

读取 task.md，如不存在则抛出 CommandError（现有行为）
新增格式校验：调用 validateTaskFormat，不通过则抛出 CommandError
解析任务列表，展示进度和待执行任务（现有行为）
提示词末尾附加任务跟踪相关指令（现有行为）

tracked === false：

不读取 task.md，不做格式校验
只输出 build.prompt 通用提示词（经 applyCommandPrefix 处理）
提示词中不包含任何任务跟踪相关内容

archive 阶段（assembler.ts assembleArchivePrompt）

tracked === true： 现有行为不变——读 task.md，检查未完成项，注入警告。

tracked === false： 不读取 task.md，不注入未完成任务警告，只输出 archive.prompt（经 applyCommandPrefix 处理）。

格式校验规则

在 task-parser.ts 中新增 validateTaskFormat 函数：

校验条件：
1. 文件中至少有一个 checkbox 行（- [ ] 或 - [x]）
2. 每个 checkbox 的文本内容不能为空（即 - [ ] 后面必须有非空文本）

不通过时抛出 CommandError：
"变更 "<变更名>" 的 task.md 格式不符合要求：必须包含至少一个 checkbox 项，且每项必须有非空描述"

默认配置变更

defaults/config.ts 中新增：

metadata: {
  tracked: true,
}

不变更的部分

BuildStage 类型不变
scanner.ts 的 taskProgress 逻辑不变（status 命令是查询行为，始终尝试读取 task.md 做信息展示，不受 tracked 开关影响）
task-parser.ts 的 parseTasks 不变，新增 validateTaskFormat 函数
pm.ts 不变
cli/ 目录下的错误类型和输出格式不变，复用现有 CommandError 和 ConfigError

影响范围

文件	变更类型	说明
`src/types.ts`	修改	metadata 新增 tracked 字段
`src/defaults/config.ts`	修改	默认配置新增 metadata.tracked: true
`src/core/config.ts`	修改	validateConfig 新增 tracked 时 task 文档校验
`src/core/task-parser.ts`	修改	新增 validateTaskFormat 函数
`src/core/assembler.ts`	修改	build/archive 阶段根据 tracked 分支处理
对应测试文件	修改/新增	覆盖所有新增逻辑

4.0 KiB Raw Blame History Unescape Escape