@jahanxu/code-flow 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahanxu/code-flow",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"

package/src/adapters/claude/commands/cf-task/archive.md

@@ -6,13 +6,15 @@
 
 - `/cf-task:archive <file>` — 归档指定的 task 文件
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
 
 ## 执行步骤
 
 ### 1. 完成度检查
 
-1. 用 Read 读取 `.code-flow/tasks/<file>.md`
+1. 用 Read 读取匹配到的 task 文件
 2. 提取所有 `## TASK-xxx` 段落的 Status
 3. 检查是否所有子任务均为 `done`
 
@@ -32,17 +34,18 @@
 
 所有子任务已完成：
 
-1. 用 Bash 创建归档目录并移动文件：
+1. 提取文件所在的日期目录名（如 `2026-03-15`）
+2. 用 Bash 创建归档目录并移动文件：
    ```bash
-   mkdir -p .code-flow/tasks/archived
-   mv .code-flow/tasks/<file>.md .code-flow/tasks/archived/
+   mkdir -p .code-flow/tasks/archived/<日期目录>
+   mv .code-flow/tasks/<日期目录>/<file>.md .code-flow/tasks/archived/<日期目录>/
    ```
-2. 输出归档摘要
+3. 如果原日期目录为空，删除空目录
 
 ### 3. 归档摘要
 
 ```
-已归档: <file>.md → .code-flow/tasks/archived/<file>.md
+已归档: <file>.md → .code-flow/tasks/archived/<日期目录>/<file>.md
 
 摘要:
   - 来源: docs/xxx设计说明书.md

package/src/adapters/claude/commands/cf-task/block.md

@@ -6,11 +6,13 @@
 
 - `/cf-task:block <file> TASK-001 "阻塞原因"`
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
 
 ## 执行步骤
 
-1. 用 Read 读取 `.code-flow/tasks/<file>.md`
+1. 用 Glob 定位任务文件，Read 读取
 2. 定位 `## TASK-001` 段落，检查当前 Status：
    - `done` → 拒绝：`TASK-001 已完成，无法标记阻塞`
    - `blocked` → 提示：`TASK-001 已处于 blocked 状态`，仍追加新的阻塞原因

package/src/adapters/claude/commands/cf-task/graph.md

@@ -7,14 +7,16 @@
 - `/cf-task:graph <file>` — 显示指定文件的依赖图
 - `/cf-task:graph` — 显示所有活跃 task 文件的依赖图
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
 
 ## 执行步骤
 
 ### 1. 读取任务数据
 
-- 指定文件：Read `.code-flow/tasks/<file>.md`
-- 全部文件：Glob `.code-flow/tasks/*.md`（排除 `archived/` 目录），逐个 Read
+- 指定文件：Glob 定位后 Read
+- 全部文件：Glob `.code-flow/tasks/**/*.md`（排除 `archived/` 目录），逐个 Read
 
 从每个 `## TASK-xxx` 段落提取：ID、标题、Status、Depends。
 

package/src/adapters/claude/commands/cf-task/note.md

@@ -8,13 +8,15 @@
 - `/cf-task:note <file> TASK-001 resolve NOTE-1` — 标记批注为已解决
 - `/cf-task:note <file> TASK-001 resolve all` — 标记所有批注为已解决
 
-其中 `<file>` 可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`（排除 `archived/`），匹配第一个结果。
 
 ## 添加批注
 
 ### 执行步骤
 
-1. 用 Read 读取 `.code-flow/tasks/<file>.md`
+1. 用 Glob 定位任务文件，Read 读取
 2. 定位 `## TASK-001` 段落下的 `### Notes` 区域
 3. 扫描已有 `[NOTE-n]`，计算下一个编号
 4. 用 Edit 在 `### Notes` 下追加：`- [NOTE-<n>] <批注内容>`

package/src/adapters/claude/commands/cf-task/plan.md

@@ -18,7 +18,26 @@
 2. 展示列表，让用户选择目标文档
 3. Read 读取选中的文档
 
