如何启用并配置 Paperclip 状态卡片（Status Cards）的更新策略与 Token 成本？-平芜编程栈

如何启用并配置 Paperclip 状态卡片（Status Cards）的更新策略与 Token 成本？

【免费下载链接】paperclipThe open-source app everyone uses to manage agents at work项目地址: https://gitcode.com/GitHub_Trending/papercl/paperclip

本文对应一个具体任务：在 Paperclip 中启用实验功能 Status Cards（状态卡片），创建第一张卡片，并把它的更新策略（手动 / 定时 / 响应式）与每日 Token 预算配置到位。Status Cards 是一张公司级共享看板，每张卡片用一句自然语言描述你关心的内容（例如 “blocked launch work updated this week — tell me the next decision.”），卡片绑定的 Summarizer Agent（默认内置 Summarizer，也可在创建时或设置中按卡片覆盖）会把这句话编译成有界的公司搜索查询，并持续按同一句话的指令生成有边界的摘要。

需要明确的前提：Status Cards 是实验功能。实验功能文档说明实验功能不受稳定操作契约保护，UI、API、行为与存储配置随时可能变化，Paperclip 不承诺兼容性、回滚或迁移；如果你依赖它承载关键流程，文档建议不要这样做。功能默认关闭（enableStatusCards默认false），关闭时 UI 路由和 REST API 直接返回 not found，不会泄漏到未启用该功能的实例。

第一步：启用 Status Cards

在应用内进入Instance Settings > Experimental，打开Status Cards。CLI 提供同一套开关界面，两个命令管理的是与 UI 相同的 opt-in 设置：

pnpm paperclipai instance settings:experimental npx paperclipai instance settings:experimental:update --payload-json '{...}'

第二条命令里的{...}是你要设置的实验功能开关 JSON，把 Status Cards 对应的enableStatusCards置为true。启用与未启用的判断依据是文档明确给出的：enableStatusCards为 off 时，UI 路由和 REST API 返回 not found；启用后这些路由才可用。

第二步：创建第一张卡片并确认编译

创建入口在 UI 的创建流程里：填一句interestPrompt，创建时界面会给出成本预估（create-flow estimate）。创建后系统立即排队一次 Summarizer 编译运行，把interestPrompt编译成查询集合并生成第一份摘要，没有单独的 summarization prompt 可以追加或替换。

也可以用 API 创建，下面的命令来自status-card-query技能文档（SKILL.md）。其中的$PAPERCLIP_API_URL、$PAPERCLIP_API_KEY、$PAPERCLIP_COMPANY_ID是运行环境提供的变量，$PAPERCLIP_API_URL末尾的/api会被剥掉后拼接完整路径：

PAPERCLIP_API_BASE="${PAPERCLIP_API_URL%/}" PAPERCLIP_API_BASE="${PAPERCLIP_API_BASE%/api}" curl -sS -X POST \ -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ -d '{"interestPrompt":"Blocked or in-review launch work updated this week"}' \ "$PAPERCLIP_API_BASE/api/companies/$PAPERCLIP_COMPANY_ID/status-cards"

创建成功返回201，并且自动排队编译。保存返回的 card id，后续改卡片或手动刷新都要用它。

判断卡片进入了正常状态，看两点：

卡片state从compiling变为active（完整状态枚举是compiling/active/error/paused_budget/paused_hours，见校验器定义）。
更新历史中出现记录：每次生成会以running/ok/failed状态写入 update history，并记录 input/output token 数与成本（数据库 schema中的status_card_updates表）。

第三步：配置更新策略（refreshPolicy）

卡片的核心成本机制是：在花费模型 token 之前先用 SQL 做变更检测。Paperclip 在调度 tick 时重跑存储的查询集，把结果与上一次指纹比较，只有出现有意义的增删或配置字段变化时，才把卡片标记为 pending 并触发更新。更新方式分增量与全量：增量更新只带上一份摘要和变化的任务；提示词或 Agent 变更、大 delta、周期性漂移防护、从归档恢复、以及显式全量刷新都会走 full rebuild。归档的卡片会被解除武装，恢复后处于 stale 状态并调度一次全量刷新，而不是悄悄沿用旧计划。

刷新策略由卡片的refreshPolicy字段控制，创建时默认是manual。文档定义的各模式：

