@joekytc/dsh-swarm 0.1.0

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

@@ -0,0 +1,170 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { tmpdir } from 'node:os';
+import { KanbanProvider } from '../services/kanban-provider.js';
+import { buildKanbanTools } from './kanban-tools.js';
+import { buildSpecCardTools } from './spec-card-tools.js';
+import { buildPlanningTools } from './planning-tools.js';
+import { handlePlanRoute, handleOpenspecRoute } from '../routes/prefix-router.js';
+import { MATTPOCOCK_PLANNING_GUIDANCE } from '../routes/planning-driver.js';
+import { attachSessionToWorkspace, resolveOrCreateWorkspace } from '../dispatcher/workspace-attach.js';
+import { PREFETCH_MANIFEST_SCHEMA } from '../domain/prefetch-manifest.js';
+import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+export const planningBySession = new Map();
+const KANBAN_HANDOFF_RULE = `
+## 主 agent 铁律（看板工作流 v2）
+- 你是计划者：只做需求澄清（grill-me）与最终收尾汇报；绝不执行任务本身。
+- 最高护栏：只读仓库——禁止 git 操作、禁止 write/edit 任何仓库源码；只允许写 KB（planning_checklist_save）与临时目录兜底。
+- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单 → 提醒用户 /openspec: 确认。
+- /openspec: 后链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。
+- 用 kanban_show / kanban_list / spec_card_view 观察进度，链完成后向用户汇报产物链接与轨迹入口。
+`;
+// 清单获取只有两条路：内存（路由1）> KB 候选页（路由2，LLM 读页重建）。禁止编造其他原因
+// （"先重试 / 查服务进程是否重启"类诊断是噪声：内存丢失唯一成因是插件重启，重启后按两条路恢复即可）。
+const RECOVERY_KB_GUIDANCE = (candidates) => `
+插件内存中的需求澄清清单已丢失（插件进程重启所致，属预期情况，按两条获取路由恢复即可，勿猜测其他原因）。
+知识库中检索到候选清单页：
+${candidates.map((c) => '- ' + c).join('\n')}
+恢复步骤（严格顺序）：
+1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
+2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts，requirementName 取页标题中【需求】后的名称）；
+3. 调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页）；
+4. 回存成功后提示用户重新发送 /openspec: 确认。
+禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
+`;
+const RECOVERY_NONE_GUIDANCE = `
+两条获取路由均无本需求的需求澄清清单（内存为空，知识库亦无匹配页）。
+处理步骤（严格顺序）：
+1. 消化当前对话上下文，判断需求澄清（grill-me 逐问收敛 + planning_prefetch 仓库事实）是否已完成但漏了保存动作；
+2. 若已完成澄清——立即调 planning_checklist_save 保存清单；若尚未完成——先完成澄清（缺仓库事实则先 planning_prefetch），再保存；
+3. 保存成功后提示用户重新发送 /openspec: 确认。
+禁止：在清单落库前建链建卡；编造"先重试 / 查服务进程是否重启"之类与清单无关的诊断。
+`;
+/** 预取子代理禁用的写能力工具（官方全局工具名；deny = 从 prompt 消失 + 拒绝执行，"one visibility"）。 */
+const PREFETCH_DENIED_TOOLS = ['bash', 'edit', 'write'];
+export function buildSpawnPrefetch(ctx) {
+    const subagents = ctx.get('subagents');
+    if (!subagents?.start)
+        return undefined;
+    return async (prompt, workspaceDir, parentAgent, signal) => {
+        // 血缘源必须由 agent loop 经 ToolRunContext 透传（planning_prefetch exec.agent）；
+        // 无 parent 说明工具面接线缺失，快速失败而非静默退化为无血缘会话。
+        if (!parentAgent)
+            throw new Error('planning_prefetch: missing parent agent — 工具运行时未注入 exec.agent');
+        const cwd = workspaceDir || process.cwd();
+        let run;
+        try {
+            run = await subagents.start('spawn', {
+                label: 'prefetch',
+                prompt: [{ type: 'text', text: prompt }],
+                parent: parentAgent,
+                signal: signal ?? new AbortController().signal,
+                maxDepth: 1,
+                toolFilter: { deny: [...PREFETCH_DENIED_TOOLS] },
+                outputSchema: PREFETCH_MANIFEST_SCHEMA,
+            });
+        }
+        catch (err) {
+            throw new Error('planning_prefetch: subagent start failed: ' + String(err));
+        }
+        try {
+            // 归组：缝生成的子会话（run.id = 子 session id）attach 到 cwd 对应工作区（失败不阻断只读采集）
+            await attachSessionToWorkspace(ctx, run.id, cwd, 'prefetch');
+            const result = await run.result;
+            // fail-fast：非 completed 终止（error/cancelled/...）抛错带诊断，不做静默兜底
+            if (result.stopReason !== 'completed') {
+                throw new Error(`planning_prefetch: subagent ended with stopReason=${result.stopReason}${result.error ? ' — ' + result.error : ''}`);
+            }
+            // outputSchema 由 spawn provider 在子代理侧强制校验；structured 合法即用，文本兜底仅作能力缺失防御
+            if (result.structured !== undefined)
+                return JSON.stringify(result.structured);
+            return (result.output ?? []).map((b) => b.text ?? '').join('');
+        }
+        finally {
+            await run.dispose().catch(() => undefined);
+        }
+    };
+}
+/** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
+ *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
+ *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
+export function registerMainSessionTools(ctx, config) {
+    const registry = ctx.get('tools');
+    if (!registry)
+        return; // 测试裸 Context 无 tools 服务（P1-9 无 inject 依赖），跳过注册
+    const provider = ctx.get('kanban');
+    if (!provider)
+        return;
+    const service = provider.service;
+    // 生产 wiring（src/index.ts:44）仅保证 tools+kanban 可用，无 wiki 服务 → 用 config.wikiVault 自建
+    //（与 dispatcher 构造同源）；测试经 ctx.get('wiki') 注入 mock 客户端。
+    const wiki = ctx.get('wiki') ?? new WikiVaultClient(config.wikiVault);
+    const caller = () => ({ actor: 'human' });
+    // 只读 kanban 子集（无 create/complete/block）
+    const readOnly = new Set(['kanban_show', 'kanban_chain', 'kanban_list', 'kanban_comment']);
+    for (const tool of buildKanbanTools(service, caller)) {
+        const name = tool.name;
+        if (name && readOnly.has(name))
+            registry.register(tool);
+    }
+    // spec_card_view 仅保留（主 agent 只读规格卡；编辑/批准经清单→/openspec: 建链，GUI 走 HTTP 桥）
+    for (const tool of buildSpecCardTools(service, caller)) {
+        if (tool.name === 'spec_card_view')
+            registry.register(tool);
+    }
+    // planning 工具（清单落库 + 只读预取）——spawnPrefetch 由模块级 buildSpawnPrefetch 提供（可单测）
+    for (const tool of buildPlanningTools({
+        service, wiki,
+        getCaller: caller,
+        spawnPrefetch: buildSpawnPrefetch(ctx),
+        tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
+        pagePrefix: config.wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
+        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 };
+            planningBySession.set('session_main', { ...cur, checklist, checklistRef: ref, checklistSource: source });
+        },
+    }))
+        registry.register(tool);
+    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链
+    registry.register(defineTool({
+        name: 'kanban_route',
+        description: 'MUST be called when the human message starts with /plan: or /openspec:. This is dsh-swarm planning, NOT the built-in /plan plan mode. /plan: = zero side-effect + start grill-me; /openspec: = create chain from saved checklist and start execution.',
+        parameters: { message: { type: 'string', required: true } },
+        output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+        async execute(args, exec) {
+            // M2(Q5)+归组：仅 /plan: 分支捕获主 agent 工作空间并可能询问注册——/openspec:/none 不触发，
+            // 避免死代码副作用多弹一次 ask（/openspec: 实际用的是 planningBySession 已存的 workspaceDir）。
+            // header.cwd 缺失或未注册时询问用户注册工作区；仍不可得保持 null（链任务随后 block 'workspace-unknown'）。
+            const plan = await handlePlanRoute(args.message, service, config.prefixRoutes, 'session_main');
+            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 });
+                return { kind: 'plan', guidance: MATTPOCOCK_PLANNING_GUIDANCE + KANBAN_HANDOFF_RULE };
+            }
+            if (plan.kind === 'none')
+                return { kind: 'none' };
+            // 路由1（内存）：planningBySession 命中 → 直接建链
+            const pctx = planningBySession.get('session_main');
+            if (pctx?.checklist && pctx.checklistRef) {
+                const input = { workspaceDir: pctx.workspaceDir, checklist: pctx.checklist, checklistRef: pctx.checklistRef, requirementName: pctx.requirementName };
+                const r = await handleOpenspecRoute(args.message, service, config.prefixRoutes, input, 'session_main');
+                return { kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, guidance: KANBAN_HANDOFF_RULE };
+            }
+            // 路由2（知识库）：内存丢失（插件重启）→ 搜 KB 候选清单页供 LLM 读页重建；搜不到/不可达 → 两条路皆空
+            let candidates = [];
+            try {
+                const pagePrefix = config.wikiVault?.pagePrefix ?? 'projects/';
+                candidates = (await wiki.search('【需求】')).map((r) => r.path).filter((p) => p.startsWith(pagePrefix)).slice(0, 5);
+            }
+            catch { /* KB 不可达/搜索失败 → 候选为空，走两条路皆空分支 */ }
+            return {
+                kind: 'openspec', approved: false, reason: 'no-checklist',
+                recovery: candidates.length > 0 ? 'kb' : 'none',
+                checklistCandidates: candidates,
+                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(candidates) : RECOVERY_NONE_GUIDANCE,
+            };
+        },
+    }));
+    console.info('[dsh-swarm] main-session tools registered (v2: kanban_route + planning + spec view + read-only kanban)');
+}

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

