konglong87 harness-track-feature-progress
Core Capabilities
从 feature_list.json 选择下一个未完成功能，更新全局状态，触发下游技能执行。
核心职责：
- 读取并解析
feature_list.json - 按 priority > category > id 排序筛选未完成功能
- 更新
GLOBAL_STATE.md（current_feature 字段） - 记录选择事件到
EVENT_LOG.md - 触发下游技能（单会话模式 → 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
成功标准：
- ✅ 成功读取并解析
feature_list.json - ✅ JSON Schema 验证通过
- ✅ 成功选择下一个未完成功能（按优先级排序）
- ✅ 成功更新
GLOBAL_STATE.md（current_feature 字段） - ✅ 成功记录事件到
EVENT_LOG.md - ✅ 输出功能信息（ID、描述、优先级、步骤）
- ✅ 触发下游技能（单会话模式 → 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
关键设计决策
JSON Schema 强约束
- 仅允许修改
passes字段 - 禁止删除或编辑功能描述
- 每次修改前验证 Schema
- 仅允许修改
优先级排序
- priority > category > id
- 确保高优先级功能优先开发
- 同优先级按分类排序（core > api > ui）
模式切换
- 自动识别项目规模
- 小项目 → 单会话模式（节省 Token）
- 大项目 → 并行模式（提高吞吐）
性能优化
大项目优化:
- 使用 JSON 压缩（去掉空格和缩进）
- Token 消耗降低 30%
状态读取优化:
- 仅读取必要字段（id, priority, category, passes）
- Token 消耗降低 50%