AI 编程项目如何估算各开发阶段的 Token 成本？

估算 AI 编程项目各开发阶段的 Token 成本，不能只把代码行数乘以模型单价。更实用的方法是先把项目拆成需求、架构、数据、核心代码、前端、测试、文档和发布八个阶段，再分别估算输入量、输出量、调用轮数与返工系数，最后输出 P10、P50 和 P90 三档预算。token-budget 项目提供了这套流程的 CLI、MCP Server 和 DeepSeek Harness 插件实现，但其阶段基准与修正系数属于启发式模型，使用前必须用团队自己的历史任务校准。

为什么按阶段估算比总量估算更可靠

不同阶段的 Token 结构并不相同。需求分析和架构设计通常需要读取较多业务资料并生成结构化说明；核心开发与前端实现包含更多代码输出；测试阶段会反复携带错误日志、源文件和修改历史；发布阶段的内容较少，但可能因环境问题产生多轮排查。把这些工作压成一个总调用次数，会掩盖真正的成本来源。

阶段化预算还能把预测与执行结果一一对应。项目结束后，可以知道是测试轮次超过预期、资料输入过大，还是半成品代码增加了排障成本，并只调整对应阶段的参数。

token-budget 的八阶段模型

项目的 plan-project-budget 工具把完整开发流程划分为八个阶段：需求分析与规格书、系统设计与架构、数据建模、核心代码生成、UI 与前端实现、测试与 QA、文档与本地化、发布与运维配置。每个阶段都有基准输入 Token、基准输出 Token 和默认调用轮数。

这些数字不是对任意项目的固定报价。它们更像一组可复用的起始参数：企划书、已有代码和项目资料会改变输入规模，项目完成度会减少尚待实现的工作，缺陷和技术债则会增加理解、修复与验证轮次。

预算层	用途	决策方式
P10	路径顺利、返工较少的低位估计	不应用作采购上限
P50	典型情况下的中位预算	用于日常排期和模型比较
P90	覆盖多数高成本运行的保守预算	用于资金预留和软限额

准备输入材料

估算前应明确企划书路径、已有代码目录和项目资料目录。企划书至少描述目标用户、核心功能、非功能要求、技术边界和验收条件。半成品项目应排除依赖缓存、构建产物、二进制资源和生成文件，否则文件统计会被无关内容放大。

项目资料并非越多越省。项目会检查 API Schema、数据字典、ER 图和 OpenAPI 等结构化信号，并对资料规模应用修正。其 README 还提示，长资料可能产生“中间信息难以检索”的问题。实际使用时应把资料质量和长度分别记录，不能用目录体积替代有效信息量。

运行项目预算估算

安装依赖后，可以从 CLI 对文本、目录或已知 Token 数做基础估算；需要完整阶段预算时，通过 Harness 或 MCP 调用 plan-project-budget。调用参数应显式给出企划书、代码和资料路径，并指定工作流与显示币种。

plan-project-budget({
  docPath: "./project/spec.md",
  codePath: "./project/app",
  materialPath: "./project/docs",
  workflow: "aider_loop",
  displayCurrency: "CNY"
})

如果只想比较一组已知用量，可以使用 estimate-cost；若要分析公开仓库，可使用 estimate-github-project。对私有仓库使用访问令牌时，应把令牌放入受控环境变量或凭据存储，不要写入提示、配置示例、日志或预算报告。

理解三个非线性修正

项目资料修正

结构清楚、与任务直接相关的资料可以减少探索轮次，但大量散文或互相矛盾的文档可能增加上下文成本。应抽样检查工具识别出的质量信号，并确认它们确实对应当前实现，而不是过期文档。

半成品完成度修正

已有测试、文档、界面和核心模块会减少从零生成的工作；但模型每轮仍可能读取现有代码。半成品并不总是线性节省，尤其在模块边界不清、依赖陈旧或实现与规格冲突时，理解和返工成本可能超过重写。

缺陷与技术债修正

工具会扫描 TODO、FIXME、HACK 和 XXX 等标记，并结合测试覆盖率调整预算。这只能作为风险信号。注释数量不能准确代表缺陷密度，低覆盖率也不等于代码一定不可维护，因此预算报告应保留修正来源并接受人工复核。

如何计算阶段费用

每个阶段先计算预计输入与输出 Token，再乘以模型相应单价；若供应商区分缓存写入、缓存读取和长上下文倍率，还要分别计价。一个简化表达是：

阶段费用 = 输入Token × 输入单价
         + 缓存读取Token × 缓存单价
         + 输出Token × 输出单价
总预算 = Σ阶段费用 × 风险系数

价格表很容易过期。项目提供 refresh-pricing 和 apply-pricing-update，但刷新结果仍应与供应商官方定价页核对，并记录币种、汇率、计价单位、缓存政策和生效日期。模型名称相同也可能因渠道和套餐不同而采用不同价格。

用真实项目校准预测

首次使用时，选择若干已完成且有用量记录的项目做回放。为每个阶段保存预测 P50、P90、实际输入、实际输出、调用轮数、缓存用量、费用和验收结果。若实际值频繁超过 P90，说明阶段基准、完成度判断或风险系数偏低。

1. 按项目类型分别建立基线，不混合网站、移动应用和大型迁移。
2. 固定模型、代理框架和上下文策略，避免一次改变多个变量。
3. 同时记录失败运行与重试，不能只统计成功的最后一次。
4. 按月检查预测覆盖率，并在模型、价格或工作流升级后重新校准。

预算应以“通过验收的项目”为单位。某个模型单次调用便宜，却需要更多修复和人工接管，最终项目成本可能更高。比较模型时至少同时观察成功率、P50 与 P90 成本、完成时间和返工次数。

把预测转成运行时控制

预测报告不是静态报价。可以把 P50 作为正常进度线，把 P90 设置为软限额，在达到阈值时要求 Agent 汇报已完成阶段、剩余任务和最新估算；再设置独立的服务端硬限额，防止无进展循环继续计费。

当需求范围扩大、测试环境不可用、关键依赖变更或半成品质量与扫描结果不符时，旧预算应立即失效。此时只估算剩余阶段，并保留原预测和变更原因，避免用事后调整掩盖首次估算误差。

结论

AI 编程项目的 Token 预算应按开发阶段、输入输出结构和返工风险拆分，而不是用文件大小或调用次数给出单一数字。token-budget 提供了八阶段估算、多模型价格比较以及半成品、资料和技术债修正，适合生成第一版 P10、P50、P90 预算。真正可靠的结果仍来自历史任务校准、官方价格核对和运行时软硬限额；把启发式报告当作可更新的预测模型，才能让它服务于排期和成本治理。