以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。
做 Agent 产品时,团队最容易在输入上偷懒:把能拿到的数据都塞进去,然后在提示词里写一句「只使用相关信息」。这句话不是契约,是愿望。模型无法判断哪些信息「相关」,更无法判断哪些信息「不该看」。输入清单要解决的问题不是「多给一点上下文」,而是明确三件事:哪些必须由用户提供,哪些由系统补齐,哪些无论如何都不能进入这次调用。
三类输入对应三种责任。用户给的,是任务意图和本次范围;系统给的,是已经存在且可追溯的事实;不许用的,是越界就会造成泄露、合规或承诺风险的数据。前两类决定 Agent 能不能做,第三类决定它有没有资格做。
三类输入不是分类,是责任分配
把输入分成三类,不是为了把字段整理得好看,而是为了在出问题时能回答「这个字段为什么在这里」。每一类都要有明确的提供者和校验方式。
| 类别 | 谁提供 | 典型内容 | 缺失或越界的后果 |
|---|---|---|---|
| 用户给 | 发起任务的人 | 目标、范围、优先级、本次例外 | 任务方向错误,Agent 只能猜 |
| 系统给 | 产品后端 | 客户数据包、历史记录、模板、权限内的目录 | 事实不全,输出无法追溯 |
| 不许用 | 任何人 | 其他客户数据、超范围个人信息、凭据、内部成本 | 泄露、合规事故、错误承诺 |
用户给的输入要尽量少而硬。少,是指只收任务真正需要的意图信息;硬,是指每一条都能被校验。比如「报告范围」可以是本季度、上月、某个业务线,但不能是「你看着办」。如果用户说不清范围,正确做法是让 Agent 追问,而不是让它从系统里找一个看起来合理的默认值。
系统给的输入要带来源和时效。系统能拿到,不等于系统应该用;系统里有,不等于这次任务该用。第 4.3 节会把时效和冲突单独展开,这里先记住一条:系统给的每个字段都要能回答「来自哪个系统、什么时候取的、权限依据是什么」。
不许用的输入要单独成表,并且由产品、法务、安全三方共同确认。它不是「最好别用」的建议,而是输入校验必须拦下的硬约束。允许清单可以随需求增长,禁止清单一旦放松,往往不是加一个字段,而是打开一个事故面。
先写「不许用」,再写「允许用」
多数团队先列允许清单,因为那部分最容易写:把数据库里有的表列一遍,再挑几个字段。这样写出来的清单会不断膨胀,而且很难解释为什么某个字段不该出现。反过来,先写禁止清单,会逼团队回答一个更重要的问题:这个产品在什么情况下必须停手。
禁止清单通常有四类:
- 跨客户数据。 一个客户的数据包不能出现在另一个客户的报告里,哪怕只是作为「参考格式」。
- 超范围个人信息。 合同只允许处理聚合后的工单量,就不应该把用户姓名、联系方式、身份证号带进上下文。
- 凭据与密钥。 API key、数据库密码、内部 token 不应出现在提示词、日志或输出里。
- 内部成本与利润。 内部报价、毛利、供应商底价不能进入对客交付物,否则一次生成就可能变成一次对外承诺。
这四类有一个共同点:它们都不是「模型会不会用错」的问题,而是「数据根本不该到达模型」的问题。提示词约束、输出过滤、事后审核都只能降低概率,不能替代输入侧的拦截。把禁止清单放在允许清单之前,产品评审的讨论会从「还能加什么」转向「哪些绝对不能进」。
B Quill 的「系统给」边界
B Quill(Meridian 的客户报告起草 Agent)是一个适合说明边界的案例。它每月处理 606 份报告,咨询团队 15 人,人工基线是每份 4.2 小时。它的输入看起来很简单:客户数据包、上月报告、行业模板。但「系统给」不等于「系统随便给」。
B 的数据包必须同时满足三个条件:属于当前客户、属于当前报告周期、在合同允许的处理范围内。三个条件缺一个,数据包就不应该进入这次调用。比如拿上个月的包来补本月缺失的指标,表面上让报告更完整,实际上会让客户看到一个已经过期的数字;拿另一个客户的包来参考结构,则可能把别人的业务细节写进本客户的报告。
这就是「系统给」的真正边界:系统提供的是经过授权、带来源、在有效期内的数据,不是「数据库里能查到的所有东西」。B 的每份报告有 12–20 页,每一页都可能引用数据包中的不同表;如果输入阶段不记录来源,审改阶段就无法判断某个数字是从哪张表来的。人工审改每份 1.6 小时,其中相当一部分时间会花在「这个数对不对」上。输入清单把来源写清楚,等于把这部分核查成本前移。
反过来,如果系统给得太多,B 的审改不会更轻松,只会更困难。数据包之外再塞进聊天记录、销售备注、历史邮件,模型会生成更多「看起来有依据」的句子,但审改的人需要逐条判断这些依据是否在合同范围内。输入越多,审改越像考古。
三种越界后果
越界不是一个抽象的风险词。产品评审时,最好把后果写到能对应具体动作的程度。下面三种后果,分别对应三类最常见的越界。
| 越界 | 具体表现 | 直接后果 |
|---|---|---|
| 跨客户数据 | 报告里出现另一家客户的案例、指标或组织名称 | 保密违约,客户信任一次性受损 |
| 超范围个人信息 | 聚合报表里带出可识别到个人的字段 | 违反数据处理约定,触发合规整改 |
| 凭据进入上下文 | key 被写进日志、提示词或生成内容 | 需要轮换密钥,并排查是否已被读取 |
这三种后果有一个共同的放大器:它们都可能在交付之后才被发现。跨客户数据可能被客户自己认出来,个人信息可能在上线审计时才被抽查到,凭据泄露可能要等到异常调用才暴露。输入侧的拦截之所以重要,是因为它是唯一能在「模型看到之前」生效的环节。
还有一种容易被忽略的越界:把内部成本表当作「背景知识」交给模型,让它在报告里解释价格构成。模型不会区分「可以内部参考」和「可以对客承诺」,它只会把看起来相关的数字写进最合适的位置。一旦这个数字出现在客户报告里,它就不再是内部估算,而是对外报价的一部分。
一份可评审的输入清单长什么样
B Quill 的输入清单在评审会上通常写成下面这样。它不追求覆盖所有字段,只覆盖会影响责任分配的字段。
| 字段 | 类别 | 提供者 | 必填 | 缺失时 |
|---|---|---|---|---|
| 报告范围 | 用户给 | 发起人 | 是 | 追问,不默认 |
| 重点议题 | 用户给 | 发起人 | 是 | 允许为空,但要在封面说明 |
| 发布对象 | 用户给 | 发起人 | 是 | 追问 |
| 当前客户数据包 | 系统给 | 数据平台 | 是 | 拒绝生成 |
| 上月报告 | 系统给 | 文档库 | 是 | 降级为无对比版本,并标注 |
| 行业模板 | 系统给 | 模板库 | 否 | 使用默认模板 |
| 其他客户数据包 | 不许用 | 无 | — | 输入校验直接拒绝 |
| 原始个人信息导出 | 不许用 | 无 | — | 输入校验直接拒绝 |
| 内部毛利表 | 不许用 | 无 | — | 输入校验直接拒绝 |
| API 凭据 | 不许用 | 无 | — | 输入校验直接拒绝 |
这张表的价值不在字段数量,而在「缺失时」这一列。必填项缺失时是追问还是拒绝,系统项缺失时是降级还是停手,禁止项出现时是告警还是阻断,都必须提前写死。否则运行时只能由模型临场决定,而模型没有权限做这种决定。
还有一个容易被漏掉的检查:用户给的意图和系统给的数据必须对齐。用户选了 A 客户,系统却只拿到 B 客户的数据包,这时正确行为是停手并说明不匹配,而不是「先用手头的数据生成一版」。后者会让一份看起来完整的报告建立在错误的客户数据上,审改的人很难在第一眼发现。
清单本身要有版本。字段增删、提供者变更、禁止项调整,都应该留下记录,并与任务规格的版本对应。没有版本的清单会在半年后变成一张没人敢改的表:谁都不知道某个字段为什么被标成禁止,也没人敢把它删掉。
把输入清单写成可校验的模型
下面这个模型把三类输入、必填项、越界后果和未登记输入做成一次校验。它的输出不是「通过/不通过」两个词,而是分别列出缺了什么、越界了什么、哪些字段根本没登记。评审会上可以直接拿它对照输入包。
// file: src/task/04-1-input-inventory.ts
// tier: L2
// verify: node --test test/task/04-1-input-inventory.test.ts
// 输入清单把每个字段归入三类:用户给、系统给、不许用。
// 「不许用」是硬边界:出现在输入包里就是违规,不是提示词能补救的问题。
export type InputClass = "user" | "system" | "forbidden";
export type Overrun = "cross-client" | "pii" | "credential" | "margin";
export type InputField = {
readonly name: string;
readonly kind: InputClass;
readonly required: boolean;
readonly risk?: Overrun;
};
export type Inventory = readonly InputField[];
export const OVERRUN_CONSEQUENCE: Record<Overrun, string> = {
"cross-client": "one client's data appears in another client's deliverable",
pii: "personal data is processed beyond the contracted purpose",
credential: "a secret is copied into logs, prompts or outputs",
margin: "internal pricing is quoted to a customer as a commitment",
};
export function classify(inventory: Inventory, name: string): InputClass | null {
const field = inventory.find((item) => item.name === name);
return field ? field.kind : null;
}
export function requiredNames(inventory: Inventory): readonly string[] {
return inventory
.filter((item) => item.kind !== "forbidden" && item.required)
.map((item) => item.name);
}
export type BundleCheck = {
readonly ok: boolean;
readonly missing: readonly string[];
readonly violations: readonly string[];
readonly unknown: readonly string[];
readonly consequences: readonly string[];
};
export function checkBundle(
inventory: Inventory,
provided: readonly string[],
): BundleCheck {
const given = new Set(provided);
const known = new Set(inventory.map((item) => item.name));
const missing = requiredNames(inventory).filter((name) => !given.has(name));
const violations = inventory
.filter((item) => item.kind === "forbidden" && given.has(item.name))
.map((item) => item.name);
const unknown = provided.filter((name) => !known.has(name));
const consequences = violations.map((name) => {
const field = inventory.find((item) => item.name === name);
return field?.risk ? OVERRUN_CONSEQUENCE[field.risk] : "unreviewed input";
});
return {
ok: missing.length === 0 && violations.length === 0 && unknown.length === 0,
missing,
violations,
unknown,
consequences,
};
}
// B Quill 的输入包:数据包由系统给,但只限当前客户、当前周期。
export const QUILL_INVENTORY: Inventory = [
{ name: "report_scope", kind: "user", required: true },
{ name: "focus_topics", kind: "user", required: true },
{ name: "audience", kind: "user", required: true },
{ name: "data_pack_current_client", kind: "system", required: true },
{ name: "last_report", kind: "system", required: true },
{ name: "report_template", kind: "system", required: true },
{ name: "other_client_pack", kind: "forbidden", required: false, risk: "cross-client" },
{ name: "raw_pii_export", kind: "forbidden", required: false, risk: "pii" },
{ name: "api_credentials", kind: "forbidden", required: false, risk: "credential" },
{ name: "internal_margin_sheet", kind: "forbidden", required: false, risk: "margin" },
];
export const QUILL_COMPLETE: readonly string[] = [
"report_scope",
"focus_topics",
"audience",
"data_pack_current_client",
"last_report",
"report_template",
];
checkBundle 的判定顺序值得注意:先算缺项,再算越界,最后算未登记。缺项说明任务做不了,越界说明任务不该做,未登记说明清单本身需要补。三种失败对应三种不同的处理动作,不能混成一句「输入不合格」。
QUILL_INVENTORY 把 B 的输入写成十条:三条用户给、三条系统给、四条禁止。QUILL_COMPLETE 是一份合法输入包,它能通过校验,但通过不代表充分;它只证明这份包没有缺必填项、没有越界、没有未登记字段。真正的质量判断仍然要看数据包是否属于当前客户和当前周期,这部分需要后端在提供数据时保证。
classify 和 requiredNames 是两个小工具。前者回答「这个字段属于哪一类」,后者回答「这次任务至少需要哪些字段」。它们看起来简单,但能把评审从「我觉得还需要一个字段」变成「这个字段属于哪一类、谁负责提供、缺失时任务是否还能做」。
模型只能校验「包里的字段是否符合清单」,它回答不了三个更前置的问题。
第一,字段的定义是否准确。比如「重点议题」到底是一段自由文本,还是一个可多选的议题列表?定义不同,校验方式就不同。第二,提供者是否真的能提供。把「上月报告」标成系统给,前提是文档库确实按客户和周期存了这份报告;如果历史报告散落在个人电脑里,这个字段在运行时就会经常缺失。第三,禁止项是否真的被拦住。清单里写了「其他客户数据包」不许用,但数据平台如果按租户隔离,这个字段根本不会出现在输入包里;如果平台没有隔离,就需要在进入上下文前加一道显式检查。
这三个问题都要在评审会上回答,不能留给实现阶段。输入清单是产品契约的一部分,不是后端接口文档的附属品。
输入清单和权限面是两张相邻的表,但不能互相替代。权限面回答「这个 Agent 能调用哪些系统和动作」,输入清单回答「这次任务实际带进了哪些数据」。一个有权限读取客户数据包的 Agent,不代表每一次报告任务都应该带上所有客户的数据;反过来,输入清单里列了某个字段,也不代表 Agent 有权限自己去取,它仍然要受权限面约束。两张表一起看,才能判断一次任务的数据边界是否闭合。
评审时怎么用这张清单
输入清单不是写完就归档的文档。每次任务规格变更、每次接入新数据源、每次客户合同更新,都应该重新过一遍。评审时按下面五步走:
- 逐字段标类别。 每个字段只能属于用户给、系统给、不许用三类之一。标不出来,说明字段的定义还不清楚。
- 给必填项写缺失行为。 缺失时是追问、降级还是拒绝执行,要提前写死,不能留给模型临场决定。
- 给禁止项写拦截点。 是在数据进入上下文前拦,还是在输出前拦?越早越好,输出前拦已经晚了。
- 给系统项写来源和时效。 来源系统、取数时间、有效期、权限依据,四项至少写前三项。
- 用一份真实输入包跑校验。 不要用理想化的样例,用最近一次真实任务的数据,看看会不会出现未登记字段。
A Relay(Northwind 的客服工单分诊 Agent)可以用这套清单检查它的工单上下文:工单正文、客户等级、历史工单属于系统给;本次分诊的特殊说明属于用户给;其他客户的工单、内部赔付底线属于不许用。C Runner(Kettle 的电商运营任务执行 Agent)则要把商品目录、价格规则、库存快照列为系统给,把供应商合同、内部毛利列为不许用。三个案例的字段不同,但三类的划分方式一致。
小结
- 输入清单分三类:用户给、系统给、不许用。三类对应三种责任,不是三种数据格式。
- 用户给的是任务意图和范围,要少而硬;说不清范围时应追问,不应默认。
- 系统给的是经授权、带来源、在有效期内的数据;能查到不等于这次该用。
- 不许用清单比允许清单更重要,它决定产品在什么情况下必须停手。
- 先写禁止清单,再写允许清单,评审讨论会从「还能加什么」转向「哪些绝对不能进」。
- 越界后果要写到具体动作:跨客户泄露、超范围个人信息、凭据进入上下文,都会在交付后才暴露。
- 输入校验要区分缺项、越界、未登记三种失败,它们对应追问、拒绝、补清单三种处理。
- B Quill 的数据包边界说明:系统给的数据必须同时满足当前客户、当前周期、合同范围。
阅读导航:上一节:3.3 aia-lab:规格完备性与可判定性打分 · 下一节:4.2 上下文预算的产品决策 。
常见错误与边界
- 把「只使用相关信息」当成输入约束。 这句话既不能校验,也不能拦截;模型无法判断相关性,更无法判断合规边界。
- 把系统能查到的都当成系统该给的。 数据库里有不等于这次任务有授权;系统给的每个字段都要有来源、时效和权限依据。
- 先列允许清单,最后补一句禁止项。 这样写出来的清单会不断膨胀,禁止项也容易被当成建议而不是硬约束。
- 只用理想样例做校验。 理想样例不会暴露未登记字段;要用最近一次真实任务的数据跑一遍。
- 把越界当成模型行为问题。 跨客户数据、超范围个人信息、凭据进入上下文,首先是数据不该到达模型,提示词补救不了。
- 忽略未登记输入。 未登记字段说明清单本身有缺口,它既不是缺项也不是越界,需要回到清单补定义。
这一节回答「Agent 能看什么」。下一节要回答一个更现实的问题:当输入装不下时,先砍什么,砍完怎么告诉用户。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。