dsh-bailinghub 0.2.0 → 0.3.0

package/docs/GETTING_STARTED.zh-CN.md

@@ -0,0 +1,83 @@
+# 三分钟开始使用
+
+这份指南面向业务系统已经接入 BailingHub 的最终用户。如果还没有完成业务接入，需要先由
+BailingHub 管理员和业务开发者准备中枢应用、授权页面与业务能力，再安装本插件。
+
+## 先向管理员获取什么
+
+只需要向管理员获取四项公开连接信息：
+
+```text
+Hub URL
+Client App ID
+Workspace
+Connection Name
+```
+
+它们用于定位 BailingHub 应用和初始业务空间，不是凭据。不要让管理员把 Client Token、Tool
+Provider 密钥、业务密码、模型 API Key、授权码、浏览器 Cookie、业务地址或租户专属登录地址
+发给你。
+
+## 第一步：安装插件
+
+把精确公开版本安装到 DSH Web Profile：
+
+```bash
+dsh plugin --profile web add dsh-bailinghub@0.3.0
+```
+
+插件会自动安装匹配版本的 BailingHub SDK，不需要再手工拼装依赖。
+
+## 第二步：填写四项连接信息
+
+可以在 DSH 插件设置页面填写，也可以使用对应环境变量：
+
+```bash
+export BAILINGHUB_HUB_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
+export BAILINGHUB_WORKSPACE='employee_assistant'
+export BAILINGHUB_CONNECTION_NAME='default'
+```
+
+上面都是占位值，请替换成自己中枢管理员提供的公开信息。不要把凭据写进 Cordis Patch，也不要
+把凭据粘贴到聊天消息里。
+
+## 第三步：在浏览器完成授权
+
+启动 DSH 后依次执行：
+
+```text
+/bailinghub login
+/bailinghub status
+/bailinghub workspaces
+```
+
+`login` 会打开 Client App 配置的唯一业务授权入口。在该页面登录或切换账号，并在业务系统要求
+时选择租户；点击同意前，确认页面显示的最终业务身份和准备使用的 workspace。整个过程沿用业务
+系统自己的登录流程，不会把业务密码或业务地址交给插件。
+
+`Connection Name` 只是本机选择器。同一可信业务身份再次授权同一 Hub/client/workspace 绑定时，
+SDK 会覆盖旧的本机连接；不同可信身份继续相互独立。如果当前名称已经属于旧身份，SDK 会保留
+它，并给新身份分配一个可用名称（例如 `default-2`），同时把新名称设为当前连接。使用
+`/bailinghub connections list` 可以查看两者，再用
+`/bailinghub connections use <名称或连接键>` 显式切换。如果登录提示需要清理，新连接其实已经
+授权成功，但某个旧连接可能仍需检查或删除：不要再次授权，应先列出连接，再删除提示的旧连接。
+
+## 第四步：尝试一条安全的业务请求
+
+新建一个会话，先尝试业务系统已经开放的一条只读请求，例如：
+
+```text
+查询演示员工 EMP-001，并汇总我能看到的资料。
+```
+
+随后可以在专用开发空间尝试一次可回滚、当前账号允许的修改。实际能问什么，取决于业务系统
+开放了哪些能力。需要审批的操作必须继续走原有审批，没有权限的操作仍然不可用。
+
+## 第五步：在 BailingHub 查看结果
+
+BailingHub 控制台应当能看到同一条可见会话、Agent Run、业务工具调用、审批状态与最终结果。
+只有插件安装成功，还不能证明业务操作已经真正完成。
+
+如果初始化失败，请在 GitHub Issue 中提供 DSH 版本、插件版本、操作系统、失败命令和脱敏错误。
+不要附带 Token、私有地址、个人信息、授权码或生产业务载荷。

package/docs/MIGRATION_VNEXT.md

@@ -1,7 +1,7 @@
-# Migration Boundary: Public 0.1.x to Native 0.2
+# Migration Boundary: Public 0.1.x to the Native Agent Client
 
 There is no automatic credential, configuration, tool, or orchestration migration from public
