dsh-bailinghub 0.4.0 → 0.6.0

package/docs/CROSS_SYSTEM_CONVERSATIONS.md

@@ -0,0 +1,138 @@
+# One conversation across business systems
+
+**Release pairing: Core 0.7.0, SDK 0.5.0 and DSH 0.5.0.** The plugin installs its exact SDK
+dependency. Core 0.6.1 / SDK 0.4.0 / DSH 0.4.0 do not include this extension; upgrade the Hub
+before selecting targets from different systems.
+
+## What you can do
+
+Select, for example, a shop account and an inventory account already authorized on the same
+BailingHub deployment. Ask the same local Agent to check product stock, then change a corresponding shop product's price and list it using permitted actions. The Agent keeps each system's tools and authorizations distinct; you do not switch
+the global connection between steps. Available actions still depend on each system's declared
+capabilities and the permissions of the selected account.
+
+The Agent initially sees the selected target directory. It searches the intended target's
+capabilities when needed, then calls the corresponding typed tool. A capability search opens
+that target's run with the search's minimal task description. Other systems do not automatically
+receive the original user turn or contribute their memory. The local Agent and the independent
+conversation audit still share the visible conversation.
+
+## Start a conversation
+
+### Understand the selected systems before choosing tools
+
+An administrator can provide each connected system's name, short purpose, usual business areas
+and boundaries in BailingHub. The Agent reads these descriptions for the selected accounts before
+its first capability search. For example, it can distinguish online selling from inventory
+management without a client-specific product dictionary. Business-supplied subject names identify
+the particular organization, project or other authorized subject for display. They are separate
+from product purpose and do not prove identity or grant permissions.
+
+A description says what the product usually does. The actual tools and permissions still come
+from authorized capability discovery. “Not loaded” means the tools have not been requested yet;
+it does not mean the product has no capabilities. Missing descriptions or an older server show
+unknown information and preserve the existing search flow. Reading a description sends no user
+message and creates no business run. Existing same-system first-turn runs are unchanged.
+
+If the server explicitly reports that a selected workspace is unavailable, its directory says
+unavailable while retaining the original selection. An uncertain network failure remains unknown;
+neither condition selects another account. A later turn reads the original target again.
+
+### Select the accounts
+
+1. Authorize each target separately and verify the intended subject on the business authorization
+   page. With a compatible business backend, the backend supplies its name automatically. A local
+   connection selector remains independent; missing names show “Authorization name pending sync”.
+   Names do not prove a mapping between two systems or distinguish duplicate-named subjects.
+2. In a new conversation, use `/bailinghub connections list`, then
+   `/bailinghub scope set <shop-connection-key> <inventory-connection-key>`.
+3. Wait for successful confirmation before sending the first message. Start with a precise
+   request identifying the intended systems, objects and allowed action.
+4. Review the separate results and any approval requests. Use `/bailinghub archive status`
+   to check visible-record upload; `/bailinghub archive sync` retries uploads without repeating
+   business actions.
+
+An empty scope remains ordinary chat. The first user message freezes the selected targets.
+Reopening a conversation restores the original selection after all original members pass
+validation; a draft that never started needs fresh confirmation. A temporary outage can be
+retried in the same runtime. Revoked/replaced members never cause a switch to a default or subset.
+
+## Host integration
+
+Keep the existing `setSessionScope`, `getSessionScope`, `restoreSessionScope`,
+`getSessionArchiveStatus` and `syncSessionArchive` flow. The returned scope view retains its v1
+schema and gains `targetMode: "multi_system"`; authorization entries additionally include
+`clientAppId` and `systemRef`. Use those public fields to group the selection UI if helpful.
+Never feed raw keys, credentials or writable scope records to the model.
+
+The built-in stores understand both v1 and v2. A custom store must retain the complete v2 record
+without reconstructing it from today's registry, preserve the original host Session identity,
+and provide atomic revision comparison. Persist original DSH events so incomplete capture can
+be detected on reopen. No second body-reporting path is required.
+
+Cross-system operation requires the matching SDK's capability negotiation, frozen-binding guard,
+and the Core's target-member archive extension. Missing support reports
+`CROSS_SYSTEM_SCOPE_UNSUPPORTED`; it is not a reason to send the first message with an old scope.
+The matched Core requires an additive database migration through its own deployment process;
+installing this plugin does not migrate or deploy the Hub.
+
+## Limits
+
+- One Hub, with independently authorized Sessions for every selected target. Cross-Hub scope
+  and multiple selected routes sharing one Agent Session are not supported.
+- Task planning and step ordering are performed by the Agent. This is not a deterministic
+  dependency engine, a distributed transaction, automatic rollback, or cross-process task recovery.
+- Original invocation recovery is available in later turns of the same live runtime. The
+  unreleased [durable recovery candidate](INVOCATION_RECOVERY.md) adds explicit recovery after
+  restart when the host retains its invocation journal. Archive restoration alone does not
+  reconstruct pending invocations or approvals.
+- Different systems' object IDs are unrelated unless a verified business mapping establishes
+  the relationship. The Agent must clarify an ambiguous mapping.
+- The runtime enforces target and capability boundaries. It does not provide automatic
+  sensitive-text redaction or a field-level cross-system data-sharing policy.
+- Complete transcript reading remains an administrator audit operation. An individual business
+  authorization does not grant an API to read the entire mixed transcript.
+
+## 简体中文
+
+本版配套 Core 0.7.0、SDK 0.5.0 与 DSH 0.5.0，插件会安装精确 SDK 依赖。
+Core 0.6.1、SDK/DSH 0.4.0 不含本次扩展；选择不同系统前先升级中枢。
+
+### 对使用者有什么变化
+
+你可以在同一个会话里选中“商城”和“库存系统”的授权，让助手先查询保温杯库存，再使用商城允许的
+改价、上架等动作。每一步都会使用对应系统的工具与授权，仍按该系统的权限和审批规则执行。
+
+助手先看到你选中的目标目录，需要哪个系统时才查找它的能力、加载它的上下文。不会因为选中了两个系统，
+就把每句话自动发送给两者。某个系统的查询结果进入本地模型后，会成为同一会话的上下文；只有允许这样共享
+的数据才适合放在同一会话。完整可见沟通通过独立会话账本归档，各系统仍保留自己的操作记录。
+
+### 怎样开始
+
+接入方可以在中枢维护系统名称、简短用途、典型业务方向和边界。助手在首次搜索工具前就能看到本会话所选系统
+的介绍，例如分清“线上售卖”和“库存管理”，不需要每个客户端分别写死产品词典。同系统的多个账号也会显示
+相同的系统归属。授权主体展示接口单独提供业务授权主体的名称，用于表示具体的组织、账号、项目等；名称不证明身份，
+也不增加权限。
+
+系统介绍说明产品通常做什么，实际能做什么仍取决于此授权的能力查询和原有权限规则。“尚未加载”表示还未
+查询工具，不表示没有能力。介绍缺失、旧版本不支持或介绍请求暂时失败时，可继续使用原有的授权工具搜索。
+读取介绍本身不发送用户正文、不创建业务运行记录；同系统原有首轮运行机制保持不变。
+
+如果服务端明确报告所选工作空间不可用，目录会显示“不可用”并保留原选择；无法确定的网络失败显示“未知”。
+两者都不会自动切换授权，后续轮次仍查询原目标。
+
+先分别授权并在业务授权页确认对象。授权主体展示接口由业务后端提供主体名称；名称缺失时明确显示“授权名称待同步”，
+内部连接标识独立保留。再新建会话，使用上面的 scope 命令选中两份固定授权。
+等选择成功后，再明确提出操作对象和要做的事。首次消息后范围固定；需要增减系统时新建会话。
+
+如果库存里的商品与商城中的某个商品需要关联，应使用已经确认的业务映射，或由用户明确确认。
+两个系统的商品名或编号看起来相同，并不能证明它们是同一对象。库存查询不等于锁库存或建立自动库存同步。
+
+### 下游需要配合什么
+
+宿主继续使用现有五个范围与归档接口，不需要另加一条正文上报链路。界面可以按新返回的系统字段分组展示，
+并继续保持“选择成功才允许发首条消息”。内置持久化已支持新记录；自定义存储需要原样保留 v2 的目标绑定、
+原会话身份、事件和修订号。Core 0.7.0 需要通过自身升级流程应用未执行的迁移（本次包括 058/059）。
+
+业务后端只需继续声明能力、独立授权并执行原有业务规则；如果用户要做的动作尚未开放，才需要补充该业务能力。
+本版解决跨系统选择、调用和完整追溯，不包含周年庆等长任务的持久依赖调度、跨进程恢复或自动回滚。

