116 lines
4.0 KiB
Markdown
116 lines
4.0 KiB
Markdown
# task.md 任务跟踪（tracked 模式）设计
|
||
|
||
## 背景
|
||
|
||
当前 build 阶段始终读取 task.md 进行任务跟踪，archive 阶段也始终检查 task.md 完成状态。但用户可能不需要任务跟踪流程（例如自定义配置中不含 task 文档），此时 build/archive 强依赖 task.md 是不合理的。
|
||
|
||
需要一种机制让用户控制是否启用任务跟踪，同时保持内置默认配置的现有行为。
|
||
|
||
## 方案
|
||
|
||
在 `metadata` 配置下新增 `tracked: boolean` 字段，控制 plan/build/archive 三阶段的任务跟踪行为。
|
||
|
||
## 配置变更
|
||
|
||
### metadata.tracked
|
||
|
||
```yaml
|
||
metadata:
|
||
command: "bunx @lanyuanxiaoyao/rune"
|
||
tracked: true
|
||
```
|
||
|
||
- 类型：`boolean`，可选，不配置时默认 `false`
|
||
- 内置默认配置中 `tracked: true`（因为内置 plan 包含 task 文档）
|
||
- 放在 `metadata` 而非 `build` 阶段内，因为它影响 plan/build/archive 三阶段
|
||
|
||
### 类型变更
|
||
|
||
```typescript
|
||
// 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：**
|
||
|
||
1. 读取 `task.md`，如不存在则抛出 CommandError（现有行为）
|
||
2. **新增格式校验**：调用 `validateTaskFormat`，不通过则抛出 CommandError
|
||
3. 解析任务列表，展示进度和待执行任务（现有行为）
|
||
4. 提示词末尾附加任务跟踪相关指令（现有行为）
|
||
|
||
**tracked === false：**
|
||
|
||
1. 不读取 task.md，不做格式校验
|
||
2. 只输出 `build.prompt` 通用提示词（经 applyCommandPrefix 处理）
|
||
3. 提示词中不包含任何任务跟踪相关内容
|
||
|
||
### 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` 中新增：
|
||
|
||
```typescript
|
||
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 分支处理 |
|
||
| 对应测试文件 | 修改/新增 | 覆盖所有新增逻辑 |
|