@joekytc/dsh-swarm 0.1.0 → 0.1.2

package/lib/routes/planning-driver.js

@@ -1,13 +1,17 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import { parsePrefix } from './prefix-router.js';
-export const MATTPOCOCK_PLANNING_GUIDANCE = `
+import { DEFAULT_PREFIX_ROUTES } from '../config.js';
+/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。 */
+export function buildPlanningGuidance(routes) {
+    return `
 # 阶段 0 规划对话（v2：需求澄清前置化）
 1. 需求澄清（grill-me）：一次只问一个问题，先澄清目的、约束、成功标准；逐项拷问假设直至用户"没有任何疑问"。
 2. 仓库事实（planning_prefetch）：调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设。
 3. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点）存入 KB（KB 不可达自动兜底临时目录）。
-4. 收尾：提醒用户以 /openspec: 确认执行结束规划阶段——/openspec: 会从清单建链并自动串行执行。
+4. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。
 护栏：规划期只读仓库，禁止任何 git/源码写入；只写 KB 与临时目录。
 `;
+}
 export function validateSpecCardForApproval(card) {
     const missing = [];
     const s = card.sections;
@@ -25,10 +29,10 @@ export function validateSpecCardForApproval(card) {
         missing.push('attachments:file-prefetch');
     return missing;
 }
-export function buildPlanningContext(chainId, card, attachments) {
+export function buildPlanningContext(chainId, card, attachments, routes = DEFAULT_PREFIX_ROUTES) {
     return [
         `# 规划上下文 chain=${chainId} specCard=${card.id}`,
-        MATTPOCOCK_PLANNING_GUIDANCE,
+        buildPlanningGuidance(routes),
         `## 当前规格卡\n${JSON.stringify(card.sections, null, 2)}`,
         `## 仓库事实附件\n${attachments.map((a) => `${a.name}: ${a.ref}`).join('\n') || '(无)'}`,
     ].join('\n\n');