package/docs/GENERATED_ARTIFACTS.md

@@ -0,0 +1,77 @@
+# 本地智能体附件空间：DSH 宿主接入
+
+智能体生成或用户明确指定用于业务的图片，可以用于活动海报、内容封面、经营图表，也可以用于商城商品。宿主把当前会话获准使用的图片登记到附件目录，插件提供目录查询和上传工具；模型选择目标授权与附件引用，中枢保存图片并返回 URL，供后续业务工具使用。图片不必在当前轮生成；仅用于聊天理解的附件不会因此自动登记或上传，聊天附件历史存档是另一项独立能力。
+
+首期支持 PNG、JPEG、WebP。附件空间提供会话级目录、上传与上传结果恢复，不把 PDF、Word、视频或完整网盘管理写成已经交付的能力。业务系统需要预先提供相应的图片 URL 接口。
+
+配套版本：Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0。新能力需部署方升级并按宿主契约接入；业务权限、审批和原身份约束保持。
+
+## 宿主需要接哪两处
+
+```js
+import { createAgentClientPlugin, createFileArtifactStore } from 'dsh-bailinghub'
+
+const plugin = createAgentClientPlugin({
+  // 保留原 SDK、scopeStore、archiveStore 等配置。
+  artifactSource: {
+    async list({ sessionId }) {
+      // 从本会话已获准用于业务的图片中读取；只返回元数据，最多 100 项。
+      return [{ artifactRef: 'campaign-banner', name: 'campaign-banner.png',
+        mime: 'image/png', bytes: generatedSize, sha256: generatedDigest }]
+    },
+    async read({ sessionId, artifactRef }) {
+      // 宿主按已登记引用读取获准文件，返回 Uint8Array。
+      // 检查归属、允许目录、符号链接及读取期间文件变化；不要直接拼接模型给出的路径。
+      return generatedBytes
+    },
+  },
+  artifactStore: createFileArtifactStore({ directory: artifactRecoveryDirectory }),
+})
+```
+
+`artifactRef` 是宿主管理的稳定引用，允许字母、数字、下划线和短横线，最多128字符；不可把同一个引用改指另一份文件。同名图片可以用不同引用。目录属于真实 DSH Session，重新打开时保持原归属；后台持久化上传元数据目录同样需要跨重启保留。也可实现自有 `artifactStore.get(uploadId)` / `reserve(record)`：reserve 必须原子、只写一次并返回先前记录或新记录，落盘完成才成功返回。内存 store 仅用于测试或明确的临时会话。
+
+未提供 artifactSource 时不会新增模型工具，已有业务流程不变。缺少持久恢复 store 时上传返回 storage_error，并且不会发送文件。
+
+## 模型实际能用的工具
+
+- `list_generated_artifacts`：读取当前会话产物目录，不返回路径或文件正文。
+- `upload_generated_artifacts`：必须明确 `authorization_ref` 与 `artifact_refs` 数组；每批1–8张，单张不超过6MiB，支持PNG/JPEG/WebP。
+
+上传成功后模型直接使用 ready URL，不需要为每次使用重复查询地址或上传。只有不确定的上传结果或会话重开恢复才查询原上传记录。
+
+业务操作独立执行并单独判断结果。例如更新商城轮播图时，所有必需图片 ready 后再提交完整清单，保留未被要求删除的旧图片；业务结果未知时保留原 invocation，不能重发写操作。
+
+模型不选择桶或密钥。中枢管理员在“智能体客户端 → 配置接入 → 工具与审批 → 生成图片上传”选择媒体存储。第一期图片用于公开展示；普通COS/OSS或显式本地存储都由部署方管理保留，不增加文件到期判定。
+
+## 失败和重开
+
+### 跨轮上传与旧错误记录恢复
+
+新上传只关联目标授权**当前轮次的 active run**。跨系统按需启动业务 run；该目标当轮尚未启动时，上传使用原会话与当前轮次、不带可选 runId，既不沿用上轮记录，也不为上传额外创建业务 run。
+
+旧候选可能保存了“本轮上传 + 上轮 run”的记录。只有配套 Core 返回 `artifact_run_turn_mismatch`（同一原身份、路由、会话均一致，仅轮次不同），且再次读取原上传 ID 明确返回 `artifact_not_found`，DSH 才自动纠正。泛化的 `artifact_run_mismatch`、授权失效、网络错误或结果未知都不能触发纠正。Core 的身份和关联检查保持生效。
+
+纠正不覆盖原恢复记录：通过现有 get/reserve 原子保存独立的 `bailing.artifact-run-link-repair.v1` 记录，保留原记录摘要和原上传 ID。修正元数据只删除已证明属于另一轮的 runId，保留原上传会话、轮次、内容及目标；实际 HTTP 始终使用原上传 ID。宿主应完整保存记录中的 `runLinkRepair` 字段，不把这个本地记录键当成新增云端上传或新产物。无需新增 store 方法。
+
+纠正必须落盘后才补传；已 ready 的原回执直接复用，pending 不改绑，确认丢失后读取原 ID。原记录或纠正记录缺失、损坏时返回 storage_error，不根据服务端 URL 猜补本地历史。旧 Core/SDK 没有精确错误码时，旧错链记录继续明确阻断；当前正确链接的新上传仍兼容原附件 API。
+
+两个工具名中的 `generated` 为兼容保留，不限制来源必须是 AI 生成。宿主需要更新自己的目录说明，让用户明确指定业务用途的图片可以受控登记，不新增聊天附件自动同步或用户手动上传入口。
+
+每文件上传身份绑定原真实 Session、连接与产物引用，首发前原子保存原 Hub/client/workspace/Agent Session、内容摘要、名称和原会话/轮次/run关联。重试或重开先读取原中枢记录，成功项直接复用 URL；pending 或尚未写入时补传原文件。即使原文件已不可读，已确认成功的上传仍可恢复。
+
+批量结果包含 `results`、`all_ready` 和 `business_operation_performed=false`。每项为 ready、pending 或 blocked。成功项保留，失败项独立处理；不要因部分上传成功就写入残缺图库。
+
+本地持久化失败返回 storage_error；原记录损坏或丢失须由宿主标记恢复缺口，不能猜补原历史。暂时网络失败可以在同一 runtime 重试，保留原记录。任何原授权成员撤销或改绑时整组阻断，不退回默认、子集或替代 Session。取消后迟到上传不会重新注册业务工具或返回可继续执行的轮次；已经保存的对象及原记录仍可在合法恢复时查询。
+
+旧SDK/Core返回artifact_unsupported，保留原业务工具能力。Lazy SDK transport 已转发新增接口，但宿主仍必须实际提供生成文件来源。测试替身与真实对象存储连通性分开验收。
+
+## 业务后端要不要改
+
+如果原业务能力已经接收图片 URL，不必改授权或审批规则。客户端将 ready URL 作为原业务参数传入即可。需要业务自身素材ID、转存或素材库归属时，另接该系统的业务导入能力。
+
+## 分开记录的已知限制
+
+配套 Core 0.8.0 已提供可配置的中枢工具限额，小时/日额度按原窗口计数，并为新调用保留加密原参数。DSH 读取 `retry_after_ms`，等待后只恢复原 `invocation_id`；长于自动等待预算时返回 `agent_client_wait.state=rate_limited`，保留等待时间和原调用。手动过早恢复也不向中枢反复请求。原权限、审批、取消和授权目标约束继续生效；旧 Core 不返回提示时仍沿原恢复流程。
+
+当前列表工具的源错误可能经过通用分类变成 unknown_failure；宿主应保留自己检查到的 storage_error/recovery_gap，不能将其描述为空目录。上传工具仍返回逐项错误。不要用新业务调用或重新上传已经 ready 的附件掩盖这些问题。

