zljr/dsh-share

dsh-share

通过局域网将 DeepSeek Harness 会话共享为只读、令牌保护的快照。

📖 中文文档

dsh-share 是一个 DeepSeek Harness 插件，它在会话标题栏中添加了一个 Share 按钮。一键即可将当前对话冻结为一个自包含的只读 HTML 页面，并打印出一个局域网 URL —— 例如 http://192.168.1.20:3081/s/ —— 同一网络上的任何设备都可以在浏览器中打开它。

主 harness 继续监听 127.0.0.1（因此永远不会暴露 agent 的命令执行）。共享由独立的只读 HTTP 服务器提供，它只会为有效令牌返回预渲染的快照页面。

功能特性

- 🔗 一键共享 —— 会话标题栏中的 Share 按钮（位于官方 "Session log" 操作旁边）。
- 🔒 只读且隔离 —— 共享服务器自行绑定 0.0.0.0:；它只暴露 GET /s/。没有 RPC，没有写入，查看时不读取会话。
- 🧊 冻结快照 —— 转录内容和会话统计在共享时被捕获；之后的编辑或压缩永远不会改变已共享的页面。
- 🔑 可撤销 + 可选过期 —— 128 位随机令牌；随时停止共享，或选择 1 小时 / 24 小时 / 7 天过期。
- 📝 Markdown 转录 —— 用户和助手消息以 Markdown 渲染（安全：原始 HTML 被转义，javascript: URL 被阻止）。
- 🪗 可读性 —— 长消息自动折叠在预览之后；连续的工具调用折叠为一个 "🛠 tool calls" 分组。
- 📊 会话统计标题栏 —— 轮次、步骤、实际耗时、工具调用时间、缓存命中、输入/输出令牌，以及当前上下文占用情况，并带有按类别划分的组成条。
- 🌗 深色与浅色主题 —— 共享页面遵循 prefers-color-scheme。
- 💾 跨重启持久化 —— 共享存储在 ~/.dsh/dsh-share.json 中。
- 📡 智能局域网地址 —— 过滤掉虚拟适配器（WSL / Hyper-V / Docker / VPN / …）并探测默认路由，以便手机可访问的 IP 排在首位。

工作原理

dsh-share 是一个双面 dsh 包，与其他 harness 插件一样：

| 部分 | 运行于 | 角色 |
|------|---------|------|
| Host (src/host) | Node（harness 进程） | 将会话事件日志折叠为转录内容 + 统计信息，存储冻结的快照，并通过独立的 node:http 服务器在 /s/ 上提供它。还暴露一个 /dsh-share RPC（create / revoke / list）。 |
| Client (src/client) | 浏览器 | 在 conversation.session.header.utilities 中注册 Share 按钮，并渲染对话框（过期选择器、复制 / 撤销 / 打开）。 |

上下文组成的令牌估算复用了 harness 自身的固定密度启发式方法（约 4 个字符 ≈ 1 个令牌），与 dsh-context 一致。

安装

从 npm 安装

dsh plugin --profile web add @zljr/dsh-share
dsh --profile web
就是这样——发布的包已经包含了构建好的 lib/，因此最终用户无需任何构建步骤。

从源码构建（本地开发）

1. 构建包产物（lib/）
pnpm install
pnpm build

2. 安装到 web profile（本地路径）
dsh plugin --profile web add /absolute/path/to/dsh-share

3. 重启 web UI
dsh --profile web

打开任意会话，点击标题栏中的 Share。共享服务器会在首次使用时惰性启动。

配置

环境变量（或通过 cordis.patch.yml 提供的配置对象）：

| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| DSH_SHARE_HOST | 0.0.0.0 | 只读共享服务器的绑定地址。 |
| DSH_SHARE_PORT | 3081 | 共享服务器的端口。 |

在 Windows 上，首次监听 0.0.0.0 可能会触发防火墙提示——请允许它，以便其他设备可以访问该链接。

安全模型

- 主 harness 仅限回环访问；只有只读共享界面可以从局域网访问。
- 共享令牌为 128 位随机（不可猜测），并且可以撤销或设置为过期。
- 共享页面不包含 JavaScript，也不包含外部资源；消息文本以 Markdown 渲染，原始 HTML 会被转义，危险 URL 会被拒绝。
- 快照是冻结的——它不是会话的实时视图，并且在创建后绝不会从会话存储中重新读取。

开发

pnpm install     # 开发依赖（typescript、esbuild、react、jsdom……）
pnpm build       # 打包 host（lib/index.js）+ client（lib/client.js）
pnpm test        # 类型检查 + host/client 功能测试
pnpm typecheck   # 仅 tsc --noEmit

项目结构

src/
shared/          # 两半共享的通信契约（仅类型）
host/
index.ts       # /dsh-share RPC + 惰性共享服务器生命周期
server.ts      # 只读 HTTP 服务器 + 局域网地址选择
store.ts       # token → 快照注册表（持久化 JSON）
transcript.ts  # 事件日志 → 人类可读记录
stats.ts       # 事件日志 → 会话统计
pricing.ts     # token 估算启发式
markdown.ts    # 安全的 Markdown 渲染
html.ts        # 快照页面渲染
client/
index.ts       # 标题栏按钮注册
components/    # ShareButton + 对话框
scripts/build.mjs  # esbuild 构建（host ESM + client __ModuleLoader__ 打包）
tests/             # host/client 功能测试（jsdom + 真实 React）

发布

npm login --registry=https://registry.npmjs.org
npm publish --registry=https://registry.npmjs.org

prepublishOnly 脚本会在每次发布前重新构建 lib/，因此 tarball 始终包含最新的 host + client 打包产物。

许可证

MIT