《AI Agent 产品开发·任务定义与能力边界》5.3 输出契约与可消费性

输出契约要同时保证结构、可消费性和可拒绝性。本节给出七个字段的契约模板,说明结构化输出为什么让校验、对比和回滚成为可能,用 B Quill 的 Markdown 草稿演示来源与事实核查,并说明用户怎样分段拒绝一个输出而不摧毁已经确认的上下文。

以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。

输出形态和交付面确定之后,还剩一个问题:交回的东西长什么样。一段自由文本、一份带格式的文档、一条结构化的动作记录,看起来都能完成任务,但它们的可消费性完全不同。自由文本适合人读,不适合系统校验;结构化记录适合系统消费,但不一定适合人审改。输出契约要做的,是在两者之间划出可验收的边界。

这一节的核心判断是:输出契约由三部分组成——结构、可消费性、可拒绝性。结构让输出能被校验,可消费性让它能被下游使用,可拒绝性让用户能说「不」而不摧毁上下文。三者缺一,输出就只是「生成了」,不是「交付了」。

输出契约的七个字段

一份可交付的输出,至少要有七类信息。它们不是固定 schema,而是一份契约模板;不同任务可以增删字段,但七类信息背后的意图不能省。

字段类型回答的问题缺失后的后果
contract_version身份这份输出按哪版契约生成下游无法判断如何解析
task_id身份这次输出对应哪个任务出错时无法追溯和回滚
client_id身份输出属于哪个客户跨客户混用无法被发现
period身份输出覆盖哪个时间范围数字口径无法核对
sections内容输出由哪些部分组成无法定位到具体段落审改
source_refs来源每个结论引用了什么事实错误无法追到输入
rejection_token拒绝用户怎样拒绝这份输出拒绝只能靠重跑,上下文丢失

前四个字段是身份,解决「这是谁的、什么时候的、对应哪次任务」。它们看起来琐碎,但缺少任何一个,下游都无法安全消费。没有 task_id,审计日志找不到对应动作;没有 client_id,跨客户数据混用无法被拦截;没有 period,同一个指标在不同月份之间会被混在一起。

sections 和 source_refs 是可消费性的核心。分段让审改可以定位,来源让核查可以追溯。一个 12–20 页的报告如果只有一个整段文本,审改者只能在全文里搜索;如果每一节都带来源,审改者可以直接跳到需要核查的数字。

rejection_token 是最容易被忽略的字段。它不是「删除」按钮的 ID,而是一份契约声明:这份输出可以被拒绝,拒绝会被记录,拒绝不会摧毁上下文。没有它,用户说「不」的唯一方式通常是重新生成,而重新生成会把已经确认的部分一起丢掉。

结构化输出的产品意义

结构化输出经常被当成工程偏好,好像只是「方便程序解析」。对产品来说,它至少带来三个能力。

可校验。 结构化的字段可以逐项检查:必填项在不在、来源是否在清单里、每个章节有没有事实核查、版本是否受支持。自由文本只能靠人读,读完之后仍然无法确认「有没有漏」。校验不是为了保证正确,而是为了把「明显不完整」挡在交付之前。

可对比。 同一份契约下的两版输出可以逐字段对比:哪一节改了、哪个数字变了、哪个来源换了。没有结构,对比只能靠文本 diff,而文本 diff 会把格式变化和内容变化混在一起。对 B Quill 这种需要审改的报告,逐节对比比全文 diff 有用得多。

可回滚。 结构化输出带 task_id 和前后值,出错时可以定位到具体动作并回滚。自由文本没有动作语义,回滚只能靠人重新操作。C Runner 的动作之所以能审计,前提就是每个动作都有结构化记录,而不是一段「已处理」的描述。

这三个能力也解释了为什么「让模型输出 Markdown」不等于「有输出契约」。Markdown 可以是结构化的载体,但如果没有字段定义、来源清单和拒绝机制,它仍然只是一段格式好看的文本。