@@ -0,0 +1,32 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { KanbanService } from '../domain/kanban-service.js';
+import type { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import { type PlanningChecklist } from '../domain/planning-checklist.js';
+import type { ToolCaller } from './kanban-tools.js';
+import type { AgentModelOptions } from '../dispatcher/dispatcher.js';
+/** 工具运行时上下文（dsh-tools ToolRunContext 窄型）：agent loop 注入调用者 Agent 与取消信号，
+ *  planning_prefetch 经官方子代理缝启动时需透传（parent + signal）。 */
+export interface PrefetchExecContext {
+    agent?: Agent;
+    signal?: AbortSignal;
+}
+export interface PlanningToolDeps {
+    service: KanbanService;
+    wiki: WikiVaultClient;
+    getCaller(): ToolCaller;
+    /** 真实实现：经官方子代理缝（ctx.subagents.start）启动只读预取子代理并返回其文本输出；测试注入 stub。
+     *  parentAgent = 发起调用的主 agent（血缘/模型继承源），由 planning_prefetch 的 exec.agent 透传。 */
+    spawnPrefetch?(prompt: string, workspaceDir: string, parentAgent?: Agent, signal?: AbortSignal): Promise<string>;
+    tempDir(): string;
+    pagePrefix?: string;
+    ownerSessionId?: string;
+    defaultModel?: AgentModelOptions;
+    /** 清单落库成功回调（kb 与 temp 两分支各调一次），供 main-session-tools 回写 planningBySession。 */
+    onChecklistSaved?(saved: {
+        ref: string;
+        source: 'kb' | 'temp';
+        checklist: PlanningChecklist;
+    }): void;
+}
+/** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
+export declare function buildPlanningTools(deps: PlanningToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/planning-tools.js

@@ -0,0 +1,102 @@
+// src/tools/planning-tools.ts
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { validatePlanningChecklist, formatChecklistBody } from '../domain/planning-checklist.js';
+import { validatePrefetchManifest } from '../domain/prefetch-manifest.js';
+import { buildChecklistSlug, CHECKLIST_PAGE_PREFIX } from '../wiki/page-path.js';
+const isWikiError = (e) => e instanceof Error && e.code === 'kb-unreachable';
+/** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
+export function buildPlanningTools(deps) {
+    const pagePrefix = deps.pagePrefix ?? 'projects/';
+    const session = deps.ownerSessionId ?? 'session_main';
+    return [
+        defineTool({
+            name: 'planning_checklist_save',
+            description: 'Save the converged requirement-clarification checklist (structured schema) to KB, falling back to a temp dir if KB is unreachable. Returns ref/path + authoritative repo path. restoreRef (optional) = existing KB page path to overwrite in place (recovery path when in-memory context was lost); omit for first-time save (creates a new timestamped page).',
+            parameters: { checklist: { type: 'json', required: true, description: 'Structured PlanningChecklist: spec six sections + manifest(repo.files) + clarifications + doubts. checklist.requirementName (optional) = /plan: rest first sentence, used for the checklist page title 【需求】, same source as the task-card title' }, restoreRef: { type: 'string', description: 'Optional KB page path to overwrite in place (recovery path); omit for new save' } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = deps.getCaller();
+                if (caller.actor !== 'human')
+                    throw new Error('permission denied: planning_checklist_save');
+                const errors = validatePlanningChecklist(args.checklist);
+                if (errors.length > 0)
+                    throw new Error('invalid planning checklist: ' + errors.join('; '));
+                const checklist = args.checklist;
+                const body = formatChecklistBody(checklist);
+                // 恢复路径（内存丢失后重建）：传 restoreRef 则覆盖原页，不产生重复页
+                if (args.restoreRef && args.restoreRef.startsWith(pagePrefix)) {
+                    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 };
+                    }
+                    catch (err) {
+                        if (!isWikiError(err))
+                            throw err;
+                        // KB 不可达 → 落临时目录兜底（不覆盖原页），回调仍回填内存
+                    }
+                }
+                const pagePath = `${CHECKLIST_PAGE_PREFIX}${buildChecklistSlug(checklist.requirementName ?? checklist.spec.problem)}-${Date.now().toString(36)}.md`;
+                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 };
+                }
+                catch (err) {
+                    if (!isWikiError(err))
+                        throw err;
+                    // KB 不可达 → 临时目录兜底
+                    const local = `${deps.tempDir()}/${session}-${Date.now().toString(36)}.md`;
+                    const { writeFileSync, mkdirSync } = await import('node:fs');
+                    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 };
+                }
+            },
+        }),
+        defineTool({
+            name: 'planning_prefetch',
+            description: 'Dispatch a READ-ONLY sub-agent to gather repo/material/KB facts for requirement clarification. Returns a structured PrefetchManifest (repo.localPath + files baseline). Never modifies the repo.',
+            parameters: {
+                scope: { type: 'string', required: true, description: 'What to prefetch (e.g. the target feature area, existing tab implementation, enums)' },
+                repoPath: { type: 'string', description: 'Target repo absolute path (if known); sub-agent confirms it' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args, exec) {
+                const caller = deps.getCaller();
+                if (caller.actor !== 'human')
+                    throw new Error('permission denied: planning_prefetch');
+                const prompt = [
+                    '# 只读仓库预取（planning_prefetch）',
+                    `scope: ${args.scope}`,
+                    `目标仓库路径: ${args.repoPath ?? '(未指定，需你确认绝对路径)'}`,
+                    '规则：只读采集仓库事实（本地路径/远端 URL/当前分支/未提交改动/目标文件基线），禁止 git 写操作、禁止修改任何文件。',
+                    '输出：仅输出一个 JSON 对象（无前后缀文字），形如 {"repo":{"localPath":"<绝对路径>","remoteUrl":"<可选>","branch":"<可选>","dirtyFiles":[]},"files":[{"path":"<相对路径>","expected":"exists|absent|content-hash","note":"<可选>"}]}',
+                ].join('\n');
+                // 官方子代理缝要求 parent（血缘/模型继承/工作目录源）+ signal（取消通道），
+                // 均由 agent loop 注入的 ToolRunContext 透传；测试直调无 exec → undefined（stub 不依赖）
+                const output = deps.spawnPrefetch
+                    ? await deps.spawnPrefetch(prompt, args.repoPath ?? '', exec?.agent, exec?.signal)
+                    : (() => { throw new Error('planning_prefetch: spawnPrefetch not wired — main-session-tools 必须注入只读预取子代理'); })();
+                const manifest = parseManifestOutput(output);
+                return { ok: true, manifest };
+            },
+        }),
+    ];
+}
+function parseManifestOutput(output) {
+    const text = output.trim();
+    const jsonText = text.startsWith('{') ? text : text.slice(text.indexOf('{'), text.lastIndexOf('}') + 1);
+    let raw;
+    try {
+        raw = JSON.parse(jsonText);
+    }
+    catch {
+        throw new Error('planning_prefetch: sub-agent did not return valid JSON manifest');
+    }
+    const errors = validatePrefetchManifest(raw);
+    if (errors.length > 0)
+        throw new Error('planning_prefetch: invalid manifest from sub-agent: ' + errors.join('; '));
+    return raw;
+}

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

@@ -0,0 +1,5 @@
+import type { WikiWorker } from '../roles/wiki-worker.js';
+import type { Task } from '../domain/types.js';
+import type { ToolCaller } from './kanban-tools.js';
+/** 预取工具工厂（W 角色 agent scope）：file/external/kb 三模式，产物引用登记（原汁原味，禁压缩）。 */
+export declare function buildPrefetchTools(worker: WikiWorker, getTask: (taskId: string) => Promise<Task>, getCaller: () => ToolCaller): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/prefetch-tools.js

@@ -0,0 +1,59 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { can } from '../domain/permissions.js';
+function guard(action, caller) {
+    if (!can(action, caller.actor, null))
+        throw new Error('permission denied: ' + action);
+}
+/** 预取工具工厂（W 角色 agent scope）：file/external/kb 三模式，产物引用登记（原汁原味，禁压缩）。 */
+export function buildPrefetchTools(worker, getTask, getCaller) {
+    return [
+        defineTool({
+            name: 'prefetch_file',
+            description: 'Register a read-only file-prefetch artifact reference under the task workspace.',
+            parameters: {
+                taskId: { type: 'string', required: true },
+                source: { type: 'string', required: true, description: 'Absolute path under the task workspace' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('prefetch', caller);
+                const task = await getTask(args.taskId);
+                const out = await worker.executePrefetch(task, 'file', args.source);
+                return out;
+            },
+        }),
+        defineTool({
+            name: 'prefetch_external',
+            description: 'Register an external-research prefetch artifact (writes ws/prefetch-external.md).',
+            parameters: {
+                taskId: { type: 'string', required: true },
+                source: { type: 'string', description: 'Optional path; defaults to the workspace prefetch-external.md' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('prefetch', caller);
+                const task = await getTask(args.taskId);
+                const out = await worker.executePrefetch(task, 'external', args.source ?? '');
+                return out;
+            },
+        }),
+        defineTool({
+            name: 'prefetch_kb',
+            description: 'Register a knowledge-base prefetch artifact (writes ws/prefetch-kb.md).',
+            parameters: {
+                taskId: { type: 'string', required: true },
+                source: { type: 'string', description: 'Optional path; defaults to the workspace prefetch-kb.md' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('prefetch', caller);
+                const task = await getTask(args.taskId);
+                const out = await worker.executePrefetch(task, 'kb', args.source ?? '');
+                return out;
+            },
+        }),
+    ];
+}

package/lib/tools/spec-card-tools.d.ts

@@ -0,0 +1,4 @@
+import { KanbanService } from '../domain/kanban-service.js';
+import type { ToolCaller } from './kanban-tools.js';
+/** 规格卡工具工厂：主会话（human）专属——编辑/批准仅 human；查看任意角色可读。 */
+export declare function buildSpecCardTools(service: KanbanService, getCaller: () => ToolCaller): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/spec-card-tools.js

@@ -0,0 +1,75 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { KanbanService } from '../domain/kanban-service.js';
+import { can } from '../domain/permissions.js';
+function guard(action, caller) {
+    if (!can(action, caller.actor, null))
+        throw new Error('permission denied: ' + action);
+}
+/** 逐字段校验 spec card sections：数组进 string 段（如 testing）会在下游 .trim() 崩溃。 */
+function validateSections(sections) {
+    const errors = [];
+    const s = (sections ?? {});
+    const strFields = [
+        ['problem', 'problem'], ['solution', 'solution'], ['testing', 'testing'], ['out_of_scope', 'out_of_scope'],
+    ];
+    for (const [, key] of strFields) {
+        if (typeof s[key] !== 'string')
+            errors.push(`sections.${key} must be a string (got: ${JSON.stringify(s[key])})`);
+    }
+    const arrFields = [['user_stories', 'user_stories'], ['impl_decisions', 'impl_decisions']];
+    for (const [, key] of arrFields) {
+        if (!Array.isArray(s[key]))
+            errors.push(`sections.${key} must be an array`);
+        else if (s[key].some((v) => typeof v !== 'string'))
+            errors.push(`sections.${key} must be string[]`);
+    }
+    return errors;
+}
+/** 规格卡工具工厂：主会话（human）专属——编辑/批准仅 human；查看任意角色可读。 */
+export function buildSpecCardTools(service, getCaller) {
+    return [
+        defineTool({
+            name: 'spec_card_view',
+            description: 'View a spec card (draft or approved).',
+            parameters: { cardId: { type: 'string', required: true, description: 'Spec card id (sc_xxx)' } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const state = await service.snapshot();
+                const card = state.specCards.get(args.cardId);
+                if (!card)
+                    throw new Error('unknown spec card: ' + args.cardId);
+                return card;
+            },
+        }),
+        defineTool({
+            name: 'spec_card_edit',
+            description: 'Edit a draft spec card sections (human only).',
+            parameters: {
+                cardId: { type: 'string', required: true },
+                sections: { type: 'json', required: true, description: 'Six-section spec card body' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const errs = validateSections(args.sections);
+                if (errs.length > 0)
+                    throw new Error('invalid spec card sections: ' + errs.join('; '));
+                const caller = getCaller();
+                guard('spec-edit', caller);
+                const card = await service.editSpecCard(args.cardId, args.sections, caller.actor);
+                return card;
+            },
+        }),
+        defineTool({
+            name: 'spec_card_approve',
+            description: 'Approve a spec card and move its chain to executing (human only).',
+            parameters: { cardId: { type: 'string', required: true } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('spec-approve', caller);
+                const card = await service.approveSpecCard(args.cardId, caller.actor);
+                return card;
+            },
+        }),
+    ];
+}

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

@@ -0,0 +1,4 @@
+import type { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import type { ToolCaller } from './kanban-tools.js';
+/** wiki-vault 工具工厂（W 角色 agent scope）：search/read/write，权限兜底 wiki-read=w/d、wiki-write=w。 */
+export declare function buildWikiTools(wiki: WikiVaultClient, getCaller: () => ToolCaller): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/wiki-tools.js

@@ -0,0 +1,57 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { can } from '../domain/permissions.js';
+import { assertAllowedWikiPagePath } from '../wiki/page-path.js';
+function guard(action, caller) {
+    if (!can(action, caller.actor, null))
+        throw new Error('permission denied: ' + action);
+}
+/** wiki-vault 工具工厂（W 角色 agent scope）：search/read/write，权限兜底 wiki-read=w/d、wiki-write=w。 */
+export function buildWikiTools(wiki, getCaller) {
+    return [
+        defineTool({
+            name: 'wiki_search',
+            description: 'Search the wiki-vault knowledge base.',
+            parameters: { q: { type: 'string', required: true } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('wiki-read', caller);
+                const results = await wiki.search(args.q);
+                return results;
+            },
+        }),
+        defineTool({
+            name: 'wiki_read',
+            description: 'Read a wiki-vault page (read-only KB access).',
+            parameters: { pagePath: { type: 'string', required: true } },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('wiki-read', caller);
+                const page = await wiki.read(args.pagePath);
+                return page;
+            },
+        }),
+        defineTool({
+            name: 'wiki_write',
+            description: 'Write a wiki-vault page under the configured pagePrefix (W only).',
+            parameters: {
+                pagePath: { type: 'string', required: true },
+                content: { type: 'string', required: true },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args) {
+                const caller = getCaller();
+                guard('wiki-write', caller);
+                // Q3&5：工具边界强校验——只允许 projects/checklists/、projects/ch_*/t_*.md、projects/ch_*/review/
+                // 三类命名空间（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 手写错域名）。
+                // 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

@@ -0,0 +1,9 @@
+import type { WikiVaultClient } from './wiki-vault-client.js';
+import type { BoardState } from '../domain/types.js';
+/**
+ * 机械互链登记：链上 w:kb 任务完成时调用。
+ * - 清单页：追加/更新「关联文档」区块，列出链上全部已 done 的 W2/W3 页。
+ * - 当前页：写回清单页链接（清单 ref 来自规格卡 kind:'kb' 附件）。
+ * 幂等（containsLine / 区块就地替换）；任何 wiki 读/写失败均静默跳过，不抛错。
+ */
+export declare function syncKbLinks(wiki: WikiVaultClient, state: BoardState, taskId: string): Promise<void>;

package/lib/wiki/kb-linkage.js

@@ -0,0 +1,87 @@
+/** 目标页若已含指定行（幂等判据），则不再重复注入。 */
+function containsLine(content, line) {
+    return content.split('\n').some((l) => l.trim() === line.trim());
+}
+/** 构造页内互链行：用 wiki 内部相对路径（#/page/…），host 变化不失效。 */
+function linkLine(label, pagePath) {
+    return `- ${label}：[#/page/${pagePath}](#/page/${pagePath})`;
+}
+/** 读取现有内容；页不存在或 KB 不可达 → 返回 null（调用方跳过，不阻塞）。 */
+async function tryRead(wiki, pagePath) {
+    try {
+        const d = await wiki.read(pagePath);
+        return d.rawMd;
+    }
+    catch {
+        return null;
+    }
+}
+async function tryWrite(wiki, pagePath, content) {
+    try {
+        await wiki.write(pagePath, content);
+    }
+    catch {
+        // 登记失败不阻塞完成（completeTask 钩子外再捕获）
+    }
+}
+/** 往文档追加「关联文档」区块（已存在则就地更新，避免重复追加）。 */
+function upsertLinkedBlock(content, header, lines) {
+    const block = ['## 关联文档', `> ${header}`, ...lines, ''].join('\n');
+    const idx = content.indexOf('## 关联文档');
+    if (idx === -1)
+        return content.replace(/\n*$/, '\n\n') + block;
+    // 替换旧区块：找到下一个二级标题或结尾
+    const next = content.indexOf('\n## ', idx + '## 关联文档'.length);
+    const end = next === -1 ? content.length : next + 1;
+    return content.slice(0, idx) + block + '\n' + content.slice(end);
+}
+/**
+ * 机械互链登记：链上 w:kb 任务完成时调用。
+ * - 清单页：追加/更新「关联文档」区块，列出链上全部已 done 的 W2/W3 页。
+ * - 当前页：写回清单页链接（清单 ref 来自规格卡 kind:'kb' 附件）。
+ * 幂等（containsLine / 区块就地替换）；任何 wiki 读/写失败均静默跳过，不抛错。
+ */
+export async function syncKbLinks(wiki, state, taskId) {
+    const task = state.tasks.get(taskId);
+    if (!task || task.assignee !== 'w' || task.mode !== 'kb')
+        return;
+    const chain = state.chains.get(task.chainId);
+    if (!chain?.specCardId)
+        return;
+    const spec = state.specCards.get(chain.specCardId);
+    // 清单页 ref：kind:'kb' 附件；仅接受 projects/ 命名空间（临时目录兜底路径不是 KB 页，跳过）
+    const checklistRef = spec?.attachments.find((a) => a.kind === 'kb')?.ref ?? null;
+    const checklistPath = checklistRef && checklistRef.startsWith('projects/') ? checklistRef : null;
+    // 链上已 done 的 W2/W3 页（含当前任务所属页）
+    const pages = [...state.tasks.values()]
+        .filter((t) => t.chainId === task.chainId && t.assignee === 'w' && t.mode === 'kb' && t.status === 'done')
+        .map((t) => ({
+        title: t.title,
+        pagePath: typeof state.handoffs.get(t.id)?.metadata?.page_path === 'string'
+            ? state.handoffs.get(t.id).metadata.page_path
+            : null,
+    }))
+        .filter((p) => p.pagePath !== null && p.pagePath.startsWith('projects/'));
+    if (pages.length === 0)
+        return;
+    // 1) 清单页：登记全部 W2/W3 页链接
+    if (checklistPath) {
+        const cur = await tryRead(wiki, checklistPath);
+        if (cur !== null) {
+            const lines = pages.map((p) => linkLine(p.title, p.pagePath));
+            await tryWrite(wiki, checklistPath, upsertLinkedBlock(cur, '需求完整链路', lines));
+        }
+    }
+    // 2) 每个 W2/W3 页：写回清单页链接
+    if (checklistPath) {
+        for (const p of pages) {
+            const cur = await tryRead(wiki, p.pagePath);
+            if (cur === null)
+                continue;
+            const line = linkLine('需求清单', checklistPath);
+            if (containsLine(cur, line))
+                continue;
+            await tryWrite(wiki, p.pagePath, upsertLinkedBlock(cur, '需求清单', [line]));
+        }
+    }
+}

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

@@ -0,0 +1,6 @@
+export declare const CHECKLIST_PAGE_PREFIX = "projects/checklists/";
+/** 从需求名（回退 problem）派生 URL 安全 slug：ASCII 化、空格/特殊字符→-、限长 40；全非 ASCII（如中文）兜底 'req'。 */
+export declare function buildChecklistSlug(name: string): string;
+export declare function isAllowedWikiPagePath(pagePath: string): boolean;
+/** 工具边界硬校验：不符白名单直接抛 kb-rejected（wiki_write 用）。 */
+export declare function assertAllowedWikiPagePath(pagePath: string): void;