《AI Agent 产品开发·任务定义与能力边界》3.1 任务规格的四要素

任务规格不是一段更长的需求描述,而是四件必须写清的事:输入清单、输出形态、验收标准、代价上限。本节逐项给模板与反例,说明缺任一项会在上线后变成什么后果,并用 A Relay、B Quill、C Runner 各写一份缩略规格,最后给出可运行的检查器。

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

第 2 章解决了「做什么、不做什么」。从这一节开始,问题变成「怎么把要做的事写清楚」。很多团队在这一步会写出一份很长的需求文档:背景、目标、用户故事、流程图、提示词草稿,什么都有,唯独没有四件事:它吃什么、吐什么、怎么算做好、最多能花多少。

这四件事就是任务规格的四要素:输入清单、输出形态、验收标准、代价上限。它们不是文档模板的四个章节,而是四个必须能独立回答的问题。缺任何一项,规格都不能进入评审;不是因为它不完整,而是因为缺了它,后面的设计会失去约束。

四要素是什么

先给结论:四要素是任务规格的最小完备集。少一项,任务就有一个维度没有被定义;多一项,通常是实现细节,不属于规格层。

要素回答的问题产物缺失后的典型症状
输入清单它能看到什么、不能看到什么用户给、系统给、禁止用三类列表上线后才发现模型读了不该读的数据
输出形态它交付的是答案、草稿还是动作三选一,并写清字段验收标准写在了错误的层级
验收标准怎么判断这一次做对了至少两条可独立判定的标准评审变成「看起来还行」
代价上限一次任务最多花多少人工和系统成本系统成本 + 人工时间,分开写上线后算不清账,节省率失真

四要素的顺序有讲究。输入和输出定义任务的形状,验收定义任务的对错,代价定义任务的边界。先写输入输出,再写验收,最后写代价;如果先写代价,很容易为了「便宜」砍掉必要的输入,最后验收更贵。

四要素也不是越细越好。输入清单写到「工单正文、账户与套餐、8 个队列定义、模板库」就够了,不需要写到具体字段名;验收标准写到「队列属于 8 个定义队列之一」就够了,不需要写判定代码。规格是给人评审的,不是给编译器执行的;它的详细程度以「另一个人能独立判断」为准。

输入清单:用户给、系统给、禁止用

输入清单要分三类写,缺一类都不算完整。

用户给:用户在这次任务里主动提供的内容。A Relay 的用户给的是新工单正文和客户补充回复;B Quill 的用户给的是客户数据包、上月报告和行业模板;C Runner 的用户给的是异常任务队列和动作偏好。用户给的内容有一个共同点:它是任务启动的必要条件,没有它任务无法开始。

系统给:系统在后台能取到的上下文。A 的系统给账户与套餐、8 个队列定义、首响模板库;B 的系统给图表渲染器、报告模板库、事实核查清单;C 的系统给商品目录快照、价格规则、库存和审计日志。系统给的内容决定了 Agent 能看到多少背景,也决定了它对系统集成的依赖。

禁止用:任务明确不能碰的数据。A 禁止用与分诊无关的支付卡号、客户未授权的历史订单;B 禁止用未脱敏的客户名单、其他客户的原始数据;C 禁止用供应商成本价、未授权的批量下架名单。禁止用这一类最容易被省略,因为它不参与「怎么完成任务」,只参与「不能怎么完成任务」。

三类输入缺一的后果不同。缺用户给,任务无法启动;缺系统给,Agent 只能靠用户现场补充,体验会退化成问答;缺禁止用,任务能跑,但会在某个边界上越权。第三类最危险,因为它在演示里不会暴露,只会在审计或事故里暴露。

写输入清单时有一个实用检查:每一类至少写两条,禁止用至少写一条。 只写一条用户给、一条系统给,通常说明任务边界还没想清楚;禁止用一条都没有,通常说明团队还没想过权限面。

输出形态:答案、草稿、动作

