[Proposal] 统一插件 api 和事件、sdk 讨论

[hikariming]

类型

信息

问题与证据

插件互相爆炸

希望得到的结果

RFC: dsh 统一插件系统 —— Plugin Manifest、Capability 与事件模型

状态: Draft / 征求意见
发起: dsh 社区生态开发者群（gui / webui / tui / 启动器 / 分发渠道 维护者共同讨论）
参考实现: fabric
讨论方式: 直接在本 RFC 的 issue / discussion 下留言，或提 PR 修改本文档

---

0. 一句话摘要

给 dsh 生态定一套与 dsh 上游版本解耦的插件标准：插件通过 manifest 声明自己是谁、需要什么能力（capability）；宿主（gui / webui / tui / 启动器）通过统一的事件与生命周期 hook 加载和驱动插件。做一件事只有一种明确的方法。

类比一句话就能懂：我们要做的是 Chrome 扩展那套（manifest + 权限声明 + 统一 API），而不是每家浏览器自己发明一遍插件机制。

---

1. 背景：我们现在的生态有多割裂

dsh 火了之后，社区自发长出了多个终端和工具链：

• 三个主要 UI 形态：gui、webui、tui，各自有自己的插件生态，互相不兼容。tui 上跑不了需要图形能力的插件，但目前没有机制提前知道一个插件"需要图形能力"，只能装上炸了才知道。
• loader 混战：早期大家各写各的 loader，谁都能做一个。后来官方引入了 plugin 注册方式，当时所有第三方 loader 一夜全废。这个教训说明：基于"加载方式"做生态是沙子上盖楼，基于"标准"做生态才能活过上游更新。
• patch 满天飞：不少插件靠直接 patch 源码实现功能。dsh 一更新，patch 全崩。目前的共识是 patch 越少越好，最好全部换成标准调用。
• 版本地狱：分发渠道（启动器/组合包）没法追着 dsh 的更新节奏做包管理，只能锁死"插件 A 0.1 + B 0.3 + C 0.7 + dsh 0.5.0"这样的版本组合包。这能用，但本质是在用锁版本对抗接口不稳定，治标不治本。
• 插件互炸：和 MC 社区早期一样，插件之间冲突频发，没有权限边界，也没有"干一件事的唯一方法"，两个插件用两种野路子改同一个东西，必然打架。

上游（dsh 官方）改内核的意愿和节奏我们控制不了，社区也明确不接受激进的内核改动。所以这套标准的第一原则是：

标准的存续不依赖 dsh 上游的任何决定。

---

2. 设计目标

来自群内讨论的三条硬性要求，作为本 RFC 的验收标准：

1. 基于 manifest / capability 声明，与 dsh 上游无关。 插件描述"我需要什么"，而不是"我怎么被加载"。
2. 接口抽象，行为可控。 插件只能通过声明过的接口做事，宿主对插件的行为有完整的知情权和拒绝权。
3. 有开发标准。 哪怕有了框架，也不能让插件想干什么就干什么。干一件事情应该有明确的唯一方法。

外加两条用户侧目标（降低两个摩擦）：

4. 降低安装摩擦：统一市场 + 经过实测的版本组合包。
5. 降低使用摩擦：插件在任意宿主上行为一致，不兼容的能优雅拒载而不是崩溃。

非目标（Non-Goals）

• 不要求 dsh 官方立刻采纳。 本标准先在社区侧跑通，成为事实标准后官方支持只是水到渠成（fabric 支持起来也不是难事）。
• 不统一 UI 实现。 gui / webui / tui 各自的渲染方式不管，只统一"插件如何声明和请求 UI 能力"。
• 不做包管理器。 分发/组合包/启动器是另一层的事，本 RFC 只保证它们有稳定的 manifest 可以消费。

---

3. 核心概念

整个体系只有四个概念，按依赖顺序：

Manifest（我是谁、我要什么）
   ↓
Capability（宿主有什么、给不给）
   ↓
Lifecycle & Events（什么时候叫醒我）
   ↓
Host API（叫醒之后我能干什么）

3.1 Manifest：插件的身份证

每个插件必须携带一个 plugin.json（或 plugin.toml，格式待议，见开放问题），这是插件与世界交互的唯一入口声明。宿主、市场、启动器、组合包工具全部只读 manifest，不猜、不扫源码。

