@joekytc/dsh-swarm 0.2.0 → 0.3.0

package/lib/services/im-delivery.js

@@ -0,0 +1,263 @@
+import { homedir } from 'node:os';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildCompletionMessage, buildBlockMessage } from '../domain/im-message.js';
+const RETRYABLE_CODES = new Set(['bot-not-connected', 'delivery-failed']);
+const DEFAULT_RETRY_DELAYS_MS = [5_000, 10_000, 15_000];
+export function isDshImLike(svc) {
+    const s = svc;
+    return typeof s === 'object' && s !== null
+        && typeof s.send === 'function'
+        && typeof s.listBots === 'function'
+        && typeof s.listTargets === 'function';
+}
+function resolveDshIm(ctx, log) {
+    const svc = ctx.get('dshIm');
+    if (!isDshImLike(svc)) {
+        log('[im-delivery] dshIm 服务缺失或形状不符，显式降级跳过（本次不投递）');
+        return null;
+    }
+    return svc;
+}
+/** botId/targetId 解析（评审决议）：配置显式指定优先；留空自动发现唯一 wecom bot + 唯一已保存群目标；
+ *  发现异常返回 error（调用方留痕不投，fail-closed——投错群比不投更糟）。 */
+export async function resolveTarget(im, cfg) {
+    let botId = cfg.botId.trim();
+    if (!botId) {
+        const bots = await im.listBots();
+        const wecom = bots.filter((b) => b.channel === 'wecom');
+        if (wecom.length !== 1)
+            return { error: `企微机器人数量=${wecom.length}（期望 1），请在插件配置 imDelivery.botId 显式指定` };
+        botId = wecom[0].botId;
+    }
+    let targetId = cfg.targetId.trim();
+    if (!targetId) {
+        const raw = await im.listTargets(botId);
+        // 宿主同 Host 服务返回裸数组（PROACTIVE_DELIVERY.md:176）；防御兼容 Connection RPC `target.list` 信封形状。
+        const targets = Array.isArray(raw) ? raw : Array.isArray(raw?.targets)
+            ? raw.targets
+            : [];
+        const groups = targets.filter((x) => x.kind === 'group');
+        if (groups.length !== 1)
+            return { error: `已保存群目标数量=${groups.length}（期望 1），请到 dsh-im 设置→IM机器人 新建目标或在插件配置 imDelivery.targetId 显式指定` };
+        targetId = groups[0].targetId;
+    }
+    return { botId, targetId };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 发送 + 退避重试（仅可重试错误码；{sent:true} 即停——dsh-im 无幂等，成功后绝不重发）。 */
+export async function sendWithRetry(im, botId, targetId, text, delays, log) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            const r = await im.send(botId, targetId, text);
+            if (r?.sent !== true) {
+                const e = new Error('dsh-im send 返回 sent!==true');
+                e.code = 'delivery-failed';
+                throw e;
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            const code = err.code ?? 'delivery-failed';
+            if (attempt >= delays.length || !RETRYABLE_CODES.has(code)) {
+                return { ok: false, error: `${code}: ${String(err)}` };
+            }
+            log(`[im-delivery] send failed (attempt ${attempt + 1}, code=${code})，retry after ${delays[attempt]}ms 后重试`);
+            await sleep(delays[attempt]);
+        }
+    }
+}
+/** storageDir 派生（config 占位符 $DSH_HOME 替换；auto 与 /sms 手动路径同源）。 */
+function deriveStorageDir(configProvider) {
+    return configProvider.getEffective().storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? homedir());
+}
+function makeDefaultLog(storageDir) {
+    return (msg) => {
+        try {
+            writeFileSync(join(storageDir, 'dispatcher.log'), new Date().toISOString() + ' ' + msg + '\n', { flag: 'a' });
+        }
+        catch { /* 忽略写失败 */ }
+    };
+}
+/** 发送器工厂：resolveDshIm → resolveTarget（fail-closed）→ sendWithRetry → 留痕。
+ *  auto 路径（wireImDelivery）失败额外写 chain/im-delivery-failed 链事件；
+ *  manual 路径（/sms，opts.manual）仅 dispatcher.log 留痕，错误同步返回给调用方。 */
+export function createSender(ctx, kanban, configProvider, opts = {}) {
+    const log = opts.log ?? makeDefaultLog(deriveStorageDir(configProvider));
+    const delays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    return async (chainId, text) => {
+        const cfg = configProvider.getEffective().imDelivery;
+        const im = resolveDshIm(ctx, log);
+        if (!im)
+            return { ok: false, error: 'dshIm 服务缺失或形状不符（需 @xmanrui/dsh-im 宿主服务）' };
+        const t = await resolveTarget(im, cfg);
+        if ('error' in t) {
+            log(`[im-delivery] target resolve failed chain=${chainId}: ${t.error}`);
+            return { ok: false, error: t.error };
+        }
+        const r = await sendWithRetry(im, t.botId, t.targetId, text, delays, log);
+        if (r.ok) {
+            log(`[im-delivery] delivered chain=${chainId} bot=${t.botId} target=${t.targetId}`);
+            return { ok: true, botId: t.botId, targetId: t.targetId };
+        }
+        // 超限显形（评审决议）：dispatcher.log 留痕；auto 路径追加 events.jsonl 双留痕；投递失败绝不 block 链。
+        log(`[im-delivery] FAILED chain=${chainId}: ${r.error}`);
+        if (!opts.manual) {
+            try {
+                await kanban.noteImDeliveryFailed(chainId, `企微投递失败（重试 ${delays.length} 次后放弃）：${r.error}`, 'system');
+            }
+            catch (err) {
+                log(`[im-delivery] noteImDeliveryFailed failed chain=${chainId}: ` + String(err));
+            }
+        }
+        return { ok: false, error: r.error };
+    };
+}
+/** 链上最后一个带 taskId 的 task/completed 事件（state.events 按 seq 有序）。 */
+function lastCompleted(state, chainId) {
+    const last = state.events.filter((e) => e.chainId === chainId && e.kind === 'task/completed' && e.taskId).at(-1);
+    return last?.taskId ? { taskId: last.taskId, at: last.at } : null;
+}
+function lastChainBlockedAt(state, chainId) {
+    const last = state.events.filter((e) => e.chainId === chainId && e.kind === 'chain/blocked').at(-1);
+    return last?.at ?? -1;
+}
+/** 全量链内按 精确 id → 唯一 id 后缀 解析（/learning UX：歧义返回候选列表）。 */
+function findByIdOrSuffix(chains, query) {
+    const exact = chains.find((c) => c.id === query);
+    if (exact)
+        return { ok: true, chainId: exact.id };
+    const matches = chains.filter((c) => c.id.endsWith(query));
+    if (matches.length === 1)
+        return { ok: true, chainId: matches[0].id };
+    if (matches.length === 0)
+        return { ok: false, error: 'chain-not-found' };
+    return { ok: false, error: 'chain-ambiguous', candidates: matches.map((c) => ({ chainId: c.id, title: c.title })) };
+}
+/** /sms 链解析（纯函数）。空 query：completion=最近满足 W3 完成判据的链（最后完成事件 at 最大）；
+ *  blocked=最近阻塞的链（chain/blocked 事件 at 最大）。显式 query：全量链精确/后缀解析后再验判据。 */
+export function resolveReportChainId(state, variant, query) {
+    const q = query.trim();
+    const chains = [...state.chains.values()];
+    if (variant === 'blocked') {
+        const blockedChains = chains.filter((c) => c.status === 'blocked');
+        if (!q) {
+            if (blockedChains.length === 0)
+                return { ok: false, error: 'chain-not-found' };
+            let best = blockedChains[0];
+            let bestAt = lastChainBlockedAt(state, best.id);
+            for (const c of blockedChains.slice(1)) {
+                const at = lastChainBlockedAt(state, c.id);
+                if (at > bestAt) {
+                    best = c;
+                    bestAt = at;
+                }
+            }
+            return { ok: true, chainId: best.id };
+        }
+        const resolved = findByIdOrSuffix(chains, q);
+        if (!resolved.ok)
+            return resolved;
+        const chain = state.chains.get(resolved.chainId);
+        if (chain.status !== 'blocked')
+            return { ok: false, error: 'not-blocked' };
+        return { ok: true, chainId: chain.id };
+    }
+    // completion：判据即 buildCompletionMessage !== null（W3 收尾机械判据，防 W2 中间态误报）
+    const candidates = chains.filter((c) => {
+        const lc = lastCompleted(state, c.id);
+        return lc !== null && buildCompletionMessage(state, c.id, lc.taskId, Date.now()) !== null;
+    });
+    if (!q) {
+        if (candidates.length === 0)
+            return { ok: false, error: 'chain-not-found' };
+        let best = candidates[0];
+        let bestAt = lastCompleted(state, best.id)?.at ?? -1;
+        for (const c of candidates.slice(1)) {
+            const at = lastCompleted(state, c.id)?.at ?? -1;
+            if (at > bestAt) {
+                best = c;
+                bestAt = at;
+            }
+        }
+        return { ok: true, chainId: best.id };
+    }
+    const resolved = findByIdOrSuffix(chains, q);
+    if (!resolved.ok)
+        return resolved;
+    if (!candidates.some((c) => c.id === resolved.chainId))
+        return { ok: false, error: 'completion-not-met' };
+    return { ok: true, chainId: resolved.chainId };
+}
+/** /sms 失败 guidance（主会话模型原样转述给用户；绝不生成消息正文）。 */
+function reportGuidance(error, candidates, sendCmd) {
+    if (error === 'chain-ambiguous' && candidates?.length) {
+        const list = candidates.map((c) => `- ${c.chainId} ${c.title}`).join('\n');
+        return `匹配到多条链，请用 ${sendCmd} <chainId> 精确指定：\n${list}`;
+    }
+    if (error === 'chain-not-found')
+        return `未找到可汇报的链。可用 ${sendCmd} <chainId> 指定（完成后自动汇报的链），或 ${sendCmd} blocked [chainId] 重发阻塞通知。`;
+    if (error === 'completion-not-met')
+        return '该链不满足完成汇报判据（W3 未收尾或中间态）。';
+    if (error === 'not-blocked')
+        return '链未处于阻塞态，无阻塞通知可发。';
+    return '投递失败，请将 error 字段原样转告用户，勿自行编造原因、勿复述消息正文。';
+}
+/** /sms 手动投递：解析链 → 领域函数渲染正文（红线：正文只出自 buildCompletionMessage/buildBlockMessage，
+ *  绝不返回给模型）→ createSender 发送。不受 imDelivery.enabled 门控（显式人工调用即意图），
+ *  但仍要求 dshIm 服务在位且形状合法、目标可解析（同 auto 路径 fail-closed 规则）。 */
+export async function sendChainReport(ctx, kanban, configProvider, opts, variant, query) {
+    const state = await kanban.snapshot();
+    const resolved = resolveReportChainId(state, variant, query);
+    if (!resolved.ok) {
+        return { ok: false, error: resolved.error, guidance: reportGuidance(resolved.error, resolved.candidates, configProvider.getEffective().prefixRoutes.send) };
+    }
+    const chainId = resolved.chainId;
+    let text;
+    if (variant === 'completion') {
+        const lc = lastCompleted(state, chainId);
+        const rendered = lc !== null ? buildCompletionMessage(state, chainId, lc.taskId, Date.now()) : null;
+        if (rendered === null)
+            return { ok: false, error: 'completion-not-met' };
+        text = rendered;
+    }
+    else {
+        const reason = state.events.filter((e) => e.chainId === chainId && e.kind === 'chain/blocked').at(-1)?.payload['reason'];
+        text = buildBlockMessage(state, chainId, String(reason ?? ''), deriveStorageDir(configProvider));
+    }
+    const r = await createSender(ctx, kanban, configProvider, { ...opts, manual: true })(chainId, text);
+    if (!r.ok)
+        return { ok: false, error: r.error };
+    return { ok: true, chainId, botId: r.botId, targetId: r.targetId };
+}
+/** 接线：订阅看板事件多播通道（不动 setOnTaskCompleted 单消费者钩子）。
+ *  listener 同步返回，投递全程 fire-and-forget 自兜异常（publish 在 emit 队列内同步调用，不得拖慢落盘）。 */
+export function wireImDelivery(ctx, kanban, configProvider, opts = {}) {
+    const storageDir = deriveStorageDir(configProvider);
+    const log = opts.log ?? makeDefaultLog(storageDir);
+    const deliver = createSender(ctx, kanban, configProvider, opts);
+    const handle = (ev) => {
+        void (async () => {
+            const cfg = configProvider.getEffective().imDelivery;
+            if (!cfg?.enabled)
+                return; // 功能关闭：零开销早退（非异常，不留痕）
+            // 仅 task/completed（带 taskId）与 chain/blocked 关心事件流；其余早退，避免每个无关事件触发 snapshot 全量重放
+            if (!((ev.kind === 'task/completed' && ev.taskId) || ev.kind === 'chain/blocked'))
+                return;
+            const state = await kanban.snapshot();
+            if (ev.kind === 'task/completed' && ev.taskId) {
+                const msg = buildCompletionMessage(state, ev.chainId, ev.taskId, Date.now());
+                if (msg)
+                    await deliver(ev.chainId, msg);
+            }
+            else if (ev.kind === 'chain/blocked') {
+                const chain = state.chains.get(ev.chainId);
+                if (!chain)
+                    return;
+                const msg = buildBlockMessage(state, ev.chainId, String(ev.payload['reason'] ?? ''), storageDir);
+                await deliver(ev.chainId, msg);
+            }
+        })().catch((err) => log('[im-delivery] handler failed ev=' + ev.kind + ': ' + String(err)));
+    };
+    return kanban.subscribe(handle);
+}