B Quill 的 Markdown 草稿

B Quill 的输出是一份 12–20 页的客户月报初稿,格式是 Markdown 加图表。它看起来像一份文档,实际上要满足一份契约。

第一,每个章节要有稳定的 id。审改者说「运营回顾这节不对」,系统要能定位到 operations,而不是在全文里找标题。第二,每个章节要带 sourceRefs,说明这一节引用了哪个数据包、哪份上月报告。第三,每个章节要带 factChecks,列出审改时需要核对的点,比如「营收与数据包总额一致」「工单量与数据包一致」。

这三项看起来增加了生成负担,但它们直接对应 B 的审改结构。B 的一次采纳率是 63%,小改率 28%,返工率 9%;三档审改时长分别是 1.25、1.95、3.0 小时,加权后是 1.6035 小时,约等于 1.6 小时。审改时间的主要构成不是「读一遍」,而是「核对数字、判断结论、补写段落」。来源和事实核查清单把核对变成可定位的动作,返工率才有机会下降。

反过来,如果草稿只有一段长文本,审改者要自己找数字、自己判断来源、自己记录问题。1.6 小时的审改会被拉长,而且审改质量取决于个人经验。输出契约不是让草稿更「工程化」,而是让审改这件事可重复。

B 的草稿还需要一个拒绝入口。审改者可能只想拒绝某一节,而不是整份报告:运营回顾的数据不对,但摘要和财务部分可以用。如果拒绝只能整份重来,已经确认的章节会被一起丢掉,审改成本会上升。

可拒绝性:拒绝而不摧毁上下文

可拒绝性是输出契约里最像产品、最不像工程的部分。它的要求是:用户可以拒绝一个输出,拒绝会被记录,上下文不会因此丢失。

具体要做到三件事:

  1. 拒绝可以分段。 能拒绝一节,就不要求拒绝整份;能拒绝一个字段,就不要求重跑整个任务。拒绝的粒度越细,用户越愿意说「不」。
  2. 拒绝要带理由。 理由不是给模型看的装饰,而是下一轮修改的输入。没有理由的拒绝,会让系统不知道是数据错了、格式错了还是判断错了。
  3. 拒绝后上下文保留。 已确认的章节、已提供的输入、已经完成的核查都要保留;重新生成只针对被拒绝的部分,而不是从零开始。

这三件事合起来,才是「可拒绝」。只提供一个「重新生成」按钮,不算可拒绝,因为用户要放弃已经做对的部分。只记录一个「不满意」标签,也不算可拒绝,因为系统不知道下一步该改什么。

对 C Runner 来说,可拒绝性表现为「动作可以被撤销或补偿」。它的错误中 86% 可回滚,回滚句柄就是拒绝机制的另一种形式;剩下 14% 不可回滚,必须在执行前显式确认,而不是执行后再说「你可以拒绝」。动作形态的拒绝窗口比草稿窄,所以它的契约要更早地暴露风险。

把输出契约写成校验模型

下面这个模型把七个字段、来源校验、事实核查和分段拒绝做成可运行的检查。它的重点不是 schema 本身,而是让「不完整」和「不可拒绝」在交付前暴露。

// file: src/task/05-3-output-contract.ts
// tier: L2
// verify: node --test test/task/05-3-output-contract.test.ts

// 输出契约:结构、可消费性、可拒绝性。
// 拒绝一个输出是正常操作,不能因此丢掉上下文,也不能逼用户从头再来。

import { type Bps, FULL } from "../core/rate.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type ContractField = {
  readonly name: string;
  readonly kind: "identity" | "content" | "provenance" | "rejection";
};

export const CONTRACT_TEMPLATE: readonly ContractField[] = [
  { name: "contract_version", kind: "identity" },
  { name: "task_id", kind: "identity" },
  { name: "client_id", kind: "identity" },
  { name: "period", kind: "identity" },
  { name: "sections", kind: "content" },
  { name: "source_refs", kind: "provenance" },
  { name: "rejection_token", kind: "rejection" },
];

