Skip to content

Spec: 插件与 Bot Feature —— 让插件完整接入 Bot(工具、prompt、数据、Panel、事件流入) #4202

Open
0 of 6 issues completed

Description

@DoodleBears

Problem Statement

Human 和第三方开发者想给 Bot 增加完整的新能力,而不只是像 MCP 那样追加几个工具。例如:

  • 共享 Todo:Bot 可以通过工具增删改查,Human 在 Panel 上直接操作同一份数据。
  • Minecraft(举例,本 Spec 不实现):只给某一个 Bot 开启;游戏事件流入这个 Bot,Bot 再通过工具回到游戏中行动。
  • VRM 角色:Bot 回复时可以声明情绪,角色 Panel 播放对应的表情。

一个插件需要同时接入四件事:数据、UI、LLM 生命周期(prompt、工具、事件),以及按 Bot 的启用范围。

现在没有这样的公开合同:

  • 接入点没有类型。 插件要自己声明 core 的接口,再用 ctx.get('botharness') as unknown as BotHarnessCore 强转(packages/todo/src/index.ts)。browser、computer、vrm-companion 都是这么做的。core 一改,插件编译时发现不了。
  • 没法只给某个 Bot 开。 contributeBotAgentSetup 对每一个 Bot 的每一个 Session 都执行(packages/core/src/plugin.ts:1202)。
  • prompt 片段没有管理。 插件可以直接写 agentCtx.systemPrompt.section,但片段没有归属、没有预算,prompt inspection 看不出来源。
  • 工具来源和免审批绑在一起。 插件把工具名加进 hostTools 这个可变集合后,workspaces/grant-execution.ts:440 会直接跳过 Grant 检查。
  • CLI parity 全靠手写。 每个插件都要手写路由和一个伪造 ToolRunContext 的 runDirect。
  • 外部事件进不来。 没有公开入口让外部事件进入 Bot Inbox。
  • 插件数据没有接入生命周期。 Profile 备份和恢复、Bot 删除、数据清除都不知道插件的数据。

旧 Spec #2219 和 ADR-0234 只覆盖了 Panel 加公开 Service 这一半,切片也是按“迁移哪块第一方面板”来切的。产品方向已经调整:IM 类产品的第一方基础功能(Memory、Inbox、Schedules、Home 等)很少有被替换的需求,用户有需要时更可能直接提 PR。所以本 Spec 取代 #2219,重点放在扩展,不追求第一方功能可替换。

Solution

发布一个公开、有类型的 SDK:@botharness/plugin-sdk。插件仍然是原生 DSH Plugin,用原生的 Bundle 打包和安装,不做自己的包管理器,也不做代码沙箱。插件通过 Host 提供的 botFeatures Service 定义 Bot Feature:插件给 Bot 提供的一个可以按 Bot 开关的能力单元。

一个 Bot Feature 用一处声明写清楚以下内容:

  • 身份:id,第三方必须带域名前缀,例如 example.com/minecraft;不带前缀的名字留给第一方。
  • 版本:合同的 version。
  • 数据范围:dataScope,取值 profile 或 bot。
  • 默认启用:enablement,取值 all-bots 或 opt-in。
  • 配置:settings,一份 schema,每个 Bot 一份配置。
  • prompt 片段:带 id 和预算,按 Feature 分槽位,并标明归属。
  • 工具:每个工具都必须声明效果(ToolEffects,见 Spec B)。
  • Panel:复用 ADR-0234 里实现、实例、绑定、位置分开的规则。
  • 数据生命周期:备份和恢复、删除 Bot、数据清除时的回调;Bot 导出或分享时是否带上数据,由插件声明,默认不带。
  • 事件流入(第二个切片):插件产生 Source Event,进入现有的 Bot Inbox 准入、triage 和合并流程。

Host 一侧的 botFeatures 是一个深模块,负责:

  • 持久化每个 Bot 开了哪些 Feature、配置是什么;只对已启用的 Bot 注入 prompt 和工具。
  • 组装 prompt 并做 inspection 归属。
  • 注册和注销工具,并校验效果声明。
  • 自动提供 CLI:tobs feature list、tobs feature tool <feature> <tool> --bot <slug> --args …(不经过模型直接执行工具)、tobs bot feature enable|disable|config。
  • 版本检查:版本不兼容时明确显示“插件不可用:需要升级”。

信任模型:插件是受信任代码。按 Bot 启用只决定这个 Bot 的 LLM 能看到和调用什么,不是安全隔离。真正的安全边界是工具效果声明加权限策略(Spec B)。

