会话桥 DylanYeung0929/dsh-session-bridge

dsh-session-bridge

一个命令行工具（外加一个 DSH 插件），读取、列出、给所有 DeepSeek Harness 对话发消息。
在终端或任意 DSH 会话里，查看 / 读取 / 给所有 DeepSeek Harness 对话发消息。

English summary · 快速开始 · 教程 · 协议

这个工具解决什么问题

DeepSeek Harness（下称 DSH）里的每个对话都是独立智能体，跑在自己的会话里，互相看不见。想「让 A 对话知道 B 对话在干什么」「在手机上继续电脑上的那个对话」，默认是做不到的。

dsh-session-bridge 把你机器上所有 DSH 会话变成可枚举、可读、可写的：

- 可枚举 —— 列出全部会话：标题、工作目录、是否正在跑、token 用量。
- 可读 —— 直接读磁盘上的转录（session.v4.jsonl.zstd），App 关着也能读。
- 可写 —— 通过 DSH 桌面 App 自己的本地 RPC，把消息追加进任意会话，让它自己的智能体真的跑一轮。
- 可聊 —— dshctl chat 提供一个带「每轮一行菜单」的跨会话聊天模式：1继续 2切换 3上下文 4退出。
- 可跟随 —— dshctl watch 订阅 session/follow 流，别的对话吐字时你这边实时滚屏（纯标准库 WebSocket 客户端，零依赖）。

┌──────────────┐ ① list / read（读磁盘，零依赖） │ 你的终端 / │ ─────────────────────────────────────┐ │ IM / 脚本 │ ▼ │ │ ② prompt（本地 HTTP JSON-RPC） ┌─────────────┐ │ dshctl.py │ ─────────────────────────────────▶│ DSH 桌面 App │ └──────────────┘ Cookie: dsh-auth-… │ :51413 │ └──────┬──────┘ │ 该会话自己的 agent 跑一轮 ▼ ~/.dsh/sessions//session.v4.jsonl.zstd

特性

| 能力 | 命令 | 需要 App 在跑？ |
| 列出所有会话 | dshctl list | 是（走 RPC） |
| 读某个会话最近 N 条 | dshctl tail <会话> 20 | 否（直接读转录） |
| 给某个会话发消息 | dshctl prompt <会话> "…" | 是 |
| 交互式跨会话聊天（带菜单） | dshctl chat <会话> | 是 |
| 实时跟随某个会话 | dshctl watch <会话> | 是（WebSocket session/follow） |
| 自检本机发现能力 | dshctl doctor | 否（只探测端口与 Cookie） |
| 记住「当前在跟谁聊」 | dshctl focus <会话> / where / focus - | 是 |
| 调任意 RPC 端点 | dshctl raw <ns/method> '<json>' | 是 |
| 在 DSH 里当工具用 | session_list / session_read / session_send / session_chat | 是 |

- 纯 Python 3 标准库 + Node ≥ 20，无第三方依赖（读转录只额外需要 zstd 命令）。
- 会话解析支持 session-<uuid> 全名、短前缀或唯一标题子串；命中多个时直接报错并列出候选，绝不悄悄选第一个（读错会话比报错更糟）。
- --json 全部命令可用，方便脚本化。
- 发消息前会打印目标会话 id + 标题，防止发错人；list 的 ● = 打开且近 5 分钟有写入，◐ = 打开但近期没动。

前置条件

| 项 | 要求 |
| 系统 | macOS（主支持）；Linux / Windows 为 beta：路径与命令行候选已覆盖，Cookie 加密值按 best-effort 解密，失败时回退到 helper 模式 |
| DSH | 桌面 App 正在运行（dshctl status 能看到 backend: app 即可） |
| Python | 3.10+（python3 --version；类型标注用了 X | None） |
| Node | ≥ 20（只有用插件/npx 时才需要） |
| zstd | brew install zstd（只在读转录时用；tail / read 命令） |

安装

方式 A：只当命令行工具用（最快，推荐先试这个）

git clone https://github.com/DylanYeung0929/dsh-session-bridge.git
cd dsh-session-bridge

