harness-track-feature-progress

Core Capabilities

从 feature_list.json 选择下一个未完成功能，更新全局状态，触发下游技能执行。

核心职责：

1. 读取并解析 feature_list.json
2. 按 priority > category > id 排序筛选未完成功能
3. 更新 GLOBAL_STATE.md（current_feature 字段）
4. 记录选择事件到 EVENT_LOG.md
5. 触发下游技能（单会话模式 → harness-goal，并行模式 → harness-schedule-parallel-agents）

Execution Steps

Step 1: 读取功能清单

工具: Read
文件: .EnjoyHarness/feature_list.json
Token 消耗: ~500 tokens（10项）或 ~8000 tokens（200项）
失败处理:
  - 如果文件不存在 → 提示"请先运行 Initializer Agent 生成功能清单"
  - 如果 JSON 格式错误 → 提示"feature_list.json 格式错误"

Step 2: 验证 JSON Schema

工具: Bash
命令: python3 tools/validate_feature_list.py
Token 消耗: ~100 tokens
失败处理:
  - 如果验证失败 → 拒绝继续执行，记录错误到 EVENT_LOG.md

Step 3: 解析 JSON（AI 内部处理）

处理逻辑:
  1. 过滤 passes: false 的功能
  2. 按 priority 排序（HIGH > MEDIUM > LOW）
  3. 按 category 排序（core > api > ui > security > performance > test）
  4. 按 id 排序（FEAT-001 > FEAT-002 > ...）
  5. 选择第一个作为当前功能

Token 消耗: ~500 tokens

Step 4: 更新全局状态

工具: Edit
文件: .EnjoyHarness/GLOBAL_STATE.md
修改字段: current_feature: null → FEAT-001
Token 消耗: ~50 tokens

Step 5: 记录事件日志

工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
  - 时间戳：2026-03-28T12:00:00
  - 事件类型：FEATURE_SELECT
  - 功能ID：FEAT-001
  - 功能描述：实现功能清单机制
Token 消耗: ~50 tokens

Step 6: 输出功能信息

输出格式:
  功能ID: FEAT-001
  分类: core
  优先级: HIGH
  描述: 实现功能清单机制 - feature_list.json 强约束管理
  验证步骤:
    1. 创建 feature_list.json 文件（符合 JSON Schema）
    2. 实现 JSON Schema 验证（Python jsonschema）
    3. 实现 harness-track-feature-progress 技能
    4. 测试功能选择逻辑（优先级排序）

Token 消耗: ~100 tokens

Step 7: 触发下游技能

单会话模式:
  - 触发: harness-goal（创建 SMART 目标）

并行模式:
  - 触发: harness-schedule-parallel-agents（批量生成子代理）

模式识别逻辑:
  if 项目规模 == "LARGE" OR 功能数 > 50 OR 用户显式指定:
    模式 = "并行模式"
  else:
    模式 = "单会话模式"

Prerequisites

必须满足：

• ✅ 已执行 harness-init（系统初始化完成）
• ✅ .EnjoyHarness/feature_list.json 存在
• ✅ JSON Schema 验证通过

如果前置条件不满足：

• 提示用户运行 harness-init 或生成功能清单
• 拒绝继续执行

Success Criteria

成功标准：

1. ✅ 成功读取并解析 feature_list.json
2. ✅ JSON Schema 验证通过
3. ✅ 成功选择下一个未完成功能（按优先级排序）
4. ✅ 成功更新 GLOBAL_STATE.md（current_feature 字段）
5. ✅ 成功记录事件到 EVENT_LOG.md
6. ✅ 输出功能信息（ID、描述、优先级、步骤）
7. ✅ 触发下游技能（单会话模式 → harness-goal，并行模式 → harness-schedule-parallel-agents）

失败情况：

• ❌ 功能清单文件不存在 → 提示生成功能清单
• ❌ JSON Schema 验证失败 → 拒绝执行，记录错误
• ❌ 无未完成功能 → 提示"所有功能已完成"，生成最终报告

Failure Recovery

错误场景 1: 功能清单文件不存在

检测: Read 失败
处理:
  1. 输出提示："请先运行 Initializer Agent 生成功能清单"
  2. 记录到 EVENT_LOG.md（ERROR | FEATURE_LIST_NOT_FOUND）
  3. 退出执行（不继续后续步骤）

