dsh-bailinghub 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,19 +4,38 @@ The dependency direction is one-way:
4
4
 
5
5
  ```text
6
6
  dsh-bailinghub
7
- -> DeepSeek Harness in-box MCP Client
8
- -> bailinghub-mcp-server
9
- -> BailingHub public Client API
10
- -> operator-selected business route
7
+ -> DeepSeek Harness native Cordis lifecycle
8
+ -> bailinghub-mcp-server/sdk
9
+ -> BailingHub Agent Client Core
10
+ -> Core-selected business adapter and final business authorization
11
11
  ```
12
12
 
13
13
  This repository owns only the DSH bundle and its compatibility evidence. It does not fork or
14
14
  modify DeepSeek Harness, BailingHub Core, the generic MCP adapter, or a downstream business
15
15
  system.
16
16
 
17
- The integration does not establish a trusted business subject, grant permissions, make an
18
- approval decision, or replace the business system's final authorization. It also does not
19
- govern DSH tools that are unrelated to the three BailingHub MCP tools.
17
+ The integration does not grant permissions, make an approval decision, or replace the business
18
+ system's final authorization. It also does not govern DSH tools unrelated to the dynamic
19
+ BailingHub tool surface.
20
20
 
21
21
  DeepSeek and DeepSeek Harness are names of their respective owners. This is an independent
22
22
  community integration, not an official DeepSeek plugin or partnership.
23
+
24
+ ## Public native line (0.2.0 onward)
25
+
26
+ Version 0.2.0 introduced this dependency path. Version 0.3.0 keeps it separate from the public
27
+ static MCP path and adds the stable multi-connection lifecycle:
28
+
29
+ ```text
30
+ DeepSeek Harness local Agent
31
+ -> dsh-bailinghub native Cordis host adapter
32
+ -> bailinghub-mcp-server/sdk
33
+ -> BailingHub Agent Client Core
34
+ -> Core-selected business adapter and final business authorization
35
+ ```
36
+
37
+ This repository owns only the DSH host adaptation and compatibility evidence. DSH owns local
38
+ reasoning and tool orchestration; the SDK owns authorization/credentials and HTTP DTO mapping;
39
+ Core owns trusted identity, authorization, candidate trimming, approval, invoke/resume, knowledge
40
+ retrieval, and audit. The adapter does not copy Core governance or knowledge bases, establish a
41
+ business identity, govern unrelated DSH tools, or upload hidden reasoning.
@@ -2,93 +2,220 @@
2
2
 
3
3
  [English](../README.md) | 简体中文
4
4
 
5
- 在电脑上的 DeepSeek Harness 里,通过 BailingHub 向已经接入的业务 route 发起受控任务,
6
- 并在同一会话中持续查看状态和可用结果,不必再进入每个业务后台里的嵌入聊天入口。
5
+ 把商城、SaaS 或其他业务系统接到 BailingHub 后,本地 DeepSeek Harness 智能体就能直接操作
6
+ 它们的后台:查询数据、修改资料,或者执行系统已经开放的其他操作。实际能做什么仍由当前业务
7
+ 账号权限和审批规则决定,执行过程也会记录在 BailingHub 中。
8
+
9
+ 具体能做什么取决于业务系统开放了哪些能力,例如:
10
+
11
+ - 查询订单、客户、商品或员工资料;
12
+ - 修改允许编辑的字段或业务状态;
13
+ - 完成其他已经授权的后台操作;
14
+ - 把结果返回到本地对话,同时在 BailingHub 中保留对应的工具步骤。
15
+
16
+ 思考、工具选择与编排留在本地 DSH;BailingHub 负责向本地智能体提供已授权的业务上下文、
17
+ 可用能力、审批状态、调用恢复与审计记录。
7
18
 
8
19
  这是独立社区集成,不是 DeepSeek 官方开发、认证、合作、背书或推荐的插件。
9
20
 
