contract-delivery-kickoff

/contract-delivery-kickoff — 决定上限的会议

只有一项任务：合同已签署，工作即将开始，首次会议决定如何花掉固定天数。/tor-procurement 编写了 ToR，selection-toolkit 完成了授标。以下是签署之后的流程。

为什么要有它

交付合同不会突然失败，而是逐渐偏离计划。首次会议逐项审阅问题清单，对每项合理建议都表示同意；到了第五个月，最后一笔款项已经没有剩余天数，超支才浮现出来。参考案例是 2026 年 6 月 12 日的 Abortion Dashboard Phase II 会议：针对 14 个合同组件，共有 9 个技术工作日和 4 个协调工作日，全程手动完成。

因此，交付成果就是算术。 准备简报和议程，是让算术进入会议室的方式。如果你制作了漂亮的文档，却没有天数预算，那你什么也没做成。

这里一切工作的原则

绝不编造。 每个合同天数、每个费率、每笔款项都必须来自合同；若有缺项，就报告给 Ane 解决。从类似合同中读出的日费率，一旦填进单元格，就和真实费率毫无区别，会议也会据此承诺支出。read 绝不会填补缺项；只要 _gaps 仍然存在，build 就会拒绝；之后 validate_spec 也会拒绝真实缺项，因此删除缺项列表也无法蒙混过关。

这里体现的五个步骤

这五个步骤都已在 2026 年 6 月 12 日的会议上得到验证。它们不是风格偏好；每一步都能杜绝会议出问题的一种情况。

1. 将每个事项划分到不同工作线。 客户负责的内容（最终文本、标签、定义、文件）一旦交付给供应商，几乎不会增加供应商的工作量。构建工作需要天数，而天数很少。划分工作线通常是会议这一小时内最省力的范围优化方式。
2. 在逐项审阅之前先商定上限。 因此，工作簿将 01 Day budget 放在 02 Triage 之前，这与手工制作的版本顺序相反。先看完一份列有 14 个合理事项的清单，才回答“9 天能做完哪些”，那么判断依据就会是清单，而不是合同。
3. 首次会议上为每一笔款项询问估算值，而不只是询问当前要启动的那笔。没有估算值不代表没有成本。工作簿会在原本应填零的地方写上 not priced，引擎则将其保留为 None，避免它隐藏在总数中。
4. 先明确受保护的事项。 不造成伤害、影响公信力或合规方面的缺陷，即使超出上限也必须修复；它们不应与其他事项争夺预算。在开始权衡之前先说明这一点，就能避免有人提议牺牲这些事项。
5. 先检查签署状态。 合同未签署意味着无法承诺任何支出，通常也意味着第一个合同交付物已经逾期。validate_spec 会拒绝签署状态未知的规范，因此无法通过遗漏来跳过此项。

代码所在位置

所有 Office 操作都在 ane_package 中完成。此技能提供判断，不负责基础设施。

• ane_package.reporting.delivery_kickoff — 规范、天数预算引擎、工作簿构建器。
• ane_package.reporting.markdown_docx — 将 Markdown 产物渲染为品牌化 Word 文档。
• ane_package.officeops.extract — document_tables 将合同预算表读取为保留空白单元格的网格；extract_text 读取正文。
• scripts/contract_kickoff.py — 驱动脚本：预算表检测、数字解析、签署状态读取、规范组装、产物文本、验证。

划清边界，以免反复争论：任何打开 Office 文件的操作都属于模块。 驱动脚本中只有一个函数会打开文档，即 load_document；测试会断言它始终只有这一个。下游所有环节都接收对象，因此无需任何 .docx 测试文件，即可测试整个解析器。

编写任何 Office 代码前，请先阅读 office-repair 中的 references/officeops-excel-api.md，并阅读此处的 references/session-moves.md，了解如何安排这一个小时。

运行方式

1. 阅读合同

python scripts/contract_kickoff.py read "Agreed offer.docx" \
    --supplier "Supplier A" --contract "Phase II delivery" \
    --out kickoff-spec.json

会打印出找到的合同角色、阶段、候选事项和所有缺口。把这些缺口带去和 Ane 讨论。最常见的缺口如下，按出现频率排序：

• 签署状态。 报价几乎从不说明是否已由对方签署。这个缺口几乎必然存在；这是第 5 步发挥作用，并非解析器出错。
• 每个阶段的天数分配。 合同会列出阶段，却很少分别为各阶段定价。这是第一次会议要讨论的问题。
• 每个事项的泳道和严重程度。 解析器无法判断内容属于客户端还是供应商构建；如果某个事项被错误标记为 Client, content，它就会被误认为免费，但实际并非如此。这些信息要和 Ane 一起确定，绝不可猜测。

