dsh-biz-bridge

DeepSeek Harness（DSH）业务桥接插件 —— 通过标准 HTTP 协议把 DSH 的 agent 能力开放给业务系统。业务方只发一个带签名的 HTTP 请求，就能拿到流式（SSE）或 回调两种响应；session_id 复用即多轮上下文，任务调度与日志全由插件落 SQLite。 附件双向转接：业务方用 URI 提交图片/文件（插件拉取并落到该 client 的工作目录）， agent 产出的文件也会被发现、登记并以签名下载接口回传。

安全：面向可信业务系统（持私钥、经签名认证的合作方）——通道可信，但业务方转发过来的 内容可能源自更上游，故内容层仍按不可信处理。插件负责入口校验（签名、SSRF、路径越界、越权、 附件体量与完整性）与 agent 能力约束（security.denyTools 移除工具、security.sandboxMode: read-only 拒绝写入与删除）；读边界与容器隔离由运行时承担——详见 docs/security.md。

• 当前版本：0.1.5（草创/早期开发，接口可能调整，暂不建议生产关键链路）
• 源码即仓库根：完整插件工程即本目录，代码随便看、随便改。

目录速览

.                            # 本仓库根
├─ src/                      # 插件源码（入口 src/index.ts）
├─ tests/                    # 单元测试（零依赖，npm test 即可跑）
├─ docs/                     # 用户文档（本 README 之外都在这）
│   ├─ building.md           #   源码构建、测试、开发调试
│   ├─ config.md             #   配置与部署（字段参考 + 部署步骤 + FAQ）
│   ├─ api.md                #   HTTP 接入（签名协议 + 接口定义 + 错误码）
│   ├─ security.md           #   安全边界（插件负责什么 / 不负责什么 + 部署建议）
│   └─ cordis.patch.yml      #   配置样例（直接复制到 profile 使用）
├─ release/                  # 发布产物（dsh-biz-bridge-0.1.5.tgz + CHANGELOG）
├─ tools/bundle/             # 便携部署包构建器（把 Node+DSH+pnpm+本插件打成可带走的目录）
└─ public/static/            # 随插件分发的参考工具页（管理员/接入测试/密钥工具；接入测试页含附件双向操作）

快速开始（clone 之后）

准备：Node ^22.19.0 || >=24.0.0（DSH 的引擎要求）；一台装有 DSH 的机器（有 dsh 命令即可，本插件的普通用法不需要 web/GUI，装好 DSH 的同一环境就行）。

第一步 · 拿到安装包（二选一）

# A. 直接用仓库随附的发布包
ls release/dsh-biz-bridge-0.1.5.tgz

# B. 或自己从源码构建（产物同样写到 release/）
pnpm install && pnpm build && npm run release    # 前提见 docs/building.md

第二步 · 建独立 profile 并安装（只做一次；会先自动带上 @deepseek-ai/dsh-base 运行时核心，再装本插件）

dsh plugin --profile bizbridge add ./release/dsh-biz-bridge-0.1.5.tgz

第三步 · 启动

dsh --profile bizbridge

启动日志出现 activation rescue 与 activated 即成功。

第四步 · 配业务方 client 公钥（改完即时生效，无需重启）

公钥表在 $DSH_HOME 同级的插件数据根下：

<runtime.path>/clients/
├─ clients.json          [{ "clientId": "...", "scope": [...], "enabled": true }]
└─ <clientId>.pem        该 client 的公钥（整段原文）

公钥从哪来：打开 http://127.0.0.1:42731/bizbridge/static/utils.html（工具页无需认证；密钥对在浏览器 本地生成、不上传；该页另一个按钮「立即同步模型配置」会向本机发一次同步请求）生成密钥对，把它给出的 公钥存成 clients/<clientId>.pem，并在 clients.json 里登记一行。

未配任何 client 时服务照常启动，但所有 API 请求返回 401、只有静态页可达（fail-closed）， 所以先跑起来是安全的。

第五步 · 跑通一次

用接入测试页 http://127.0.0.1:42731/bizbridge/static/client.html 跑一次 stream / callback。附件也能在这页直接试：表单里「添加附件」填 URI， 或点「填入本机示例」用插件自己的静态页当 file 附件；入站回执与产物清单都带「下载」按钮 （走签名下载接口）。

模型不止默认那两个？ 桥接 profile 是 headless，provider 目录按 profile 存：在 dsh-web （--profile web）里配的模型，桥接每次启动会自动同步过来（models.syncFromProfile: web）； 改完不想重启，就用工具页的「立即同步模型配置」。只同步 provider 段，默认模型不动。 字段与两种模式（跟随 web / 自己显式配）见 docs/config.md 的 ### models。

字段与降级语义（解析失败保留上一份、enabled:false 即停用）见 docs/config.md 的 §auth。

常规用法就是上面这条独立进程路径：它和你的 web/GUI 互不干扰，改/重启它都不会 中断正在跑的 web 会话。把插件并入其它 profile 只是开发联调的可选路径，细节见 docs/config.md。

目标机器不能预装 Node / DSH 时：用 tools/bundle/ 生成一个 自带运行时（Node + DSH + pnpm）的便携包 —— 目标机器解压即可跑，上述流程在包内等价。 该产物体积数百 MB，由使用者在本机生成，不进本仓库。

详细文档（子文档）

想看什么	去哪
源码构建、测试、开发调试	docs/building.md
生成便携部署包（自带 Node/DSH/pnpm）	tools/bundle/README.md
配置与部署（字段参考 + 部署步骤 + FAQ）	docs/config.md
HTTP 接入：签名协议、接口定义、错误码	docs/api.md
安全边界：插件负责什么、不负责什么	docs/security.md
配置样例（直接复制到 profile 使用）	docs/cordis.patch.yml
版本历史与发布说明	release/CHANGELOG.md

License

MIT