@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/domain/review-evidence.js

@@ -24,7 +24,7 @@ export function validateReviewEvidence(role, handoff) {
         // 计划结构字段：评审须给出被评审计划产物引用（如 artifacts_path/page 结构）——缺则视为证据不足
         const planRef = ev.reviewPage ?? (handoff.metadata ?? {})['artifacts_path'];
         if (!planRef)
-            missing.push('review_evidence.plan (artifacts_path/reviewPage)');
+            missing.push('metadata.artifacts_path (被评审计划的 openspec 目录绝对路径，继承被评审 P 卡) 或 review_evidence.reviewPage');
     }
     else {
         // DT：实证校验证据（fail 评审同样必须已实证——test 字段必须存在；仅 pass 要求 exit 0）

package/lib/domain/state-machine.js

@@ -10,11 +10,12 @@ const TASK_TRANSITIONS = {
 };
 const CHAIN_TRANSITIONS = {
     planning: { 'chain/executing': 'executing' },
-    executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted' },
+    executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted', 'chain/blocked': 'blocked' },
+    blocked: {},
     completed: {},
     aborted: {},
 };
-// D23：'chain/audit-warning' / 'chain/audit-confirmed' 不是状态转换——
+// 'chain/audit-warning' / 'chain/audit-confirmed' 不是状态转换——
 // Chain 保持 completed，只向投影写入验收核对视图（auditWarnings）。
 // projection.ts 对这两类事件专门处理、不调用 transitionChain，故此处不注册。
 const SPEC_TRANSITIONS = {

package/lib/domain/task-parents.js

@@ -1,5 +1,5 @@
 /**
- * 每阶段任务卡的语义输入来源（R20 依赖)：第 1 项为主来源。
+ * 每阶段任务卡的语义输入来源：第 1 项为主来源。
  * key = `${assignee}:${mode}`；w:kb 特判（w2→P、w3→D）见 semanticParentDeps。
  * 未列出的 mode（如旧兼容 align）不设语义 parents（返回空）。
  */

package/lib/domain/types.d.ts

@@ -1,7 +1,7 @@
 export type Role = 'v' | 'p' | 'w' | 'd' | 'pt' | 'dt';
 export type TaskMode = 'file' | 'external' | 'kb' | 'openspec' | 'mattpocock' | 'align' | 'execute' | 'review-plan' | 'review-impl';
 export type TaskStatus = 'triage' | 'todo' | 'ready' | 'running' | 'blocked' | 'done' | 'failed' | 'archived';
-export type ChainStatus = 'planning' | 'executing' | 'completed' | 'aborted';
+export type ChainStatus = 'planning' | 'executing' | 'blocked' | 'completed' | 'aborted';
 export type SpecCardStatus = 'draft' | 'approved';
 /** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃。 */
 export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up';
@@ -40,7 +40,7 @@ export interface ReviewEvidence {
         kbUrl: string;
     };
 }
-export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
+export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
 export interface SpecCardSections {
     problem: string;
     solution: string;
@@ -61,7 +61,7 @@ export interface Chain {
     rootTaskId: string | null;
     specCardId: string | null;
     ownerSessionId: string;
-    /** 发起 /plan: 的主 agent 会话工作目录（Q5：角色会话统一创建于此，便于管理 profile 会话）。null=未捕获（GUI 建链），回退 kanban 存储。 */
+    /** 发起 /plan: 的主 agent 会话工作目录（角色会话统一创建于此，便于管理 profile 会话）。null=未捕获（GUI 建链），回退 kanban 存储。 */
     workspaceDir: string | null;
     createdAt: number;
 }
@@ -105,14 +105,14 @@ export interface Handoff {
     metadata: Record<string, unknown>;
     completedAt: number;
 }
-/** D23 链完成验收核对证据：主会话越权写工作区产物的单个线索。 */
+/** 链完成验收核对证据：主会话越权写工作区产物的单个线索。 */
 export interface AuditEvidence {
     source: 'main-session-scan' | 'artifact-reconciliation' | string;
     detail: string;
     paths: string[];
     at?: number;
 }
-/** D23 链完成验收核对投影视图：warning 事件 + （可选）用户确认。 */
+/** 链完成验收核对投影视图：warning 事件 + （可选）用户确认。 */
 export interface ChainAudit {
     evidence: AuditEvidence[];
     warnedAt: number;

package/lib/index.js

@@ -1,28 +1,16 @@
+import { homedir } from 'node:os';
 import { KanbanProvider } from './services/kanban-provider.js';
 import { Config } from './config.js';
 import { registerMainSessionTools } from './tools/main-session-tools.js';
 import { installRolePresets } from './roles/preset-installer.js';
+import { installLlWikiSkill } from './roles/skill-installer.js';
 import { registerKanbanHttp } from './routes/kanban-http.js';
 import { startDispatcher } from './dispatcher/dispatcher.js';
+import { ConfigProvider } from './services/config-provider.js';
+import { wireImDelivery } from './services/im-delivery.js';
 export const name = 'dsh-swarm';
 export { Config };
-// P1-9：无 inject——KanbanProvider 只用文件系统（FileEventStore），不依赖 ctx.storage 等任何服务。
-/** 可选服务延迟装配：插件 apply 时各服务可能尚未提供（cordis 注入顺序），轮询 ctx.get 直至可用再接线。 */
-function wireWhenAvailable(ctx, name, fn, timeoutMs = 60000) {
-    if (ctx.get(name)) {
-        fn();
-        return () => { };
-    }
-    const timer = setInterval(() => {
-        if (ctx.get(name)) {
-            clearInterval(timer);
-            clearTimeout(to);
-            fn();
-        }
-    }, 500);
-    const to = setTimeout(() => clearInterval(timer), timeoutMs);
-    return () => { clearInterval(timer); clearTimeout(to); };
-}
+// 无 inject——KanbanProvider 只用文件系统（FileEventStore），不依赖 ctx.storage 等任何服务。
 /** 等待多个服务同时可用后再接线（如 tools 先于 kanban 出现时，单服务轮询会过早执行）。 */
 function wireAllAvailable(ctx, names, fn, timeoutMs = 60000) {
     const ready = () => names.every((name) => Boolean(ctx.get(name)));
@@ -42,15 +30,30 @@ function wireAllAvailable(ctx, names, fn, timeoutMs = 60000) {
 }
 export function apply(ctx, config) {
     // cordis 4：Service 构造即注册（super(ctx,'kanban') 调 ctx.reflect.provide），无需手动 provide。
-    const provider = new KanbanProvider(ctx, config);
-    // D22：把包内角色裁剪 preset 组合安装到 $DSH_HOME/.agent-presets/（真实 API 下唯一可发现的自定义根）。
+    // ConfigProvider 在 apply 中创建一次（override 存放于 storageDir，$DSH_HOME 占位符在此解析），
+    // 全链路（KanbanProvider/HTTP 桥/主会话工具/调度器）共享同一实例实现配置面板热生效。
+    const storageDir = config.storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? homedir());
+    const configProvider = new ConfigProvider(ctx, config, storageDir);
+    // KanbanProvider 持 ConfigProvider 引用，kb_url base 经 getter 热读取（配置面板改后无需重建）。
+    const provider = new KanbanProvider(ctx, config, configProvider);
+    // 把包内角色裁剪 preset 组合安装到 $DSH_HOME/.agent-presets/（真实 API 下唯一可发现的自定义根）。
     const installed = installRolePresets();
+    installLlWikiSkill(); // 尽力而为：失败仅告警不阻断
     console.info('[dsh-swarm] role presets installed: ' + (installed.length ? installed.join(',') : 'none'));
+    // IM 投递（企微，2026-09-07 评审决议）：W3 收尾/链阻塞时经 dsh-im 投群。
+    // imDelivery.enabled=false（默认）时事件处理器零开销早退；dshIm 服务缺失显式降级留痕。
+    const disposeImDelivery = wireImDelivery(ctx, provider.service, configProvider);
+    ctx.on('dispose', disposeImDelivery);
+    // LLM 运行时延迟取用：registerKanbanHttp 内部消费（llm-catalog 枚举），接线时 llm 服务已就绪。
+    const llm = () => ctx.get('llm');
     // 可选服务接线均延迟到服务可用后：
-    // - Web GUI 数据桥（GET /kanban/board + POST /kanban/action，仅 webServer 存在时挂载）
-    wireWhenAvailable(ctx, 'webServer', () => registerKanbanHttp(ctx, provider, config));
-    // - P1-3 主会话工具面（spec_card_view/edit/approve + kanban 只读子集 + 前缀路由工具）
-    wireAllAvailable(ctx, ['tools', 'kanban'], () => registerMainSessionTools(ctx, config));
-    // - 调度层：事件唤醒 V（R20）+ 每任务 agent runner + 看门狗（仅 agents 可用时启动）
-    wireAllAvailable(ctx, ['agents', 'kanban'], () => startDispatcher(ctx, config));
+    // - Web GUI 数据桥（GET /kanban/board + POST /kanban/action + 配置读写 + llm-catalog，仅 webServer 存在时挂载）
+    //   llm 需在 webServer 就绪且 llm 就绪后取，wireAllAvailable 双服务轮询比单服务更稳。
+    wireAllAvailable(ctx, ['webServer', 'llm'], () => registerKanbanHttp(ctx, provider, configProvider, llm(), config));
+    // - 主会话工具面（spec_card_view/edit/approve + kanban 只读子集 + 前缀路由工具）
+    //   收 ConfigProvider，wiki 客户端与全部配置读点经 getEffective() 调用时热读取。
+    wireAllAvailable(ctx, ['tools', 'kanban'], () => registerMainSessionTools(ctx, configProvider));
+    // - 调度层：事件唤醒 V + 每任务 agent runner + 看门狗（仅 agents 可用时启动）
+    // startDispatcher 收 ConfigProvider（模型链/wiki 热生效）。
+    wireAllAvailable(ctx, ['agents', 'kanban'], () => startDispatcher(ctx, configProvider));
 }

package/lib/roles/clean-fs-tools.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** 需剥离的带毒参数（dsh-sandbox escalation 配对参数；写死避免依赖宿主内部导出）。 */
+export declare const ESCALATION_PARAM_KEYS: readonly ["sandbox_permissions", "justification"];
+/** 剥离 escalation 参数：净化后新对象返回；本就干净则原对象透传（零拷贝零改写）。 */
+export declare function stripEscalationArgs(args: unknown): unknown;
+/**
+ * 给 danger-full-access 会话 shadow 注册去毒版 write/edit/bash。
+ *
+ * 行为契约：
+ * - 干净版 = 宿主定义浅拷贝 + parameters 去掉两带毒字段（JSON 深拷贝后删除，注册表保证 lossless JSON）
+ *   + execute 换成「剥参 → 转发宿主原工具 execute」。写逻辑零自实现，行为 100% 官方。
+ * - 宿主 schema 本就无带毒参数（无沙箱后端的组合，escalationModes 为空）→ 无需 shadow，跳过
+ *   （最小触碰面：不去盖一个本来就干净的版本）。
+ * - 转发失败面（宿主定义不可达 / 缺 execute / 同层注册冲突）→ 该工具不挂 + console.error 显形，
+ *   宿主带毒版本保持可见（fail-safe：绝不注册一个自实现写文件的半成品）。
+ * - 幂等：setup 重入（live 会话修复路径 resumeOrReuse 会重跑 setup）先以品牌标记识别已挂
+ *   shadow → 跳过；同层冲突抛错也被捕获显形，不炸 setup（宿主版本继续可见，plan-guard 兜底网仍在）。
+ *
+ * @param agentCtx agent setup 收到的 scoped ctx（agentCtx.tools 即该 scope 的注册表）
+ * @param agent Agent 实例（= dsh-tools scope key，exec.agent 同源；get 的 scope 视角参数）
+ */
+export declare function installCleanFsTools(agentCtx: Context, agent: unknown): void;

package/lib/roles/clean-fs-tools.js

@@ -0,0 +1,117 @@
+// src/roles/clean-fs-tools.ts
+// danger-full-access 会话（P、D(execute)）的 write/edit/bash 工具菜单去毒。
+//
+// 为什么：宿主 dsh-tool-fs / dsh-tool-bash 在组合层把可选参数 sandbox_permissions / justification
+// 合入 write/edit/bash schema（dsh-tool-fs lib/index.js:617/771 schemaFields()、dsh-tool-bash
+// lib/index.js:285-289；广播与否只看组合默认沙箱模式 :1111，会话层 sandbox/mode 改不掉）。
+// 在 danger-full-access（权限天花板）会话里，escalation「必须严格更宽」无更宽可升——任何值
+// 都被 approveEscalation 拒绝，模型却仍从菜单看到这两个按钮，触发拒绝-重试循环
+// （2026-09-02 P 会话 30 连败事故根因）。plan-guard 的带参拦截保留为兜底网（toolsets.ts 不动），
+// 本文件是根治面：agent scope shadow 注册「无带毒参数的干净版」盖住宿主版本 + execute 剥参转发。
+//
+// 宿主探明结论：
+// - 遮蔽语义（dsh-tools lib/index.js view/get + dsh-scope ScopedLayers）：scope 自身层注册在
+//   inherited（global + preset standing 祖先层）之后覆盖 visible map → agent scope 同名注册
+//   真实盖住宿主版本；「重复注册 fail」仅指同一层内（NamedEntries.insert），跨层 shadow 合法。
+//   agentPresets.mount 是 bindScopeParent（agent scope 挂为 preset standing scope 的 child），
+//   preset 里 tool-fs/tool-bash 的注册落在 standing 祖先层而非 agent own 层 → 本模块经
+//   agentCtx.tools.register 落 own 层，无同层冲突（kanban_comment 遮蔽已实证该通道）。
+// - 转发通道：agentCtx.tools.get(name, agent) 返回该 scope 可见定义（shadow 注册前即宿主原定义，
+//   kanban-p/d 的 fs/bash 在 preset standing 祖先层，全局视角 get(name) 反而可能取不到）；
+//   直接调用 hostDef.execute(cleanArgs, exec) 与注册表 dispatchToolBody 的调用形态逐字一致
+//   （lib/index.js:3174 tool.execute(exec.arguments, exec)）。绕开 approval/escalation 前置管线
+//   安全：resolvePolicy 在两参皆缺时走 standingPolicy 路径（dsh-sandbox validateEscalationArgs
+//   对 (undefined, undefined) 放行）——即官方默认行为，escalation 管线本就不触发。
+// - guard 管线在 dispatch 前运行且 deny-only（registry pre-execute → guardReason → dispatch），
+//   转发是对宿主 execute 的普通函数调用，不存在 guard 二次绕过问题。
+// - justification 仅为 escalation 配套参数（dsh-sandbox：「justification is only valid together
+//   with sandbox_permissions」），与两参一并剥离 = 官方 standing 行为，无害。
+/** 需剥离的带毒参数（dsh-sandbox escalation 配对参数；写死避免依赖宿主内部导出）。 */
+export const ESCALATION_PARAM_KEYS = ['sandbox_permissions', 'justification'];
+/** 需去毒的宿主工具名单：write/edit（dsh-tool-fs）+ bash（dsh-tool-bash，schema 同样带毒）。 */
+const CLEAN_FS_TOOL_NAMES = ['write', 'edit', 'bash'];
+/** 本模块 shadow 的品牌标记（幂等判定：setup 重入/live 修复重跑 setup 时识别已挂 shadow）。
+ *  Symbol.for 跨模块实例一致；对象展开会复制自有可枚举 symbol 属性，标记随干净版定义存活。 */
+const CLEAN_FS_BRAND = Symbol.for('dsh-swarm.clean-fs-shadow');
+/** 从 agentCtx 解出工具注册表（缺 service = 测试桩/异常宿主 → undefined）。 */
+function toolsRuntimeOf(agentCtx) {
+    const tools = agentCtx.tools;
+    if (!tools || typeof tools.get !== 'function' || typeof tools.register !== 'function')
+        return undefined;
+    return tools;
+}
+/** 剥离 escalation 参数：净化后新对象返回；本就干净则原对象透传（零拷贝零改写）。 */
+export function stripEscalationArgs(args) {
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return args;
+    const a = args;
+    const poisoned = ESCALATION_PARAM_KEYS.some((k) => a[k] !== undefined);
+    if (!poisoned)
+        return args;
+    const { sandbox_permissions: _sp, justification: _j, ...rest } = a;
+    return rest;
+}
+/**
+ * 给 danger-full-access 会话 shadow 注册去毒版 write/edit/bash。
+ *
+ * 行为契约：
+ * - 干净版 = 宿主定义浅拷贝 + parameters 去掉两带毒字段（JSON 深拷贝后删除，注册表保证 lossless JSON）
+ *   + execute 换成「剥参 → 转发宿主原工具 execute」。写逻辑零自实现，行为 100% 官方。
+ * - 宿主 schema 本就无带毒参数（无沙箱后端的组合，escalationModes 为空）→ 无需 shadow，跳过
+ *   （最小触碰面：不去盖一个本来就干净的版本）。
+ * - 转发失败面（宿主定义不可达 / 缺 execute / 同层注册冲突）→ 该工具不挂 + console.error 显形，
+ *   宿主带毒版本保持可见（fail-safe：绝不注册一个自实现写文件的半成品）。
+ * - 幂等：setup 重入（live 会话修复路径 resumeOrReuse 会重跑 setup）先以品牌标记识别已挂
+ *   shadow → 跳过；同层冲突抛错也被捕获显形，不炸 setup（宿主版本继续可见，plan-guard 兜底网仍在）。
+ *
+ * @param agentCtx agent setup 收到的 scoped ctx（agentCtx.tools 即该 scope 的注册表）
+ * @param agent Agent 实例（= dsh-tools scope key，exec.agent 同源；get 的 scope 视角参数）
+ */
+export function installCleanFsTools(agentCtx, agent) {
+    const tools = toolsRuntimeOf(agentCtx);
+    if (!tools)
+        return; // 无工具服务（测试桩）跳过；宿主版本自然保持可见
+    for (const name of CLEAN_FS_TOOL_NAMES) {
+        try {
+            // shadow 注册前取样：get(name, agent) 走该 agent scope 视角——own 层尚无同名时返回
+            // inherited（global + preset standing 祖先层）里的宿主原定义
+            const visible = tools.get(name, agent);
+            if (!visible || typeof visible !== 'object' || !visible.parameters || typeof visible.execute !== 'function') {
+                console.error('[dsh-swarm][clean-fs] host "' + name + '" not reachable via agent-scope registry — shadow skipped, host version stays visible');
+                continue;
+            }
+            if (visible[CLEAN_FS_BRAND])
+                continue; // 幂等：上次 setup 已挂 shadow
+            const props = visible.parameters.properties;
+            const poisoned = !!props && ESCALATION_PARAM_KEYS.some((k) => props[k] !== undefined);
+            if (!poisoned)
+                continue; // 宿主 schema 本就干净（无沙箱组合）→ 无需 shadow
+            // parameters 深拷贝去毒（注册表已保证 lossless JSON，JSON 往返安全）；
+            // 宿主编译态无 additionalProperties:false（parameterSchemaSpecToJsonSchema 开根），
+            // 模型惯性硬塞的带毒参数由 execute 剥参兜住，不会在宿主 execute 的 args 校验处炸出。
+            const parameters = JSON.parse(JSON.stringify(visible.parameters));
+            if (parameters['properties'] && typeof parameters['properties'] === 'object') {
+                for (const key of ESCALATION_PARAM_KEYS)
+                    delete parameters['properties'][key];
+            }
+            // 防御：宿主未来若把两参数标成必填，required 一并过滤（当前为可选，此过滤为空操作）
+            if (Array.isArray(parameters['required'])) {
+                parameters['required'] = parameters['required'].filter((k) => !ESCALATION_PARAM_KEYS.includes(k));
+            }
+            tools.register({
+                ...visible,
+                parameters,
+                [CLEAN_FS_BRAND]: true,
+                // 剥参后转发宿主原 execute：调用形态与注册表 dispatchToolBody 逐字一致（args, exec）。
+                // 禁止在此自实现任何写逻辑——行为漂移风险，宿主升级即失效。
+                execute(args, exec) {
+                    return visible.execute(stripEscalationArgs(args), exec);
+                },
+            });
+        }
+        catch (err) {
+            // fail-safe：单工具失败只降级该工具（宿主版本保持可见），不阻断其余工具与 setup
+            console.error('[dsh-swarm][clean-fs] shadow register failed for "' + name + '" — host version stays visible: ' + String(err));
+        }
+    }
+}

package/lib/roles/preset-installer.js

@@ -4,9 +4,9 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
- * D22 角色裁剪 preset 的运行时安装（2026-08-15 取舍记录）：
+ * 角色裁剪 preset 的运行时安装（2026-08-15 取舍记录）：
  * - 组合文件随包分发（personas/kanban-{v,p,w,d}/agent.cordis.yml，随 npm 包分发）。
- *   kanban-v 于 2026-08-17 补充（R21 对齐）：V=butler·orchestrator 零执行能力，组合仅 persona+instructions。
+ *   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 下无效；
@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url';
  *   agentPresets.mount(agentCtx, 'kanban-v'|'kanban-p'|'kanban-w'|'kanban-d') 即可解析。
  * - 幂等：重复安装覆盖同名文件；缺组合文件（未随包）则跳过并让 runner 降级日志。
  */
-const PRESET_IDS = ['kanban-v', 'kanban-p', 'kanban-w', 'kanban-d', 'kanban-pt', 'kanban-dt'];
+const PRESET_IDS = ['kanban-v', 'kanban-p', 'kanban-w', 'kanban-d', 'kanban-pt', 'kanban-dt', 'swarm'];
 /** 包内组合目录（随包分发）。src/roles/ 与 lib/roles/ 深度一致，均经 ../../ 回到包根。 */
 export function packagePresetsDir() {
     return fileURLToPath(new URL('../../personas/', import.meta.url));

package/lib/roles/skill-installer.d.ts

@@ -0,0 +1,6 @@
+export declare function packageSkillDir(): string;
+export declare function userSkillsRoot(): string;
+export declare function installLlWikiSkill(opts?: {
+    src?: string;
+    dstRoot?: string;
+}): 'installed' | 'exists' | 'skipped';

package/lib/roles/skill-installer.js

@@ -0,0 +1,32 @@
+// src/roles/skill-installer.ts
+// llm-wiki skill 自动安装：DSH 的 dsh-tool-skill 只从 ~/.agents/skills/ 发现 skill，
+// 不扫插件包内 skills 目录（同 agent-presets 只认 $DSH_HOME/.agent-presets 的先例）。
+// 完整复制（含 deps/assets/tests 全部子目录）；幂等（SKILL.md 已存在跳过）；尽力而为（失败仅告警）。
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function packageSkillDir() {
+    return fileURLToPath(new URL('../../skills/llm-wiki-skill/', import.meta.url));
+}
+export function userSkillsRoot() {
+    return join(homedir(), '.agents', 'skills');
+}
+export function installLlWikiSkill(opts) {
+    const src = opts?.src ?? packageSkillDir();
+    const dst = join(opts?.dstRoot ?? userSkillsRoot(), 'llm-wiki-skill');
+    if (!existsSync(src))
+        return 'skipped';
+    if (existsSync(join(dst, 'SKILL.md')))
+        return 'exists';
+    try {
+        mkdirSync(dst, { recursive: true });
+        cpSync(src, dst, { recursive: true });
+        console.info('[dsh-swarm] llm-wiki-skill installed -> ' + dst);
+        return 'installed';
+    }
+    catch (err) {
+        console.warn('[dsh-swarm] llm-wiki-skill install skipped -> ' + dst + ': ' + String(err));
+        return 'skipped';
+    }
+}

package/lib/roles/toolsets.d.ts

@@ -1,18 +1,13 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { KanbanService } from '../domain/kanban-service.js';
-import type { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
 import type { Role } from '../domain/types.js';
-/** 判定 wiki 路径是否位于 DT 评审命名空间 projects/<chain>/review/（拒绝 ../、绝对路径、非 review 前缀）。 */
+import type { ConfigProvider } from '../services/config-provider.js';
+import { isRoleComposed } from '../dispatcher/agent-runner.js';
+export { isRoleComposed };
+/** 判定 wiki 路径是否位于 DT 评审命名空间 projects/<repoSlug>/<chainId>/review/
+ *  （repoSlug=[a-z0-9-]+ 通配，chainId 精确匹配；拒绝 ../、绝对路径、跨链、旧格式直挂根）。 */
 export declare function isReviewNamespacePath(pagePath: string, chainId: string): boolean;
-/**
- * 评审引擎决策（DT）：ocr（open-code-review Delegation 模式）优先；
- * 不可用 fallback superpowers code-review；两者都不可用 → review-tool-unavailable（阻塞）。
- * 纯函数便于单测；真实可用性探测在 agent-runner 装配（探活 ocr 二进制/失败）。
- */
-export declare function resolveReviewEngine(available: {
-    ocr: boolean;
-    codeReview: boolean;
-}): 'ocr' | 'code-review' | 'review-tool-unavailable';
 /**
  * DT 写护栏 = PT 只读护栏（源码/git/写标记 bash 拒绝）+ wiki_write 仅 review namespace 收窄。
  * repoRoot 为 D 目标仓库；chainId 用于 wiki 评审命名空间校验。
@@ -25,23 +20,34 @@ export declare function buildReadOnlyWriteGuard(_repoRoot: string): (execution:
     name?: string;
     arguments?: unknown;
 }) => string | undefined;
-/** P 专用写护栏（Q3）：读全放行；git mutation 一律拒绝；写仅允许目标仓库 openspec/changes 目录。
+/** 本地模式 KB 写护栏：全名只读拦截（base）之上，仅对「实际写目标全部为
+ *  库根内绝对路径」的写操作豁免。目标提取不到 / 相对路径 / 越界 → 维持 base 拒绝（fail-closed）。
+ *  仅 local 模式对 W/DT 装配；remote 模式仍用 buildReadOnlyWriteGuard（库根写也被拒）。
+ *  审查修订：extractWriteTargets 保持既有双参签名（cmd, redirectRe），按入口分流
+ *  传 BASH_REDIRECT_TARGET_RE / CODE_REDIRECT_TARGET_RE（与 buildPlanWriteGuard 同款）——
+ *  单参调用会在首个写意图命令上 TypeError。 */
+export declare function buildKbWriteGuard(kbRoot: string): (execution: {
+    name?: string;
+    arguments?: unknown;
+}) => string | undefined;
+/** P 专用写护栏：读全放行；git mutation 一律拒绝；写仅允许目标仓库 openspec/changes 目录。
  *  直接 fs 写工具 → 路径经 resolve 归一化后须落在 <workspaceRoot>/openspec/changes/ 之下（相邻段对判定）；
  *  bash/run_code 写标记命令 → 命令文本须含 `openspec/changes` 子串，且提取出的实际写目标（重定向
- *  目标 / writeFileSync 实参）逐条经 resolve+isPlanPath 校验（I1：杀 openspec/changes/../.. 穿越写源码）。
+ *  目标 / writeFileSync 实参）逐条经 resolve+isPlanPath 校验（杀 openspec/changes/../.. 穿越写源码）。
  *  源码/src/lib/tests 等写不入（不含该子串）——"禁止改动源码"为工具级硬约束，非 prompt 软约束。
  *  execution 以 dsh-tools 形态 { name, arguments } 传入（与 buildReadOnlyWriteGuard 一致）。 */
 export declare function buildPlanWriteGuard(workspaceRoot: string): (execution: {
     name?: string;
     arguments?: unknown;
 }) => string | undefined;
-/** 按角色在 agent scope 注册工具面（P1-3 统一注册策略）：
- *  所有 kanban 工具从 T9 工厂选取 + getCaller 闭包（actor=role、boundTaskId=taskId）。
+/** 按角色在 agent scope 注册工具面（统一注册策略）：
+ *  所有 kanban 工具从工具工厂选取 + getCaller 闭包（actor=role、boundTaskId=taskId）。
  *  can() 权限兜底仍保留在工具 execute 内（纵深防御第二道）。 */
 export declare function installRoleTools(agentCtx: Context, role: Role, deps: {
     kanban: KanbanService;
     wiki: WikiVaultClient;
     taskId?: string;
+    kbMode?: 'remote' | 'local';
 }): Promise<void>;
 export declare function registerDtTaskChain(taskId: string, chainId: string): void;
 export declare function unregisterDtTaskChain(taskId: string): void;
@@ -60,3 +66,53 @@ export declare function buildSubagentTreeGuard(deps?: SubagentGuardDeps): (execu
     arguments?: unknown;
     agent?: unknown;
 }) => string | undefined;
+/** 蜂群模式主会话硬闸：全局 guard，按 header.agentPreset==='swarm'
+ *  精准判定（先例 buildSubagentTreeGuard）。swarm 会话 = 扩权参数教学拦截（宿主 bash/write/edit
+ *  schema 广播 sandbox_permissions/justification，模型带参重试会触发天花板会话 approveEscalation
+ *  死循环——独立 DT 同款拦截）+ git 反选（与独立 DT 共用 GIT_MUTATION_VERBS/dualVerbGitDenyReason，
+ *  buildPlanWriteGuard 同款分段提取判定，跳过 git 全局选项、提取不到动词 fail-closed，先行判定——
+ *  git 变更动词多数同时命中只读基座的写标记，须以 swarm-guard 文案优先返回）+ 只读基座
+ *  （buildReadOnlyWriteGuard：直接写工具全名拦截 + bash/run_code 写标记）。其余会话恒放行
+ *  （角色会话自有 agent scope 护栏兜底，双保险不叠加）。 */
+export declare function buildSwarmSessionGuard(): (execution: {
+    name?: string;
+    arguments?: unknown;
+    agent?: unknown;
+}) => string | undefined;
+/** 独立评审（standalone DT）全局硬闸。独立会话判定（同时成立）：
+ *  header.agentPreset === 'kanban-dt'、未经角色组合标记（!isRoleComposed）、parentSession
+ *  非 kbn- 前缀（与 buildSubagentTreeGuard 判据对齐：有 kbn- parentSession 的是链上系
+ *  DT 子代理，交由该 guard 管——其 incarnation 可能无组合标记、宿主 id 也可能非 kbn-
+ *  前缀，漏判会把链评审写入误当独立模式拒掉）、且（能从 execution.agent 取到 session
+ *  id 时）id 非 kbn- 前缀。不满足 → 不走独立规则。
+ *  独立模式规则（按序）：
+ *  1. kanban 写工具（complete/block/comment/heartbeat/create）→ 拒（独立评审不挂任务链）；
+ *  2. bash/run_code/write/edit → 扩权参数教学拦截（sandbox_permissions/justification 任一
+ *     出现即拒并教模型去参——只读会话无扩权场景，宿主沙箱校验报错文案晦涩）；bash/run_code
+ *     再过 git 反选（swarm-guard 同款分段提取：&&/||/;/|/换行 分段、跳过全局选项、提取不到
+ *     动词 fail-closed 拒）：仅禁变更动词与双态动词的变更子形态（见 GIT_STANDALONE_DENY_VERBS
+ *     /standaloneGitDenyReason），查询、clone/fetch、裸 checkout/switch 放行；非 git 段不因
+ *     git 规则拒绝；最后挂只读基座 buildReadOnlyWriteGuard（写动词/重定向照拒；clone/fetch
+ *     落盘是 git 自身行为，BASH_WRITE_RE 无此二动词天然放行，无需特判）；
+ *  3. wiki_write（独立模式）→ 仅放行 projects/<repo>/reviews/<主题>-<日期>/ 命名空间；
+ *  4. wiki_write（非独立会话）→ 链上组合会话（isRoleComposed）放行（自有 agent-scope
+ *     guard 管，链命名空间写入绝不被本 guard 误拦）；其余（main/swarm/未知 GUI）拒绝
+ *     ——评审工具全局注册后 wiki_write 收紧到评审会话；
+ *  5. 其余工具（read/glob/grep/ocr_review/wiki_read/wiki_search 等）→ 放行。 */
+export declare function buildStandaloneDtGuard(): (execution: {
+    name?: string;
+    arguments?: unknown;
+    agent?: unknown;
+}) => string | undefined;
+/** 独立评审工具全局注册：ocr_review + wiki 三原语（wiki_read/wiki_search/wiki_write）。
+ *  独立评审不经 agent-runner 角色组合，角色工具面不存在，故在插件全局 ctx 注册；
+ *  caller 固定 actor='dt'（can('wiki-write','dt')=true），wiki_write 的会话级收紧由
+ *  buildStandaloneDtGuard 完成（链上组合会话放行，main/swarm/未知 GUI 拒绝）。
+ *  wiki 客户端按 kbMode 构造（与 registerMainSessionTools 同源：remote 优先 ctx.get('wiki')
+ *  注入（测试 mock），生产热读取 getEffective().wikiVault；local 走 LocalWikiClient）。
+ *  local 模式不注册 wiki_write：LocalWikiClient.abs 只接受 wiki/** 形态，而 wiki_write
+ *  工具边界只放行 projects/... 命名空间——双锁死（任何路径都写不进）。与链上 DT local
+ *  行为一致（走 skill/fs 工具而非 wiki 原语）；wiki_read/wiki_search 不受写路径白名单
+ *  约束，照常注册。
+ *  registry 缺失（测试裸 Context）→ return，与 registerMainSessionTools 同款防御。 */
+export declare function registerStandaloneReviewerTools(ctx: Context, configProvider: ConfigProvider): void;