package/lib/services/kanban-provider.d.ts

@@ -9,7 +9,7 @@ declare module '@deepseek-ai/cordis' {
 }
 export declare class KanbanProvider extends Service {
     readonly service: KanbanService;
-    /** T32 fix：GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
+    /** GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
     runner: {
         runTask(taskId: string): Promise<void>;
     } | null;

package/lib/services/kanban-provider.js

@@ -7,12 +7,12 @@ import { deriveGatePlan, isGatePlan, branchMatches } from '../domain/gate-policy
 import { runGateCommands } from './gate-runner.js';
 export class KanbanProvider extends Service {
     service;
-    /** T32 fix：GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
+    /** GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
     runner = null;
     /** 整链硬删除后的联动钩子（由 startDispatcher 装配注入）：dispatcher 游标同步 + V 编排 entry 清理。
      *  purge 物理重排 events seq，若不同步则删链后新建链的可唤醒事件被运行中实例永久跳过。 */
     onChainDeleted = null;
-    // Task 6：经 configProvider getter 读 effective 配置——配置面板改 wikiVault.baseUrl 后 kb_url 前缀校验热生效。
+    // 经 configProvider getter 读 effective 配置——配置面板改 wikiVault.baseUrl 后 kb_url 前缀校验热生效。
     constructor(ctx, config, configProvider) {
         super(ctx, 'kanban');
         const dir = config.storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? homedir());

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

@@ -6,7 +6,7 @@ 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

@@ -10,11 +10,15 @@ 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) => string;
+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 层——最终防线是链级看门狗（防线①）。 */