dsh-bailinghub 0.3.0 → 0.5.0

package/docs/GETTING_STARTED.zh-CN.md

@@ -1,83 +1,133 @@
-# 三分钟开始使用
+# 开始使用 0.5.0
 
-这份指南面向业务系统已经接入 BailingHub 的最终用户。如果还没有完成业务接入，需要先由
-BailingHub 管理员和业务开发者准备中枢应用、授权页面与业务能力，再安装本插件。
+这份指南面向业务系统已经接入 BailingHub 的用户。管理员需要先准备 Core 0.7.0、公开的 Client
+App ID、workspace 和浏览器业务授权入口。多系统时，每个目标分别授权，且属于同一中枢、同一
+审计域；已有能力无需重新声明，但每项动作必须已由相应业务系统开放。
 
-## 先向管理员获取什么
+## 第一步：安装与配置
 
-只需要向管理员获取四项公开连接信息：
+使用 Node.js `22.19.0+` 或 `24+`，并安装兼容的 DSH：
 
-```text
-Hub URL
-Client App ID
-Workspace
-Connection Name
+```bash
+npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile web add dsh-bailinghub@0.5.0
 ```
 
-它们用于定位 BailingHub 应用和初始业务空间，不是凭据。不要让管理员把 Client Token、Tool
-Provider 密钥、业务密码、模型 API Key、授权码、浏览器 Cookie、业务地址或租户专属登录地址
-发给你。
-
-## 第一步：安装插件
-
-把精确公开版本安装到 DSH Web Profile：
+插件会自动安装 SDK 0.5.0。通过插件设置填写四项公开信息，或使用对应环境变量。下面都是
+占位值，需要替换成管理员提供的中枢地址、Client App ID 和 workspace：
 
 ```bash
-dsh plugin --profile web add dsh-bailinghub@0.3.0
+export BAILINGHUB_HUB_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
+export BAILINGHUB_WORKSPACE='order_assistant'
+export BAILINGHUB_CONNECTION_NAME='A 店'
+dsh --profile web --dump-config
+dsh web
 ```
 
-插件会自动安装匹配版本的 BailingHub SDK，不需要再手工拼装依赖。
+`Connection Name` 是你设置的本机名称。这四项都不是凭据；不要把业务密码、Client Token、签名
+密钥、模型 Key、业务 API 地址或授权页面地址写入插件设置或聊天消息。
 
-## 第二步：填写四项连接信息
+## 第二步：分别授权账号
 
-可以在 DSH 插件设置页面填写，也可以使用对应环境变量：
+在 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'
+```text
+/bailinghub login
+/bailinghub doctor
+/bailinghub status
 ```
 
-上面都是占位值，请替换成自己中枢管理员提供的公开信息。不要把凭据写进 Cordis Patch，也不要
-把凭据粘贴到聊天消息里。
+浏览器会打开原业务授权页面。在那里登录、切换账号，并按业务系统要求选择门店或租户；同意前
+核对实际业务身份。可信身份由业务授权页面决定，本机名称 `A 店` 不证明身份。配套后端可自动
+提供授权主体名称，它与固定连接键、系统用途说明独立；缺名会明确提示。同名或改名不重建授权，
+也不更改原会话记录。
+
+如需使用**同一系统、同一 workspace** 的 B 店，用同样的三项公开信息创建清晰命名的新连接，
+再分别授权：
+
+```text
+/bailinghub connections add "B 店" https://hub.example.com example-agent-client order_assistant
+/bailinghub login
+/bailinghub connections list
+```
 
-## 第三步：在浏览器完成授权
+请在业务页确认选中了 B 店。如果实际再次同意的是同一可信身份，SDK 会替换它的旧连接和 Session，
+不会凭名称造出第二个身份。从已有名称授权另一身份时，原连接保留，新身份会获得可用别名。
+`default-2` 之类的名称不能证明是哪家店，使用前应核对对应关系。若登录提示需要清理，新连接
+已经授权成功；请检查并删除提示的旧条目，不要重复授权。
 
-启动 DSH 后依次执行：
+要接入**另一个系统**，使用管理员提供的该系统 Client App 与 workspace，并在同一中枢上
+独立授权。例如库存目标可以使用以下占位配置：
 
 ```text
