Paperclip 仪表盘与状态卡片怎么读：五组指标的口径、数据来源与刷新机制
一家跑着十几个 Agent 的「自治公司」，最容易出问题的地方不是某个 Agent 崩了，而是你根本不知道它崩了。任务卡在 in progress 三天没人动，某个 Agent 悄悄把当月预算烧到 100% 然后自己停了，你却以为它还在干活。
Paperclip 的仪表盘就是解决这件事的。但仪表盘这种东西有个通病：一屏数字看着一目了然，实际每个数字背后的口径你都说不清——「停滞任务」到底停多久算停滞？「成本汇总」是当月还是当天？「Agent 活跃数」里的 running 和 active 是一回事吗？口径不清，看板就成了心理安慰。
这篇把官方文档里写明的口径逐条拆开，包括仪表盘本体、背后那个 API，以及另一套容易和它混淆的东西——实验特性「状态卡片（Status Cards）」。需要先说清楚：以下全部来自 Paperclip 官方文档，我们没有部署运行过这套系统，所以不会讲任何界面长相、按钮位置或者实测数字。
仪表盘上到底是哪五组数
官方文档对仪表盘的定位是「你这家自治公司的实时健康概览」。它展示的内容固定为五组：
| 指标组 | 官方口径 |
|---|---|
| Agent status | 按状态统计 Agent 数量：active、idle、running、error |
| Task breakdown | 按状态统计任务数量：todo、in progress、blocked、done |
| Stale tasks | 处于 in progress 但长时间没有更新的任务 |
| Cost summary | 当月支出对预算，以及消耗速率（burn rate） |
| Recent activity | 公司范围内最近发生的变更（mutations） |
这里有一处值得先记下来的细节：仪表盘指南和 API 文档给出的枚举值并不完全一致。指南里 Agent 状态写的是 active / idle / running / error 四个，API 文档多了一个 paused；任务状态指南写的是 todo / in progress / blocked / done，API 文档则是 backlog / todo / in_progress / blocked / done 五个，且用的是下划线写法。
这不是文字游戏。如果你要拿这个接口做二次开发——比如把公司健康度接到自己的告警系统——枚举值对不上就会漏计或者报错。以 API 文档的那份为准更稳妥，因为它描述的是返回结构；但真正落地前还是得实际调一次看返回值。官方文档没有对这处差异做说明。
顺带一提，「停滞任务」的具体阈值，两份文档都只写到「in progress 且近期无活动」，没有给出具体是多少小时或多少天，也没有说这个阈值能否配置。这属于官方文档未说明的部分，别自己脑补一个数字写进运维手册。
一个 GET 就能把这五组数取全
仪表盘不是只能在网页里看，同一份数据有对应的接口：
GET /api/companies/{companyId}/dashboard
文档明确写了这是「一次调用拿到一家公司的健康摘要」，返回内容就是上面那五组：Agent 按状态计数、任务按状态计数、停滞任务、成本汇总、近期活动。
有意思的是官方给这个接口列的三类使用者，能反过来帮你理解 Paperclip 的设计思路：
- Board operator（看板操作者，也就是人）：在网页端做一次快速健康检查。
- CEO agent：在每次心跳（heartbeat）开始时建立态势感知。
- Manager agent：查看团队状态、识别阻塞点。
也就是说，这个接口不只是给人看的面板后端，它同时是 Agent 自己的「环境感知输入」。CEO 类 Agent 每轮心跳先拉一次仪表盘，再决定这一轮干什么——这就是为什么它被设计成单次调用返回全景，而不是让调用方拼五个接口。Agent 心跳与卡死排查另有专文，见 Agent 不干活时的心跳与看门狗排查。
三个真正需要盯的数
五组数不是同等重要。官方文档专门列了「Key Metrics to Watch」，只挑了三个：
Blocked tasks（被阻塞的任务）。文档的说法很直白：这些需要你介入。做法是去读任务下面的评论，搞清楚到底卡在哪，然后采取行动——重新指派、解除阻塞，或者给出审批。审批链路本身是另一套机制，不在仪表盘这一层解决。
Budget utilization（预算利用率）。这条有一个硬机制：Agent 在预算到 100% 时会自动暂停。文档给的运营建议是，看到某个 Agent 逼近 80% 就该做决定了——是给它加预算，还是重新排它手上的活的优先级。等到 100% 才发现，它已经停了。预算与「token 工资」的完整设定见预算与超支控制。
Stale work（停滞的活）。文档给的判断链条是：处于 in progress 却没有近期评论的任务，可能意味着 Agent 卡住了；这时候去查这个 Agent 的运行历史（run history）里有没有报错。注意这是个「可能」，不是确定性结论——一个 Agent 埋头跑长任务不吭声，和它真的挂了，在仪表盘上是同一个样子，得下钻到 run history 才能分辨。
至于「近期活动」这一组，仪表盘上给的是最新变更的概览，完整的审计追溯是另一套东西，见活动日志与审计追溯。
状态卡片：另一套东西，别和仪表盘混为一谈
Paperclip 里还有一个叫「状态卡片」的功能，容易被当成仪表盘的一部分，其实机制完全不同。
首先，它是实验特性。需要在 Instance Settings > Experimental 里打开 Status Cards。文档写得很清楚：当 enableStatusCards 处于关闭状态时，相关的 UI 路由和 REST 接口一律返回 not found——这个功能不会泄漏到没启用的实例里。
其次，它的产出方式和仪表盘正相反。仪表盘是结构化计数，状态卡片是用一句话喂出来的持续摘要。你给一张卡片写一条消息，官方给的例子是这样一句：本周更新过的、被阻塞的发布相关工作，告诉我下一个决策是什么。卡片背后的 Agent（默认是内置的 Summarizer，也可以在创建时或设置里按卡片单独指定）会把这段自然语言编译成一组有界的公司搜索查询，把这组「有效查询集」存下来，之后每次写摘要都拿同一条消息当指令。文档特别强调：没有另一个可以追加或替换的摘要提示词，就这一条。
刷新策略：先用 SQL 判断变没变，再决定要不要花 token
状态卡片最值得学的是它的省钱设计。它在调用模型之前先做 SQL 层面的变更检测：调度器每次 tick 时重跑存好的查询集，把结果和上一次的指纹（fingerprint）比对，只有出现了有意义的新增、删除或者配置字段变化，才把卡片标记为待更新。
在这之上有四种刷新策略：
| 策略 | 行为 |
|---|---|
| Manual（默认） | 有变化只把卡片标为 stale，Paperclip 绝不自动发起更新 |
| Interval | 每 5、15、30 或 60 分钟检查一次，只在被监视的结果发生变化时才发起更新 |
| Reactive | 等过防抖窗口后，在显著变化时更新。v1 默认防抖 60 秒，每小时最多 6 次 |
| Active hours | 配置窗口之外发生的变化，攒到窗口内再一起更新 |
另外还有一层「每日 token 上限」：卡片达到自己的预算后，自动更新停摆，但手动刷新仍然可用。
更新分增量和全量两种。增量更新只把上一版摘要和变化了的那些任务喂进去。而以下几种情况会触发全量重建：提示词或 Agent 变更、变化量过大、周期性的漂移防护（drift guard）、从归档恢复，以及显式的全量刷新。归档掉的卡片是「解除武装」状态，恢复之后不会偷偷按老日程继续跑，而是留在 stale 状态并排一次全量重建。这个处理挺讲究——从归档里恢复出来的卡片，它的历史指纹已经不可信了。
官方给的成本估算，以及它的前提
文档给了一张估算表，但把前提写在了前面：这些是规划用的估算，基于 v1 Summarizer 默认的 haiku 级模型；供应商定价和所选模型都会改变实际成本。换句话说这张表是用来做量级判断的，不是账单。
| 工作类型 | 估算用量 | 估算成本 |
|---|---|---|
| 增量更新 | 1–2k 输入，约 0.3k 输出 token | $0.003–0.006 |
| 繁忙的 15 分钟卡片跑 9 小时 | 约 10–18 次经变更门控的更新 | $0.03–0.10/天 |
| Reactive 最坏情况 | 每小时 6 次、连续 9 小时 | $0.15–0.35/天/卡 |
| 全量重建 | 5–8k 输入，约 1k 输出 token | $0.01–0.02 |
| 变更检测 | 纯 SQL | $0 |
每次完成的生成都会走正常的成本账本计入，同时复制一份到状态卡片的更新历史里。看板上能看到当日 token 与成本合计、每次更新的历史、归档卡片的生命周期总成本，以及创建流程里的预估。
真正该注意的是最后一行：变更检测本身是 $0。也就是说 Interval 策略把检查频率调高，并不直接等于花钱，花钱的是「检测到变化后发起的那次更新」。这跟直觉里「查得越勤越贵」是反过来的。
Agent 自己建卡片，护栏有哪些
带有 tasks:assign 权限的 Agent 可以通过 REST 接口创建状态卡片。这类 Agent 创建的卡片在 v1 的创建界面里是刻意隐藏的，但会出现在公司共享的看板上。
官方列的额外护栏有这么几条：
- Agent 只能管理、刷新、重新编译、归档或删除自己创建的卡片；
- 单个 Agent 最多创建 20 张卡片，删掉一张就腾出一个名额；
- Agent 的兴趣提示词上限 4,000 字符；
- 看板侧创建的提示词沿用 API 通用的 20,000 字符上限；
- 所有路由依然是公司作用域，并且仍然受
enableStatusCards开关控制。
还有两条实现约束：创建卡片会立刻给 Summarizer 排一次编译运行；Agent 不应该自己去调查询或摘要写回的接口，那些接口只接受被指派的 Summarizer 生成 issue 和 run。官方另外提到仓库里带了一个 status-card-query skill，是可以直接抄的 Agent API 用法示例。
还有一个临时的调试视图
文档里承认调试标签页是临时的：它暴露兴趣提示词、编译出来的查询 JSON 和一次 dry-run 结果，用途是在实验期调试查询编译器，官方明说它不打算变成常驻的操作者工作流。
移除条件官方也写死了三条，同时满足才能拿掉：编译失败和有效被监视任务数能从常规卡片抽屉和更新历史里诊断出来；支持团队能通过 API 检查存储的查询并做 dry-run，而不需要看板用户去读原始 JSON；状态卡片的 QA 里没有依赖这个调试专用界面的待办验收或回归用例。即便这个标签页被移除，底层 API 仍可能保留给支持工具用。
对使用者的实际含义是：现在能从调试视图里看到的东西，将来可能换个位置，别把它写进你团队的固定 SOP。
什么时候这套东西不够用
别指望仪表盘替你判断 Agent 死没死。 停滞任务只是一个信号，官方给的下一步也是让你去看 run history。仪表盘做的是「让你知道该去哪看」，不是「告诉你结论」。
状态卡片是实验特性，别拿它当生产依赖。 关闭开关时接口直接 not found，调试视图明确写了会移除，v1 的一些默认值（60 秒防抖、每小时 6 次、20 张卡片）也是标了 v1 的——这些都是可能变的。要不要开，得先想清楚它坏掉那天你的流程会不会跟着停。实验特性的整体开关逻辑见实验特性开关怎么用。
成本表只能做量级估算。 前提写在文档里：haiku 级默认模型、v1 的 Summarizer。你换了模型或者供应商调价，这张表就不成立了。要拿真数就去查成本账本。
几个关键参数官方没写。 停滞任务的判定阈值、仪表盘实时更新的具体传输方式、Agent 状态枚举两份文档不一致该以哪份为准——这三处文档里都没有给出答案，接接口之前建议先实际调一次确认。
延伸阅读
- 从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
- 本专题共 40 篇，完整分组目录见专题页
- Paperclip 公司配置怎么导出导入：包结构、collision 策略与「导入后不自动跑」
- Paperclip 实验特性开关怎么用：官方标为实验性的功能，开之前要想清楚什么
本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档
与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。
我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；
部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。
请以仓库最新内容为准。