# dsh-connection-card-host
**中文** | [English](README.md)
**参与贡献:** **[卡片与适配插件清单 →](awesome/README.zh.md)** · **[贡献指南 →](awesome/CONTRIBUTING.md)** · **[English list](awesome/README.md)**
任何普通 DSH 插件都能进清单当卡片用。一个 PR 一行,带证据。
> **让 DSH 的多个会话互相看得见、说得上话、共用得上工具 —— 而互不打扰。**
在一个 DSH 里同时开着好几个会话(一个查资料、一个写代码、一个跑实验)是常态,
但它们**互相隔离**:不知道对方在干什么,也没法把结论递过去。
这个插件把「连接」做成 DSH 里的一等对象:**会话是节点,连接是容器,卡片是连接级插件**。
**实际操作**(录屏)
|
**结构示意**([架构图](docs/capabilities.md))
|
左:真实操作(原视频) · 右:同一动作的结构示意,标出了「开关语义」
---
## 目录
- [它能做什么](#它能做什么)
- [三十秒上手](#三十秒上手)
- [三个层次:感知 / 约定 / 传话](#三个层次感知--约定--传话)
- [连接上的卡片](#连接上的卡片)
- [卡片能做什么 · 不能做什么](#卡片能做什么--不能做什么)
- [社区卡片与适配插件](#社区卡片与适配插件)
- [架构与成本](#架构与成本)
- [为什么这样做](#为什么这样做)
- [安装](#安装)
- [怎么用](#怎么用)
- [怎么用](#怎么用)
- [配置项](#配置项)
- [卸载](#卸载)
- [FAQ](#faq)
- [怎么用](#怎么用)
- [配置项](#配置项)
- [卸载](#卸载)
- [FAQ](#faq)
- [卡片开发](#卡片开发)
- [维护](#维护)
---
## 它能做什么
| | |
|:---|:---|
| **互相看得见** | 查得到对方**正在改哪个文件、计划进行到第几步、最近用了什么工具** —— 自动采集,对方不需要专门告诉你 |
| **说得上话** | 给对端发消息,**三档紧急度自己判断**:只告知(不打断)/排队/插话 |
| **共用得上工具** | 连接上可以挂**卡片**:卡片能给会话提供工具,甚至带几十 MB 的真依赖 |
| **共用前提** | 「公约盒」存放双方说好的事:接口、单位、命名、分工边界 |
| **互不打扰** | 感知是**拉取式**的 —— 对方不查就零成本;不相关的连接**不会吵到你** |
---
## 三十秒上手
1. **建连接**:按住输入框左侧的圆点(或会话行上的「…」),拖到左侧会话列表里的某一行。
**从锚点拖**(录屏)
|
**从会话行拖 → 连上之后**(录屏)
|
锚点原视频 · 会话行原视频
- **开关语义**:拖到未连的行 = 连接;拖到**已连**的行 = 断开(悬停时会提示)
- 也可以从侧栏「连接」面板里选两个会话
2. **完事**。两端各自收到一条静默通知(说清了连上了谁、能做什么),**不打断任何人**。
3. 想看得更细:点侧栏「连接」,或者让会话自己调 `connection_peer_work`。
连接建立后,会话行右侧会出现**竖轨**,两端各一个**彩色圆点** —— 那是该方向的权限:
---
## 三个层次:感知 / 约定 / 传话
这三层是**分开的**,因为它们的代价差别很大:
| 层 | 机制 | 进对方上下文吗 | 迫使对方行动吗 | 成本 |
|:---|:---|:---|:---|:---|
| **A 工作状态** | 拉取(对端主动查) | 只在它查的时候 | ❌ 不会 | **0** |
| **B 公约盒** | 拉取(对端主动查) | 只在它查的时候 | ❌ 不会 | **0** |
| **C 传话** | 推送(进对方收件箱) | **无条件** | ✅ **必然** | 每条都花 |
**关键事实**:在 DSH 里投递一条消息 = **迫使对方跑一轮**(agent loop 没有"看到但不理"这个状态)。
所以「说话」和「感知」必须分开做 —— 想要对方**知道**,用 A/B;想要对方**做事**,才用 C。
### A. 工作状态(自动,0 成本)
自动从运行事件里采集,**不要求模型额外产出任何东西**:
```
【session-bd5ac1b1】
状态:正在执行命令(2 秒前)
最近动过的文件:water-boat/src/water.js
进度:第 69 轮 / 第 39 步
```
### B. 公约盒(显式,0 成本)
双方说好的标准:接口签名、单位、坐标系、命名、**谁的活归谁**。
面板上可增删;会话用 `connection_conventions` / `connection_declare` 读写。
> **为什么是"拉"不是"推"**:推送会把对方上下文慢慢填满,而大部分时候它用不上。
> 做成"存在盒子里、需要时自己查",成本就是 0。
### C. 传话(三档紧急度,**由发起方判断**)
| 档位 | 底层 | 对方会怎样 |
|:---|:---|:---|
| `quiet` | `inject` | 放进上下文**但不唤醒** —— 它下次干活时看到,**不被打断** |
| `normal` | `followup` | **排队** —— 处理完手头的事就看到 |
| `urgent` | `steer` | **插话** —— 插进它**正在跑的那一轮**,当场读到 |
`urgent` 而对端空闲时**自动降级为排队**(下一轮立刻开始,效果等同即时),不会失败。
> **判断原则**(写在工具描述里):打断是有代价的(对方要中断当前思路)。
> 大部分消息不急 —— 默认 `normal`,只有确实需要它**立刻**改变行为时才 `urgent`。
---
## 连接上的卡片
**卡片 = 挂在连接上、且能分端可见的插件。**
| | DSH 插件 | 卡片 |
|:---|:---|:---|
| 装在哪 | 整个 DSH(profile) | **一条连接** |
| 谁能调 | 所有会话 | **只这条连接上的会话** |
| 可见性 | 全局 | **可分端**:两端 / 仅 A / 仅 B |
| 生命周期 | 随 DSH 起停 | 随连接上的装载卸载 |
### 卡片能给会话提供工具
卡片里 `api.registerTool(name, fn)` 注册的工具,连接上的会话可以用
**一个**常驻桥接工具按需发现并调用:
```
connection_card_tool ← 唯一常驻的(1 个 schema)
├─ 不传 tool → 列出本连接上「对你在的这一端可见」的卡片与工具
└─ 传 tool → 调用它
```
**为什么是一个桥接、而不是每个工具各占一个 schema**:后者会让**每个会话**都为
每个卡片工具付常驻成本,而卡片是随连接动态装载的。桥接只占 1 个,
而且天然能在桥接层强制可见范围。
**可见范围真的拦得住**:
```
A 端可见该卡片 ✅
B 端看不到 ✅
B 端硬调它 → 拒绝 「这张卡片只对 A 端可见(你在 B 端)」
```
### 卡片里可以塞真依赖
卡片可以自带真依赖(连几十 MB 的解析库也可以):把插件连同依赖包成一张卡片,
装到 `$DSH_HOME/connection-cards/cards/`,**不碰 DSH profile**。
会话通过桥接调用,拿回真实解析结果。
### 面板内安装与更新
- **装**:包名 / 仓库 tgz 地址 / 本地目录 → 装进我们自己的目录,**不跑 pnpm、不改 profile**
- **卸**:已安装的卡片带「卸载」入口(**点击前确认一次**,并说清会连同它的卡片实例一起移除)。
内置卡**不给卸载** —— 它们随插件分发,删了下次升级又回来,给按钮只会让人白点。
卸载后**如实回报**清了什么、什么被占用没清掉。
- **更新**:已安装的卡片带「检查更新」入口,三态分列
```
「检查更新」→「↑ 更新到 x.y.z」/「已是最新」/「无法检查」
```
**"无法检查"绝不显示成"已是最新"** —— 那是谎报。
---
## 卡片能做什么 · 不能做什么
任何普通 DSH 插件都可以挂到某条连接上当卡片。是否可用,看三项**静态条件**:
| 条件 | 支持 | 不支持 |
|---|---|---|
| **作用域** | 注册到**连接级**位置(会话消息区、输入区)或**纯能力**(没有客户端 UI) | 注册到 **App 级**位置(侧栏、整体布局、设置页、主题、标题栏、工作区)—— 这类是给"装在 App 上"用的,挂到连接上没有意义 |
| **宿主依赖** | 卡片**入口会加载到**的文件里,所用依赖都能解析 | 入口真正依赖的包缺失(安装时会**分类说明**:缺宿主能力 ⇒ 要改卡片设计;缺第三方依赖 ⇒ 补依赖即可) |
| **宿主能力** | 只用到 `tools` / `effect` / `llm` / `prompt` | 需要其它宿主服务(凭据、Web 服务、会话控制、命令、子进程等)—— 本插件不提供,**会明确拒绝** |
> 判定只看**入口真正会加载到的文件**:测试、构建脚本、CLI、类型声明**不算**运行时依赖。
### 客户端 UI 的可用范围
| 客户端形态 | 结果 |
|---|---|
| 只用槽位与副作用钩子(`slots` / `effect`) | **可以渲染**,且是可交互的真组件 |
| 依赖更多客户端服务(本地化、配置表单、连接、路由、设置页等) | **挂得上、槽位也注册,但渲染不出来** —— 会在面板里**显示具体原因**,不会白屏 |
| 客户端产物大小 | 上限 **32 MB**(自带素材的整包 bundle 可以很大) |
| 组件入参 | 以**无 props** 方式调用 —— 需要槽位 props 的组件会报错(错误被限制在那一块,不影响其他卡片) |
### 候选列表里的标注
每张卡片带一个徽标:**适配 / 能力 / 局部 / 全局 / 未判定**。
标注意义是让你**在安装前**就知道它适不适合当卡片 —— **只标注、不阻断**,你仍然可以挂。
---
## 社区卡片与适配插件
内置那几张卡只是**起点**,不是上限。**任何普通 DSH 插件都能当卡片挂**,而卡片本来就只是一个包
—— 所以这份清单可以**从仓库外面长出来**。
**清单的源在 [`awesome/README.zh.md`](awesome/README.zh.md)**(提 PR 改那边,一个 PR 一行,
规则见[贡献指南](CONTRIBUTING.md))· [English list](awesome/README.md)
展开清单 —— 4 张内置卡 · 适配插件 · 已知不兼容
### 内置卡片
随插件分发,在卡片候选列表里直接选。
| 卡片 | 它做什么 | 需要(读 / 写) | 事件 |
|---|---|---|---|
| **目标中继**(`goal-relay-card`) | 把目标与状态同步给对端,两边对"我们在做什么"有同一份认知 | `goal_status` / `relay_goal` | `goal_updated`、`goal_completed` |
| **监控**(`monitor-card`) | 盯对端的预设状态与会话活动,抛出 `preset_error` / `session_idle` | `preset_status`、`session_log` / — | `preset_error`、`session_idle` |
| **自愈**(`self-heal-card`) | 收到 `preset_error` 就让对端修预设,并把结果回报 | `preset_status` / `repair_preset` | `preset_error`、`preset_repaired` |
| **连接礼仪**(`connection-etiquette`) | 把四档紧急度讲给两边,并按你选的档位转发附注 | — / `send_message` | — |
### 当卡片好用的插件
| 插件 | 它给这条连接带来什么 | 状态 |
|---|---|---|
| [`dsh-client-ui-voice`](https://github.com/hajixiaolei-art/dsh-client-ui-voice) | 按住说话的语音输入控件 | ✅ 挂得上 · UI **捕获并渲染** · 1 个槽位 |
| [`gal-view`](https://github.com/Ayase34/gal-view) | 模型/场景查看面板 | ⚠️ 挂得上 · 槽位注册成功 · 渲染要客户端 hook |
### 已知不兼容
列出来是为了**省你一个晚上**。面板里的拒绝会写清确切原因。
| 插件 | 为什么今天挂不上 |
|---|---|
| [`dsh-usage`](https://github.com/linxin666/dsh-usage) | 宿主半边 import 了 11 个本插件不提供的包(`credentials`、`webServer`、`session`…)⇒ 它需要的是**另一种宿主**,不是卡片 |
| 侧栏 / 主题 / 布局类替换 | **全局** UI,不是连接级 —— 它们属于 App。候选列表会把它们标成 `全局` |
### 社区卡片
_还没有条目 —— 第一个可以是你。_
> 卡片做的事,是**让一个插件去教一条连接**:给那个会话工具、在两端之间传事件、
> 把界面放在**对话旁边**而不是**接管整个 App**。
---
## 架构与成本
三层,边界很硬 —— 每层只跟下一层说话:
```
┌─────────────────────────────────────────────────────────────┐
│ 卡片层(连接级插件) │
│ 只依赖 CardAPI,绝不 import @deepseek-ai/* │
│ → DSH 升级不影响卡片;我们改 CardAPI 才影响(有版本护栏) │
├─────────────────────────────────────────────────────────────┤
│ 连接层(本插件) │
│ 连接 / 权限 / 感知 / 公约盒 / 卡片宿主 / 消息投递 │
│ → DSH 升级时,只需要改这一层 │
├─────────────────────────────────────────────────────────────┤
│ DSH 适配层(DSHAdapter + 白名单 + 审计) │
│ 所有 DSH 交互的唯一出口;不重写 DSH 的通信/权限/插件系统 │
└─────────────────────────────────────────────────────────────┘
```
### 权限是**分方向**的
一根线两端各一个圆点,颜色是**那个方向**的权限 —— 两个方向互不影响,
可以做成「甲能发、乙只能看」:
**只读不影响感知**:工作状态与公约盒都是对端**主动查询**的,与权限无关。
降低权限立即生效;提高权限需要被授权的一方确认。
### 卡片工具怎么到会话手里
卡片注册的工具**不各占一个 schema** —— 会话只看得见**一个**常驻桥接,
按需发现、按需调用,且在桥接层强制可见范围:
---
### 成本省在哪
| 项 | 数字 | 说明 |
|:---|:---|:---|
| **感知(A + B 两层)** | **0 上下文** | 拉取式;对端不查就不产生任何成本 |
| **卡片工具** | **1 个常驻 schema** | 而不是每个卡片工具各占一个 |
| **自动镜像** | **0(已关闭)** | 默认关闭(自动转发会把大量无关内容灌给对方) |
| **不相关的连接** | **0 打扰** | 搭线不唤醒;不相关的会话照常干活 |
**唯一固定成本**:本插件 5 个 `connection_*` 工具的 schema ≈ **1700 tokens 常驻** ——
**且只在参与了连接的会话里常驻**:没连接的会话由 `system-prompt/assemble` 自动摘掉
(没有连接的会话看不到这些工具)。
---
## 安装
> **你正在看的是预览线仓库。** 对外发布走[稳定门面](https://github.com/Noob-stupid/dsh-connection-card-host)。
> 下面第一、二条对两个仓库都成立(npm 包与门面同源)。
**npm(推荐,可锁版本)**:
```sh
dsh plugin --profile web add @noob-stupid/dsh-connection-card-host
```
**GitHub 直装**(装**默认分支最新提交**,不是固定版本):
```sh
# 稳定线
dsh plugin --profile web add github:Noob-stupid/dsh-connection-card-host
# 预览线(最新开发版,就是本仓库)
dsh plugin --profile web add github:Noob-stupid/dsh-connection-card-host-preview
# 同上,GitHub 简写(可省 github:)—— 带斜杠就走 GitHub 仓库
dsh plugin --profile web add Noob-stupid/dsh-connection-card-host
```
**固定版本:用 Releases 的 tgz 附件**:
```sh
dsh plugin --profile web add https://github.com/Noob-stupid/dsh-connection-card-host/releases/download/v1.0.2/noob-stupid-dsh-connection-card-host-1.0.2.tgz
```
- ⚠️ `github:` 与简写装的是**默认分支的最新提交**,**不是固定版本**;要固定版本请用
npm 的版本号(`@noob-stupid/dsh-connection-card-host@1.0.2`)或上面的 Releases tgz。
- `lib/` 已随仓库提交(npm 包里也带上):装完即可用,不需要构建步骤。
**规则**:**带斜杠 → 当 GitHub 仓库;不带斜杠 → 当 npm 包名。**
(`dsh-connection-card-host` 这个不带斜杠的裸名在 npm 上不存在,会 404 —— 别用。)
**兼容性**:`peerDependencies` 声明 `@deepseek-ai/dsh >=0.2.0-rc.1 <0.3.0` ——
DSH 会在安装时**按版本门控**,不匹配会明确拒绝并说明原因(而不是装上再崩)。
## 怎么用
1. **建连接** —— 在面板里挑两个会话;**两个方向各自设权限**。
2. **挂卡片** —— 打开一条连接,从候选列表里选一张;生效在你选的那一端(A / B / 两端)。
3. **和对端说话** —— 卡片的工具会对那一端的会话可用;发消息时你选紧急度
(`quiet` 只告知 / `normal` 排队 / `urgent` 插话 / `preempt` 抢占)。
4. **卸卡片** —— 从连接上移除即可;卡片本身仍然是装着的。
### agent 的 skill 随插件一起装好
装上插件就够了:它通过 DSH 的 skill-provider 通道注册一个 **`connection-card` skill**,
所以那个实例里**任何 agent** 都能在会话目录里看到这套连接工具怎么用 ——
不用往 `~/.dsh/skills/` 拷文件,也不用多做一步。
- 文本的唯一出处:[`skills/connection-card.md`](skills/connection-card.md)。
- 插件加载期间它就在;**卸载插件它就消失**(注册绑定在插件生命周期上)。
- 内容覆盖:五个宿主工具各自什么时候用、四档紧急度怎么挑
(`quiet` 只告知 / `normal` 排队 / `urgent` 插话 / `preempt` 抢占)。
- 想当**普通本地 skill** 用也行:同一个文件就是一份合法的扁平 skill,
拷成 `~/.dsh/skills/connection-card.md` 即可。
## 配置项
| 设置 | 默认 | 作用 |
|---|---|---|
| 适配层 | **关闭** | 允许把普通 DSH 插件当卡片挂载。你不打开,它什么也不做。 |
| 自动镜像 | **关闭** | 自动把会话内容转发给对方。有意保持关闭:转发过去的多半是噪音。 |
| 视图偏好 | 按连接 | 连接轨道上显示几条泳道。 |
## 卸载
- **卸一张卡片** —— 候选列表里对已安装的卡片有「卸载」入口(确认时会说明它挂在几条连接上)。
内置卡不提供卸载:它们随插件分发,升级后会回来。没清掉的东西会**如实说明**。
- **卸整个插件** —— 从 DSH profile 里移除即可。卡片与连接数据在
`$DSH_HOME/connection-cards/`,不会被顺手删掉。
## FAQ
**挂卡片需要先装什么吗?**
不需要。卡片装在本插件自己的目录里,**不在你的 profile 里跑 pnpm**,也不改你的 DSH profile。
**某个插件挂不上,为什么?**
拒绝会说明是哪一类:**宿主能力**(这张卡要的东西本插件不提供)或**第三方依赖**(依赖缺失)。
前者要改卡片设计,后者把依赖随卡片带上即可。
**挂上了但看不到界面?**
它的客户端半边用到了槽位与副作用钩子之外的服务。面板会**显示具体原因**,不是白屏。
**挂卡片会改动我的 DSH 吗?**
不会。它不重写 DSH、不碰你的 profile,随时可以撤掉。
---
## 卡片开发
一张卡片就是一个带 `dshCard` 清单的 npm 包:
```json
{
"name": "my-card",
"version": "1.0.0",
"main": "index.js",
"dshCard": { "id": "my-card", "name": "我的卡片", "entry": "index.js", "api": 1 }
}
```
```js
// index.js —— ⚠️ 绝不 import 任何 @deepseek-ai/*,所有交互走 api
export function apply(api) {
api.log(`已装载(scope=${api.scope})`)
// 给连接上的会话提供工具
api.registerTool('greet', async (args) => {
return `你好,${args?.name ?? '世界'}`
})
}
// 面板 HTML(可选)
export function renderPanel(api) {
return `可见范围:${api.scope}
`
}
```
| `api` 成员 | 说明 |
|:---|:---|
| `registerTool(name, fn)` | 注册工具 → 会话经 `connection_card_tool` 调用 |
| `send(kind, text)` / `read()` | 以某一端身份收发连接消息 |
| `on(event, handler)` / `emit(event, data)` | 连接级事件 |
| `scope` | 本实例作用在哪一端(`both` / `a` / `b`) |
| `log(...)` | 写宿主日志 |
**`dshCard.api`** 是卡片声明自己需要的 **CardAPI 版本**(缺省 1):
- **加东西不升版本** —— 老卡片照常跑
- **删或改语义才升版本** —— 宿主会拒绝装载要更高版本的卡片,并说明原因
> 这是**我们自己的兼容性护栏**:卡片不依赖 DSH 内部包,所以 DSH 升级不影响卡片;
> 但**我们改 `CardAPI` 会影响卡片**,而 DSH 的版本门控管不到这一层。
细节见 [`docs/card-protocol.md`](docs/card-protocol.md)。
---
## 维护
**已实现**
- 连接:拖拽建连(开关语义)、三会话两两相连、持久化 + 重启恢复
- 权限:分方向三档、不对称、升级需对方确认、拒绝原因自证
- 感知 A:自动采集工作状态(0 上下文)
- 共识 B:公约盒(0 上下文)
- 传话 C:三档紧急度 + 自动降级
- 卡片:模板发现 / 装载 / 按端可见 / 面板内安装 / **更新** / 崩溃隔离
- 卡片工具:桥接调用 + 可见范围强制
- 卡片目录**版本化**(装载中也能更新)
- **工具按会话 scope**:没参与连接的会话**不背** `connection_*` 的 schema(省 ~1700 tokens),
走官方 `system-prompt/assemble` waterfall,整条链 **fail-open**(拿不准就原样下发)
—— **`v1.0.1` 起才有此行为**;`v1.0.0` 是全局注册
**已知未做**
| 项 | 说明 |
|:---|:---|
| `mountUI` / `requestRemote` | 接口已就位、实现待补(`mountUI` 目前只设了个 dataset 属性) |
| 卡片工具的 schema | 不占独立 schema(有意为之);调用方需先 list 再 call |
**已知坑:改完代码后"测试全绿但用户看到旧行为"**
这个坑会**反复**发生,而且现象很像"功能坏了",所以单独写出来:
| 半边 | 什么时候才装载新代码 |
|:---|:---|
| **宿主半边**(`lib/index.js` 等) | 改完 `lib/` 对**已运行的进程无效** —— 必须**重启 DSH 或热重载插件**。否则面板里跑的还是旧代码(真实撞过:用户点安装报的还是最初那版的 `fetch failed`,而代码早就修好了) |
| **客户端半边**(`lib/client.js`) | 即使宿主重载了,浏览器**还要刷新页面**才装载新包(本实例 `client-hmr` 是 active 的,但用户不刷新就看不到新行为) |
**排查口诀**:先看报错**长什么样**。旧代码的报错往往是**光秃秃一句**(`fetch failed`),
新代码的报错会**列出通道、字节数、归因**。一眼就能分辨跑的是哪一版。
同类误读还有一个(不是本插件的问题,但对端同结论):**对端会话离线时**,
连接消息会走冷唤醒通道落地成普通消息、**没有卡片壳** —— 见下面那条「已知差异」。
**已知差异:连接消息在"对端离线"时没有卡片壳**(不是故障,是投递通道差异)
同一套机制,两种落点:
| 对端状态 | 投递通道 | 界面表现 |
|:---|:---|:---|
| **在线** | `agents.followup` → 代理收件箱 | **折叠卡**(带状态行、可展开) |
| **不在线** | 冷唤醒兜底 `sessionController.prompt` | **普通消息**(没有卡片壳) |
后者由框架渲染成一条普通用户消息,**投递方控制不了它的外观**。所以我们在**内容开头加了标识**
(`COLD_DELIVERY_PREFIX`):
```
📨 【连接消息】
> 对端会话不在线时,这条消息会以普通消息送达(卡片本身没问题)。
> 会话在线时,同样的消息会显示为带状态的卡片。
```
看到这个标识就说明卡片正常,只是对端当时不在线。
**不需要发送方配合**改任何字段。
---
## 文档
| 文档 | 内容 |
|:---|:---|
| [`docs/capabilities.md`](docs/capabilities.md) | **能力清单**:逐项支持情况、上下文成本、已知限制 |
| [`docs/card-protocol.md`](docs/card-protocol.md) | 卡片协议:清单、CardAPI、安装校验、分发来源 |
| [`docs/compatibility.md`](docs/compatibility.md) | 兼容性:DSH 版本门控机制、两条防线 |
| [`docs/adapter-api.md`](docs/adapter-api.md) | DSH 适配层:稳定接口与白名单 |
---
MIT · 与 DSH 官方无隶属关系