@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/services/llm-catalog.d.ts

@@ -0,0 +1,35 @@
+export interface CatalogProvider {
+    id: string;
+    name: string;
+}
+export interface CatalogModel {
+    id: string;
+    name: string;
+    efforts: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface LlmCatalog {
+    providers: CatalogProvider[];
+    models: Record<string, CatalogModel[]>;
+}
+export interface LlmRuntimeLike {
+    listProviders(): Array<{
+        id: string;
+        name: string;
+    }>;
+    listModels(provider: string): Promise<Array<{
+        id: string;
+        name: string;
+    }>>;
+    resolveModelInfo(provider: string, model: string): Promise<{
+        reasoning?: {
+            efforts?: Array<{
+                id: string;
+                name: string;
+            }>;
+        };
+    }>;
+}
+export declare function buildLlmCatalog(llm: LlmRuntimeLike): Promise<LlmCatalog>;

package/lib/services/llm-catalog.js

@@ -0,0 +1,19 @@
+export async function buildLlmCatalog(llm) {
+    const providers = llm.listProviders().map((p) => ({ id: p.id, name: p.name }));
+    const models = {};
+    for (const p of providers) {
+        const list = await llm.listModels(p.id);
+        const entries = [];
+        for (const m of list) {
+            let efforts = [];
+            try {
+                const info = await llm.resolveModelInfo(p.id, m.id);
+                efforts = (info.reasoning?.efforts ?? []).map((e) => ({ id: e.id, name: e.name }));
+            }
+            catch { /* effort 解析失败 → 空 */ }
+            entries.push({ id: m.id, name: m.name, efforts });
+        }
+        models[p.id] = entries;
+    }
+    return { providers, models };
+}

package/lib/services/ocr-cli.d.ts

@@ -0,0 +1,35 @@
+/** ocr CLI runner（@alibaba-group/open-code-review 命令行）：二进制定位、探活、执行与托管 provider 配置。
+ * 踩坑警告：插件进程 PATH 常缺 npm 全局 bin 目录，不能裸依赖 PATH 找 ocr（社区方案踩过）——
+ * 故按常见 npm 全局 bin 目录逐个探测并进程内缓存定位结果。 */
+import { execFile } from 'node:child_process';
+export declare const OCR_PACKAGE = "@alibaba-group/open-code-review";
+export declare const OCR_MANAGED_PROVIDER_NAME = "dsh-managed";
+export declare const INSTALL_GUIDANCE: string;
+export type OcrCliDeps = {
+    execFileFn?: typeof execFile;
+    env?: NodeJS.ProcessEnv;
+    homedirFn?: () => string;
+};
+export declare function probeOcr(deps?: OcrCliDeps): Promise<{
+    installed: boolean;
+    version: string;
+    binPath: string | null;
+}>;
+export declare function runOcr(args: string[], opts: {
+    cwd: string;
+    timeoutMs?: number;
+}, deps?: OcrCliDeps): Promise<{
+    stdout: string;
+    stderr: string;
+    error?: string;
+}>;
+export declare function managedProviderReady(deps?: OcrCliDeps): boolean;
+export declare function wireManagedProvider(a: {
+    baseUrl: string;
+    protocol: 'openai' | 'anthropic';
+    apiKey: string;
+    model: string;
+}, deps?: OcrCliDeps): Promise<{
+    ok: boolean;
+    log: string;
+}>;

package/lib/services/ocr-cli.js

@@ -0,0 +1,128 @@
+// src/services/ocr-cli.ts
+/** ocr CLI runner（@alibaba-group/open-code-review 命令行）：二进制定位、探活、执行与托管 provider 配置。
+ * 踩坑警告：插件进程 PATH 常缺 npm 全局 bin 目录，不能裸依赖 PATH 找 ocr（社区方案踩过）——
+ * 故按常见 npm 全局 bin 目录逐个探测并进程内缓存定位结果。 */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+export const OCR_PACKAGE = '@alibaba-group/open-code-review';
+export const OCR_MANAGED_PROVIDER_NAME = 'dsh-managed';
+export const INSTALL_GUIDANCE = [
+    `未检测到 ocr CLI（${OCR_PACKAGE}）。`,
+    `请二选一安装：在 GUI 配置面板点击「安装 ocr」按钮；或在终端执行 \`npm install -g ${OCR_PACKAGE}\`。`,
+    '安装后执行 `ocr --version` 验证。',
+    '托管模式下 ocr 的模型 provider 由本插件统一接管配置，无需手工登录。',
+].join('');
+const BIN_NAME = 'ocr';
+/** 版本号分段数值比较（升序）：'v22.22.2' 与 'v9.1.0' 字符串比较会错序，必须逐段转数字。 */
+function versionAsc(a, b) {
+    const pa = a.replace(/^v/, '').split('.');
+    const pb = b.replace(/^v/, '').split('.');
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = Number(pa[i] ?? 0) - Number(pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** 扫描目录序：进程 PATH（nvm 激活版本在其中）→ nvm versions 布局取最新 → 常见固定 bin 目录。
+ * 踩坑：标准 nvm 布局是 ~/.nvm/versions/node/<ver>/bin，~/.nvm/current 软链仅部分环境存在，
+ * 只扫后者会漏掉 npm install -g 的真实落点（GUI 安装成功但探活判未安装的根因）。 */
+const scanBinDirs = (home, env) => {
+    const dirs = (env.PATH ?? '').split(delimiter).filter(Boolean);
+    const nvmRoot = join(home, '.nvm', 'versions', 'node');
+    try {
+        for (const v of readdirSync(nvmRoot).sort(versionAsc).reverse())
+            dirs.push(join(nvmRoot, v, 'bin'));
+    }
+    catch { /* 无 nvm 目录：跳过 */ }
+    dirs.push(join(home, '.nvm', 'current', 'bin'), '/opt/homebrew/bin', '/usr/local/bin', join(home, '.local', 'bin'));
+    return dirs;
+};
+/** 进程内缓存按 homedir 隔离，避免注入不同 home 时串路径；命中后仍需 existsSync 复核（文件可能已被删）。 */
+let cached = null;
+function resolveBin(deps = {}) {
+    const env = deps.env ?? process.env;
+    const fromEnv = env.OCR_OCR_BIN;
+    if (fromEnv)
+        return fromEnv; // 显式指定优先，不进缓存
+    const home = deps.homedirFn ? deps.homedirFn() : homedir();
+    if (cached && cached.homedir === home && existsSync(cached.binPath))
+        return cached.binPath;
+    for (const dir of scanBinDirs(home, env)) {
+        const candidate = join(dir, BIN_NAME);
+        if (existsSync(candidate)) {
+            cached = { homedir: home, binPath: candidate };
+            return candidate;
+        }
+    }
+    return null; // 未命中不缓存，留待下次重扫
+}
+export async function probeOcr(deps = {}) {
+    const binPath = resolveBin(deps);
+    if (!binPath)
+        return { installed: false, version: '', binPath: null };
+    try {
+        const run = promisify(deps.execFileFn ?? execFile);
+        // 始终传 options 对象：保持 (bin, args, opts, cb) 四参调用形态，promisify 包装的回调式 fake/真实现均兼容
+        const { stdout } = await run(binPath, ['--version'], {});
+        return { installed: true, version: stdout.split('\n')[0].trim(), binPath };
+    }
+    catch {
+        // 探活失败（含 ENOENT）：定位结果仍保留，供上层展示/诊断
+        return { installed: false, version: '', binPath };
+    }
+}
+export async function runOcr(args, opts, deps = {}) {
+    const binPath = resolveBin(deps);
+    if (!binPath)
+        return { stdout: '', stderr: INSTALL_GUIDANCE, error: 'ocr-not-installed' };
+    const run = promisify(deps.execFileFn ?? execFile);
+    try {
+        const { stdout, stderr } = await run(binPath, args, {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs ?? 600_000,
+            maxBuffer: 64 * 1024 * 1024,
+            windowsHide: true,
+        });
+        return { stdout, stderr };
+    }
+    catch (err) {
+        // 绝不抛出：非零退出/超时/ENOENT 统一转结果对象（promisify 拒因自带 stdout/stderr）
+        const e = err;
+        return {
+            stdout: typeof e.stdout === 'string' ? e.stdout : '',
+            stderr: typeof e.stderr === 'string' ? e.stderr : '',
+            error: e.message ?? String(err),
+        };
+    }
+}
+export function managedProviderReady(deps = {}) {
+    try {
+        const home = deps.homedirFn ? deps.homedirFn() : homedir();
+        const cfg = JSON.parse(readFileSync(join(home, '.opencodereview', 'config.json'), 'utf8'));
+        return cfg.provider === OCR_MANAGED_PROVIDER_NAME && typeof cfg.model === 'string' && cfg.model.length > 0;
+    }
+    catch {
+        return false; // 文件不存在/解析失败/字段缺失一律视为未就绪
+    }
+}
+export async function wireManagedProvider(a, deps = {}) {
+    // ocr 官方非交互配置：五组 config set 按序写入自定义 provider
+    const steps = [
+        ['provider', ['config', 'set', 'provider', OCR_MANAGED_PROVIDER_NAME]],
+        ['model', ['config', 'set', 'model', a.model]],
+        ['providers.dsh-managed.url', ['config', 'set', 'providers.dsh-managed.url', a.baseUrl]],
+        ['providers.dsh-managed.protocol', ['config', 'set', 'providers.dsh-managed.protocol', a.protocol]],
+        ['providers.dsh-managed.api_key', ['config', 'set', 'providers.dsh-managed.api_key', a.apiKey]],
+    ];
+    const home = deps.homedirFn ? deps.homedirFn() : homedir();
+    for (const [name, args] of steps) {
+        const r = await runOcr(args, { cwd: home, timeoutMs: 120_000 }, deps);
+        if (r.error)
+            return { ok: false, log: `config set ${name} 失败: ${r.error} ${r.stderr.slice(0, 500)}`.trim() };
+    }
+    return { ok: true, log: 'ocr managed provider wired: dsh-managed' };
+}

package/lib/tools/kanban-tools.d.ts

@@ -1,11 +1,11 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import { type Actor } from '../domain/permissions.js';
 /** 工具执行上下文：由角色 agent scope 注入；主会话=human；调度器=system。
- *  boundTaskId：角色 agent 会话绑定的任务（AgentSessionRef.task_id，P1-4 会话绑定）。 */
+ *  boundTaskId：角色 agent 会话绑定的任务（AgentSessionRef.task_id）。 */
 export interface ToolCaller {
     actor: Actor;
     boundTaskId?: string;
 }
-/** 工具定义工厂（P1-3）：不直接注册；由 T15 toolsets 按角色 agent-scope 装配，或由主会话注册其专属子集。
+/** 工具定义工厂：不直接注册；由 toolsets 按角色 agent-scope 装配，或由主会话注册其专属子集。
  *  getCaller：装配方提供的闭包（捕获 actor/boundTaskId），execute 内取用——不依赖 execute 第二参数（DSH ToolRunContext 真实形状以官方为准）。 */
 export declare function buildKanbanTools(service: KanbanService, getCaller: () => ToolCaller): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/kanban-tools.js

@@ -1,11 +1,12 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { KanbanService } from '../domain/kanban-service.js';
 import { can } from '../domain/permissions.js';
 function guard(action, caller, task = null) {
     if (!can(action, caller.actor, task))
         throw new Error('permission denied: ' + action);
 }
-/** 工具定义工厂（P1-3）：不直接注册；由 T15 toolsets 按角色 agent-scope 装配，或由主会话注册其专属子集。
+/** 工具定义工厂：不直接注册；由 toolsets 按角色 agent-scope 装配，或由主会话注册其专属子集。
  *  getCaller：装配方提供的闭包（捕获 actor/boundTaskId），execute 内取用——不依赖 execute 第二参数（DSH ToolRunContext 真实形状以官方为准）。 */
 export function buildKanbanTools(service, getCaller) {
     return [

package/lib/tools/main-session-tools.d.ts

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { KanbanConfig } from '../config.js';
+import type { PrefixRoutes } from '../config.js';
+import type { ConfigProvider } from '../services/config-provider.js';
 import { type PlanningToolDeps } from './planning-tools.js';
 import type { PlanningChecklist } from '../domain/planning-checklist.js';
 /** v2 规划上下文（/plan: 捕获 → planning_checklist_save 回写 → /openspec: 建链）。模块级内存，随插件进程存活。 */
@@ -9,12 +10,30 @@ export interface PlanningContext {
     checklist: PlanningChecklist | null;
     checklistRef: string | null;
     checklistSource: 'kb' | 'temp' | null;
-    /** T7：/plan: rest 原始需求描述（建链默认标题来源，优先级最高）。 */
+    /** /plan: rest 原始需求描述（建链默认标题来源，优先级最高）。 */
     requirementName: string | null;
+    /** 蜂群模式标记：kanban_route 触发方式（intent=swarm / 前缀=prefix）；planning_checklist_save 指导文案分叉数据源。 */
+    mode?: 'swarm' | 'prefix' | null;
 }
 export declare const planningBySession: Map<string, PlanningContext>;
+export declare const KANBAN_HANDOFF_RULE: (routes: PrefixRoutes, opts?: {
+    swarm?: boolean;
+}) => string;
+/** 防线③：/openspec: 成功后的逐链确定性叙述规则（2026-09-04 mtmgp81q：模型口播 ch_1_mtjrhkrf
+ *  与工具结果 ch_1_mtmgp81q 脱节）。逐字引用锚点 + firstCard 成败结论；整包缓存回放仍可能
+ *  绕过 prompt 层——最终防线是链级看门狗（防线①）。 */
+export declare function buildOpenspecNarrationRule(r: {
+    chainId: string;
+    specCardId: string;
+    firstCard?: {
+        taskId: string;
+        status: string;
+    } | {
+        pending: true;
+    };
+}): string;
 export declare function buildSpawnPrefetch(ctx: Context): PlanningToolDeps['spawnPrefetch'] | undefined;
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
-export declare function registerMainSessionTools(ctx: Context, config: KanbanConfig): void;
+export declare function registerMainSessionTools(ctx: Context, configProvider: ConfigProvider): void;

package/lib/tools/main-session-tools.js

@@ -1,25 +1,57 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { tmpdir } from 'node:os';
 import { KanbanProvider } from '../services/kanban-provider.js';
 import { buildKanbanTools } from './kanban-tools.js';
 import { buildSpecCardTools } from './spec-card-tools.js';
 import { buildPlanningTools } from './planning-tools.js';
 import { handlePlanRoute, handleOpenspecRoute, handleLearningRoute } from '../routes/prefix-router.js';
+import { sendChainReport } from '../services/im-delivery.js';
 import { recallMemoryIndex, searchChecklists } from '../wiki/memory-recall.js';
 import { buildPlanningGuidance } from '../routes/planning-driver.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from '../dispatcher/workspace-attach.js';
 import { PREFETCH_MANIFEST_SCHEMA } from '../domain/prefetch-manifest.js';
 import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import { LocalWikiClient } from '../wiki/local-kb-client.js';
+import { ensureLocalKbRoot } from '../wiki/local-kb.js';
+import { LOCAL_CHECKLIST_PREFIX } from '../wiki/page-path.js';
 export const planningBySession = new Map();
-const KANBAN_HANDOFF_RULE = (routes) => `
+export const KANBAN_HANDOFF_RULE = (routes, opts) => {
+    const confirmLine = opts?.swarm
+        ? `- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单。
+- 确认闸：清单落库后向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链；模糊、岔开话题、只提修改意见 = 未确认，继续澄清。禁止未确认建链。`
+        : `- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单 → 提醒用户 ${routes.openspec} 确认。`;
+    const nextLine = opts?.swarm
+        ? `- 用户确认后你调 kanban_route{intent:'openspec'}；链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。`
+        : `- ${routes.openspec} 后链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。`;
+    return `
 ## 主 agent 铁律（看板工作流 v2）
 - 你是计划者：只做需求澄清（grill-me）与最终收尾汇报；绝不执行任务本身。
 - 最高护栏：只读仓库——禁止 git 操作、禁止 write/edit 任何仓库源码；只允许写 KB（planning_checklist_save）与临时目录兜底。
-- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单 → 提醒用户 ${routes.openspec} 确认。
-- ${routes.openspec} 后链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。
+${confirmLine}
+${nextLine}
 - 用 kanban_show / kanban_list / spec_card_view 观察进度，链完成后向用户汇报产物链接与轨迹入口。
 - 经验沉淀：链路完成后，用户可发 ${routes.learning}（或 ${routes.learning} <chainId>）沉淀本链经验；主 agent 消化机械证据包后调 planning_learning_save 入库。
+- 叙述铁律：回复中的链号/卡号（ch_/sc_/t_ 编号）只能逐字复制自工具结果；建链成败以工具结果字段为准，禁止编造或沿用旧对话里的编号。
 `;
+};
+/** 防线③：/openspec: 成功后的逐链确定性叙述规则（2026-09-04 mtmgp81q：模型口播 ch_1_mtjrhkrf
+ *  与工具结果 ch_1_mtmgp81q 脱节）。逐字引用锚点 + firstCard 成败结论；整包缓存回放仍可能
+ *  绕过 prompt 层——最终防线是链级看门狗（防线①）。 */
+export function buildOpenspecNarrationRule(r) {
+    const firstCardLine = !r.firstCard
+        ? '- 首卡结果未采集（旧返回体）。汇报前先调 kanban_show 复核链状态，以 kanban_show 复核后再汇报，禁止臆断建卡成功。'
+        : 'pending' in r.firstCard
+            ? `- 首卡尚未创建（等待超时，看门狗接管）。回复必须写明「首卡尚未创建，看门狗接管」，禁止声称建卡成功。`
+            : `- 首卡已创建：taskId=${r.firstCard.taskId}（status=${r.firstCard.status}）。回复必须写明「首卡已创建」。`;
+    return [
+        '## 本次建链结果（回复必须逐字引用，禁止改写编号）',
+        `- chainId=${r.chainId}`,
+        `- specCardId=${r.specCardId}`,
+        firstCardLine,
+        '- 铁律：回复中的 ch_/sc_/t_ 编号只能逐字复制自本结果；禁止出现本结果之外的任何编号；禁止声称与本结果矛盾的建卡状态。',
+    ].join('\n');
+}
 // 清单获取只有两条路：内存（路由1）> KB 候选页（路由2，LLM 读页重建）。禁止编造其他原因
 // （"先重试 / 查服务进程是否重启"类诊断是噪声：内存丢失唯一成因是插件重启，重启后按两条路恢复即可）。
 const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
@@ -28,7 +60,7 @@ const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
 ${candidates.map((c) => '- ' + c).join('\n')}
 恢复步骤（严格顺序）：
 1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
-2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts，requirementName 取页标题中【需求】后的名称）；
+2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；
 3. 调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页）；
 4. 回存成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
@@ -89,17 +121,21 @@ export function buildSpawnPrefetch(ctx) {
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
-export function registerMainSessionTools(ctx, config) {
+export function registerMainSessionTools(ctx, configProvider) {
     const registry = ctx.get('tools');
     if (!registry)
-        return; // 测试裸 Context 无 tools 服务（P1-9 无 inject 依赖），跳过注册
+        return; // 测试裸 Context 无 tools 服务，跳过注册
     const provider = ctx.get('kanban');
     if (!provider)
         return;
     const service = provider.service;
-    // 生产 wiring（src/index.ts:44）仅保证 tools+kanban 可用，无 wiki 服务 → 用 config.wikiVault 自建
-    //（与 dispatcher 构造同源）；测试经 ctx.get('wiki') 注入 mock 客户端。
-    const wiki = ctx.get('wiki') ?? new WikiVaultClient(config.wikiVault);
+    // 生产 wiring（src/index.ts）仅保证 tools+kanban 可用，无 wiki 服务 → 经 configProvider 自建
+    //（与 dispatcher 构造同源，getEffective() 调用时热读取 baseUrl/pagePrefix）；测试经 ctx.get('wiki') 注入 mock 客户端。
+    // 双模式：local 模式走 LocalWikiClient 本地检索（不发 HTTP），remote 用配置的 WikiVaultClient。
+    const kbMode = configProvider.mode;
+    const wiki = kbMode === 'local'
+        ? new LocalWikiClient(ensureLocalKbRoot())
+        : (ctx.get('wiki') ?? new WikiVaultClient(() => configProvider.getEffective().wikiVault));
     const caller = () => ({ actor: 'human' });
     // 只读 kanban 子集（无 create/complete/block）
     const readOnly = new Set(['kanban_show', 'kanban_chain', 'kanban_list', 'kanban_comment']);
@@ -115,13 +151,16 @@ export function registerMainSessionTools(ctx, config) {
     }
     // planning 工具（清单落库 + 只读预取）——spawnPrefetch 由模块级 buildSpawnPrefetch 提供（可单测）
     for (const tool of buildPlanningTools({
-        service, wiki,
+        service, wiki: wiki, // local 模式为 LocalWikiClient（write/read/search 同面，双模式客户端）
         getCaller: caller,
         spawnPrefetch: buildSpawnPrefetch(ctx),
         tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
-        pagePrefix: config.wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
-        prefixRoutes: config.prefixRoutes,
-        memoryEnabled: config.memory?.enabled ?? true,
+        pagePrefix: configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
+        kbMode: configProvider.mode, // 双模式：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/）
+        prefixRoutes: configProvider.getEffective().prefixRoutes,
+        memoryEnabled: configProvider.getEffective().memory?.enabled ?? true,
+        resolveWorkspaceDir: () => planningBySession.get('session_main')?.workspaceDir ?? null,
+        flowMode: () => planningBySession.get('session_main')?.mode ?? null,
         ownerSessionId: 'session_main',
         onChecklistSaved({ ref, source, checklist }) {
             const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
@@ -129,28 +168,40 @@ export function registerMainSessionTools(ctx, config) {
         },
     }))
         registry.register(tool);
-    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链
-    const { plan, openspec, learning } = config.prefixRoutes;
+    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链；/sms 手动投递链报告（前缀路由注册时快照，用于工具描述）
+    const { plan, openspec, learning, send } = configProvider.getEffective().prefixRoutes;
     registry.register(defineTool({
         name: 'kanban_route',
-        description: `MUST be called when the human message starts with ${plan}, ${openspec}, or ${learning}. This is dsh-swarm planning, NOT the built-in /plan plan mode. ${plan} = zero side-effect + start grill-me (+ auto KB memory index); ${openspec} = create chain from saved checklist; ${learning} = distill experience from a chain (evidence pack + planning_learning_save).`,
-        parameters: { message: { type: 'string', required: true } },
+        description: `Route hub for dsh-swarm kanban workflow (NOT the built-in /plan plan mode). Two trigger forms. (1) PREFIX form — MUST be called when the human message starts with ${plan}, ${openspec}, ${learning}, or ${send}; omit intent. (2) INTENT form (swarm preset sessions) — MUST be called with intent when the human expresses: a hands-on development requirement → intent='plan'; explicit approval to start the workflow after the checklist was saved → intent='openspec'; distill/retrospect lessons from a chain → intent='learning' (message = chainId or title words, may be empty = latest chain); deliver a chain report to the WeCom group → intent='send' (block notice: prefix message with 'blocked '). When intent is set, message = the user's raw words (no prefix). Ambiguous intent → do NOT call, ask the user instead. Semantics: ${plan} = zero side-effect + start grill-me (+ auto KB memory index); ${openspec} = create chain from saved checklist; ${learning} = distill experience from a chain (evidence pack + planning_learning_save); ${send} = manually deliver a chain report to the WeCom group (bare = latest completed chain; '${send} blocked [chainId]' = resend block notice; bypasses imDelivery.enabled; the message body is composed by system code — never compose or repeat it, only relay the delivery status).`,
+        parameters: { message: { type: 'string', required: true }, intent: { type: 'string', description: "swarm preset sessions: 'plan' | 'openspec' | 'learning' | 'send' — model-judged intent; omit for prefix-triggered calls" } },
         output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
         async execute(args, exec) {
-            // M2(Q5)+归组：仅 /plan: 分支捕获主 agent 工作空间并可能询问注册——/openspec:/none 不触发，
-            // 避免死代码副作用多弹一次 ask（/openspec: 实际用的是 planningBySession 已存的 workspaceDir）。
-            // header.cwd 缺失或未注册时询问用户注册工作区；仍不可得保持 null（链任务随后 block 'workspace-unknown'）。
-            const plan = await handlePlanRoute(args.message, service, config.prefixRoutes, 'session_main');
+            // intent 路径（蜂群模式）：handler 内部会重 parsePrefix(message)，无前缀 message
+            // 会判成 none —— 因此 intent 命中时合成「前缀 + rest」消息再进 handler；handler 零改动、
+            // 前缀路径零感知。intent 优先于 message 前缀；非法 intent 回退 parsePrefix（none 兜底）。
+            // 简报矛盾修正：intent 命中时 message 若自带已知前缀（模型契约
+            // 违例，description 明文 raw words no prefix），原样拼接会使 rest 带旧前缀 → handler 内必
+            // chain-not-found → brief 断言不可能绿；故丢弃载荷只保留 intent 裸前缀
+            //（learning 裸 = 最近链，与既有 '/learning' 语义一致）。raw words 正常路径与简报逐字节一致。
+            const routes = configProvider.getEffective().prefixRoutes;
+            const INTENTS = ['plan', 'openspec', 'learning', 'send'];
+            const intent = INTENTS.includes(args.intent ?? '') ? args.intent : null;
+            const trimmed = args.message.trim();
+            const routeMessage = intent
+                ? `${routes[intent]}${trimmed && !INTENTS.some((k) => trimmed.startsWith(routes[k])) ? ' ' + trimmed : ''}`
+                : args.message;
+            const plan = await handlePlanRoute(routeMessage, service, routes, 'session_main');
             if (plan.kind === 'plan') {
                 const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
                 const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话');
-                planningBySession.set('session_main', { workspaceDir, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: plan.rest });
-                let guidance = buildPlanningGuidance(config.prefixRoutes) + KANBAN_HANDOFF_RULE(config.prefixRoutes);
-                if ((config.memory?.enabled ?? true) && workspaceDir) {
+                planningBySession.set('session_main', { workspaceDir, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: plan.rest, mode: intent ? 'swarm' : 'prefix' });
+                let guidance = buildPlanningGuidance(configProvider.getEffective().prefixRoutes, { swarm: intent === 'plan' }) + KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes, { swarm: intent === 'plan' });
+                if ((configProvider.getEffective().memory?.enabled ?? true) && workspaceDir) {
                     const idx = await recallMemoryIndex(wiki, {
                         requirementName: plan.rest || null,
                         workspaceDir,
-                        maxEntries: config.memory?.maxIndexEntries ?? 8,
+                        maxEntries: configProvider.getEffective().memory?.maxIndexEntries ?? 8,
+                        kbMode,
                     });
                     if (idx)
                         guidance += '\n' + idx;
@@ -158,31 +209,85 @@ export function registerMainSessionTools(ctx, config) {
                 return { kind: 'plan', guidance };
             }
             if (plan.kind === 'learning') {
-                const r = await handleLearningRoute(args.message, service, config.prefixRoutes, 'session_main');
+                const r = await handleLearningRoute(routeMessage, service, configProvider.getEffective().prefixRoutes, 'session_main');
                 if (r.error)
                     return { kind: 'learning', error: r.error, guidance: r.guidance };
                 return { kind: 'learning', chainId: r.chainId, brief: r.brief, guidance: r.guidance };
             }
+            if (plan.kind === 'send') {
+                // /sms 手动投递：rest 'blocked [chainId]' → 阻塞通知；其余 → 完成汇报（query = rest）。
+                // 红线：消息正文由 sendChainReport 内的领域函数渲染并发送，本分支只返回投递状态（绝不含正文）。
+                const rest = plan.rest;
+                const variant = rest.startsWith('blocked') ? 'blocked' : 'completion';
+                const query = variant === 'blocked' ? rest.slice('blocked'.length).trim() : rest;
+                const r = await sendChainReport(ctx, service, configProvider, { retryDelaysMs: [] }, variant, query);
+                if (r.ok) {
+                    const noun = variant === 'blocked' ? '阻塞通知' : '完成汇报';
+                    return {
+                        kind: 'send', chainId: r.chainId, botId: r.botId, targetId: r.targetId,
+                        guidance: `${noun}已投递企微群（/sms 手动触发）。请仅向用户确认投递成功与目标群，勿复述消息正文。`,
+                    };
+                }
+                return { kind: 'send', error: r.error, guidance: r.guidance ?? '请将 error 字段原样转告用户，勿复述消息正文。' };
+            }
             if (plan.kind === 'none')
                 return { kind: 'none' };
             // 路由1（内存）：planningBySession 命中 → 直接建链
             const pctx = planningBySession.get('session_main');
             if (pctx?.checklist && pctx.checklistRef) {
+                // 恢复补捕①：内存有清单但 workspaceDir=null（主 agent 重启后清单经 KB 恢复、异常态）→
+                // 从 exec.agent.session.header.cwd 捡回工作区，路由1 继续正常建链。已有值绝不重解析
+                // （不重复弹 ask，对齐下方 /plan: 分支注释顾虑）；解析 null（无 cwd/无通道/用户跳过）保持
+                // 现状 → 走 handleOpenspecRoute 的 workspace-unknown fail-fast（不吞错、不猜测路径）。
+                if (!pctx.workspaceDir) {
+                    const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
+                    const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
+                    if (workspaceDir) {
+                        pctx.workspaceDir = workspaceDir;
+                        planningBySession.set('session_main', pctx);
+                    }
+                }
+                // 闸2：清单落库的仓库与当前工作区不一致 → 硬拦不建链（KB 页路径带 repoSlug 维度的前提是链与工作区同源）
+                const localPath = pctx.checklist.manifest.repo.localPath;
+                if (pctx.workspaceDir && localPath !== pctx.workspaceDir) {
+                    return {
+                        kind: 'openspec', approved: false, reason: 'workspace-mismatch',
+                        error: `[workspace-mismatch] 清单 manifest.repo.localPath (${localPath}) 与当前工作区 (${pctx.workspaceDir}) 不一致。请在目标仓库工作区内重新执行 ${configProvider.getEffective().prefixRoutes.plan} 重新澄清落库后再 ${configProvider.getEffective().prefixRoutes.openspec}（不可跳过）。`,
+                    };
+                }
                 const input = { workspaceDir: pctx.workspaceDir, checklist: pctx.checklist, checklistRef: pctx.checklistRef, requirementName: pctx.requirementName };
-                const r = await handleOpenspecRoute(args.message, service, config.prefixRoutes, input, 'session_main');
-                return { kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, guidance: KANBAN_HANDOFF_RULE(config.prefixRoutes) };
+                const r = await handleOpenspecRoute(routeMessage, service, configProvider.getEffective().prefixRoutes, input, 'session_main');
+                // 护栏拦截（如 workspace-unknown）：透传失败原因与恢复指引，不得伪装成建链成功
+                if (r.approved === false || !r.chainId || !r.specCardId) {
+                    return { kind: 'openspec', approved: false, reason: r.reason ?? 'unknown', guidance: r.guidance };
+                }
+                return {
+                    kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, firstCard: r.firstCard,
+                    guidance: KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes, { swarm: planningBySession.get('session_main')?.mode === 'swarm' }) + '\n\n' + buildOpenspecNarrationRule({ chainId: r.chainId, specCardId: r.specCardId, firstCard: r.firstCard }),
+                };
             }
             // 路由2（知识库）：内存丢失（插件重启）→ 搜 KB 候选清单页供 LLM 读页重建；搜不到/不可达 → 两条路皆空
+            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession（checklist 等
+            // 字段保持 cur 或空缺省），后续 planning_checklist_save 触发 onChecklistSaved 的 { ...cur } 展开自然
+            // 带上 workspaceDir。解析失败不阻塞恢复 guidance 返回（行为同现状，只是少捕一次）。
+            if (!planningBySession.get('session_main')?.workspaceDir) {
+                const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
+                const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
+                if (workspaceDir) {
+                    const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
+                    planningBySession.set('session_main', { ...cur, workspaceDir });
+                }
+            }
             let candidates = [];
             try {
-                candidates = await searchChecklists(wiki, config.wikiVault?.pagePrefix ?? 'projects/');
+                candidates = await searchChecklists(wiki, kbMode === 'local' ? LOCAL_CHECKLIST_PREFIX : (configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/'));
             }
             catch { /* KB 不可达/搜索失败 → 候选为空，走两条路皆空分支 */ }
             return {
                 kind: 'openspec', approved: false, reason: 'no-checklist',
                 recovery: candidates.length > 0 ? 'kb' : 'none',
                 checklistCandidates: candidates,
-                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(config.prefixRoutes, candidates) : RECOVERY_NONE_GUIDANCE(config.prefixRoutes),
+                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(configProvider.getEffective().prefixRoutes, candidates) : RECOVERY_NONE_GUIDANCE(configProvider.getEffective().prefixRoutes),
             };
         },
     }));

package/lib/tools/ocr-review-tools.d.ts

@@ -0,0 +1,11 @@
+/** ocr_review 工具：把 ocr CLI 三子命令（preview/rule/managed）封装为 cordis 工具，DT 评审角色工具面注册。
+ * 依赖全注入可换 fake（tests），缺省用 ocr-cli 真实现。 */
+import { type ToolDefinition as ToolDef } from '@deepseek-ai/dsh-tools';
+import { managedProviderReady, probeOcr, runOcr } from '../services/ocr-cli.js';
+/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。 */
+export declare function buildOcrReviewTool(deps: {
+    runOcrFn?: typeof runOcr;
+    probeFn?: typeof probeOcr;
+    managedReadyFn?: typeof managedProviderReady;
+    cwd?: () => string;
+}): ToolDef;