【Agent开发实习小记】：让文档成为证据：来源盘点、引文校验与能力完整性评估

从“我读过这些材料”走向“这条结论由哪份材料中的哪句话支撑”。以下内容如有侵权及时告知作者若有误、纰漏之处可评论反馈。欢迎自由交流讨论摘要上一篇讨论了第三方 API 能力验证中的现实痛点资料分散、版本差异和执行副作用会让“接口有响应”与“能力已经被可靠证明”之间出现距离。要缩短这段距离第一步不是立即发起请求而是先回答我们实际读取了哪些材料它们分别能够证明什么本文介绍如何将 Markdown、PDF、文本说明和验收范围整理为inventory再由可核验引文派生claim、能力矩阵、问题清单和完整性结论。文中的文件名、引文、字段和值均为虚构示例不对应任何真实服务或运行记录。一、现实痛点读过文档仍然说不清依据“文档已经看过了”是一种工作状态却不是可以交接的证据。实际评估中快速开始、字段表、示例代码和版本记录经常由不同人员分别阅读最终虽然整理出了一张功能表却很难回答某条结论来自哪份材料、哪一页或哪几行相关内容是规范性说明还是只在某个示例中出现多个版本描述不一致时为什么采用其中一个说法PDF 中的表格、脚注或图片是否在文本提取时丢失“文档没有提到”是完整搜索后的判断还是阅读时没有注意到如果这些问题没有答案后续测试计划就容易建立在个人记忆或隐含假设上。测试失败后也很难判断问题来自目标 API、文档矛盾还是最初的理解就缺少证据。因此静态评估的产物不应只是摘要而应是一份能够被复核的证据账本。二、inventory先确认“看到了什么”2.1 文本提取不等于完整阅读API 能力可能分散在快速开始、字段表、错误说明、版本记录和示例中。PDF 还可能将关键限制放在表格、脚注、流程图或扫描页里。提取工具可以建立可搜索语料但不能自动证明以下内容没有丢失表格列顺序和跨页字段是否正确脚注、图片标注和代码符号是否完整扫描页是否只有图片而没有文本页面阅读顺序是否被破坏文件是否存在乱码、截断或替换字符。因此提取语料只是引用校验的基础。对于无法确认的内容应保留unknown而不是根据常见 API 设计补齐。2.2 inventory 需要记录什么inventory为每份用户提供的来源建立稳定记录通常包括来源 ID例如S-001用户提供的相对路径或来源标识文件类型可读取时计算的 SHA-256提取是否完整提取语料corpus的位置需要人工复核的诊断信息。即使文件不可读或提取不完整也应进入 inventory。直接忽略会制造“所有资料都已审查”的错觉明确记录则可以说明受影响的结论以及下一步需要补充什么材料。2.3 哈希和来源指纹的作用哈希不是文档摘要也不评价内容质量。它用于把评估绑定到当时读取的文件版本。在这一工作流中source_fingerprint由完整sources数组的规范化 JSON 计算。来源内容或元数据发生变化后旧 assessment 和测试计划都需要重新复核不能只凭相同文件名继续复用。三、多份材料如何交叉核对3.1 来源优先级必须局部判断多个来源讨论同一主题时可以按以下顺序判断用户明确给出的验收范围针对同一接口和上下文的规范性说明能够核验更新时间且确实更新的来源。这个优先级只对当前主题有效。某份材料在字段定义上更权威不代表它自动覆盖其他材料中的错误、清理或费用说明。被选为优先来源也不能抹去旧材料中的差异和矛盾。如果版本关系或适用范围无法确认应记录为unknown而不是猜测哪一份“应该更新”。3.2 示例只能证明自身上下文假设虚构材料中只有以下示例{variant:model-a,input_type:text,quality:standard}它能证明示例使用了这一组参数但不能证明所有 variant 都支持standardmodel-a支持所有输入类型这些参数可以拆开并重新组合到其他场景。示例不是参数池。没有匹配上下文的证据时应限制结论范围并在后续计划中记录参数选择理由。四、证据账本让结论能够回到原文4.1 最小证据结构一条证据可以抽象为{id:E-001,source_id:S-001,locator:第 6 页表 2,quote:任务接口返回 task_id。,interpretation:该引文说明创建响应包含任务标识。,strength:direct}字段职责应保持清晰quote来源中的短文本不混入总结locator页码、行号、表格或章节位置interpretation这段引文能够证明的最小事实strength证据强度。证据强度分为三类强度含义direct规范性文字直接支持该事实example-only只在特定示例上下文中出现inferred由多条已引用事实推导必须保持推断身份4.2 为什么解释不能写进 quote如果原文只写了“示例使用 model-a”就不能把 quote 改写成“所有模型均支持”。原文没有说过的话不能伪装成引文。合理写法是保留原句并在 interpretation 中说明它只能证明当前示例。这样既保留了证据价值也明确限制了推断范围。4.3 引文校验的基本检查assessment 输出前至少应确认每个source_id都存在于 inventory每个 quote 都能在原文或 corpus 中找到locator、引文和解释没有错位每条重要结论都有证据或者明确标记为未知。空白和 Unicode 可以按照统一规则规范化但不能借机替换关键词、补写句子或修正文档内容。五、从证据派生 claim、能力矩阵和问题清单5.1 claim 是最小可证明事实claim应具体到能够被证据支撑也能够被后续测试验证。例如“支持异步任务”过于宽泛可以拆成创建响应是否返回任务标识查询接口是否描述状态字段和终态成功终态是否描述结果位置失败终态是否包含错误信息是否存在取消、删除或其他清理契约。每个 claim 应记录状态、证据 ID、是否可测试及原因。合法状态包括supported、partial、unsupported、contradictory和unknown。5.2 能力矩阵负责防止漏项能力矩阵不是通用 API 检查表而是从当前验收范围和已声明功能链中派生。一个抽象的异步能力矩阵可以是能力维度文档状态对后续验证的影响authsupported可以设计受控请求但仍需 live 证据createsupported需要断言任务 ID不能只检查状态码query/statuspartial需要补充终态或轮询边界resultunknown不能声称生命周期已经闭合cleanupunknown写入或持久资源风险需要单独处理它的目的不是给目标 API 打分而是暴露认证、请求、响应、生命周期、结果、错误和清理等必要维度是否有依据。5.3 四类问题必须分开类别判断标准missing_items完成目标功能链所需的契约维度没有可用说明differences多个来源表述不同但尚未证明无法同时成立contradictions同一上下文下的规范性描述无法同时成立unknowns来源质量、版本关系或适用条件不足当前无法判断这四类问题对应不同动作缺失项需要补充契约差异需要明确适用范围矛盾需要确认正确版本未知则需要补充来源或保持未验证。证明缺失时也不能编造一句“文档没有该字段”的引文。应引用已描述的功能范围和相关上下文再说明完整搜索后仍缺少哪一项契约。六、完整性状态必须保持客观6.1 四种完整性状态状态含义complete当前范围所需的契约维度都有充分证据live 仍可能未验证partial核心行为已描述但存在重要缺口、矛盾或未知incomplete必需功能链已被材料证明缺失或不可使用unknown来源质量或范围不足无法判断覆盖度complete最容易被误读。它只表示来源材料覆盖了当前范围内的必要契约维度不表示目标 API 已经在线通过更不表示已经满足性能、稳定性、合规和运维要求。如果仍有阻断性或高严重度问题未解决也不应使用complete。6.2 “没有证据”不等于“证据证明没有”如果来源中没有找到清理接口只能说“当前材料未提供可核验的清理契约”不能据此断言目标 API 一定没有清理能力。同理示例没有展示某个字段不等于字段一定不存在文档没有描述某个错误码也不等于在线服务不会返回它。报告需要区分已确认事实、材料缺口和未验证行为。6.3 反幻觉审计评估完成后应检查实质性陈述是否都有引用是否存在无证据的结论哪些在线声明仍未经过 live 验证哪些来源存在不可读、提取不完整或版本关系不明是否把planned、manual或未执行事项写成了成功。只有没有未引用的实质陈述也没有把未执行的 live 声明写成已验证时反幻觉审计才能通过。七、为什么还需要测试计划assessment 回答的是“材料声明了什么”不能证明目标 API 当前按契约运行。下一步仍需从 claim 和能力矩阵中选择有决策价值的测试。如果缺少计划设计容易走向两个极端只执行默认成功示例漏掉主要变体和生命周期边界对所有参数做笛卡尔积制造冗余请求、额外费用和难以解释的失败。下一篇将讨论如何为每个 case 绑定claim_ids写明必要性和通过/失败的决策影响并处理动态断言、capture、依赖、轮询与 cleanup。八、小结评估不是摘要而是证据链文档驱动的能力评估可以概括为来源材料 - inventory - evidence - claim - capability matrix - finding lists - completeness status它不会自动证明目标 API 可用却能让后续测试明确知道该验证什么、为什么验证以及哪些结论在 live 之前必须保持克制。发布前可以用六个问题快速复核每份来源是否都进入 inventory并记录了提取状态每条重要 claim 是否有可定位引文示例是否被限制在自身上下文缺失、差异、矛盾和未知是否被正确区分complete是否没有冒充 live 或生产结论是否删除了真实服务名、域名、凭据、任务 ID、日志和费用信息系列导航第一篇为什么要做一个文档驱动的 API 能力审计 Skill第二篇让文档成为证据来源盘点、引文校验与能力完整性评估本文第三篇从功能声明到最小测试计划覆盖主要变体而不制造笛卡尔积规划中第四篇如何安全执行 Agent 生成的 API 测试授权门、网络边界与证据分层规划中第五篇从可运行到可信赖一个审计 Skill 的迭代复盘与工程心得规划中参考资料与说明OpenAI DocsCodex Skillshttps://developers.openai.com/codex/skills.md本文介绍的是经过泛化的工程方法本文不构成对任何具体第三方 API 服务的安全、性能、合规或生产就绪评价。