{
  "id": "com.example.better-sidebar",
  "name": "Better Sidebar",
  "version": "1.2.0",
  "apiVersion": "1.x",
  "entry": "dist/main.js",
  "capabilities": {
    "required": ["ui.panel", "session.read", "events.message"],
    "optional": ["ui.tray", "storage.local"]
  },
  "contributes": {
    "panels": [{ "id": "sidebar", "slot": "left", "title": "Sidebar" }],
    "commands": [{ "id": "sidebar.toggle", "title": "Toggle Sidebar" }]
  },
  "compat": {
    "hosts": ["gui>=2.0", "webui>=1.4"]
  }
}

关键设计：

• apiVersion 对齐的是本标准的版本，不是 dsh 的版本。 这就是"和 dsh 上游解耦"的具体落点：dsh 更新只影响标准的适配层（fabric），不影响千百个插件。
• capabilities.required vs optional：required 缺一个就拒载（干净地拒，给用户明确提示），optional 缺了则降级运行。这直接解决"tui 装上需要 gui 能力的插件然后爆炸"的问题——tui 看一眼 manifest 就说"这个我跑不了"，装都不让装。
• contributes 是声明式扩展点：插件不是"拿到句柄之后为所欲为"，而是提前声明"我要在左侧 slot 贡献一个面板"。宿主决定怎么渲染、放不放。

3.2 Capability：能力即权限

Capability 是一份由标准定义、宿主实现的能力清单。初版建议的命名空间（对应群里提到的分类）：

命名空间	内容	说明
ui.*	panel / tray / statusbar / dialog / theme	gui、webui 全量实现；tui 实现子集
session.*	read / write / history	会话上下文的读写
events.*	message / tool-call / lifecycle	订阅业务事件流
storage.*	local / shared	插件私有存储与跨插件共享存储
net.*	fetch	网络访问（默认关闭，需用户确认）
fs.*	read / write	文件访问（默认关闭，需用户确认）

规则只有两条：

1. 没声明的 capability，调用直接抛错。 不存在"偷偷能用"。
2. 每个 capability 在标准里有且只有一套 API。 想画面板只有 ui.panel 一条路，没有第二种野路子——这就是"唯一方法"原则的落地。

3.3 Lifecycle & Events：forge 思路，不是 loader 思路

这是讨论里最重要的一个转向，值得单独说清楚：

loader 思路：对单个文件/模块做内容转换（像 webpack loader）。问题：谁都能写一个，官方一统一就全废，而且根本表达不了"扩展"。

forge 思路：在运行时的特定生命周期阶段自动触发扩展逻辑（像 Minecraft Forge / Fabric 的 hook）。性能可能略低一点，但这才是"扩展"该有的样子。

所以本标准的插件没有"加载脚本"这个概念，只有"注册到生命周期和事件上的回调"：

生命周期事件（宿主保证的顺序）

host:ready → plugin:activate → [运行期业务事件...] → plugin:deactivate → host:shutdown

业务事件（"业务事件化"）

把 dsh 的核心业务流程抽象成标准事件，插件订阅事件而不是 hack 内部函数：

session:created / session:closed
message:before-send / message:sent / message:received
tool:before-call / tool:result
ui:panel-mounted / ui:panel-destroyed

before-* 类事件支持可取消/可修改语义（返回修改后的 payload 或 cancel），这是插件影响行为的唯一合法方式。事件清单本身随标准 apiVersion 演进，走 RFC 流程增删。

3.4 Host API：插件视角的世界

插件代码里只 import 一个东西：

import { definePlugin } from "@dsh-std/api";

export default definePlugin((ctx) => {
  // ctx 上只有 manifest 里声明过的能力
  ctx.events.on("message:received", async (msg) => {
    await ctx.storage.local.set("last", msg.id);
  });

  ctx.ui.panel("sidebar", (panel) => {
    panel.render(/* 声明式 UI 描述，由宿主决定如何渲染 */);
  });

  return {
    deactivate() { /* 清理 */ }
  };
});

注意 panel.render 接受的是声明式 UI 描述而不是 DOM 操作——这样 gui 用原生控件渲染、webui 用 React 渲染、tui 用字符界面渲染，插件一份代码三端跑（前提是它只用了三端都有的 capability）。