@@ -36,16 +40,16 @@ export function buildPlanningContext(chainId, card, attachments) {
 export async function approveIfReady(message, service, cfg, chainId, specCardId) {
     const parsed = parsePrefix(message, cfg);
     if (parsed.kind !== 'openspec')
-        return { ok: false, missing: ['prefix'], guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+        return { ok: false, missing: ['prefix'], guidance: buildPlanningGuidance(cfg) };
     const state = await service.snapshot();
     const card = state.specCards.get(specCardId);
     if (!card)
-        return { ok: false, missing: ['spec-card'], guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+        return { ok: false, missing: ['spec-card'], guidance: buildPlanningGuidance(cfg) };
     if (card.status === 'approved')
         return { ok: true, card };
     const missing = validateSpecCardForApproval(card);
     if (missing.length > 0) {
-        return { ok: false, missing, guidance: MATTPOCOCK_PLANNING_GUIDANCE };
+        return { ok: false, missing, guidance: buildPlanningGuidance(cfg) };
     }
     const approved = await service.approveSpecCard(specCardId, 'human');
     return { ok: true, card: approved };

package/lib/routes/prefix-router.d.ts

@@ -1,20 +1,18 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import type { PlanningChecklist } from '../domain/planning-checklist.js';
+import type { PrefixRoutes } from '../config.js';
 export interface PrefixRouteResult {
-    kind: 'plan' | 'openspec' | 'none';
+    kind: 'plan' | 'openspec' | 'learning' | 'none';
     chainId?: string;
     specCardId?: string;
     rest: string;
+    brief?: string;
+    guidance?: string;
+    error?: string;
 }
-export declare function parsePrefix(message: string, cfg: {
-    plan: string;
-    openspec: string;
-}): PrefixRouteResult;
+export declare function parsePrefix(message: string, cfg: PrefixRoutes): PrefixRouteResult;
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
-export declare function handlePlanRoute(message: string, _service: KanbanService, cfg: {
-    plan: string;
-    openspec: string;
-}, _ownerSessionId: string): Promise<PrefixRouteResult>;
+export declare function handlePlanRoute(message: string, _service: KanbanService, cfg: PrefixRoutes, _ownerSessionId: string): Promise<PrefixRouteResult>;
 export interface OpenspecPlanningInput {
     workspaceDir: string | null;
     checklist: PlanningChecklist;
@@ -23,7 +21,8 @@ export interface OpenspecPlanningInput {
     requirementName?: string | null;
 }
 /** v2：/openspec: 建链——从清单机械映射规格卡六段 → 挂 file-prefetch(仓库 localPath)+kb(清单页) → 批准 → executing。 */
-export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: {
-    plan: string;
-    openspec: string;
-}, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;
+export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: PrefixRoutes, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;
+/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+export declare function buildLearningGuidance(routes: PrefixRoutes): string;
+/** v2：/learning 零副作用——不建链建卡，仅机械提取证据包供主 agent 蒸馏。歧义返回候选列表，链不存在返回错误文本（不 throw）。 */
+export declare function handleLearningRoute(message: string, service: KanbanService, cfg: PrefixRoutes, _ownerSessionId: string): Promise<PrefixRouteResult>;

package/lib/routes/prefix-router.js

@@ -1,10 +1,13 @@
 import { KanbanService, buildChainTitle } from '../domain/kanban-service.js';
+import { buildLearningBrief, resolveLearningChainId } from '../domain/memory.js';
 export function parsePrefix(message, cfg) {
     const trimmed = message.trim();
     if (trimmed.startsWith(cfg.plan))
         return { kind: 'plan', rest: trimmed.slice(cfg.plan.length).trim() };
     if (trimmed.startsWith(cfg.openspec))
         return { kind: 'openspec', rest: trimmed.slice(cfg.openspec.length).trim() };
+    if (trimmed.startsWith(cfg.learning))
+        return { kind: 'learning', rest: trimmed.slice(cfg.learning.length).trim() };
     return { kind: 'none', rest: trimmed };
 }
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
@@ -26,3 +29,30 @@ export async function handleOpenspecRoute(message, service, cfg, planning, owner
     await service.approveSpecCard(card.id, 'human');
     return { kind: 'openspec', chainId: chain.id, specCardId: card.id, rest: parsed.rest };
 }
+/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+export function buildLearningGuidance(routes) {
+    return [
+        '## 经验蒸馏指令（' + routes.learning + '）',
+        '消化上方「链上下文 + 机械信号证据包」，蒸馏 1-3 条可复用经验（返工根因 / 阻塞原因 / 审计教训）。',
+        '每条约成 LearningEntry（title 一句话≤80 字符；lesson 教训；evidence 必须填本链 chain id 作机械证据；tags 自由标签）。',
+        '调 planning_learning_save：scope=chain 存需求级 projects/<chainId>/learnings/；仓库通用经验用 scope=project（自动归入目标仓库项目级）。',
+        '无值得沉淀的经验时，明确回复「无新经验」，不要硬凑。',
+    ].join('\n');
+}
+/** v2：/learning 零副作用——不建链建卡，仅机械提取证据包供主 agent 蒸馏。歧义返回候选列表，链不存在返回错误文本（不 throw）。 */
+export async function handleLearningRoute(message, service, cfg, _ownerSessionId) {
+    const parsed = parsePrefix(message, cfg);
+    if (parsed.kind !== 'learning')
+        return parsed;
+    const state = await service.snapshot();
+    const resolved = resolveLearningChainId(state, parsed.rest);
+    if (resolved === null) {
+        return { kind: 'learning', rest: parsed.rest, error: 'chain-not-found', guidance: `未找到可蒸馏经验的链。可用 ${cfg.learning} <chainId> 指定，或先经 ${cfg.plan}${cfg.openspec} 建立链路。` };
+    }
+    if ('candidates' in resolved) {
+        const list = resolved.candidates.map((c) => `- ${c.chainId} ${c.title}`).join('\n');
+        return { kind: 'learning', rest: parsed.rest, error: 'chain-ambiguous', guidance: `匹配到多条链，请用 ${cfg.learning} <chainId> 精确指定：\n${list}` };
+    }
+    const brief = buildLearningBrief(state, resolved.chainId);
+    return { kind: 'learning', chainId: resolved.chainId, rest: parsed.rest, brief, guidance: buildLearningGuidance(cfg) };
+}

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

@@ -4,23 +4,25 @@ 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';
 export const planningBySession = new Map();
-const KANBAN_HANDOFF_RULE = `
+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 入库。
 `;
 // 清单获取只有两条路：内存（路由1）> KB 候选页（路由2，LLM 读页重建）。禁止编造其他原因
 // （"先重试 / 查服务进程是否重启"类诊断是噪声：内存丢失唯一成因是插件重启，重启后按两条路恢复即可）。
-const RECOVERY_KB_GUIDANCE = (candidates) => `
+const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
 插件内存中的需求澄清清单已丢失（插件进程重启所致，属预期情况，按两条获取路由恢复即可，勿猜测其他原因）。
 知识库中检索到候选清单页：
 ${candidates.map((c) => '- ' + c).join('\n')}
@@ -28,15 +30,15 @@ ${candidates.map((c) => '- ' + c).join('\n')}
 1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
 2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts，requirementName 取页标题中【需求】后的名称）；
 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"）。 */
@@ -118,6 +120,8 @@ export function registerMainSessionTools(ctx, config) {
         spawnPrefetch: buildSpawnPrefetch(ctx),
         tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
         pagePrefix: config.wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
+        prefixRoutes: config.prefixRoutes,
+        memoryEnabled: config.memory?.enabled ?? true,
         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 };
@@ -126,9 +130,10 @@ export function registerMainSessionTools(ctx, config) {
     }))
         registry.register(tool);
     // kanban_route：/plan: 捕获规划上下文；/openspec: 用清单建链
+    const { plan, openspec, learning } = config.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) {
@@ -140,7 +145,23 @@ export function registerMainSessionTools(ctx, config) {
                 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(config.prefixRoutes) + KANBAN_HANDOFF_RULE(config.prefixRoutes);
+                if ((config.memory?.enabled ?? true) && workspaceDir) {
+                    const idx = await recallMemoryIndex(wiki, {
+                        requirementName: plan.rest || null,
+                        workspaceDir,
+                        maxEntries: config.memory?.maxIndexEntries ?? 8,
+                    });
+                    if (idx)
+                        guidance += '\n' + idx;
+                }
+                return { kind: 'plan', guidance };
+            }
+            if (plan.kind === 'learning') {
+                const r = await handleLearningRoute(args.message, service, config.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' };
@@ -149,20 +170,19 @@ export function registerMainSessionTools(ctx, config) {
             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 };
+                return { kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, guidance: KANBAN_HANDOFF_RULE(config.prefixRoutes) };
             }
             // 路由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);
+                candidates = await searchChecklists(wiki, config.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(config.prefixRoutes, candidates) : RECOVERY_NONE_GUIDANCE(config.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 {
@@ -20,6 +21,8 @@ export interface PlanningToolDeps {
     tempDir(): string;
     pagePrefix?: string;
     ownerSessionId?: string;
+    /** 斜杠命令前缀路由（决策12 单一事实源），用于 description 文案派生。 */
+    prefixRoutes: PrefixRoutes;
     defaultModel?: AgentModelOptions;
     /** 清单落库成功回调（kb 与 temp 两分支各调一次），供 main-session-tools 回写 planningBySession。 */
     onChecklistSaved?(saved: {
@@ -27,6 +30,8 @@ export interface PlanningToolDeps {
         source: 'kb' | 'temp';
         checklist: PlanningChecklist;
     }): void;
+    /** memory.enabled；false 时 planning_memory_recall 返回 disabled 提示（planning_learning_save 不受影响）。 */
+    memoryEnabled?: boolean;
 }
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export declare function buildPlanningTools(deps: PlanningToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/planning-tools.js

@@ -2,7 +2,8 @@
 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';
+import { buildChecklistSlug, CHECKLIST_PAGE_PREFIX, assertAllowedWikiPagePath } 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) {
@@ -12,7 +13,7 @@ export function buildPlanningTools(deps) {
         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: spec six sections + manifest(repo.files) + clarifications + doubts. 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();
@@ -83,6 +84,94 @@ export function buildPlanningTools(deps) {
                 return { ok: true, manifest };
             },
         }),
+        defineTool({
+            name: 'planning_learning_save',
+            description: 'Save a distilled learning (experience) to the knowledge base. scope=chain → projects/<chainId>/learnings/ (requirement-level); scope=project → projects/<repoSlug>/learnings/ (repo-level, repoSlug derived from the chain workspaceDir). 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 (args.scope === 'chain') {
+                    prefix = `projects/${args.chainId}/learnings/`;
+                }
+                else {
+                    if (!chain.workspaceDir)
+                        throw new Error('scope=project requires chain.workspaceDir (target repo) — chain has none');
+                    prefix = `projects/${buildRepoSlug(chain.workspaceDir)}/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 (whitelist: projects/checklists/, projects/learnings/, projects/<slug>/learnings/, projects/ch_*/learnings/, projects/ch_*/t_*.md, projects/ch_*/review/) truncated to 8000 chars. 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)' },
+                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) {
+                    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/wiki/memory-recall.d.ts

@@ -0,0 +1,16 @@
+import type { WikiVaultClient, WikiSearchResult } from './wiki-vault-client.js';
+export declare function recallLearningIndex(wiki: WikiVaultClient, opts: {
+    requirementName: string | null;
+    workspaceDir: string | null;
+}): Promise<WikiSearchResult[]>;
+export declare function recallDocIndex(wiki: WikiVaultClient, opts: {
+    requirementName: string | null;
+    workspaceDir: string | null;
+}): Promise<WikiSearchResult[]>;
+export declare function recallMemoryIndex(wiki: WikiVaultClient, opts: {
+    requirementName: string | null;
+    workspaceDir: string | null;
+    maxEntries: number;
+}): Promise<string | null>;
+/** /openspec: 恢复路径复用：搜【需求】候选清单页（projects/ 前缀 top5）。 */
+export declare function searchChecklists(wiki: WikiVaultClient, pagePrefix?: string): Promise<string[]>;

package/lib/wiki/memory-recall.js

@@ -0,0 +1,58 @@
+import { buildMemoryIndexBlock, weightedRank, buildRepoSlug } from '../domain/memory.js';
+const TIMEOUT_MS = 6_000;
+async function withTimeout(p) {
+    try {
+        return await Promise.race([p, new Promise((resolve) => setTimeout(() => resolve(null), TIMEOUT_MS))]);
+    }
+    catch {
+        return null;
+    }
+}
+/** 路1 范围：全局 + 当前仓库项目级 learnings（workspaceDir null → 仅全局）。 */
+function isScopedLearning(path, repoSlug) {
+    if (path.startsWith('projects/learnings/'))
+        return true;
+    if (repoSlug && path.startsWith(`projects/${repoSlug}/learnings/`))
+        return true;
+    return false;
+}
+export async function recallLearningIndex(wiki, opts) {
+    const repoSlug = opts.workspaceDir ? buildRepoSlug(opts.workspaceDir) : null;
+    if (opts.requirementName) {
+        const r = await withTimeout(wiki.search(opts.requirementName));
+        if (!r)
+            return [];
+        return weightedRank(r.filter((x) => isScopedLearning(x.path, repoSlug)), (x) => x.score, (x) => x.mtime);
+    }
+    const r = await withTimeout(wiki.search('【Learning】'));
+    if (!r)
+        return [];
+    return r.filter((x) => isScopedLearning(x.path, repoSlug)).sort((a, b) => b.mtime - a.mtime);
+}
+export async function recallDocIndex(wiki, opts) {
+    if (!opts.requirementName)
+        return [];
+    const r = await withTimeout(wiki.search(opts.requirementName));
+    if (!r)
+        return [];
+    const repoSlug = opts.workspaceDir ? buildRepoSlug(opts.workspaceDir) : null;
+    return r
+        .filter((x) => x.path.startsWith('projects/') && !isScopedLearning(x.path, repoSlug))
+        .sort((a, b) => b.score - a.score);
+}
+export async function recallMemoryIndex(wiki, opts) {
+    const [learnings, docs] = await Promise.all([
+        recallLearningIndex(wiki, { requirementName: opts.requirementName, workspaceDir: opts.workspaceDir }),
+        recallDocIndex(wiki, { requirementName: opts.requirementName, workspaceDir: opts.workspaceDir }),
+    ]);
+    const learningEntries = learnings.slice(0, Math.ceil(opts.maxEntries / 2)).map((r) => ({ kind: 'learning', title: r.title, path: r.path }));
+    const docEntries = docs.slice(0, opts.maxEntries - learningEntries.length).map((r) => ({ kind: 'doc', title: r.title, path: r.path }));
+    return buildMemoryIndexBlock([...learningEntries, ...docEntries]);
+}
+/** /openspec: 恢复路径复用：搜【需求】候选清单页（projects/ 前缀 top5）。 */
+export async function searchChecklists(wiki, pagePrefix = 'projects/') {
+    const r = await withTimeout(wiki.search('【需求】'));
+    if (!r)
+        return [];
+    return r.map((x) => x.path).filter((p) => p.startsWith(pagePrefix)).slice(0, 5);
+}

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

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

package/lib/wiki/page-path.js

@@ -5,8 +5,9 @@
 //   DT 评审页    projects/ch_<id>/review/<name>.md      （DT wiki_write，工具边界强制）
 import { WikiError } from './wiki-vault-client.js';
 export const CHECKLIST_PAGE_PREFIX = 'projects/checklists/';
-/** 白名单：wiki_write 只允许写这三类命名空间（杜绝 LLM 自造路径/拼错层级）。id 段宽松匹配（兼容真实 nid 两段式 ch_1_xxx 与测试单段 ch_1）。 */
-const KB_PAGE_PATH_RE = /^projects\/(?:checklists\/|ch_[0-9a-z_]+\/(?:t_[0-9a-z_]+\.md|review\/))/;
+export const LEARNINGS_PAGE_PREFIX = 'projects/learnings/';
+/** 白名单：checklists + 三级 learnings + 链命名空间（杜绝 LLM 自造路径）。 */
+const KB_PAGE_PATH_RE = /^projects\/(?:checklists\/|learnings\/|[a-z0-9-]+\/learnings\/|ch_[0-9a-z_]+\/(?:t_[0-9a-z_]+\.md|review\/|learnings\/))/;
 /** 从需求名（回退 problem）派生 URL 安全 slug：ASCII 化、空格/特殊字符→-、限长 40；全非 ASCII（如中文）兜底 'req'。 */
 export function buildChecklistSlug(name) {
     const slug = name
@@ -20,9 +21,13 @@ export function buildChecklistSlug(name) {
 export function isAllowedWikiPagePath(pagePath) {
     return KB_PAGE_PATH_RE.test(pagePath);
 }
+/** 三级 learnings 路径谓词：全局 / 项目级 / 需求级。 */
+export function isLearningsPath(pagePath) {
+    return /^projects\/(?:learnings\/|[a-z0-9-]+\/learnings\/|ch_[0-9a-z_]+\/learnings\/)/.test(pagePath);
+}
 /** 工具边界硬校验：不符白名单直接抛 kb-rejected（wiki_write 用）。 */
 export function assertAllowedWikiPagePath(pagePath) {
     if (!isAllowedWikiPagePath(pagePath)) {
-        throw new WikiError('kb-rejected', undefined, `page path outside allowed namespaces (projects/checklists/, projects/ch_*/t_*.md, projects/ch_*/review/): ${pagePath}`);
+        throw new WikiError('kb-rejected', undefined, `page path outside allowed namespaces (projects/checklists/, projects/learnings/, projects/<slug>/learnings/, projects/ch_*/learnings/, projects/ch_*/t_*.md, projects/ch_*/review/): ${pagePath}`);
     }
 }

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

@@ -7,6 +7,7 @@ export interface WikiSearchResult {
     path: string;
     title: string;
     score: number;
+    mtime: number;
 }
 export declare class WikiVaultClient {
     private readonly cfg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A governed swarm of six specialist DSH agents (orchestrator, planner, knowledge-base bridge, developer and two reviewers) that turns a requirement into a strict phase pipeline with machine-verified delivery evidence, review-gated merges, a full audit-log event stream and a live kanban tab; design inspired by the Hermes Agent kanban",
   "license": "MIT",
   "author": "joekytc",

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

@@ -59,7 +59,7 @@
 
 # run_code 供验证程序（跑测试/构建/typecheck 编排）；ToolGuard 拦其对源码的写
 - id: tool-presentation
-  name: '@deepseek-ai/dsh-tool-presentation'
+  name: '@deepseek-ai/dsh-agent-tool-presentation'
   config:
     mode: both