cost-estimate

此技能是一套以证据为依据的估算工作流。

不可妥协的规则：

1. 使用 .agents/skills/cost-estimate/helpers/ 下的辅助脚本，不要手动重新计算代码行数、会话或成本。
2. 明确范围：整个仓库、branch:<name> 或 commit:<hash>。
3. 将原始工程工时与组织开销和团队乘数分开。
4. 将定价标准和报告架构保留在参考资料中，不要内联到调用流程中。
5. 外部市场费率调研是可选的。除非用户明确要求其他市场或地区，否则使用内置费率。

成本估算

输入

• $request：可选的范围或估算指导，例如 branch:feat/foo、commit:abc1234、地区提示或目标受众

目标

生成可信的估算，以便：

• 使用辅助脚本衡量请求的代码范围
• 将代码归类到恰当的生产力类别
• 计算工程工时和成本，避免重复计算开销
• 将估算转换为切实可行的日历和团队成本视图
• 清晰报告假设、置信度和 Claude ROI

步骤 0：确定范围和模式

将请求解析为以下其中一项：

• 整个仓库
• branch:<name>
• commit:<hash>

如果请求含糊不清，默认推断为整个仓库。如果用户提供了地区或市场提示，将其纳入最终的费率讨论。否则，使用内置基准费率。

成功标准：运行脚本前，明确估算目标和定价依据。

步骤 1：使用辅助脚本衡量实际代码范围

使用 .agents/skills/cost-estimate/helpers/ 中的辅助工具链：

• loc_counter.py
• git_session_analyzer.py
• cost_calculator.py
• report_generator.py

针对已确定的范围运行 loc_counter.py，以获取：

• 总行数
• 文件数量
• 语言明细
• 目录明细
• 源代码、测试、配置和文档的分类
• 来自 all_files 的逐文件类别候选项

在 Git 历史可用时运行 git_session_analyzer.py，以便 Claude ROI 使用实际会话估算，而非基于代码行数的回退估算。

规则：

• 优先采用脚本输出，而非临时使用 find、wc 或内联算术
• 如果范围是分支或提交，衡量差异，而非整个仓库
• 如果 Git 历史缺失或无助于分析，之后改用基于代码行数的 Claude 工时估算

成功标准：获得范围大小的结构化 JSON，以及在可能时获得活跃会话估算。

步骤 2：将代码归入生产力类别

检查 loc_counter.py 的输出，并将每一行相关源代码归入且仅归入一个类别。

使用 references/estimation-rates.md 获取：

• 类别键
• 生产力范围
• 开销范围
• 市场费率基准
• 角色乘数
• 组织效率常数
• Claude ROI 常数

分类规则：

• 每行源代码只分配一次
• 将测试、配置/构建和文档与产品代码分开
• 识别 GPU、本机互操作、音视频、系统扩展或设备端 ML 等专业工作
• 没有文件级证据时，不要夸大复杂度
• 如果某个目录中的文件显然属于同一类别，可将其归为一组，但应单独说明例外文件

成功标准：生成完整的类别到代码行数的 JSON 数据，供计算器使用。

第 3 步：运行计算器并检查结果是否合理

将各类别的总量传入 cost_calculator.py。

计算器应生成：

• 基础编码工时
• 开销工时
• 预计总工时
• 合理性检查：每小时有效代码行数
• 日历时间表
• 仅工程团队成本
• 全团队成本
• Claude 工时可用时的 Claude ROI 字段

规则：

• 不要将开销计入类别分配；计算器会自动添加开销
• 如果合理性检查结果超出目标范围，请调整类别分配，或说明该仓库为何确实偏离常规
• 默认使用内置市场费率，除非用户明确要求采用其他市场基准

成功标准：计算器输出内部一致，且已检查合理性。

第 4 步：完善 Claude ROI 和置信度

如果存在会话数据，请检查并仅在默认的提交密度启发式明显低估大范围工作时进行调整。如果缺少会话数据，请使用 references/estimation-rates.md 中的 Claude 生产力备用常数。