输出形态只有三种:答案、草稿、动作。它不是 UI 形态,而是责任形态。

形态交付物人接下来做什么典型案例
答案一个建议、一个分类、一个字段值确认、修改或忽略A Relay 的队列、优先级、模板号
草稿一份需要人加工的半成品审改、补充、发布B Quill 的 12–20 页报告初稿
动作一次已经发生的外部状态变更事后审计、必要时回滚C Runner 的改价、改库存、下架

输出形态由自主档决定:建议档和审批档输出答案,草稿档输出草稿,执行档输出动作。这个映射不是文字游戏,它决定了验收标准该写在哪一层。答案的验收看「建议是否正确」,草稿的验收看「初稿是否可审改」,动作的验收看「执行是否可回滚、可审计」。

输出形态最常见的错误,是把动作写成答案。比如「Agent 帮我把价格改了,然后告诉我改了多少」——这已经是动作,不是答案;如果规格里写的是答案,验收就会漏掉回滚和审计。反过来,把答案写成动作也会出问题:一个只给建议的功能,如果规格按动作验收,团队会误以为它可以直接改数据。

写输出形态时,除了三选一,还要写清交付字段。A 的答案必须包含队列、优先级、模板号三个字段;B 的草稿必须包含页数、图表来源、事实核查清单;C 的动作必须包含任务号、动作类型、前后值、回滚句柄。字段是验收的抓手,没有字段,验收只能靠感觉。

验收标准:至少两条,形式与事实

验收标准是四要素里最容易被写虚的一项。常见写法是「回答准确」「内容专业」「用户满意」,这些都不是验收标准,而是愿望。验收标准必须能被机器或人独立判定,并且判定成本可接受。

最低要求是两条:一条管形式,一条管事实。

形式标准检查输出是否满足结构约束。A 的形式标准是「队列属于 8 个定义队列之一」「优先级是 P1–P4 之一」;B 的形式标准是「草稿在 12–20 页之间」;C 的形式标准是「价格变动在配置阈值内」。形式标准通常可以机器判定,成本很低。

事实标准检查输出是否与输入一致。A 的事实标准是「模板号能解析到已发布模板」;B 的事实标准是「每张图能追到数据包来源」;C 的事实标准是「审计日志记录动作前后值」。事实标准有时需要人判断,但它仍然要有明确的判断材料,不能是「看起来对」。

两条标准的分工,是让验收既有硬门槛,又有事实核查。只有形式标准,输出可能格式完美但内容错误;只有事实标准,输出可能内容正确但结构不可消费。两条都有,才能同时管住「能不能用」和「对不对」。

验收标准还要写判定成本。A 的验收发生在人确认的 45 秒里,所以标准必须一眼能看;B 的验收发生在 1.6 小时的审改里,所以标准可以细一些;C 的验收发生在 8% 抽检、单次 12 分钟里,所以标准必须能从事后日志里读出来。判定时间越短,标准越要外显;判定时间越长,标准越要可追溯。

代价上限:人工与系统分开

代价上限回答的是「一次任务最多能花多少」。它必须分两栏写:系统成本上限和人工时间上限。两栏不能合成一个数,因为两者的计价方式不同,混在一起会让节省率失真。

系统成本包括模型调用和基础设施分摊。A 是 0.017 美元/单(模型 0.011 + 基础设施 0.006);B 是 0.32 美元/份(模型 0.198 + 基础设施 0.122);C 是 0.072 美元/任务(模型 0.024 + 基础设施 0.048)。这些是案例事实表里的系统成本,不是人工成本。

人工时间上限是 Agent 介入后的人均耗时。A 是 0.75 分钟/单,B 是 1.6 小时/份(96 分钟),C 是 4.04 分钟/任务。注意 C 的 4.04 分钟包含审计摊销 0.96 分钟和转人工摊销 3.08 分钟;只算审计不算转人工,会把人工上限低估到 0.96 分钟,后面的节省率会从 73.7% 错成 90.8%。

