dsh-kingdom 0.3.1

package/lib/worker/dsh-subagent.js

@@ -0,0 +1,117 @@
+/**
+ * dsh-kingdom — DshSubagentExecutor：用 dsh one-shot subagent 执行 Worker（裁决 2）。
+ *
+ * 裁决 2 冻结的形状：
+ * - Worker 用 `ctx.subagents.start(provider, { label, prompt, outputSchema })` **one-shot 独立执行**；
+ * - **不**采用常驻 `ctx.agents.create`；
+ * - 每次执行都是新的 execution/session（REWORK 也一样，裁决 5）；
+ * - Structured Worker Result 由 subagent 的 `outputSchema` 约束，
+ *   宿主（本类）接收后交给 Task Core 落 worker_results。
+ *
+ * 这也是为什么 `kingdom_report_result` **不是**独立工具：Worker 是 one-shot subagent，
+ * 它没有机会自己调工具改 Task 状态 —— 结果只能经宿主这一条路回来。
+ *
+ * ## 为什么这里对 ctx.subagents 用结构化局部类型
+ *
+ * 本插件是独立分发的 tgz，peer 只声明 5 条（见 README）。为了不新增第 6 条 peer、
+ * 也不让编译产物 .d.ts 泄漏 subagent 类型，这里按 dsh 已发布的接口**结构化**地
+ * 声明所需最小面，而不 import `@deepseek-ai/dsh-subagent`。
+ * 对应 checkout 定义（0.1.0/0.2.0 基线一致）：
+ * - `SubagentRuntime.start(name, request)` — packages/subagent/subagent/src/index.ts:414
+ * - `SubagentStartRequest{label,prompt,parent,signal,outputSchema}` — .../src/types.ts:100
+ * - `SubagentRun{id,result,dispose}` / `SubagentResult{output,structured,stopReason}` — .../src/types.ts:219,249
+ */
+import { buildWorkerPrompt, parseStructuredResult, WORKER_OUTPUT_SCHEMA, } from './executor.js';
+/**
+ * 判定 stopReason 是否算“正常跑完”。
+ * 非 completed 一律视为宿主观察到的运行失败（裁决 6），不去解释 Worker 想说什么。
+ */
+function stopReasonFailure(stopReason) {
+    switch (stopReason) {
+        case 'completed': return null;
+        case 'aborted': return 'subagent 执行被取消（aborted）';
+        case 'error': return 'subagent 执行失败（模型或传输层 error）';
+        case 'max-tokens': return 'subagent 未完成即触达 token 上限（max-tokens）';
+        case 'refusal': return 'subagent 拒绝了该任务（refusal）';
+        default: return `subagent 以异常终止原因结束（${stopReason}）`;
+    }
+}
+/**
+ * 薄封装：把一次 Worker 执行落到一个 one-shot subagent run 上。
+ *
+ * 失败一律收敛成 `executor-failure`，**从不抛异常给 Task Core**
+ * —— 让状态机只面对两种确定结局（result / executor-failure），
+ * 而不是异常与返回值两条并行的控制流。
+ */
+export class DshSubagentExecutor {
+    kind;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.kind = `dsh-subagent:${options.provider}`;
+    }
+    async execute(task, context) {
+        const { subagents, provider, parent, signal } = this.options;
+        if (subagents.getProvider(provider) === undefined) {
+            const available = subagents.list();
+            return {
+                kind: 'executor-failure',
+                sessionId: null,
+                reason: `未注册 subagent provider "${provider}"`
+                    + `（当前可用：${available.length > 0 ? available.join(' / ') : '无'}）`,
+            };
+        }
+        // 启动阶段失败没有 run，也就没有 session id 可记。
+        let run;
+        try {
+            run = await subagents.start(provider, {
+                label: `Worker: ${task.title}`.slice(0, 80),
+                prompt: [{ type: 'text', text: buildWorkerPrompt(context) }],
+                parent,
+                signal,
+                outputSchema: WORKER_OUTPUT_SCHEMA,
+            });
+        }
+        catch (error) {
+            return {
+                kind: 'executor-failure',
+                sessionId: null,
+                reason: `subagent 启动失败：${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        // 已发布的 run 必须 dispose 才能达到静默，即使结果路径抛错。
+        const sessionId = run.id;
+        try {
+            const result = await run.result;
+            const failure = stopReasonFailure(result.stopReason);
+            if (failure !== null)
+                return { kind: 'executor-failure', sessionId, reason: failure };
+            const structured = parseStructuredResult(result.structured);
+            if (structured === null) {
+                return {
+                    kind: 'executor-failure',
+                    sessionId,
+                    reason: 'subagent 正常结束但未交回合法的结构化结果（outputSchema 未满足）',
+                };
+            }
+            return { kind: 'result', result: structured, sessionId };
+        }
+        catch (error) {
+            // run.result 只在 seam 无法表达的基础设施故障时 reject。
+            return {
+                kind: 'executor-failure',
+                sessionId,
+                reason: `subagent 运行异常：${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        finally {
+            try {
+                await run.dispose();
+            }
+            catch {
+                // dispose 失败不改写已判定的执行结局；run 已经落定。
+            }
+        }
+    }
+}
+//# sourceMappingURL=dsh-subagent.js.map

package/lib/worker/dsh-subagent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh-subagent.js","sourceRoot":"","sources":["../../src/worker/dsh-subagent.ts"],"names":[],"mappings":"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"}

package/lib/worker/executor.js

@@ -0,0 +1,94 @@
+/**
+ * 约束 Worker 结构化输出的 JSON Schema。
+ *
+ * 必须落在 dsh 强制的 schema 子集内
+ * （见 checkout `packages/core/tools/src/json-schema.ts`）：
+ * - 根必须是 object（assertObjectJsonSchema）；
+ * - `enum` 只允许挂在**已声明 scalar `type`** 的节点上
+ *   —— 裸 `{ enum: [...] }` 会被判为 `.enum requires type or oneOf` 而拒绝，
+ *   所以 outcome 显式写了 `type: 'string'`。
+ */
+export const WORKER_OUTPUT_SCHEMA = {
+    type: 'object',
+    required: ['outcome', 'summary'],
+    properties: {
+        outcome: {
+            type: 'string',
+            enum: ['COMPLETED', 'FAILED', 'BLOCKED'],
+            description: 'COMPLETED=你认为已完成；FAILED=你认为做不成；BLOCKED=被外部阻塞。这是你的声明，最终由 Supervisor 裁定。',
+        },
+        summary: {
+            type: 'string',
+            description: '给 Supervisor 审查用的自述摘要：做了什么、结果如何、是否满足验收标准。',
+        },
+        artifacts: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '产出物列表（文件路径或制品标识）。',
+        },
+        risks: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '风险与遗留问题。',
+        },
+    },
+};
+/** 未知值兜底为 BLOCKED 之前，先判定是否是合法 outcome。 */
+function isOutcome(value) {
+    return value === 'COMPLETED' || value === 'FAILED' || value === 'BLOCKED';
+}
+/** 只保留字符串项的数组；非数组返回 undefined。 */
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const items = value.filter((v) => typeof v === 'string');
+    return items.length > 0 ? items : undefined;
+}
+/**
+ * 把 subagent 交回的 `structured` 收敛成 StructuredResult。
+ *
+ * provider 已按 outputSchema 校验过，这里是**宿主侧的第二道防御**：
+ * 形状不合法就返回 null，调用方据此判定 executor-failure（裁决 6）。
+ * 不猜、不补默认值 —— 一个形状不对的 Claim 不是 Claim。
+ */
+export function parseStructuredResult(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!isOutcome(record.outcome))
+        return null;
+    if (typeof record.summary !== 'string' || record.summary.trim().length === 0)
+        return null;
+    const artifacts = stringArray(record.artifacts);
+    const risks = stringArray(record.risks);
+    return {
+        outcome: record.outcome,
+        summary: record.summary,
+        ...artifacts ? { artifacts } : {},
+        ...risks ? { risks } : {},
+    };
+}
+/**
+ * 构造这一轮 Worker 的 prompt。
+ *
+ * 裁决 5：REWORK 轮次必须注入「原 Task + Acceptance Criteria +
+ * 上一轮 Result 摘要 + Supervisor REWORK reason」。
+ * one-shot subagent 不继承父会话上下文，所以 prompt 必须自包含。
+ */
+export function buildWorkerPrompt(context) {
+    const { task, acceptanceCriteria, attemptNo, prevResultSummary, reworkReason } = context;
+    const lines = [
+        '你是本王国某个领地的 Worker，现在承接一个任务。请独立完成它，然后交回结构化结果。',
+        '',
+        `## 任务：${task.title}`,
+    ];
+    if (task.description)
+        lines.push('', task.description);
+    lines.push('', '## 验收标准', acceptanceCriteria?.trim() || '（未显式给出验收标准；请按任务描述的字面要求交付。）');
+    if (attemptNo > 1) {
+        lines.push('', `## 这是第 ${attemptNo} 次尝试（返工）`, 'Supervisor 审查了你上一轮的结果并要求返工。请针对返工理由改进，不要重复上一轮的问题。', '', '### 上一轮你提交的摘要', prevResultSummary?.trim() || '（上一轮无可用摘要。）', '', '### Supervisor 的返工理由', reworkReason?.trim() || '（未给出具体理由。）');
+    }
+    lines.push('', '## 交回要求', '按 outputSchema 交回 { outcome, summary, artifacts?, risks? }。', 'outcome 是你的**自述**：COMPLETED / FAILED / BLOCKED。', '注意：你的结果是一个待审查的 Claim，不是任务完成的事实 —— 是否 DONE 由 Supervisor 裁定。', 'summary 请写清楚你做了什么、是否满足每一条验收标准、以及你无法确认的地方。');
+    return lines.join('\n');
+}
+//# sourceMappingURL=executor.js.map

package/lib/worker/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/worker/executor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "dsh-kingdom",
+  "version": "0.3.1",
+  "description": "独立 dsh 插件：安装后会话内初始化/接入本地王国，Territory/Binding CRUD + Task 治理闭环（Worker Claim ≠ Fact）+ Execution 生命周期",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "kingdom",
+    "governance",
+    "multi-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lusblead/dsh-Kingdom.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lusblead/dsh-Kingdom/issues"
+  },
+  "homepage": "https://github.com/lusblead/dsh-Kingdom#readme",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-commands": ">=0.0.1-rc <2",
+    "@deepseek-ai/dsh-llm": ">=0.0.1-rc <2",
+    "@deepseek-ai/dsh-tools": ">=0.0.1-rc <2",
+    "cordis": ">=4.0.0-rc <5",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}