报告：

• 预计 Claude 活跃工时
• 相对于人类基准费率的速度倍数
• 每 Claude 工时的价值
• 概括性 ROI 和节省金额

同时说明置信度：

• 范围、类别构成和历史数据清晰时为高
• 历史数据或分类不完整时为中
• 请求有意要求近似估算，或仓库内容仅部分可用时为低

成功标准：ROI 说明清楚、范围明确，且不过度夸大。

第 5 步：生成报告正文

使用 report_generator.py 生成 Markdown 框架，然后根据需要完善说明文字。

加载 references/report-contract.md，了解报告的必需结构和最低章节要求。

最终估算应涵盖：

• 执行摘要
• 代码库指标
• 开发时间估算
• 日历时间视图
• 仅工程团队成本
• 全团队成本
• Claude ROI
• 假设和注意事项

规则：

• 开篇呈现执行摘要和 Claude ROI
• 报告应便于利益相关方阅读，避免过多罗列工具输出
• 明确说明范围依据
• 手动编辑说明文字时，保留转义后的货币格式

成功标准：估算内容易读、结构清晰，并符合报告契约。

防护要求

• 不要添加 disable-model-invocation；这是一个以读取分析为主的工作流。
• 不要添加 paths:；这是一个通用估算技能。
• 不要在 SKILL.md 中内嵌价格表、角色矩阵或完整报告模板。
• 除非辅助脚本链不可用，否则不要用手动计算替代辅助脚本输出。
• 不要在未说明范围、假设和置信度的情况下给出成本数字。
• 除非用户明确要求，且确实进行了相关调研，否则不要声称已针对特定地区的市场进行了验证。

何时加载参考资料

• references/estimation-rates.md 用于查看生产力分档、开销费率、市场费率基准、团队乘数、效率常数和 Claude ROI 备用常数。

• references/report-contract.md 用于查看强制章节顺序、报告契约和必需的注意事项。

辅助脚本

• .agents/skills/cost-estimate/helpers/loc_counter.py

  • 整个仓库：不带标志
  • 分支差异：--branch <name>（可选 --base <base>）
  • 单个提交：--commit <hash>
  • 输出：包含 totals、by_language、by_directory、all_files 的 JSON

• .agents/skills/cost-estimate/helpers/git_session_analyzer.py

  • 所有提交：不带标志
  • 指定分支：--branch <name>
  • 输出：包含 total_commits、total_sessions、estimated_active_hours、sessions[] 的 JSON

• .agents/skills/cost-estimate/helpers/cost_calculator.py

  • 输入：通过 stdin 管道传入类别 JSON
  • 标志：--rate <hourly>、--claude-hours <N>
  • 有效类别键：simple_crud_ui_boilerplate、standard_views、complex_ui、business_logic、database_persistence、audio_video_processing、gpu_shader、native_interop、system_extensions、on_device_ml、tests、config_build、documentation
  • 输出：包含 base_coding、overhead、total_estimated_hours、sanity_check、calendar_time、engineering_cost、team_costs、claude_roi 的 JSON

• .agents/skills/cost-estimate/helpers/report_generator.py

  • 标志：--calc <costs.json>、--sessions <sessions.json>、--project <name>、--scope <desc>
  • 单个部分：--section <name>
  • 可用部分：executive_summary、development_time、calendar_time、engineering_cost、team_cost、grand_total、claude_roi、assumptions
  • 输出：可直接粘贴的 Markdown

请直接使用这些脚本。此技能中的判断工作是分类、校准和说明，而非重新实现这些脚本。

输出约定

报告：

1. 已确定的范围和定价依据
2. 关键仓库指标和复杂度驱动因素
3. 工程工时和合理性检查结果
4. 仅工程成本和团队成本范围
5. Claude ROI 和置信度
6. 假设、注意事项和任何数据缺失限制