代价上限不是实际成本,而是设计约束。实际成本可以低于上限,但不能高于上限;高于上限时,要么改任务边界,要么改自主档,要么承认这个任务不划算。把上限写成实际值,等于没有上限;把上限写成一个拍脑袋的整数,等于给后面埋一个无法解释的数字。

写代价上限还有一个好处:它强迫团队在规格阶段就把「人工」和「系统」分开。很多项目上线后算不清账,不是因为数字难算,而是因为规格里只有一个「总成本」,无法拆出人工和系统各自占多少。

缺一项会怎样

四要素缺任何一项,后果都能在上线后观察到:

缺失项上线后的表现根因
输入清单模型读了不该读的数据,或任务经常缺上下文权限面和上下文边界没有定义
输出形态验收标准和交付方式不匹配,团队对「做完了」理解不一责任形态没有定义
验收标准评审靠印象,返工无法归因对错没有独立判据
代价上限节省率算不清,人工和系统成本混在一起成本边界没有定义

这四种表现有一个共同点:它们都不是模型问题,而是规格问题。模型升级不会让缺失的输入清单自动出现,也不会让模糊的验收标准变清楚;它只会让问题更晚暴露,代价更高。把四要素落成工程需求与架构的写法,见 需求与案例 ;本节只给出产品侧的最小充分条件。

三案例缩略规格

把四要素套到三个案例上,得到三份缩略规格。它们不是完整需求文档,只是四个问题的答案。

要素A RelayB QuillC Runner
输入清单用户给工单与回复;系统给账户、8 个队列、模板库;禁止用无关支付信息用户给数据包、上月报告、行业模板;系统给渲染器、模板库、核查清单;禁止用未脱敏名单用户给异常队列、动作偏好;系统给目录、价格规则、库存、审计日志;禁止用供应商成本价
输出形态答案:队列 + 优先级 + 模板号草稿:12–20 页报告初稿动作:改价、改库存、下架,带前后值与回滚句柄
验收标准队列属于 8 类之一;优先级 P1–P4;模板号可解析页数 12–20;图表可追源;附事实核查清单动作有回滚句柄或标记不可回滚;日志记前后值;价格在阈值内
代价上限系统 0.017 美元/单;人工 0.75 分钟/单系统 0.32 美元/份;人工 1.6 小时/份系统 0.072 美元/任务;人工 4.04 分钟/任务

这张表可以直接放进评审材料。它的价值不在于数字精确,而在于四个问题都有答案;评审时可以逐格问「这一格为什么这么写」,而不是笼统地问「这个方案行不行」。

代码:四要素检查器

把四要素写成检查器,输入是一份规格草稿,输出是「通过」或「缺哪一项」。检查器不判断任务好不好,只判断规格是否完备。

// file: src/task/03-1-spec-four-parts.ts
// tier: L2
// verify: node --test test/task/03-1-spec-four-parts.test.ts

// 任务规格四要素:输入清单、输出形态、验收标准、代价上限。
// 缺任何一项,规格都不能进入评审;代价上限把人工与系统分开写。

import { QUILL, RELAY, RUNNER } from "../cases.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type PartName = "inputs" | "output" | "acceptance" | "cost-ceiling";

export const PART_ORDER: readonly PartName[] = [
  "inputs",
  "output",
  "acceptance",
  "cost-ceiling",
];

export const PART_LABEL: Record<PartName, string> = {
  inputs: "输入清单",
  output: "输出形态",
  acceptance: "验收标准",
  "cost-ceiling": "代价上限",
};

export type OutputKind = "answer" | "draft" | "action";
export const OUTPUT_KINDS: readonly OutputKind[] = ["answer", "draft", "action"];

export type InputInventory = {
  readonly fromUser: readonly string[];
  readonly fromSystem: readonly string[];
  readonly forbidden: readonly string[];
};