10
- ## 使用者得到什么
21
+ > **当前稳定版本线:**`dsh-bailinghub@0.3.0` 使用下文说明的原生 Agent Client 流程。
22
+ > 公开 `0.1.1` 仅作为明确的静态 MCP 兼容路径继续保留。
11
23
 
12
- 安装后,DeepSeek Harness 会发现三个原生工具:
24
+ 希望用最短路径完成首次使用,可以直接阅读[三分钟开始使用](GETTING_STARTED.zh-CN.md)。
13
25
 
14
- | Harness 工具 | 能力 |
15
- | --- | --- |
16
- | `mcp__bailinghub__submit_governed_job` | 使用稳定请求 ID 提交一项业务任务 |
17
- | `mcp__bailinghub__get_governed_job` | 查询同一个任务的当前状态和公开结果 |
18
- | `mcp__bailinghub__wait_for_governed_job` | 有界等待同一个任务,不重复提交 |
26
+ ## 0.3 Agent Client 的关系
27
+
28
+ ```text
29
+ DeepSeek Harness 本地智能体
30
+ -> dsh-bailinghub 原生 Cordis 适配器
31
+ -> bailinghub-mcp-server/sdk
32
+ -> BailingHub Agent Auth + Agent API
33
+ -> 部署者选择的业务接入与最终业务授权
34
+ ```
35
+
36
+ 各层职责保持独立:
37
+
38
+ - **BailingHub Core** 负责 Agent Auth、可信业务身份、运行时上下文、知识库与记忆投影、
39
+ 能力治理、审批、调用状态和审计记录。
40
+ - **`bailinghub-mcp-server/sdk`** 负责浏览器登录、PKCE、凭据存储与刷新,以及按
41
+ Hub/client/workspace 选择连接和映射 HTTP DTO。
42
+ - **`dsh-bailinghub`** 只负责 DSH 会话、提示词、命令和动态工具生命周期,不保存凭据,
43
+ 也不直接调用业务 API。
19
44
 
20
- BailingHub 仍位于模型与业务系统之间。中枢地址、Client Token 和 route 都由运营者预先
21
- 配置,不是模型参数;模型不能借工具参数切换 route,也不能提交管理员凭据、执行器凭据、
22
- 审批结论或业务系统密钥。
45
+ Agent Client 不是 BailingHub 现有的“执行器”。执行器接收中枢任务并处理必须靠近某台机器
46
+ 完成的工作;Agent Client 则把交互式思考与编排循环放在用户本地 DSH 智能体中。
23
47
 
24
- ## 安装
48
+ ## 安装前准备
49
+
50
+ 部署者和业务接入开发者需要先在自己的 BailingHub 中准备这些公开标识:
51
+
52
+ 1. 一套可访问的 HTTPS BailingHub,并部署匹配版本的 Agent Auth 与 Agent API;
53
+ 2. 一个公开 Agent Client 应用标识 `clientAppId`;
54
+ 3. 至少一个允许授权的 workspace;在 Agent Client v1 中,workspace id 就是
55
+ BailingHub route id;
56
+ 4. 在中枢 Client App 上配置一个稳定且不绑定具体账号、租户的业务授权入口,并在该 route
57
+ 后方接通受治理的 ACC/Tool Provider 能力。登录、切换账号和选择租户都由业务授权页完成。
58
+
59
+ 最终用户**不需要**在插件中填写业务 API 地址、业务账号密码、Tool Provider 签名密钥、
60
+ BailingHub Client Token 或模型提供方 Key。
61
+
62
+ ## 安装 0.3 版本线
25
63
 
26
64
  前置条件:
27
65
 
28
66
  - Node.js `22.19.0+` 或 `24+`;
