create-external-bot-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create an External Bot Integration

创建外部 Bot 集成

Make an existing external agent a useful Paperclip participant: Paperclip can assign work to it, and it can initiate governed work from its own conversation. It uses its relevant native capabilities, returns inspectable results to Paperclip, and participates in normal admission, authority, and finalization.
This workflow incorporates the September 30–October 9, 2026 Dot integration. Provider facts and code paths in the references are dated evidence, not a claim that every future bot supports the same APIs. Verify the current implementation and official provider documentation before choosing a transport or changing code.
让现有的外部 agent 成为真正有用的 Paperclip 参与者:Paperclip 可以向它分配工作,它也可以从自己的对话中发起受治理的工作。它使用相关的 native capabilities,将可检查的结果返回给 Paperclip,并参与正常的 admission、authority 和 finalization。
本工作流纳入了 2026 年 9 月 30 日至 10 月 9 日的 Dot 集成。参考资料中的 provider facts 和 code paths 是特定日期的证据,并不表示每个未来的 bot 都支持相同的 APIs。选择传输方式或修改代码之前,请核实当前实现和 provider 官方文档。

1. Establish the release contract before narrowing the implementation

1. 在缩小实现范围前先确定发布契约

Read release-contract.md. Infer already-stated requirements and authorization from the conversation. Ask only about consequential unknowns; do not ask the user to repeat “two way,” Cloud, or use of Runner.
Record the target environment, acting identity, capabilities, allowed human setup steps, delivery/stop expectations, and checkable finish line. Keep one compact matrix in the existing plan or task. Follow repository conventions if creating a plan file. “Works” must name its level: prototype, real provider, real Runner, managed sandbox, deployed tenant, or unattended first-time onboarding.
Reuse the current implementation and qualification evidence. Inspect the relevant checkout, instructions, app/Cloud PRs, and Runner artifact. Do not recreate work already merged or apply an old plan to a different deployed revision.
阅读 release-contract.md。从对话中推断已经明确说明的要求和授权范围。仅询问后果重大的未知事项;不要要求用户重复说明“双向”、Cloud 或使用 Runner。
记录目标环境、执行身份、能力、允许的人工设置步骤、交付/停止预期,以及可核验的完成标准。在现有 plan 或 task 中保留一份紧凑矩阵。如果创建 plan 文件,请遵循仓库约定。“可用”必须注明其层级:prototype、real provider、real Runner、managed sandbox、deployed tenant 或 unattended first-time onboarding。
复用当前实现和 qualification evidence。检查相关 checkout、说明、app/Cloud PR 和 Runner artifact。不要重新创建已经合并的工作,也不要将旧 plan 套用到不同的已部署 revision 上。

2. Prove the uncertain provider boundary first

2. 首先证明不确定的 provider 边界

Identify supported ways to authenticate, wake the agent, load tools, correlate work, return results, and stop or revoke authority. Check events/subscriptions as well as direct APIs and chat channels. Do not assume that a bot mention wakes another bot, that MCP notifications wake an offline agent, or that a plugin listed in settings is callable in the agent's current conversation.
Use a synthetic company and stable public HTTPS endpoint. Start with a scripted client for deterministic protocol tests, then the actual provider account:
  1. Fresh connection → callable read tool → verified event round trip.
  2. Paperclip assignment → autonomous acceptance → persisted result → finalization.
  3. Idle bot request → one governed intake → useful action → finalization.
If idle autonomy is in scope, the third journey is a first milestone, not an optional expansion. Do not make the user create a placeholder task for the bot. Label every nudge, operator repair, simulated dependency, and manual tool call. A successful assisted run does not prove prompt-only first-time setup.
确定受支持的 authentication、唤醒 agent、加载 tools、关联 work、返回 results,以及停止或撤销 authority 的方式。检查 events/subscriptions 以及 direct APIs 和 chat channels。不要作出以下假设:提及某个 bot 会唤醒另一个 bot;MCP notifications 会唤醒离线 agent;settings 中列出的 plugin 可以在 agent 的当前 conversation 中调用。
使用 synthetic company 和稳定的公共 HTTPS endpoint。先使用 scripted client 进行确定性的 protocol 测试,然后使用实际 provider account:
  1. 全新连接 → 可调用的读取工具 → 已验证的 event 往返。
  2. Paperclip 任务分配 → 自主接受 → 持久化结果 → finalization。
  3. 空闲 bot 请求 → 一次受治理的 intake → 有用操作 → finalization。
如果范围包含 idle autonomy,第三个 journey 就是首个 milestone,而不是可选的扩展。不要要求用户为 bot 创建 placeholder task。标记每一次 nudge、operator repair、simulated dependency 和 manual tool call。成功的人工辅助运行并不能证明首次设置仅靠 prompt 即可完成。

3. Reuse Runner while keeping placement and capability separate

