以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。
输出形态和交付面确定之后,还剩一个问题:交回的东西长什么样。一段自由文本、一份带格式的文档、一条结构化的动作记录,看起来都能完成任务,但它们的可消费性完全不同。自由文本适合人读,不适合系统校验;结构化记录适合系统消费,但不一定适合人审改。输出契约要做的,是在两者之间划出可验收的边界。
这一节的核心判断是:输出契约由三部分组成——结构、可消费性、可拒绝性。结构让输出能被校验,可消费性让它能被下游使用,可拒绝性让用户能说「不」而不摧毁上下文。三者缺一,输出就只是「生成了」,不是「交付了」。
输出契约的七个字段
一份可交付的输出,至少要有七类信息。它们不是固定 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 的草稿还需要一个拒绝入口。审改者可能只想拒绝某一节,而不是整份报告:运营回顾的数据不对,但摘要和财务部分可以用。如果拒绝只能整份重来,已经确认的章节会被一起丢掉,审改成本会上升。
可拒绝性:拒绝而不摧毁上下文
可拒绝性是输出契约里最像产品、最不像工程的部分。它的要求是:用户可以拒绝一个输出,拒绝会被记录,上下文不会因此丢失。
具体要做到三件事:
- 拒绝可以分段。 能拒绝一节,就不要求拒绝整份;能拒绝一个字段,就不要求重跑整个任务。拒绝的粒度越细,用户越愿意说「不」。
- 拒绝要带理由。 理由不是给模型看的装饰,而是下一轮修改的输入。没有理由的拒绝,会让系统不知道是数据错了、格式错了还是判断错了。
- 拒绝后上下文保留。 已确认的章节、已提供的输入、已经完成的核查都要保留;重新生成只针对被拒绝的部分,而不是从零开始。
这三件事合起来,才是「可拒绝」。只提供一个「重新生成」按钮,不算可拒绝,因为用户要放弃已经做对的部分。只记录一个「不满意」标签,也不算可拒绝,因为系统不知道下一步该改什么。
对 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 小时,也就看不到来源和事实核查缺失时成本会怎么上升。
契约评审的五个问题
输出契约上会时,可以按五个问题检查:
- 身份字段齐不齐? 任务号、客户、周期、版本,缺一个下游就无法安全消费。
- 每个结论能不能追到来源? 来源不在清单里,或者章节没有来源,都视为不可追溯。
- 审改者能不能定位到节? 章节 id 稳定,才能分段审改、分段拒绝、分段对比。
- 拒绝的粒度够不够细? 只能整份拒绝,说明契约只支持重跑,不支持协作。
- 下游消费的是结构还是文本? 如果下游只读文本,结构化字段至少也要能导出;否则契约只停留在生成侧。
五个问题里,第四个最容易被忽略。团队通常愿意做结构化和来源,因为这两件事看起来「有价值」;拒绝机制看起来像异常处理,容易被放到二期。但没有拒绝机制,用户对输出的每一次不满意都会变成一次重跑,重跑的成本会吃掉结构化带来的收益。
小结
- 输出契约由三部分组成:结构、可消费性、可拒绝性;三者缺一,输出只是生成,不是交付。
- 七个字段里,前四个是身份,sections 和 source_refs 是可消费性的核心,rejection_token 是可拒绝性的入口。
- 结构化输出带来三个能力:可校验、可对比、可回滚;它们不是工程偏好,而是产品能力。
- Markdown 可以是结构化的载体,但没有字段、来源和拒绝机制,它仍然只是格式好看的文本。
- B Quill 的草稿按节带来源和事实核查,审改才能从「读一遍」变成「核对着改」。
- B 的三档审改是 63% 采纳、28% 小改、9% 返工,加权 1.6035 小时;只报 1.6 小时会隐藏返工档的成本。
- 可拒绝性要求:拒绝可分粒度、拒绝带理由、拒绝后上下文保留;只给「重新生成」不算可拒绝。
- C Runner 的拒绝窗口更窄:86% 可回滚,14% 不可回滚,后者必须在执行前显式确认。
阅读导航:上一节:5.2 交付面:界面、文件还是系统写入 · 下一节:6.1 建议、草稿、审批、执行四档 。
常见错误与边界
- 把结构化当成工程偏好。 结构带来可校验、可对比、可回滚,这三项都是产品能力,不是程序员的整洁癖。
- 只有整段文本,没有章节 id。 审改无法定位,拒绝只能整份重来,已经确认的内容会被一起丢掉。
- 来源只写在文末。 文末的来源清单无法回答「这一节的数字从哪来」;来源要跟到节,最好跟到具体数字。
- 没有拒绝令牌。 用户说「不」只能靠重新生成,上下文和已确认部分都会丢失;可拒绝性不是异常处理,是契约的一部分。
- 拒绝不带理由。 没有理由,系统不知道是数据、格式还是判断错了,下一轮只能盲改。
- 把 1.6 小时当成单一审改成本。 它是 63/28/9 三档的加权;返工档是 3.0 小时,来源缺失会把更多草稿推进返工档。
这一节回答「交回的东西长什么样」。下一章进入自主度定档:建议、草稿、审批、执行四档,以及分数之上为什么还有一条组织线。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。