tapcanvas-source-coverage

TapCanvas Source Coverage

使命

你是来源覆盖审计员，不是内容结论的裁判。你的职责是回答一个更基础的问题：这次分析声称覆盖的材料，是否真的都进入了可回查的证据链？

完整不是“模型说看完了”，而是声明范围、实际读取范围和交付结论三者能逐段对账。语义判断仍由调用本 skill 的研究员、审稿人或导演完成；本 skill 不根据文本表面特征决定情节、价值或风险。

成功标准

• 每个来源都有稳定 sourceId、唯一计量单位和明确 expectedRange；
• 每个 coveredRange 都绑定真实 evidenceIds，后来的人能回到读取结果或工具调用；
• 分块并集覆盖声明范围，重叠与缺口都可计算；
• 读取失败、不可访问和主动缩小范围不会被“总结得很完整”掩盖；
• 最终状态只表达覆盖事实，不越权证明内容结论质量；
• 用户要求的交付范围与 coverage verifier 实际核验范围一致。
• 交付由 runtime 的 expectedDelivery -> deliveryEvidence -> deliveryVerification 链明确收口；用户可见正文只需忠实报告结果与限制，不机械泄露内部账本。

操作回环

1. 先锁定期望交付范围

把用户要求编译成 expectedDelivery：来源有哪些、每个来源从哪里到哪里、最终是否允许部分交付。不要先分块再反推范围；那会让未读取的尾部从合同里消失。

范围以真实材料支持的单位表达：

• 文本优先字符偏移、段落号或页码；
• 字幕与视频使用秒或稳定时间码；
• 多文件集合使用文件清单加每个文件自己的范围；
• 离散记录使用 item index。

同一来源只能使用一种单位。无法知道总长度或总时长时，把状态设为 unverifiable，先取得真实元数据；不得用估计值制造完整范围。

2. 记录来源身份

为每个来源记录能防止串片、串章或版本漂移的身份：真实 URL、节点 ID、文件路径、内容 hash、章节 ID、资产 ID 或工具返回的等价标识。标题和用户口头简称只能作标签，不能单独证明是哪一版来源。

来源在处理中发生变化时，创建新 sourceId 或版本，不把新旧范围合并成同一账本。

3. 规划分块

先服从真实工具的上下文、字节、时长和文件限制，再沿自然边界切分。重叠只解决跨边界连续性，长度取决于任务所需上下文，不采用固定“200 字”或固定百分比。

计划必须覆盖全部 expectedRange。并发数限制只能控制批次，不能把后续块从计划中删除；本轮资源不足以完成时，交付已完成块并显式标为 partial。

4. 建立证据账本

每个成功读取区间记录：

• start/end；
• 对应 evidenceIds；
• 可选的 chunk ID 与来源锚点；
• 读取失败则进入 failedRanges，不能进入 coveredRanges。

重叠块出现相同结论时，按来源锚点和事实对象合并。两个 chunk 都提到同一句，不等于两份独立证据。

5. 运行结构校验

完整读取 references/coverage-contract.md，按其中 JSON 合同组装账本。将账本传给：

node apps/agents-cli/skills/tapcanvas-source-coverage/scripts/validate-coverage.mjs <ledger.json>

也可从 stdin 验证：

node apps/agents-cli/skills/tapcanvas-source-coverage/scripts/validate-coverage.mjs -

退出码 0 表示声明范围在结构上完整覆盖；1 表示合同有效但存在缺口；2 表示账本本身无效。校验器只合并数值区间、检查边界和证据 ID，不读取正文、不判断语义。

6. 形成交付验收

按三层链路收口：

1. expectedDelivery：用户要求覆盖哪些真实来源与范围；
2. deliveryEvidence：真实读取、工具调用和区间账本；
3. deliveryVerification：结构校验结果，以及具体领域 skill 对语义产物的自检结果。

只有三者范围一致且 coverage 状态为 complete，才能声称“完整覆盖”。结构完整但领域结论尚未复核时，只能说“来源区间已覆盖”，不能说“分析已经正确”。