-`dsh-bailinghub@0.1.x` to the native 0.2 Agent Client.
+`dsh-bailinghub@0.1.x` to the native 0.3 Agent Client.
 
 ## What remains unchanged
 
@@ -20,9 +20,9 @@ the orchestration. Local DSH does not obtain a trusted Agent Session or dynamic
 The retained [legacy patch](../cordis.patch.yml) documents that historical meaning. It is not
 selected by the current native package metadata, and its presence is not a dual-mode switch.
 
-## What changes in 0.2
+## What changed in 0.2
 
-| Concern | Public 0.1.1 | Native 0.2 |
+| Concern | Public 0.1.1 | Native 0.2 and later |
 | --- | --- | --- |
 | DSH integration | in-box MCP client | native Cordis host adapter |
 | Core unit | governed job | conversation, run, and governed invocation |
@@ -32,20 +32,35 @@ selected by the current native package metadata, and its presence is not a dual-
 | Business identity | not established by DSH | Agent Session approved through the business boundary |
 | Hub audit | job records | conversation, run, completion, and invocation trajectory |
 
+## What 0.3 adds
+
+Version 0.3 keeps the same native boundary and adds stable named multi-connection lifecycle,
+same-binding trusted-identity reconciliation, and Windows CurrentUser DPAPI credential storage.
+It does not reinterpret or migrate the public 0.1.x Client Token path.
+
 The new plugin config is limited to `hubUrl`, `clientAppId`, `workspace`, and `connectionName`.
 The old `BAILINGHUB_CLIENT_TOKEN` is not read, copied, exchanged, or converted into an Agent
 Session. Browser authorization creates a new independently revocable credential in SDK-owned
-secure storage.
+secure storage. The plugin does not accept a business URL: the Hub Client App resolves to one
+stable, account- and tenant-neutral business authorization entry, where the user can log in,
+switch account, and select a tenant.
 
 ## Safe evaluation before migration
 
-Do not replace a working production profile merely to evaluate 0.2.0. Use a separate DSH home or
-another isolated Web profile and verify that the CLI really honors that location.
+Do not replace a working production profile merely to evaluate 0.3.0. Use a separate DSH home or
+another isolated Web profile and verify that the CLI really honors that location. Stable public
+`0.3.0` creates a separate credential for each name registered through
+`connections add` while authorization is pending. After authorization, the SDK replaces an older
+same-binding connection when its trusted `on_behalf_of` is the same; different trusted identities
+remain independent. A different identity returned from a same-alias login keeps the original
+alias and Session and receives a non-conflicting alias that becomes current. Use the exact matching
+SDK installed by the DSH package when evaluating that behavior.
 
 1. Keep the existing `0.1.1` profile and its legacy environment unchanged.
-2. Install the exact released 0.2 package into an isolated profile.
+2. Install the exact released 0.3 package into an isolated profile.
 3. Configure only the four public native fields using neutral values for dry composition.
-4. Run `/bailinghub login` and approve a dedicated non-production business identity/workspace.
+4. Run `/bailinghub login` and approve a dedicated non-production client app/workspace whose
+   credential can be revoked without affecting a maintainer's existing profile.
 5. Verify status, workspace discovery, one read, one permitted mutation, approval/resume, and Hub
    trajectory.
 6. Separately re-run the `0.1.1` submit and same-job follow-up against the newly released Core.
@@ -53,18 +68,18 @@ another isolated Web profile and verify that the CLI really honors that location
 Passing the native path does not prove legacy compatibility, and passing the legacy path does not
 prove the native Agent Client.
 
-## Moving a profile to 0.2
+## Moving a profile to 0.3
 
 Only after the isolated acceptance passes:
 
 1. Record the exact old plugin, DSH, MCP, and Core versions without copying credentials into the
    migration record.
 2. Finish or cancel outstanding legacy jobs. A wait timeout is not a terminal failure.
-3. Install the exact accepted 0.2 plugin version. Do not use an unpinned dist-tag.
+3. Install the exact accepted 0.3 plugin version. Do not use an unpinned dist-tag.
 4. Replace the legacy plugin configuration with the four native fields. Remove the old Client
    Token from that process environment after confirming no remaining 0.1 integration uses it.
