harness-determine-granularity

Core Capabilities

基于项目规模分析，自动选择粒度等级（COARSE/MEDIUM/FINE），更新全局状态，推荐执行模式。

核心职责：

1. 读取项目规模分析报告（PROJECT_SCALE_REPORT.md）
2. 根据判定规则确定粒度等级
3. 推荐执行模式（快速/单会话/子代理并行）
4. 更新 GLOBAL_STATE.md（granularity_level 字段）
5. 更新 feature_list.json（granularity_level 字段）
6. 输出粒度决策报告

Execution Steps

Step 1: 读取项目规模分析报告

工具: Read
文件: .EnjoyHarness/PROJECT_SCALE_REPORT.md
Token 消耗: ~300 tokens
失败处理:
- 如果文件不存在 → 提示"请先运行 harness-analyze-project-scale"
- 如果文件损坏 → 尝试重新分析项目规模

Step 2: 提取关键数据

提取字段:
- total_features: 功能总数
- total_apis: 接口总数
- estimated_hours: 预计执行时间
- complexity_level: 复杂度等级

Token 消耗: ~100 tokens

Step 3: 应用判定规则

判定规则（优先级从高到低）:

规则 1: FINE（细粒度）
条件:
  - 功能数 > 50 OR
  - 接口数 > 10 OR
  - 执行时间 > 100 小时
动作:
  - granularity_level = FINE
  - recommended_mode = 子代理并行
  - max_parallel_agents = 3

规则 2: MEDIUM（中粒度）
条件:
  - 功能数 >= 10 OR
  - 接口数 >= 5 OR
  - 执行时间 >= 20 小时
动作:
  - granularity_level = MEDIUM
  - recommended_mode = 单会话模式
  - max_features_per_session = 1

规则 3: COARSE（粗粒度）
条件:
  - 功能数 < 10 AND
  - 接口数 < 5 AND
  - 执行时间 < 20 小时
动作:
  - granularity_level = COARSE
  - recommended_mode = 快速模式
  - one_shot_execution = true

Token 消耗: ~100 tokens

Step 4: 更新 GLOBAL_STATE.md

工具: Edit
文件: .EnjoyHarness/GLOBAL_STATE.md
修改字段:
  granularity_level: COARSE/MEDIUM/FINE
  recommended_mode: 快速模式/单会话模式/子代理并行
  max_parallel_agents: 0/1/3
  estimated_hours: {从分析报告中读取}

Token 消耗: ~50 tokens

Step 5: 更新 feature_list.json

工具: Read + Edit
文件: .EnjoyHarness/feature_list.json
修改字段:
  granularity_level: COARSE/MEDIUM/FINE
  estimated_features_per_session: {基于粒度计算}

计算公式:
- COARSE: 所有功能（一次性完成）
- MEDIUM: 1 功能/会话
- FINE: 3 功能/批次（子代理并行）

Token 消耗: ~100 tokens
验证:
- 使用 Python jsonschema 验证 JSON 格式

Step 6: 输出粒度决策报告

报告格式:
🎯 粒度等级决策报告

项目规模数据:
- 功能总数: {total_features}
- 接口总数: {total_apis}
- 预计执行时间: {estimated_hours} 小时
- 复杂度等级: {complexity_level}

粒度等级: {granularity_level}
判定依据:
- 功能数: {total_features} ({criteria_features})
- 接口数: {total_apis} ({criteria_apis})
- 执行时间: {estimated_hours} 小时 ({criteria_time})

推荐执行模式: {recommended_mode}
配置参数:
- max_parallel_agents: {max_parallel_agents}
- max_features_per_session: {max_features_per_session}

下一步建议:
- 如果 FINE → 使用子代理并行模式，每批 3 个功能
- 如果 MEDIUM → 使用单会话模式，每次 1 个功能
- 如果 COARSE → 使用快速模式，一次性完成所有功能

Token 消耗: ~200 tokens

Prerequisites

必须满足：

• ✅ 已执行 harness-analyze-project-scale（项目规模分析完成）
• ✅ 存在 PROJECT_SCALE_REPORT.md 文件

如果前置条件不满足：

• 如果缺少分析报告 → 自动调用 harness-analyze-project-scale

Success Criteria

成功标准：

1. ✅ 成功读取项目规模分析报告
2. ✅ 正确应用判定规则
3. ✅ 成功更新 GLOBAL_STATE.md
4. ✅ 成功更新 feature_list.json
5. ✅ 输出详细的粒度决策报告

失败情况：

• ❌ 缺少分析报告 → 自动触发分析
• ❌ JSON 格式验证失败 → 记录错误，拒绝写入

Failure Recovery

错误场景 1: 缺少分析报告

检测: PROJECT_SCALE_REPORT.md 不存在
处理:
1. 自动调用 harness-analyze-project-scale
2. 等待分析完成
3. 继续执行粒度判定

错误场景 2: 数据提取失败

检测: 无法提取关键字段（功能数、接口数、执行时间）
处理:
1. 尝试重新分析项目规模
2. 如果仍然失败 → 使用默认值:
   - 功能数: 10（MEDIUM）
   - 接口数: 5
   - 执行时间: 50 小时