-### 2. 分析文档，拆解子任务
+### 2. 建立章节索引
+
+Read 设计文档后，**先扫描文档结构**，建立章节索引表：
+
+```
+章节索引:
+  §1 概述 (L1-L25)
+  §2 需求分析 (L26-L80)
+    §2.1 用户故事 (L28-L55)
+    §2.2 非功能需求 (L56-L80)
+  §3 详细设计 (L81-L200)
+    §3.1 数据模型 (L83-L110)
+    §3.2 API 接口 (L111-L155)
+    §3.3 业务逻辑 (L156-L200)
+  ...
+```
+
+此索引用于后续步骤中精确记录每个子任务的来源章节。
+
+### 3. 分析文档，拆解子任务
 
 阅读设计文档内容，按以下原则拆解：
 
@@ -28,12 +47,20 @@
 - 预估编码时间 15-60 分钟
 
 **提取内容**：
-- 功能需求 → 子任务标题 + 描述
+- 功能需求 → 子任务标题 + 描述（提炼重点，不必复制全文）
 - 实现要点 → Checklist 条目
 - 模块依赖 → Depends 字段
 - 紧急程度 → Priority（P0 核心功能 / P1 重要功能 / P2 优化项）
 
-### 3. 生成任务文件方案
+**关键：精确记录章节引用**
+
+每个子任务的 `Source` 字段必须记录该任务对应的详设文档**具体章节和行号范围**。
+
+引用格式：`文件路径#章节标题(L起始-L结束)`，多个章节用逗号分隔。
+
+验证方法：记录引用后，用 Read 工具按行号范围回读验证，确保引用内容与子任务描述一致。如不一致，修正行号。
+
+### 4. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
 
@@ -51,9 +78,10 @@
 - **Status**: draft
 - **Priority**: P0
 - **Depends**:
+- **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
 
 ### Description
-<从设计文档提取的需求描述>
+<从设计文档提取的需求重点，不必复制全文>
 
 ### Checklist
 - [ ] <具体实现步骤1>
@@ -68,6 +96,13 @@
 ---
 
 ## TASK-002: <子任务标题>
+
+- **Status**: draft
+- **Priority**: P1
+- **Depends**: TASK-001
+- **Source**: docs/xxx.md#§3.2 API 接口(L111-L155), docs/xxx.md#§3.3 业务逻辑(L156-L180)
+
+### Description
 ...
 ```
 
@@ -77,11 +112,13 @@
 拆解结果（共 N 个子任务）：
 
 TASK-001: <标题> [P0]
+  来源: §3.1 数据模型 (L83-L110)
   描述: ...
   Checklist: N 项
   依赖: 无
 
 TASK-002: <标题> [P1]
+  来源: §3.2 API 接口 (L111-L155), §3.3 业务逻辑 (L156-L180)
   描述: ...
   Checklist: N 项
   依赖: TASK-001
@@ -90,24 +127,26 @@ TASK-002: <标题> [P1]
 - 修改某个子任务的内容
 - 删除不需要的子任务
 - 合并过于细碎的子任务
-- 调整依赖关系
+- 调整依赖关系和章节引用
 ```
 
 等待用户确认或调整。
 
-### 4. 写入文件
+### 5. 写入文件
 
 用户确认后：
-1. 文件名取模块/功能名（kebab-case），如 `auth-module.md`、`payment-api.md`
-2. 用 Write 写入 `.code-flow/tasks/<name>.md`
+1. 文件名取模块/功能名（kebab-case），如 `auth-module.md`
+2. 按当前日期创建目录：`.code-flow/tasks/<YYYY-MM-DD>/`
+3. 用 Write 写入 `.code-flow/tasks/<YYYY-MM-DD>/<name>.md`
 
-### 5. 输出摘要
+### 6. 输出摘要
 
 ```
-已生成任务文件: .code-flow/tasks/<name>.md
+已生成任务文件: .code-flow/tasks/2026-03-15/auth-module.md
 - 子任务数: N
 - P0: x 个, P1: y 个, P2: z 个
 - 依赖链深度: N 层
+- 详设引用覆盖: §3.1, §3.2, §3.3, §3.5 (共 4 个章节)
 
 建议执行顺序:
   1. TASK-001 (无依赖)
@@ -116,7 +155,7 @@ TASK-002: <标题> [P1]
   ...
 
 下一步:
-  - 审阅任务: 直接阅读 .code-flow/tasks/<name>.md
-  - 添加批注: /cf-task:note <name> TASK-001 "批注内容"
-  - 开始编码: /cf-task:start <name>
+  - 审阅任务: 直接阅读 .code-flow/tasks/2026-03-15/auth-module.md
+  - 添加批注: /cf-task:note auth-module TASK-001 "批注内容"
+  - 开始编码: /cf-task:start auth-module
 ```

