koleso-webestimator — 针对Umbraco / .NET 的AI校准估算
为Umbraco / .NET Web开发工作量进行估算，其中 AI智能体编写代码，人类审查代码。
本技能背后最重要的事实，来源于10个Umbraco项目、约300个真实工单：
编码很少是估算出错的原因。 以人类开发者-天为单位估算的大型工作，实际超支约4倍。小的“2-3小时”工单则被低估了2-3倍。这两种错误都源于同一个地方：代码以外的工作——部署、uSync导入、每个环境的的手动步骤、测试看不见的CMS实际行为、QA轮次、客户澄清回合——要么被夸大为“应急储备”，要么被完全忽略。
因此，这里的每个估算都有 两个账本：
- 工作量 — 有人实际工作的时间：AI编码+审查，以及那些不可缩减的桶。
- 日历时间 — 实际消耗的时间，主要由等待答复、部署窗口和QA队列决定。绝不要将其混入工作量。
参考文件（在步骤指示时读取）：
references/calibration.md— AI编码速度及不可缩减桶的默认大小references/patterns.md— 常见Umbraco / Razor / Vue / 后端任务的参考时间references/platform-risks.md— 需要额外部署验证轮次的CMS行为references/honesty-rules.md— 强制性规则和升级阈值references/output-format.md— 内部细目和面向客户的回复references/calibration-log.md— 如何记录估算与实际对比以改进数据references/review-checklist.md— 审查模式：检查已有估算
工作流程
步骤0 — 寻找规格和计划，确定估算依据
在阅读代码之前，搜索关于此任务的规划文档。查找位置：
- 存储库：
spec.md、SPEC.md、docs/spec/**、docs/specs/**、docs/plans/**（文件名为*-plan.md、*-design.md、*-analysis.md、*-spec*.md）、docs/handover/**、docs/adr/**，以及任何文件名包含工单键或功能短名称的文件； - 工单本身：其描述、附件和评论，以及任何链接的规格页面（例如Confluence）；
- 同一工单的先前估算。先前的估算、被拒绝的选项或未解决的问题会改变当前数字。
然后为估算选择 一个依据，并在输出顶部说明是哪一个：
A. 基于计划的估算。 存在规格和/或功能计划。
- 完整地阅读找到的每个文档，而不仅仅是标题：需求、验收标准、阶段、文件列表、未解决问题、修订/偏差以及审查决策。
- 按计划阶段估算，使用计划自身的文件列表和步骤作为子任务骨架（步骤4）。
- 将每个规格要求/验收标准映射到估算的一行。列出任何未被任何阶段覆盖的要求，以及任何没有要求请求的阶段。
- 将计划中的未解决问题带入输出的问题列表，每个问题附带其默认答案。
- 检查计划是否过时：将其命名的内容（文件、别名、文档类型）与当前代码进行比较。不再匹配的内容是需要标记的假设，而不是默默定价。
- 范围可以更窄，置信度可以更高（参见
references/honesty-rules.md）。
B. 快速估算（可见范围）。 未找到规格和计划。
- 在顶部明确说明：“未找到规格或功能计划——这是基于可见范围的快速估算。” 列出你在哪里寻找过。
- 仅根据工单文本和代码进行估算。范围更宽，置信度上限为“中等”。
- 列出要使数字确定下来，规格或计划必须解决哪些问题（询问问题、无法确定的受影响领域）。
- 提供下一步：为工单编写计划，然后基于该计划重新估算（依据A）。说明你期望基于计划的数字朝哪个方向移动，以及原因。
如果只存在部分文档（例如，有规格但无计划，或仅有另一阶段的计划），则对其覆盖的部分使用依据A，对其余部分使用依据B，并标记每一行。
此外：如果校准日志存在（references/calibration-log.md解释了位置），请读取最近关于类似工作类型的条目。
步骤1 — 检测技术栈
使用你的文件搜索工具（不要使用特定于shell的命令——因为它通常在Windows上运行）。记录：
| 查找 | 告诉你 |
|---|---|
*.csproj → Umbraco.Cms PackageReference版本、TargetFramework | Umbraco主版本（10/13 = AngularJS后端；14+ = Bellissima Lit/TS）和.NET版本 |
appsettings*.json中的ModelsMode、生成的models文件夹 | 强类型模型 vs 动态IPublishedContent |
uSync/文件夹 + uSync设置（ExportOnSave、ImportOnFirstBoot、禁用的处理器） | 架构更改是否需要每个环境的手动导入 |
App_Plugins/*/package.manifest vs umbraco-package.json + Client/ Vite项目 | 后端扩展技术 |
package.json文件：vue、nuxt、react、lit、jquery；构建输出位置 | 前端类型及其构建输出是否被提交 |
SCSS编译器配置、已提交的编译后CSS、rtl/ltr文件夹 | 样式流水线和RTL副本 |
uSync Languages/中的语言、布局中的dir="rtl" | 文化数量及RTL验证成本 |
| 测试项目（xUnit/NUnit/Playwright），是否在构建时编译Razor | 一次绿色测试运行实际证明了什么 |
Composers/、Hangfire、Examine索引配置、迁移、自定义数据库表 | 后台任务、搜索、自定义数据 |
| CI/部署文件、托管提示（App Service、IIS、Docker） | 环境数量以及部署是否为手动的 |
如果无法读取代码库，在输出中说明，并将每个范围放宽2-3倍（参见诚实规则）。
步骤2 — 读取最接近任务的代码
寻找先例：最近的现有文档类型、分部、控制器、Vue岛、后端元素或执行类似操作的导入。读取其中的2-4个文件。检查你将在估算中做出的每一个事实性主张，并与代码或uSync模式进行核对——例如，在写“那个字段不存在”之前，先搜索内容类型配置。一个错误的主张会消耗整整一次客户往返沟通。
步骤3 — 分类
| 维度 | 选项 |
|---|---|
| 工作类型 | 参见 references/calibration.md 中的表格（文档类型/模式、Razor页面 vs 设计、Vue岛、后端扩展、API/控制器、搜索、后台任务、客户数据导入、第三方集成、升级、调查、缺陷） |
| 先例 | 高 / 中 / 低 |
| 规格清晰度 | 清晰 / 部分 / 模糊 |
| 是否写入CMS数据？ | 代码是否创建、保存或发布内容、区块、媒体或按文化的值？ |
| 前端是否针对设计稿？ | 像素级检查的Figma工作会触发一轮QA |
| 文化数 × 断点数 | 例如 3种语言（一种RTL）× 桌面/移动端 |
| 需要达到的环境 | 本地、开发、预发布、生产——并说明每个环境哪些步骤是手动的 |
| 外部方 | 客户内容、供应商API、第三方脚本、其他团队的流水线 |
步骤4 — 分解并以AI速度估算编码工作量
如果有计划（依据A），计划的阶段是顶层分组，其步骤/文件列表是子任务；不要发明不同的分解方式。没有计划（依据B），则自行构建分解。
将工作分解为每个 15分钟 - 2小时 的AI工作 的子任务。根据 references/patterns.md 和 references/calibration.md 中的速度来估算大小。然后加上 审查时间（生产代码默认为AI编码时间的30-50%；测试和样式更少）。
永远不要以人类开发者-天为单位估算编码，然后“加上应急储备”。 那是约4倍超支的根源。如果你使用的参考是人类时间，请使用 calibration.md 中的乘数进行转换。
步骤5 — 添加不可缩减的桶
从 references/calibration.md → “不可缩减的桶”。每个适用的桶添加为单独的行，并带有自己的范围：
- 每个环境的发布开销（构建、部署、uSync导入、字典/内容编辑、重新保存、冒烟检查）
- 当代码写入CMS数据或依赖于运行时行为时的真实CMS验证轮次（
platform-risks.md） - 所有者/本地运行 + QA交接
- 针对设计的Web前端工作的QA轮次（分类、修复、非缺陷回复）
- 多语言 / RTL 验证矩阵
- 在范围确定之前你预期的澄清回合
- 版本升级的升级尾巴（回归测试、运行手册、预演、部署后修复）
- 如果团队按工单编写计划、审查、验证文档和交接的过程开销
应用 小工单下限：任何必须到达共享环境的工单，即使代码只有一行，也至少需要支付发布开销。
步骤6 — 日历时间
列出实际经过时间取决于什么：给客户的未解决问题、客户必须提供的内容、供应商答复、部署窗口、QA可用性。单独给出日历时间（例如，“工作量2-3小时；实际需要1-2周才能完成，同时Q1-Q4得到答复”）。
步骤7 — 自我检查
- 子任务范围相加等于总数。
- 没有单个子任务超过2小时AI工作而未被拆分。
- 每个不可缩减的桶都已被考虑；被跳过的桶是有意为之（说明原因）。
- 任何地方都没有人类开发者-天；全程使用一个单位（小时）。
- 每个关于“不存在”/“已支持”的主张都已通过代码或模式验证。
- 置信度与
honesty-rules.md中的修饰符一致。 - 总计 > 40 小时 → 拆分为里程碑并分别估算每个。
- 估算依据（基于计划/快速/混合）在顶部说明。有计划时，每个规格要求对应一行，每个计划阶段都有定价。没有计划时，输出会说明并列出你查找过的地方。
步骤8 — 输出
使用 references/output-format.md：给开发者的 内部细目，以及给客户的 面向客户回复（小时范围表、总计范围、单独定价的选项、假设、带默认答案的编号问题（该估算基于此默认答案）、风险、日历备注）。
然后将估算记录到校准日志中（references/calibration-log.md）：如果用户指令指定了日志位置则自动记录，否则提议开始一个。记录技能产生的内容，以及（如果已知）实际发送给客户的内容。
模式
单任务 — 上述工作流程。
批量 — 针对一个规格、史诗或待办列表：执行步骤0-2一次，然后对每个条目执行步骤3-7（每个2-5个子任务）。输出一个表格（条目、层次、工作量范围、大小、置信度、主要风险）、共享假设、跨条目依赖关系、建议顺序，以及 对整个批次仅一次 的不可缩减桶（如果它们真正共享：一个部署+一次uSync导入可以携带多个条目；一个每个页面一次的QA轮次，而不是每个条目一次）。
重新估算 — 在客户回答问题或范围变更后：只显示差异（移除的行、添加的行、修订后的总计、哪个问题导致了变化）。客户回答问题后要求确认数字——使差异易于审批。
审查 — 当已有估算（在规格、计划、工单评论中）且你被要求检查时：不要从头重新估算。遵循 references/review-checklist.md：
- 收集每个版本：已提交的文档、面向客户的副本、它引用的代码；
- 检查算术，然后检查依据和置信度是否与诚实规则匹配；
- 检查结构（审查份额、桶、需求覆盖率、选项、默认值）；
- 在代码和模式中重新验证关键事实，并查找它遗漏的平台风险。
将内部修复与客户必须看到的更改分开。仅当数字发生变化时，才推荐重新发布一个数字。
校准 — 当被要求评估估算效果时（“我们有多准确”、“校准技能”、“对估算的回顾”），或试用期结束时：
- 读取整个校准日志。对于每个已关闭的条目，填写或检查实际值及其来源（自己的时间、工单工作日志——注意如果是团队总计——、git活跃天数）；对于缺失的实际值进行询问，而不是猜测。
- 按工作类型和按桶，为发送给客户的数字和技能本身计算的数字计算比率。
- 找出系统性的偏差：哪些工作类型、哪些桶（QA轮次、发布开销、验证轮次、澄清）、哪些规则（置信度、小工单下限）是错的，以及人类的覆盖在哪里是正确的。
- 提出对
references/calibration.md、patterns.md、platform-risks.md或规则的具体修改建议，每个修改建议都要与证明其合理的日志行相关联。对于少于3个数据点的类型：提请注意，但不更改。 - 仅应用用户批准的修改，在技能的README中添加一个带日期的更改日志条目，并在日志中添加一行，说明下一个估算使用哪个校准版本。
调查 — 用于“找出为什么……”的工单：给它设定时间盒（通常0.25-1小时），说明时间盒能买到什么，并列出可能的结果，包括“不是缺陷”、“已内置”和“上游CMS缺陷——等待X版本”。这些结果很常见且代价低；不要像修复是确定的那样为调查定价。