@joekytc/dsh-swarm 0.2.0 → 0.3.0

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 } 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 层——最终防线是链级看门狗（防线①）。 */
@@ -114,14 +124,14 @@ export function buildSpawnPrefetch(ctx) {
 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 +151,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 +168,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 → 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, 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 +209,27 @@ 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 手动投递：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 命中 → 直接建链
@@ -218,14 +256,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 读页重建；搜不到/不可达 → 两条路皆空

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

@@ -9,11 +9,13 @@ 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() };
                 }
             },
         }),
@@ -123,7 +125,7 @@ export function buildPlanningTools(deps) {
                 const entry = args.learning;
                 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 +136,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 +173,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.0",
   "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",

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

@@ -1,12 +1,12 @@
-# kanban-d — D(fullstack-dev) 裁剪 agent preset（D22，2026-08-15）。
+# kanban-d — D(fullstack-dev) 裁剪 agent preset（2026-08-15）。
 #
-# 官方 agent-presets 无 include/patch 语义，本文件为手写最小组合（取舍见 Task 33 提交）。
+# 官方 agent-presets 无 include/patch 语义，本文件为手写最小组合（取舍见 git 提交历史）。
 # 保留完整开发能力：persona/instructions + bash/pwsh + fs + fs-search + jobs + skill
 # + compaction + ask-user + todo + run_code(tool-presentation)。
 # 0.1.0 调整（2026-08-21）：开放 delegation（spawn/fork + control/list-agents，one-shot；
 # 子代理继承 D 权限与沙箱，产物归属 D 的 feature 分支 git 证据）与 goal（条件启用：
 # spec/实施计划提及 /goal 目标模式关键词时由系统注入目标模式指令）。
-# 仍裁剪：workflow/ralph（编排循环归 R20 链路职责）、plan-mode(planning)、web。
+# 仍裁剪：workflow/ralph（编排循环归链路编排职责）、plan-mode(planning)、web。
 
 - id: persona
   name: '@deepseek-ai/dsh-persona'
@@ -147,10 +147,10 @@
   name: '@deepseek-ai/dsh-tool-goal'
 
 # ── presentation (run_code) ─────────────────────────────────────────────────
-# B1：mode 由 code 改为 both —— code 模式下注册表把「直接调用 bash/kanban_* 等工具」解析为
+# mode 由 code 改为 both —— code 模式下注册表把「直接调用 bash/kanban_* 等工具」解析为
 # UNKNOWN_TOOL（仅 run_code 可模型直呼），导致 D 无法直接 kanban_complete/kanban_block 收尾；
 # native 又隐藏 run_code。both = 原生工具 schema + run_code 并存：bash/fs/kanban_* 可直接调用，
-# run_code（tools.* 路由）亦可用，正好是 D=执行者的工具面（见 checklist B1/B5）。
+# run_code（tools.* 路由）亦可用，正好是 D=执行者的工具面。
 - id: tool-presentation
   name: '@deepseek-ai/dsh-agent-tool-presentation'
   config:

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

@@ -1,4 +1,4 @@
-# kanban-dt — DT(impl verify+review) 裁剪 agent preset（交付质量链 Task 9）。
+# kanban-dt — DT(impl verify+review) 裁剪 agent preset（交付质量链）。
 #
 # DT = 只读实现校验+评审角色：kanban 任务工具 + spec_card_view + wiki 只读（评审区写由 ToolGuard 收窄）。
 # 组合：persona + instructions + bash + fs + fs-search + run_code（验证命令用，ToolGuard 拦源码写）。
@@ -27,10 +27,28 @@
       You may spawn read-only check subagents (spawn, one-shot) to parallelize the
       verification; they are hard-locked read-only by the global subagent guard — do
       not attempt writes through them.
-      3. Review engine priority: open-code-review (ocr review --from <TARGET_BRANCH> --to
-      <branch>, delegation mode; <branch> = D's feature branch from the parent handoff
-      metadata.branch) → fallback superpowers code-review when ocr is unavailable →
-      kanban_block('review-tool-unavailable') only when both are unavailable.
+      3. The review engine is decided by the config panel reviewEngine.mode (default:
+      delegate). Delegate = call ocr_review{sub:'preview'} for the review scope →
+      ocr_review{sub:'rule'} for per-file review rules → review the git diff file by file
+      yourself → classify findings by severity (Critical/High must be reported, Medium with
+      context, Low dropped by default). Managed = call ocr_review{sub:'managed',
+      from:<TARGET_BRANCH>, to:<branch>} for normalized findings in one shot (<branch> = D's
+      feature branch from the parent handoff metadata.branch); silently fall back to the
+      delegate flow when status is not completed or the tool returns managed-not-configured
+      guidance. When ocr is not installed the tool returns install guidance (installable
+      from the GUI config panel); in chain scenarios kanban_block('review-tool-unavailable')
+      and note the GUI install option in the reason. Standalone review mode (no bound chain
+      task): review user-specified local dirs, branch ranges (--from/--to), single commits,
+      uncommitted diffs or public repo URLs (git clone to a temp dir, discard after
+      review); git queries (status/log/show/diff/rev-list/merge-base/blame etc.), clone/fetch
+      and bare checkout/switch are allowed while mutations (push/merge/rebase/reset/commit/
+      add/clean/restore etc.) are always rejected by the guard — you are a read-only
+      reviewer; never pass the sandbox_permissions/justification escalation params on
+      bash/write/edit (read-only sessions have no escalation use case; passing them
+      triggers the host sandbox validation error); output the full report in conversation,
+      then wiki_write to
+      projects/<repoSlug>/reviews/<topic>-<date>/ after user confirmation; no kanban tools;
+      never modify reviewed code.
       4. Wiki writes only under the whitelisted projects/<repoSlug>/<chain>/review/ namespace
       (repoSlug is derived from the chain workspaceDir).
       5. Write the review conclusion into kanban_complete metadata review_evidence =

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

@@ -1,9 +1,9 @@
-# kanban-p — P(planner) 裁剪 agent preset（D22，2026-08-15）。
+# kanban-p — P(planner) 裁剪 agent preset（2026-08-15）。
 #
 # 组合方式：官方 agent-presets 无 include/patch 语义（cordis/code 均为 standard 的
-# 整目录副本），故本文件为手写最小组合（取舍已记入 Task 33 提交信息）。
+# 整目录副本），故本文件为手写最小组合（取舍已记入 git 提交历史）。
 # 仅保留规划所需基座：persona/instructions + bash + fs + fs-search。
-# 裁剪（设计 §4）：无 run_code(tool-presentation)、jobs、skill、goal、plan-mode(planning)、
+# 裁剪（最小能力面）：无 run_code(tool-presentation)、jobs、skill、goal、plan-mode(planning)、
 # compaction、delegation(subagent/fork/workflow/ralph)、ask-user、todo、web。
 # 局限：dsh-tool-bash 无 readonly 模式，P 的"只读命令（cat/git show）"纪律由
 # runner 设置的 danger-full-access sandbox + 工具级硬护栏（buildPlanWriteGuard：写仅允许

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

@@ -1,4 +1,4 @@
-# kanban-pt — PT(plan review) 裁剪 agent preset（交付质量链 Task 8）。
+# kanban-pt — PT(plan review) 裁剪 agent preset（交付质量链）。
 #
 # PT = 只读计划评审角色：kanban 任务工具 + spec_card_view（无 create/wiki/执行）。
 # 组合：persona + instructions + bash + fs + fs-search（与 P/W 同类基座，读/找用）。

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

@@ -1,6 +1,6 @@
-# kanban-v — V(orchestrator) 裁剪 agent preset（2026-08-17，R21 对齐）。
+# kanban-v — V(orchestrator) 裁剪 agent preset（2026-08-17）。
 #
-# V = butler·orchestrator：唯一可 kanban_create、零执行能力（R21「disabled: browser/file/
+# V = butler·orchestrator：唯一可 kanban_create、零执行能力（「disabled: browser/file/
 # web/search/delegation/code_execution；只路由」）。组合仅 persona + agent-instructions
 # （+ installRoleTools 注入的 kanban/spec 工具）——不含 bash/fs/fs-search/run_code/jobs/
 # skill/goal/plan-mode/compaction/delegation/web/todo 等任何执行/探索/派单工具，
@@ -18,7 +18,7 @@
       Rules:
       1. You have NO execution or exploration tools (no bash/fs/run_code/web/search/delegation);
       facts come only from kanban_show/kanban_list/spec_card_view and the injected context.
-      2. R20 phase-by-phase creation: create the next phase's task only after the previous
+      2. Phase-by-phase creation: create the next phase's task only after the previous
       phase's completion event; no cross-phase parallelism. Chain: P(openspec) → (PT plan
       review, on demand) → W2(kb sync) → D(execute, the ONLY executor) → DT(impl verify+review)
       → W3(kb sync) → summary. Create a PT card only when P(openspec) completes with