---

4. 宿主的义务

一个终端（gui / webui / tui / 其他）想成为"标准兼容宿主"，需要做到：

1. 只通过 manifest 加载插件，不支持任何旁路加载。
2. 实现 capability 协商：对 required 缺失的插件明确拒载并给出人话提示（"该插件需要图形界面能力，当前终端不支持"）。
3. 保证生命周期事件的顺序和送达。
4. 公布自己的 capability 实现清单（机器可读），供市场和启动器做兼容性匹配。

宿主可以有自己的私有扩展 capability（如 x-tui.keymap），但必须带 x- 前缀，且插件依赖私有 capability 时市场会明确标注"仅限 XX 终端"。

---

5. 分发与版本策略

• 市场（marketplace）：统一索引 manifest，按 capability 需求 × 宿主实现清单自动算兼容性，用户在 tui 里根本刷不到纯 gui 插件。
• 组合包（modpack 模式）：继续保留，且升级为一等公民。组合包 = 一份锁定的 {标准版本, 宿主版本, [插件@版本...]} 清单 + 实测通过标记。启动器只消费这份清单。现在锁版本是无奈，将来锁版本是发行版（类比 Linux distro：滚动更新给折腾党，锁定组合包给普通用户）。
• semver 纪律：标准 API 的 breaking change 必须升 major；宿主对旧 apiVersion 至少保留一个 major 的兼容窗口。

---

6. 迁移路径

1. fabric 作为参考实现先行：把 dsh 与 fabric 的启动解耦（进行中），fabric 实现本标准 v0 的事件层和 capability 协商。
2. 现有插件迁移：把所有 patch 点替换成标准事件/API 调用（这一步大部分可以让 AI 批量做，然后人工跑测试），补一份 manifest。
3. starter 框架：官方出一套插件脚手架（模板 + 类型定义 + 本地调试宿主），把"写一个 hello world 插件"压到 10 分钟以内。
4. 三端认领：gui / webui / tui 各出一名代表认领宿主侧适配（讨论中 better sidebar 等项目已有人认领）。

---

7. 开放问题（欢迎在评论区认领）

1. manifest 格式：JSON or TOML？要不要支持 JS 动态生成（倾向不支持，保持静态可分析）？
2. 事件清单 v0 的最小集：上文列出的事件哪些进第一版？before-* 的取消语义边界在哪？
3. 声明式 UI 的表达力：三端公共子集能覆盖多少真实需求？复杂 UI 是否允许 webui-only 的 x- capability 逃生舱？
4. 性能预算：事件总线相比直接 hook 的开销，需要一个 benchmark 基线（有同学已有 benchmark 经验，求接手）。
5. 权限 UX：net.* / fs.* 这类敏感能力的用户确认流程长什么样？
6. 治理：标准的修改流程——谁有 merge 权，RFC 多久一个周期？

---

8. 为什么现在做、为什么是我们做

• 现在参与讨论的群体已经覆盖了生态 top 插件作者 + 三端维护者 + 主要分发渠道。我们不定标准，就没有人有能力定标准了；我们各自为战，用户就继续在版本地狱里炸。
• 历史已经验证过一次：loader 时代的所有投入在官方统一注册方式后一夜归零。依赖实现的生态会死，依赖标准的生态才能穿越上游的更新周期。
• Chrome 用"强内核 + manifest 扩展生态"证明了这条路；MC 社区用 Forge/Fabric 证明了即使官方不配合，社区标准也能成为事实标准。我们两个先例都有，抄作业就行。

下一步：对本 RFC 有意见的老师直接开 issue 或评论；一周后汇总修订为 v0.1，随后 fabric 侧开始按 v0.1 实现事件层原型。

涉及资产与授权

所有插件

受影响群体及安全、权利、速度风险

无

替代方案、可逆性与回滚

无

利益冲突

无

建议负责人和复审日

无

公开记录

• 我理解相关控制者确认前它可能始终只是提案。

[btspoony]

plugin.json 这个名字可能要商榷一下，因为 https://agent-plugins.org/ 规范其他 harness 的 repository plugin (只有 skills, mcp, hooks 的类型) 已经占了这个名字了。

