# dsh-Kingdom 3.1.0 本地候选说明

> 本文是 3.1.0 的历史记录，描述的是当时的语法与行为。**3.2.0 起主管的 `role.bind` 必须同时给出
> `territory_id`**（席位与领地主理同一事务原子写入），本文第 48 行附近的示例已不适用于 3.2.0；
> 请以 [3.2 版本说明](V3.2-RELEASE-NOTES.md) 为准。

3.1.0 只有两处产品变更：**DSH peer 兼容范围** 与 **无 live Agent 会话的席位绑定**。
schema、事件账本、GUI 与治理语义均未改动——沿用 schema v4 与既有事件类型，没有新增表、
没有新增迁移。

## 验证状态（本轮实际执行过的）

| 项 | 结果 |
|---|---|
| `npm run typecheck`（`tsc -p tsconfig.json --noEmit`） | 通过，0 错误 |
| 全量 `node --test tests/*.test.ts` | 586 项：**584 通过 / 0 失败 / 2 跳过**（2 项为 Unix-only 用例） |
| 定向用例 `tests/index-owner-binding-integration.test.ts` | 8/8 通过（含 2 个 v3.1 新增用例） |
| peer 谓词复算（运行时自带 `semver@7.8.5`） | `0.1.5-rc.2` ✓、`0.1.7-rc.2` ✓；`0.1.6-*` 与 `0.1.8+` 刻意不含 |
| peer 预检复算（用 DSH 0.1.7-rc.2 自带的 `evaluatePluginCompatibility`，`includePrerelease: true`） | `0.1.7-rc.2` → 不跳过；父提交声明 → 4 条 peer 全部不兼容（会被整层跳过） |
| 发布门 `pwsh -File scripts/release.ps1 -Version 3.1.0 -DryRun` | P0–P3 全 PASS |
| 本机 profile 重装 3.1.0（2026-09-28 11:43） | 完成：profile 依赖指向 `dsh-kingdom-3.1.0.tgz`，已装 `version=3.1.0`，`lib/index.js` 与候选构建同哈希 |
| DSH `0.1.7-rc.2` 实机加载回归（2026-09-28 11:48 起） | 完成：宿主命令行指向 `dsh-0.1.7-rc.2`，`skipping profile bundle` 与 `disabling profile plugin` 均 **0 行** |
| 无 live Agent 会话的真机验证 | 完成：`ROLE_BOUND` 事件记 `session_evidence=DURABLE_SESSION`（无 live Agent 的会话被接受）；不存在的 session id 仍被 `SESSION_ABSENT` 拒绝且零写入 |

**未执行（NOT_RUN）**：真实浏览器人工交互验收；DSH 0.1.7 下**全部 14 条 bundle 的真实 boot**（只做了
`--dump-config` dry-run 与行级门禁的离线复算）；其它第三方插件在 0.1.7 下的业务功能正确性；Linux 平台；
收益与成本测量。未运行过的项不得当作已通过。本版发布前的独立审查结论与 Owner 验收记录见发布回执（不在包内）。

## 1. DSH peer 兼容范围放宽

- 旧：`@deepseek-ai/dsh-commands` / `dsh-llm` / `dsh-tools` = `>=0.1.5-rc.1 <0.1.5`，
  `dsh-token-meter` = `>=0.1.5-rc.2 <0.1.5`。
- 新：两条版本线并列 `>=0.1.5-rc.1 <0.1.6-0 || >=0.1.7-0 <0.1.8-0`
  （`dsh-token-meter` 下界为 `0.1.5-rc.2`）。`package-lock.json` 的 peer 快照同步。
- **为什么必须分线写**：在 semver 的 prerelease 规则下，`>=0.1.5-rc.1 <0.2.0` 并**不包含**
  `0.1.7-rc.2`（只包含 0.1.5-rc 线与 0.1.8 稳定版）。分线写法是唯一能同时表达"已验证的
  0.1.5-rc 线"与"目标 0.1.7 线"且不误收未测版本的形式。