package/docs/GETTING_STARTED.md

@@ -1,8 +1,10 @@
-# Get started with 0.4.0
+# Get started with 0.6.0
 
 This guide is for users whose business system is already connected to BailingHub. Your
-administrator must prepare Core 0.6.1, a public Client App ID, a workspace, and the business
-browser-authorization entry first. You do not need to change business capability declarations.
+administrator must prepare Core 0.8.0, a public Client App ID, a workspace, and the business
+browser-authorization entry first. For multiple systems, prepare one independently authorized
+connection per target on the same Hub and audit domain. Existing business capability declarations
+remain valid; each requested action must already be exposed by its own system.
 
 ## 1. Install and configure
 
@@ -10,10 +12,10 @@ Use Node.js `22.19.0+` or `24+` and the compatible DSH version:
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.4.0
+dsh plugin --profile web add dsh-bailinghub@0.6.0
 ```
 
-The plugin installs SDK 0.4.0 automatically. Enter the four public values in DSH plugin settings,
+The plugin installs SDK 0.6.0 automatically. Enter the four public values in DSH plugin settings,
 or use their environment names. The example values below are placeholders:
 
 ```bash
@@ -41,7 +43,10 @@ In DSH, authorize the first account:
 
 The browser opens the original business authorization page. Sign in or switch accounts there,
 select the intended store/tenant when asked, and check the actual identity before approving.
