konglong87 harness-analyze-project-scale
Core Capabilities
分析项目规模，统计功能数、接口数，估算执行时间，确定粒度等级（COARSE/MEDIUM/FINE）。
核心职责：
- 读取需求文档（README.md、docs/、specifications/）
- 统计功能数（features、user stories）
- 统计接口数（API endpoints、RPC methods）
- 估算执行时间（基于历史数据）
- 确定粒度等级（COARSE/MEDIUM/FINE）
- 输出规模分析报告
Execution Steps
Step 1: 读取需求文档
工具: Read
文件列表:
- README.md（项目概述）
- docs/requirements.md（需求文档）
- docs/specifications.md（技术规范）
- docs/api.md（API 文档）
Token 消耗: ~2000 tokens（小型项目）或 ~10000 tokens（大型项目）
失败处理:
- 如果文件不存在 → 跳过，继续检查其他文件
- 如果所有文件都不存在 → 提示"缺少需求文档，请提供项目概述"
Step 2: 统计功能数
分析逻辑:
1. 识别功能描述关键词:
- "实现"、"开发"、"添加"（功能动词）
- "用户故事"、"User Story"（敏捷术语）
- "功能点"、"Feature"（需求术语）
2. 统计方法:
- 提取所有功能描述
- 去重（避免重复计数）
- 分类（core/api/ui/security/performance/test）
Token 消耗: ~500 tokens
Step 3: 统计接口数
分析逻辑:
1. 识别 API 接口:
- HTTP 方法（GET/POST/PUT/DELETE）
- 路由定义（/api/xxx）
- RPC 方法（grpc/protobuf）
2. 统计方法:
- 正则表达式匹配路由定义
- 去重（避免重复计数）
- 分类（auth/user/product/order/payment）
Token 消耗: ~300 tokens
Step 4: 估算执行时间
估算公式:
execution_time = (
功能数 * avg_time_per_feature
+ 接口数 * avg_time_per_api
+ 复杂度系数
)
参数定义:
- avg_time_per_feature: 2 小时（基于历史数据）
- avg_time_per_api: 1 小时（基于历史数据）
- 复杂度系数:
- 简单: 1.0
- 中等: 1.5
- 复杂: 2.0
示例:
- 功能数: 50
- 接口数: 10
- 复杂度: 中等（1.5）
- 执行时间 = (50 * 2 + 10 * 1) * 1.5 = 165 小时
Token 消耗: ~100 tokens
Step 5: 确定粒度等级
粒度等级定义:
- COARSE（粗粒度）:
- 功能数: <10
- 接口数: <5
- 执行时间: <20 小时
- 适用场景: 紧急修复、小型项目、线性任务
- MEDIUM（中粒度）:
- 功能数: 10-50
- 接口数: 5-10
- 执行时间: 20-100 小时
- 适用场景: 中型项目、模块化开发、迭代优化
- FINE（细粒度）:
- 功能数: >50
- 接口数: >10
- 执行时间: >100 小时
- 适用场景: 大型项目、复杂系统、长期演进
判定逻辑:
if 功能数 > 50 or 接口数 > 10 or 执行时间 > 100:
granularity_level = FINE
elif 功能数 >= 10 or 接口数 >= 5 or 执行时间 >= 20:
granularity_level = MEDIUM
else:
granularity_level = COARSE
Token 消耗: ~100 tokens
Step 6: 输出规模分析报告
报告格式:
📊 项目规模分析报告
项目名称: {project_name}
分析时间: {timestamp}
功能统计:
- 功能总数: {total_features}
- 核心功能: {core_features}
- API 功能: {api_features}
- UI 功能: {ui_features}
- 安全功能: {security_features}
- 性能功能: {performance_features}
- 测试功能: {test_features}
接口统计:
- 接口总数: {total_apis}
- 认证接口: {auth_apis}
- 用户接口: {user_apis}
- 产品接口: {product_apis}
- 订单接口: {order_apis}
- 支付接口: {payment_apis}
执行估算:
- 预计执行时间: {estimated_hours} 小时
- 复杂度等级: {complexity_level}
- 推荐模式: {recommended_mode}
粒度等级: {granularity_level}
判定依据:
- 功能数: {total_features} ({criteria_features})
- 接口数: {total_apis} ({criteria_apis})
- 执行时间: {estimated_hours} 小时 ({criteria_time})
下一步建议:
- 如果 FINE → 使用子代理并行模式（max_parallel_agents: 3）
- 如果 MEDIUM → 使用单会话模式（max_features_per_session: 1）
- 如果 COARSE → 使用快速模式（一次性完成）
Token 消耗: ~300 tokens
Prerequisites
必须满足：
- ✅ 已执行
harness-init（系统初始化） - ✅ 项目根目录存在（有可分析的文件）
如果前置条件不满足：
- 如果未初始化 → 提示"请先运行 harness-init"
- 如果缺少需求文档 → 提示"请提供需求文档（README.md 或 docs/requirements.md）"
Success Criteria
成功标准：
- ✅ 成功读取需求文档（至少一个）
- ✅ 成功统计功能数（分类统计）
- ✅ 成功统计接口数（分类统计）
- ✅ 成功估算执行时间（基于历史数据）
- ✅ 成功确定粒度等级（COARSE/MEDIUM/FINE）
- ✅ 输出详细的规模分析报告
失败情况：
- ❌ 所有需求文档不存在 → 自动基于 README、目录结构和默认参数估算
- ❌ 无法提取功能或接口 → 自动回退到保守估算，不依赖用户手动提供规模数据
Failure Recovery
错误场景 1: 缺少需求文档
检测: 所有文档文件不存在
处理:
1. 自动回退到以下信息源：
- README.md
- docs/ 目录结构
- 源码目录结构与文件数量
2. 使用默认参数估算规模
3. 记录 WARNING | SCALE_ANALYSIS_DEGRADED
4. 提供文档模板作为后续优化参考:
- README.md（项目概述）
- docs/requirements.md（需求列表）
错误场景 2: 无法提取功能
检测: 正则表达式匹配失败
处理:
1. 尝试不同的提取策略:
- 关键词搜索（实现、开发、添加）
- 标题解析（## 功能列表）
- 表格解析（| 功能 | 描述 |）
2. 如果仍然失败 → 使用目录、文件命名和模块数做保守估算
错误场景 3: 执行时间估算不准确
检测: 历史数据不足（首次运行）
处理:
1. 使用默认参数估算:
- avg_time_per_feature: 2 小时
- avg_time_per_api: 1 小时
2. 提示用户: "首次运行，使用默认参数估算"
3. 记录 WARNING | SCALE_ESTIMATE_DEFAULTED
Relationships
Triggers (触发下游)
分析完成:
- 触发 harness-track-feature-progress（使用正确的粒度等级）
- 写入 GLOBAL_STATE.md（granularity_level 字段）
Triggered By (被谁触发)
触发时机:
- harness-init 完成后（自动分析项目规模）
- 用户显式调用："分析项目规模"
- 功能清单生成前（确定粒度等级）
Dependencies (前置依赖)
必须依赖:
- harness-init（系统初始化）
Token 消耗分析
小型项目（10项）:
- Read 需求文档: ~2000 tokens
- 统计功能数: ~500 tokens
- 统计接口数: ~300 tokens
- 估算执行时间: ~100 tokens
- 确定粒度等级: ~100 tokens
- 输出报告: ~300 tokens
总计: ~3300 tokens
大型项目（200项）:
- Read 需求文档: ~10000 tokens
- 其他步骤相同
总计: ~11300 tokens
性能优化:
- 仅读取必要文档（README.md + docs/requirements.md）
- Token 消耗降低 50%
Examples
示例 1: 大型项目（FINE 粒度）
输入:
项目: 电商平台
README.md: "本项目包含用户管理、商品管理、订单管理、支付系统等 215 个功能点..."
API 文档: "提供 25 个 REST API 接口..."
处理:
1. Read README.md → 提取 215 个功能
2. Read API 文档 → 提取 25 个接口
3. 分类统计:
- 功能: core(30), api(50), ui(80), security(25), performance(15), test(15)
- 接口: auth(5), user(8), product(6), order(4), payment(2)
4. 估算执行时间:
- (215 * 2 + 25 * 1) * 1.5 = 682.5 小时
5. 确定粒度等级: FINE（功能数 > 50, 接口数 > 10）
输出:
📊 项目规模分析报告
项目名称: 电商平台
功能总数: 215
接口总数: 25
预计执行时间: 682.5 小时
粒度等级: FINE
判定依据:
- 功能数: 215 (>50) ✅
- 接口数: 25 (>10) ✅
- 执行时间: 682.5 小时 (>100) ✅
推荐模式: 子代理并行（max_parallel_agents: 3）
示例 2: 中型项目（MEDIUM 粒度）
输入:
项目: 博客系统
README.md: "本项目包含文章管理、评论管理、用户管理等 35 个功能点..."
API 文档: "提供 8 个 REST API 接口..."
处理:
1. Read README.md → 提取 35 个功能
2. Read API 文档 → 提取 8 个接口
3. 分类统计:
- 功能: core(10), api(12), ui(8), security(3), performance(2)
- 接口: auth(2), user(3), article(2), comment(1)
4. 估算执行时间:
- (35 * 2 + 8 * 1) * 1.2 = 93.6 小时
5. 确定粒度等级: MEDIUM（功能数 10-50）
输出:
📊 项目规模分析报告
项目名称: 博客系统
功能总数: 35
接口总数: 8
预计执行时间: 93.6 小时
粒度等级: MEDIUM
判定依据:
- 功能数: 35 (10-50) ✅
- 接口数: 8 (5-10) ✅
- 执行时间: 93.6 小时 (<100) ✅
推荐模式: 单会话模式（max_features_per_session: 1）
示例 3: 小型项目（COARSE 粒度）
输入:
项目: 待办事项
README.md: "本项目包含添加任务、删除任务、标记完成等 5 个功能点..."
处理:
1. Read README.md → 提取 5 个功能
2. 无 API 文档 → 接口数: 0
3. 分类统计:
- 功能: core(3), ui(2)
4. 估算执行时间:
- (5 * 2 + 0 * 1) * 1.0 = 10 小时
5. 确定粒度等级: COARSE（功能数 <10）
输出:
📊 项目规模分析报告
项目名称: 待办事项
功能总数: 5
接口总数: 0
预计执行时间: 10 小时
粒度等级: COARSE
判定依据:
- 功能数: 5 (<10) ✅
- 接口数: 0 (<5) ✅
- 执行时间: 10 小时 (<20) ✅
推荐模式: 快速模式（一次性完成）
Implementation Notes
关键设计决策
- 粒度等级定义
- COARSE: <10 功能（适合快速完成任务）
- MEDIUM: 10-50 功能（适合模块化开发）
- FINE: >50 功能（适合子代理并行）
- 执行时间估算
- 基于历史数据（avg_time_per_feature, avg_time_per_api）
- 考虑复杂度系数（简单/中等/复杂）
- 动态调整（完成后更新历史数据）
- 分类统计
- 功能分类（core/api/ui/security/performance/test）
- 接口分类（auth/user/product/order/payment）
- 便于优先级排序和任务分配
性能优化
Token 优化:
- 仅读取必要文档（README.md + docs/requirements.md）
- 正则表达式优化（避免贪婪匹配）
- 增量式统计（逐步提取，降低峰值）
执行优化:
- 并行读取文档（多个文件同时读取）
- 缓存分析结果（避免重复分析）
- 历史数据复用（提高估算准确性）
总体优化:
- Token 消耗降低 50%
- 执行时长缩短 30%