export type CostCeiling = {
  readonly systemCentsPerTask: number;
  readonly humanMinutesPerTask: number;
};

export type SpecDraft = {
  readonly taskId: string;
  readonly inputs: InputInventory;
  readonly output: OutputKind;
  readonly acceptance: readonly string[];
  readonly costCeiling: CostCeiling;
};

export type CompleteSpec = SpecDraft & {
  readonly parts: readonly PartName[];
};

export function checkSpec(draft: SpecDraft): Result<CompleteSpec> {
  const missing: PartName[] = [];
  const errors: string[] = [];

  if (
    draft.inputs.fromUser.length === 0 ||
    draft.inputs.fromSystem.length === 0 ||
    draft.inputs.forbidden.length === 0
  ) {
    missing.push("inputs");
    errors.push("inputs need user, system and forbidden lists");
  }

  if (!OUTPUT_KINDS.includes(draft.output)) {
    missing.push("output");
    errors.push(`output ${String(draft.output)} is not one of answer, draft, action`);
  }

  if (draft.acceptance.length < 2) {
    missing.push("acceptance");
    errors.push("acceptance needs at least two criteria");
  }

  if (
    draft.costCeiling.systemCentsPerTask <= 0 ||
    draft.costCeiling.humanMinutesPerTask <= 0
  ) {
    missing.push("cost-ceiling");
    errors.push("cost ceiling needs system cents and human minutes");
  }

  if (missing.length > 0) {
    return fail(errors.join("; "));
  }

  return ok({ ...draft, parts: PART_ORDER });
}

// 三份缩略规格。系统成本直接由案例事实表的两项相加,人工上限取 Agent 后的人工。
export const CASE_SPECS: Record<"A" | "B" | "C", SpecDraft> = {
  A: {
    taskId: "relay-ticket-triage",
    inputs: {
      fromUser: ["新工单正文", "客户补充回复"],
      fromSystem: ["账户与套餐", "8 个队列定义", "首响模板库"],
      forbidden: ["与分诊无关的支付卡号", "客户未授权的历史订单"],
    },
    output: "answer",
    acceptance: [
      "队列属于 8 个定义队列之一",
      "优先级是 P1 到 P4 之一",
      "模板号能解析到已发布模板",
    ],
    costCeiling: {
      systemCentsPerTask: RELAY.modelCents + RELAY.infraCents,
      humanMinutesPerTask: RELAY.humanMinutes,
    },
  },
  B: {
    taskId: "quill-client-report",
    inputs: {
      fromUser: ["客户数据包", "上月报告", "行业模板"],
      fromSystem: ["图表渲染器", "报告模板库", "事实核查清单"],
      forbidden: ["未脱敏的客户名单", "其他客户的原始数据"],
    },
    output: "draft",
    acceptance: [
      "草稿在 12 到 20 页之间",
      "每张图能追到数据包来源",
      "发布前附事实核查清单",
    ],
    costCeiling: {
      systemCentsPerTask: QUILL.modelCents + QUILL.infraCents,
      humanMinutesPerTask: QUILL.humanMinutes,
    },
  },
  C: {
    taskId: "runner-ops-action",
    inputs: {
      fromUser: ["异常任务队列", "动作偏好"],
      fromSystem: ["商品目录快照", "价格规则", "库存", "审计日志"],
      forbidden: ["供应商成本价", "未授权的批量下架名单"],
    },
    output: "action",
    acceptance: [
      "每个动作有回滚句柄或标记不可回滚",
      "审计日志记录动作前后值",
      "价格变动在配置阈值内",
    ],
    costCeiling: {
      systemCentsPerTask: RUNNER.modelCents + RUNNER.infraCents,
      humanMinutesPerTask: RUNNER.humanMinutes,
    },
  },
};

export function buildAll(): readonly Result<CompleteSpec>[] {
  return [CASE_SPECS.A, CASE_SPECS.B, CASE_SPECS.C].map((spec) =>
    checkSpec(spec),
  );
}