export type Section = {
  readonly id: string;
  readonly markdown: string;
  readonly sourceRefs: readonly string[];
  readonly factChecks: readonly string[];
};

export type ReportDraft = {
  readonly contractVersion: string;
  readonly taskId: string;
  readonly clientId: string;
  readonly period: string;
  readonly sections: readonly Section[];
  readonly sourceRefs: readonly string[];
  readonly rejectionToken: string;
};

export const SUPPORTED_VERSION = "1.0";

export function validateDraft(draft: ReportDraft): Result<ReportDraft> {
  if (draft.contractVersion !== SUPPORTED_VERSION) {
    return fail(`unsupported contract version ${draft.contractVersion}`);
  }
  if (!draft.taskId || !draft.clientId || !draft.period) {
    return fail("identity fields must be present");
  }
  if (!draft.rejectionToken) {
    return fail("missing rejection token: a draft must be rejectable");
  }
  if (draft.sections.length === 0) {
    return fail("a draft needs at least one section");
  }
  for (const section of draft.sections) {
    if (section.sourceRefs.length === 0) {
      return fail(`section ${section.id} has no source ref`);
    }
    if (section.factChecks.length === 0) {
      return fail(`section ${section.id} has no fact check`);
    }
    for (const ref of section.sourceRefs) {
      if (!draft.sourceRefs.includes(ref)) {
        return fail(`section ${section.id} cites unknown source ${ref}`);
      }
    }
  }
  return ok(draft);
}

export type Rejection = {
  readonly scope: "section" | "draft";
  readonly targetId: string;
  readonly reason: string;
  readonly draftKept: true;
};

export function rejectSection(
  draft: ReportDraft,
  sectionId: string,
  reason: string,
): Result<{ readonly draft: ReportDraft; readonly rejection: Rejection }> {
  if (!draft.sections.some((section) => section.id === sectionId)) {
    return fail(`unknown section ${sectionId}`);
  }
  if (reason.trim().length === 0) {
    return fail("a rejection needs a reason");
  }
  return ok({
    draft,
    rejection: {
      scope: "section",
      targetId: sectionId,
      reason,
      draftKept: true,
    },
  });
}

// B Quill 的审改结构:63% 采纳、28% 小改、9% 返工,加权 1.6035 小时。
export const QUILL_REVIEW = {
  mix: { accept: 6_300, minor: 2_800, rework: 900 },
  hours: { accept: 1.25, minor: 1.95, rework: 3.0 },
};

export function weightedReviewHours(): number {
  const { mix, hours } = QUILL_REVIEW;
  return (
    (mix.accept * hours.accept +
      mix.minor * hours.minor +
      mix.rework * hours.rework) /
    FULL
  );
}

export const QUILL_DRAFT: ReportDraft = {
  contractVersion: "1.0",
  taskId: "quill-2026-10-acme",
  clientId: "acme",
  period: "2026-10",
  sections: [
    {
      id: "summary",
      markdown: "## 本月摘要\n\n本月核心指标与上月对比。\n",
      sourceRefs: ["pack-2026-10-acme"],
      factChecks: ["revenue matches pack total"],
    },
    {
      id: "operations",
      markdown: "## 运营回顾\n\n工单量与响应时长回顾。\n",
      sourceRefs: ["pack-2026-10-acme", "last-report-2026-09"],
      factChecks: ["ticket volume matches pack"],
    },
  ],
  sourceRefs: ["pack-2026-10-acme", "last-report-2026-09"],
  rejectionToken: "reject-quill-2026-10-acme-v1",
};

export const QUILL_REVIEW_SHARE: Bps = 10_000;

validateDraft 先查版本和身份字段,再查拒绝令牌,最后逐节检查来源和事实核查。这个顺序是有意的:身份不对,后面的内容没有意义;不能拒绝,草稿再完整也不可交付;来源和核查缺失,审改无法定位。