brew install zstd # 若还没有bash
./tools/dshctl.py status # 应该输出 backend: app port: 51413

方式 B：装成全局命令 bash
npm install -g ./ # 在仓库目录里执行
dshctl status # 之后任意目录可用

方式 C：装成 DSH 插件（在任意 DSH 会话里用工具）

在 DSH 的配置档目录（macOS 默认 ~/.dsh/profiles/desktop）里： bash
cd ~/.dsh/profiles/desktop
npm install /绝对路径/dsh-session-bridge

然后把它加进 package.json 的 dsh.profile.bundles： json
"bundles": [
"...",
"@dylanyeung/dsh-session-bridge"
]

重启 DSH 后，会话里就多了四个工具：session_list、session_read、session_send、session_chat。

npm install 只装包，不会自动登记 bundle —— 上面那步必须做，否则重启后看不到这四个工具
（验证：~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles 里要有 @dylanyeung/dsh-session-bridge）。

发布到 npm 之后，也可以直接： bash
cd ~/.dsh/profiles/desktop && npm install @dylanyeung/dsh-session-bridge

仓库名仍叫 dsh-session-bridge；npm 包名带 scope，因为不带 scope 的同名包已被另一个作者占用。

插件只是把命令行包了一层，所以仍然需要 python3 在 PATH 里；想换解释器就设 DSH_SESSION_BRIDGE_PYTHON=/opt/homebrew/bin/python3。

快速开始 bash

1. 看看有哪些会话（● 表示正在跑）

./tools/dshctl.py list

2. 读某个会话最近 10 条（App 关了也能读）

./tools/dshctl.py tail "安装插件" 10

3. 给那个会话发一句话，并等它跑完

./tools/dshctl.py prompt "安装插件" "用一句话汇报你现在的进度" --wait 90

4. 进入交互式跨会话聊天（每轮后给一行菜单）

./tools/dshctl.py chat "安装插件"

5. 实时跟随某个会话，它吐字时你这边滚屏（Ctrl-C 退出）

./tools/dshctl.py watch "安装插件" --lines 3

chat 模式每轮回复后固定打印一行，在手机上也能盲打：

1继续 2切换 3上下文 4退出 ← 直接打字=继续

按 1（或「继续」）会再问一句要说什么，直接回车就发「继续」；空行同样等于继续。

命令行参考

dshctl.py status
dshctl.py doctor [--json] # 本机平台 / App 目录 / Cookie 库 / 命令行 / 活端口 dshctl.py list [--full] [--json] dshctl.py tail <会话> [N] [--json] [--full] dshctl.py watch <会话> [--lines N] [--no-stream] [--reasoning] [--json] [--quiet] dshctl.py prompt <会话> <文本> [--steer] [--wait SECS] dshctl.py chat <会话> [--steer] [--timeout SECS] [--context N] dshctl.py focus <会话> | focus - dshctl.py where dshctl.py raw <namespace/method> '<args json>' dshctl.py start [--port N] [--key K] # 兜底：App 没开时起一个 helper web 实例 dshctl.py stop

| 参数 | 说明 |
| --steer | 打断当前正在跑的轮次，把消息插进去（默认 queue，排在后面） |
| --wait SECS | 等该会话的轮次结束，最多 SECS 秒 |
| --json | 机器可读输出（list --json 默认给紧凑字段，加 --full 给原始完整行） |
| --lines N | watch 先回放最后 N 条（默认 5，0 = 只跟新内容） |
| --no-stream | watch 不跟踪半成品正文，只在消息落盘后打印 |
| --reasoning | watch 同时打印思考增量（默认隐藏） |
| 会话选择 | session-<uuid> 全名 / 唯一短前缀 / 唯一标题子串；有歧义时报错并列出候选 |

插件工具