3. 复用 Runner,同时将 placement 与 capability 分开

Read runner-architecture.md before changing execution or authority. For Paperclip, prefer the existing Runner infrastructure: shared lifecycle, receipts, recovery, and a future sandbox boundary for workspace tools. The bot's model and native tools can remain entirely at its provider.
Use the ordinary configured managed execution environment on Cloud. One admitted assignment reuses its Runner across messages and tool calls; idle connection traffic does not allocate compute. A sandbox hosting Runner does not grant the bot filesystem or shell access. Never add a fallback to the control-plane host.
Implement dedicated agent identity, durable assignment/operation state, current authority checks, and normal finalization. Treat a proposed alternative backend as an explicit architecture decision with preserved invariants and evidence of benefit, not as a reaction to the latest question about overhead.
在更改 execution 或 authority 之前,阅读 runner-architecture.md。对于 Paperclip,优先复用现有 Runner 基础设施:共享 lifecycle、receipts、recovery,以及未来用于 workspace tools 的 sandbox boundary。bot 的 model 和 native tools 可以完全保留在 provider 侧。
在 Cloud 上使用常规配置的 managed execution environment。一项获准的 assignment 会在多条 messages 和 tool calls 之间复用其 Runner;idle connection traffic 不会分配 compute。承载 Runner 的 sandbox 不会授予 bot filesystem 或 shell 权限。绝不要将 fallback 添加到 control-plane host。
实现专用 agent identity、持久化的 assignment/operation state、当前 authority checks,以及常规 finalization。将拟议的替代 backend 视为一项明确的 architecture decision,同时保留各项 invariants 和收益证据;不要把它当作对最近一个 overhead 问题的即时反应。

4. Build onboarding as a watched, resumable workflow

4. 将 onboarding 构建为可观察、可恢复的工作流

Read onboarding-and-prompts.md. Start at the natural UI entry: invite an external agent, select the provider, copy a setup prompt, give it to the bot, and watch real connection checks. Reuse the product's copy-prompt component and provider-independent invitation flow.
Distinguish OAuth grant, runtime tool availability, subscription verification, event confirmation, and agent readiness. Generate or renew pending prompts automatically where safe; preserve connected agents. Finish with an explicit Done action. Use stories for waiting, expiry, errors, pause, readiness, and recovery, then verify the real rendered transitions and persistence.
The prompt must tell the bot to use its own relevant tools/apps/skills and return results. The Paperclip catalog governs Paperclip calls, not the bot's entire runtime. Limit qualification restrictions to the specific test and Paperclip destination. Never turn “use this test connection” into “use no other tools.”
阅读 onboarding-and-prompts.md。从自然的 UI entry 开始:邀请外部 agent、选择 provider、复制 setup prompt、将其交给 bot,并观察真实的 connection checks。复用产品现有的 copy-prompt 组件和与 provider 无关的 invitation flow。
区分 OAuth grant、runtime tool availability、subscription verification、event confirmation 和 agent readiness。在安全的情况下自动生成或续期 pending prompts;保留已连接的 agents。以明确的 Done 操作结束。为 waiting、expiry、errors、pause、readiness 和 recovery 编写 stories,然后验证真实渲染的 transitions 和 persistence。
prompt 必须指示 bot 使用其相关的 tools/apps/skills 并返回 results。Paperclip catalog 管理的是 Paperclip calls,而不是 bot 的整个 runtime。将 qualification restrictions 限定在该特定测试和 Paperclip destination。绝不要把“使用此测试连接”变成“不使用其他工具”。

5. Qualify both correctness and the ordinary user experience

5. 同时验证正确性和普通用户体验

Read conformance-tests.md and select the rows required by the release contract. Reuse existing Runner and Product E2E fixtures; add regression cases for uncovered contracts instead of building a parallel test system. Keep simulated protocol, actual provider, and actual deployment evidence separate. A provider saying “done” is not proof of task disposition or cleanup.
Test a lost response, duplicate wake, follow-up at completion, real controller restart, authority loss, and cleanup. For recovery, compare the original run, assignment, session, process identity, and lease. A restart test in which the controller never restarted is invalid. Unknown mutation outcomes require reconciliation, not a new request ID and a second execution.
If setup needs a reboot, app reattachment, or manual inbox nudge, record the functional success and the remaining onboarding defect separately. Do not quietly teach the tester to navigate around a product defect and then call it self-serve.
阅读 conformance-tests.md,并选择 release contract 要求的 rows。复用现有 Runner 和 Product E2E fixtures;针对未覆盖的 contracts 添加 regression cases,而不是构建一套并行 test system。保持 simulated protocol、actual provider 和 actual deployment evidence 相互分离。provider 声称“done”并不能证明 task disposition 或 cleanup 已完成。
测试 lost response、duplicate wake、completion 时的 follow-up、真实 controller restart、authority loss 和 cleanup。对于 recovery,比较原始 run、assignment、session、process identity 和 lease。controller 从未真正重启的 restart test 是无效的。未知 mutation outcome 需要 reconciliation,而不是使用新的 request ID 再执行一次。
如果 setup 需要 reboot、app reattachment 或 manual inbox nudge,请分别记录功能成功和仍然存在的 onboarding defect。不要暗中教测试人员绕过 product defect,然后将其称为 self-serve。

