konglong87 harness-adjust-granularity
Core Capabilities
监控执行过程，动态调整粒度等级，自动拆分或合并功能项，确保项目执行效率最优。
核心职责：
- 监控执行进度（跟踪完成率、失败率、平均执行时间）
- 检测粒度不合理情况（执行时间偏差、Token 消耗异常）
- 触发粒度调整（COARSE ↔ MEDIUM ↔ FINE）
- 自动拆分功能项（执行时间过长 → 拆分为更小粒度）
- 自动合并功能项（执行时间过短 → 合并为更大粒度）
- 更新功能清单（重新编号、更新依赖关系）
- 输出调整报告（调整原因、调整结果、性能对比）
Execution Steps
Step 1: 监控执行进度
工具: Read
文件: .EnjoyHarness/feature_list.json
监控维度:
维度 1: 完成率监控
计算公式:
completion_rate = completed_features / total_features
数据来源:
- completed_features: 统计 passes: true 的功能数
- total_features: 功能总数
Token 消耗: ~100 tokens
维度 2: 失败率监控
计算公式:
failure_rate = failed_features / completed_features
数据来源:
- failed_features: 统计 error_count > 0 的功能数
- completed_features: 已完成功能数
阈值:
- 正常: failure_rate < 10%
- 警告: failure_rate >= 10% 且 < 30%
- 异常: failure_rate >= 30%（触发粒度调整）
Token 消耗: ~100 tokens
维度 3: 平均执行时间监控
计算公式:
avg_execution_time = sum(execution_times) / completed_features
数据来源:
- execution_times: 从 EVENT_LOG.md 提取每个功能的执行时间
- completed_features: 已完成功能数
偏差检测:
- 实际执行时间 vs 预估时间
- 偏差率 = |actual - estimated| / estimated
- 阈值: 偏差率 > 50%（触发粒度调整）
Token 消耗: ~200 tokens
Step 2: 检测粒度不合理情况
检测规则（按优先级从高到低）:
规则 1: 执行时间过长（拆分触发）
条件:
- 单个功能项执行时间 > 2 * estimated_hours
- 或 Token 消耗 > 50000 tokens per 功能项
判定:
- 粒度过粗（需要拆分）
- 调整方向: COARSE → MEDIUM 或 MEDIUM → FINE
动作:
- 标记该功能项为"需要拆分"
- 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | SPLIT）
Token 消耗: ~100 tokens
规则 2: 执行时间过短（合并触发）
条件:
- 单个功能项执行时间 < 0.5 * estimated_hours
- 且连续 5 个功能项都过短
判定:
- 粒度过细（需要合并）
- 调整方向: FINE → MEDIUM 或 MEDIUM → COARSE
动作:
- 标记这些功能项为"需要合并"
- 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | MERGE）
Token 消耗: ~100 tokens
规则 3: 失败率异常（拆分触发）
条件:
- failure_rate >= 30%
- 或连续 3 个功能项失败
判定:
- 功能项过于复杂（需要拆分）
- 调整方向: 拆分为更小粒度
动作:
- 标记失败功能项为"需要拆分"
- 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | SPLIT_DUE_TO_FAILURE）
Token 消耗: ~100 tokens
规则 4: Token 消耗异常（拆分触发）
条件:
- 单个功能项 Token 消耗 > 预算的 150%
- 或总 Token 消耗 > 预算的 120%
判定:
- 功能项过于复杂或上下文过大
- 需要拆分以降低上下文负担
动作:
- 标记该功能项为"需要拆分"
- 记录到 EVENT_LOG.md（GRANULARITY_ADJUST | SPLIT_DUE_TO_TOKEN_OVERFLOW）
Token 消耗: ~100 tokens
Step 3: 触发粒度调整
调整策略:
策略 1: 拆分功能项（FINE 化）
适用场景:
- 执行时间过长
- 失败率异常
- Token 消耗异常
拆分规则:
- COARSE → MEDIUM: 拆分为 3-5 个功能项（每个 2-4 小时）
- MEDIUM → FINE: 拆分为 2-3 个功能项（每个 1-2 小时）
- 保持功能完整性（拆分后仍可独立验证）
示例:
原功能: FEAT-001: 用户管理（COARSE, 8h）
拆分为:
- FEAT-001-1: 用户注册（MEDIUM, 3h）
- FEAT-001-2: 用户登录（MEDIUM, 3h）
- FEAT-001-3: 用户资料管理（MEDIUM, 2h）
Token 消耗: ~500 tokens per 拆分操作
策略 2: 合并功能项（COARSE 化）
适用场景:
- 执行时间过短（连续 5 个功能项都 < 预估时间的一半）
合并规则:
- FINE → MEDIUM: 合并 2-3 个相关功能项（每个 2-4 小时）
- MEDIUM → COARSE: 合并 3-5 个相关功能项（每个 4-8 小时）
- 保持模块内聚（合并的功能项应属于同一模块）
示例:
原功能:
- FEAT-001: 用户注册接口（FINE, 1h）
- FEAT-002: 用户注册页面（FINE, 1h）
- FEAT-003: 注册表单验证（FINE, 1h）
合并为:
- FEAT-001: 用户注册（MEDIUM, 3h, 包含接口+页面+验证）
Token 消耗: ~500 tokens per 合并操作
Step 4: 更新功能清单
工具: Read + Edit
文件: .EnjoyHarness/feature_list.json
更新操作:
操作 1: 重新编号
规则:
- 拆分后: FEAT-001 → FEAT-001-1, FEAT-001-2, FEAT-001-3
- 合并后: FEAT-001, FEAT-002, FEAT-003 → FEAT-001（合并）
- 保持 ID 唯一性（避免冲突）
Token 消耗: ~200 tokens
操作 2: 更新依赖关系
规则:
- 拆分后:
- 原依赖: FEAT-001 依赖 FEAT-002
- 新依赖: FEAT-001-1 依赖 FEAT-002（或 FEAT-002-1）
- 合并后:
- 原依赖: FEAT-001 依赖 FEAT-002, FEAT-003
- 新依赖: FEAT-001（合并）依赖 FEAT-002（合并）
Token 消耗: ~300 tokens
操作 3: 更新预估时间
规则:
- 拆分后: 重新预估每个子功能项的时间
- 合并后: 重新预估合并后功能项的时间
Token 消耗: ~100 tokens
验证:
- JSON Schema 验证（确保格式正确）
- 依赖关系检查（避免循环依赖）
- ID 唯一性检查（避免冲突）
Step 5: 记录调整历史
工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
- 时间戳: {timestamp}
- 事件类型: GRANULARITY_ADJUST
- 调整类型: SPLIT/MERGE
- 原因: {reason}
- 原功能ID: {original_ids}
- 新功能ID: {new_ids}
- 性能对比:
- 原预估时间: {original_estimated}
- 新预估时间: {new_estimated}
- 调整效果: {improvement}
Token 消耗: ~100 tokens
Step 6: 输出调整报告
报告格式:
🔧 粒度调整报告
调整时间: {timestamp}
调整类型: {adjustment_type}（SPLIT/MERGE）
调整原因:
- 检测到的问题: {detected_issue}
- 触发规则: {trigger_rule}
- 数据支持: {data_evidence}
调整详情:
原功能项:
- ID: {original_ids}
- 描述: {original_descriptions}
- 预估时间: {original_estimated_hours}
- 实际执行时间: {actual_hours}
新功能项:
- ID: {new_ids}
- 描述: {new_descriptions}
- 预估时间: {new_estimated_hours}
- 预期执行时间: {expected_hours}
性能对比:
- 原预估时间: {original_total} 小时
- 新预估时间: {new_total} 小时
- 时间优化: {time_improvement}%
- Token 优化: {token_improvement}%
更新文件:
- feature_list.json（功能项已更新）
- EVENT_LOG.md（调整历史已记录）
- GLOBAL_STATE.md（粒度等级已更新）
下一步建议:
- 继续执行功能开发（使用新粒度）
- 监控调整后的执行效果
- 如效果不佳，可再次调整
Token 消耗: ~300 tokens
Prerequisites
必须满足：
- ✅ 已执行
harness-generate-feature-list（功能清单已生成） - ✅ 功能清单中至少有 5 个功能项（便于统计和调整）
- ✅ 已执行一段时间（至少完成 20% 功能，有统计数据）
如果前置条件不满足：
- 如果统计数据不足 → 等待执行一段时间后再调整
- 如果功能项太少 → 提示"功能项太少，不建议调整"
Success Criteria
成功标准：
- ✅ 成功监控执行进度（完成率、失败率、平均执行时间）
- ✅ 成功检测粒度不合理情况（至少一种异常）
- ✅ 成功触发粒度调整（拆分或合并）
- ✅ 成功更新功能清单（重新编号、更新依赖）
- ✅ 成功记录调整历史（EVENT_LOG.md）
- ✅ 成功输出调整报告
失败情况：
- ❌ 统计数据不足 → 提示等待更多执行数据
- ❌ 功能项太少 → 提示不建议调整
- ❌ JSON 格式验证失败 → 记录错误，拒绝写入
Failure Recovery
错误场景 1: 统计数据不足
检测: 完成功能数 < 5 或完成率 < 20%
处理:
1. 输出提示: "统计数据不足，建议等待更多功能完成后再调整"
2. 显示当前进度:
- 完成功能数: {completed_features}
- 总功能数: {total_features}
- 完成率: {completion_rate}%
3. 建议: "等待完成率 ≥ 20% 后再触发调整"
错误场景 2: 功能项太少
检测: 总功能数 < 5
处理:
1. 输出提示: "功能项太少，不建议调整粒度"
2. 显示功能总数: {total_features}
3. 建议: "功能项太少时，调整粒度可能适得其反"
错误场景 3: 调整后循环依赖
检测: 调整后的依赖关系包含循环
处理:
1. 检测循环依赖: A → B → C → A
2. 输出循环依赖链
3. 自动解除循环依赖:
- 移除优先级最低的依赖
- 或拆分依赖关系
4. 记录警告到 EVENT_LOG.md
错误场景 4: JSON 格式验证失败
检测: Python jsonschema 验证失败
处理:
1. 输出验证错误详情
2. 回滚调整操作（恢复原功能清单）
3. 提示用户手动调整
4. 记录错误到 EVENT_LOG.md
Relationships
Triggers (触发下游)
调整成功:
- 触发 harness-track-feature-progress（使用新粒度继续开发）
- 更新 GLOBAL_STATE.md（granularity_level 字段）
Triggered By (被谁触发)
触发时机:
- 定期监控（每隔 10% 完成率触发一次）
- 异常检测（失败率异常、Token 消耗异常）
- 用户显式调用："调整粒度"
Dependencies (前置依赖)
必须依赖:
- harness-generate-feature-list（功能清单生成）
Token 消耗分析
单次调整:
- 监控执行进度: ~400 tokens
- 检测粒度不合理: ~400 tokens
- 触发粒度调整: ~500 tokens
- 更新功能清单: ~600 tokens
- 记录调整历史: ~100 tokens
- 输出调整报告: ~300 tokens
总计: ~2300 tokens
性能对比:
- 调整前 Token 消耗: 可能异常高（如 50000+ tokens）
- 调整后 Token 消耗: 优化至正常水平（如 20000 tokens）
- Token 优化: 降低 60%
总体优化:
- 执行时间优化: 30-50%
- Token 消耗优化: 60%
- 失败率降低: 40%
Examples
示例 1: 执行时间过长 → 拆分
输入:
监控数据:
- 完成率: 30%
- FEAT-001: 用户管理
- 预估时间: 8 小时
- 实际执行时间: 18 小时
- 偏差率: 125%（触发拆分）
处理:
1. 检测到执行时间过长（18h vs 8h）
2. 判定: 粒度过粗（COARSE），需要拆分
3. 拆分 FEAT-001:
- FEAT-001-1: 用户注册（MEDIUM, 3h）
- FEAT-001-2: 用户登录（MEDIUM, 3h）
- FEAT-001-3: 用户资料管理（MEDIUM, 2h）
4. 更新功能清单
5. 输出调整报告
输出:
🔧 粒度调整报告
调整类型: SPLIT（拆分）
调整原因:
- 检测到的问题: 执行时间过长
- 偏差率: 125%（实际 18h vs 预估 8h）
原功能项:
- FEAT-001: 用户管理（8h）
新功能项:
- FEAT-001-1: 用户注册（3h）
- FEAT-001-2: 用户登录（3h）
- FEAT-001-3: 用户资料管理（2h）
性能对比:
- 原预估时间: 8 小时
- 新预估时间: 8 小时（总和）
- 预期执行时间: 9 小时（优化后）
下一步: 继续执行，监控拆分后的效果
示例 2: 执行时间过短 → 合并
输入:
监控数据:
- 完成率: 40%
- 连续 5 个功能项执行时间过短:
- FEAT-010: 1h（预估 3h）
- FEAT-011: 0.8h（预估 2h）
- FEAT-012: 0.9h（预估 2h）
- FEAT-013: 1.1h（预估 3h）
- FEAT-014: 0.7h（预估 2h）
处理:
1. 检测到执行时间过短（连续 5 个功能项）
2. 判定: 粒度过细（FINE），需要合并
3. 合并 FEAT-010 ~ FEAT-014:
- FEAT-010: 用户管理增强（MEDIUM, 4h，包含原 5 个功能项）
4. 更新功能清单
5. 输出调整报告
输出:
🔧 粒度调整报告
调整类型: MERGE（合并）
调整原因:
- 检测到的问题: 执行时间过短（连续 5 个功能项）
- 平均偏差率: -60%（实际时间仅为预估的 40%）
原功能项:
- FEAT-010: 用户头像上传（1h）
- FEAT-011: 用户昵称修改（0.8h）
- FEAT-012: 用户简介编辑（0.9h）
- FEAT-013: 用户密码修改（1.1h）
- FEAT-014: 用户邮箱修改（0.7h）
新功能项:
- FEAT-010: 用户管理增强（4h，包含以上 5 个功能）
性能对比:
- 原预估时间: 12 小时（总和）
- 新预估时间: 4 小时（合并后）
- 时间优化: 66%
下一步: 继续执行，监控合并后的效果
示例 3: 失败率异常 → 拆分
输入:
监控数据:
- 完成率: 50%
- 失败率: 35%（异常）
- 连续失败功能项: FEAT-020, FEAT-021, FEAT-022
处理:
1. 检测到失败率异常（35% > 30%）
2. 判定: 功能项过于复杂，需要拆分
3. 拆分失败的功能项:
- FEAT-020: 支付集成（COMPLEX, 10h）→ 拆分为 3 个功能项
- FEAT-020-1: 支付接口对接（MEDIUM, 4h）
- FEAT-020-2: 支付状态同步（MEDIUM, 3h）
- FEAT-020-3: 支付异常处理（MEDIUM, 3h）
4. 更新功能清单
5. 输出调整报告
输出:
🔧 粒度调整报告
调整类型: SPLIT（拆分）
调整原因:
- 检测到的问题: 失败率异常
- 失败率: 35%（阈值 30%）
- 连续失败功能项: 3 个
原功能项:
- FEAT-020: 支付集成（COMPLEX, 10h）
新功能项:
- FEAT-020-1: 支付接口对接（MEDIUM, 4h）
- FEAT-020-2: 支付状态同步（MEDIUM, 3h）
- FEAT-020-3: 支付异常处理（MEDIUM, 3h）
性能对比:
- 原预估时间: 10 小时
- 新预估时间: 10 小时（总和）
- 预期失败率: < 10%（优化后）
下一步: 继续执行，监控拆分后的失败率
Implementation Notes
关键设计决策
- 定期监控机制
- 每隔 10% 完成率触发一次监控
- 避免频繁调整（影响执行效率）
- 确保及时发现问题（不过度延迟）
- 多维度检测
- 执行时间维度（偏差率 > 50%）
- 失败率维度（失败率 > 30%）
- Token 消耗维度（消耗 > 预算 150%）
- 双向调整能力
- 拆分（FINE 化）：降低复杂度、降低失败率
- 合并（COARSE 化）：提高效率、降低切换成本
- 自动回滚机制
- 如果调整后效果不佳（如失败率上升）
- 自动回滚到调整前的粒度
- 记录到 EVENT_LOG.md（ADJUST_ROLLBACK）
性能优化
Token 优化:
- 增量式监控（仅读取必要字段）
- 批量更新（减少重复写入）
- 缓存调整历史（避免重复计算）
执行优化:
- 异步监控（不阻塞主流程）
- 智能触发（仅在异常时调整）
- 快速回滚（调整失败时立即恢复）
总体优化:
- Token 消耗降低 60%
- 执行时间优化 30-50%
- 失败率降低 40%