@joekytc/dsh-swarm 0.2.0 → 0.3.1

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

@@ -6,6 +6,7 @@ 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, createSender, parseSendRequest, resolveReportChainId, DSH_IM_MISSING_PREFIX, DSH_IM_MISSING_GUIDANCE } 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';
@@ -15,16 +16,25 @@ 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();
-export 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 层——最终防线是链级看门狗（防线①）。 */
@@ -108,20 +118,33 @@ export function buildSpawnPrefetch(ctx) {
         }
     };
 }
-/** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
+/** 自由投递 guidance：三步教学（实查基准 → 生成正文 → sms_send 投递）+ 红线分界。 */
+function buildFreeSendGuidance(routes, query, dm) {
+    return [
+        '## 自由投递指令（' + routes.send + '）',
+        '用户意图：' + query + '；投递目标：' + (dm ? '私聊' : '群聊') + '。',
+        '1. 先 kanban_show / kanban_list 实查看板与相关链状态，取得事实基准；禁止编造数据、禁止虚构进度。',
+        '2. 按用户意图撰写中文正文（≤4000 字符，先结论后细节）。本自由投递正文由你撰写（显式豁免）；但链完成/阻塞汇报正文由系统渲染，你始终不撰写、不复述、不改写。',
+        '3. ' + (dm
+            ? '调 sms_send{text: <正文>, dm: true} 投递（目标为私聊，已由 -s/私聊语义确定）。'
+            : '调 sms_send{text: <正文>, dm: false} 投递；若用户消息含「私聊/私信/单聊」语义，改传 dm: true（目标为私聊）。'),
+        '投递结果只向用户确认成功与目标，不复述正文；失败时把 error/guidance 原样转告，勿编造原因。',
+    ].join('\n');
+}
+/** 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, 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）仅保证 tools+kanban 可用，无 wiki 服务 → 经 configProvider 自建
     //（与 dispatcher 构造同源，getEffective() 调用时热读取 baseUrl/pagePrefix）；测试经 ctx.get('wiki') 注入 mock 客户端。
-    // D3 双模式：local 模式走 LocalWikiClient 本地检索（不发 HTTP），remote 用配置的 WikiVaultClient。
+    // 双模式：local 模式走 LocalWikiClient 本地检索（不发 HTTP），remote 用配置的 WikiVaultClient。
     const kbMode = configProvider.mode;
     const wiki = kbMode === 'local'
         ? new LocalWikiClient(ensureLocalKbRoot())
@@ -141,15 +164,16 @@ export function registerMainSessionTools(ctx, configProvider) {
     }
     // planning 工具（清单落库 + 只读预取）——spawnPrefetch 由模块级 buildSpawnPrefetch 提供（可单测）
     for (const tool of buildPlanningTools({
-        service, wiki: wiki, // local 模式为 LocalWikiClient（write/read/search 同面，D3 双模式客户端）
+        service, wiki: wiki, // local 模式为 LocalWikiClient（write/read/search 同面，双模式客户端）
         getCaller: caller,
         spawnPrefetch: buildSpawnPrefetch(ctx),
         tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
         pagePrefix: configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
-        kbMode: configProvider.mode, // D3 双模式：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/）
+        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 };
@@ -157,23 +181,34 @@ export function registerMainSessionTools(ctx, configProvider) {
         },
     }))
         registry.register(tool);
-    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链（前缀路由注册时快照，用于工具描述）
-    const { plan, openspec, learning } = configProvider.getEffective().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, or free-form delivery of user-intent content → 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; any other non-empty message = free-form delivery: compose a fact-grounded body per the returned guidance and call sms_send (append ' -s' to the message or mention 私聊 for private chat)).`,
+        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, configProvider.getEffective().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(configProvider.getEffective().prefixRoutes) + KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes);
+                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,
@@ -187,11 +222,41 @@ export function registerMainSessionTools(ctx, configProvider) {
                 return { kind: 'plan', guidance };
             }
             if (plan.kind === 'learning') {
-                const r = await handleLearningRoute(args.message, service, configProvider.getEffective().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 三岔：先链后自由。blocked 前缀/空 rest/链 id 命中 → 既有机械汇报（正文系统渲染，红线不变）；
+                // 其余非空 rest → 自由投递（正文由主 agent 按意图生成，显式豁免；事实基准=看板实查）。
+                // -s 独立 token 由 parseSendRequest 剥离置 dm；manual 路径零重试。
+                const parsed = parseSendRequest(plan.rest);
+                const targetOpts = { retryDelaysMs: [], manual: true, targetKind: (parsed.dm ? 'user' : 'group') };
+                const deliver = async (variant, query) => {
+                    const r = await sendChainReport(ctx, service, configProvider, targetOpts, variant, query);
+                    if (r.ok) {
+                        const noun = variant === 'blocked' ? '阻塞通知' : '完成汇报';
+                        const dest = parsed.dm ? '私聊' : '群聊';
+                        return {
+                            kind: 'send', chainId: r.chainId, botId: r.botId, targetId: r.targetId,
+                            guidance: `${noun}已投递${dest}（/sms 手动触发）。请仅向用户确认投递成功与目标，勿复述消息正文。`,
+                        };
+                    }
+                    return { kind: 'send', error: r.error, guidance: r.guidance ?? '请将 error 字段原样转告用户，勿复述消息正文。' };
+                };
+                if (parsed.variant !== 'free')
+                    return deliver(parsed.variant === 'blocked' ? 'blocked' : 'completion', parsed.query);
+                // free 候选复判链：显式 id 命中/歧义/判据不满足都归链汇报路径，仅 chain-not-found 才自由
+                const state = await service.snapshot();
+                const resolved = resolveReportChainId(state, 'completion', parsed.query);
+                if (resolved.ok || resolved.error !== 'chain-not-found')
+                    return deliver('completion', parsed.query);
+                return {
+                    kind: 'send', mode: 'free', dm: parsed.dm,
+                    guidance: buildFreeSendGuidance(configProvider.getEffective().prefixRoutes, parsed.query, parsed.dm),
+                };
+            }
             if (plan.kind === 'none')
                 return { kind: 'none' };
             // 路由1（内存）：planningBySession 命中 → 直接建链
@@ -218,14 +283,14 @@ export function registerMainSessionTools(ctx, configProvider) {
                     };
                 }
                 const input = { workspaceDir: pctx.workspaceDir, checklist: pctx.checklist, checklistRef: pctx.checklistRef, requirementName: pctx.requirementName };
-                const r = await handleOpenspecRoute(args.message, service, configProvider.getEffective().prefixRoutes, input, 'session_main');
+                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) + '\n\n' + buildOpenspecNarrationRule({ chainId: r.chainId, specCardId: r.specCardId, 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 读页重建；搜不到/不可达 → 两条路皆空
@@ -253,5 +318,39 @@ export function registerMainSessionTools(ctx, configProvider) {
             };
         },
     }));
+    // sms_send：自由投递出口（/sms 非链意图 → guidance 教学 → 此工具实际发送）。manual 路径零重试；
+    // 缺 dsh-im 插件走 DSH_IM_MISSING_PREFIX/GUIDANCE 友好提醒；text 硬上限 4000 字符、空白拒绝。
+    registry.register(defineTool({
+        name: 'sms_send',
+        description: 'Deliver a free-form message via dsh-im (WeCom). text = body composed per the free-delivery guidance returned by kanban_route (fact-grounded via kanban_show; <=4000 chars). dm=false -> the single saved group target; dm=true -> the single saved private-chat target (kind=user; exactly one must exist). Manual path: no retry on failure; missing dsh-im plugin returns install guidance.',
+        parameters: {
+            text: { type: 'string', required: true, description: 'Message body (1..4000 chars) composed per the free-delivery guidance' },
+            dm: { type: 'boolean', description: 'true = private chat; omit/false = group' },
+        },
+        output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+        async execute(args) {
+            // actor 边界与 planning 工具同构：主会话工具面仅限人工触发，非 human caller 一律拒绝
+            if (caller().actor !== 'human')
+                throw new Error('permission denied: sms_send');
+            const text = typeof args.text === 'string' ? args.text.trim() : '';
+            if (!text)
+                throw new Error('text required（正文必填，按自由投递 guidance 生成）');
+            if (text.length > 4000)
+                throw new Error(`text too long: ${text.length} > 4000 chars`);
+            const dm = args.dm === true;
+            const deliver = createSender(ctx, service, configProvider, { retryDelaysMs: [], manual: true, targetKind: dm ? 'user' : 'group' });
+            const r = await deliver('free-send', text);
+            if (!r.ok) {
+                return {
+                    kind: 'send', mode: 'free', dm, error: r.error,
+                    guidance: r.error.startsWith(DSH_IM_MISSING_PREFIX) ? DSH_IM_MISSING_GUIDANCE : undefined,
+                };
+            }
+            return {
+                kind: 'send', mode: 'free', dm, botId: r.botId, targetId: r.targetId,
+                guidance: '已投递（自由投递）。请仅向用户确认投递成功与目标（群聊/私聊），勿复述正文。',
+            };
+        },
+    }));
     console.info('[dsh-swarm] main-session tools registered (v2: kanban_route + planning + spec view + read-only kanban)');
 }

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;

package/lib/tools/ocr-review-tools.js

@@ -0,0 +1,63 @@
+// src/tools/ocr-review-tools.ts
+/** ocr_review 工具：把 ocr CLI 三子命令（preview/rule/managed）封装为 cordis 工具，DT 评审角色工具面注册。
+ * 依赖全注入可换 fake（tests），缺省用 ocr-cli 真实现。 */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { INSTALL_GUIDANCE, managedProviderReady, probeOcr, runOcr } from '../services/ocr-cli.js';
+import { buildOcrArgs, parseManagedJson, parsePreviewJson, shouldSuggestManaged, SUGGEST_MANAGED_FILES } from '../domain/ocr-review.js';
+/** 托管未配置时的降级引导：不改道执行，交还调用方决策。 */
+const MANAGED_FALLBACK_TEXT = '托管模式未配置 LLM——本次按委托模式执行：改调 sub=\'preview\' 获取评审范围后自行评审';
+const SUBS = ['preview', 'rule', 'managed'];
+/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。 */
+export function buildOcrReviewTool(deps) {
+    const runOcrFn = deps.runOcrFn ?? runOcr;
+    const probeFn = deps.probeFn ?? probeOcr;
+    const managedReadyFn = deps.managedReadyFn ?? managedProviderReady;
+    return defineTool({
+        name: 'ocr_review',
+        description: 'Review code changes via the ocr CLI. Three subcommands: '
+            + "'preview' — first step of delegated review; lists reviewable files and branch metadata "
+            + '(JSON output: mode/files/excluded/mergeBase) so you can review them yourself; '
+            + "'rule' — batch-fetch review rule groups for the file paths returned by preview; "
+            + "'managed' — full hosted review where ocr uses its own configured LLM and returns normalized findings JSON "
+            + "(requires prior wiring: ocr config provider=dsh-managed). "
+            + "Start with 'preview' to scope the review; prefer 'managed' for large change sets when the managed provider is configured.",
+        parameters: {
+            sub: { type: 'string', required: true, description: "'preview' | 'rule' | 'managed'" },
+            repo: { type: 'string', description: '仓库根绝对路径；缺省用当前工作目录' },
+            from: { type: 'string', description: 'base 分支/引用（range 模式）' },
+            to: { type: 'string', description: '目标分支/引用（range 模式，默认 HEAD）' },
+            commit: { type: 'string', description: '单次提交审查' },
+            paths: { type: 'array', items: { type: 'string' }, description: 'rule 子命令的文件路径列表' },
+        },
+        output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
+        async execute(args) {
+            const probe = await probeFn();
+            if (!probe.installed)
+                return INSTALL_GUIDANCE;
+            if (args.sub === 'managed' && !managedReadyFn())
+                return MANAGED_FALLBACK_TEXT;
+            if (!SUBS.includes(args.sub))
+                throw new Error(`ocr_review: invalid sub '${args.sub}' (expected 'preview' | 'rule' | 'managed')`);
+            if (args.sub === 'rule' && (!args.paths || args.paths.length === 0))
+                throw new Error("ocr_review: sub='rule' requires non-empty paths (file path list)");
+            if (args.sub === 'managed' && !args.commit && !args.from)
+                throw new Error("ocr_review: sub='managed' requires commit or from (base ref)");
+            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs: 600_000 });
+            if (res.error && !res.stdout)
+                throw new Error(`ocr_review: ${res.error} ${res.stderr.slice(0, 500)}`.trim());
+            if (args.sub === 'preview') {
+                const preview = parsePreviewJson(res.stdout);
+                if (shouldSuggestManaged(preview.files.length)) {
+                    return JSON.stringify({ ...preview, suggestion: `文件较多（N>${SUGGEST_MANAGED_FILES}），可在配置面板切换托管模式` });
+                }
+                return JSON.stringify(preview);
+            }
+            if (args.sub === 'rule')
+                return res.stdout.slice(0, 8000);
+            const report = parseManagedJson(res.stdout);
+            if (report.status !== 'completed' && res.error)
+                return JSON.stringify({ ...report, message: res.error });
+            return JSON.stringify(report);
+        },
+    });
+}

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

