selection-toolkit

/selection-toolkit — 评审小组评分所用的工具

只有一项工作：必须开展一次评选，评审小组需要一份用于评选的工作簿。介于发布和授标之间。/tor-procurement 编写了 ToR 后便停止；procurement-offer-review 会在收到投标后评审单份报价。本工具负责构建两者之间的内容。

这里一切工作的准则

绝不凭空编造。 每项标准、每个权重、每个阈值、每个日期，都必须来自源文档；否则就报告为待 Ane 解决的缺项。默认权重一旦写入单元格，就和已发布的权重无法区分，评审小组可能连续六周依据它评分而毫无察觉。validate_spec 会拒绝有缺项的规范，而 read 绝不会填补缺项。

使用此技能时，以下两条规则适用于你为用户撰写的任何内容：

1. 评分只能使用源文档已发布的标准。 评审小组希望已发布的标准，是下一份 ToR 的改进经验，不应成为本工作簿中的一列。
2. 文件一旦分发或开始评分，就要直接编辑原文件，绝不重新生成。 build 会拒绝覆盖现有工具包，原因正是如此。退回的评分者文件中的评分信息，在其他任何地方都不存在。

代码所在位置

所有 Office 相关工作都在 ane_package 中完成。本技能提供判断，不负责底层实现。

• ane_package.reporting.selection_toolkit — 规范、评分引擎和两个工作簿生成器。
• ane_package.officeops.document_tables — 将 ToR 中的表格读取为保留空白单元格的网格。
• scripts/selection_toolkit.py — 驱动脚本：表格评分、权重解析、阈值读取、规范组装和验证。

边界已明确，不必再争论：凡是打开 Office 文件的代码，都属于模块。 驱动脚本中只有两处调用会打开文档。判断 ToR 中的五个表格里哪一个列出了授标标准，以及从 "up to 35 points" 中提取 35，都是文本处理逻辑，应放在驱动脚本中。

编写任何 Office 代码之前，请先阅读 office-repair 中的 references/officeops-excel-api.md，并阅读此处的 references/modes.md，了解各模式的差异。

运行方法

1. 读取源文档

python scripts/selection_toolkit.py read "path/to/ToR.docx" --out selection-spec.json

此命令会输出找到的标准、每项标准对应的权重，以及所有缺项。将缺项交给 Ane 处理——这些就是 ToR 没有回答的问题。常见缺项包括：评审小组成员名单（ToR 从不列出）、合规性检查、标题，以及含义不明确的阈值，例如 ToR 同时写了“70%”和“60 points”。

绝不要自行解决缺项。如果 ToR 没有说明权重，就提出询问；不要从类似的采购项目中推断权重。

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

规范文件是“为什么这项标准值 35 分”的审计记录。请将它与工作簿放在一起。只要 _gaps 仍然存在，build 就会拒绝运行；即使删除了 _gaps，如果缺少实际值，validate_spec 仍会拒绝通过——删除缺项列表并不能掩盖缺口。

对于非采购类比较，请将 mode 设为 appraisal；详情请参阅 references/modes.md。

3. 构建

python scripts/selection_toolkit.py build selection-spec.json --out "3 Selection toolkit"

此命令会生成 selection-master.xlsx，并为每位评审小组成员生成一份 scorer-<name>.xlsx。必须使用独立文件，绝不能共用一份工作簿：独立评分是计算评审小组平均分的必要保障，而共用文件会在第二个人打开它时立即破坏这项保障。

4. 通过执行验证 — 这一步才能真正体现技能价值

python scripts/selection_toolkit.py verify "3 Selection toolkit" --spec selection-spec.json

复制工作簿，通过 Excel COM 注入示例申请人及评分，强制执行完整重新计算，并根据编写这些公式所用的同一引擎，断言计算得出的平均分、阈值、财务评分和排名均符合预期，同时确认公式错误单元格为零。