| 工具 | 参数 | 作用 |
| session_list | full?: boolean | 列出全部会话；默认紧凑（id / 标题 / cwd / running / updatedAt / outputTokens），full:true 返回原始完整行 |
| session_read | session: string, count?: number | 读该会话最近 N 条（磁盘转录） |
| session_send | session: string, message: string, steer?: boolean, wait?: number | 追加消息并让该会话的智能体跑一轮 |
| session_chat | action: string, session?: string, text?: string, lines?: number, wait?: number | 和命令行 chat 共用同一个焦点状态（~/.cache/dshctl-chat.json）：open / say / peek / close / status，适合连续多轮对话 |
模型侧看到的例子： text
session_list({ full: true })
session_read({ session: "安装插件", count: 6 })
session_send({ session: "安装插件", message: "把结论压缩成三行", wait: 60 })
session_chat({ action: "open", session: "安装插件" })
session_chat({ action: "say", text: "把结论压缩成三行", wait: 60 })

跨会话对话协议（给聊天机器人 / IM 场景）

如果中间隔着一层聊天通道（微信、Slack、IM 机器人），不要指望用 chat 的终端 REPL —— 对方按键到不了你的进程。正确做法是「状态外置 + 每轮渲染菜单」： bash ./tools/dshctl.py focus "安装插件" # 记住当前对话对象 → ~/.cache/dshctl-chat.json (600) ./tools/dshctl.py where # 看当前在跟谁聊 ./tools/dshctl.py focus - # 退出

之后用户回 1/2/3/4（或 继续/切换/上下文/退出）时：

| 输入 | 动作 |
| 1 / 任意文字 | 把文字发给当前会话；1 后再空行、或直接空行都等于发「继续」 |
| 2 | 列出会话，选一个后切换 |
| 3 | 打印最近 N 条上下文 |
| 4 | 退出（focus -） |

菜单固定一行，因为小屏上多行选项很难点：1继续 2切换 3上下文 4退出。

工作原理（三分钟版）

1. 鉴权：从 DSH 桌面 App 的 Chromium Cookie 库 ~/Library/Application Support/@deepseek-ai/dsh-desktop/Cookies 里取 dsh-auth- （value 列就是明文，无需解 Keychain），payload 里带 authority: "127.0.0.1:51413"。
2. 调用：POST http://127.0.0.1:51413/api/<namespace>/<method>，body 是
{"type":"client-request","rpcId":…,"method":"session/prompt","payload":{"args":{…}}}。
3. 发消息：session/prompt 的 args 是 {"request":{requestId, sessionId, content:[{type:"text",text}], mode:"queue"|"steer"}} —— 注意 session/list 用的是 {"_request":{}}，参数名不一样。
4. 读回复：不依赖 RPC，直接 zstd -dc 解 ~/.dsh/sessions/<项目>/session-<uuid>/session.v4.jsonl.zstd，取最后一条 assistant/message。

完整字段、错误码、边界条件见 docs/PROTOCOL.md；手把手操作见 docs/TUTORIAL.md。

安全模型与红线

- 凭据只经过内存：helper 启动时 DEEPSEEK_API_KEY 只通过子进程 env 传入、不落盘（0.1.1 起；旧版写进 ~/.cache/dshctl.json 的 key 会在下次 start 时自动清掉）。helper 自己的短期 token 存在 600 的 ~/.cache/dshctl.json 里，供后续命令复用；focus 状态文件只存会话 id 和标题。
- 所有写操作都必须显式指名会话；解析失败宁可不发（报 no session matching）。
- 本项目作者的默认红线（你也可以写进自己的 agent 规则里）：
- 不代转账、不代答应、不发文件/图片、不加好友/退群；
- 代表用户发言前先核对「目标会话标题」，发完回报结果；
- 不要把 ~/.dsh/.credentials.yaml、Cookie 库内容贴到任何对话或日志里。
- 这个工具等价于「让当前会话拥有给别的会话发消息的能力」——它不会绕过任何模型侧的权限，只是把 DSH 已有的 RPC 暴露给你。

故障排查