6. Deliver one identifiable candidate and verify the deployed path

6. 交付一个可明确识别的 candidate,并验证 deployed path

Read troubleshooting-and-deployment.md when setting up a test drive, diagnosing a failure, or deploying. Preserve one environment manifest: checkout/revision, origin, local port, data directory, tenant, image/Runner artifact, active task, and owned resources. Keep secrets out. Retain the environment while the user/provider is testing; do not expire it silently or reset the OAuth database behind a cached client registration.
Use the repository's adapter, eval, PR, and release workflows when available. The Paperclip
create-agent-adapter
skill covers shared configuration surfaces;
paperclip-runner-release
coordinates a release;
test-it-for-real
validates the actual experience. Discover their installed locations rather than assuming they are siblings of this skill. This skill adds external-bot-specific contracts.
Carry authorized merge and rollout through the app, ingress, and Runner artifact dependencies. Verify the serving revision and repeat the main journeys on the real tenant with ordinary defaults. Distinguish implementation defects, provider behavior, infrastructure failures, and test/evidence defects. Bound retries by the operation and observed cause; preserve the same resumable deployment request.
Report supported capabilities, exact live evidence, interventions, unsupported provider controls, remaining gates, and resource disposition. Never equate unknown cost with zero cost, or revoked Paperclip access with confirmed global bot stop. This skill supplies procedure, not new permission to message, grant access, spend, publish, or deploy. Apply the current user's authorization and host policies.
在设置 test drive、诊断 failure 或部署时,阅读 troubleshooting-and-deployment.md。保留一份 environment manifest:checkout/revision、origin、local port、data directory、tenant、image/Runner artifact、active task 和 owned resources。不要包含 secrets。
在 user/provider 仍在测试时保留 environment;不要静默地使其过期,也不要在存在 cached client registration 时重置 OAuth database。
在可用时,使用仓库现有的 adapter、eval、PR 和 release workflows。Paperclip
create-agent-adapter
skill 涵盖共享 configuration surfaces;
paperclip-runner-release
协调 release;
test-it-for-real
验证实际体验。查找这些 skills 的安装位置,不要假定它们与当前 skill 相邻。本 skill 会增加 external-bot-specific contracts。
完成经授权的 merge 和 rollout,并处理 app、ingress 和 Runner artifact dependencies。验证 serving revision,并在真实 tenant 上使用常规默认设置重复主要 journeys。区分 implementation defects、provider behavior、infrastructure failures 和 test/evidence defects。根据 operation 和 observed cause 限制 retries;保留同一个可恢复的 deployment request。
报告 supported capabilities、准确的 live evidence、interventions、不受支持的 provider controls、剩余 gates 和 resource disposition。绝不要把未知成本等同于零成本,也不要把已撤销的 Paperclip access 等同于已确认全局停止 bot。本 skill 提供的是 procedure,而不是发送消息、授予 access、spending、publishing 或 deploying 的新权限。必须遵循当前用户的 authorization 和 host policies。

References

参考资料

  • Release contract: scope, capability matrix, provider research, architecture decision, and finish-line template.
  • Runner architecture: identity, state, admission, receipts, follow-ups, recovery, files, and concrete Paperclip anchors.
  • Onboarding and prompts: UI states, consent, lifetime, tool loading, native capabilities, and reusable prompt text.
  • Conformance tests: runnable journey recipes, failure matrix, evidence schema, and release gates.
  • Troubleshooting and deployment: network planes, specific symptom-to-action diagnostics, stable environments, managed execution, and release provenance.
  • Dot case study: dated incidents, exact historical protocol/tool names, observed limitations, and source trail. Read when comparing a new provider to Dot or checking why a rule exists.
  • 发布契约:范围、capability matrix、provider research、architecture decision 和 finish-line template。
  • Runner 架构:identity、state、admission、receipts、follow-ups、recovery、files,以及具体的 Paperclip anchors。
  • Onboarding 与 prompts:UI states、consent、lifetime、tool loading、native capabilities 和 reusable prompt text。
  • 一致性测试:可运行的 journey recipes、failure matrix、evidence schema 和 release gates。
  • 故障排查与部署:network planes、具体的 symptom-to-action diagnostics、stable environments、managed execution 和 release provenance。
  • Dot 案例研究:有日期记录的 incidents、确切的 historical protocol/tool names、observed limitations 和 source trail。在将新 provider 与 Dot 比较或检查某项规则为何存在时阅读。