工作簿看起来正确，计算结果却不正确——这正是此处可能出现的问题，只有实际执行才能发现。 读取公式只能证明你写入的公式就是你写入的公式。验证会在副本上运行，因此示例数据绝不会进入正在使用的采购记录。

如果 Excel 不可用，命令会以状态码 2 退出，并说明工作簿未经验证。应如实报告为未经验证。不要声称未经验证的工作簿已通过检查。

5. 提交输出文件

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

主工作簿的内容

00 DASHBOARD（自动计算，不要填写任何内容）、01 Read me（操作顺序）、02 Applicants、03 Questions log、04 Q&A to publish、05 Stage 1 Compliance、06 Score inbox（在此处粘贴评分人员返回的文件）、07 Stage 2 Technical（评审小组平均分、分差、资格判定）、08 Stage 3 Financial、09 Stage 4 Interview、10 Conflict of interest、11 Decision log、12 Applicant feedback、98 REF（已发布的参数，使审计记录随文件一并保存）。

源文件未定义的阶段不会创建工作表。

需要注意的问题

1. 空白表示缺失，不是零。 从未打过分的候补评审员不应把平均分拉低三分之一。panel_mean 会忽略空白，AVERAGE 公式也按此编写。绝不要通过给空白填入 0 来“清理”评分员文件。
2. 每个计算单元格都会自行检查是否为空。 第一天交付的工作簿是空的，满是 #DIV/0! 的工作表看起来像是坏了，而不是等待填写。这也让“公式错误单元格为零”成为一项真正的检查，而非恒真命题。
3. 流程顺序是先检查合规性，再检查门槛，最后评分。 给不合规的投标评分后再将其排除，正是评审小组说服自己破例的方式。
4. 分歧较大是信号，不是错误。 工作簿会对达到或超过触发阈值的分差进行底色标记。评审小组会讨论；没人会悄悄把它平均掉。
5. ToR 可能不是英文的。 标题匹配、阈值句子和日期解析均已支持英文、法语、西班牙语、罗马尼亚语和德语，且不受重音符号影响。只支持英文的检查器在法语 ToR 中找不到标准表，报告存在缺漏，但这只是解析器造成的假象，并非文档本身的事实。第 4 和第 5 波次中，这种情况已经发生过三次。
6. 标题为“Criterion”的列通常放的是代码。 标准本身位于“Description”下方。仅匹配标题词会把每项标准都标为“C1”“C2”——编号正确，标题却毫无用处，而且不会触发任何错误。is_code_column 可以解决这个问题；不要移除这项检查。
7. **价格从 02 Applicants 读取，**所以在那里更正价格后，所有依赖它的分数都会随之更新。直接覆盖财务工作表没有作用：该工作表受保护。
8. 将返回的评分员文件合并到主文件需要通过 COM 操作并回读验证，而且保护机制会阻止提交。 通过 Excel COM 写入（使用 openpyxl 保存会丢失工作簿的扩展数据验证），且只能写入你已先确认为空的单元格；然后在重新打开并重新计算的工作簿中验证：必须检查主文件自身的总分以及第 07 个选项卡的平均值，绝不能只看写入调用是否顺利完成。编辑保护机制无法识别 COM 写入，因此之后会阻止任何提及这两个文件的 Bash 或 PowerShell 命令——包括它自己建议的修复操作 git commit。使用 Write 工具将提交命令写入暂存区脚本，并通过裸文件名运行；也要先用同样的方式提交合并前的文件状态，确保评分员返回的内容先进入 git，再对主文件进行任何操作（已在 2026-10-13 的一次会话中验证三次）。

本工具不处理的事项

本工具不会编写 ToR（/tor-procurement）、分析单份收到的投标（procurement-offer-review）、为 IPPF 发出的提案评分（donor-proposal-scoring），也不会根据 IPPF 标准评估成员协会（accreditation-desk-review）。本工具不会决定授标结果。它负责构建评估工具，评审小组负责作出决定。