[morlay]

应参考 k8s

apiGroup
version
kind

事件含全 type meta
扩展服务 apiGroup+kind，跨版本自动适配

版本兼容到主版本即可

[mattheliu]

很多插件靠改 patch 实现，并且很多插件都绑定死了版本，每个插件对应的版本也不一样，依赖还是太地狱了。

还有一个最主要的点：现在的插件非常多，有没有一个比较好的验证方式？希望大家也讨论一下关于验证方式的问题，不要变成 SkillHub 或 ClawHub

[morlay]

webui 层考虑设计 url query state
可借鉴 grafana dashboard，多 panel 的状态 url query 持久化

[shine-233]

我觉得可以加入一下插件溯源和定位，我之前做过一个鼠标指到哪里就显示对应地方的是什么插件，原理应该不难，DSH 插件越来越多以后，我觉得除了插件收录和安装入口，还需要一套插件溯源与影响分析机制。安装前，用户应该能看到插件会新增或修改哪些配置、服务和 UI，需要哪些依赖，以及可能访问哪些文件、网络或凭据权限；安装后，如果出现功能异常或插件冲突，还应该能定位到具体的插件、patch 层和依赖链，并支持禁用或回滚。
插件市场解决的是“发现和安装”，而这套机制解决的是“解释、验证和排障”。不知道大家觉得插件来源映射、安装影响预览和运行时溯源应该如何设计，是否应该把它们作为 DSH 插件平台的基础能力？
这个想法主要是把“安装前预览”和“运行后溯源”分开了。
安装前可以分析：
manifest；
依赖；
patch 目标；
配置和服务变更；
构建脚本；
文件、网络和凭据权限。
运行后还需要记录：
哪个插件注册了某个服务或工具；
哪个插件贡献了某个 UI；
哪个 patch 覆盖了哪一层配置；
某次异常涉及哪些插件；
禁用或卸载后哪些运行时效果被清理。

[r05En1cU]

我基于群里的讨论，实现了一个在 Fabric 基础上的类似 NeoForge 方向的事件封装 PoC 并取得了些进展：r05En1cU/dsh-forge，定位是"类 NeoForge 的运行时事件封装+分层修改注入的API框架"，有几个和 RFC 互补的点：

1. 运行时 mixin → 标准事件的机制

RFC 提到"把 patch 换成标准调用"，dsh-forge 的方案是 defineCatalog + defineEventPoint：运行期解析目标方法 → descriptor 快照 → wrapper → 恢复。不需要 --import 预加载，卸载时自动恢复旧状态。这样 catalog 作者声明一次介入点，下游开发者永远只写 ctx.on()，等效下游开发者可以直接通过这套 API 自定义 Cordis Event。

2. 复用官方 HMR，零额外事件总线

dsh-forge 没有自建事件总线，而是把介入点直接映射为官方 Cordis 事件（ctx.emit / ctx.on）。fiber 卸载时 listener 自动回收，性能开销 ≈ 一次函数调用 + 官方事件分发。这块在实现上可以基于创造模式的那套有严格顺序的加载和卸载语义设计实现。

3. 全局独占：让冲突显式化

RFC 背景提到"两个插件用两种野路子改同一个东西，必然打架"。dsh-forge 的运行期目标全局独占设计：同一目标被多个第三方包 patch 时直接 loud error，不做隐式链式叠加。我们认为冲突只有显式化才能治理，而不是假装它能自动叠加。

仓库：https://github.com/r05En1cU/dsh-forge

[qing3a]

验证层视角：几点补充

以 DSH 插件验证工具（dsh-plugin-verify，做 manifest 静态校验与行为判定）维护者的身份支持这个方向。标准一旦成型，验证逻辑必须跟着标准走而不是跟着某个宿主/加载器走——这正好是 RFC 引用的 loader 教训在验证层的翻版。下面补几点让"可验证性"从第一天就是标准的一部分。

1. manifest 建议拆两个版本号

建议在现有 apiVersion（对齐标准 API）之外加 schemaVersion，专门指 manifest 文件格式的版本：