- **为什么必须改**：DSH `0.1.7-rc.2` 的 `@deepseek-ai/dsh-app-boot` 新增插件兼容性预检
  （`evaluatePluginCompatibility`，`lib/index.js:286-313`）。它只检查 `@deepseek-ai/dsh` 与
  `@deepseek-ai/dsh-*`，判据是 `semver.satisfies(runtime, range, { includePrerelease: true })`；
  `loadProfileDirectory`（`:919-955`）对 `dsh.profile.bundles` 中每个 bundle 判定，不通过且未豁免
  即抛出 → 收进 `skippedBundles` → **该 bundle 整层不加载**。症状是启动不报错，只在 stderr 留
  一行 skip 警告，而工具、`/kingdom` 命令与 GUI 会一起消失。
- **只改声明不够**：预检读取的是**已安装副本**的 `package.json`。必须重新打包并重装该 profile，
  否则升级后仍然是旧的 `<0.1.5` 声明。
- 未改 `@deepseek-ai/cordis`（`>=4.0.0-rc <5`）与 `@deepseek-ai/schemastery`（`^3.18.0`）：它们
  不在预检集合内，且 0.1.7-rc.2 携带的 4.0.4 / 3.18.4 均落在范围内。

## 2. 无 live Agent 的会话现在可以绑定席位

- **症状**：对一个刚创建、尚未产生任何消息的会话执行
  `/kingdom role.bind {"role_type":"SUPERVISOR",…,"session_id":"…"}` 会得到
  `INPUT_DENIED [SESSION_ABSENT]`，于是无法预先设置主管席位。
- **原因**：目标会话校验只接受 live Agent（`agents.get(session_id)` 返回同一条 Agent，且状态为
  `idle` 或 `running`）。DSH 的 Agent 一旦被回收就会移出注册表（`AgentStatus` 本身只有
  `idle | running`，disposal 不是第三种状态），此后该 session_id 再也过不了校验。
- **现行为**（`resolveDirectTargetSession`）：
  1. live Agent 命中 → 放行，事件记 `session_evidence: "LIVE_AGENT"`；
  2. 仅当分类为 `ABSENT`（注册表里没有这条 live Agent）时，回退到"该 session_id 已在本机 DSH
     持久会话存储中登记"的存在性证明（`ctx.sessionQuery.observeSession`，只用 header 做身份比对，
     观察租约用完即释放）→ 放行，事件记 `session_evidence: "DURABLE_SESSION"`；
  3. 两条路都证明不了 → 仍然拒绝，**零写入**。
- **没有放宽的部分**：`FOREIGN` / `MULTIPLE` / `EXPIRED` / `UNKNOWN` 一律保持 fail-closed，不因
  "可能是它"而放行；调用者身份校验（`resolveTrustedToolSession`）未改动，仍要求 live Agent；
  宿主未挂载 `sessionQuery` 时退化为原行为（拒绝并说明缺少观察通道）。Owner 管理窗口的目标会话
  校验与列表使用同一解析器，行为一致。
- **语义边界**：`DURABLE_SESSION` 只说明"这条会话属于本机 DSH"，**不说明它当前可执行**。席位在
  该会话真正启动前不能派发或复核；这条证据强度差异会记进 `ROLE_BOUND` /
  `BINDING_PROFILE_UPDATED` 事件的 `session_evidence` 字段，供审计区分。

## 3. 与本机现状的关系

本文件描述 3.1.0 候选。截至 2026-09-28：本机 `web` profile 已于 11:43 重装为 `dsh-kingdom-3.1.0`
（依赖指向 `dsh-kingdom-3.1.0.tgz`），运行宿主自 11:48 起为 DSH `0.1.7-rc.2`，且未出现任何 bundle 跳过。
回退路径：保留的 `dsh-kingdom-3.0.0.tgz`、profile 三件套备份、会话与 storages 全量副本、王国库一致性
副本，以及 `rollback-to-015.ps1`。