@joekytc/dsh-swarm 0.1.1 → 0.2.0

package/lib/services/kanban-provider.js

@@ -1,14 +1,52 @@
 import { Service } from '@deepseek-ai/cordis';
 import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
 import { KanbanService } from '../domain/kanban-service.js';
 import { FileEventStore } from '../domain/event-store.js';
+import { deriveGatePlan, isGatePlan, branchMatches } from '../domain/gate-policy.js';
+import { runGateCommands } from './gate-runner.js';
 export class KanbanProvider extends Service {
     service;
     /** T32 fix：GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
     runner = null;
-    constructor(ctx, config) {
+    /** 整链硬删除后的联动钩子（由 startDispatcher 装配注入）：dispatcher 游标同步 + V 编排 entry 清理。
+     *  purge 物理重排 events seq，若不同步则删链后新建链的可唤醒事件被运行中实例永久跳过。 */
+    onChainDeleted = null;
+    // Task 6：经 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());
-        this.service = new KanbanService(new FileEventStore(dir), config.wikiVault?.baseUrl);
+        this.service = new KanbanService(new FileEventStore(dir), () => configProvider.getEffective().wikiVault?.baseUrl);
+        // P1 实测闸装配（组合根）：complete 前派生 GatePlan → 分支一致性核对 → 实测执行。
+        // hook 绝不 throw：意外异常记日志并返回 null（零感知 skip，fail-open 与分支不一致语义一致）。
+        this.service.setGateHook(async (task, handoff) => {
+            try {
+                // 热读取（同 wikiVault.baseUrl 先例，getEffective）：配置面板改 gates 后无需重建即生效。
+                const cfg = configProvider.getEffective().gates ?? { enabled: true, timeoutMs: 600000, forbidden: ['rm -rf /', 'git push'] };
+                const plan = deriveGatePlan({ assignee: task.assignee, mode: task.mode, handoff, config: { enabled: cfg.enabled } });
+                if (!isGatePlan(plan))
+                    return null; // skip：disabled/非 D/旧卡/路径违规
+                const wt = plan.commands[0].cwd;
+                // 分支一致性核对（防报假 worktree 绕闸）：查询失败或与 metadata.branch 不一致 → skip 零感知。
+                const current = await new Promise((resolve) => {
+                    const child = spawn('git', ['-C', wt, 'rev-parse', '--abbrev-ref', 'HEAD'], { stdio: ['ignore', 'pipe', 'pipe'] });
+                    let out = '';
+                    child.stdout.on('data', (c) => { out += c.toString('utf8'); });
+                    child.on('error', () => resolve(null));
+                    child.on('close', (code) => resolve(code === 0 ? out.trim() || null : null));
+                });
+                if (!branchMatches(current, handoff.metadata?.['branch']))
+                    return null;
+                const report = await runGateCommands(plan.commands, { timeoutMs: cfg.timeoutMs, forbidden: cfg.forbidden });
+                const detail = report.ok
+                    ? plan.commands.map((c) => c.command).join(' && ') + ' exit 0'
+                    : `${report.failure.code}: ${report.failure.command} — ${report.failure.detail}\n${(report.results.at(-1)?.output ?? '').slice(-2000)}`;
+                return { ok: report.ok, detail };
+            }
+            catch (error) {
+                console.error('[dsh-swarm] gate hook failed (zero-awareness skip): ' + String(error));
+                return null;
+            }
+        });
     }
 }

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

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

package/lib/services/llm-catalog.js

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

package/lib/tools/kanban-tools.js