{
  "id": "com.example.better-sidebar",
  "name": "Better Sidebar",
  "version": "1.2.0",
  "schemaVersion": "0.1",
  "apiVersion": "1.x",
  "entry": "dist/main.js",
  "capabilities": { "required": ["ui.panel", "session.read"], "optional": ["ui.tray"] },
  "contributes": { "commands": [{ "id": "sidebar.toggle", "title": "Toggle Sidebar" }] }
}

两个版本号语义不同、解耦演进：apiVersion 演进影响运行时行为，schemaVersion 演进只影响结构。验证工具据此选择校验规则，市场/启动器据此解析字段，迁移期不必为格式演进卡住能力演进。

2. capability 需要一份权威注册表

"没声明的 capability 调用直接抛错"要成立，前提是 capability 名称本身是封闭、可枚举的。建议标准维护一份注册表（namespace + API 签名 + 宿主实现要求），manifest 里引用的每个 capability 必须能在注册表里查到。这样拼写错误、自造野路子能力名在安装前就被拦截，而不必等运行时抛错。x- 前缀做私有逃生舱，注册表是正路。

3. contributes 的 id 需要全局唯一规则 + 静态冲突检测

建议对 contributes 里的 id（panels/commands 等）规定反向域名风格并要求全局唯一。校验器可以做跨插件静态冲突检测：两个插件贡献了同一个 id，装之前就报"冲突，不能共存"，而不是等加载时互相覆盖/panic——这是"插件互炸"在声明层就能拦住的部分。

4. 迁移期需要一个显式 patch 声明段（可选）

RFC 6.2 的目标是把 patch 全量换成标准调用，但迁移期内存量插件仍然在 patch。建议 manifest 预留一个可选的声明段（比如 overrides），让迁移期的 patch 至少是显式的：patch 了哪个入口、覆盖了哪一层。验证器可以据此做"安装影响预览"，用户装之前能看到"这个插件会修改 X"，运行后也能溯源到具体插件。这不会推迟消灭 patch，只是让过渡期不再黑盒。

5. 建议标准定义统一的机器可读校验报告

兼容性匹配是市场的核心功能（RFC 5.1），它依赖机器可读的校验结果。建议标准顺手定义一个校验报告 schema（plugin × host × capability 支持情况 + 拒绝原因 + 校验器标识与版本），市场、启动器、CI、用户界面都消费同一份格式。校验器是谁、用的标准哪一版，本身也要在报告里可追溯。

6. 开放问题的回应

• 问题1（格式）：支持 JSON，且"静态可分析"应是硬要求——校验器、市场、启动器都依赖它，JS 动态生成会让整个兼容性体系失效。另外 plugin.json 这个名字与 agent-plugins.org 的既有规范冲突（btspoony 提的），从跨 harness 互操作的角度支持换名，避免同一个名字在 agent 生态里有两个互相矛盾的含义。
• 问题2（事件 v0 最小集）：建议从严。每个事件进 v0 都要过"没有它这件事做不成"的论证，宁可 v0.1 事件少、语义清，后面按 RFC 流程增补，也别让 v0 背上语义含糊的包袱——事件语义含糊会直接传导成验证规则的含糊。

如果 v0.1 定稿，dsh-plugin-verify 会按其 schema 做一致性校验，并在 fabric 原型阶段把"标准校验器跑通示例插件"作为一个可验收项。

[T-Auto]

dsh-tui 愿意做标准兼容宿主的第一个落地。我们曾经在自己仓库提出过一套自己的方案，建立agent 环境依赖链可追溯、可一键部署复现、增量迁移，并承担规范与溯源职责————

这是因为 TUI 的用户很多是在无头服务器、远程容器里跑任务或做科学计算，对环境稳定性和一键复现的要求高。

本 RFC 确立了插件的能力抽象与事件契约，我们在 TUI 侧则重点补全状态可观测性、依赖锁定与运行时确定性保障。所以认领 tui 宿主侧适配时，我们会把溯源可视化一并带进来，即负责"装了什么、改了什么、能不能回滚，能不能在一台新容器上迅速复原用户已经配置好的agent复杂插件工作区"

我们在 TUI 侧的具体落地计划：

1. 严格按 Manifest 校验

   • 彻底关闭旁路加载，只认静态声明。
   • 严格执行 Capability 协商：如果插件把 ui.panel 这类能力标为 required，TUI 直接拦截并弹提示，不在运行时静默崩溃；标为 optional 的则降级运行。