-5. Start DSH, run `/bailinghub login`, inspect the business authorization page, and authorize the
-   intended workspace.
+5. Start DSH, run `/bailinghub login`, use the business page to log in or switch account and select
+   a tenant if required, then authorize the intended workspace.
 6. Run `/bailinghub status`, open a new conversation, and repeat the accepted read/mutation checks.
 7. Confirm BailingHub receives visible conversation and invocation audit without hidden reasoning.
 
@@ -76,6 +91,12 @@ key to this plugin.
 
 Rollback is explicit; it does not convert the Agent Session back into a Client Token.
 
+Before downgrading a 0.3 profile to 0.2, first use the installed 0.3 plugin to finish active runs
+and remove every named instance through `/bailinghub connections remove <name>`. The SDK returns
+the registry to schema v1 after the last such instance is removed. Stable `0.2.0` fails closed on
+schema v2; do not manually delete the registry, Keychain entry, DPAPI ciphertext, or secure file
+credentials as a downgrade shortcut.
+
 1. Finish active native runs and use `/bailinghub sync` for any known pending completion.
 2. Run `/bailinghub logout` if the new Agent Session should be revoked.
 3. Reinstall exact `dsh-bailinghub@0.1.1` in the target profile.
@@ -90,17 +111,18 @@ reuse, move, or republish an npm version or Git tag as a rollback mechanism.
 
 ## Release gates
 
-Before any public 0.2 release:
+Before any public 0.3 release:
 
 1. The matching BailingHub Core Agent Auth/Agent API contracts are released.
 2. The exact `bailinghub-mcp-server/sdk` version is publicly installable and has passed DTO,
    credential, invoke/resume, and completion tests.
-3. Installing only `dsh-bailinghub` into a clean DSH `0.1.0-rc.7` profile installs and resolves that
+3. Installing only `dsh-bailinghub` into a clean DSH `0.1.1-rc.2` profile installs and resolves that
    exact SDK dependency automatically.
 4. Browser login, session isolation, dynamic tool replacement, approval recovery, visible
-   completion, and Hub trajectory pass from the packaged artifact.
+   completion, same-identity replacement, different-identity isolation, and Hub trajectory pass
+   from the packaged artifact.
 5. Public `0.1.1` still works against the new Core through the unchanged Client API.
 6. The maintainer explicitly selects the public version and migration story.
 
-Do not tag or publish a future 0.2.x version until all gates pass, and do not describe release
+Do not tag or publish a future 0.3.x version until all gates pass, and do not describe release
 validation as public adoption.

package/docs/PROJECT_BOUNDARIES.md

@@ -21,9 +21,10 @@ BailingHub tool surface.
 DeepSeek and DeepSeek Harness are names of their respective owners. This is an independent
 community integration, not an official DeepSeek plugin or partnership.
 
-## Public native 0.2.0
+## Public native line (0.2.0 onward)
 
-Version 0.2.0 adds a separate dependency path without reinterpreting the public static MCP path:
+Version 0.2.0 introduced this dependency path. Version 0.3.0 keeps it separate from the public
+static MCP path and adds the stable multi-connection lifecycle:
 
 ```text
 DeepSeek Harness local Agent

package/docs/README.zh-CN.md

@@ -2,16 +2,28 @@
 
 [English](../README.md) | 简体中文
 
-让本地 DeepSeek Harness 智能体发现并调用由自托管 BailingHub 治理的业务能力。思考、工具
-选择与编排留在本地 DSH；可信身份、运行时上下文、候选能力裁剪、审批、调用恢复与审计仍由
-BailingHub 负责。
+把商城、SaaS 或其他业务系统接到 BailingHub 后，本地 DeepSeek Harness 智能体就能直接操作
+它们的后台：查询数据、修改资料，或者执行系统已经开放的其他操作。实际能做什么仍由当前业务
+账号权限和审批规则决定，执行过程也会记录在 BailingHub 中。
+
+具体能做什么取决于业务系统开放了哪些能力，例如：
+
+- 查询订单、客户、商品或员工资料；
+- 修改允许编辑的字段或业务状态；
+- 完成其他已经授权的后台操作；
+- 把结果返回到本地对话，同时在 BailingHub 中保留对应的工具步骤。
+
+思考、工具选择与编排留在本地 DSH；BailingHub 负责向本地智能体提供已授权的业务上下文、
+可用能力、审批状态、调用恢复与审计记录。
 
 这是独立社区集成，不是 DeepSeek 官方开发、认证、合作、背书或推荐的插件。
 
-> **当前稳定版本线：**`dsh-bailinghub@0.2.0` 使用下文说明的原生 Agent Client 流程。
+> **当前稳定版本线：**`dsh-bailinghub@0.3.0` 使用下文说明的原生 Agent Client 流程。
 > 公开 `0.1.1` 仅作为明确的静态 MCP 兼容路径继续保留。
 
-## 0.2 Agent Client 的关系
+希望用最短路径完成首次使用，可以直接阅读[三分钟开始使用](GETTING_STARTED.zh-CN.md)。
+
+## 0.3 Agent Client 的关系
 
 ```text
 DeepSeek Harness 本地智能体