@@ -1,4 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { KanbanService } from '../domain/kanban-service.js';
 import { can } from '../domain/permissions.js';
 function guard(action, caller, task = null) {

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

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { KanbanConfig } from '../config.js';
+import type { PrefixRoutes } from '../config.js';
+import type { ConfigProvider } from '../services/config-provider.js';
 import { type PlanningToolDeps } from './planning-tools.js';
 import type { PlanningChecklist } from '../domain/planning-checklist.js';
 /** v2 规划上下文（/plan: 捕获 → planning_checklist_save 回写 → /openspec: 建链）。模块级内存，随插件进程存活。 */
@@ -13,8 +14,22 @@ export interface PlanningContext {
     requirementName: string | null;
 }
 export declare const planningBySession: Map<string, PlanningContext>;
+export declare const KANBAN_HANDOFF_RULE: (routes: PrefixRoutes) => string;
+/** 防线③：/openspec: 成功后的逐链确定性叙述规则（2026-09-04 mtmgp81q：模型口播 ch_1_mtjrhkrf
+ *  与工具结果 ch_1_mtmgp81q 脱节）。逐字引用锚点 + firstCard 成败结论；整包缓存回放仍可能
+ *  绕过 prompt 层——最终防线是链级看门狗（防线①）。 */
+export declare function buildOpenspecNarrationRule(r: {
+    chainId: string;
+    specCardId: string;
+    firstCard?: {
+        taskId: string;
+        status: string;
+    } | {
+        pending: true;
+    };
+}): string;
 export declare function buildSpawnPrefetch(ctx: Context): PlanningToolDeps['spawnPrefetch'] | undefined;
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
-export declare function registerMainSessionTools(ctx: Context, config: KanbanConfig): void;
+export declare function registerMainSessionTools(ctx: Context, configProvider: ConfigProvider): void;

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

@@ -1,42 +1,66 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { tmpdir } from 'node:os';
 import { KanbanProvider } from '../services/kanban-provider.js';
 import { buildKanbanTools } from './kanban-tools.js';
 import { buildSpecCardTools } from './spec-card-tools.js';
 import { buildPlanningTools } from './planning-tools.js';
-import { handlePlanRoute, handleOpenspecRoute } from '../routes/prefix-router.js';
-import { MATTPOCOCK_PLANNING_GUIDANCE } from '../routes/planning-driver.js';
+import { handlePlanRoute, handleOpenspecRoute, handleLearningRoute } from '../routes/prefix-router.js';
+import { recallMemoryIndex, searchChecklists } from '../wiki/memory-recall.js';
+import { buildPlanningGuidance } from '../routes/planning-driver.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from '../dispatcher/workspace-attach.js';
 import { PREFETCH_MANIFEST_SCHEMA } from '../domain/prefetch-manifest.js';
 import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
+import { LocalWikiClient } from '../wiki/local-kb-client.js';
+import { ensureLocalKbRoot } from '../wiki/local-kb.js';
+import { LOCAL_CHECKLIST_PREFIX } from '../wiki/page-path.js';
 export const planningBySession = new Map();
-const KANBAN_HANDOFF_RULE = `
+export const KANBAN_HANDOFF_RULE = (routes) => `
 ## 主 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；你不要自己执行。
+- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单 → 提醒用户 ${routes.openspec} 确认。
+- ${routes.openspec} 后链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。
 - 用 kanban_show / kanban_list / spec_card_view 观察进度，链完成后向用户汇报产物链接与轨迹入口。
+- 经验沉淀：链路完成后，用户可发 ${routes.learning}（或 ${routes.learning} <chainId>）沉淀本链经验；主 agent 消化机械证据包后调 planning_learning_save 入库。
+- 叙述铁律：回复中的链号/卡号（ch_/sc_/t_ 编号）只能逐字复制自工具结果；建链成败以工具结果字段为准，禁止编造或沿用旧对话里的编号。
 `;
+/** 防线③：/openspec: 成功后的逐链确定性叙述规则（2026-09-04 mtmgp81q：模型口播 ch_1_mtjrhkrf
+ *  与工具结果 ch_1_mtmgp81q 脱节）。逐字引用锚点 + firstCard 成败结论；整包缓存回放仍可能
+ *  绕过 prompt 层——最终防线是链级看门狗（防线①）。 */
+export function buildOpenspecNarrationRule(r) {
+    const firstCardLine = !r.firstCard
+        ? '- 首卡结果未采集（旧返回体）。汇报前先调 kanban_show 复核链状态，以 kanban_show 复核后再汇报，禁止臆断建卡成功。'
+        : 'pending' in r.firstCard
+            ? `- 首卡尚未创建（等待超时，看门狗接管）。回复必须写明「首卡尚未创建，看门狗接管」，禁止声称建卡成功。`
+            : `- 首卡已创建：taskId=${r.firstCard.taskId}（status=${r.firstCard.status}）。回复必须写明「首卡已创建」。`;
+    return [
+        '## 本次建链结果（回复必须逐字引用，禁止改写编号）',
+        `- chainId=${r.chainId}`,
+        `- specCardId=${r.specCardId}`,
+        firstCardLine,
+        '- 铁律：回复中的 ch_/sc_/t_ 编号只能逐字复制自本结果；禁止出现本结果之外的任何编号；禁止声称与本结果矛盾的建卡状态。',
+    ].join('\n');
+}
 // 清单获取只有两条路：内存（路由1）> KB 候选页（路由2，LLM 读页重建）。禁止编造其他原因
 // （"先重试 / 查服务进程是否重启"类诊断是噪声：内存丢失唯一成因是插件重启，重启后按两条路恢复即可）。
-const RECOVERY_KB_GUIDANCE = (candidates) => `
+const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
 插件内存中的需求澄清清单已丢失（插件进程重启所致，属预期情况，按两条获取路由恢复即可，勿猜测其他原因）。
 知识库中检索到候选清单页：
 ${candidates.map((c) => '- ' + c).join('\n')}
 恢复步骤（严格顺序）：
 1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
-2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts，requirementName 取页标题中【需求】后的名称）；
+2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；
 3. 调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页）；
-4. 回存成功后提示用户重新发送 /openspec: 确认。
+4. 回存成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
 `;
-const RECOVERY_NONE_GUIDANCE = `
+const RECOVERY_NONE_GUIDANCE = (routes) => `
 两条获取路由均无本需求的需求澄清清单（内存为空，知识库亦无匹配页）。
 处理步骤（严格顺序）：
 1. 消化当前对话上下文，判断需求澄清（grill-me 逐问收敛 + planning_prefetch 仓库事实）是否已完成但漏了保存动作；
 2. 若已完成澄清——立即调 planning_checklist_save 保存清单；若尚未完成——先完成澄清（缺仓库事实则先 planning_prefetch），再保存；
-3. 保存成功后提示用户重新发送 /openspec: 确认。
+3. 保存成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：在清单落库前建链建卡；编造"先重试 / 查服务进程是否重启"之类与清单无关的诊断。
 `;
 /** 预取子代理禁用的写能力工具（官方全局工具名；deny = 从 prompt 消失 + 拒绝执行，"one visibility"）。 */
@@ -87,7 +111,7 @@ export function buildSpawnPrefetch(ctx) {
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 用清单建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
-export function registerMainSessionTools(ctx, config) {
+export function registerMainSessionTools(ctx, configProvider) {
     const registry = ctx.get('tools');
     if (!registry)
         return; // 测试裸 Context 无 tools 服务（P1-9 无 inject 依赖），跳过注册
@@ -95,9 +119,13 @@ export function registerMainSessionTools(ctx, config) {
     if (!provider)
         return;
     const service = provider.service;
-    // 生产 wiring（src/index.ts:44）仅保证 tools+kanban 可用，无 wiki 服务 → 用 config.wikiVault 自建
-    //（与 dispatcher 构造同源）；测试经 ctx.get('wiki') 注入 mock 客户端。
-    const wiki = ctx.get('wiki') ?? new WikiVaultClient(config.wikiVault);
+    // 生产 wiring（src/index.ts）仅保证 tools+kanban 可用，无 wiki 服务 → 经 configProvider 自建
+    //（与 dispatcher 构造同源，getEffective() 调用时热读取 baseUrl/pagePrefix）；测试经 ctx.get('wiki') 注入 mock 客户端。
+    // D3 双模式：local 模式走 LocalWikiClient 本地检索（不发 HTTP），remote 用配置的 WikiVaultClient。
+    const kbMode = configProvider.mode;
+    const wiki = kbMode === 'local'
+        ? new LocalWikiClient(ensureLocalKbRoot())
+        : (ctx.get('wiki') ?? new WikiVaultClient(() => configProvider.getEffective().wikiVault));
     const caller = () => ({ actor: 'human' });
     // 只读 kanban 子集（无 create/complete/block）
     const readOnly = new Set(['kanban_show', 'kanban_chain', 'kanban_list', 'kanban_comment']);
@@ -113,11 +141,15 @@ export function registerMainSessionTools(ctx, config) {
     }
     // planning 工具（清单落库 + 只读预取）——spawnPrefetch 由模块级 buildSpawnPrefetch 提供（可单测）
     for (const tool of buildPlanningTools({
-        service, wiki,
+        service, wiki: wiki, // local 模式为 LocalWikiClient（write/read/search 同面，D3 双模式客户端）
         getCaller: caller,
         spawnPrefetch: buildSpawnPrefetch(ctx),
         tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
-        pagePrefix: config.wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
+        pagePrefix: configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
+        kbMode: configProvider.mode, // D3 双模式：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,
         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 };
@@ -125,44 +157,99 @@ export function registerMainSessionTools(ctx, config) {
         },
     }))
         registry.register(tool);
-    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链
+    // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链（前缀路由注册时快照，用于工具描述）
+    const { plan, openspec, learning } = configProvider.getEffective().prefixRoutes;
     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.',
+        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 } },
         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');
+            const plan = await handlePlanRoute(args.message, service, configProvider.getEffective().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 };
+                let guidance = buildPlanningGuidance(configProvider.getEffective().prefixRoutes) + KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes);
+                if ((configProvider.getEffective().memory?.enabled ?? true) && workspaceDir) {
+                    const idx = await recallMemoryIndex(wiki, {
+                        requirementName: plan.rest || null,
+                        workspaceDir,
+                        maxEntries: configProvider.getEffective().memory?.maxIndexEntries ?? 8,
+                        kbMode,
+                    });
+                    if (idx)
+                        guidance += '\n' + idx;
+                }
+                return { kind: 'plan', guidance };
+            }
+            if (plan.kind === 'learning') {
+                const r = await handleLearningRoute(args.message, 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 === 'none')
                 return { kind: 'none' };
             // 路由1（内存）：planningBySession 命中 → 直接建链
             const pctx = planningBySession.get('session_main');
             if (pctx?.checklist && pctx.checklistRef) {
+                // 恢复补捕①：内存有清单但 workspaceDir=null（主 agent 重启后清单经 KB 恢复、异常态）→
+                // 从 exec.agent.session.header.cwd 捡回工作区，路由1 继续正常建链。已有值绝不重解析
+                // （不重复弹 ask，对齐下方 /plan: 分支注释顾虑）；解析 null（无 cwd/无通道/用户跳过）保持
+                // 现状 → 走 handleOpenspecRoute 的 workspace-unknown fail-fast（不吞错、不猜测路径）。
+                if (!pctx.workspaceDir) {
+                    const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
+                    const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
+                    if (workspaceDir) {
+                        pctx.workspaceDir = workspaceDir;
+                        planningBySession.set('session_main', pctx);
+                    }
+                }
+                // 闸2：清单落库的仓库与当前工作区不一致 → 硬拦不建链（KB 页路径带 repoSlug 维度的前提是链与工作区同源）
+                const localPath = pctx.checklist.manifest.repo.localPath;
+                if (pctx.workspaceDir && localPath !== pctx.workspaceDir) {
+                    return {
+                        kind: 'openspec', approved: false, reason: 'workspace-mismatch',
+                        error: `[workspace-mismatch] 清单 manifest.repo.localPath (${localPath}) 与当前工作区 (${pctx.workspaceDir}) 不一致。请在目标仓库工作区内重新执行 ${configProvider.getEffective().prefixRoutes.plan} 重新澄清落库后再 ${configProvider.getEffective().prefixRoutes.openspec}（不可跳过）。`,
+                    };
+                }
                 const input = { workspaceDir: pctx.workspaceDir, checklist: pctx.checklist, checklistRef: pctx.checklistRef, requirementName: pctx.requirementName };
-                const r = await handleOpenspecRoute(args.message, service, config.prefixRoutes, input, 'session_main');
-                return { kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, guidance: KANBAN_HANDOFF_RULE };
+                const r = await handleOpenspecRoute(args.message, 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 }),
+                };
             }
             // 路由2（知识库）：内存丢失（插件重启）→ 搜 KB 候选清单页供 LLM 读页重建；搜不到/不可达 → 两条路皆空