+/bailinghub connections add "库存系统" https://hub.example.com inventory-client inventory_assistant
 /bailinghub login
-/bailinghub status
-/bailinghub workspaces
+/bailinghub connections list
+```
+
+这些配置不能从产品名称推测。每个选中目标都需要独立原 Agent Session；同系统流程中已有的
+B 店连接可以继续保留。
+
+## 第三步：选择本次会话的业务范围
+
+**新建会话，在发送任何消息前**执行：
+
+```text
+/bailinghub connections list
+/bailinghub scope set <商城连接键> <库存连接键>
+/bailinghub scope
 ```
 
-`login` 会打开 Client App 配置的唯一业务授权入口。在该页面登录或切换账号，并在业务系统要求
-时选择租户；点击同意前，确认页面显示的最终业务身份和准备使用的 workspace。整个过程沿用业务
-系统自己的登录流程，不会把业务密码或业务地址交给插件。
+从列表复制固定连接键替换占位符，不能直接填写名称。可以选单份授权、同系统多份授权，或
+同一中枢、同一审计域的多个系统。等设置成功回显后再发请求。相应能力已开放、商品关系已确认时：
 
-`Connection Name` 只是本机选择器。同一可信业务身份再次授权同一 Hub/client/workspace 绑定时，
-SDK 会覆盖旧的本机连接；不同可信身份继续相互独立。如果当前名称已经属于旧身份，SDK 会保留
-它，并给新身份分配一个可用名称（例如 `default-2`），同时把新名称设为当前连接。使用
-`/bailinghub connections list` 可以查看两者，再用
-`/bailinghub connections use <名称或连接键>` 显式切换。如果登录提示需要清理，新连接其实已经
-授权成功，但某个旧连接可能仍需检查或删除：不要再次授权，应先列出连接，再删除提示的旧连接。
+```text
+先查保温杯库存。有货就把商城对应商品的售价改为 59 元并上架；没货就先不要上架。
+```
+
+系统说明可在首次查工具前解释“线上售卖”和“库存管理”的区别。“尚未加载”表示还没查询工具，
+不是没有能力。查库存不等于锁库存或自动同步；改价、上架及审批要分别核对结果。
+
+原同系统流程仍可选择 A 店和 B 店，在报表能力可用时对比营业情况。没有实际调用的系统不能
+被标为已执行。
 
-## 第四步：尝试一条安全的业务请求
+智能体自行选择每次调用使用哪份选中授权；实际数据和操作范围仍由业务权限决定。先验证一次
+查询，再在开发空间尝试一次可回滚且允许的修改。需要审批的操作继续沿用原规则。
 
-新建一个会话，先尝试业务系统已经开放的一条只读请求，例如：
+未选择范围，或执行 `/bailinghub scope none` 时，只进行普通聊天，不启动 BailingHub 业务执行。
+第一条消息会固定这个选择。之后要增减账号，或从普通聊天开启业务访问，需要新建会话；切换
+连接管理的默认连接不会改变会话范围。
+
+## 第四步：核对业务结果与沟通过程
+
+在业务后台核对最终结果，在 BailingHub 查看原调用轨迹。配合 Core 0.7.0，还能把可见用户消息、
+助手回复、轮次与相关执行记录放在同一份沟通记录里查看。多授权的各份执行记录仍分别保留自身
+调用摘要。
 
 ```text