3. 提示用户: "使用默认值估算"

错误场景 3: JSON 格式验证失败

检测: Python jsonschema 验证失败
处理:
1. 记录到 EVENT_LOG.md（ERROR | JSON_VALIDATION_FAILED）
2. 输出验证错误详情
3. 拒绝写入 feature_list.json
4. 触发 harness-handle-failure；仅真实阻塞时升级人工介入

Relationships

Triggers (触发下游)

粒度确定后:
- 触发 harness-track-feature-progress（使用正确的粒度等级）
- 触发 feature_list.json 更新（granularity_level 字段）

Triggered By (被谁触发)

触发时机:
- harness-analyze-project-scale 完成后（自动）
- 用户显式调用："确定粒度等级"
- 功能清单生成前（确保粒度等级正确）

Dependencies (前置依赖)

必须依赖:
- harness-analyze-project-scale（项目规模分析）

Token 消耗分析

单次执行:
- Read 分析报告: ~300 tokens
- 提取关键数据: ~100 tokens
- 应用判定规则: ~100 tokens
- 更新 GLOBAL_STATE.md: ~50 tokens
- 更新 feature_list.json: ~100 tokens
- 输出决策报告: ~200 tokens
总计: ~850 tokens

性能优化:
- 复用分析报告（避免重复分析）
- 增量式更新（仅修改必要字段）
- Token 消耗降低 30%

Examples

示例 1: 大型项目 → FINE

输入:
功能总数: 215
接口总数: 25
预计执行时间: 682.5 小时

处理:
1. 应用判定规则:
   - 功能数 215 > 50 ✅ → FINE
2. 推荐执行模式: 子代理并行
3. 配置参数:
   - max_parallel_agents: 3
   - max_features_per_session: 3（每批）

输出:
🎯 粒度等级决策报告

粒度等级: FINE
判定依据:
- 功能数: 215 (>50) ✅
- 接口数: 25 (>10) ✅
- 执行时间: 682.5 小时 (>100) ✅

推荐执行模式: 子代理并行
配置参数:
- max_parallel_agents: 3
- max_features_per_session: 3

下一步建议: 使用子代理并行模式，每批 3 个功能

示例 2: 中型项目 → MEDIUM

输入:
功能总数: 35
接口总数: 8
预计执行时间: 93.6 小时

处理:
1. 应用判定规则:
   - 功能数 35 >= 10 → MEDIUM
   - 执行时间 93.6 < 100 → 不满足 FINE
2. 推荐执行模式: 单会话模式
3. 配置参数:
   - max_parallel_agents: 0
   - max_features_per_session: 1

输出:
🎯 粒度等级决策报告

粒度等级: MEDIUM
判定依据:
- 功能数: 35 (10-50) ✅
- 接口数: 8 (5-10) ✅
- 执行时间: 93.6 小时 (<100) ✅

推荐执行模式: 单会话模式
配置参数:
- max_parallel_agents: 0
- max_features_per_session: 1

下一步建议: 使用单会话模式，每次 1 个功能

示例 3: 小型项目 → COARSE

输入:
功能总数: 5
接口总数: 0
预计执行时间: 10 小时

处理:
1. 应用判定规则:
   - 功能数 5 < 10 → COARSE
2. 推荐执行模式: 快速模式
3. 配置参数:
   - one_shot_execution: true

输出:
🎯 粒度等级决策报告

粒度等级: COARSE
判定依据:
- 功能数: 5 (<10) ✅
- 接口数: 0 (<5) ✅
- 执行时间: 10 小时 (<20) ✅

推荐执行模式: 快速模式
配置参数:
- one_shot_execution: true

下一步建议: 使用快速模式，一次性完成所有功能

示例 4: 边界条件 → FINE

输入:
功能总数: 51
接口总数: 10
预计执行时间: 102 小时

处理:
1. 应用判定规则:
   - 功能数 51 > 50 → FINE（刚好超过阈值）
2. 推荐执行模式: 子代理并行

输出:
🎯 粒度等级决策报告

粒度等级: FINE
判定依据:
- 功能数: 51 (>50) ✅（刚好超过 FINE 阈值）
- 接口数: 10 (=10) ❌（不满足 FINE）
- 执行时间: 102 小时 (>100) ✅

下一步建议: 使用子代理并行模式

Implementation Notes

关键设计决策

1. 判定规则优先级

• 功能数 > 接口数 > 执行时间（优先级递减）
• 任一条件满足 → 触发对应粒度等级
• 避免冲突（高优先级覆盖低优先级）

2. 配置参数联动

• FINE → max_parallel_agents: 3
• MEDIUM → max_features_per_session: 1
• COARSE → one_shot_execution: true

3. 自动触发机制

• 缺少分析报告 → 自动调用分析技能
• 确保粒度等级始终正确

性能优化

Token 优化:
- 复用分析报告（避免重复读取）
- 增量式更新（仅修改必要字段）
- JSON 压缩（降低写入开销）

执行优化:
- 自动触发分析（减少用户干预）
- 快速判定（O(1) 时间复杂度）
- 批量更新（一次写入多个字段）

总体优化:
- Token 消耗降低 30%
- 执行时长缩短 20%