User Stories

  1. As a Human, I want 安装一个插件后在 Bot 设置里看到它提供的 Bot Feature,以及每个 Bot 是否开启, so that 我知道每个 Bot 能做什么。
  2. As a Human, I want 只给指定的 Bot 开启某个 Feature(例如 Minecraft), so that 其他 Bot 不会看到无关的工具和 prompt。
  3. As a Human, I want 通用 Feature(例如 Todo)装好后默认对所有 Bot 生效,同时我可以逐个关闭, so that 常用能力不需要一个个手动打开。
  4. As a Human, I want 为每个 Bot 单独设置 Feature 的配置(例如 Minecraft 服务器地址), so that 不同 Bot 可以接入不同的环境。
  5. As a Human, I want 在 Panel 上直接操作插件的数据(例如勾选 Todo), so that 我和 Bot 维护的是同一份数据。
  6. As a Human, I want 插件数据随 Profile 备份和恢复,删除 Bot 时一并清理它的 Bot 级数据, so that 插件数据不会丢失,也不会残留。
  7. As a Human, I want 分享或导出一个 Bot 时默认不带上插件数据, so that 个人数据不会意外泄露。
  8. As a Human, I want 插件版本和 Host 不兼容时看到明确的“不可用:需要升级”, so that 不会遇到无声的故障。
  9. As a Human, I want 在 prompt inspection 里看到每一段 prompt 来自哪个 Feature、占了多少预算, so that 我能排查 Bot 行为的来源。
  10. As a plugin author, I want 从 npm 安装有类型的 SDK, so that 不需要复制 core 的内部接口,也不用强转。
  11. As a plugin author, I want 写一处声明就同时得到工具、prompt、数据、Panel 和 CLI, so that 不必在多个内部入口之间手工拼接。
  12. As a plugin author, I want 自定义外部事件如何进入 Bot 的 Inbox、是否唤醒 Bot,以及是否 steer 正在运行的 turn 或 step, so that 游戏、webhook 这类事件源可以按自己的节奏和 Bot 交互,又不会刷爆 Bot。
  13. As a plugin author, I want 有一份作者指南和模板,照着就能写出一个完整的插件, so that 第一个插件就能跑通。
  14. As a coding agent, I want 每个插件工具自动拥有不经模型的 CLI 执行路径, so that 可以直接验证和定位问题。
  15. As a maintainer, I want browser、computer、vrm-companion 都改用公开 SDK, so that 第一方插件和第三方插件走同一条路径。

Implementation Decisions

  • 术语:插件(Plugin)是打包单位,沿用 DSH 的原生概念。Bot Feature 是插件给 Bot 提供的、可以按 Bot 开关的单元。一个插件可以提供零个或多个 Bot Feature,也可以只提供 Panel。这两个词需要写进 GLOSSARY.md。
  • SDK 版本:先发 0.x,文档写明 0.x 期间可能有破坏性变更。从第一天起就实现合同主版本检查、未知字段忽略和“不可用”状态。S5 完成,且 todo 加上 vrm-companion 或 ingress 示例插件,至少两个真实插件跑通后,发 1.0。
  • 分发:v1 只走原生 DSH 安装(npm 包加 DSH 安装流程)。上架 Marketplace 留作后续。
  • 启用:由插件声明默认值,Human 可以在 Bot 设置和 CLI 里逐个 Bot 覆盖。启用状态和配置由 Host 持久化,按现有规则进入 Profile 备份。
  • prompt:按 Feature 分配槽位,有字符预算,超出时截断并给出提示,Session 期间冻结(和 Soul、Core Memory 的语义一致)。插件不能修改别人的片段。
  • 工具:效果声明 effects 必填(依赖 Spec B 的 E1)。“由 Host 提供”只表示来源,不再意味着跳过授权;hostTools 可变集合由 Feature 注册取代。
  • 事件流入(S4):插件可以定制三件事。(1) 准入:产生 Source Event,进入现有的 Bot Inbox 准入、triage 和合并流程,不直接往 Session 里塞消息,也不新建第二条注意力管线。(2) 唤醒策略:只记录、立即唤醒,或按合并窗口批量唤醒;Host 统一保证限流和上限。(3) Steer:Bot 正在运行时,事件可以插入当前的 turn 或 step(复用 steer、followup 语义),也可以排队。具体的外部集成(游戏、webhook)只作为举例,不在本 Spec 里实现。
  • 回合钩子(beforeTurn、afterTurn):不在 v1 范围内,等出现真实需求再设计,而且只允许观察。
  • Panel:继承 ADR-0234 中仍然有效的决定:实现、实例、绑定、位置四者分开;Group Channel 里没有 Bot-bound Panel;领域 Service 是唯一权威,Panel 只是消费者;事件只承诺“当前状态加实时通知”,不承诺回放。必需角色的替换不在范围内。
  • Browser 和 Computer:只改用公开的工具贡献入口,删掉鸭子类型转换,不改它们的设备授权语义。

Testing Decisions

  • 以外部可观察的行为为准:启用和禁用会改变 Bot 能看到的工具和 prompt;关闭 Panel 后工具仍然能用;Host 重启后数据仍在;删除 Bot 后它的 Bot 级数据被清理;版本不兼容时显示明确的不可用状态。
  • 每个切片都要在真实的隔离 Host 上,用 tobs feature tool 直接执行工具,并用真实模型的 tool trace 验证。
  • 每张票的验收条款编号写成 AC-n,便于验收报告直接引用(见验收条款 issue)。
  • S5 的独立作者测试:一个全新的 agent 只看作者指南,就能写出、安装并演示第二个插件。

Out of Scope

  • 让第一方基础功能可替换,包括 Memory、Inbox、Schedules、Activity Center、Home、Channel List、Sessions、Members、Messages 和 Control Rail。
  • 代码沙箱,以及 Bot 级的安装隔离。
  • 上架 Marketplace。
  • 回合钩子和消息中间件。
  • 通用的事件回放、离线补发和 exactly-once 保证。
  • Human 修改插件作者声明的工具效果。

Further Notes

Slices

切片 内容 Blocked by
S0 #4204 ADR 与术语 —
S1 #4206 SDK 0.x 加 Todo 全局看板 tracer S0 #4204、E1 #4205
S2 #2306 vrm-companion 迁到 SDK,加情绪工具(#2306) S1 #4206
S3 #4207 Browser 和 Computer 改用公开的工具贡献入口 S1 #4206
S4 #4208 事件流入:Inbox 准入、唤醒策略、turn/step steer,以及 Bot 级数据;以 CLI 驱动的最小示例插件作为 tracer S1 #4206
S5 #4209 作者指南、模板、作者 skill,SDK 发 1.0 S1 #4206、S4 #4208

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:panelsPanel contributions, bindings, layout and lifecyclefeature:runtimeInstalled runtime and profile validationscope:hubParent coordination map or epic; not a standalone implementation slicescope:specNormative specification for follow-on slices

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions