《AI Agent 产品开发·任务定义与能力边界》4.1 输入清单:用户给、系统给、不许用

输入清单要先把字段分成用户给、系统给、不许用三类,并用“不许用”划定硬边界。本节给出三类模板、B Quill 数据包的边界示例、三种越界后果,以及一个能校验缺项、越界和未登记输入的 TypeScript 模型,帮助团队在评审会上直接判定输入契约是否成立。

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

做 Agent 产品时,团队最容易在输入上偷懒:把能拿到的数据都塞进去,然后在提示词里写一句「只使用相关信息」。这句话不是契约,是愿望。模型无法判断哪些信息「相关」,更无法判断哪些信息「不该看」。输入清单要解决的问题不是「多给一点上下文」,而是明确三件事:哪些必须由用户提供,哪些由系统补齐,哪些无论如何都不能进入这次调用。

三类输入对应三种责任。用户给的,是任务意图和本次范围;系统给的,是已经存在且可追溯的事实;不许用的,是越界就会造成泄露、合规或承诺风险的数据。前两类决定 Agent 能不能做,第三类决定它有没有资格做。

三类输入不是分类,是责任分配

把输入分成三类,不是为了把字段整理得好看,而是为了在出问题时能回答「这个字段为什么在这里」。每一类都要有明确的提供者和校验方式。

类别谁提供典型内容缺失或越界的后果
用户给发起任务的人目标、范围、优先级、本次例外任务方向错误,Agent 只能猜
系统给产品后端客户数据包、历史记录、模板、权限内的目录事实不全,输出无法追溯
不许用任何人其他客户数据、超范围个人信息、凭据、内部成本泄露、合规事故、错误承诺

用户给的输入要尽量少而硬。少,是指只收任务真正需要的意图信息;硬,是指每一条都能被校验。比如「报告范围」可以是本季度、上月、某个业务线,但不能是「你看着办」。如果用户说不清范围,正确做法是让 Agent 追问,而不是让它从系统里找一个看起来合理的默认值。

系统给的输入要带来源和时效。系统能拿到,不等于系统应该用;系统里有,不等于这次任务该用。第 4.3 节会把时效和冲突单独展开,这里先记住一条:系统给的每个字段都要能回答「来自哪个系统、什么时候取的、权限依据是什么」。

不许用的输入要单独成表,并且由产品、法务、安全三方共同确认。它不是「最好别用」的建议,而是输入校验必须拦下的硬约束。允许清单可以随需求增长,禁止清单一旦放松,往往不是加一个字段,而是打开一个事故面。

先写「不许用」,再写「允许用」

多数团队先列允许清单,因为那部分最容易写:把数据库里有的表列一遍,再挑几个字段。这样写出来的清单会不断膨胀,而且很难解释为什么某个字段不该出现。反过来,先写禁止清单,会逼团队回答一个更重要的问题:这个产品在什么情况下必须停手。

禁止清单通常有四类:

  1. 跨客户数据。 一个客户的数据包不能出现在另一个客户的报告里,哪怕只是作为「参考格式」。
  2. 超范围个人信息。 合同只允许处理聚合后的工单量,就不应该把用户姓名、联系方式、身份证号带进上下文。
  3. 凭据与密钥。 API key、数据库密码、内部 token 不应出现在提示词、日志或输出里。
  4. 内部成本与利润。 内部报价、毛利、供应商底价不能进入对客交付物,否则一次生成就可能变成一次对外承诺。

这四类有一个共同点:它们都不是「模型会不会用错」的问题,而是「数据根本不该到达模型」的问题。提示词约束、输出过滤、事后审核都只能降低概率,不能替代输入侧的拦截。把禁止清单放在允许清单之前,产品评审的讨论会从「还能加什么」转向「哪些绝对不能进」。

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 有权限自己去取,它仍然要受权限面约束。两张表一起看,才能判断一次任务的数据边界是否闭合。

评审时怎么用这张清单

输入清单不是写完就归档的文档。每次任务规格变更、每次接入新数据源、每次客户合同更新,都应该重新过一遍。评审时按下面五步走:

  1. 逐字段标类别。 每个字段只能属于用户给、系统给、不许用三类之一。标不出来,说明字段的定义还不清楚。
  2. 给必填项写缺失行为。 缺失时是追问、降级还是拒绝执行,要提前写死,不能留给模型临场决定。
  3. 给禁止项写拦截点。 是在数据进入上下文前拦,还是在输出前拦?越早越好,输出前拦已经晚了。
  4. 给系统项写来源和时效。 来源系统、取数时间、有效期、权限依据,四项至少写前三项。
  5. 用一份真实输入包跑校验。 不要用理想化的样例,用最近一次真实任务的数据,看看会不会出现未登记字段。

A Relay(Northwind 的客服工单分诊 Agent)可以用这套清单检查它的工单上下文:工单正文、客户等级、历史工单属于系统给;本次分诊的特殊说明属于用户给;其他客户的工单、内部赔付底线属于不许用。C Runner(Kettle 的电商运营任务执行 Agent)则要把商品目录、价格规则、库存快照列为系统给,把供应商合同、内部毛利列为不许用。三个案例的字段不同,但三类的划分方式一致。

小结

  • 输入清单分三类:用户给、系统给、不许用。三类对应三种责任,不是三种数据格式。
  • 用户给的是任务意图和范围,要少而硬;说不清范围时应追问,不应默认。
  • 系统给的是经授权、带来源、在有效期内的数据;能查到不等于这次该用。
  • 不许用清单比允许清单更重要,它决定产品在什么情况下必须停手。
  • 先写禁止清单,再写允许清单,评审讨论会从「还能加什么」转向「哪些绝对不能进」。
  • 越界后果要写到具体动作:跨客户泄露、超范围个人信息、凭据进入上下文,都会在交付后才暴露。
  • 输入校验要区分缺项、越界、未登记三种失败,它们对应追问、拒绝、补清单三种处理。
  • B Quill 的数据包边界说明:系统给的数据必须同时满足当前客户、当前周期、合同范围。

阅读导航:上一节:3.3 aia-lab:规格完备性与可判定性打分 · 下一节:4.2 上下文预算的产品决策 。

常见错误与边界

  1. 把「只使用相关信息」当成输入约束。 这句话既不能校验,也不能拦截;模型无法判断相关性,更无法判断合规边界。
  2. 把系统能查到的都当成系统该给的。 数据库里有不等于这次任务有授权;系统给的每个字段都要有来源、时效和权限依据。
  3. 先列允许清单,最后补一句禁止项。 这样写出来的清单会不断膨胀,禁止项也容易被当成建议而不是硬约束。
  4. 只用理想样例做校验。 理想样例不会暴露未登记字段;要用最近一次真实任务的数据跑一遍。
  5. 把越界当成模型行为问题。 跨客户数据、超范围个人信息、凭据进入上下文,首先是数据不该到达模型,提示词补救不了。
  6. 忽略未登记输入。 未登记字段说明清单本身有缺口,它既不是缺项也不是越界,需要回到清单补定义。

这一节回答「Agent 能看什么」。下一节要回答一个更现实的问题:当输入装不下时,先砍什么,砍完怎么告诉用户。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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