错误场景 2: JSON Schema 验证失败

检测: validate_feature_list.py 返回非零退出码
处理:
  1. 输出提示："feature_list.json 格式错误，请检查 JSON Schema"
  2. 记录到 EVENT_LOG.md（ERROR | JSON_SCHEMA_VALIDATION_FAILED）
  3. 退出执行（不继续后续步骤）

错误场景 3: 无未完成功能

检测: passes: false 的功能为空
处理:
  1. 输出提示："所有功能已完成"
  2. 触发最终报告生成
  3. 记录到 EVENT_LOG.md（INFO | ALL_FEATURES_COMPLETED）
  4. 退出执行

错误场景 4: GLOBAL_STATE.md 更新失败

检测: Edit 失败
处理:
  1. 重试一次（最多 2 次）
  2. 如果仍然失败 → 记录到 EVENT_LOG.md（ERROR | GLOBAL_STATE_UPDATE_FAILED）
  3. 触发 harness-handle-failure

Relationships

Triggers (触发下游)

单会话模式:
  - harness-goal（创建 SMART 目标）

并行模式:
  - harness-schedule-parallel-agents（批量生成子代理）

Triggered By (被谁触发)

触发时机:
  - 主会话启动时（自动）
  - 子代理完成后（主会话选择下一个功能）
  - 功能开发完成后（标记完成，选择下一个）
  - 用户显式调用："选择下一个功能"

Dependencies (前置依赖)

必须依赖:
  - harness-init（系统初始化）

Token 消耗分析

小项目（10项）:
  - 读取 feature_list.json: ~500 tokens
  - JSON Schema 验证: ~100 tokens
  - 解析和排序: ~500 tokens
  - 更新 GLOBAL_STATE.md: ~50 tokens
  - 记录 EVENT_LOG.md: ~50 tokens
  - 输出功能信息: ~100 tokens
  总计: ~1300 tokens

大项目（200项）:
  - 读取 feature_list.json: ~8000 tokens
  - 其他步骤相同
  总计: ~8800 tokens

Examples

示例 1: 选择第一个功能

输入:
  feature_list.json 包含 6 个功能，全部 passes: false

处理:
  1. 读取并解析 JSON
  2. 验证 JSON Schema
  3. 过滤 passes: false（6 个功能）
  4. 排序：
     - FEAT-001 (priority: HIGH, category: core)
     - FEAT-002 (priority: HIGH, category: core)
     - FEAT-003 (priority: HIGH, category: core)
     - FEAT-004 (priority: MEDIUM, category: api)
     - FEAT-005 (priority: MEDIUM, category: api)
     - FEAT-006 (priority: LOW, category: ui)
  5. 选择 FEAT-001
  6. 更新 GLOBAL_STATE.md（current_feature: FEAT-001）
  7. 记录到 EVENT_LOG.md
  8. 输出功能信息
  9. 触发 harness-goal（单会话模式）

输出:
  功能ID: FEAT-001
  分类: core
  优先级: HIGH
  描述: 实现功能清单机制 - feature_list.json 强约束管理

示例 2: 无未完成功能

输入:
  feature_list.json 包含 6 个功能，全部 passes: true

处理:
  1. 读取并解析 JSON
  2. 过滤 passes: false（空列表）
  3. 输出提示："所有功能已完成"

输出:
  🎉 所有功能已完成！
  总功能数：6
  已完成：6
  完成率：100%

  下一步：
  - 生成最终报告
  - 触发 harness-auto-full-execution 结束流程

Implementation Notes

关键设计决策

1. JSON Schema 强约束
   • 仅允许修改 passes 字段
   • 禁止删除或编辑功能描述
   • 每次修改前验证 Schema
2. 优先级排序
   • priority > category > id
   • 确保高优先级功能优先开发
   • 同优先级按分类排序（core > api > ui）
3. 模式切换
   • 自动识别项目规模
   • 小项目 → 单会话模式（节省 Token）
   • 大项目 → 并行模式（提高吞吐）

性能优化

大项目优化:
  - 使用 JSON 压缩（去掉空格和缩进）
  - Token 消耗降低 30%

状态读取优化:
  - 仅读取必要字段（id, priority, category, passes）
  - Token 消耗降低 50%