2. 公开宿主能力清单

   • 随 TUI 每个版本维护一份机器可读的能力清单（明确标清支持哪些 session.*、storage.local 以及 ui.statusbar 等 TUI 子集能力），私有能力统一打 x-tui. 前缀，方便市场和启动器做静默过滤。

3. 生命周期与事件拦截实际落地

   • TUI 自身的渲染管线是事件驱动 + 差分终端输出，天然契合这套 Lifecycle。我们在此前已经开始在做第一套标准的生命周期实现，确保 host:ready 到 plugin:deactivate 的触发顺序，并完整支持 before-* 事件的修改与取消语义。

4. 联动校验与溯源排障（联动 @shine-233 和 @qing3a）

   • 在 TUI 侧记录插件注入的配置、注册的服务与 UI 槽位，方便用户排查是哪个插件在打架，并支持一键清理恢复。
   • 我们会把现有的 TUI 构建/布局回归断言接入 @qing3a 提到的 dsh-plugin-verify

---

针对几个开放问题的看法：

对Manifest 格式与命名：坚持静态 JSON，坚决不要动态 JS 配置，保证市场和验证工具能做纯静态分析。另外赞同 @btspoony 的意见，避开已被占用的 plugin.json，建议直接叫 dsh-manifest.json 或 dsh-plugin.json。

对v0 事件集，支持克制原则，第一版宁缺毋滥，只进会话、消息流和核心拦截点，把语义定义死，避免后续出现兼容包袱。
对UI 表达力，不要强求三端通用 UI 表达力过剩，TUI 优先保证状态栏、确认弹窗等最小公共子集；复杂的端特有交互走 x- 扩展槽，在市场上明确打标即可。

[Yan-Zero]

Remote SSH 场景给这个 RFC 带来了一个具体的反例，值得在标准里明确处理。

"宿主"这个词在 Remote SSH 下对不上

RFC 把 gui/webui/tui 都叫宿主，但远端运行时证明这不够：同一个远端 Host profile 可以同时被本地 TUI 和 Web 连接，插件在远端注册，用户交互在本地发生。"宿主"实际上是两件事混在一起说了——插件在哪里执行（Runtime，由远端 profile 决定）和结果怎么呈现给用户（Presentation，由本次连接的客户端能力决定）。这两个不是一个东西，不能合并成一个 isRemote 或 hostType。

当前 Remote SSH 的命令目录缺子命令

以 dsh-codex 为例：远端 host 通过 commandCatalog 把 /codex 暴露给 TUI，TUI 的 commandList 里能看到根命令。但 HostCommandDescriptor 只有 name、description、input.hint，没有子命令树。/codex login device、/codex set native-compaction on 这些子命令是通过 tuiCommandTrees 注册的，而远端 Host 上根本没有这个 service——它不运行 TUI。结果是远端命令在补全菜单里只有一层，子命令全部丢失。

解法方向：把可移植的命令语法放进 HostCommandDescriptor，让 Host catalog 能带子命令树。这个信息已经在插件里存在（dsh-codex 的 codexSubcommands 函数），只是没有路径传到远端客户端。

登录方式不应该在插件注册时决定

dsh-codex 的 TuiLoginController 里 prompt.type === 'select' 硬编码返回 'browser'，然后直接调 openBrowser()。独立 CLI（bin.ts）支持 --device-code flag，同样的 answerPrompt 函数在 deviceCode 为 true 时选 'device_code'。

远端执行时 openBrowser() 会试图打开远端机器上的浏览器，这显然不对。但问题不是"检测到远端就走 device flow"——同一个 Host 可能同时被 TUI 和 Web 连接，没有唯一的"当前客户端能力"可以在插件注册时保存。

能力信息必须随每次调用携带。最直接的做法：/codex login、/codex login browser、/codex login device 分成三个入口，用户明确选择，不需要猜环境。裸 /codex login 需要能力协商时，capability 必须来自本次 invocation 的客户端上下文，而不是插件初始化时记录的全局状态。

CommandResult 的 text 字段不适合放 device code