-The business page determines the identity; the local label `Store A` does not.
+The business page determines the identity; the local label `Store A` does not. A compatible
+backend supplies the approved subject name automatically. The current display name is separate
+from its fixed key and the system description; missing names remain explicit. Duplicate names
+or renames do not recreate authorization or change old conversation records.
 
 For another account in the **same system and workspace**, register a clearly named connection,
 using the same three administrator-provided values, then authorize it separately:
@@ -59,24 +64,45 @@ an available alias. Names such as `default-2` do not prove which store was autho
 mapping before use. If login reports cleanup required, the new connection is already authorized;
 inspect and remove the reported old entry rather than authorizing again.
 
+To add a **different system**, use its administrator-provided Client App and workspace on the
+same Hub, then authorize it independently. For example, an inventory target may use:
+
+```text
+/bailinghub connections add "Inventory" https://hub.example.com inventory-client inventory_assistant
+/bailinghub login
+/bailinghub connections list
+```
+
+These are placeholders, not values to guess from a product name. Each selected target needs its
+own original Agent Session. Keep the existing Store B connection if using the same-system flow.
+
 ## 3. Choose this conversation's business scope
 
 Start a **new conversation before sending any message**, then run:
 
 ```text
 /bailinghub connections list
-/bailinghub scope set <store-a-connection-key> <store-b-connection-key>
+/bailinghub scope set <shop-connection-key> <inventory-connection-key>
 /bailinghub scope
 ```
 
 Copy the fixed connection keys from the list; the scope command does not accept names. Select
