@joekytc/dsh-swarm 0.3.12 → 0.5.1

package/lib/roles/preset-installer.js

@@ -1,36 +1,103 @@
 // src/roles/preset-installer.ts
-import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { JSON_SCHEMA, load as loadYaml, Type } from 'js-yaml';
 /**
- * 角色裁剪 preset 的运行时安装（2026-08-15 取舍记录）：
- * - 组合文件随包分发（personas/kanban-{v,p,w,d}/agent.cordis.yml，随 npm 包分发）。
- *   kanban-v 于 2026-08-17 补充：V=butler·orchestrator 零执行能力，组合仅 persona+instructions。
- * - 官方 dsh-agent-presets 的 roots 在 web 启动的 composeProfile 中被强制覆盖为
- *   官方 shipped root 单一路径（profile-boot 内 SHIPPED_PRESET_ROOT 硬编码），
- *   因此 cordis.patch.yml 追加 roots 指向包内目录在真实 API 下无效；
- *   唯一可发现的自定义根是 includeUserRoot 派生的 `$DSH_HOME/.agent-presets`。
- * - 故插件 apply 时把包内组合复制到 `$DSH_HOME/.agent-presets/<id>/`，
- *   agentPresets.mount(agentCtx, 'kanban-v'|'kanban-p'|'kanban-w'|'kanban-d') 即可解析。
- * - 幂等：重复安装覆盖同名文件；缺组合文件（未随包）则跳过并让 runner 降级日志。
+ * 角色裁剪 preset 的双路安装：
+ *
+ * 路径一 · 目录写（0.1.7-rc.x 宿主的底线）：把包内组合复制到 `$DSH_HOME/.agent-presets/<id>/`，
+ * 老宿主的 agent-presets 发现逻辑扫该目录完成装载。0.2.0 宿主不再扫描任何目录，此路不影响新宿主。
+ *
+ * 路径二 · 运行时注册（0.2.0 起的唯一生效路径）：0.2.0 的 dsh-agent-preset-registry 是纯运行时
+ * 服务，preset 定义只经 `agentPresets.register(definition)` 进入（官方 dsh-agent-preset 插件
+ * 即在 Service.init 中 yield register(config)），无任何目录发现。本插件经 ctx 取 agentPresets
+ * 服务（未就绪则短轮询等待），把与目录写同一份 yml 解析出的定义注册进去，两个路径语义同源。
+ *
+ * 幂等：目录写覆盖同名文件；运行时注册遇宿主 "Duplicate agent preset" 视为已注册成功。
+ * 尽力而为：单 preset 目录写/注册失败仅告警不阻断插件启动，后续挂载失败由 runner 降级日志兜底。
  */
 const PRESET_IDS = ['kanban-v', 'kanban-p', 'kanban-w', 'kanban-d', 'kanban-pt', 'kanban-dt', 'swarm'];
+/** 等待 agentPresets 服务就绪的超时（宿主组合启动期服务装配可能晚于插件 apply）。 */
+const REGISTER_WAIT_MS = 60000;
 /** 包内组合目录（随包分发）。src/roles/ 与 lib/roles/ 深度一致，均经 ../../ 回到包根。 */
 export function packagePresetsDir() {
     return fileURLToPath(new URL('../../personas/', import.meta.url));
 }
-/** $DSH_HOME/.agent-presets（agent-presets 服务 includeUserRoot 派生根；DSH_HOME 缺省 ~/.dsh）。 */
+/** $DSH_HOME/.agent-presets（0.1.7-rc.x 宿主用户预设根；DSH_HOME 缺省 ~/.dsh）。 */
 export function userPresetsRoot() {
     return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), '.agent-presets');
 }
