@marswave/cola-plugin-sdk

v0.0.4

Published

16 days ago

SDK for building Cola channel plugins that connect external messaging platforms to Cola.

0High
0Medium
0Low

Cola Plugin SDK 中文说明

Cola Plugin SDK 是用于开发 Cola 插件的 TypeScript SDK。

Cola 插件是一个本地 Node.js 包，可以在 Cola 代码库之外扩展 Cola。同一个插件可以承担下面三种角色的任意组合：

Channel。 把外部消息平台（Slack、微信、设备、消息队列等）接入 Cola，在外部平台和 Cola 之间路由消息。
Tools。 注册 LLM 可调用的工具（Notion 搜索、SQL 查询，任何你希望模型能直接调用的能力）。工具默认是全局可见的，所以纯工具型插件不需要 channel。
Observer。 跨所有会话订阅 Cola 的 session 事件流——桌面、CLI、每个渠道都涵盖——用于埋点、审计镜像或跨渠道自动化。

插件不应该 import Cola desktop、server 或 shared 的内部模块；SDK 就是面向插件作者的稳定边界。

English | 中文

文档

安装

pnpm add @marswave/cola-plugin-sdk

主要能力

definePlugin()：通用入口。可声明顶层 tools[]（每个 tool 自带 scope: 'global' | 'own-channel'）、可选的 start / stop 生命周期钩子，以及可选的 channel。
defineChannel()：纯 channel 插件的轻量包装，不需要顶层 tools 或生命周期钩子时使用。
公开类型：插件元数据、channel capabilities、gateway/outbound/auth/config adapters、commands、host runtime、STT/TTS、顶层 tools，以及带 origin 标签和 scope: 'self' | 'all' 订阅参数的 session lifecycle events。
createPollLoop() 和 withBackoff()：适合轮询型 channel 的工具函数。

插件元数据

Cola 从 ~/.cola/plugins/<id>/package.json 发现已安装插件。插件包必须声明 cola.plugin；channel plugin 还应声明 cola.channel，用于展示名称、说明、别名和文档路径。

插件入口在安装前需要先构建成 JavaScript，cola.plugin.entry 必须指向 Cola 运行时可以 import 的文件。

只有当插件使用了某个 Cola 版本才提供的运行时能力时，才需要在 cola.plugin.minColaVersion 声明最低 Cola app 版本，例如 "0.9.10"。插件自身版本和 @marswave/cola-plugin-sdk 依赖版本本身不会要求用户升级 Cola。

核心概念

Gateway

Gateway adapter 负责平台侧的接收循环。它可以使用长轮询、WebSocket、消息队列或平台自己的接入方式。收到消息后调用 ctx.deliver()，传入稳定的 sessionId、 sender、可选的路由信息、规范化文本和附件。

Cola 会占用 plugin:<pluginId>: 这个 scope 前缀，插件只需要决定后缀，例如 ['dm', userId] 或 ['room', roomId]。

Outbound

Outbound adapter 根据 deliveryContext 把 Cola 的回复发回原平台。支持文本发送的 channel 必须实现 sendText()；媒体、typing 状态和 reaction 是可选能力。

如果要发送媒体或文件，实现 sendMedia() 并声明 mediaCapabilities。 supportedKinds 可以把上传限制在 'image'、'video'、'audio' 和/或 'file'；不填则接受 capabilities.send 已启用的所有类型。 maxBytesPerFile、maxBytesTotal 和 maxCount 用来发布平台限制，Cola 会在调用 adapter 前先按这些限制筛选。

Auth 与身份绑定

Auth adapter 负责登录和断开连接。二维码和状态变化可以通过 ctx.onQrCode() 和 ctx.onStatus() 暴露给 Cola。平台账号授权完成后，调用 ctx.runtime.identity.bind(senderId)，Cola 才会接受这个 sender 的消息。断开连接时应调用 unbind()。

群聊与访问授权

默认情况下，投递的消息会被当作私聊（DM）。要支持群聊，需要在 deliver payload 上设置 conversation，并标明机器人是否被 @提及：

await ctx.deliver({
  sessionId: ['group', groupId],
  sender: { id: senderId, name: senderName },
  conversation: { kind: 'group', id: groupId }, // 'group' | 'channel' | 'direct'
  mentionedBot, // 从入站消息里检测；group/channel 必填
  message: text
})

没有 mentionedBot: true 的群消息会被静默忽略，agent 只在被显式 @ 时才介入。完全省略 conversation 会被当作私聊（向后兼容）。

授权分两条轴：