| 症状 | 原因 | 解决 |
| dshctl: cannot find the DSH app cookie | App 没开，或 Cookie 库路径不同 | 先启动 DSH 桌面 App；确认 ~/Library/Application Support/@deepseek-ai/dsh-desktop/Cookies 存在 |
| connect ECONNREFUSED 127.0.0.1:51413 | 端口变了（DSH 重启会换端口） | dshctl status 会读 Cookie payload 里的端口；仍失败就用 dshctl start 起 helper |
| 会话名不唯一 / dshctl: ambiguous … | 标题或前缀命中多个会话（这是有意的保护） | 按列出的候选补全 id，或改用更长的标题 |
| no session matching "xxx" | 标题 / 前缀不存在 | 用完整 session-<uuid>，或改用唯一标题子串 |
| missing "_request" / missing "request" | 参数名写错 | list 用 _request，prompt 用 request（见协议文档） |
| 能读不能发 | App 在跑但会话 preset 是 desktop 专属 | 这是设计限制：helper 实例不 compose computer-use 之类 preset，只能直连 App |
| tail 报 zstd 不存在 | 没装 zstd | brew install zstd |

目录结构

dsh-session-bridge/
├── bin/dshctl.mjs # npm bin 垫片 → tools/dshctl.py ├── lib/index.mjs # DSH 插件：session_list / session_read / session_send / session_chat ├── tools/dshctl.py # 命令行：本地 RPC 客户端 + watch 流 + 交互式 chat ├── tools/dshtool.py # 纯离线：读 zstd 转录 ├── tools/ws.py # 纯标准库 RFC 6455 客户端（watch 用） ├── tools/appenv.py # 跨平台 App 目录 / Cookie 库 / 命令行 / 端口发现 ├── tests/ # 离线单测 + 插件契约 └── .github/workflows/ci.yml ├── cordis.patch.yml # 插件注册声明 ├── docs/PROTOCOL.md # RPC 协议（逆向所得，含错误码） ├── docs/TUTORIAL.md # 10 分钟教程 └── examples/ # 可复制的小脚本

开发与测试 bash
python3 -m py_compile tools/dshctl.py tools/dshtool.py tools/ws.py tools/appenv.py
node --check lib/index.mjs
python3 -m unittest discover -s tests -v # 68 个离线单测：消息提取、resolve 消歧、lock 语义、

跨平台路径、AES/GCM 向量、WebSocket 帧、watch 渲染

node tests/plugin.test.mjs # 插件契约：stub defineTool → 断言注册 4 个工具
./tools/dshctl.py list --json | head # 端到端可用性（需要 App 在跑）

CI（.github/workflows/ci.yml）每次 push 都会跑：Python 3.10 / 3.13 × ubuntu / macOS（语法闸 + 单测 + 命令行冒烟 + 文档文件存在性）、Node 20 / 22（package.json 契约 + 插件注册测试 + cordis patch 形状）。全部离线，不需要 DeepSeek Harness 或任何凭据。

本项目是在实际使用中逆向出来的，边界条件都记在 docs/PROTOCOL.md；欢迎提 issue / PR 补平台支持（Windows、纯 headless 无 App 场景）。

Roadmap

- [x] Linux / Windows 的 Cookie 与端口发现 → tools/appenv.py（路径/命令行/端口全平台；Cookie 加密值是 best-effort）
- [x] dshctl watch <会话>：实时跟随某会话输出（/api/remote.mux + session/follow，tools/ws.py）
- [x] 插件里直接暴露 session_chat（与命令行 chat 共用焦点状态）
- [x] 单元测试 + CI（GitHub Actions：python 3.10/3.13 × ubuntu/macOS、node 20/22）

License

MIT © 2026 Dylan Yeung

English summary

dsh-session-bridge 让你从一个命令行或作为 DSH 插件，列出、读取并向每个 DeepSeek Harness 会话发消息。

- dshctl list | tail | watch | prompt | chat | focus | doctor | raw —— 只用 Python 3 标准库。
- session_list / session_read / session_send / session_chat —— 四个第一方 DSH 工具。
- 认证 = 复用桌面 App 自己的 dsh-auth- cookie；传输 = 本地 JSON-RPC，地址 127.0.0.1:51413；转录直接从磁盘用 zstd 读。
- chat 每轮结束后打印一行菜单（1 continue 2 switch 3 context 4 quit），在手机上也能用。

逆向出的协议见 docs/PROTOCOL.md，10 分钟上手见 docs/TUTORIAL.md。