@@ -26,7 +38,7 @@ DeepSeek Harness 本地智能体
 - **BailingHub Core** 负责 Agent Auth、可信业务身份、运行时上下文、知识库与记忆投影、
   能力治理、审批、调用状态和审计记录。
 - **`bailinghub-mcp-server/sdk`** 负责浏览器登录、PKCE、凭据存储与刷新，以及按
-  Hub/client/workspace 隔离连接和映射 HTTP DTO。
+  Hub/client/workspace 选择连接和映射 HTTP DTO。
 - **`dsh-bailinghub`** 只负责 DSH 会话、提示词、命令和动态工具生命周期，不保存凭据，
   也不直接调用业务 API。
 
@@ -41,27 +53,28 @@ Agent Client 不是 BailingHub 现有的“执行器”。执行器接收中枢
 2. 一个公开 Agent Client 应用标识 `clientAppId`；
 3. 至少一个允许授权的 workspace；在 Agent Client v1 中，workspace id 就是
    BailingHub route id；
-4. 该 route 后方已经接通业务授权页面，以及受治理的 ACC/Tool Provider 能力。
+4. 在中枢 Client App 上配置一个稳定且不绑定具体账号、租户的业务授权入口，并在该 route
+   后方接通受治理的 ACC/Tool Provider 能力。登录、切换账号和选择租户都由业务授权页完成。
 
 最终用户**不需要**在插件中填写业务 API 地址、业务账号密码、Tool Provider 签名密钥、
 BailingHub Client Token 或模型提供方 Key。
 
-## 安装 0.2 版本线
+## 安装 0.3 版本线
 
 前置条件：
 
 - Node.js `22.19.0+` 或 `24+`；
-- `pnpm` 与 DeepSeek Harness `0.1.0-rc.7`；
+- `pnpm` 与兼容矩阵中列出的 DeepSeek Harness 版本；
 - 已完成上面的 BailingHub 接入准备。
 
 将精确稳定版本安装到 DSH Web Profile：
 
 ```bash
-npm install --global pnpm @deepseek-ai/dsh@0.1.0-rc.7
-dsh plugin --profile web add dsh-bailinghub@0.2.0
+npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile web add dsh-bailinghub@0.3.0
 ```
 
-`dsh-bailinghub@0.2.0` 会自动安装精确兼容的 `bailinghub-mcp-server@0.2.0` 依赖。
+`dsh-bailinghub@0.3.0` 会自动安装精确兼容的 `bailinghub-mcp-server@0.3.0` 依赖。
 DSH 用户不应该再自行猜测或单独安装某个 SDK 版本。
 
 ## 配置一个中枢连接
@@ -73,7 +86,7 @@ DSH 用户不应该再自行猜测或单独安装某个 SDK 版本。
 | `hubUrl` | `BAILINGHUB_HUB_URL` | 开发者自己部署的 BailingHub 公共 HTTPS 地址 | 否 |
 | `clientAppId` | `BAILINGHUB_CLIENT_APP_ID` | 在该中枢注册的公共 Agent Client 应用标识 | 否 |
 | `workspace` | `BAILINGHUB_WORKSPACE` | 初始已授权 workspace/route id | 否 |