Manual：默认。变化只会让卡片变 stale，Paperclip 不会启动任何自动更新。
Interval：按 5、15、30 或 60 分钟检查，且只有被监视的结果确实变化时才启动更新。
Reactive：等待防抖窗口，再在显著变化后更新。v1 默认是 60 秒防抖、每小时最多 6 次更新。
Active hours：把配置时间窗外的变化攒批到稍后的更新。
Daily token caps：卡片达到预算后暂停自动工作，手动刷新仍然可用。

refreshPolicy的完整字段来自 statusCardRefreshPolicySchema：mode（manual/interval/reactive，默认manual）、intervalMinutes（interval 模式必填，正整数）、debounceSeconds（reactive 模式必填，正整数）、maxUpdatesPerHour、triggers、activeHours、dailyTokenCap。其中triggers指定哪些变化算数，默认statusTransitions、membershipChanges、humanComments、assigneeChanges均为true，anyUpdate为false。

创建卡片时即可带出策略。例如 interval 模式，每 15 分钟检查，并把自动更新限制在工作时段、设每日 Token 上限：

{ "interestPrompt": "Blocked or in-review launch work updated this week", "refreshPolicy": { "mode": "interval", "intervalMinutes": 15, "activeHours": { "start": "09:00", "end": "18:00", "timezone": "Asia/Shanghai" }, "dailyTokenCap": 200000 } }

reactive 模式的对应写法：

{ "refreshPolicy": { "mode": "reactive", "debounceSeconds": 60, "maxUpdatesPerHour": 6 } }

两点适用条件：activeHours的start/end必须匹配HH:MM格式，timezone必须是合法的 IANA 时区标识，否则校验报错（Invalid timezone identifier）；dailyTokenCap是正整数，达到上限后卡片进入paused_budget状态。已有的卡片用PATCH /api/status-cards/$STATUS_CARD_ID提交包含refreshPolicy的 JSON 即可调整。手动刷新走POST /api/status-cards/$STATUS_CARD_ID/refresh，请求体{"full": false}表示增量，{"full": true}表示强制全量重建。

第四步：核对 Token 成本与验证结果

文档给出的是基于 v1 Summarizer 的 haiku 级默认模型的规划估算，供应商计价和实际选择的模型都会改变真实成本，下表按原文呈现（估算值）：

工作类型	估算用量	估算成本
增量更新	1–2k input，约 0.3k output tokens	$0.003–0.006
繁忙的 15 分钟卡片持续 9 小时	约 10–18 次变更门控更新	$0.03–0.10/天
Reactive 最坏情况	每小时 6 次更新持续 9 小时	$0.15–0.35/天/卡片
全量重建	5–8k input，约 1k output tokens	$0.01–0.02
变更检测	仅 SQL	$0

验证方式有四个观察点，全部来自文档描述的实际行为：

看板显示当天的 token 与成本总计、每次更新的历史、归档卡片的历史总成本，以及创建流程里的预估。
每次完成的生成会写入常规成本账本（cost ledger），并复制进 status-card 更新历史；每次记录带inputTokens、outputTokens、costCents、model、changeSummary和status。
卡片达到dailyTokenCap后自动工作暂停（state变为paused_budget），手动刷新仍可执行——如果预算设得过低，你会看到这个状态而不是更新失败。
实验期间有一个临时 debug tab，展示 interest prompt、编译后的 query JSON 和 dry-run 结果，用于在查询编译器调优阶段检查卡片编译是否正确；文档明确说明它不打算成为永久运维流程，支持工具在 tab 移除后仍可通过 API 检查存储的查询和 dry-run。

可选分支：由 Agent 创建卡片

拥有tasks:assign权限的 Agent 可以通过 REST API 创建卡片。Agent 创建的卡片刻意不出现在 v1 创建 UI 中，但会出现在共享公司看板上。附加护栏（文档原文限制）：

Agent 只能管理、刷新、重编译、归档或删除自己创建的卡片；
每个 Agent 最多创建 20 张卡片，删除卡片会释放名额；
Agent 的 interest prompt 上限 4,000 字符，看板侧创建的 prompt 保留通用的 20,000 字符 API 上限；
所有路由仍是公司级作用域，并且都位于enableStatusCards之后；
创建卡片会立即排队 Summarizer 编译运行；Agent 不应自行调用/query和/summary写回端点，这两个端点只接受被分配的 Summarizer 生成 issue 和 run。

可复制的 Agent API 示例见 status-card-query 技能。