dsh-session-bridge

> One CLI (and one DSH plugin) to read, list and message every DeepSeek Harness conversation.
> 在终端或任意 DSH 会话里，查看 / 读取 / 给所有 DeepSeek Harness 对话发消息。

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

这个工具解决什么问题

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

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

• 可枚举 —— 列出全部会话：标题、工作目录、是否正在跑、token 用量。
• 可读 —— 直接读磁盘上的转录（session.v4.jsonl.zstd），App 关着也能读。
• 可写 —— 通过 DSH 桌面 App 自己的本地 RPC，把消息追加进任意会话，让它自己的 agent 真的跑一轮。
• 可聊 —— 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

特性

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

前置条件

安装

方式 A：只当 CLI 用（最快，推荐先试这个）

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

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

方式 B：装成全局命令

npm install -g ./            # 在仓库目录里执行
dshctl status                # 之后任意目录可用

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

在 DSH 的 profile 目录（macOS 默认 ~/.dsh/profiles/desktop）里：

cd ~/.dsh/profiles/desktop
npm install /绝对路径/dsh-session-bridge

然后把它加进 package.json 的 dsh.profile.bundles：

"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 之后，也可以直接：

cd ~/.dsh/profiles/desktop && npm install @dylanyeung/dsh-session-bridge

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

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

快速开始

# 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（或「继续」）会再问一句要说什么，直接回车就发「继续」；空行同样等于继续。

CLI 参考

dshctl.py status
dshctl.py doctor [--json]           # 本机平台 / App 目录 / Cookie 库 / CLI / 活端口
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  ''
dshctl.py start [--port N] [--key K]   # 兜底：App 没开时起一个 helper web 实例
dshctl.py stop

插件工具

模型侧看到的例子：

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 —— 对方按键到不了你的进程。正确做法是「状态外置 + 每轮渲染菜单」：

./tools/dshctl.py focus "安装插件"   # 记住当前对话对象 → ~/.cache/dshctl-chat.json (600)
./tools/dshctl.py where              # 看当前在跟谁聊
./tools/dshctl.py focus -            # 退出

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

菜单固定一行，因为小屏上多行选项很难点：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//，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-/session.v4.jsonl.zstd，取最后一条 assistant/message。

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

和 DSH 原生 session_search 的关系

DSH 自带一个实验性 bundle @deepseek-ai/dsh-experimental-session-search，里面的
dsh-tool-session-query 注册了五个只读工具：

它默认不启用：既不在 @deepseek-ai/dsh-base，也不在 desktop profile 的
dsh.profile.bundles 里，要用得自己把这个 bundle 加进 profile。

所以两边的关系是：

• 重叠：让 agent 回顾/检索以前的会话内容——原生这五个工具就够了，本插件不多做事。
• 原生没有：dshctl list 这种带 running/打开状态的会话清单；往任意一个既有会话里发 prompt；
  watch 的实时流式跟随；chat 的跨会话轮次状态机；以及不依赖宿主进程、能在 cron/脚本里跑的 CLI。
• 原生确实有 send_message / spawn_teammate，但那是发给 Agent Team 里自己 spawn 的 teammate，
  不是 workspace 里已经存在的任意会话。

一句话：只想"翻旧账"用原生；要"给别的会话派活、盯活、脚本化"，才需要这个插件。

安全模型与红线

• 凭据只经过内存：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 暴露给你。

故障排查

目录结构

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         # CLI：本地 RPC 客户端 + watch 流 + 交互式 chat
├── tools/dshtool.py        # 纯离线：读 zstd 转录
├── tools/ws.py             # 纯标准库 RFC 6455 客户端（watch 用）
├── tools/appenv.py         # 跨平台 App 目录 / Cookie 库 / CLI / 端口发现
├── tests/                  # 离线单测 + 插件契约
└── .github/workflows/ci.yml
├── cordis.patch.yml        # 插件注册声明
├── docs/PROTOCOL.md        # RPC 协议（逆向所得，含错误码）
├── docs/TUTORIAL.md        # 10 分钟教程
└── examples/               # 可复制的小脚本

开发与测试

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（语法闸 + 单测 + CLI 冒烟 + 文档文件存在性）、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（路径/CLI/端口全平台；Cookie 加密值是 best-effort）
• [x] dshctl watch <会话>：实时跟随某会话输出（/api/remote.mux + session/follow，tools/ws.py）
• [x] 插件里直接暴露 session_chat（与 CLI 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 lets you list, read and message every DeepSeek Harness session from one CLI or as a DSH plugin.

• dshctl list | tail | watch | prompt | chat | focus | doctor | raw — Python 3 stdlib only.
• session_list / session_read / session_send / session_chat — four first-party DSH tools.
• Auth = reuse the desktop app's own dsh-auth-* cookie; transport = local JSON-RPC at 127.0.0.1:51413; transcripts are read straight off disk with zstd.
• chat prints a one-line menu after every turn (1 continue 2 switch 3 context 4 quit) so it stays usable on a phone.

See docs/PROTOCOL.md for the reverse-engineered protocol and docs/TUTORIAL.md for a 10-minute walkthrough.