以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。
三个案例分别是 A Relay(Northwind 的客服工单分诊 Agent)、B Quill(Meridian 的客户报告起草 Agent)和 C Runner(Kettle 的电商运营任务执行 Agent);后文简称 A、B、C。
当一个组织有了第二个 Agent 产品,最先出现的不是平台,而是一句反复被问的问题:「这个能力我们是不是已经有了?」如果没有一份能回答这个问题的目录,团队会靠记忆、聊天记录和口口相传来判断,结果通常是两种:要么重复建设,要么把一个能力硬塞给不合适的场景。
能力目录就是为这个问题准备的。它不是能力清单,不是技术文档,也不是平台功能列表。它是一份对外承诺:这个能力做什么、给谁、多久返回、谁负责、用什么标准判断它有没有变差。五个字段缺一个,能力就会在某个方向上变成无人负责的公共品。
三个案例的目录成熟度差别很大:A 没有目录,B 只有半页文档,C 有包含 SLA 与责任人的完整目录。这个差别不是文档习惯,而是组合阶段的差别:A 只有一个产品,目录可以装在负责人脑子里;B 有两个产品,必须有半页纸让两个产出团队对齐;C 有三条任务线和一层平台,目录必须能支撑跨团队查询和审计。
目录不是文档,是契约
普通文档描述「我们做了什么」,能力目录承诺「你可以指望什么」。前者可以随时补充,后者一旦登记就要被遵守。这个区别决定了目录不能写成散文,而要写成字段。
一个能力被登记进目录,意味着四件事:使用者可以按 SLA 安排自己的流程;责任人承诺在能力退化时处理;评测基线可以在模型或提示词变更后复跑;其他团队在立项时可以先查目录,而不是先找熟人。四件事里任何一件做不到,这个条目就只是文档,不是契约。
目录也不应该记录实现细节。提示词版本、模型名称、工具调用链属于实现,应该放在能力条目背后的工程系统里。把实现写进目录,会让目录在每次模型升级时过期,最后没人愿意维护。目录只回答产品问题:做什么、给谁、多久、谁负责、怎么判断好坏。
五个字段
五个字段对应五个产品问题,缺任何一个,能力都会在某个方向上失去约束。
| 字段 | 回答的问题 | 缺失后的后果 |
|---|---|---|
| 做什么 | 这个能力的边界在哪里,不做什么 | 团队重复建设,或把无关任务塞进来 |
| 给谁 | 谁使用、谁验收、成功由谁定义 | 验收对象不明,成功标准随使用者变化 |
| SLA | 多久返回,超时怎么办 | 用户无法安排等待与接管,时延期望失控 |
| 责任人 | 谁对能力退化负责 | 出问题时没人修,能力变成公共品 |
| 评测基线 | 用什么指标判断它有没有变差 | 模型或提示词变更后无法发现退化 |
做什么要写成一句可否定的话。比如「新工单的队列归属、P1–P4 优先级与首响模板建议」,这句话同时说明了它不做什么:不回复客户、不关闭工单、不改订单。边界越具体,目录越有用;写成「智能处理工单」等于没写。
给谁要落到岗位和人数,而不是部门名。「支持团队 9 人」比「客服部门」更能约束验收;因为人数决定了培训、通知预算和接管能力。给谁还包括「谁验收」:使用者不一定是验收人,支持团队用建议,支持运营负责人定验收线。
SLA 要区分机器时间和人工时间。A 的 18 秒是模型与系统耗时,45 秒是人确认耗时,产品级承诺是 63 秒;如果把 18 秒写成 SLA,用户会以为整件事 18 秒完成,实际还要加上人的确认。B 的 11 分钟是初稿生成时间,不含 1.6 小时审改;C 的 2.4 分钟是任务执行时间,不含 0.96 分钟审计摊销。SLA 写错,后面所有时间账都会错。
责任人要写角色,不写人名。角色在组织调整后仍然有效,人名会过期。责任人不是「出事后背锅的人」,而是「能力退化时有权排期修复的人」;没有排期权,责任人只是名义上的。
评测基线要包含至少一个主指标和一个错误指标。只有主指标,能力会在边缘案例上退化;只有错误指标,能力会因为过度保守而变得没用。A 的主指标是采纳率 78%、错误指标是采纳后错误率 2.9%;B 的主指标是一次采纳率 63%、错误指标是事实错误率 4.6%;C 的主指标是自动完成率 78%、错误指标是审计错误率 1.7%。
三案例各登记一条
把三个案例各登记一条,可以看出目录字段在不同责任档下的写法差异。
| 案例 | 做什么 | 给谁 | SLA | 责任人 | 评测基线 |
|---|---|---|---|---|---|
| A Relay | 工单队列、P1–P4 优先级、首响模板建议 | Northwind 支持团队 9 人 | 63 秒(18 秒生成 + 45 秒确认) | 支持运营负责人 | 采纳率 78%、分诊正确率 91.4%、采纳后错误率 2.9% |
| B Quill | 12–20 页客户月报初稿 | Meridian 咨询团队 15 人 | 660 秒(初稿生成 11 分钟) | 咨询交付负责人 | 一次采纳 63%、小改 28%、返工 9%、事实错误 4.6% |
| C Runner | 上下架检查、价格异常、库存跟进 | Kettle 运营团队 24 人 | 144 秒(单任务执行 2.4 分钟) | 运营平台负责人 | 自动完成 78%、审计错误 1.7%、可回滚 86%、不可回滚 0.238% |
三条目录的写法差异,正好对应三种责任。A 的 SLA 必须把人工确认算进去,因为人是决策链的一环;B 的 SLA 只承诺初稿生成,因为审改时间由报告质量决定,不能由产品承诺;C 的 SLA 只承诺单任务执行,因为审计是抽检,不是每个任务都发生。
评测基线也随责任变化。A 看建议对不对,B 看草稿要不要大改,C 看动作错没错。三个错误指标不能互相替代:A 的 2.9% 是采纳后仍出错,B 的 4.6% 是审改时发现的事实错误,C 的 1.7% 是审计发现的错误。把它们放进同一张跨产品排行榜,会得出错误结论,因为分母和发现方式都不同。
缺字段会发生什么
缺字段的后果不是「文档不完整」,而是某个具体角色失去依据。可以逐项看。
缺做什么,团队会在立项时重复建设。两个团队各自做一个「工单分类」能力,一个叫分诊、一个叫路由,半年后才发现输入输出几乎一样,但字段口径已经分叉。目录的第一价值不是复用,而是防止这种无意识的重复。
缺给谁,验收会变成平均分。A 的支持团队、B 的咨询团队、C 的运营团队对「好」的定义不同;没有明确的使用者和验收人,产品会用一张综合表验收,三个团队都不满意。
缺SLA,用户无法安排等待。A 的工单分诊如果只写「快速返回」,支持人员不知道能不能等;B 的报告如果只写「异步生成」,咨询顾问无法安排客户会议;C 的任务如果只写「后台执行」,运营无法决定什么时候看审计。
缺责任人,能力退化时没人修。事实表第十节里,A 与 B 的责任地图中「做了但没人知道」一格都是未定义;这不是说他们一定没人管,而是说责任没有写下来。没有写下来的责任,在组织调整或人员离职后就会消失。
缺评测基线,模型升级时无法判断好坏。Agent 产品的能力会随模型、提示词、工具和数据的变更而漂移;没有基线,团队只能靠用户投诉发现退化。C 的审计错误率 1.7% 和不可回滚错误率 0.238% 之所以重要,是因为它们能在发布前回答「这次改动有没有让不可回滚错误变多」。
目录的维护节奏
目录不是写完就结束的文档。它至少要在三种时刻更新:能力边界变化时、SLA 变化时、评测基线变化时。三种更新对应三种评审,不能合并成一次「文档更新」。
能力边界变化,通常意味着产品组合变化:一个能力从「只做建议」扩展到「可以直接执行」,责任档变了,目录条目要重写,不能只改一句话。SLA 变化,通常意味着基础设施或人工流程变化:模型提速、确认步骤增加、审计比例调整,都会改变用户能指望的时间。评测基线变化,通常意味着模型或评测集变化:换了模型、加了新样本、调整了阈值,都要记录版本,否则下一次退化无法归因。
维护责任应该跟着责任人走。责任人每季度至少复看一次条目,确认 SLA 仍然可达、评测基线仍然有效、边界没有悄悄扩张。这个节奏听起来很轻,但它能防止目录变成「上线时写一次、以后再也没人看」的文档。
写成可审计的模型
下面这个模型把五个字段做成可审计的结构:每个条目缺哪个字段、缺了之后有什么风险、整个目录的完整度如何,都能一次算出来。三个案例各登记一条,数字来自统一事实表。
// file: src/scale/02-1-capability-catalog.ts
// tier: L2
// verify: node --test test/scale/02-1-capability-catalog.test.ts
// 能力目录的五个产品字段:做什么、给谁、SLA、责任人、评测基线。
// 缺任何一个字段,能力都会在某个方向上变成无人负责的公共品。
export type EvalUnit = "ratio" | "seconds" | "minutes";
export type EvalMetric = {
readonly name: string;
readonly value: number;
readonly unit: EvalUnit;
};
export type CatalogEntry = {
readonly id: string;
readonly what: string;
readonly forWhom: string;
readonly slaSeconds: number;
readonly slaNote: string;
readonly owner: string;
readonly evals: readonly EvalMetric[];
};
export type CatalogField =
| "what"
| "forWhom"
| "slaSeconds"
| "owner"
| "evals";
export const REQUIRED_FIELDS: readonly CatalogField[] = [
"what",
"forWhom",
"slaSeconds",
"owner",
"evals",
];
export const MISSING_RISK: Record<CatalogField, string> = {
what: "边界不清,团队会重复建设或把无关任务塞进来",
forWhom: "验收对象不明,成功标准随使用者变化",
slaSeconds: "没有时延承诺,用户无法安排等待与接管",
owner: "出现退化时没人负责修复,能力变成公共品",
evals: "无法判断模型或提示词变更是否让能力变差",
};
export function auditEntry(entry: Partial<CatalogEntry>): {
readonly complete: boolean;
readonly missing: readonly CatalogField[];
readonly risks: readonly string[];
} {
const missing: CatalogField[] = [];
if (!entry.what || entry.what.trim() === "") missing.push("what");
if (!entry.forWhom || entry.forWhom.trim() === "") missing.push("forWhom");
if (!entry.slaSeconds || entry.slaSeconds <= 0) missing.push("slaSeconds");
if (!entry.owner || entry.owner.trim() === "") missing.push("owner");
if (!entry.evals || entry.evals.length === 0) missing.push("evals");
return {
complete: missing.length === 0,
missing,
risks: missing.map((field) => MISSING_RISK[field]),
};
}
export function auditCatalog(
entries: readonly Partial<CatalogEntry>[],
): {
readonly total: number;
readonly complete: number;
readonly missingByField: Record<CatalogField, number>;
} {
const missingByField: Record<CatalogField, number> = {
what: 0,
forWhom: 0,
slaSeconds: 0,
owner: 0,
evals: 0,
};
let complete = 0;
for (const entry of entries) {
const audit = auditEntry(entry);
if (audit.complete) complete += 1;
for (const field of audit.missing) missingByField[field] += 1;
}
return { total: entries.length, complete, missingByField };
}
export function formatSla(seconds: number): string {
return `${(seconds / 60).toFixed(2)} 分钟`;
}
export const CATALOG: readonly CatalogEntry[] = [
{
id: "relay-ticket-triage",
what: "新工单的队列归属、P1–P4 优先级与首响模板建议",
forWhom: "Northwind 支持团队 9 人",
slaSeconds: 63,
slaNote: "18 秒模型生成 + 45 秒人工确认",
owner: "支持运营负责人",
evals: [
{ name: "建议采纳率", value: 0.78, unit: "ratio" },
{ name: "分诊正确率", value: 0.914, unit: "ratio" },
{ name: "采纳后仍出错率", value: 0.029, unit: "ratio" },
],
},
{
id: "quill-report-draft",
what: "客户月报初稿,12–20 页 Markdown 加图表",
forWhom: "Meridian 咨询团队 15 人",
slaSeconds: 660,
slaNote: "单份初稿生成 11 分钟",
owner: "咨询交付负责人",
evals: [
{ name: "一次采纳率", value: 0.63, unit: "ratio" },
{ name: "小改率", value: 0.28, unit: "ratio" },
{ name: "返工率", value: 0.09, unit: "ratio" },
{ name: "事实错误率", value: 0.046, unit: "ratio" },
],
},
{
id: "runner-ops-execution",
what: "上下架检查、价格异常、库存跟进三类运营任务的执行",
forWhom: "Kettle 运营团队 24 人",
slaSeconds: 144,
slaNote: "单任务执行 2.4 分钟",
owner: "运营平台负责人",
evals: [
{ name: "自动完成率", value: 0.78, unit: "ratio" },
{ name: "审计发现错误率", value: 0.017, unit: "ratio" },
{ name: "错误中可回滚比例", value: 0.86, unit: "ratio" },
{ name: "不可回滚错误率", value: 0.00238, unit: "ratio" },
],
},
];
auditEntry 逐项检查五个字段:字符串为空、SLA 小于等于 0、评测列表为空,都算缺失;每个缺失字段映射到一条具体风险。auditCatalog 汇总整份目录的完整度和各字段缺失次数,适合在季度评审时看趋势:如果 owner 连续两个季度缺失最多,说明责任分配是系统性问题,不是个别条目忘了填。
CATALOG 里的三条条目展示了三种写法。A 的 SLA 是 63 秒,由 18 秒生成和 45 秒确认相加;B 是 660 秒,即 11 分钟;C 是 144 秒,即 2.4 分钟。评测基线保留了主指标和错误指标,C 还保留了可回滚比例和不可回滚错误率,因为执行档的审计需要能回答「错了能不能撤回」。
模型不评价条目写得好不好,只回答字段齐不齐。这个边界很重要:目录审计是结构检查,不是产品评审;字段齐全但内容空洞的条目仍然可能没用,但字段缺失的条目一定无法被依赖。先用模型保证结构,再用评审保证内容。
从目录到平台边界
能力目录回答「有什么、给谁、谁负责」,下一个问题自然是「这些能力由谁维护」。当共享能力变多,平台团队和业务团队会开始争论某个东西该归谁:队列规则、优先级映射、模型配额、审计日志,哪些进平台,哪些留业务?
这个问题的答案不能靠组织架构图,而要靠一张边界表。下一节会把平台与业务的职责拆成契约、配额、任务、验收四类,用 A Relay 的 8 个工单队列和 P1–P4 优先级做例子,说明为什么有些东西看起来像平台能力,实际上必须留在业务。
小结
- 能力目录是契约,不是文档;登记意味着使用者可以指望 SLA、责任人可以承诺修复、评测可以复跑。
- 五个字段是做什么、给谁、SLA、责任人、评测基线;每个字段对应一个具体的产品约束。
- 做什么要写成可否定的一句话,给谁要落到岗位和人数,SLA 要区分机器时间与人工时间。
- 责任人写角色不写人名,评测基线至少包含一个主指标和一个错误指标。
- A 的 SLA 是 63 秒(18 秒生成 + 45 秒确认),B 是 660 秒(11 分钟),C 是 144 秒(2.4 分钟)。
- 缺字段的后果是具体角色失去依据:重复建设、平均分验收、等待失控、无人修复、退化不可见。
- 目录要在能力边界、SLA、评测基线变化时更新,责任人每季度至少复看一次。
- 目录审计只回答字段齐不齐,内容好不好仍要靠产品评审;两者不能互相替代。
阅读导航:上一节:1.3 三案例的产品组合决策 · 下一节:2.2 平台与业务的边界 。
常见错误与边界
- 把目录写成能力清单。 清单只列名字,目录要写边界、对象、SLA、责任和评测;没有后四项,清单无法被依赖。
- 把机器耗时当成 SLA。 A 的 18 秒只是生成时间,用户实际等待还包括 45 秒确认;SLA 写错会让时间账整体失真。
- 责任人写人名。 人名会随组织调整过期,角色才能持续;责任人还要有排期修复的权力。
- 评测基线只写主指标。 只有采纳率没有错误率,能力会在边缘案例上退化;只有错误率没有主指标,能力会变得过度保守。
- 把目录当成一次性文档。 能力边界、SLA、评测基线变化时都要更新;不更新的目录比没有目录更危险,因为它给人错误的确定感。
- 用跨产品排行榜比较错误率。 A 的 2.9%、B 的 4.6%、C 的 1.7% 分母和发现方式不同,不能直接排名;目录应保留口径说明。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。