Repository navigation
Open
0 / 60 of 6 issues completedOpen
0 / 60 of 6 issues completed
Copy link
Labels
feature:panelsPanel contributions, bindings, layout and lifecyclePanel contributions, bindings, layout and lifecyclefeature:runtimeInstalled runtime and profile validationInstalled runtime and profile validationscope:hubParent coordination map or epic; not a standalone implementation sliceParent coordination map or epic; not a standalone implementation slicescope:specNormative specification for follow-on slicesNormative specification for follow-on slices
Milestone
Description
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
- As a Human, I want 安装一个插件后在 Bot 设置里看到它提供的 Bot Feature,以及每个 Bot 是否开启, so that 我知道每个 Bot 能做什么。
- As a Human, I want 只给指定的 Bot 开启某个 Feature(例如 Minecraft), so that 其他 Bot 不会看到无关的工具和 prompt。
- As a Human, I want 通用 Feature(例如 Todo)装好后默认对所有 Bot 生效,同时我可以逐个关闭, so that 常用能力不需要一个个手动打开。
- As a Human, I want 为每个 Bot 单独设置 Feature 的配置(例如 Minecraft 服务器地址), so that 不同 Bot 可以接入不同的环境。
- As a Human, I want 在 Panel 上直接操作插件的数据(例如勾选 Todo), so that 我和 Bot 维护的是同一份数据。
- As a Human, I want 插件数据随 Profile 备份和恢复,删除 Bot 时一并清理它的 Bot 级数据, so that 插件数据不会丢失,也不会残留。
- As a Human, I want 分享或导出一个 Bot 时默认不带上插件数据, so that 个人数据不会意外泄露。
- As a Human, I want 插件版本和 Host 不兼容时看到明确的“不可用:需要升级”, so that 不会遇到无声的故障。
- As a Human, I want 在 prompt inspection 里看到每一段 prompt 来自哪个 Feature、占了多少预算, so that 我能排查 Bot 行为的来源。
- As a plugin author, I want 从 npm 安装有类型的 SDK, so that 不需要复制 core 的内部接口,也不用强转。
- As a plugin author, I want 写一处声明就同时得到工具、prompt、数据、Panel 和 CLI, so that 不必在多个内部入口之间手工拼接。
- As a plugin author, I want 自定义外部事件如何进入 Bot 的 Inbox、是否唤醒 Bot,以及是否 steer 正在运行的 turn 或 step, so that 游戏、webhook 这类事件源可以按自己的节奏和 Bot 交互,又不会刷爆 Bot。
- As a plugin author, I want 有一份作者指南和模板,照着就能写出一个完整的插件, so that 第一个插件就能跑通。
- As a coding agent, I want 每个插件工具自动拥有不经模型的 CLI 执行路径, so that 可以直接验证和定位问题。
- 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
- 取代:Spec: 原生 Panel Plugins、公开能力与事件、绑定及多实例 #2219、Panel Plugins migration: 第一方 Panels 公开合同迁移(T8–T15) #2234 和 T2–T15(Panel Plugins T2: 全局 Task Kanban 与 Bot 任务工具 #2223–Panel Plugins T7: Messages 替换与聊天状态连续性 #2228、Panel Plugins T8: Memory Evolution 迁移为独立 Plugin #2235–Panel Plugins T15: Computer Panel 迁移到公开贡献与绑定合同 #2242)、Panel Plugins:Panel 对其他插件的公开 Host Event 做出反应 #2327。T1 Panel Plugins T1: 独立 VRM 角色 Panel、Activity 与说话表现 #2222(VRM)以“已交付”关闭。[Plugins S2] vrm-companion 迁到 SDK:Bot 回复携带情绪,说话时呈现喜怒哀乐 #2306 改挂到 S2 下。Spec: 原生 Panel Plugins、公开能力与事件、绑定及多实例 #2219 吸收进来的 1788 和 75 系列验收条款经评审后放弃。
- ADR:S0 新写一份 ADR,部分取代 ADR-0234(第一方面板迁移和必需角色替换的部分),并补充 ADR-0203。
- 依赖:S1 依赖 S0 和 Spec B 的 E1。S2、S3、S4 依赖 S1,三者之间互不依赖。S5 依赖 S1 和 S4。
- 设计讨论记录:
docs/research/2026-11-15-bot-features-tool-effects-and-criteria.md。
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
Labels
feature:panelsPanel contributions, bindings, layout and lifecyclePanel contributions, bindings, layout and lifecyclefeature:runtimeInstalled runtime and profile validationInstalled runtime and profile validationscope:hubParent coordination map or epic; not a standalone implementation sliceParent coordination map or epic; not a standalone implementation slicescope:specNormative specification for follow-on slicesNormative specification for follow-on slices
Activity