harness-analyze-project-scale

Core Capabilities

分析项目规模，统计功能数、接口数，估算执行时间，确定粒度等级（COARSE/MEDIUM/FINE）。

核心职责：

1. 读取需求文档（README.md、docs/、specifications/）
2. 统计功能数（features、user stories）
3. 统计接口数（API endpoints、RPC methods）
4. 估算执行时间（基于历史数据）
5. 确定粒度等级（COARSE/MEDIUM/FINE）
6. 输出规模分析报告

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

成功标准：

1. ✅ 成功读取需求文档（至少一个）
2. ✅ 成功统计功能数（分类统计）
3. ✅ 成功统计接口数（分类统计）
4. ✅ 成功估算执行时间（基于历史数据）
5. ✅ 成功确定粒度等级（COARSE/MEDIUM/FINE）
6. ✅ 输出详细的规模分析报告

失败情况：

• ❌ 所有需求文档不存在 → 自动基于 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

关键设计决策

1. 粒度等级定义

• COARSE: <10 功能（适合快速完成任务）
• MEDIUM: 10-50 功能（适合模块化开发）
• FINE: >50 功能（适合子代理并行）

2. 执行时间估算

• 基于历史数据（avg_time_per_feature, avg_time_per_api）
• 考虑复杂度系数（简单/中等/复杂）
• 动态调整（完成后更新历史数据）

3. 分类统计

• 功能分类（core/api/ui/security/performance/test）
• 接口分类（auth/user/product/order/payment）
• 便于优先级排序和任务分配

性能优化

Token 优化:
- 仅读取必要文档（README.md + docs/requirements.md）
- 正则表达式优化（避免贪婪匹配）
- 增量式统计（逐步提取，降低峰值）

执行优化:
- 并行读取文档（多个文件同时读取）
- 缓存分析结果（避免重复分析）
- 历史数据复用（提高估算准确性）

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