-/** 安装角色裁剪 preset 到用户预设根；返回成功安装的 preset id 列表（空=无随包组合）。
- *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
- *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
-export function installRolePresets() {
+// 宿主 entry-list YAML 方言的镜像（@deepseek-ai/cordis-plugin-include 的 entryListSchema）：
+// `!!js` 标量解析为 { __jsExpr } 表达式节点，由宿主 Loader 在行激活时求值（组合内
+// `disabled: !!js process.platform === 'win32'` 等行依赖此节点形态，禁在解析期求值）。
+const JS_EXPR_TAG = new Type('tag:yaml.org,2002:js', {
+    kind: 'scalar',
+    resolve: (data) => typeof data === 'string',
+    construct: (data) => ({ __jsExpr: data }),
+});
+const ENTRY_LIST_SCHEMA = JSON_SCHEMA.extend(JS_EXPR_TAG);
+/** 镜像宿主 registry 的入口列表形状校验：顶层为带 name 的行数组（组行递归其 config）。 */
+function entryListProblem(rows, at = '') {
+    if (!Array.isArray(rows))
+        return at === '' ? 'composition must be a top-level list of plugin rows' : `group ${at} must hold a list of plugin rows`;
+    for (const [index, row] of rows.entries()) {
+        const label = at === '' ? `row ${String(index + 1)}` : `${at} row ${String(index + 1)}`;
+        if (typeof row !== 'object' || row === null || Array.isArray(row))
+            return `${label} is not a plugin row`;
+        const name = row.name;
+        if (typeof name !== 'string' || name === '')
+            return `${label} names no plugin (a "name" string is required)`;
+        const config = row.config;
+        if (row.group === true && config !== undefined) {
+            const nested = entryListProblem(config, label);
+            if (nested !== undefined)
+                return nested;
+        }
+    }
+    return undefined;
+}
+/** 解析包内单个 preset 的组合与元数据为宿主 registry 定义；组合缺失返回 undefined。 */
+export function readPresetDefinition(pkgDir, id) {
+    const srcFile = join(pkgDir, id, 'agent.cordis.yml');
+    if (!existsSync(srcFile))
+        return undefined;
+    let rows;
+    let meta;
+    try {
+        rows = loadYaml(readFileSync(srcFile, 'utf8'), { schema: ENTRY_LIST_SCHEMA });
+        const metaFile = join(pkgDir, id, 'preset.yml');
+        meta = existsSync(metaFile)
+            ? loadYaml(readFileSync(metaFile, 'utf8'), { schema: JSON_SCHEMA })
+            : {};
+    }
+    catch (err) {
+        console.warn('[dsh-swarm] role preset parse failed ' + id + ': ' + String(err));
+        return undefined;
+    }
+    const problem = entryListProblem(rows);
+    if (problem !== undefined) {
+        console.warn('[dsh-swarm] role preset composition invalid ' + id + ': ' + problem);
+        return undefined;
+    }
+    const definition = {
+        id,
+        plugins: rows,
+    };
+    if (typeof meta.name === 'string')
+        definition.name = meta.name;
+    if (typeof meta.description === 'string')
+        definition.description = meta.description;
+    if (typeof meta.order === 'number')
+        definition.order = meta.order;
+    return definition;
+}
+/** 路径一：目录写（0.1.7-rc.x 宿主发现根）。返回成功写入的 preset id 列表。 */
+function writeUserDirPresets() {
     const src = packagePresetsDir();
     const dstRoot = userPresetsRoot();
-    const installed = [];
+    const written = [];
     for (const id of PRESET_IDS) {
         const srcFile = join(src, id, 'agent.cordis.yml');
         if (!existsSync(srcFile))
@@ -42,14 +109,81 @@ export function installRolePresets() {
             const meta = join(src, id, 'preset.yml');
             if (existsSync(meta))
                 copyFileSync(meta, join(dstDir, 'preset.yml'));
-            installed.push(id);
+            written.push(id);
         }
         catch (err) {
             // 尽力而为：写入失败（如沙箱/权限拒绝）仅告警，不阻断插件启动
-            console.warn('[dsh-swarm] role preset install skipped ' + id + ' -> ' + dstRoot + ': ' + String(err));
+            console.warn('[dsh-swarm] role preset dir write skipped ' + id + ' -> ' + dstRoot + ': ' + String(err));
         }
     }
-    return installed;
+    return written;
+}
+/** 路径二：运行时注册全部包内 preset；返回注册成功/失败 id 列表与成功项的撤销句柄（组合缺失的 id 不计）。 */
+export async function registerRolePresets(registry, ids, pkgDir = packagePresetsDir()) {
+    const registered = [];
+    const failed = [];
+    const disposers = [];
+    for (const id of ids) {
+        const definition = readPresetDefinition(pkgDir, id);
+        if (!definition)
+            continue;
+        try {
+            disposers.push(await registry.register(definition));
+            registered.push(id);
+        }
+        catch (err) {
+            // 插件重 apply 时定义已在 registry：与首次注册语义等价，按成功计
+            if (String(err).includes('Duplicate agent preset')) {
+                registered.push(id);
+                continue;
+            }
+            failed.push(id);
+            console.warn('[dsh-swarm] role preset runtime register failed ' + id + ': ' + String(err));
+        }
+    }
+    return { registered, failed, disposers };
+}
+/** 短轮询等待宿主 agentPresets 服务就绪；超时返回 undefined（降级仅目录写）。 */
+async function waitForPresets(ctx, timeoutMs) {
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const poll = setInterval(() => {
+            const found = ctx.get?.('agentPresets');
+            if (found) {
+                clearInterval(poll);
+                resolve(found);
+            }
+            else if (Date.now() - started >= timeoutMs) {
+                clearInterval(poll);
+                resolve(undefined);
+            }
+        }, 500);
+    });
+}
+/**
+ * 双路安装入口。目录写同步完成并即时留痕；运行时注册等服务就绪后完成并留痕。
+ * 返回前目录写已落盘；注册部分异步收敛（fire-and-forget 调用方须 catch）。
+ */
+export async function installRolePresets(ctx, opts = {}) {
+    const dirWritten = writeUserDirPresets();
+    console.info('[dsh-swarm] role preset dir write: ' + (dirWritten.length ? dirWritten.join(',') : 'none'));
+    const registry = await waitForPresets(ctx, opts.registerWaitMs ?? REGISTER_WAIT_MS);
+    if (!registry) {
+        console.warn('[dsh-swarm] role presets installed: dir-write=' + (dirWritten.join(',') || 'none')
+            + ' runtime-register=none (agentPresets service unavailable; directory write only)');
+        return { dirWritten, runtimeRegistered: [], runtimeFailed: [], runtimeMode: 'unavailable' };
+    }
+    const { registered, failed, disposers } = await registerRolePresets(registry, PRESET_IDS);
+    console.info('[dsh-swarm] role presets installed: dir-write=' + (dirWritten.join(',') || 'none')
+        + ' runtime-register=' + (registered.join(',') || 'none')
+        + (failed.length ? ' failed=' + failed.join(',') : ''));
+    // 插件卸载/重载时撤销注册，避免宿主 registry 留下失效定义（官方 register 契约：声明方持有 disposer）。
+    ctx.on?.('dispose', () => {
+        for (const dispose of disposers.splice(0))
+            void dispose().catch(() => { });
+    });
+    const report = { dirWritten, runtimeRegistered: registered, runtimeFailed: failed, runtimeMode: 'runtime' };
+    return report;
 }
 /**
  * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程

package/lib/routes/kanban-http.js

@@ -309,12 +309,27 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                 if (req.method === 'PUT' && req.url?.startsWith('/kanban/config')) {
                     const raw = JSON.parse((await readBody(req)) || '{}');
                     // 归一化缺省字段，保证缺字段走 400 校验失败而非 500。
-                    // reviewEngine/imDelivery 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带这些字段时保存不清空既有配置。
+                    // reviewEngine/imDelivery/chainFallback 缺省时回退当前 effective（再兜底默认）：旧客户端
+                    // bundle 不带这些字段时保存不清空既有配置；chainFallback 属部署配置只读，原样回填。
                     const cur = configProvider.getEffective();
                     const fb = cur.reviewEngine;
+                    const cfb = cur.roles.chainFallback;
                     const snapshot = {
                         wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
-                        roles: { models: raw.roles?.models ?? {} },
+                        roles: {
+                            models: Object.fromEntries(Object.entries(raw.roles?.models ?? {}).map(([k, m]) => [
+                                k,
+                                // 旧客户端 bundle 不带 fallbacks 字段：回填当前 effective 链，避免保存时误清降级链。
+                                m.fallbacks === undefined
+                                    ? { ...m, fallbacks: cur.roles.models?.[k]?.fallbacks ?? [] }
+                                    : m,
+                            ])),
+                        },
+                        chainFallback: {
+                            provider: raw.chainFallback?.provider ?? cfb?.provider ?? '',
+                            model: raw.chainFallback?.model ?? cfb?.model ?? '',
+                            reasoningEffort: raw.chainFallback?.reasoningEffort ?? cfb?.reasoningEffort ?? 'high',
+                        },
                         reviewEngine: {
                             mode: raw.reviewEngine?.mode ?? fb?.mode ?? 'delegate',
                             managed: {
@@ -331,8 +346,14 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                     const toProbe = [];
                     for (const role of ROLES) {
                         const m = snapshot.roles.models[role];
-                        if (m?.provider?.trim() && m?.model?.trim())
+                        if (m?.provider?.trim() && m?.model?.trim()) {
                             toProbe.push({ provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort });
+                            // 降级候选同口径预检：死组合保存时拦下，不流入派发。
+                            for (const f of m.fallbacks ?? []) {
+                                if (f.provider?.trim() && f.model?.trim())
+                                    toProbe.push({ provider: f.provider, model: f.model, reasoningEffort: f.reasoningEffort });
+                            }
+                        }
                     }
                     if (snapshot.reviewEngine.mode === 'managed' && snapshot.reviewEngine.managed.provider.trim() && snapshot.reviewEngine.managed.model.trim()) {
                         toProbe.push({ provider: snapshot.reviewEngine.managed.provider, model: snapshot.reviewEngine.managed.model });

package/lib/services/config-provider.js

@@ -80,6 +80,11 @@ export class ConfigProvider extends Service {
                 if (a !== b)
                     keys.add(`roles.models.${role}.${f}`);
             }
+            // 降级链整组审计（实例必不同，按内容比较）。
+            const af = prev.roles?.models?.[role]?.fallbacks;
+            const bf = next.roles?.models?.[role]?.fallbacks;
+            if (JSON.stringify(af ?? []) !== JSON.stringify(bf ?? []))
+                keys.add(`roles.models.${role}.fallbacks`);
         }
         if (prev.reviewEngine?.mode !== next.reviewEngine?.mode)
             keys.add('reviewEngine.mode');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.3.12",
+  "version": "0.5.1",
   "description": "A governed swarm of six specialist DSH agents (orchestrator, planner, knowledge-base bridge, developer and two reviewers) that turns a requirement into a strict phase pipeline with machine-verified delivery evidence, review-gated merges, a full audit-log event stream and a live kanban tab; design inspired by the Hermes Agent kanban",
   "license": "MIT",
   "author": "joekytc",
@@ -33,7 +33,8 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-workspace"
       ]
     }
   },
@@ -58,27 +59,32 @@
     "test": "vitest run",
     "build:client": "node scripts/build-client.mjs"
   },
+  "dependencies": {
+    "js-yaml": "^4.3.2"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-credentials": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-persona": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-bash": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-fs": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-fs-search": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-credentials": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-persona": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-bash": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-fs-search": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "~0.1.7-rc.2 || ^0.2.0-rc.2",
+    "@deepseek-ai/dsh-util-values": "~0.1.7-rc.2 || ^0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-store": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-layout": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.9",
+    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
@@ -90,4 +96,4 @@
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
   }
-}
+}

package/personas/kanban-d/agent.cordis.yml

@@ -12,7 +12,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the fullstack development agent (the ONLY executor) powered by the {{model}} model.
       Your working directory is {{cwd}}. You implement and test the aligned spec; you are
       the sole accountable executor and may delegate implementation subtasks. Rules:
@@ -134,12 +134,14 @@
   config:
     provider: spawn
     toolName: subagent
+    maxDepth: 3
 
 - id: tool-subagent-fork
   name: '@deepseek-ai/dsh-tool-subagent'
   config:
     provider: fork
     toolName: subagent_fork
+    maxDepth: 3
 
 - id: tool-subagent-control
   name: '@deepseek-ai/dsh-tool-subagent-control'

package/personas/kanban-dt/agent.cordis.yml

@@ -11,7 +11,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the implementation verifier + reviewer agent (read-only) powered by the {{model}}
       model. Your working directory is {{cwd}}. You empirically verify D's implementation and
       review it — you never modify source and you never execute writes. Rules:
@@ -95,3 +95,4 @@
   config:
     provider: spawn
     toolName: subagent
+    maxDepth: 3

package/personas/kanban-p/agent.cordis.yml

@@ -15,7 +15,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the planning agent (planner) powered by the {{model}} model. Your working
       directory is {{cwd}}. You produce the implementation plan only — you are NOT the
       executor. When injected repo facts are insufficient, you may do READ-ONLY self-inspection

package/personas/kanban-pt/agent.cordis.yml

@@ -9,7 +9,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the plan-review agent (read-only) powered by the {{model}} model. Your working
       directory is {{cwd}}. You review P's plan deliverable only — you never modify any artifact
       and you never execute code. Rules:

package/personas/kanban-v/agent.cordis.yml

@@ -12,7 +12,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the orchestration agent (butler) powered by the {{model}} model. Your working
       directory is {{cwd}}. You only decompose, dispatch and summarize — you are NEVER the executor.
       Rules:

package/personas/kanban-w/agent.cordis.yml

@@ -12,7 +12,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       You are the knowledge officer (Knowledge Officer) powered by the {{model}} model. Your
       working directory is {{cwd}}. You curate the requirement knowledge base (KB) in one of two
       modes (the active mode and the local KB root, when local, are stated in your task context);

package/personas/swarm/agent.cordis.yml

@@ -6,7 +6,7 @@
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
-    text: >-
+    prefix: >-
       你是蜂群模式的领队。本模式下你负责把「要动手开发的需求」转化为一条多角色工作流链并跟进到交付；其余对话正常应答。
 
       ## 分流判定（每轮先判）