代码里的 checkSpec() 按四要素依次检查:输入清单三类是否都非空、输出形态是否在三种之内、验收标准是否至少两条、代价上限是否同时有系统成本和人工时间。任何一项不满足,返回 fail 并写明原因。

CASE_SPECS 里的三份规格直接从案例事实表取值:系统成本是模型成本加基础设施成本,人工上限是 Agent 介入后的人工时间。这样写有两个好处:第一,数字只有一处来源,不会在文章和代码之间漂移;第二,代价上限天然分成两栏,不会被合并成一个「总成本」。

buildAll() 把三份规格一起跑一遍。测试里会检查三份都通过,也会故意删掉禁止用列表、减到一条验收标准、把系统成本设成 0,确认检查器会在对应位置报错。检查器的价值不是拦住所有坏规格,而是让「缺哪一项」变成可复现的输出。

评审用法

四要素检查器适合在规格评审前跑一遍,不适合在评审会上当众跑。用法建议如下:

  1. 先让产品经理自检。 四要素各写一条,跑一次检查器;不通过的先补,不要带到会上。
  2. 评审时逐要素问依据。 输入清单问「禁止用为什么是这几条」,输出形态问「为什么是答案不是动作」,验收标准问「谁在几分钟内怎么判」,代价上限问「人工和系统为什么这么分」。
  3. 把不通过的项记成待办。 不要在会上现场改规格,改成待办,会后补完再跑一次。
  4. 规格通过后再写提示词。 提示词是实现,规格是边界;边界没定就写提示词,等于在流沙上盖房子。

这套用法和 1.3 的任务规格结构是衔接的:1.3 用 Assessment 和 TaskSpec 把产品假设写成可校验对象,3.1 的四要素是那个对象的内容要求。两者不重复:前者管结构,后者管内容。

小结

  • 任务规格的最小完备集是四要素:输入清单、输出形态、验收标准、代价上限。
  • 输入清单分三类:用户给、系统给、禁止用;缺禁止用最危险,因为它只在审计时暴露。
  • 输出形态只有答案、草稿、动作三种,由自主档决定,不是 UI 形态。
  • 验收标准至少两条:一条管形式,一条管事实;每条都要能独立判定。
  • 代价上限必须把系统成本和人工时间分开写,不能合成一个「总成本」。
  • C Runner 的人工上限 4.04 分钟包含审计 0.96 分钟和转人工 3.08 分钟,漏掉转人工会把节省率算错。
  • 四要素缺任何一项,问题都会在上线后以「模型不准」的假象出现,实际是规格缺失。
  • 规格通过后再写提示词;边界没定,提示词优化没有终点。

阅读导航:上一节:2.3 不该交给 Agent 的任务清单 · 下一节:3.2 从「答得好」到可判定的验收标准 。

常见错误与边界

  1. 把四要素写成四个章节。 四要素是四个必须回答的问题,不是文档目录;每一要素都要有具体内容,不能只写标题。
  2. 输入清单只写用户给。 系统给决定 Agent 能看到多少背景,禁止用决定它不能碰什么;三类缺一,规格都不完整。
  3. 把动作写成答案。 动作会改变外部状态,必须按动作验收,写清前后值、回滚句柄和审计日志;按答案验收会漏掉这些。
  4. 验收标准只写「准确」「专业」。 这些是愿望,不是标准;至少两条,一条管形式,一条管事实,每条都要有判断材料。
  5. 把人工和系统成本合成一个数。 合成之后无法拆出节省率,也无法判断是模型贵还是人贵;两栏必须分开。
  6. 漏掉转人工成本。 C Runner 的人工上限是 4.04 分钟,不是 0.96 分钟;只算审计会把节省率从 73.7% 夸大成 90.8%。

四要素检查器只能保证规格「写全了」,不能保证规格「写对了」。下一节专门处理其中最难的要素:验收标准,看看怎么把「答得好」翻译成可判定的条款。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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