package/src/adapters/claude/commands/cf-task/start.md

@@ -7,7 +7,9 @@
 - `/cf-task:start <file> TASK-001` — 激活指定文件中的单个子任务
 - `/cf-task:start <file>` — 激活文件内所有可执行的 draft 子任务
 
-其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略路径前缀和 `.md` 后缀。
+其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略日期目录前缀和 `.md` 后缀。
+
+查找逻辑：用 Glob 搜索 `.code-flow/tasks/**/<file>.md`，匹配第一个结果。
 
 示例：
 - `/cf-task:start auth-module TASK-002`
@@ -17,7 +19,7 @@
 
 ### 1. 前置检查
 
-用 Read 读取 `.code-flow/tasks/<file>.md`，定位 `## TASK-xxx` 段落：
+用 Read 读取任务文件，定位 `## TASK-xxx` 段落：
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
 - `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
@@ -33,22 +35,35 @@
 - 所有依赖必须为 `done`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
-### 2. 激活并编码
+### 2. 加载详设上下文
+
+前置检查通过后，**编码前先加载关联的详设文档章节**：
+
+1. 读取子任务的 `Source` 字段，解析章节引用
+   - 格式：`docs/xxx.md#§3.1 数据模型(L83-L110)`
+   - 提取：文件路径 + 行号范围
+2. 用 Read 按行号范围读取详设文档的对应章节（使用 offset/limit 参数）
+3. 将读取的章节内容作为编码上下文，与 Checklist 一起指导实现
+
+示例：Source 为 `docs/auth.md#§3.2 API 接口(L111-L155), docs/auth.md#§3.5 错误码(L201-L220)`
+→ Read `docs/auth.md` offset=111 limit=45
+→ Read `docs/auth.md` offset=201 limit=20
+
+### 3. 激活并编码
 
-前置检查通过后：
 1. 用 Edit 更新子任务 Status 为 `in-progress`
 2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
 3. 更新文件头 `Updated` 日期
-4. 读取 `### Checklist`，逐项执行编码工作
+4. 结合详设上下文 + Checklist，逐项执行编码工作
 5. 每完成一个 checklist 项 → 用 Edit 将 `- [ ]` 改为 `- [x]`
 
-### 3. 自动完成
+### 4. 自动完成
 
 当所有 checklist 项都勾选为 `[x]` 后：
 1. 用 Edit 更新 Status 为 `done`
 2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
 3. 更新文件头 `Updated` 日期
-4. 输出：`TASK-xxx 已完成 ✓`
+4. 输出：`TASK-xxx 已完成`
 
 ## 整文件模式
 
@@ -56,7 +71,13 @@
 
 用 Read 读取整个 task 文件，提取所有 `## TASK-xxx` 段落的 ID、Status、Depends。
 
-### 2. 构建执行计划
+### 2. 加载详设文档
+
+读取文件头的 `Source` 字段，用 Read 加载完整的详设文档作为全局上下文。
+
+> 注：整文件模式加载完整详设（因为涉及所有子任务），单任务模式只加载关联章节（节省 token）。
+
+### 3. 构建执行计划
 
 按依赖关系拓扑排序：
 1. 筛选所有 `draft` 状态的子任务
@@ -81,13 +102,13 @@
 开始执行...
 ```
 
-### 3. 按序执行
+### 4. 按序执行
 
-对每个可激活的子任务，执行单任务模式的步骤 2-3。
+对每个可激活的子任务，执行单任务模式的步骤 3-4（详设已在步骤 2 加载，无需重复读取）。
 
 完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
 
-### 4. 输出摘要
+### 5. 输出摘要
 
 ```
 执行完成：

package/src/adapters/claude/commands/cf-task/status.md

@@ -11,7 +11,7 @@
 
 ### 1. 读取任务数据
 
-- 用 Glob 搜索 `.code-flow/tasks/*.md`（排除 `archived/` 目录）
+- 用 Glob 搜索 `.code-flow/tasks/**/*.md`（排除 `archived/` 目录）
 - 逐个 Read，提取每个 `## TASK-xxx` 的：ID、标题、Status、Priority、Depends、Checklist 完成度
 
 ### 2. 输出总览表格