-| `connectionName` | `BAILINGHUB_CONNECTION_NAME` | 当前 SDK 隔离连接的本地别名 | 否 |
+| `connectionName` | `BAILINGHUB_CONNECTION_NAME` | 用户选择的本机连接名称 | 否 |
 
 使用中性占位值的示例：
 
@@ -85,7 +98,8 @@ export BAILINGHUB_CONNECTION_NAME='default'
 ```
 
 也可以通过 DSH 的插件设置界面填写同样四个字段。不要在 Cordis Patch 中增加 Token、授权
-页面地址、业务域名或任何凭据。
+页面地址、业务域名或任何凭据。中枢会根据 Client App 找到唯一业务授权入口。
+`connectionName` 只是用户控制的本机连接选择器，不是账号、租户或身份声明。
 
 启动前检查最终合成配置：
 
@@ -100,18 +114,25 @@ dsh web
 
 ```text
 /bailinghub login
+/bailinghub doctor
 /bailinghub status
 /bailinghub workspaces
 ```
 
-`login` 会打开系统浏览器。业务侧授权页面负责确认当前已登录的业务身份和申请的
-workspace，然后返回受 `state` 与 PKCE S256 保护的随机回环回调。Access Token 与 Refresh
-Token 只进入 SDK 所有的安全存储，不会写入插件配置，也不会由命令输出。
+`login` 会在系统浏览器打开中枢管理员配置的唯一业务授权入口。业务授权页负责登录、切换账号、
+选择租户，并确认最终业务身份和申请的 workspace，然后返回受 `state` 与 PKCE S256 保护的
+随机回环回调。Access Token 与 Refresh Token 只进入 SDK 所有的安全存储，不会写入插件配置，
+也不会由命令输出。
 
 常用命令：
 
 | 命令 | 用途 |
 | --- | --- |
+| `/bailinghub doctor` | 在不输出凭据的前提下检查宿主 API、公开配置、SDK、授权状态和 workspace 连通性 |
+| `/bailinghub connections list` | 查看本机公开连接元数据与授权状态，不输出 Token |
+| `/bailinghub connections add <名称> <中枢地址> <clientAppId> <workspace>` | 创建并选择另一个本机连接实例；公开绑定可以与已有实例相同 |
+| `/bailinghub connections use <名称或连接键>` | 只为之后新建的会话选择一个已登记连接 |
+| `/bailinghub connections remove <名称或连接键>` | 先远程撤销 Agent Session，再删除本机凭据和公开元数据 |
 | `/bailinghub login` | 在浏览器授权当前 Hub/client/workspace |
 | `/bailinghub status` | 查看当前连接状态，但不输出凭据 |
 | `/bailinghub workspaces` | 查看当前业务授权允许使用的 workspace |
@@ -119,10 +140,30 @@ Token 只进入 SDK 所有的安全存储，不会写入插件配置，也不会
 | `/bailinghub sync` | 重试同步待处理的可见回复，不重复业务工具调用 |
 | `/bailinghub logout` | 撤销并删除当前 Agent Session |
 
-标准 v1 登录只申请当前配置的 workspace。`use` 只有在当前 Agent Session 明确包含目标
-workspace 时才会成功，不能借此任意切换中枢 route。当前命令始终使用这个插件实例配置的四个
-字段，不接受连接别名选择器。连接另一套 Hub 或 route 时，应使用第二个 DSH Profile/插件实例，
-或修改四字段并重新加载当前 Profile；设置新的 `connectionName` 后再完成浏览器授权。
+插件四字段是启动连接。其他连接可用 `connections add` 登记；BailingHub 控制台“智能体客户端”
+页面也能生成同样的不含秘密命令。重启后，适配器会在第一个新 Agent 会话或用户命令前读取 SDK
+registry，并采用其中当前连接的公开元数据；registry 缺失或不可用时安全回退到这四个启动字段。
+连接名含空格时需要加引号。执行 `connections use` 后，如果该绑定尚未授权，再执行
+`/bailinghub login`。
+
+连接选择只能由用户斜杠命令发起，不会作为模型工具暴露。切换只影响之后创建的 Agent 会话，已有
+会话继续固定在原连接与 workspace。`/bailinghub use <workspace>` 是另一件事：只有当前 Agent
+Session 已经允许目标 workspace 时才成功。
+
+删除当前连接后，适配器会读取 SDK registry，把剩余的当前连接（包括没有别名的连接）设为新会话
+默认值；删除最后一个连接后则明确进入未配置状态。删除后的 registry 刷新失败不会把已经成功的
+删除改写成错误；如果删除的是非当前连接，刷新不可用时也会保留仍然有效的默认连接。
+
+对于同一个 `Hub + clientAppId + workspace` 公开绑定，最终身份由业务授权页及其可信
+`on_behalf_of` 结果决定。如果另一个本机连接名已经授权同一身份，SDK 会用本次连接覆盖旧连接，
+并撤销旧 Agent Session；不同可信身份则继续作为相互独立的连接。如果从一个已经属于其他身份的
+`connectionName` 发起登录，SDK 会保留原连接名及其 Session，为新身份分配一个不冲突的本机名称
+（例如 `default-2`），并把新连接设为后续会话的当前选择。用户可以用 `connections list` 查看
+两者，再用 `connections use <名称或连接键>` 显式切换。如果登录结果返回
+`cleanupRequired: true`，说明新连接仍然授权成功，但一个或多个同绑定旧连接还需要显式清理；
+如果身份检查被推迟，此时还不能断言它们是同一身份。不要重复授权；先查看 `connections list`，
+再对提示的旧连接执行
+`/bailinghub connections remove <名称或连接键>`。
 
 首次验收时，新建一个 DSH 会话，先做一次只读查询，再做一次允许的修改。确认 BailingHub
 后台能看到同一个会话、run、可见最终回复和工具调用轨迹。需要审批的能力必须在审批后恢复
@@ -133,9 +174,10 @@ workspace 时才会成功，不能借此任意切换中枢 route。当前命令
 
 ## 安全与隐私边界
 
-- 模型不能通过工具参数选择 Hub URL、workspace、身份、凭据、审批结论或能力版本；
-- SDK 在 macOS 使用 Keychain；Linux 与其他 POSIX 系统必须显式启用安全文件回退；0.2.0
-  暂不支持 Windows Agent Session 凭据存储；
+- 模型不能通过工具参数选择 Hub URL、workspace、本机连接、业务身份、凭据、审批结论或能力版本；
+- SDK 在 macOS 使用 Keychain；Windows 凭据文件保存在 LocalAppData 并由 CurrentUser DPAPI
+  保护，Windows PowerShell 或 DPAPI 不可用时失败关闭，不会降级为明文；Linux 与其他 POSIX
+  系统必须显式启用安全文件回退；
 - BailingHub 对每次治理调用重新校验身份、scope、审批、幂等与调用状态，业务系统仍执行
   最终权限判断；
 - 适配器会发送 Agent Client 契约所需的可见用户输入、受治理工具参数/结果和可见最终回复，
@@ -167,12 +209,12 @@ mcp__bailinghub__get_governed_job
 mcp__bailinghub__wait_for_governed_job
 ```
 
-0.2 Agent Client 不会自动读取或迁移 0.1 Client Token。测试升级或回滚时必须显式固定版本，
-并遵循 [0.1 到 0.2 的迁移边界](MIGRATION_VNEXT.md)。
+0.3 Agent Client 不会自动读取或迁移 0.1 Client Token。测试升级或回滚时必须显式固定版本，
+并遵循 [0.1 到 0.3 的迁移边界](MIGRATION_VNEXT.md)。
 
 ## 兼容范围与反馈
 
-0.2.0 只对 [COMPATIBILITY.md](COMPATIBILITY.md) 中列出的版本完成了验证。DeepSeek
+0.3.0 只对 [COMPATIBILITY.md](COMPATIBILITY.md) 中列出的版本完成了验证。DeepSeek
 Harness 仍是 Developer Preview，每次 Harness 升级都必须重新执行 Native Lifecycle Smoke。
 
 问题请提交到 [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues)。