Agent 的能力清单该怎么列

2026-08-25

什么时候才需要这份清单

手脚接完的那几天，人是最不需要清单的。哪个工具干什么、哪一步靠谁，全在你脑子里，随手就能改。

问题出现在两个时刻。

一个是某天某一步不动了。我那个写公众号文章的 Agent，卡在等人确认的地方，屏幕上什么都没有。这时候你要判断的是：是它没想明白该往下走，还是消息压根没送到人那边，还是身份授权过期了。这三种情况的排查入口完全不同，但从对话记录里看，它们长得一模一样——都是”没反应”。

另一个是有人问你”你这个 Agent 都用了什么”。你顺口报一串名字，对方点点头，然后就默认这些东西全都在跑。等他自己照着搭一遍，才发现里面有些东西根本不在运行路径上。

这两件事指向同一个缺口：你手上有一堆工具名，但没有一份说明这些名字各自站在什么位置的东西。能力清单要解决的就是这个，它不是给人看你用了多少工具，是给人（包括几周后的你自己）一张能定位的地图。

三个当场能问自己的问题

判断一份清单列得对不对，我不看它列了多少项，看它能不能过这三问。

第一问：把这一项从机器上拿掉，今天这一趟还能不能跑完？

能跑完，说明它不在运行路径上——它是你用来搭这个 Agent 的东西，不是这个 Agent 跑起来的东西。这两类必须分开成两栏，不能混在一起排。跑不完，才归到运行侧。

这一问是整份清单的分水岭，我下一节专门讲为什么。

第二问：出故障的时候，我能不能凭这份清单说出”该去看谁”？

拿”消息没送到”举例。如果清单上只写着这个 Agent”能收发飞书消息”，那么故障时你得从头翻一遍才知道去哪查。如果清单上分了两格，一格写实时收发靠什么、一格写身份和授权靠什么，你看一眼就知道该先验哪一条。

清单的信息量，等于它能帮你砍掉多少个可能性。砍不掉可能性的条目，写了等于没写。

第三问：每一格后面，能不能补上一句”它不负责什么”？

补不出来，通常说明你自己对这一格的边界也是含糊的。而含糊的地方，就是几周后你会记错的地方。

我这份清单实际分成的几格

我给那个 Agent 列的清单是这么分栏的，每一格我都尽量用最短的原话写死，不做发挥。

运行底座。跑这个 Agent 的引擎是什么、挂的是哪个专用 Profile、用的是哪个模型。模型这一格我只留格子不写死型号——型号会换，但清单上必须留着这一格。我担心的是换过模型之后出现的行为变化，因为清单上压根没有这一格，被顺手归到流程写坏了。

设计与维护工具。我这一格写的是：Codex 负责设计维护岗位卡、工作流、流程图、Profile，排错与验收。后面紧跟一句：Codex 不是在线运行引擎。

消息通道。原话是：实时收发由 Hermes Feishu Gateway 完成，不是 lark-cli 轮询。

身份与授权。原话是：lark-cli 负责身份、授权与连通性检查。

外部能力。网页读取/搜索（原文提取与事实核验）、小云雀 xyq-nest-skill（生成原创封面）、本地文件工具。这一格里的每一项，我都在后面挂上它服务于工序的哪一步——读取和搜索服务于资料核验，封面生成服务于封面那一步。挂不上工序的能力，说明它当初是顺手接的，不是这个岗位需要的。

还有一格是链路状态，我认为它比前面几格更容易被漏掉。已经跑通的写在一起：飞书收发、选题分析、方向确认、提纲确认、资料核验、正文撰写、封面生成、本地结构化保存。没跑通的单独列出来，我这里唯一未接通的是微信公众号草稿箱写入，所以状态那一格明确写着：交付终点是”文章和封面已生成并保存”，不是”已进入草稿箱”。

能力清单如果只列”有什么”，读的人会默认这些能力全都是通的。把未接通的那条也放上清单、占一整行，是我这份清单里最不肯省的一行。

为什么”设计维护”和”在线运行”必须分成两栏

这是这份清单最要紧的一刀，也是我把第一问放在最前面的原因。

设计维护工具和运行底座，在自然语言里都叫”我用的工具”。但它们的在场时间完全不同：一个只在你改岗位卡、改工作流、排错验收的时候在场；另一个在 Agent 每一次干活的时候都在场。

混在一起写，会长出一个很难被发现的误解：读的人会以为设计工具也在跟着跑。这个误解一旦成立，后面全是错的——他会以为线上出问题可以靠设计工具即时干预，会以为设计工具的能力就是这个 Agent 的运行时能力，会在移交的时候把设计侧的依赖当成部署前提一起搬过去。

所以我在那一格里，写完职责之后必须再写一句否定句：Codex 不是在线运行引擎。

同样的写法我用在了消息通道上。跟飞书打交道的东西有两个，一个在运行路径上、一个在旁路，光看名字分不出来。所以那两格的原话都带否定：实时收发不是 lark-cli 轮询；lark-cli 负责的是身份、授权与连通性检查。

我的做法是：清单里带否定句的那几行，往往比肯定句那几行更值钱。肯定句告诉你这东西能干什么，否定句挡住的是你即将做出的错误推断。当两个条目的名字看起来像同一类东西、或者一个东西的名气大到会被默认”什么都能干”的时候，那一行就该带上否定句。

这条判据在什么时候不适用

工具只有两三样、且没打算交给别人的时候。 这时候清单的维护成本高于收益，直接看 Profile 更快。我这份清单是在需要跟别人解释、以及需要隔几天回头排错之后才变成必要的，不是一开始就有的。

清单不能当运行依据。 它是给人看的地图，不是配置文件。写在清单上不等于装好了、连通了、授权还没过期。真值只能以实际跑一趟为准，这一点和验收标准是同一个道理：状态描述不是事实，产物才是。

分栏维度是按这个岗位的形态长出来的，不要照抄格数。 我这里会分出”消息通道”和”身份授权”两格，是因为这个岗位有人工闸门，闸门依赖消息送达；会分出”外部能力”，是因为它要读网页、要产图。一个不跟人对话、也不产图的 Agent，硬凑这几格只会得到几个空栏。真正该抄的是那三问，不是我的栏目名。

清单会过期，而且过期得比你以为的快。 我自己的说明书里就有一份写于某一天的状态描述，几天之后里面大部分条目已经不成立了。所以我的判断是：状态类的那几格必须配上写入日期，尤其是”链路状态”那一格——没有日期的状态描述，读的人无从判断它还能不能信。

这篇的判据来自我自己带 Agent 干活的实践，样本有限。它更像一份可以拿去验证的假设，而不是一份可以照抄的规范。