rejectSection 不修改草稿,只返回原草稿和一条拒绝记录。这个设计看起来「什么都没做」,但它正是可拒绝性的关键:拒绝是附加信息,不是破坏性操作。已确认的章节保留,被拒绝的章节带上理由进入下一轮,上下文不会被清空。

weightedReviewHours 用 63/28/9 的三档比例和 1.25/1.95/3.0 小时的三档时长算出 1.6035 小时。它提醒一件事:审改成本不是一个平均数,而是三档的加权;如果只报一个「1.6 小时」,团队会看不到返工档的 3.0 小时,也就看不到来源和事实核查缺失时成本会怎么上升。

契约评审的五个问题

输出契约上会时,可以按五个问题检查:

  1. 身份字段齐不齐? 任务号、客户、周期、版本,缺一个下游就无法安全消费。
  2. 每个结论能不能追到来源? 来源不在清单里,或者章节没有来源,都视为不可追溯。
  3. 审改者能不能定位到节? 章节 id 稳定,才能分段审改、分段拒绝、分段对比。
  4. 拒绝的粒度够不够细? 只能整份拒绝,说明契约只支持重跑,不支持协作。
  5. 下游消费的是结构还是文本? 如果下游只读文本,结构化字段至少也要能导出;否则契约只停留在生成侧。

五个问题里,第四个最容易被忽略。团队通常愿意做结构化和来源,因为这两件事看起来「有价值」;拒绝机制看起来像异常处理,容易被放到二期。但没有拒绝机制,用户对输出的每一次不满意都会变成一次重跑,重跑的成本会吃掉结构化带来的收益。

小结

  • 输出契约由三部分组成:结构、可消费性、可拒绝性;三者缺一,输出只是生成,不是交付。
  • 七个字段里,前四个是身份,sections 和 source_refs 是可消费性的核心,rejection_token 是可拒绝性的入口。
  • 结构化输出带来三个能力:可校验、可对比、可回滚;它们不是工程偏好,而是产品能力。
  • Markdown 可以是结构化的载体,但没有字段、来源和拒绝机制,它仍然只是格式好看的文本。
  • B Quill 的草稿按节带来源和事实核查,审改才能从「读一遍」变成「核对着改」。
  • B 的三档审改是 63% 采纳、28% 小改、9% 返工,加权 1.6035 小时;只报 1.6 小时会隐藏返工档的成本。
  • 可拒绝性要求:拒绝可分粒度、拒绝带理由、拒绝后上下文保留;只给「重新生成」不算可拒绝。
  • C Runner 的拒绝窗口更窄:86% 可回滚,14% 不可回滚,后者必须在执行前显式确认。

阅读导航:上一节:5.2 交付面:界面、文件还是系统写入 · 下一节:6.1 建议、草稿、审批、执行四档 。

常见错误与边界

  1. 把结构化当成工程偏好。 结构带来可校验、可对比、可回滚,这三项都是产品能力,不是程序员的整洁癖。
  2. 只有整段文本,没有章节 id。 审改无法定位,拒绝只能整份重来,已经确认的内容会被一起丢掉。
  3. 来源只写在文末。 文末的来源清单无法回答「这一节的数字从哪来」;来源要跟到节,最好跟到具体数字。
  4. 没有拒绝令牌。 用户说「不」只能靠重新生成,上下文和已确认部分都会丢失;可拒绝性不是异常处理,是契约的一部分。
  5. 拒绝不带理由。 没有理由,系统不知道是数据、格式还是判断错了,下一轮只能盲改。
  6. 把 1.6 小时当成单一审改成本。 它是 63/28/9 三档的加权;返工档是 3.0 小时,来源缺失会把更多草稿推进返工档。

这一节回答「交回的东西长什么样」。下一章进入自主度定档:建议、草稿、审批、执行四档,以及分数之上为什么还有一条组织线。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图