-one key for one account, or several for the same Hub/Client App/workspace. Wait for the successful
-confirmation before sending. For example, when the reporting capability is available:
+one key for one account, several for the same system, or several systems on one Hub and audit
+domain. Wait for successful confirmation. With the required inventory/shop capabilities and a
+confirmed product mapping, you can ask:
 
 ```text
-Compare today's sales at Store A and Store B. Show each store separately.
+Check tumbler stock. If any are available, change the corresponding shop product to 59 and list it.
+Otherwise leave it unlisted.
 ```
 
+The system description can explain online selling versus inventory before tool search. “Not loaded”
+means tools have not been queried, not that none exist. A stock read does not reserve or synchronize
+stock. Check price and listing outcomes separately, including any pending approval.
+
+For the retained same-system flow, select Store A and Store B instead and compare their sales
+when reporting tools are available. A system that was not used must not be marked as executed.
+
 The Agent chooses which selected authorization to use for each call. The system still decides
 which data and actions that authorization permits. Test a read first, then a reversible permitted
 update in a development workspace. Approval-required work follows the original approval flow.
@@ -89,7 +115,7 @@ connection does not change a conversation's scope.
 ## 4. Check results and the visible conversation
 
 Check the actual business result and its original invocation trail in BailingHub. With the matching
-Core 0.6.1, you can also follow visible user/assistant messages, turns, and the linked runs as one
+Core 0.8.0, you can also follow visible user/assistant messages, turns, and the linked runs as one
 conversation record. Multi-authorization runs keep their own call summaries separately.
 
 ```text

package/docs/GETTING_STARTED.zh-CN.md

@@ -1,7 +1,8 @@
-# 开始使用 0.4.0
+# 开始使用 0.6.0
 
-这份指南面向业务系统已经接入 BailingHub 的用户。管理员需要先准备 Core 0.6.1、公开的 Client
-App ID、workspace 和浏览器业务授权入口；已有业务能力无需为多账号重新声明。
+这份指南面向业务系统已经接入 BailingHub 的用户。管理员需要先准备 Core 0.8.0、公开的 Client
+App ID、workspace 和浏览器业务授权入口。多系统时，每个目标分别授权，且属于同一中枢、同一
+审计域；已有能力无需重新声明，但每项动作必须已由相应业务系统开放。
 
 ## 第一步：安装与配置
 
@@ -9,10 +10,10 @@ App ID、workspace 和浏览器业务授权入口；已有业务能力无需为
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.4.0
+dsh plugin --profile web add dsh-bailinghub@0.6.0
 ```
 
-插件会自动安装 SDK 0.4.0。通过插件设置填写四项公开信息，或使用对应环境变量。下面都是
+插件会自动安装 SDK 0.6.0。通过插件设置填写四项公开信息，或使用对应环境变量。下面都是
 占位值，需要替换成管理员提供的中枢地址、Client App ID 和 workspace：
 
 ```bash
@@ -38,7 +39,9 @@ dsh web
 ```
 
 浏览器会打开原业务授权页面。在那里登录、切换账号，并按业务系统要求选择门店或租户；同意前
-核对实际业务身份。可信身份由业务授权页面决定，本机名称 `A 店` 不证明身份。
+核对实际业务身份。可信身份由业务授权页面决定，本机名称 `A 店` 不证明身份。配套后端可自动
+提供授权主体名称，它与固定连接键、系统用途说明独立；缺名会明确提示。同名或改名不重建授权，
+也不更改原会话记录。
 
 如需使用**同一系统、同一 workspace** 的 B 店，用同样的三项公开信息创建清晰命名的新连接，
 再分别授权：