-查询演示员工 EMP-001，并汇总我能看到的资料。
+/bailinghub archive status
+/bailinghub archive sync
 ```
 
-随后可以在专用开发空间尝试一次可回滚、当前账号允许的修改。实际能问什么，取决于业务系统
-开放了哪些能力。需要审批的操作必须继续走原有审批，没有权限的操作仍然不可用。
+第一条查看上传状态，第二条补传已保存记录，不会重做业务操作。`synced` 表示已保存事件获中枢
+确认，不代表业务成功；`pending` 表示尚未传完；`blocked` 表示原授权当前无法允许上传；
+`unsupported` 表示 SDK 或中枢不支持归档。`storage_error`、`recovery_gap` 表示采集本身可能
+不完整；宿主没有历史可供核对时，覆盖度为未验证。
+
+## 第五步：断网或重开后继续
+
+重开已保存的业务会话时，核验全部原授权后才恢复原账号范围。若离线重开，联网后可以在同一
+会话执行 `/bailinghub archive sync` 或 `/bailinghub scope` 再试一次。临时网络不确定可以恢复；
+已撤销、被替换的授权，损坏的范围快照或存储冲突仍会阻断整组，不会自动换账号。
 
-## 第五步：在 BailingHub 查看结果
+恢复范围与补传记录，**不等于恢复进程重启前未完成的业务调用或审批**。未开始的保存草稿需要
+重新选择；旧版已开始但没有有效范围快照的会话只能保留为历史，请另开新会话。
+`/bailinghub sync` 只用于当前仍运行会话的待同步执行结尾记录。
 
-BailingHub 控制台应当能看到同一条可见会话、Agent Run、业务工具调用、审批状态与最终结果。
-只有插件安装成功，还不能证明业务操作已经真正完成。
+所选账号的上下文会共用本地模型会话；本机私有归档含明文任务正文，直到手动清理才删除。它不
+采集隐藏思考、附件或全部历史。启用前请看[隐私说明](../PRIVACY.md)；数据需要隔离的账号应分开
+会话，不要在可见消息里粘贴秘密。
 
-如果初始化失败，请在 GitHub Issue 中提供 DSH 版本、插件版本、操作系统、失败命令和脱敏错误。
-不要附带 Token、私有地址、个人信息、授权码或生产业务载荷。
+初始化失败时，可向 [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues)
+提供版本、操作系统、失败命令和脱敏错误，不附带凭据、私有地址、授权码、个人信息或生产载荷。

package/docs/MIGRATION_VNEXT.md

@@ -1,7 +1,130 @@
-# 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.3 Agent Client.
+# Migrate to 0.5.0
+
+## From 0.4.0: add systems without replacing existing authorizations
+
+Version 0.5.0 extends one-system multi-account conversations to different business systems on one
+Hub and audit domain. It adds system descriptions before capability search and optional business
+subject names. The four public plugin fields, existing host scope/archive APIs, permissions and
+business approval rules remain in place.
+
+1. Have the administrator back up and upgrade to Core 0.7.0. Apply only outstanding migrations in
+   order; upgrading from 0.6.1 includes 058/059. The plugin installer does not migrate the Hub.
+2. Finish active business work and retry known pending completions with `/bailinghub sync`.
+   Retain the original DSH home, SDK credentials, real Session events, scope files and archive outbox.
+3. Install and restart DSH:
+
+   ```bash
+   dsh plugin --profile web add dsh-bailinghub@0.5.0
+   ```
+
+   The package installs exact SDK 0.5.0. Do not manually mix in an older SDK or a local file dependency.
+4. Check `/bailinghub doctor` and `/bailinghub connections list`. Valid existing authorizations
+   continue working; no new login is needed just for a version change or a display rename.
+5. Add and authorize only the extra systems needed for the new task. In a new conversation, select
+   their fixed connection keys and wait for `/bailinghub scope` to confirm before sending a message.
+6. Test an inventory read and a low-risk shop action with confirmed product mappings. Check each
+   target, separate result/approval, and original run link. Then check `/bailinghub archive status`.
+
+Existing started v1 conversations keep their exact original scope and archive identity. The upgrade
+never expands them to every account or converts them to a cross-system selection. A saved unstarted
+draft requires confirmation; a started conversation whose scope cannot be restored stays blocked.
+The same-runtime offline recovery rules continue to use the complete original group.
+
+Custom hosts keep `setSessionScope`, `getSessionScope`, `restoreSessionScope`,
+`getSessionArchiveStatus` and `syncSessionArchive`. Custom stores must preserve complete scope/outbox
+v2 records, original bindings, events, acknowledgement positions and CAS revisions. Hosts may show
+current `subjectDisplay` fields and omit a manual display-name input, but keep internal connection
+selectors/keys separate; do not rebuild authorization or archive state to update a name. Missing
+names stay explicit. Administrator-maintained system descriptions are separate from subject names
+and do not grant tools or permissions.
+
+### 0.4 用户升级摘要
+
+管理员先备份并升级 Core 0.7.0，按顺序仅执行未完成迁移（从 0.6.1 升级包括 058/059）。用户先
+结束当前业务任务，用 `/bailinghub sync` 重试待同步结尾，安装 `dsh-bailinghub@0.5.0` 并重启。
+插件自动安装 SDK 0.5.0。保留原凭据、真实 Session 事件及范围/待传文件；有效授权不因升级或改名重建。
+
+已有同系统会话范围保持不变。要把商城与库存一起使用，分别授权，另开会话，在首消息前选中固定
+连接键并等确认。先验证库存查询与一个低风险商城动作，核对各自结果、原审批和执行关联。
+自定义宿主保留原五个接口；自定义存储需完整保存 v2 的原绑定、事件、确认进度与修订号。名称
+只用于展示，不能替代连接键、身份或系统说明。详情见[本次更新](RELEASE_NOTES_v0.5.0.md#简体中文)。
+
+### Downgrading from 0.5 to 0.4
+
+Finish active work and synchronize pending completions and archives first. Keep the original profile
+and v2 files as recovery material. Version 0.4.0 does not understand cross-system v2 scope/outbox or
+provide this release's system/subject metadata. Do not reinterpret v2 as v1, delete it, or reconstruct
+it from the current registry. Use a separate profile with new same-system conversations if reverting.
+An application downgrade does not undo an accepted business action or remove its Hub audit. Core
+database rollback follows Core's own migration guide; never drop new columns as a plugin rollback.
+
+## Historical 0.3.0 → 0.4.0 behavior
+
+The section below documents the scope change introduced in 0.4.0. When upgrading directly to 0.5.0,
+follow the current install/Core versions above and also preserve these explicit-scope requirements.
+
+### From 0.3.0: choose the conversation scope explicitly
+
+Version 0.4.0 keeps the four public configuration fields and existing SDK-owned authorizations.
+It changes how a conversation gets business access: logging in or selecting a default no longer
+automatically enables it. A new conversation is ordinary chat until you select its scope.
+
+1. Ask the administrator to upgrade the Hub to Core 0.6.1. The plugin installs exact SDK 0.4.0.
+2. Before restarting, finish active business work and retry known pending run completions with
+   `/bailinghub sync`. Do not assume a process restart resumes an invocation or approval.
+3. Upgrade the plugin and restart DSH:
+
+   ```bash
+   dsh plugin --profile web add dsh-bailinghub@0.4.0
+   ```
+
+4. Run `/bailinghub doctor` and `/bailinghub connections list`. Existing valid authorizations can
+   be selected; you do not need to authorize them again merely because the plugin was upgraded.
+5. Start a new conversation. Before its first message, run
+   `/bailinghub scope set <connection-key> [<another-connection-key> ...]`, using fixed keys from
+   the list, then `/bailinghub scope`. Wait for successful confirmation. Select only this task's
+   accounts; several accounts must share one Hub/Client App/workspace.
+6. Try a read, then a reversible permitted update. Check the actual result and original business
+   calls in BailingHub. Use `/bailinghub archive status` to inspect the separate visible record.
+
+Keep old started conversations as history: if they have no valid locked scope snapshot, they
+cannot automatically adopt today's selected connection. A stored draft that never started needs
+explicit selection again. Existing 0.4 saved business conversations can reopen with their original
+scope after every member is revalidated. An offline reopen can retry in the same conversation
+with `/bailinghub scope` or `/bailinghub archive sync` once connectivity returns.
+
+The new archive uploads visible user/assistant text, turn boundaries, and original run links for
+the full frozen member set. Local pending events survive restart and upload without replaying
+business work. It does not backfill all pre-upgrade history or restore unfinished invocations.
+A detectable gap stays `recovery_gap`; missing host history is unverified. Review [Privacy](../PRIVACY.md):
+the local outbox retains plaintext visible text, including acknowledged events, until removed by
+the host/operator. There is no automatic retention cleanup.
+
+### 0.3 用户升级摘要
+
+先由管理员升级 Core 0.6.1；结束当前业务任务并用 `/bailinghub sync` 收口待同步结尾记录，再安装
+`dsh-bailinghub@0.4.0` 并重启 DSH。已有有效授权可继续使用，不必仅因插件升级重新授权。
+执行 `/bailinghub connections list` 后，**新建会话，在首条消息前**用
+`/bailinghub scope set <连接键> [<另一连接键> ...]` 选择账号，并等待 `/bailinghub scope`
+确认。未选范围就只是普通聊天；旧版已开始会话没有范围快照时不能直接恢复业务访问。
+
+上传状态用 `/bailinghub archive status` 查看，联网后用 `/bailinghub archive sync` 补传。
+这会恢复原范围并上传已保存文本，不会恢复重启前的业务调用或待审批操作，也不代表全部旧历史已
+归档。更多步骤见[中文上手指南](GETTING_STARTED.zh-CN.md)与[隐私说明](../PRIVACY.md)。
+
+## Downgrading from 0.4 to 0.3
+
+Finish current business work and synchronize pending completions and archives before an explicit
+downgrade. Keep the old profile and its scope/outbox files intact. Version 0.3.0 does not provide
+0.4's explicit scope gate, multi-authorization conversation, or archive retries; its new conversations
+use its selected default connection. Use a separate profile and new conversation if reverting.
+Do not delete credential or archive files as a downgrade shortcut. A downgrade does not cancel an
+accepted business action or delete its Hub audit.
+
+## Legacy 0.1.x to the native Agent Client
+
+There is no automatic credential, configuration, tool, or orchestration migration from the legacy
+static MCP path. The following boundary remains separate from the 0.3 to 0.4 upgrade above.
 
 ## What remains unchanged
 
@@ -47,9 +170,9 @@ switch account, and select a tenant.
 
 ## Safe evaluation before migration
 
-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
+Do not replace a working production profile merely to evaluate 0.5.0. Use a separate DSH home or
+another isolated Web profile and verify that the CLI really honors that location. The named
+connection lifecycle introduced in `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
@@ -57,30 +180,31 @@ alias and Session and receives a non-conflicting alias that becomes current. Use
 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.3 package into an isolated profile.
