# dsh-Kingdom 2.0 使用指南

这是运行于 DSH 的个人 Agent 工作台。任务规划、角色分工、执行、返工、主管审查、用量和人类管理窗口已连通。默认单执行者；协作须明确采纳，工具按需展示默认关闭。

## 支持组合与安装

本轮验证环境为 Windows、Node 24.11.1、DSH CLI 0.1.5-rc.1；Session/Agent/Tools/Commands/PiAI/token-meter 主要组件实际为0.1.5-rc.2、Cordis4.0.2。包声明Node≥22.19，但本轮没有逐个验证所有Node/操作系统组合。

2.0 支持经过验证的 DSH `0.1.5-rc` 组件组合；较旧宿主请继续使用对应旧版 Kingdom。使用官方 DSH 的同一套依赖，避免在插件目录再装一份不同版本的 DSH Core。包包含编译插件、内置 GUI、12 个角色 SVG、bundle 补丁与本指南，不需要另起前端服务。

已有可用 `web` profile 时，安装准确版本：

```shell
dsh plugin --profile web add dsh-kingdom@2.0.0 --registry=https://registry.npmjs.org
```

也可从 [GitHub Release](https://github.com/lusblead/dsh-Kingdom/releases/tag/v2.0.0) 下载 tgz，核对随附校验清单后安装：

```shell
dsh plugin --profile web add ./dsh-kingdom-2.0.0.tgz
```

若要先隔离试用，在新的终端给 DSH 选择一个新的目录，再按所用官方模板建立 profile；不要指向已有正式数据目录。例如：

```powershell
$env:DSH_HOME = Join-Path $env:LOCALAPPDATA 'KingdomTrial'
```

选择自己的全新目录，不覆盖已有 `KingdomTrial`。按官方模板建立并配置 `web` profile 后再安装插件，启动时沿用同一个 `DSH_HOME` 和 profile。仅安装插件不会自动配好模型或绑定角色。模型 Provider 配置由 DSH 管理，必须使用真实可用的模型路线；“模型已配置”不等于执行成功。

## 第一次使用

1. 在可信的本机直接命令入口运行 `/kingdom init`。若希望通过网页填写初始化内容，可直接输入下面的单次管理命令；两种初始化方式任选一种。Owner 是人类操作者，不是 Agent 角色或会话。
2. 准备独立的宰相与主管DSH会话，建立角色绑定、领地及主理主管，给执行者选择模型配置。每个执行者保留一个长期会话，同一会话不跨领地。
3. 打开 `/kingdom gui` 查看今日工作台、任务、待我处理、地图、用量与设置。普通进度无需人类逐条处理；主管审查和人类管理事项分开显示。
4. 常用人类管理动作在 `/kingdom owner.gui` 创建的独立短时窗口进行，先逐字段预览再提交。窗口只包含当次明确动作与资源范围，至多10分钟；到期需重新从直接入口激活。管理窗口不能代替主管ACCEPT。

空库首次初始化的网页命令（初始化后不能重复使用）：

```text
/kingdom owner.gui {"kingdomId":null,"actions":["init"],"scope":{"kingdomWide":false,"territoryIds":[],"bindingIds":[],"roleTypes":[],"targetSessionIds":[],"workspaceRoots":[]},"ttlMs":600000}
```

日常窗口的 `owner.gui` 参数是 `{kingdomId,actions,scope,ttlMs}`；scope 包含 `kingdomWide/territoryIds/bindingIds/roleTypes/targetSessionIds/workspaceRoots`。使用 `/kingdom status` 和 `/kingdom help` 核对真实王国、角色和命令，只填写本次需要的范围。窗口到期或打开失败后重新从直接入口激活，不能把干净的 `/owner` 或 `/console` 地址当作含一次性授权的启动链接。不要分享带启动票据的地址。

普通工作台和人类管理窗口分别持有短时控制状态：人类管理窗口不能代替宰相建任务或主管 ACCEPT；切换角色时从对应真实 DSH 会话重新执行 `/kingdom gui`。若按钮不可用，先查看其原因，核对当前会话、领地及绑定。模型不能通过转述“用户同意”激活人类窗口。

## 日常任务与协作

从一句目标建立可编辑草稿，明确范围和验收；宰相创建任务，主管指派并授予当次能力，执行者产生Claim。主管可ACCEPT、REWORK或FAIL。执行结束、主管接受、人类验收是不同状态；返工保留原验收与上一轮理由。

小任务使用单执行者。适合拆分时，宰相提出一份有理由、成员、依赖、范围、产物与整合人的计划；人类准确采纳后，主管有界推进。首版至多两个子项及一个主整合者，专家强制只读。独立目录可并行，同一目录读共享、写独占；不能并行写同一工作区时先等待结算，再串行推进。

子项被接受后，主整合者还要完成父任务并单独审查。成员多数同意不能代替验证；计划和摘要不能授予权限。失败收缩为串行只停止新增并行，不粗暴中止已有执行。

## 用量与异常

用量页区分Provider实报、预留估计、在途、未确认、共享/未归属与恢复中。没有可信价格表时金额显示未知，不能把估计当账单。计划的协调费用标为同期王国成本保守上界；软预算只限制新增，已在途仍可能继续产生费用。

等待超时不等于失败。已有Dispatch、丢响应、迟到结果或清理不明时，先由当前合法主管对账原执行，不能重发来试运气。原进程证据完整的迟到结果可对账；重启后旧内存凭据不能恢复，证据不足保持RECOVERING/资源占用，界面说明可确认事实及缺口。尚不承诺任意运行状态都能一键暂停、恢复或中止。

## 升级、备份和回退

先停止新增任务并核对所有活动/恢复执行，再对源库做SQLite一致备份；WAL模式下不能只复制主 `.db` 文件。保留原版本、配置及备份，在全新目录恢复副本并核验完整性、外键、Task/结果/事件和未结算占用，之后才考虑正式切换。

已有v3库默认不自动迁移v4；新库自动具备v4，旧库只有在准确迁移授权和副本验证后才显式启用迁移。1.4/1.5在现有事件账本增加事实，不清洗历史结果。恢复备份不会恢复旧Owner窗口或不透明运行凭据。

尚未写入新事实时，可以在隔离目录恢复旧程序与旧备份。写入新计划/预算/资源事实后，不能盲目用旧程序打开新库；旧程序不懂这些约束。出现问题先保留新库和日志，在新路径恢复最近一致副本，不覆盖原始数据、不伪造已运行工作被撤销。

## 当前限制

本地隔离脚本验证证明的是接线与异常约束。没有完成真实付费 Provider 的质量/缓存/成本成对实验，也没有测出真人主动操作时间减少约 30% 或任务 Token 费用下降 20%。因此不宣称收益达标，不自动打开工具展示或协作。记忆、跨任务召回、自动会话续接、大规模扩队、云端多租户及自动主管 ACCEPT 不在本版内。

安装、恢复、修复和最终包的实测范围见 [2.0 版本说明](V2.0-RELEASE-NOTES.md)。公开版本及下载以 [Releases](https://github.com/lusblead/dsh-Kingdom/releases) 和 [官方 npm](https://www.npmjs.com/package/dsh-kingdom) 为准；发布不替代正式数据迁移或真人使用验收。