@@ -54,24 +57,41 @@ dsh web
 `default-2` 之类的名称不能证明是哪家店，使用前应核对对应关系。若登录提示需要清理，新连接
 已经授权成功；请检查并删除提示的旧条目，不要重复授权。
 
+要接入**另一个系统**，使用管理员提供的该系统 Client App 与 workspace，并在同一中枢上
+独立授权。例如库存目标可以使用以下占位配置：
+
+```text
+/bailinghub connections add "库存系统" https://hub.example.com inventory-client inventory_assistant
+/bailinghub login
+/bailinghub connections list
+```
+
+这些配置不能从产品名称推测。每个选中目标都需要独立原 Agent Session；同系统流程中已有的
+B 店连接可以继续保留。
+
 ## 第三步：选择本次会话的业务范围
 
 **新建会话，在发送任何消息前**执行：
 
 ```text
 /bailinghub connections list
-/bailinghub scope set <A店连接键> <B店连接键>
+/bailinghub scope set <商城连接键> <库存连接键>
 /bailinghub scope
 ```
 
-从列表复制固定连接键替换占位符，不能直接填写连接名称。只操作一家店就选一个键；多份授权
-必须属于相同中枢、Client App 和 workspace。等待设置成功回显后，再发送请求。例如，业务系统
-已开放报表能力时可以说：
+从列表复制固定连接键替换占位符，不能直接填写名称。可以选单份授权、同系统多份授权，或
+同一中枢、同一审计域的多个系统。等设置成功回显后再发请求。相应能力已开放、商品关系已确认时：
 
 ```text
-对比今天 A 店和 B 店的营业情况，按门店分别说明。
+先查保温杯库存。有货就把商城对应商品的售价改为 59 元并上架；没货就先不要上架。
 ```
 
+系统说明可在首次查工具前解释“线上售卖”和“库存管理”的区别。“尚未加载”表示还没查询工具，
+不是没有能力。查库存不等于锁库存或自动同步；改价、上架及审批要分别核对结果。
+
+原同系统流程仍可选择 A 店和 B 店，在报表能力可用时对比营业情况。没有实际调用的系统不能
+被标为已执行。
+
 智能体自行选择每次调用使用哪份选中授权；实际数据和操作范围仍由业务权限决定。先验证一次
 查询，再在开发空间尝试一次可回滚且允许的修改。需要审批的操作继续沿用原规则。
 
@@ -81,7 +101,7 @@ dsh web
 
 ## 第四步：核对业务结果与沟通过程
 
-在业务后台核对最终结果，在 BailingHub 查看原调用轨迹。配合 Core 0.6.1，还能把可见用户消息、
+在业务后台核对最终结果，在 BailingHub 查看原调用轨迹。配合 Core 0.8.0，还能把可见用户消息、
 助手回复、轮次与相关执行记录放在同一份沟通记录里查看。多授权的各份执行记录仍分别保留自身
 调用摘要。
 

package/docs/INVOCATION_RECOVERY.md