+2. Install the exact released 0.5.0 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 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.
+5. Verify status and workspace discovery. In a new conversation explicitly select its scope, then
+   verify one read, one permitted mutation, approval/resume, and the Hub trajectory.
 6. Separately re-run the `0.1.1` submit and same-job follow-up against the newly released Core.
 
 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.3
+## Moving a legacy 0.1 profile to 0.5
 
 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.3 plugin version. Do not use an unpinned dist-tag.
+3. Install the exact accepted 0.5.0 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`, 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.
+6. Run `/bailinghub status`, open a new conversation, explicitly select its scope before the first
+   message, and repeat the accepted read/mutation checks.
 7. Confirm BailingHub receives visible conversation and invocation audit without hidden reasoning.
 
 The developer or deployer supplies the Hub URL, public client app id, and initial workspace/route.
@@ -111,7 +235,7 @@ reuse, move, or republish an npm version or Git tag as a rollback mechanism.
 
 ## Release gates
 
-Before any public 0.3 release:
+Before a public 0.5 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,
@@ -119,10 +243,11 @@ Before any public 0.3 release:
 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, same-identity replacement, different-identity isolation, and Hub trajectory pass
-   from the packaged artifact.
+   completion, same-identity replacement, different-identity isolation, explicit one/many-account
+   scope, visible archive, offline reopen/retry, and Hub trajectory pass from the packaged artifact.
+   Revocation must block the complete original selection, and archive retries must not replay business work.
 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.3.x version until all gates pass, and do not describe release
+Do not tag or publish a future version until all gates pass, and do not describe release
 validation as public adoption.

package/docs/PROJECT_BOUNDARIES.md

@@ -23,8 +23,12 @@ community integration, not an official DeepSeek plugin or partnership.
 
 ## Public native line (0.2.0 onward)
 
-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:
+Version 0.2.0 introduced this dependency path; 0.3.0 added the named connection lifecycle.
+Version 0.4.0 added explicit same-system conversation scope and visible conversation archiving.
+Version 0.5.0 extends selection across systems on one Hub and audit domain, and adds controlled
+system descriptions and business subject display names. These names do not establish identity or
+product mappings, and cross-system selection does not provide durable task orchestration or rollback.
+All remain separate from the public static MCP path:
 
 ```text
 DeepSeek Harness local Agent