+            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession（checklist 等
+            // 字段保持 cur 或空缺省），后续 planning_checklist_save 触发 onChecklistSaved 的 { ...cur } 展开自然
+            // 带上 workspaceDir。解析失败不阻塞恢复 guidance 返回（行为同现状，只是少捕一次）。
+            if (!planningBySession.get('session_main')?.workspaceDir) {
+                const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
+                const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
+                if (workspaceDir) {
+                    const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
+                    planningBySession.set('session_main', { ...cur, workspaceDir });
+                }
+            }
             let candidates = [];
             try {
-                const pagePrefix = config.wikiVault?.pagePrefix ?? 'projects/';
-                candidates = (await wiki.search('【需求】')).map((r) => r.path).filter((p) => p.startsWith(pagePrefix)).slice(0, 5);
+                candidates = await searchChecklists(wiki, kbMode === 'local' ? LOCAL_CHECKLIST_PREFIX : (configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/'));
             }
             catch { /* KB 不可达/搜索失败 → 候选为空，走两条路皆空分支 */ }
             return {
                 kind: 'openspec', approved: false, reason: 'no-checklist',
                 recovery: candidates.length > 0 ? 'kb' : 'none',
                 checklistCandidates: candidates,
-                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(candidates) : RECOVERY_NONE_GUIDANCE,
+                guidance: candidates.length > 0 ? RECOVERY_KB_GUIDANCE(configProvider.getEffective().prefixRoutes, candidates) : RECOVERY_NONE_GUIDANCE(configProvider.getEffective().prefixRoutes),
             };
         },
     }));

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