device flow 返回的 verification URI 和 user code 是短期有效的授权码，放进 command/done 会话日志不合适。更通用的需求是一个非持久化的 presentation 通道：告诉客户端"显示这段文字、提供这个可点击的 URL"，客户端自己决定怎么渲染，Remote SSH 只是透明转发，不需要理解 Codex。

这和 RFC 的 contributes.commands 声明式方向是一致的：插件声明它需要呈现什么，客户端决定怎么呈现。

---

以上几点都有具体的代码出处，不是假设，供 RFC 讨论参考。

[T-Auto]

认可 @Yan-Zero 的看法，RFC 当前对 Host 这个概念的定义并不清晰。插件运行在哪里，和用户通过什么终端与它交互，是两个不同维度。

如果把二者都称为 Host，Remote SSH、Web/TUI 同时连接同一个远端 profile 时，很快就会出现 capability、登录方式、UI 呈现、事件订阅等状态到底属于谁的问题。

我建议 RFC 不要通过继续增加 isRemote / hostType 一类字段修补，而是正式拆成三层：

• Runtime层，即插件实际运行的位置，包含local / remote / container
• Presentation层，包含tui / webui / gui /
• Control层，负责建立连接，管理 session，授权 invocation生命周期以及运行时状态

其中 Runtime 与 Presentation 必须完全解耦。

例如，同一个 Remote Runtime 可以被tui,gui,webui等多个 Presentation attach；反过来，一个 TUI 也应该可以在多个 Runtime 之间透明切换。

这和我们正在实现的目标相同：TUI 不应该成为远程任务的宿主进程，而应该成为远程/本地 Runtime 的统一控制与观测界面。本地和远程对 TUI 来说只是 Runtime location 的不同，而不是两套完全不同的产品。

@Yan-Zero 提到的， /codex login 的问题，非常典型。远端机器有没有浏览器，属于 Runtime；当前用户有没有浏览器、能不能弹 URL、能不能显示交互式选择，属于 Presentation。我们应该区分 Runtime Capability 与 Presentation Capability，否则一个 Remote Runtime 同时被 TUI 和 WebUI 使用时，插件根本无法正确判断当前请求应该怎么呈现。

对于一个包含id，description，arguments，options的CommandDescriptor，使用

/codex
/codex login
/codex login browser
/codex login device

对于本地 TUI、远程 TUI、WebUI 都只是同一个 command tree 的不同 presentation，这比让每个客户端自己维护一份 tuiCommandTrees 更符合 RFC 想建立的“唯一方法”原则。

此外，CommandResult 不应该什么都往用户界面里塞。例如对于授权登录场景，其需要展示给用户，可能包含 URL，复制，敏感，不应该进入持久化 session history。这里我建议标准里增加一个轻量的 ephemeral presentation channel，插件只声明presentation.show({ type: "auth-device-code", uri: "...", userCode: "...", expiresAt: "..." })，TUI 显示文本和二维码，WebUI 显示按钮，GUI 打开浏览器，某些纯 CLI 环境打印 URL都应该由 Presentation 层决定，Remote transport 只负责透明传递标准化事件。

所以RFC的Host概念应当重定义。一个插件到底运行在哪台机器上，和用户现在通过 TUI、WebUI 还是 GUI 来操作它，其实是两件完全不同的事情。中间再加上一层 SSH、WebSocket 之类的连接方式，就更不应该全部叫 Host。Runtime 解决的是插件到底在哪里运行，Transport 解决的是 Runtime 和客户端之间怎么建立连接，而 Presentation 则负责用户最终通过什么方式看到和操作这些能力。这样的话，插件本身只需要面对 Runtime 提供的统一接口，不需要知道自己是在本地运行，还是通过 SSH、WebSocket 甚至 Kubernetes Exec 被远程调用，更不需要关心最后是 TUI、WebUI 还是 GUI 在展示它，这样其实也更符合 Remote SSH 的实际情况，比如一个远程 Runtime 完全可以同时被本地 TUI 和 WebUI 连接。对于插件来说，它不用管中间到底是 SSH 还是 WebSocket。SSH 只是其中一种，以后完全可以有：Local IPC，HTTP，Container Exec，Kubernetes Exec，甚至未来出现的新的连接方式。

