dsh-kingdom 0.3.1

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, lusblead
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,184 @@
+<div align="center">
+
+# 🏰 dsh-Kingdom
+
+**在 DeepSeek Harness 里，装一个插件，拥有一个自己的 Agent 王国。**
+
+[![Version](https://img.shields.io/badge/version-0.3.1-blue)](https://github.com/lusblead/dsh-Kingdom/releases)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-green)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-0.1.0--rc.5-orange)](#compatibility)
+[![Node](https://img.shields.io/badge/Node-%3E%3D22.19-339933)](#requirements)
+
+</div>
+
+---
+
+## 这是什么？
+
+**dsh-Kingdom 是一个 DeepSeek Harness（DSH）插件**：安装后，你不需要部署任何服务、数据库或 GUI，直接在 DSH 会话里用自然语言就能**创建并运行一个属于自己的最小王国**——
+
+```text
+你：初始化王国
+DSH：已创建王国「My Kingdom」，你成为 Owner
+
+你：给当前项目建一个 RAG 研发领
+DSH：已创建领地「RAG 研发领」
+
+你：让 Chancellor 把"检查测试情况"规划成任务，Supervisor 派给 Worker 执行，然后验收
+DSH：任务 CREATED → ASSIGNED → RUNNING → REVIEW → DONE ✅
+```
+
+**王国是真实的**：角色、领地、任务、验收记录全部持久化在本地，重启 DSH 也不会消失。
+
+---
+
+## ✨ 核心特性
+
+| 特性 | 说明 |
+|---|---|
+| 🚀 **零门槛安装** | 一个 tgz + 一条命令，无需 bash / tsc / 外部服务 / GUI |
+| 🏛 **完整角色体系** | Owner / Chancellor / Supervisor / Worker，角色与 Session / 模型解耦 |
+| 📋 **真实治理闭环** | 规划 → 分配 → 独立执行 → 验收，任务状态全程留痕 |
+| ⚖️ **Claim ≠ Fact** | **Worker 说自己完成了 ≠ 任务完成**——完成权只在 Supervisor，代码强制，不是口头约定 |
+| 👷 **Worker 独立执行** | 每次执行在独立 DSH 会话（one-shot subagent）进行，结果结构化返回 |
+| 🔁 **返工留痕** | REWORK 后同一 Worker 新会话重做，每次尝试（attempt）都有记录 |
+| 💾 **重启恢复** | 全部状态存本地 SQLite，关掉 DSH 再开，王国原样还在 |
+| 🎭 **GUI 就绪**（可选） | 结构化快照 + 本地通道（默认关闭），为可视化界面预留接口 |
+
+---
+
+## 🚀 快速开始
+
+### 1. 前置要求
+
+- **DeepSeek Harness（dsh）** ≥ `0.1.0-rc.5`
+- **Node.js** ≥ `22.19`（内置 SQLite，插件零原生依赖）
+- 一个可用的模型 API key（Worker 执行需要）
+
+### 2. 安装
+
+**方式 A：npm（推荐）**
+
+```bash
+dsh plugin --profile web add dsh-kingdom
+```
+
+**方式 B：从 GitHub Releases 下载 tgz**
+
+从 [Releases](https://github.com/lusblead/dsh-Kingdom/releases) 下载 `dsh-kingdom-0.3.1.tgz`，然后：
+
+```bash
+dsh plugin --profile web add ./dsh-kingdom-0.3.1.tgz
+```
+
+> 安装时会打印 5 条 peer dependency warning——**这是预期的**（这些包由 DSH 运行时提供），不是失败。
+> 判断安装成功：**重启 DSH 后** `/kingdom status` 能返回真实状态。
+
+重启 DSH，插件自动加载。开始使用：
+
+```bash
+/kingdom init      # 初始化或接入本地王国（幂等）
+/kingdom status    # 查看王国真实状态
+```
+
+### 3. 30 秒体验一个王国
+
+```
+你：初始化王国
+你：给当前项目创建一个 RAG 研发领
+你：任命一个 Chancellor 和 Supervisor，绑定一个 Worker
+你：让 Chancellor 规划"检查测试情况"为任务，Supervisor 派给 Worker
+你：开始执行任务
+你：验收任务（ACCEPT / REWORK / FAIL）
+你：王国现在什么情况？
+```
+
+每一步都用自然语言，模型自动调用对应的 `kingdom_*` 工具完成真实写入。
+
+---
+
+## 🛠 工具一览
+
+| 阶段 | 工具 |
+|---|---|
+| 王国基础 | `kingdom_init` · `kingdom_status` |
+| 领地 | `kingdom_create_territory` · `kingdom_list_territories` |
+| 角色 | `kingdom_bind_role` · `kingdom_list_bindings` |
+| 任务治理 | `kingdom_plan_task` · `kingdom_assign_task` · `kingdom_start_task` · `kingdom_review_task` · `kingdom_list_tasks` |
+| 执行控制 | `kingdom_execution_control` |
+| GUI（可选） | `kingdom_snapshot` · `kingdom_task_detail` |
+
+---
+
+## 🧠 它如何保证"治理是真的"？
+
+这是 dsh-Kingdom 与其他 Agent 编排工具最根本的区别：
+
+```text
+Worker 交回结果 ──→ 这是一条 Claim（自述），只进 REVIEW
+                        ↓
+               Supervisor ACCEPT ──→ DONE（组织事实）
+               Supervisor REWORK ──→ 返工（同 Worker 新会话）
+               Supervisor FAIL   ──→ FAILED（组织事实）
+```
+
+- **Worker 没有"完成"的权力**：它没有上报结果的工具，结果经宿主接收后落库，任务永远停在 `REVIEW`。
+- **没有任何工具能把任务直接置为 DONE**——DONE 唯一入口是 Supervisor 的 ACCEPT。
+- **即使是 Worker 自称失败**，任务也只到 REVIEW；FAILED 只能是 Supervisor 裁定，或宿主观察到执行器客观失败（启动失败/异常退出）。
+- 每次执行（attempt）都记入 `worker_results`，返工历史完整可查。
+
+> **一句话：模型可以提出动作，但只有程序决定状态。**
+
+---
+
+## 📁 数据与存储
+
+| 路径 | 说明 |
+|---|---|
+| `~/.dsh/kingdom/kingdom.db` | 王国全部数据（SQLite，自包含） |
+| 7 张表 | kingdoms · territories · role_bindings · tasks · worker_results · executions · events |
+
+每一版升级都是**零 migration**——旧库打开即自动收敛，数据不丢。
+
+---
+
+## 🗺 路线图
+
+| 版本 | 内容 | 状态 |
+|---|---|---|
+| 0.1.x | 王国基础：初始化/领地/角色绑定/重启恢复 | ✅ 已发布 |
+| 0.2.x | 任务治理闭环：plan/assign/execute/review + **Claim ≠ Fact** | ✅ 已发布 |
+| 0.3.x | 执行生命周期 + GUI 适配层 + 热插拔加固 | ✅ 已发布 |
+| 未来 | 多 Worker、Handoff、GUI 正式版、完整治理后端 | 🚧 规划中 |
+
+---
+
+## 📖 文档
+
+- [LICENSE](LICENSE) — BSD-3-Clause
+
+## 🤝 参与贡献
+
+欢迎提交 Issue / PR。开发环境需要 DSH checkout：
+
+```bash
+DSH_CHECKOUT=<checkout> bash scripts/build.sh   # 或手动 tsc
+node scripts/p2-smoke.mjs                        # Phase 2 自测（81 断言）
+node scripts/p3-smoke.mjs                        # Phase 3 自测（113 断言）
+node scripts/hotplug-audit.mjs                   # 热插拔审计（27 断言）
+npm pack                                         # 产出可分发 tgz
+```
+
+## 📜 许可证
+
+[BSD-3-Clause](LICENSE) © 2026 lusblead
+
+---
+
+<div align="center">
+
+**Unofficial project, independently developed and maintained by community members.**
+
+*DSH · Agent Kingdom · Multi-agent governance*
+
+</div>

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-kingdom bundle patch：把本插件作为 profile bundle 层插入。
+# 安装（dsh plugin add dsh-kingdom）后自动进入 profile bundles，
+# 重启 DSH 自动加载，无需 dev_inject_plugin。
+- insert:
+    - id: dsh-kingdom
+      name: 'dsh-kingdom'

package/lib/core/binding.js

@@ -0,0 +1,57 @@
+/**
+ * dsh-kingdom — Role Binding 基础 CRUD（Phase 1）。
+ *
+ * Role、Runtime、Model、Session 解耦：
+ *   Role → Binding → DSH Session → Model/Tools
+ * Binding 可以更换 Session；Role 的组织身份不因模型或 Session 改变而改变。
+ *
+ * Phase 1 仅支持：绑定角色↔session（role_type 枚举 + role_name + session_id 可选）、
+ * 列出绑定。角色类型固定 OWNER/CHANCELLOR/SUPERVISOR/WORKER，不支持动态创建角色类型。
+ */
+import { randomUUID } from 'node:crypto';
+export const ROLE_TYPES = ['OWNER', 'CHANCELLOR', 'SUPERVISOR', 'WORKER'];
+export function bindRole(store, input) {
+    const roleType = input.roleType.trim().toUpperCase();
+    if (!ROLE_TYPES.includes(roleType)) {
+        return `错误：role_type 必须是 ${ROLE_TYPES.join(' / ')} 之一。`;
+    }
+    const roleName = input.roleName?.trim() || `${roleType}-${randomUUID().slice(0, 8)}`;
+    // 同角色已存在：Phase 1 同一角色只保留一个绑定（重复绑定返回既有，不改）
+    const existing = store.getBindingByRole(input.kingdomId, roleType);
+    if (existing) {
+        return `角色 ${roleType} 已有绑定（${existing.role_name}，session=${existing.session_id ?? '未绑定 session'}）。如需更换 session，先解绑或未来版本支持。`;
+    }
+    const now = new Date().toISOString();
+    store.insertBinding({
+        binding_id: randomUUID(),
+        kingdom_id: input.kingdomId,
+        role_type: roleType,
+        role_name: roleName,
+        runtime_type: 'dsh',
+        session_id: input.sessionId?.trim() || null,
+        principal_id: null,
+        created_at: now,
+        updated_at: now,
+    });
+    store.appendEvent({
+        event_id: randomUUID(),
+        kingdom_id: input.kingdomId,
+        event_type: 'ROLE_BOUND',
+        actor_role: roleType,
+        actor_id: null,
+        target_type: 'binding',
+        target_id: null,
+        payload_json: JSON.stringify({ role_name: roleName, session_id: input.sessionId ?? null }),
+        created_at: now,
+    });
+    return `已绑定角色 ${roleType}（${roleName}${input.sessionId ? `，session=${input.sessionId}` : '，未指定 session'}）。`;
+}
+export function listBindings(store, kingdomId) {
+    const rows = store.listBindings(kingdomId);
+    if (rows.length === 0)
+        return '当前王国还没有角色绑定。';
+    return rows
+        .map((b) => `- ${b.role_type}（${b.role_name}，session=${b.session_id ?? '未绑定'}）`)
+        .join('\n');
+}
+//# sourceMappingURL=binding.js.map

package/lib/core/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../src/core/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAA;AAUlF,MAAM,UAAU,QAAQ,CAAC,KAAmB,EAAE,KAAoB;IAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACpD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAoB,CAAC,EAAE,CAAC;QAC/C,OAAO,oBAAoB,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAA;IACzD,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,QAAQ,IAAI,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;IAEpF,0CAA0C;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IAClE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,MAAM,QAAQ,SAAS,QAAQ,CAAC,SAAS,YAAY,QAAQ,CAAC,UAAU,IAAI,aAAa,4BAA4B,CAAA;IAC9H,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACpC,KAAK,CAAC,aAAa,CAAC;QAClB,UAAU,EAAE,UAAU,EAAE;QACxB,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,SAAS,EAAE,QAAQ;QACnB,SAAS,EAAE,QAAQ;QACnB,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,IAAI;QAC3C,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG;KAChB,CAAC,CAAA;IACF,KAAK,CAAC,WAAW,CAAC;QAChB,QAAQ,EAAE,UAAU,EAAE;QACtB,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,UAAU,EAAE,YAAY;QACxB,UAAU,EAAE,QAAQ;QACpB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,SAAS;QACtB,SAAS,EAAE,IAAI;QACf,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QAC1F,UAAU,EAAE,GAAG;KAChB,CAAC,CAAA;IACF,OAAO,SAAS,QAAQ,IAAI,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,CAAA;AAC7G,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAmB,EAAE,SAAiB;IACjE,MAAM,IAAI,GAAqB,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;IAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,cAAc,CAAA;IAC5C,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,CAAiB,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,UAAU,IAAI,KAAK,GAAG,CAAC;SAC/F,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}