2. 与 Ane 一起填写规格，然后删除 _gaps

规格文件是“为什么这份合同需要 9 天”的审计记录。请将它与资料包放在一起。

3. 构建

python scripts/contract_kickoff.py build kickoff-spec.json --out "Session 1"

会生成工作簿，以及 PREP-brief.md、AGENDA-to-supplier.md 和 NOTE-template.md，并将它们分别渲染为品牌化的 Word 文档。**Markdown 是权威版本。**编辑 .md 并重新运行；绝不要编辑 .docx 后指望修改能在重新构建后保留。

build 还会将合同自身的提案输入引擎运行，并报告它是否符合合同上限。合同提案要求 10 天，而已购买的天数只有 9 天，这是无法通过任何会议协商消除的问题。在起草议程时发现这一点，远比在会议现场发现要省事得多。

build 不会覆盖现有工作簿。一旦工作簿在会议中使用，其中的估算和决策便不会在其他地方留有记录。

4. 通过执行进行验证

python scripts/contract_kickoff.py verify "Session 1" --spec kickoff-spec.json

会复制工作簿，通过 Excel COM 注入示例天数，强制进行完整重新计算，并根据生成公式时使用的同一 Python 引擎，检查 Excel 得出的数值，同时确认公式错误单元格为零。

**工作簿看起来正确，但计算结果错误，是此处需要防范的故障模式。**读取公式只能证明你写入的公式确实是你写入的公式。验证在副本上运行，因此示例数据绝不会写入正式合同记录。

如果 Excel 不可用，该命令会以 2 退出，并说明工作簿尚未验证。应报告为未经验证。切勿将未经验证的工作簿说成已经检查过。

5. 提交输出文件

编辑保留保护机制无法识别 Excel COM 或 openpyxl 写入，因此会将生成的文件标记为手动编辑。请将它们作为最后一步提交，而不要让它们处于未提交状态。

工作簿内容

00 Guide（先列签署状态，然后说明如何安排这一小时，最后介绍严重程度和泳道的词汇），01 Day budget（按角色列出：阶段、提案天数与商定天数、小时数、占比、金额，之后是总计、合同天数和剩余天数；泳道拆分会根据分流表实时计算），02 Triage（每个候选事项占一行，会话中需填写的列会以底色标示），03 Decision log，98 REF（合同参数，让审计记录随文件一同保存）。

容易踩的坑

1. **合同使用了另一种语言。**预算表标题、费率用词和签字措辞会在英语、法语、西班牙语、罗马尼亚语和德语中进行忽略重音的匹配。仅支持英语的检查器在法语报价中找不到预算表，于是报告一个缺项；这反映的是解析器的问题，而不是文档的问题。连续三轮都遇到了这个问题。
2. **在上述五种语言中，有四种会将 1.234 读作一千二百三十四。**若将它读作 1.234，日费率就会变成零花钱，整个预算也会悄无声息地变得毫无意义。parse_number 会根据实际出现的分隔符推断数字格式，而不是自行假设。
3. **总计行不是资源明细。**把它当作资源明细来读会使签约天数翻倍，而得出的上限宽裕到让预算超支永远无从察觉。
4. **None 和 0.0 表示的天数并不相同。**一项无人报价的分项与报价为零的分项，在总计中无法区分，而前者才是导致合同出问题的原因。引擎会保留 None；工作簿则写入 not priced。
5. **预算仍有结余时，预警就会触发。**如果某个类别的约定天数超过合同自身提议天数的 1.5 倍以上，就会发出信号，即使总额仍低于上限也不例外。只有超出限制后才发出信号的约束，预警得太迟；本技能正是为避免这个问题而存在。
6. **议程会发给供应商。**签字预警、受保护事项清单，以及 Ane 对合同薄弱之处的判断，都应留在准备简报中。测试会断言这些内容不会泄露。
7. **先询问对方的估价，再说出你的期望。**先说出预期结果会锚定数字，而这个被锚定的数字随后会成为整个预算的基础。

本工具不负责的事项

本工具不会编写 ToR（/tor-procurement）、运行评审小组（selection-toolkit）、分析单份收到的报价（procurement-offer-review），也不会跟踪 IPPF 收到的捐助方拨款（implementation-pack）。它不会在第一场会议之后管理合同，也不会决定哪些内容超出范围。它负责构建工具并进行计算；由 Ane 和供应商作出决定。