@@ -4,6 +4,7 @@ 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';
+import type { PrefixRoutes } from '../config.js';
 /** 工具运行时上下文（dsh-tools ToolRunContext 窄型）：agent loop 注入调用者 Agent 与取消信号，
  *  planning_prefetch 经官方子代理缝启动时需透传（parent + signal）。 */
 export interface PrefetchExecContext {
@@ -19,7 +20,11 @@ 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。 */
+    kbMode?: 'remote' | 'local';
     ownerSessionId?: string;
+    /** 斜杠命令前缀路由（决策12 单一事实源），用于 description 文案派生。 */
+    prefixRoutes: PrefixRoutes;
     defaultModel?: AgentModelOptions;
     /** 清单落库成功回调（kb 与 temp 两分支各调一次），供 main-session-tools 回写 planningBySession。 */
     onChecklistSaved?(saved: {
@@ -27,6 +32,10 @@ export interface PlanningToolDeps {
         source: 'kb' | 'temp';
         checklist: PlanningChecklist;
     }): void;
+    /** memory.enabled；false 时 planning_memory_recall 返回 disabled 提示（planning_learning_save 不受影响）。 */
+    memoryEnabled?: boolean;
+    /** 闸1：/plan: 捕获的当前工作区（main-session-tools 注入）；非 null 且与清单 localPath 不一致 → 阻断落库。 */
+    resolveWorkspaceDir?: () => string | null;
 }
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export declare function buildPlanningTools(deps: PlanningToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/planning-tools.js

@@ -1,18 +1,24 @@
 // src/tools/planning-tools.ts
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 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';
+import { buildChecklistSlug, KB_PAGE_NAMESPACES_HINT, LOCAL_CHECKLIST_PREFIX, LOCAL_LEARNING_BASE, assertAllowedWikiPagePath, assertLocalKbPagePath } from '../wiki/page-path.js';
+import { validateLearning, formatLearningBody, buildRepoSlug } from '../domain/memory.js';
 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 修复）
     const pagePrefix = deps.pagePrefix ?? 'projects/';
+    const checklistPrefix = local ? LOCAL_CHECKLIST_PREFIX : pagePrefix;
     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' } },
+            parameters: { checklist: { type: 'json', required: true, description: 'Structured PlanningChecklist: {requirementName?, spec: {problem, solution, user_stories, impl_decisions, testing, out_of_scope}, manifest, clarifications, doubts: Array<{"q": string, "resolved": boolean, "answer"?: string}>, risks?}. spec.user_stories: array of plain strings — each element ONE sentence "As a <role>, I want <capability>, so that <benefit>"; NEVER objects/nested. spec.impl_decisions: array of plain strings — one decision per element; NEVER objects. clarifications: non-empty required — record every Q&A asked during this planning round; Array<{"q": string, "a": string}> with keys exactly "q"/"a" (NOT "question"/"answer"). risks (optional): Array<{"description": string, "source": string, "mitigation": string}> — register real risks/non-blocking concerns surfaced during clarification; omit or [] when none. checklist.requirementName (optional) = ' + deps.prefixRoutes.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();
@@ -22,9 +28,13 @@ export function buildPlanningTools(deps) {
                 if (errors.length > 0)
                     throw new Error('invalid planning checklist: ' + errors.join('; '));
                 const checklist = args.checklist;
+                const wsDir = deps.resolveWorkspaceDir?.() ?? null;
+                if (wsDir && checklist.manifest.repo.localPath !== wsDir) {
+                    throw new Error(`[workspace-mismatch] 清单 manifest.repo.localPath (${checklist.manifest.repo.localPath}) 与当前工作区 (${wsDir}) 不一致。请在目标仓库工作区内重新执行 ${deps.prefixRoutes.plan} 重新澄清落库（不可跳过）。`);
+                }
                 const body = formatChecklistBody(checklist);
                 // 恢复路径（内存丢失后重建）：传 restoreRef 则覆盖原页，不产生重复页
-                if (args.restoreRef && args.restoreRef.startsWith(pagePrefix)) {
+                if (args.restoreRef && args.restoreRef.startsWith(checklistPrefix)) {
                     try {
                         await deps.wiki.write(args.restoreRef, body);
                         deps.onChecklistSaved?.({ ref: args.restoreRef, source: 'kb', checklist });
@@ -36,7 +46,10 @@ export function buildPlanningTools(deps) {
                         // KB 不可达 → 落临时目录兜底（不覆盖原页），回调仍回填内存
                     }
                 }
-                const pagePath = `${CHECKLIST_PAGE_PREFIX}${buildChecklistSlug(checklist.requirementName ?? checklist.spec.problem)}-${Date.now().toString(36)}.md`;
+                const slug = buildChecklistSlug(checklist.requirementName ?? checklist.spec.problem);
+                const pagePath = local
+                    ? `${checklistPrefix}${slug}-${Date.now().toString(36)}.md`
+                    : `${pagePrefix}${buildRepoSlug(checklist.manifest.repo.localPath)}/checklists/${slug}-${Date.now().toString(36)}.md`;
                 try {
                     await deps.wiki.write(pagePath, body);
                     deps.onChecklistSaved?.({ ref: pagePath, source: 'kb', checklist });
@@ -83,6 +96,109 @@ export function buildPlanningTools(deps) {
                 return { ok: true, manifest };
             },
         }),
+        defineTool({
+            name: 'planning_learning_save',
+            description: 'Save a distilled learning (experience) to the knowledge base. Remote KB: scope=chain → projects/<repoSlug>/<chainId>/learnings/ (requirement-level); scope=project → projects/<repoSlug>/learnings/ (repo-level). repoSlug is derived from the chain workspaceDir; both scopes require chain.workspaceDir. Local KB: both scopes → wiki/synthesis/learnings/<chainId|repoSlug>/. Returns ref. Soft-fails {ok:false,reason:"kb-unreachable"} when KB is unreachable (no temp fallback).',
+            parameters: {
+                learning: { type: 'json', required: true, description: 'LearningEntry: { title (≤80 chars), lesson, evidence (mechanical chain/task id — required), tags: string[] }' },
+                scope: { type: 'string', enum: ['chain', 'project'], required: true, description: '"chain" (requirement-level) | "project" (repo-level)' },
+                chainId: { type: 'string', required: true, description: 'The chain this learning is distilled from; must exist' },
+            },
+            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_learning_save');
+                const errors = validateLearning(args.learning);
+                if (errors.length > 0)
+                    throw new Error('invalid learning: ' + errors.join('; '));
+                if (args.scope !== 'chain' && args.scope !== 'project')
+                    throw new Error('invalid scope: ' + String(args.scope));
+                if (typeof args.chainId !== 'string' || !args.chainId.trim())
+                    throw new Error('chainId required');
+                const state = await deps.service.snapshot();
+                const chain = state.chains.get(args.chainId);
+                if (!chain)
+                    throw new Error('unknown chain: ' + args.chainId);
+                const entry = args.learning;
+                let prefix;
+                if (local) {
+                    // local（D5）：scope=chain 直接挂 chainId；scope=project 挂 repoSlug（需 workspaceDir）
+                    if (args.scope === 'chain') {
+                        prefix = `${LOCAL_LEARNING_BASE}${args.chainId}/`;
+                    }
+                    else {
+                        if (!chain.workspaceDir)
+                            throw new Error('scope=project requires chain.workspaceDir (target repo) — chain has none');
+                        prefix = `${LOCAL_LEARNING_BASE}${buildRepoSlug(chain.workspaceDir)}/`;
+                    }
+                }
+                else {
+                    // remote（workspace 计划 T3）：两 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)}/`;
+                    prefix = args.scope === 'chain' ? `${wsRoot}${args.chainId}/learnings/` : `${wsRoot}learnings/`;
+                }
+                const pagePath = `${prefix}${buildChecklistSlug(entry.title)}-${Date.now().toString(36)}.md`;
+                try {
+                    await deps.wiki.write(pagePath, formatLearningBody(entry));
+                    return { ok: true, ref: pagePath, scope: args.scope };
+                }
+                catch (err) {
+                    if (isWikiError(err))
+                        return { ok: false, reason: 'kb-unreachable' };
+                    throw err;
+                }
+            },
+        }),
+        defineTool({
+            name: 'planning_memory_recall',
+            description: 'Recall KB memory for planning. path mode: read a full page truncated to 8000 chars. path mode whitelist: remote = ' + KB_PAGE_NAMESPACES_HINT + '; local = any wiki/** relative path inside the local KB root. query mode: full-text search returning top 5 {path,title,score}. Returns {ok:false,reason:"kb-unreachable"} on KB failure; {ok:false,reason:"disabled"} when memory is disabled.',
+            parameters: {
+                path: { type: 'string', description: 'KB page path to read in full (mutually exclusive with query). remote mode: projects/ namespace path; local mode: wiki/** relative path inside the local KB root.' },
+                query: { type: 'string', description: 'Full-text query; returns top 5 result paths (mutually exclusive with path)' },
+            },
+            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_memory_recall');
+                if (deps.memoryEnabled === false)
+                    return { ok: false, reason: 'disabled' };
+                const hasPath = typeof args.path === 'string' && args.path.trim().length > 0;
+                const hasQuery = typeof args.query === 'string' && args.query.trim().length > 0;
+                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 读腿全拒）
+                    if (local)
+                        assertLocalKbPagePath(args.path);
+                    else
+                        assertAllowedWikiPagePath(args.path);
+                    try {
+                        const d = await deps.wiki.read(args.path);
+                        const content = d.rawMd.length > 8000 ? d.rawMd.slice(0, 8000) + '…' : d.rawMd;
+                        return { ok: true, path: args.path, content };
+                    }
+                    catch (err) {
+                        if (isWikiError(err))
+                            return { ok: false, reason: 'kb-unreachable' };
+                        throw err;
+                    }
+                }
+                try {
+                    const results = (await deps.wiki.search(args.query)).slice(0, 5).map((r) => ({ path: r.path, title: r.title, score: r.score }));
+                    return { ok: true, results };
+                }
+                catch (err) {
+                    if (isWikiError(err))
+                        return { ok: false, reason: 'kb-unreachable' };
+                    throw err;
+                }
+            },
+        }),
     ];
 }
 function parseManifestOutput(output) {

package/lib/tools/prefetch-tools.js

@@ -1,4 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { can } from '../domain/permissions.js';
 function guard(action, caller) {
     if (!can(action, caller.actor, null))

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

@@ -1,4 +1,5 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { KanbanService } from '../domain/kanban-service.js';
 import { can } from '../domain/permissions.js';
 function guard(action, caller) {