@@ -0,0 +1,182 @@
+# Reopen a conversation and recover its original business actions
+
+Available in DSH 0.6.0 with SDK 0.6.0 and Core 0.8.0. Configure a durable invocation store and preserve original Session records.
+
+A shop listing may still await approval when a user closes the Agent. An inventory
+adjustment may have reached the server even though its response was lost. Reopening
+the same conversation must keep those actions attached to their original accounts
+and calls. It must not create a second listing or stock adjustment from remembered text.
+
+The plugin adds durable **invocation metadata**, separate from the visible conversation
+archive and attachment space. It retains the original fixed scope fingerprint/revision,
+connection key, Hub/client/workspace, Agent Session, authorization reference, run,
+invocation ID, tool name, declaration revision, host call ID and parameter digest.
+It also stores the last received state, receipt digest and retry deadline. It does not
+store credentials, raw tool arguments, receipt bodies or conversation text in this journal.
+Digests support association and change detection; they are not independent tamper-proof evidence.
+
+## What happens before and after reopening
+
+1. Before a new business request leaves the host, save its original binding using
+   compare-and-swap (CAS). If that cannot be confirmed, do not send the request.
+2. After a response, save only its state and digest. A failed save remains
+   `storage_error` with an unsaved record. A successful business response does not
+   erase the local recovery-storage error.
+3. Reopen the real DSH Session with its original persisted events and scope. Reuse
+   its invocation store. Do not create a replacement Session or replay user messages.
+4. Inspect or restore local invocation metadata. This does **not** create business
+   runs, invoke/resume business actions, or restore old dynamic tools.
+5. When the user or Agent explicitly requests recovery, call
+   `resume_governed_tool_invocation` with only the original `invocation_id`. The plugin
+   verifies every original scope member and uses that call's original target. It sends
+   `resume` with the original ID and an empty payload, never a replacement `invoke`.
+
+`resume` is **not a read-only status operation**: Core may continue an approved or
+otherwise resumable original operation. Unknown dispatched writes remain subject to
+Core's existing reconciliation and approval rules. Reopening alone does not do this.
+This feature does not automatically continue a whole task, DAG or sequence of actions.
+When the user starts a new recovery turn, the existing runtime may create a current-turn
+run for the original selected target to keep the new conversation/audit association.
+That run never replaces the recovered call's original run or invocation. The startup and
+local status/restore stage creates no such run.
+
+A local last-known state is not current server proof (`result_verified: false`). After
+full reopening, recovery obtains the original server receipt even if local metadata says
+`executed`. Within a living host, its original confirmed response may be reused. A
+cancelled or ended turn can retain late original receipts without re-enabling its tools.
+
+## Host integration
+
+The default plugin uses its protected `invocation-records` directory under the DSH
+plugin data directory. A host supplying a custom `scopeStore` must **explicitly** supply
+an `invocationStore`; omission preserves existing business behavior but does not support
+durable recovery after a full restart. `null` also explicitly disables the new store.
+
+```js
+import { createAgentClientPlugin, createFileInvocationStore } from 'dsh-bailinghub'
+
+const plugin = createAgentClientPlugin({
+  scopeStore: hostScopeStore,
+  archiveStore: hostArchiveStore,
+  invocationStore: createFileInvocationStore({ directory: hostInvocationDirectory }),
+})
+```
+
+Place `hostInvocationDirectory` in the same durable, access-controlled host data area as
+the original Session scope. Never derive it from model input. An explicit memory store
+is exported for tests; a new empty memory store is not persistence after process restart.
+
+Custom adapters implement the same asynchronous interface:
+
+```js
+await store.load(sessionId) // null or the complete metadata record
+await store.save(sessionId, nextRecord, expectedRevision) // return saved record
+```
+
+The current record schema is `bailing.agent-invocations.v2`; original v1 records
+without task bindings remain readable and do not acquire a task implicitly.
+Its top-level fields are `schema`,
+`sessionId`, `revision`, `entries`. Revisions start at 1; missing expects `null`. Save must
+atomically compare the previous revision, persist the full record, and acknowledge only
+after durable success. A load error must not return `null`. Custom stores must retain
+the strict metadata-only field restrictions and enforce the same 8 MiB record bound.
+
+In the standard DSH command interface, `/bailinghub invocations status` reads this
+status and `/bailinghub invocations restore` retries only the local metadata save.
+Neither command calls the business resume endpoint.
+
+The runtime exposes:
+
+| Interface | Effect |
+| --- | --- |
+| `getSessionInvocationStatus(sessionId)` | Verify original scope and read local journal status. |
+| `restoreSessionInvocations(sessionId)` | Verify scope and flush pending local metadata with original CAS identity. No business invocation or resume. |
+| `inspectSessionInvocation(realSession, invocationId, { signal }?)` | Read the original remote receipt without a model turn or new run. Does not continue an approved action. |
+| `resumeSessionInvocation(realSession, invocationId, { signal }?)` | Explicitly inspect, then continue an eligible original undispatched action at most once. Later observation is read-only. |
+
+The first two return `state`, `entries`, `unsavedRecords`, plus `revision`/`reason` when available.
+Each entry has `invocation_id`, `authorization_ref`, `tool`, `original_run_id`,
+`last_known_state`, `retry_at`, and `result_verified: false`. Treat tool names as data.
+Do not turn these entries into new calls or consider the task complete from this list.
+
+The two remote actions require the actual Session and return a
+`bailing.agent-session-invocation-action.v1` envelope. `ready` means the interface
+returned normally, not that the business action succeeded. `resume_dispatched`
+only reports whether the runtime submitted resume to the SDK, not whether the
+Hub received it or the business action ran; read the original receipt for
+business state. A missing result remains unconfirmed. Storage or coverage failures
+retain priority, and a failure after sending resume never proves no dispatch occurred.
+See the [idle-panel integration and failure contract](TASK_CONTROL.md).
+
+| State | Host action |
+| --- | --- |
+| `ready` | Metadata is readable and saved; explicit original-call recovery is available for known records. This is not a claim that every historical call has a journal record. It does not confirm Core connectivity or the business outcome. |
+| `inactive` | No selected business scope, or the conversation has not started. Ordinary chat makes no Hub request for this journal. |
+| `unsupported` | No invocation store. Existing same-host business/recovery behavior is retained. |
+| `blocked` | Original scope or invocation binding is unavailable/conflicting. Do not switch account or use a surviving subset. |
+| `storage_error` | Restore local persistence first. Keep unsaved records and the original call identity. |
+
+Keep conversation archive `storage_error`, `unsavedEvents` and `recovery_gap` visible
+independently. A `ready` invocation journal cannot make an incomplete transcript complete. If local
+metadata is unsaved while authorization is also blocked, preserve `storage_error` and
+`unsavedRecords` as the primary state, with `scope_state: blocked` and `scope_reason`;
+this does not enable business access or discard either failure.
+
+## Failure and compatibility rules
+
+- `invocation_store_unavailable` / `invocation_store_conflict`: category `storage_error`,
+  next action `restore_invocations`. Do not interpret `not_dispatched` on a failed
+  recovery attempt as evidence that the original business action never ran.
+- `invocation_binding_unavailable` / `invocation_binding_conflict`: inspect original
+  evidence. Never guess the binding from transcript text or accept model-supplied targets.
+- `invocation_store_unsupported`: the host has not enabled durable invocation storage.
+- An authoritative HTTP 404 with SDK `publicCode=invocation_not_found` stops the
+  current recovery poll immediately, even if an older receipt said `awaiting_approval`.
+  Both the native model tool and direct `runtime.resume` preserve the original ID in
+  `feedback`: `category=invocation_outcome_unknown`, `code=invocation_not_found`,
+  `next_action=inspect_original`, `retryable=false`, `original_outcome=unverified`.
+  Dispatch remains `attempted` or `unknown`; the original business outcome is not
+  declared unexecuted. The local journal, scope and original run are retained.
+  Inspect that call's original evidence instead of retrying automatically or
+  reconstructing a new write. The existing feedback schema and host APIs are unchanged.
+- An arbitrary 404, a message containing that name, a missing public code or a
+  conflicting status is not authoritative not-found evidence. Older SDKs and custom
+  transports keep conservative bounded recovery for unconfirmed requests. A timeout
+  or temporary network failure does not become a missing-record diagnosis.
+- Existing SDK/Core network, authorization, unsupported and reconciliation feedback
+  continues unchanged. No new Core endpoint, SDK method, database migration or business
+  backend capability declaration is required for this feature.
+
+Whole-scope revalidation includes single-system multiple accounts. Temporary offline
+checks stay closed but can recover in the same runtime. A confirmed revoked or rebound
+member blocks the complete original group. Existing cross-Hub restrictions remain.
+
+Concurrent writers cannot overwrite a different stored outcome with a stale receipt.
+On a conflict, preserve both the stored record and unsaved local status for inspection.
+Do not clear an unsaved record simply to make the screen green. File-store locks are
+not automatically treated as stale: after an abnormal host exit while saving, an
+operator must establish that no writer remains, preserve the record/lock evidence and
+resolve storage ownership before retrying. Do not instruct a model to delete locks.
+
+The journal closes the host-side identity gap, not every crash gap. If the host saved
+its dispatch fence but crashed before the request reached Core, an explicit resume can
+return `invocation_not_found`. That response does not authorize automatic reconstruction
+or resubmission. Missing/deleted records from older installations cannot be backfilled
+from conversation prose. Old sessions without a journal remain explicitly unsupported
+or unavailable; new calls begin producing records once the host enables the store.
+
+## Acceptance expectations
+
+Use synthetic shop/inventory data and real persisted DSH Session events. Cover pending
+approval and lost responses across complete host reconstruction; unchanged original
+invocation ID, authorization and run; zero duplicate `invoke`; no automatic startup
+resume; all-member revalidation; offline recovery; pre/post-dispatch storage failures;
+CAS conflicts and lost save acknowledgements; cancellation before delayed save returns;
+and empty scope with zero Hub requests. Preserve the existing long-task tool retention,
+declaration-change, archive and attachment regressions.
+
+For missing-record regressions, use the real SDK and Core's error response shape
+`{"error":"invocation_not_found","message":"..."}` with HTTP 404. Test both recovery
+paths for pending approval and unknown outcomes. Require accurate final model/host
+feedback and no replacement `invoke`, rediscovery, changed target or journal revision.
+A test that only reproduces the old generic error is not a passing recovery test.