对于 dsh-tui 项目本身，我们并不是希望把远程部署、profile、调度、workflow 等能力全部塞进 dsh-tui，但从越来越普遍的远端部署，分布式计算的用户角度看，TUI 侧最需要承担“溯源、依赖锁定、运行时确定性和一键复原”的职责。它们最终必须形成一个完整、可验证、可恢复的工作环境。TUI 已经正在把标准从 API 层真正落到用户工作流里的控制面。

我希望 RFC 把 Reference Host 正式纳入标准生态，如果标准只定义了插件怎么写，没有指明如何验证一个宿主真的正确实现了标准，最终还是很容易回到“每个客户端各自实现一遍”的混乱状态。

TUI 愿意做第一批标准兼容宿主。RFC 定义好标准以后，需要一个真正跑起来的参考实现，然后由 TUI、WebUI、GUI 等不同宿主去做实际的兼容性验证。TUI 可以尝试跑完整套验证，Manifest 静态校验， capability 协商，生命周期和事件顺序，command tree，到具体调用时的 Presentation capability。Remote Runtime 的 attach/detach 也可以直接作为实际场景验证，同时把插件到底注册了什么、依赖了什么、修改了什么这些溯源信息记录下来。

这样做，插件出了问题以后，不用只能骂“又炸了，什么混乱生态”，还能够继续查找依赖链和具体插件定位，还能清理、禁用或者回滚。

TUI 不会负责实现所有插件能力，而是先把 RFC 里的东西真正跑通、测通。后面 WebUI、GUI 或其他宿主可以直接拿同一套验证标准来做兼容性测试。最终就会形成一个比较完整的链路：标准负责定义规则，参考实现负责验证规则，宿主负责落地，验证工具负责判断是否真的符合，最后市场和分发工具再建立在这些结果之上。

我非常赞同 Yan 提出的Remote SSH 这个 RFC 在具体部署过程中的应用反例。我们需要标准化一个插件 Runtime 如何被不同 Presentation attach、调用、观察和控制。这样来，Remote SSH 可以作为第一个验证场景——TUI、WebUI、GUI 只是不同的 Presentation，而 profile、workflow、agent、scheduler 等插件则可以独立开发。

我不赞同AGI的时代是单机本地工具的时代。AGI的时代是集群的时代，是算力网络的时代，未来的架构必须可以承担成千上万个 Agent、Tool 与异构运行。未来 Agent 与人类协作，不可以被单物理机器制约。

[T-Auto]

另外我补充一点， 依赖锁定、一键复现、环境可观测性 并非只是c端需求。LLM的后训练，LLM与Harness框架联动，验证LLM在复杂混乱环境下的性能，以及自我迭代，十分需要一个建设依赖锁定、一键复现、环境可观测性 的基础设施。我想后训练过拟合的后果大家有目共睹。

[Qiuner]

这个 RFC 的方向非常认同，尤其是 manifest/capability 与 host capability list。我最近也在从 DSH Desktop 的新壳角度思考同一个问题：插件加入 DSH 后，如何保证它能和其他插件共同运行，并且能安全退出。

我想补一个可能值得放进 v0 核心的问题：除了 Manifest / Capability / Lifecycle / Host API，还需要一层明确的 Composition Rules。

插件声明可以拆成三类：

• requires：我需要什么 capability
• provides：我提供什么 service/capability
• contributes：我向共享界面或系统贡献什么入口

其中 provides 很重要，因为插件之间最好依赖能力，而不是依赖具体插件。例如 Git 插件可以 provide git.client，其他插件 requires git.client，至于由哪个插件实现、是否允许多个 provider、是否需要用户选择，应该由标准定义。

同时，每类共享资源需要有机器可判定的组合规则：

• commands: many, id 不可冲突
• workspace.panel: many, shell 负责组合和呈现
• model.providers: many
• model.default: selected one
• shell.root: shell owned only

这样宿主能在启动前判断插件集合是 merge、soft conflict、selection needed 还是 hard conflict，而不是依赖加载顺序。

另外，事件/hook 这层我建议分级：

• declarative contribution 是默认路径
• lifecycle hook 必须标准化
• observe event 可以较早开放
• mutate/block 类 before-* hook 需要 manifest 强声明、顺序规则、超时、错误隔离和审计

这样可以避免新的标准又退化成“大家抢 hook 顺序”。