29
- - 已安装 `pnpm` 与 `@deepseek-ai/dsh@0.1.0-rc.7`;
30
- - 一套可访问的 [BailingHub](https://github.com/bailinghub/bailinghub#快速上手);
31
- - 一个只允许目标 route 的 BailingHub Client Token。
67
+ - `pnpm` 与兼容矩阵中列出的 DeepSeek Harness 版本;
68
+ - 已完成上面的 BailingHub 接入准备。
69
+
70
+ 将精确稳定版本安装到 DSH Web Profile:
32
71
 
33
72
  ```bash
34
- npm install --global pnpm @deepseek-ai/dsh@0.1.0-rc.7
35
- dsh plugin --profile web add dsh-bailinghub@0.1.1
73
+ npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
74
+ dsh plugin --profile web add dsh-bailinghub@0.3.0
36
75
  ```
37
76
 
38
- 在启动 Harness 的终端或进程环境中配置:
77
+ `dsh-bailinghub@0.3.0` 会自动安装精确兼容的 `bailinghub-mcp-server@0.3.0` 依赖。
78
+ DSH 用户不应该再自行猜测或单独安装某个 SDK 版本。
79
+
80
+ ## 配置一个中枢连接
81
+
82
+ 原生插件只有四个宿主配置字段:
83
+
84
+ | 插件字段 | 环境变量 | 含义 | 是否 Secret |
85
+ | --- | --- | --- | --- |
86
+ | `hubUrl` | `BAILINGHUB_HUB_URL` | 开发者自己部署的 BailingHub 公共 HTTPS 地址 | 否 |
87
+ | `clientAppId` | `BAILINGHUB_CLIENT_APP_ID` | 在该中枢注册的公共 Agent Client 应用标识 | 否 |
88
+ | `workspace` | `BAILINGHUB_WORKSPACE` | 初始已授权 workspace/route id | 否 |
89
+ | `connectionName` | `BAILINGHUB_CONNECTION_NAME` | 用户选择的本机连接名称 | 否 |
90
+
91
+ 使用中性占位值的示例:
39
92
 
40
93
  ```bash
41
- export BAILINGHUB_BASE_URL='https://hub.example.com'
42
- export BAILINGHUB_CLIENT_TOKEN='替换为仅允许指定-route-的-client-token'
43
- export BAILINGHUB_ROUTE='order_assistant'
94
+ export BAILINGHUB_HUB_URL='https://hub.example.com'
95
+ export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
96
+ export BAILINGHUB_WORKSPACE='order_assistant'
97
+ export BAILINGHUB_CONNECTION_NAME='default'
44
98
  ```
45
99
 
46
- 检查最终配置,然后启动本机 Web 界面:
100
+ 也可以通过 DSH 的插件设置界面填写同样四个字段。不要在 Cordis Patch 中增加 Token、授权
101
+ 页面地址、业务域名或任何凭据。中枢会根据 Client App 找到唯一业务授权入口。
102
+ `connectionName` 只是用户控制的本机连接选择器,不是账号、租户或身份声明。
103
+
104
+ 启动前检查最终合成配置:
47
105
 
48
106
  ```bash
49
107
  dsh --profile web --dump-config
50
108
  dsh web
51
109
  ```
52
110
 
53
- 接下来可以直接要求 Harness 通过 BailingHub 提交任务、保存返回的 `job_id`,并等待或
54
- 查询同一个任务。
111
+ ## 浏览器授权与使用
55
112
 
56
- 第一次尝试时,请选择当前 route 已支持的任务,并明确要求:使用稳定 `request_id` 只提交
57
- 一次,保存返回的 `job_id`;有界等待超时后,只查询同一个任务,不要重新提交。
113
+ 在 DSH 中依次执行:
58
114
 
59
- ## 正确任务流程
115
+ ```text
116
+ /bailinghub login
117
+ /bailinghub doctor
118
+ /bailinghub status
119
+ /bailinghub workspaces
120
+ ```
60
121
 
61
- 1. 为一项业务请求生成一个稳定的 `request_id`;
62
- 2. 只调用一次 `mcp__bailinghub__submit_governed_job`;
63
- 3. 保存返回的 `job_id`;
64
- 4. 短时调用 `wait_for_governed_job`,或者稍后调用 `get_governed_job`;
65
- 5. 等待超时不等于任务失败,不能因此重新提交一份替代任务。
122
+ `login` 会在系统浏览器打开中枢管理员配置的唯一业务授权入口。业务授权页负责登录、切换账号、
123
+ 选择租户,并确认最终业务身份和申请的 workspace,然后返回受 `state` 与 PKCE S256 保护的
124
+ 随机回环回调。Access Token 与 Refresh Token 只进入 SDK 所有的安全存储,不会写入插件配置,
125
+ 也不会由命令输出。
66
126
 
67
- ## 身份与权限边界
127
+ 常用命令:
68
128
 
69
- 使用本机 Harness 界面,省掉的是“必须打开业务后台聊天入口”这一步;它不代表 Harness
70
- 登录态或本机用户自动成为可信业务身份。当前 `0.1.x` Bundle 有意不接受模型传入行动主体。route 或
71
- 下游业务系统仍需解析可信主体并执行最终授权;如果目标动作必须具备业务身份,而当前接入
72
- 路径无法建立该身份,该动作就应保持不可用或被拒绝。
129
+ | 命令 | 用途 |
130
+ | --- | --- |
131
+ | `/bailinghub doctor` | 在不输出凭据的前提下检查宿主 API、公开配置、SDK、授权状态和 workspace 连通性 |
132
+ | `/bailinghub connections list` | 查看本机公开连接元数据与授权状态,不输出 Token |
133
+ | `/bailinghub connections add <名称> <中枢地址> <clientAppId> <workspace>` | 创建并选择另一个本机连接实例;公开绑定可以与已有实例相同 |
134
+ | `/bailinghub connections use <名称或连接键>` | 只为之后新建的会话选择一个已登记连接 |
135
+ | `/bailinghub connections remove <名称或连接键>` | 先远程撤销 Agent Session,再删除本机凭据和公开元数据 |
136
+ | `/bailinghub login` | 在浏览器授权当前 Hub/client/workspace |
137
+ | `/bailinghub status` | 查看当前连接状态,但不输出凭据 |
138
+ | `/bailinghub workspaces` | 查看当前业务授权允许使用的 workspace |
139
+ | `/bailinghub use <workspace>` | 为新会话切换到另一个已授权 workspace |
140
+ | `/bailinghub sync` | 重试同步待处理的可见回复,不重复业务工具调用 |
141
+ | `/bailinghub logout` | 撤销并删除当前 Agent Session |
142
+
143
+ 插件四字段是启动连接。其他连接可用 `connections add` 登记;BailingHub 控制台“智能体客户端”
144
+ 页面也能生成同样的不含秘密命令。重启后,适配器会在第一个新 Agent 会话或用户命令前读取 SDK
145
+ registry,并采用其中当前连接的公开元数据;registry 缺失或不可用时安全回退到这四个启动字段。
146
+ 连接名含空格时需要加引号。执行 `connections use` 后,如果该绑定尚未授权,再执行
147
+ `/bailinghub login`。
148
+
149
+ 连接选择只能由用户斜杠命令发起,不会作为模型工具暴露。切换只影响之后创建的 Agent 会话,已有
150
+ 会话继续固定在原连接与 workspace。`/bailinghub use <workspace>` 是另一件事:只有当前 Agent
151
+ Session 已经允许目标 workspace 时才成功。
152
+
153
+ 删除当前连接后,适配器会读取 SDK registry,把剩余的当前连接(包括没有别名的连接)设为新会话
154
+ 默认值;删除最后一个连接后则明确进入未配置状态。删除后的 registry 刷新失败不会把已经成功的
155
+ 删除改写成错误;如果删除的是非当前连接,刷新不可用时也会保留仍然有效的默认连接。
156
+
157
+ 对于同一个 `Hub + clientAppId + workspace` 公开绑定,最终身份由业务授权页及其可信
158
+ `on_behalf_of` 结果决定。如果另一个本机连接名已经授权同一身份,SDK 会用本次连接覆盖旧连接,
159
+ 并撤销旧 Agent Session;不同可信身份则继续作为相互独立的连接。如果从一个已经属于其他身份的
160
+ `connectionName` 发起登录,SDK 会保留原连接名及其 Session,为新身份分配一个不冲突的本机名称
161
+ (例如 `default-2`),并把新连接设为后续会话的当前选择。用户可以用 `connections list` 查看
162
+ 两者,再用 `connections use <名称或连接键>` 显式切换。如果登录结果返回
163
+ `cleanupRequired: true`,说明新连接仍然授权成功,但一个或多个同绑定旧连接还需要显式清理;
164
+ 如果身份检查被推迟,此时还不能断言它们是同一身份。不要重复授权;先查看 `connections list`,
165
+ 再对提示的旧连接执行
166
+ `/bailinghub connections remove <名称或连接键>`。
167
+
168
+ 首次验收时,新建一个 DSH 会话,先做一次只读查询,再做一次允许的修改。确认 BailingHub
169
+ 后台能看到同一个会话、run、可见最终回复和工具调用轨迹。需要审批的能力必须在审批后恢复
170
+ 原 invocation,不能生成替代业务调用。
171
+
172
+ 本版本在 DSH Code Mode 下会明确降级,因为当前 Code Mode 无法安全呈现本轮动态 Schema。
173
+ 需要执行受治理业务操作时应使用 Native Tool Mode。
174
+
175
+ ## 安全与隐私边界
176
+
177
+ - 模型不能通过工具参数选择 Hub URL、workspace、本机连接、业务身份、凭据、审批结论或能力版本;
178
+ - SDK 在 macOS 使用 Keychain;Windows 凭据文件保存在 LocalAppData 并由 CurrentUser DPAPI
179
+ 保护,Windows PowerShell 或 DPAPI 不可用时失败关闭,不会降级为明文;Linux 与其他 POSIX
180
+ 系统必须显式启用安全文件回退;
181
+ - BailingHub 对每次治理调用重新校验身份、scope、审批、幂等与调用状态,业务系统仍执行
182
+ 最终权限判断;
183
+ - 适配器会发送 Agent Client 契约所需的可见用户输入、受治理工具参数/结果和可见最终回复,
184
+ 但不会上传隐藏思考片段;
185
+ - 本插件只治理它注册的 BailingHub 工具,不会拦截 DSH 其他工具或模型提供方流量。
186
+
187
+ 生产使用前请阅读[安全策略](../SECURITY.md)、[隐私说明](../PRIVACY.md)、
188
+ [Agent Client 契约](AGENT_CLIENT_CONTRACT.md)和[兼容范围](COMPATIBILITY.md)。
189
+
190
+ ## 公开 0.1.x 静态兼容模式
191
+
192
+ 公开 `dsh-bailinghub@0.1.1` 仍是不可变的纯配置 Bundle。它通过 DSH 内置 MCP Client 启动
193
+ `bailinghub-mcp-server@0.1.1`,把运营者提供的一个 Client Token 固定绑定到一个 route,
194
+ 并由 BailingHub 完成编排。
73
195
 
74
- 本 Bundle 只治理通过这三个 BailingHub 工具提交的任务,不会自动拦截 Harness 中安装的
75
- 其他工具。
196
+ ```bash
197
+ dsh plugin --profile web add dsh-bailinghub@0.1.1
76
198
 
77
- ## 供应链说明
199
+ export BAILINGHUB_BASE_URL='https://hub.example.com'
200
+ export BAILINGHUB_CLIENT_TOKEN='replace-with-a-route-scoped-client-token'
201
+ export BAILINGHUB_ROUTE='order_assistant'
202
+ ```
203
+
204
+ 它只暴露三个固定工具:
78
205
 
79
- 这个 Bundle 没有自定义运行时代码、生产依赖和安装脚本。Harness 启动时,会由内置 MCP
80
- Client 在 Agent 沙箱之外执行固定命令
81
- `npx -y --package=bailinghub-mcp-server@0.1.1 bailinghub-mcp-server`。首次启动可能需要
82
- 访问 npm;敏感环境应审查并固定版本,生产镜像可提前缓存该精确版本。
206
+ ```text
207
+ mcp__bailinghub__submit_governed_job
208
+ mcp__bailinghub__get_governed_job
209
+ mcp__bailinghub__wait_for_governed_job
210
+ ```
83
211
 
84
- MCP Server 默认拒绝非回环明文 HTTP。只有在受控私网中已经由其他可信边界终止 TLS 时,
85
- 才可设置 `BAILINGHUB_ALLOW_INSECURE_HTTP=true`。
212
+ 0.3 Agent Client 不会自动读取或迁移 0.1 Client Token。测试升级或回滚时必须显式固定版本,
213
+ 并遵循 [0.1 到 0.3 的迁移边界](MIGRATION_VNEXT.md)。
86
214
 
87
215
  ## 兼容范围与反馈
88
216
 
89
- 首版验证范围为 DeepSeek Harness `0.1.0-rc.7`、`bailinghub-mcp-server@0.1.1` 与
90
- BailingHub Client API v1。Harness 当前仍是 Developer Preview,升级 Harness 后应重新
91
- 执行兼容性 Smoke。
217
+ 0.3.0 只对 [COMPATIBILITY.md](COMPATIBILITY.md) 中列出的版本完成了验证。DeepSeek
218
+ Harness 仍是 Developer Preview,每次 Harness 升级都必须重新执行 Native Lifecycle Smoke。
92
219
 
93
220
  问题请提交到 [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues)。
94
221
  请勿附带 Token、私有部署地址、个人信息或生产业务数据。
package/lib/index.js ADDED
@@ -0,0 +1,53 @@
1
+ import Schema from '@deepseek-ai/schemastery'
2
+
3
+ import { BailingHubAgentClientRuntime } from './runtime.js'
4
+ import { createTransportProvider } from './transport.js'
5
+
6
+ export const name = 'dsh-bailinghub'
7
+ export const inject = ['systemPrompt', 'tools', 'commands']
8
+
9
+ export const Config = Schema.object({
10
+ hubUrl: Schema.string()
11
+ .default('')
12
+ .description('BailingHub public HTTPS URL. Loopback HTTP is allowed for local development only.'),
13
+ clientAppId: Schema.string()
14
+ .default('')
15
+ .description('Public Agent Client application id issued by BailingHub.'),
16
+ workspace: Schema.string()
17
+ .default('')
18
+ .description('Initial BailingHub workspace/route. The Hub resolves business endpoints and authorization.'),
19
+ connectionName: Schema.string()
20
+ .default('default')
21
+ .description('Local SDK connection alias. Credentials remain in SDK-owned secure storage.'),
22
+ })
23
+
24
+ export function createAgentClientPlugin(options = {}) {
25
+ return {
26
+ name,
27
+ inject,
28
+ Config,
29
+ apply(ctx, config) {
30
+ const getTransport = createTransportProvider(config, options)
31
+ const runtime = new BailingHubAgentClientRuntime(
32
+ ctx,
33
+ config,
34
+ getTransport,
35
+ options.recovery,
36
+ ).install()
37
+ ctx.provide('bailingHubAgentClient', runtime)
38
+ },
39
+ }
40
+ }
41
+
42
+ export function apply(ctx, config) {
43
+ return createAgentClientPlugin().apply(ctx, config)
44
+ }
45
+
46
+ export { BailingHubAgentClientRuntime } from './runtime.js'
47
+ export {
48
+ DEFAULT_SDK_MODULE,
49
+ REQUIRED_METHODS,
50
+ assertTransport,
51
+ createLazySdkTransport,
52
+ createTransportProvider,
53
+ } from './transport.js'