Paperclip 实验特性开关怎么用：官方标为实验性的功能，开之前要想清楚什么
在 Paperclip 里看到一个功能挂着「实验」标记，最现实的问题只有一个：这东西能不能放到每天要跑的流程上。是当成”提前尝鲜、坏了不心疼”的玩具，还是可以让团队的排期、审批、成本核算都依赖它。
官方文档在这件事上没有含糊。关于实验特性的那段定性，几乎是一句话就把责任划清了：实验特性是选择性开启（opt-in）的，提供时不带任何兼容性保证，它们可能随时损坏、变更或被移除，使用风险自负。这不是免责声明式的客套，后面还跟着更具体的展开——连你已经存下来的配置都在”可能变”的范围内。
这篇把文档里散落在几处的实验特性条款拼到一起：官方对「实验性」的准确定义、开关在哪、目前从文档里能反查到哪些东西被标了实验，以及拿状态卡片（Status Cards）这个描述最细的实验特性当样本，看看打开一个实验开关究竟会带进来哪些新变量。先说清楚：以下全部来自官方文档写明的机制与命令，我们没有安装、也没有运行过 Paperclip，界面上具体有几个开关、默认是开是关，文档没写，这里不猜。
一、「实验性」在 Paperclip 文档里到底指什么
官方的说法是：当一个功能被标为实验性，说明 Paperclip 仍在评估这个功能的产品形态和实现细节。展开成三条：
- 该功能尚未进入稳定的操作员契约（stable operator contract）；
- UI、API、CLI、行为、以及已存储的配置都可能随功能演进而改变；
- Paperclip 不承诺兼容性、不承诺回滚、不承诺迁移、也不承诺长期支持。
第二条值得单独拎出来。很多人默认”实验”只是界面还在改，最多接口调整一下。但文档把 stored configuration（已存储的配置）也列进了可变范围——意味着你今天在实验特性里配好的那套东西，本身就不保证下个版本还认。第三条里”不承诺迁移”和”不承诺回滚”是配套的：既不保证帮你把旧配置迁到新形态，也不保证能退回旧行为。
文档随后给了一句结论，句式很硬：如果某个重要工作流需要稳定的行为，就不要依赖实验特性。这句话是整篇文档里唯一的建议，也基本是判断标准本身。
二、开关在哪：一个实例设置入口 + 两条 CLI 命令
官方写明，board operator（看板操作员）从应用里的 Instance Settings > Experimental 启用或停用实验功能。CLI 暴露的是同一个面：
pnpm paperclipai instance settings:experimental
npx paperclipai instance settings:experimental:update --payload-json '{...}'
文档专门补了一句：这两条命令改动的，就是 UI 管理的那批 opt-in 设置。也就是说没有”CLI 专属实验开关”这回事，两边是同一份状态。
在仓库的 CLI 参考里，这两条命令被归在「Instance Settings Commands」一组，和 settings:general、settings:general:update、instance database-backup、instance scheduler-heartbeats 并列，并且紧跟着重复了那句”opt-in、无兼容性保证、风险自负”的免责。从命令分组能看出的一个事实是：实验开关是实例级设置，不是每家公司各配一份。而后面状态卡片的文档里会看到，功能路由本身仍然是公司作用域的——开关在实例层，作用范围在公司层，这两层要分开看。
settings:experimental:update 的入参是 --payload-json，需要你自己知道键名。官方文档没有给出实验开关的完整键名清单，能从别处文档反查到的几个，列在下一节。
三、文档里目前能查到被标为实验的几处
| 对象 | 开关键 / 标记方式 | 文档原口径 |
|---|---|---|
| 状态卡片 Status Cards | enableStatusCards | 明确写成”实验性的公司级持久摘要看板”，从 Instance Settings > Experimental 启用 |
Apps / 连接器的 /apps/* 路由 | enableApps | 连接器手册里写：enableApps 这个实验设置必须打开，/apps/* 路由才可用 |
Gemini CLI 适配器 gemini_local | 无独立开关，条目上直接标 experimental | 适配器总览的原话是”适配器包已存在，但尚未进入稳定的类型枚举”；Docker 文档列本地适配器时同样在它后面标了 experimental |
| 已被移除的实验性内置 Agent | — | 内置 Agent 文档写：启动对账时忽略未知的 marker key，这样可以避免”被移除的实验性内置 Agent”把服务器启动搞挂 |
几点值得展开：
enableStatusCards 关掉时是”不存在”，不是”没权限”。 文档写得很具体：开关关闭时，UI 路由和 REST API 都返回 not found，该功能不会泄漏到未启用的实例上。对做集成的人来说这是个明确信号——你的脚本打到状态卡片接口拿到 404，先查实验开关，别急着怀疑路径写错。
enableApps 是连接器接入链路上的一道前置条件。 连接器手册在讲 Notion 接入的实例前提时，把它和”实例基址必须是 HTTPS 或 loopback HTTP”并列写在一起。也就是说，走连接器这条路，实验开关不是可选的锦上添花，而是路由存不存在的开关。连接器接入的完整链路见 /learn/paperclip-lianjieqi-playbook/。
gemini_local 的实验性是另一种形态。 它没有实例级开关，而是以适配器条目上的标注存在，官方的措辞是包已经有了、但类型枚举还没稳定下来。选适配器时这条要单独记一笔，其余几类适配器的对照见 /learn/paperclip-adapter-zenme-xuan/。
最后一条其实是”实验特性退场”留下的痕迹。 内置 Agent 的启动对账逻辑专门容忍未知 marker key，理由文档直说了，就是防止被移除的实验性内置项阻断服务器启动。这条侧面印证了前面那句”可能被移除”不是修辞。
四、拿状态卡片当样本：打开一个实验开关会多出哪些变量
状态卡片是官方文档里写得最细的实验特性，正好能看清”实验”具体实验在什么地方。注意：以下全部是官方标注为实验性的功能，其行为与默认值随时可能变更。
功能形态确实还在定。 文档里有一个临时的调试视图，暴露 interest prompt、编译出来的查询 JSON 和一次 dry-run 结果，官方直说它存在的原因是”实验性的查询编译器还在调”，并且明确写了”不打算成为长期的操作员工作流”，还列了三条移除条件：编译失败与生效的被观察任务数能从常规卡片抽屉和更新历史里诊断出来、支持人员能通过 API 检查存储的查询和 dry-run 而不必让看板用户去读原始 JSON、状态卡片的 QA 没有依赖该调试 UI 的验收或回归用例。一个功能连自己的调试入口什么时候该拆都写进文档了，说明形态确实没定。
刷新策略是一组带默认值的选择题：
| 策略 | 官方描述 |
|---|---|
| Manual | 默认项。数据变化会把卡片标为陈旧，但 Paperclip 不会自动发起更新 |
| Interval | 每 5、15、30 或 60 分钟检查一次，只有被观察结果确实变了才发起更新 |
| Reactive | 等过防抖窗口后，在发生显著变化时更新。文档写明 v1 默认是 60 秒防抖、每小时至多 6 次更新 |
| Active hours | 配置窗口之外的变化被攒起来，合并到之后的一次更新里 |
| 每日 token 上限 | 卡片用到预算上限后暂停自动工作，手动刷新仍然可用 |
在花模型 token 之前，Paperclip 先用 SQL 做变更检测：调度器 tick 时重跑存下来的查询集，和上一次的指纹比对，把有意义的新增、删除或配置字段变化标为待更新。增量更新只拿到上一版摘要和变化的任务；全量重建则发生在提示词或 Agent 变更后、增量过大、周期性漂移守护、从归档恢复，以及显式全量刷新时。
成本这块，官方给的是规划用的估算，不是承诺。 文档自己写明前提：以下估算基于 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 与成本合计、每次更新的历史、归档卡片的生命周期成本，以及创建流程里的预估。预算与 token 消耗怎么设闸门，见 /learn/paperclip-yusuan-chaozhi/；看板与卡片本身的读法见 /learn/paperclip-yibiaopan/。
Agent 自己建卡是受限的。 有 tasks:assign 权限的 Agent 可以通过 REST API 创建状态卡片，这类卡片在 v1 的创建 UI 里被有意隐藏，但会出现在公司共享看板上。护栏有四条：一个 Agent 只能管理、刷新、重编译、归档或删除自己创建的卡片；一个 Agent 最多创建 20 张卡，删掉一张就释放一个名额；Agent 的 interest prompt 上限 4000 字符，看板侧创建的提示词沿用 20000 字符的通用 API 上限；所有路由仍然是公司作用域，且都在 enableStatusCards 之后。另外，创建卡片会立刻排一次 Summarizer 编译运行，而 Agent 不应该自己去调查询或摘要写回接口——那些接口只接受指派给 Summarizer 的那次生成 issue 与 run。
把上面这些数字串起来看，会发现一个共同点：v1 默认值、v1 Summarizer、v1 创建 UI——文档在措辞上反复挂 v1，等于提前声明这些具体数字是当前版本的，不构成承诺。你在容量规划或成本模型里引用它们时，最好把出处和版本一起记下来。
五、开之前值得逐条过一遍的判断
官方给的使用场景和操作员预期，可以拼成一张自查表：
| 先问自己 | 官方口径 | 答不上来就别开 |
|---|---|---|
| 这个工作流能不能承受损坏与频繁变动？ | 明确要求先判断工作流能否容忍 breakage 或 churn | 不能承受，就用稳定功能顶上 |
| 会不会有别的稳定流程反过来依赖它？ | 要求避免让实验特性成为稳定生产流程的依赖 | 一旦成了依赖，被移除时连累的是上游 |
| 铺开范围控制住了吗？ | 要求在理解它在你公司里的行为之前，保持小范围 | 先在一两个非关键流程上跑 |
| 有人盯变更吗？ | 要求关注发布说明与文档中该功能契约的变化 | 没人盯，就等于把风险留给下一次升级 |
| 停用后能全身而退吗？ | 官方期望里包含”准备好在功能变化或消失时停止使用它” | 退出路径想不清楚，先别接进核心流程 |
对应的”适合用”的场景，官方列了四类：在更大范围铺开前评估一项新能力、测试非关键工作流、能接受版本之间的行为变化、以及做好了随时停用的准备。四条都是同一个意思的不同说法——把实验特性放在你能随时撤掉的位置上。
六、什么时候不该开，以及文档没说的部分
不该开的判断，官方那句话最硬：重要工作流需要稳定行为，就不要依赖实验特性。这里的”依赖”包括间接依赖——比如某个稳定的例行任务把状态卡片的输出当输入，那它就已经依赖上了。
生命周期上有一处值得留意的细节。 状态卡片文档写：归档的卡片会被解除武装（disarmed），恢复其中一张时，它处于陈旧状态并被排入一次全量刷新，而不是悄悄按原来的计划恢复运行。这是实验特性里少见的把状态机边界写清楚的地方，也提示了一点——恢复归档不等于恢复原状，成本会以全量重建的形态重新发生一次。
文档没说的，得诚实标出来：
- 官方文档没有给出实验开关的完整清单，
settings:experimental:update的 payload 键名要靠各功能文档反查（本文表格里的三处是能查到的部分，不代表全部）。 - 实验特性毕业为稳定特性的流程、是否提供配置迁移，官方文档未说明；反过来，文档倒是明确写了不承诺 migration 与 rollback。
- 变更从哪得知，文档只给了一句方向：关注发布说明与文档。没有列出变更通知渠道或废弃期长度。
- 各个开关在实际实例上的默认状态、UI 上如何呈现，我们没有部署过，文档也没写，这里不做描述。
真要动手的话，顺序其实很清楚：先用 instance settings:experimental 把当前状态读出来存一份，再决定改哪个键；开的时候只开一个，配一个非关键的公司或流程去跑；成本敏感的实验特性（状态卡片这种带调度的）先把每日 token 上限和刷新策略压到最保守的一档——Manual 本来就是默认。等你能说清它在你这边的行为，再谈要不要放宽。
延伸阅读
- 从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
- 本专题共 40 篇，完整分组目录见专题页
- Paperclip 适配器怎么选：五类接入方式的前提、限制与官方对照表
- Paperclip HTTP 适配器接入自建 Agent：要实现哪些端点、鉴权与回调契约怎么写
本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档
与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。
我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；
部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。
请以仓库最新内容为准。