dsh-connection-card-host
中文 | English
让 DSH 的多个会话互相看得见、说得上话、共用得上工具 —— 而互不打扰。
在一个 DSH 里同时开着好几个会话（一个查资料、一个写代码、一个跑实验）是常态，
但它们互相隔离：不知道对方在干什么，也没法把结论递过去。
这个插件把「连接」做成 DSH 里的一等对象：会话是节点，连接是容器，卡片是连接级插件。
左：真实操作（原视频） · 右：同一动作的结构示意，标出了「开关语义」
目录
它能做什么
| |
|---|
| 互相看得见 | 查得到对方正在改哪个文件、计划进行到第几步、最近用了什么工具 —— 自动采集，对方不需要专门告诉你 |
| 说得上话 | 给对端发消息，三档紧急度自己判断：只告知（不打断）／排队／插话 |
| 共用得上工具 | 连接上可以挂卡片：卡片能给会话提供工具，甚至带几十 MB 的真依赖 |
| 共用前提 | 「公约盒」存放双方说好的事：接口、单位、命名、分工边界 |
| 互不打扰 | 感知是拉取式的 —— 对方不查就零成本；不相关的连接不会吵到你 |
连线颜色表示该方向的权限：灰=只读，蓝=可建议，橙=可写入；两端可不对称
三十秒上手
- 建连接：按住输入框左侧的圆点（或会话行上的「…」），拖到左侧会话列表里的某一行。
锚点原视频 · 会话行原视频
- 开关语义：拖到未连的行 = 连接；拖到已连的行 = 断开（悬停时会提示）
- 也可以从侧栏「连接」面板里选两个会话
- 完事。两端各自收到一条静默通知（说清了连上了谁、能做什么），不打断任何人。
- 想看得更细：点侧栏「连接」，或者让会话自己调
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 端）」
卡片里可以塞真依赖
实测：把社区插件 dsh-pdf 的解析核 + pdfjs-dist（33 MB） 包成一张卡片，
装到 $DSH_HOME/connection-cards/cards/，不碰 DSH profile。
会话通过桥接调用，拿回真实解析结果。
面板内安装与更新
卡片选择器：内置卡片一键加；也可以给包名、仓库 tgz 地址或本地目录来安装
架构速览
三层，边界很硬 —— 每层只跟下一层说话：
┌─────────────────────────────────────────────────────────────┐
│ 卡片层（连接级插件） │
│ 只依赖 CardAPI，绝不 import @deepseek-ai/* │
│ → DSH 升级不影响卡片；我们改 CardAPI 才影响（有版本护栏） │
├─────────────────────────────────────────────────────────────┤
│ 连接层（本插件） │
│ 连接 / 权限 / 感知 / 公约盒 / 卡片宿主 / 消息投递 │
│ → DSH 升级时，只需要改这一层 │
├─────────────────────────────────────────────────────────────┤
│ DSH 适配层（DSHAdapter + 白名单 + 审计） │
│ 所有 DSH 交互的唯一出口；不重写 DSH 的通信/权限/插件系统 │
└─────────────────────────────────────────────────────────────┘
权限是分方向的
一根线两端各一个圆点，颜色是那个方向的权限 —— 两个方向互不影响，
可以做成「甲能发、乙只能看」：
连线颜色表示该方向的权限：灰=只读，蓝=可建议，橙=可写入；两端可不对称
只读不影响感知：工作状态与公约盒都是对端主动查询的，与权限无关。
降低权限立即生效；提高权限需要被授权的一方确认。
卡片工具怎么到会话手里
卡片注册的工具不各占一个 schema —— 会话只看得见一个常驻桥接，
按需发现、按需调用，且在桥接层强制可见范围：
会话用一个常驻桥接工具，按需发现并调用卡片提供的工具，且受可见范围约束
为什么这样做
1. 不重写 DSH
不碰 DSH 的通信、权限、插件系统；卡片不注册到 DSH 全局 Loader。
所有 DSH 交互走中间适配层，DSH 升级时只需要改这个插件。
2. 双向自动镜像 —— 我们把它关掉了
早期版本会自动把会话内容转发给对方。实测下来这是错的，三次事故：
- 用户给 A 下的指令被镜像给 B → B 当成自己的任务去做
- 助手的汇报被镜像 → 对端当成用户指令去响应
- 助手对用户说的旁白被镜像 → 对端显示「收到执行请求」并真的跑了一轮
对端的量化：30 条 / 12,765 字的镜像占它会话"用户侧字符"的 77.8%，其中没有一条产生了有用动作。
所以默认不自动转发任何东西。 跨会话传话走显式发送，感知走 A/B 两层。
3. 打断是要花钱的
旧实现的投递策略是"对端在跑就插话"—— 等价于每条消息都是最高优先级。
现在紧急度由发起方判断，默认排队。
省在哪
| 项 | 数字 | 说明 |
|---|
| 感知（A + B 两层） | 0 上下文 | 拉取式；对端不查就不产生任何成本 |
| 卡片工具 | 1 个常驻 schema | 而不是每个卡片工具各占一个 |
| 自动镜像 | 0（已关闭） | 关闭前实测 77.8% 是无用内容 |
| 不相关的连接 | 0 打扰 | 搭线不唤醒；不相关的会话照常干活 |
唯一固定成本：本插件 5 个 connection_* 工具的 schema ≈ 1700 tokens 常驻。
（这一项还可以再优化 —— 见当前状态。）
安装
本插件不上 npm。 DSH 的 peer 依赖（@deepseek-ai/dsh-client-runtime 等）不在公开 registry 上，
所以 npm install 会去公开 registry 装 peerDependencies 并必然失败
（实测报 notarget ... @deepseek-ai/dsh-client-runtime）。安装走 GitHub：
# 稳定线（本仓库，对外门面）
dsh plugin --profile web add github:Noob-stupid/dsh-connection-card-host
# 同上，GitHub 简写（可省 github:）—— 带斜杠就走 GitHub 仓库
dsh plugin --profile web add Noob-stupid/dsh-connection-card-host
# 要固定版本：用 Releases 的 tgz 附件（当前已发布 v1.0.1）
dsh plugin --profile web add https://github.com/Noob-stupid/dsh-connection-card-host/releases/download/v1.0.1/dsh-external-dsh-connection-card-host-1.0.1.tgz
# 同一份 tgz 先下载到本地再装，效果相同
dsh plugin --profile web add ./dsh-external-dsh-connection-card-host-1.0.1.tgz
- 开发发生在预览线仓库
dsh-connection-card-host-preview；
本仓库是稳定门面，只在发版时按晋级流程同步。
lib/ 已随仓库提交：装完即可用，不需要构建步骤，本包也没有需要授权的构建脚本。
（dsh plugin 依赖 pnpm 在 PATH 上。）- ⚠️
github: 与简写装的是默认分支的最新提交，不是固定版本；
要固定版本请用上面的 Releases tgz。
四种写法的实测结果（pnpm 用 profile 同款配置 nodeLinker: hoisted +
autoInstallPeers: false，装完 lib 161 个文件）：
| 写法 | 结果 |
|---|
github:user/repo | ✅ 可用 |
user/repo（GitHub 简写） | ✅ 可用 |
| tgz 地址 / 本地路径 | ✅ 可用 |
| 裸包名（无斜杠 → 当成 npm 包名，走 registry） | ❌ 404，别用 |
dsh-connection-card-host 与 @dsh-external/dsh-connection-card-host 在 npm 上都不存在。
兼容性：peerDependencies 声明 @deepseek-ai/dsh >=0.2.0-rc.1 <0.3.0 ——
DSH 会在安装时按版本门控，不匹配会明确拒绝并说明原因（而不是装上再崩）。
卡片开发
一张卡片就是一个带 dshCard 清单的 npm 包：
{
"name": "my-card",
"version": "1.0.0",
"main": "index.js",
"dshCard": { "id": "my-card", "name": "我的卡片", "entry": "index.js", "api": 1 }
}
// 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 `<div>可见范围：${api.scope}</div>`
}
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。
当前状态
已实现并实测
- 连接：拖拽建连（开关语义）、三会话两两相连、持久化 + 重启恢复
- 权限：分方向三档、不对称、升级需对方确认、拒绝原因自证
- 感知 A：自动采集工作状态（0 上下文）
- 共识 B：公约盒（0 上下文）
- 传话 C：三档紧急度 + 自动降级
- 卡片：模板发现 / 装载 / 按端可见 / 面板内安装 / 更新 / 崩溃隔离
- 卡片工具：桥接调用 + 可见范围强制
- 卡片目录版本化（装载中也能更新）
已知未做
| 项 | 说明 |
|---|
| 工具按会话 scope | 5 个 connection_* 目前全局注册 —— 没连接的会话也背着 ~1700 tokens。接缝已定位（system-prompt/assemble waterfall），差注册写法 |
mountUI / requestRemote | 空壳（mountUI 只设了个 dataset 属性） |
| 卡片工具的 schema | 不占独立 schema（有意为之）；调用方需先 list 再 call |
文档
MIT · 与 DSH 官方无隶属关系