私聊按 sender 授权：cola channel allow <pluginId> <senderId>。
群组整体授权：cola channel allow-group <pluginId> <groupId>，这样群里每个成员都被允许，无需逐个添加。

未授信的私聊，以及 @提及了机器人但未授权的群组，会收到引导提示，提示里会写明要执行的命令。可用 channel.unauthorizedHint(target) 覆盖文案。授权管理命令：cola channel allow / revoke / allow-group / revoke-group / allowlist。

Host Runtime

ctx.runtime 暴露插件可以安全使用的宿主能力，包括身份绑定、只读配置（config.get()）、写回本插件自有配置（config.patch(partial)：浅合并进本插件持久化配置，热更新无需重启，忽略保留键 pluginDir，且只能写自己的配置——适合在运行时把拿到的凭据写回，例如扫码注册之后）、 session events（session 生命周期、compaction、agent 循环、turn、assistant message stream、tool:call/tool:result、运行时 tool:execution_*，默认本插件 scope，传 { scope: 'all' } 可订阅所有会话）、本地 STT/TTS、模型调用（llm.generateText(prompt, opts?) 返回纯文本， llm.generateObject(prompt, schema, opts?) 按 JSON Schema 强制返回并校验结构化结果，llm.streamText(prompt, opts?) 以 AsyncIterable<string> 增量产出文本；均使用用户配置的主模型，可选 { systemPrompt?, timeoutMs? } （超时覆盖整次调用，含流式全程），未配置 provider key 或调用失败时抛错）、日志上报，以及在配置或登录状态变化后重启 gateway 的 reloadGateway()。完整事件目录、origin 标签以及"不转发"契约见 event 参考文档。

插件工具

插件可以通过顶层 tools 数组注册 LLM 可调用的工具。每个工具声明一个 scope：

'global'（默认）—— 在所有会话（桌面、CLI、所有插件渠道）中可见。适合通用能力型工具（Notion 搜索、SQL 查询等）。
'own-channel' —— 仅当本插件自己的 channel session 处于激活状态时可见。需要同时声明 channel。

工具名会被加上前缀 plugin__<pluginId>__<name> 暴露给 LLM，避免不同插件之间的短名冲突。tool:call / tool:result 事件回传不带前缀的原名。

export default definePlugin({
  id: 'notion',
  meta: { label: 'Notion', description: 'Notion 集成' },
  tools: [
    {
      name: 'search',
      description: '搜索 Notion 工作区',
      parameters: { type: 'object', properties: { q: { type: 'string' } } },
      async execute({ q }, ctx) {
        // ...
        return { content: [{ type: 'text', text: 'result' }] }
      }
    }
  ]
})

parameters 是 JSON Schema（Typebox schema 在运行时就是 JSON Schema）。 execute() 收到解析好的入参和 PluginToolContext，里面包含 sessionId （桌面 / CLI scope 下为 undefined）、scopeKey、toolCallId、AbortSignal、插件 logger 以及只读 config。返回 { content, details?, isError? }。

生命周期与跨渠道观察

Plugin.start(ctx) 在插件加载时执行一次，Plugin.stop() 在卸载时执行一次。适合在里面注册监听器、启动后台任务等。两者都有 5 秒超时保护，避免慢启动拖住宿主。

runtime.events.on(type, handler, options?) 支持 options.scope：

'self'（默认）—— 只接收本插件 scope 的 session 事件。
'all' —— 接收 Cola 里所有 session 事件，包括桌面、CLI 和其他插件。适合跨渠道自动化和全局可观测性。

每条事件 payload 都带有 origin 判别字段（{ kind: 'plugin', pluginId } | { kind: 'desktop' } | { kind: 'cli', user } | { kind: 'other', scopeKey }），跨 scope 的 handler 可以据此判断事件来源。

export default definePlugin({
  id: 'observer',
  meta: { label: 'Observer', description: '把活动镜像到 webhook' },
  async start({ runtime }) {
    runtime.events.on(
      'turn:end',
      (e) => {
        runtime.logger.info(`turn ${e.turnIndex} 结束于 ${e.origin.kind}`)
      },
      { scope: 'all' }
    )
  }
})

监听器是只读的：返回值会被忽略，每个 handler 还有 2 秒超时保护。tool:* 事件里的 toolName 永远是原始名（例如 lookup_user，不是 plugin__example__lookup_user）。

兼容性

SDK 发布后按 semver 管理。删除或改变公开导出是 breaking change。标记为 @internal 的类型和 adapter 暂时不稳定，在正式公开前可能变化。

许可证

MIT。详见 LICENSE。