@@ -20,10 +20,10 @@ export interface PlanningToolDeps {
     spawnPrefetch?(prompt: string, workspaceDir: string, parentAgent?: Agent, signal?: AbortSignal): Promise<string>;
     tempDir(): string;
     pagePrefix?: string;
-    /** KB 双模式（D3）：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/），缺省 remote。 */
+    /** KB 双模式：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/），缺省 remote。 */
     kbMode?: 'remote' | 'local';
     ownerSessionId?: string;
-    /** 斜杠命令前缀路由（决策12 单一事实源），用于 description 文案派生。 */
+    /** 斜杠命令前缀路由（单一事实源），用于 description 文案派生。 */
     prefixRoutes: PrefixRoutes;
     defaultModel?: AgentModelOptions;
     /** 清单落库成功回调（kb 与 temp 两分支各调一次），供 main-session-tools 回写 planningBySession。 */
@@ -36,6 +36,9 @@ export interface PlanningToolDeps {
     memoryEnabled?: boolean;
     /** 闸1：/plan: 捕获的当前工作区（main-session-tools 注入）；非 null 且与清单 localPath 不一致 → 阻断落库。 */
     resolveWorkspaceDir?: () => string | null;
+    /** 蜂群模式分叉：main-session-tools 注入 () => planningBySession.get('session_main')?.mode ?? null。
+     *  'swarm' 时 checklist_save 成功返回体附 nextStep 确认闸指引；前缀模式返回体不变。 */
+    flowMode?: () => 'swarm' | 'prefix' | null;
 }
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export declare function buildPlanningTools(deps: PlanningToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/planning-tools.js

@@ -4,16 +4,18 @@ import {} from '@deepseek-ai/dsh-util-values';
 import { validatePlanningChecklist, formatChecklistBody } from '../domain/planning-checklist.js';
 import { validatePrefetchManifest } from '../domain/prefetch-manifest.js';
 import { buildChecklistSlug, KB_PAGE_NAMESPACES_HINT, LOCAL_CHECKLIST_PREFIX, LOCAL_LEARNING_BASE, assertAllowedWikiPagePath, assertLocalKbPagePath } from '../wiki/page-path.js';
-import { validateLearning, formatLearningBody, buildRepoSlug } from '../domain/memory.js';
+import { validateLearning, formatLearningBody, buildRepoSlug, countLearningSignals } from '../domain/memory.js';
 const isWikiError = (e) => e instanceof Error && e.code === 'kb-unreachable';
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export function buildPlanningTools(deps) {
     const local = deps.kbMode === 'local';
-    // checklist 前缀双模式（D3/D5）：remote → projects/<repoSlug>/checklists/（repoSlug 段在 pagePath 拼接，workspace 计划 T3）；
-    // local → wiki/queries/checklists/（local 时 LocalWikiClient.write 仅接受 wiki/** 相对路径，projects/ 会被 kb-rejected——I1 修复）
+    // checklist 前缀双模式：remote → projects/<repoSlug>/checklists/（repoSlug 段在 pagePath 拼接）；
+    // local → wiki/queries/checklists/（local 时 LocalWikiClient.write 仅接受 wiki/** 相对路径，projects/ 会被 kb-rejected）
     const pagePrefix = deps.pagePrefix ?? 'projects/';
     const checklistPrefix = local ? LOCAL_CHECKLIST_PREFIX : pagePrefix;
     const session = deps.ownerSessionId ?? 'session_main';
+    const SWARM_NEXT_STEP = '向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:\'openspec\'} 建链；模糊、岔开话题、只提修改意见 = 未确认，继续澄清。禁止未确认建链。';
+    const swarmNext = () => (deps.flowMode?.() === 'swarm' ? { nextStep: SWARM_NEXT_STEP } : {});
     return [
         defineTool({
             name: 'planning_checklist_save',
@@ -38,7 +40,7 @@ export function buildPlanningTools(deps) {
                     try {
                         await deps.wiki.write(args.restoreRef, body);
                         deps.onChecklistSaved?.({ ref: args.restoreRef, source: 'kb', checklist });
-                        return { ok: true, ref: args.restoreRef, source: 'kb', repoPath: checklist.manifest.repo.localPath };
+                        return { ok: true, ref: args.restoreRef, source: 'kb', repoPath: checklist.manifest.repo.localPath, ...swarmNext() };
                     }
                     catch (err) {
                         if (!isWikiError(err))
@@ -53,7 +55,7 @@ export function buildPlanningTools(deps) {
                 try {
                     await deps.wiki.write(pagePath, body);
                     deps.onChecklistSaved?.({ ref: pagePath, source: 'kb', checklist });
-                    return { ok: true, ref: pagePath, source: 'kb', repoPath: checklist.manifest.repo.localPath };
+                    return { ok: true, ref: pagePath, source: 'kb', repoPath: checklist.manifest.repo.localPath, ...swarmNext() };
                 }
                 catch (err) {
                     if (!isWikiError(err))
@@ -64,7 +66,7 @@ export function buildPlanningTools(deps) {
                     mkdirSync(deps.tempDir(), { recursive: true });
                     writeFileSync(local, body, 'utf8');
                     deps.onChecklistSaved?.({ ref: local, source: 'temp', checklist });
-                    return { ok: true, ref: local, source: 'temp', repoPath: checklist.manifest.repo.localPath };
+                    return { ok: true, ref: local, source: 'temp', repoPath: checklist.manifest.repo.localPath, ...swarmNext() };
                 }
             },
         }),
@@ -100,7 +102,7 @@ export function buildPlanningTools(deps) {
             name: 'planning_learning_save',
             description: 'Save a distilled learning (experience) to the knowledge base. Remote KB: scope=chain → projects/<repoSlug>/<chainId>/learnings/ (requirement-level); scope=project → projects/<repoSlug>/learnings/ (repo-level). repoSlug is derived from the chain workspaceDir; both scopes require chain.workspaceDir. Local KB: both scopes → wiki/synthesis/learnings/<chainId|repoSlug>/. Returns ref. Soft-fails {ok:false,reason:"kb-unreachable"} when KB is unreachable (no temp fallback).',
             parameters: {
-                learning: { type: 'json', required: true, description: 'LearningEntry: { title (≤80 chars), lesson, evidence (mechanical chain/task id — required), tags: string[] }' },
+                learning: { type: 'json', required: true, description: 'LearningEntry: { title (≤80 chars), lesson, evidence (mechanical chain/task id — required), tags: string[] — must include one of mistake/reusable/env-trap/collab-contract/efficiency (category criteria enforced) }' },
                 scope: { type: 'string', enum: ['chain', 'project'], required: true, description: '"chain" (requirement-level) | "project" (repo-level)' },
                 chainId: { type: 'string', required: true, description: 'The chain this learning is distilled from; must exist' },
             },
@@ -121,9 +123,15 @@ export function buildPlanningTools(deps) {
                 if (!chain)
                     throw new Error('unknown chain: ' + args.chainId);
                 const entry = args.learning;
+                // A 类硬复核（0.3.1）：mistake 标签须通过机械信号复核（累计 ≥2），不复信模型自报
+                if (Array.isArray(entry.tags) && entry.tags.includes('mistake')) {
+                    const total = countLearningSignals(state, args.chainId);
+                    if (total < 2)
+                        throw new Error(`[mistake-gate] 标记 mistake 需链上 阻塞/返工/评审失败/审计警告 累计 ≥2 次，当前链累计 ${total} 次。请核对证据包；不满足时改用其他类别标签（reusable/env-trap/collab-contract/efficiency）或回复「无新经验」`);
+                }
                 let prefix;
                 if (local) {
-                    // local（D5）：scope=chain 直接挂 chainId；scope=project 挂 repoSlug（需 workspaceDir）
+                    // local：scope=chain 直接挂 chainId；scope=project 挂 repoSlug（需 workspaceDir）
                     if (args.scope === 'chain') {
                         prefix = `${LOCAL_LEARNING_BASE}${args.chainId}/`;
                     }
@@ -134,7 +142,7 @@ export function buildPlanningTools(deps) {
                     }
                 }
                 else {
-                    // remote（workspace 计划 T3）：两 scope 均要求 chain.workspaceDir，统一挂 projects/<repoSlug>/
+                    // remote：两 scope 均要求 chain.workspaceDir，统一挂 projects/<repoSlug>/
                     if (!chain.workspaceDir)
                         throw new Error('learning save requires chain.workspaceDir (target repo) — chain has none');
                     const wsRoot = `${pagePrefix}${buildRepoSlug(chain.workspaceDir)}/`;
@@ -171,8 +179,8 @@ export function buildPlanningTools(deps) {
                 if (hasPath === hasQuery)
                     throw new Error('provide exactly one of path|query');
                 if (hasPath) {
-                    // path 白名单按 KB 双模式分支（D3/D9）：remote → projects/** 命名空间；local → wiki/**（
-                    // Task 11 后 local 的 checklist/learning 全落 wiki/ 前缀，用 projects/ 白名单会把 local 读腿全拒）
+                    // path 白名单按 KB 双模式分支：remote → projects/** 命名空间；local → wiki/**（
+                    // local 的 checklist/learning 全落 wiki/ 前缀，用 projects/ 白名单会把 local 读腿全拒）
                     if (local)
                         assertLocalKbPagePath(args.path);
                     else

package/lib/tools/wiki-tools.js

@@ -44,11 +44,11 @@ export function buildWikiTools(wiki, getCaller) {
             async execute(args) {
                 const caller = getCaller();
                 guard('wiki-write', caller);
-                // Q3&5：工具边界强校验——只允许 projects/<repoSlug>/ 白名单命名空间（KB_PAGE_NAMESPACES_HINT 五类，
+                // 工具边界强校验——只允许 projects/<repoSlug>/ 白名单命名空间（KB_PAGE_NAMESPACES_HINT 五类，
                 // 见 page-path.ts），杜绝 LLM 自造路径/拼错层级导致 kb_url 无法跳转。
                 assertAllowedWikiPagePath(args.pagePath);
                 const out = await wiki.write(args.pagePath, args.content);
-                // Q4：工具直接拼完整 kb_url（host 用 config.wikiVault.baseUrl，杜绝 LLM 手写错域名）。
+                // 工具直接拼完整 kb_url（host 用 config.wikiVault.baseUrl，杜绝 LLM 手写错域名）。
                 // W 角色交付闸（kanban_complete w:kb）同时校验 host 前缀，双保险。
                 const base = wiki.baseUrl.replace(/\/$/, '');
                 return { path: out.path, kb_url: `${base}/#/page/${args.pagePath}` };

package/lib/wiki/kb-linkage.d.ts

@@ -1,5 +1,5 @@
 import type { BoardState } from '../domain/types.js';
-/** kb-linkage 所需最小 wiki 面（WikiVaultClient / LocalWikiClient 均满足，D2 双模式客户端注入）。 */
+/** kb-linkage 所需最小 wiki 面（WikiVaultClient / LocalWikiClient 均满足，双模式客户端注入）。 */
 type KbWikiClient = {
     read(pagePath: string): Promise<{
         rawMd: string;

package/lib/wiki/local-kb-client.js

@@ -1,7 +1,7 @@
 // src/wiki/local-kb-client.ts
 // 本地 KB 客户端（llm-wiki 目录结构）：与 WikiVaultClient 同构的 search/read/write 面，
 // local 模式下替换注入（planning 工具 / kb-linkage / memory-recall 复用既有逻辑，零分支扩散）。
-// 排序原则 D12：相关性优先 7 : 新鲜度 3（0.7*scoreNorm + 0.3*mtimeNorm）。
+// 排序原则：相关性优先 7 : 新鲜度 3（0.7*scoreNorm + 0.3*mtimeNorm）。
 import { readdirSync, readFileSync, writeFileSync, mkdirSync, statSync, existsSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import { WikiError } from './wiki-vault-client.js';
@@ -12,7 +12,7 @@ export class LocalWikiClient {
     root;
     constructor(root) { this.root = root; }
     abs(pagePath) {
-        assertLocalKbPagePath(pagePath); // Task 1 白名单单一来源（wiki/**、拒 .. 与绝对路径），勿内联重复
+        assertLocalKbPagePath(pagePath); // 白名单单一来源（wiki/**、拒 .. 与绝对路径），勿内联重复
         const t = resolve(this.root, pagePath);
         if (!isInsideKbRoot(this.root, t))
             throw new WikiError('kb-rejected', undefined, `kb-rejected: path escapes local KB root: ${pagePath}`);
@@ -25,7 +25,7 @@ export class LocalWikiClient {
             writeFileSync(t, content, 'utf8');
         }
         catch (err) {
-            // §9 降级链依赖：fs 失败归一 kb-unreachable（planning 工具按 code 判定 temp 兜底/软失败，审查 M5）
+            // 降级链依赖：fs 失败归一 kb-unreachable（planning 工具按 code 判定 temp 兜底/软失败）
             throw new WikiError('kb-unreachable', undefined, `kb-unreachable: local KB write failed: ${String(err)}`);
         }
         return { path: pagePath };

package/lib/wiki/local-kb.d.ts

@@ -1,5 +1,5 @@
 export declare function localKbRoot(): string;
-/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)（设计 §9）。 */
+/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)。 */
 export declare function ensureLocalKbRoot(root?: string): string;
 /** target 须为绝对路径且解析后落在 root 内（resolve 折叠重复斜杠；相对路径 fail-closed，
  *  因为 bash/fs 里的相对目标语义属会话 cwd 而非库根，护栏不可猜测）。 */

package/lib/wiki/local-kb.js

@@ -1,5 +1,5 @@
 // src/wiki/local-kb.ts
-// 本地 KB（llm-wiki）库根工具（设计 D4：独立 <DSH_HOME>/storages/kanban/wiki/，隔离用户个人 ~/.llm-wiki-path）。
+// 本地 KB（llm-wiki）库根工具（设计：独立 <DSH_HOME>/storages/kanban/wiki/，隔离用户个人 ~/.llm-wiki-path）。
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import { mkdirSync } from 'node:fs';
@@ -7,7 +7,7 @@ export function localKbRoot() {
     const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
     return join(dshHome, 'storages', 'kanban', 'wiki');
 }
-/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)（设计 §9）。 */
+/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)。 */
 export function ensureLocalKbRoot(root = localKbRoot()) {
     mkdirSync(root, { recursive: true });
     return root;

package/lib/wiki/page-path.d.ts

@@ -1,5 +1,5 @@
 /** 命名空间提示（报错/工具 description 文案单一来源，禁止散落硬编码）。 */
-export declare const KB_PAGE_NAMESPACES_HINT = "projects/<repoSlug>/checklists/\u3001projects/<repoSlug>/learnings/\u3001projects/<repoSlug>/ch_*/learnings/\u3001projects/<repoSlug>/ch_*/t_*.md\u3001projects/<repoSlug>/ch_*/review/";
+export declare const KB_PAGE_NAMESPACES_HINT = "projects/<repoSlug>/checklists/\u3001projects/<repoSlug>/learnings/\u3001projects/<repoSlug>/ch_*/learnings/\u3001projects/<repoSlug>/ch_*/t_*.md\u3001projects/<repoSlug>/ch_*/review/\u3001projects/<repoSlug>/reviews/<topic>-<ymd>/";
 /** 从需求名（回退 problem）派生 URL 安全 slug：ASCII 化、空格/特殊字符→-、限长 40；全非 ASCII（如中文）兜底 'req'。 */
 export declare function buildChecklistSlug(name: string): string;
 export declare function isAllowedWikiPagePath(pagePath: string): boolean;

package/lib/wiki/page-path.js

@@ -4,10 +4,12 @@
 //   需求清单      projects/<repoSlug>/checklists/<slug>-<ts>.md  （planning_checklist_save，代码强制）
 //   实施计划/结果 projects/<repoSlug>/ch_<id>/t_<id>.md          （W2/W3 wiki_write，工具边界强制）
 //   DT 评审页     projects/<repoSlug>/ch_<id>/review/<name>.md   （DT wiki_write + 写护栏强制）
+//   独立评审报告  projects/<repoSlug>/reviews/<topic>-<ymd>/     （独立 DT 模式 wiki_write，形态由 domain/ocr-review 判定）
 //   经验          projects/<repoSlug>/learnings/、projects/<repoSlug>/ch_<id>/learnings/
 import { WikiError } from './wiki-vault-client.js';
+import { isStandaloneReviewNamespacePath } from '../domain/ocr-review.js';
 /** 命名空间提示（报错/工具 description 文案单一来源，禁止散落硬编码）。 */
-export const KB_PAGE_NAMESPACES_HINT = 'projects/<repoSlug>/checklists/、projects/<repoSlug>/learnings/、projects/<repoSlug>/ch_*/learnings/、projects/<repoSlug>/ch_*/t_*.md、projects/<repoSlug>/ch_*/review/';
+export const KB_PAGE_NAMESPACES_HINT = 'projects/<repoSlug>/checklists/、projects/<repoSlug>/learnings/、projects/<repoSlug>/ch_*/learnings/、projects/<repoSlug>/ch_*/t_*.md、projects/<repoSlug>/ch_*/review/、projects/<repoSlug>/reviews/<topic>-<ymd>/';
 /** 白名单：projects/<repoSlug>/ 下五类命名空间（repoSlug=[a-z0-9-]+，杜绝 LLM 自造路径）。 */
 const KB_PAGE_PATH_RE = /^projects\/[a-z0-9-]+\/(?:checklists\/|learnings\/|ch_[0-9a-z_]+\/(?:t_[0-9a-z_]+\.md|review\/|learnings\/))/;
 /** 从需求名（回退 problem）派生 URL 安全 slug：ASCII 化、空格/特殊字符→-、限长 40；全非 ASCII（如中文）兜底 'req'。 */
@@ -21,7 +23,8 @@ export function buildChecklistSlug(name) {
     return slug || 'req';
 }
 export function isAllowedWikiPagePath(pagePath) {
-    return KB_PAGE_PATH_RE.test(pagePath);
+    // 独立评审命名空间（projects/<repoSlug>/reviews/<topic>-<ymd>/）复用 domain/ocr-review 判定，保持单一来源。
+    return KB_PAGE_PATH_RE.test(pagePath) || isStandaloneReviewNamespacePath(pagePath);
 }
 /** learnings 路径谓词：项目级 / 需求级（均在 repoSlug 下）。 */
 export function isLearningsPath(pagePath) {
@@ -33,7 +36,7 @@ export function assertAllowedWikiPagePath(pagePath) {
         throw new WikiError('kb-rejected', undefined, `page path outside allowed namespaces (${KB_PAGE_NAMESPACES_HINT}): ${pagePath}`);
     }
 }
-// ── 本地 KB（llm-wiki）路径规则（双模式 D5/D9）──────────────────────────────
+// ── 本地 KB（llm-wiki）路径规则（双模式）──────────────────────────────
 export const LOCAL_CHECKLIST_PREFIX = 'wiki/queries/checklists/';
 export const LOCAL_LEARNING_BASE = 'wiki/synthesis/learnings/';
 /** 本地模式交付白名单：KB 库根下 wiki/** 相对路径（拒绝对象路径、.. 穿越、空串）。 */

package/lib/wiki/wiki-vault-client.d.ts

@@ -15,7 +15,7 @@ export declare class WikiVaultClient {
         baseUrl: string;
         pagePrefix: string;
     });
-    /** P2：暴露 baseUrl getter（下游 WikiWorker 拼 kb_url 用），不挖私有字段；经 getCfg 每次取最新配置（热生效）。 */
+    /** 暴露 baseUrl getter（下游 WikiWorker 拼 kb_url 用），不挖私有字段；经 getCfg 每次取最新配置（热生效）。 */
     get baseUrl(): string;
     private request;
     search(q: string): Promise<WikiSearchResult[]>;

package/lib/wiki/wiki-vault-client.js

@@ -11,7 +11,7 @@ export class WikiError extends Error {
 export class WikiVaultClient {
     getCfg;
     constructor(getCfg) { this.getCfg = getCfg; }
-    /** P2：暴露 baseUrl getter（下游 WikiWorker 拼 kb_url 用），不挖私有字段；经 getCfg 每次取最新配置（热生效）。 */
+    /** 暴露 baseUrl getter（下游 WikiWorker 拼 kb_url 用），不挖私有字段；经 getCfg 每次取最新配置（热生效）。 */
     get baseUrl() { return this.getCfg().baseUrl; }
     async request(method, path, body) {
         const url = this.getCfg().baseUrl.replace(/\/$/, '') + path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.2.0",
+  "version": "0.3.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",