@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/tools/ocr-review-tools.js

@@ -0,0 +1,63 @@
+// src/tools/ocr-review-tools.ts
+/** ocr_review 工具：把 ocr CLI 三子命令（preview/rule/managed）封装为 cordis 工具，DT 评审角色工具面注册。
+ * 依赖全注入可换 fake（tests），缺省用 ocr-cli 真实现。 */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { INSTALL_GUIDANCE, managedProviderReady, probeOcr, runOcr } from '../services/ocr-cli.js';
+import { buildOcrArgs, parseManagedJson, parsePreviewJson, shouldSuggestManaged, SUGGEST_MANAGED_FILES } from '../domain/ocr-review.js';
+/** 托管未配置时的降级引导：不改道执行，交还调用方决策。 */
+const MANAGED_FALLBACK_TEXT = '托管模式未配置 LLM——本次按委托模式执行：改调 sub=\'preview\' 获取评审范围后自行评审';
+const SUBS = ['preview', 'rule', 'managed'];
+/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。 */
+export function buildOcrReviewTool(deps) {
+    const runOcrFn = deps.runOcrFn ?? runOcr;
+    const probeFn = deps.probeFn ?? probeOcr;
+    const managedReadyFn = deps.managedReadyFn ?? managedProviderReady;
+    return defineTool({
+        name: 'ocr_review',
+        description: 'Review code changes via the ocr CLI. Three subcommands: '
+            + "'preview' — first step of delegated review; lists reviewable files and branch metadata "
+            + '(JSON output: mode/files/excluded/mergeBase) so you can review them yourself; '
+            + "'rule' — batch-fetch review rule groups for the file paths returned by preview; "
+            + "'managed' — full hosted review where ocr uses its own configured LLM and returns normalized findings JSON "
+            + "(requires prior wiring: ocr config provider=dsh-managed). "
+            + "Start with 'preview' to scope the review; prefer 'managed' for large change sets when the managed provider is configured.",
+        parameters: {
+            sub: { type: 'string', required: true, description: "'preview' | 'rule' | 'managed'" },
+            repo: { type: 'string', description: '仓库根绝对路径；缺省用当前工作目录' },
+            from: { type: 'string', description: 'base 分支/引用（range 模式）' },
+            to: { type: 'string', description: '目标分支/引用（range 模式，默认 HEAD）' },
+            commit: { type: 'string', description: '单次提交审查' },
+            paths: { type: 'array', items: { type: 'string' }, description: 'rule 子命令的文件路径列表' },
+        },
+        output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
+        async execute(args) {
+            const probe = await probeFn();
+            if (!probe.installed)
+                return INSTALL_GUIDANCE;
+            if (args.sub === 'managed' && !managedReadyFn())
+                return MANAGED_FALLBACK_TEXT;
+            if (!SUBS.includes(args.sub))
+                throw new Error(`ocr_review: invalid sub '${args.sub}' (expected 'preview' | 'rule' | 'managed')`);
+            if (args.sub === 'rule' && (!args.paths || args.paths.length === 0))
+                throw new Error("ocr_review: sub='rule' requires non-empty paths (file path list)");
+            if (args.sub === 'managed' && !args.commit && !args.from)
+                throw new Error("ocr_review: sub='managed' requires commit or from (base ref)");
+            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs: 600_000 });
+            if (res.error && !res.stdout)
+                throw new Error(`ocr_review: ${res.error} ${res.stderr.slice(0, 500)}`.trim());
+            if (args.sub === 'preview') {
+                const preview = parsePreviewJson(res.stdout);
+                if (shouldSuggestManaged(preview.files.length)) {
+                    return JSON.stringify({ ...preview, suggestion: `文件较多（N>${SUGGEST_MANAGED_FILES}），可在配置面板切换托管模式` });
+                }
+                return JSON.stringify(preview);
+            }
+            if (args.sub === 'rule')
+                return res.stdout.slice(0, 8000);
+            const report = parseManagedJson(res.stdout);
+            if (report.status !== 'completed' && res.error)
+                return JSON.stringify({ ...report, message: res.error });
+            return JSON.stringify(report);
+        },
+    });
+}

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

@@ -20,8 +20,10 @@ export interface PlanningToolDeps {
     spawnPrefetch?(prompt: string, workspaceDir: string, parentAgent?: Agent, signal?: AbortSignal): Promise<string>;
     tempDir(): string;
     pagePrefix?: string;
+    /** KB 双模式：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/），缺省 remote。 */
+    kbMode?: 'remote' | 'local';
     ownerSessionId?: string;
-    /** 斜杠命令前缀路由（决策12 单一事实源），用于 description 文案派生。 */
+    /** 斜杠命令前缀路由（单一事实源），用于 description 文案派生。 */
     prefixRoutes: PrefixRoutes;
     defaultModel?: AgentModelOptions;
     /** 清单落库成功回调（kb 与 temp 两分支各调一次），供 main-session-tools 回写 planningBySession。 */
@@ -32,6 +34,11 @@ export interface PlanningToolDeps {
     }): void;
     /** memory.enabled；false 时 planning_memory_recall 返回 disabled 提示（planning_learning_save 不受影响）。 */
     memoryEnabled?: boolean;
+    /** 闸1：/plan: 捕获的当前工作区（main-session-tools 注入）；非 null 且与清单 localPath 不一致 → 阻断落库。 */
+    resolveWorkspaceDir?: () => string | null;
+    /** 蜂群模式分叉：main-session-tools 注入 () => planningBySession.get('session_main')?.mode ?? null。
+     *  'swarm' 时 checklist_save 成功返回体附 nextStep 确认闸指引；前缀模式返回体不变。 */
+    flowMode?: () => 'swarm' | 'prefix' | null;
 }
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
 export declare function buildPlanningTools(deps: PlanningToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/tools/planning-tools.js

@@ -1,19 +1,26 @@
 // 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, assertAllowedWikiPagePath } 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 前缀双模式：remote → projects/<repoSlug>/checklists/（repoSlug 段在 pagePath 拼接）；
+    // local → wiki/queries/checklists/（local 时 LocalWikiClient.write 仅接受 wiki/** 相对路径，projects/ 会被 kb-rejected）
     const pagePrefix = deps.pagePrefix ?? 'projects/';
+    const checklistPrefix = local ? LOCAL_CHECKLIST_PREFIX : pagePrefix;
     const session = deps.ownerSessionId ?? 'session_main';
+    const SWARM_NEXT_STEP = '向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:\'openspec\'} 建链；模糊、岔开话题、只提修改意见 = 未确认，继续澄清。禁止未确认建链。';
+    const swarmNext = () => (deps.flowMode?.() === 'swarm' ? { nextStep: SWARM_NEXT_STEP } : {});
     return [
         defineTool({
             name: 'planning_checklist_save',
             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) = ' + 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' } },
+            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();
@@ -23,13 +30,17 @@ 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 });
-                        return { ok: true, ref: args.restoreRef, source: 'kb', repoPath: checklist.manifest.repo.localPath };
+                        return { ok: true, ref: args.restoreRef, source: 'kb', repoPath: checklist.manifest.repo.localPath, ...swarmNext() };
                     }
                     catch (err) {
                         if (!isWikiError(err))
@@ -37,11 +48,14 @@ 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 });
-                    return { ok: true, ref: pagePath, source: 'kb', repoPath: checklist.manifest.repo.localPath };
+                    return { ok: true, ref: pagePath, source: 'kb', repoPath: checklist.manifest.repo.localPath, ...swarmNext() };
                 }
                 catch (err) {
                     if (!isWikiError(err))
@@ -52,7 +66,7 @@ export function buildPlanningTools(deps) {
                     mkdirSync(deps.tempDir(), { recursive: true });
                     writeFileSync(local, body, 'utf8');
                     deps.onChecklistSaved?.({ ref: local, source: 'temp', checklist });
-                    return { ok: true, ref: local, source: 'temp', repoPath: checklist.manifest.repo.localPath };
+                    return { ok: true, ref: local, source: 'temp', repoPath: checklist.manifest.repo.localPath, ...swarmNext() };
                 }
             },
         }),
@@ -86,7 +100,7 @@ export function buildPlanningTools(deps) {
         }),
         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).',
+            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)' },
@@ -110,13 +124,23 @@ export function buildPlanningTools(deps) {
                     throw new Error('unknown chain: ' + args.chainId);
                 const entry = args.learning;
                 let prefix;
-                if (args.scope === 'chain') {
-                    prefix = `projects/${args.chainId}/learnings/`;
+                if (local) {
+                    // local：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：两 scope 均要求 chain.workspaceDir，统一挂 projects/<repoSlug>/
                     if (!chain.workspaceDir)
-                        throw new Error('scope=project requires chain.workspaceDir (target repo) — chain has none');
-                    prefix = `projects/${buildRepoSlug(chain.workspaceDir)}/learnings/`;
+                        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 {
@@ -132,9 +156,9 @@ export function buildPlanningTools(deps) {
         }),
         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.',
+            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)' },
+                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) }] },
@@ -149,7 +173,12 @@ export function buildPlanningTools(deps) {
                 if (hasPath === hasQuery)
                     throw new Error('provide exactly one of path|query');
                 if (hasPath) {
-                    assertAllowedWikiPagePath(args.path);
+                    // path 白名单按 KB 双模式分支：remote → projects/** 命名空间；local → wiki/**（
+                    // 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;

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) {

package/lib/tools/wiki-tools.js

@@ -1,6 +1,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import {} from '@deepseek-ai/dsh-util-values';
 import { can } from '../domain/permissions.js';
-import { assertAllowedWikiPagePath } from '../wiki/page-path.js';
+import { assertAllowedWikiPagePath, KB_PAGE_NAMESPACES_HINT } from '../wiki/page-path.js';
 function guard(action, caller) {
     if (!can(action, caller.actor, null))
         throw new Error('permission denied: ' + action);
@@ -34,7 +35,7 @@ export function buildWikiTools(wiki, getCaller) {
         }),
         defineTool({
             name: 'wiki_write',
-            description: 'Write a wiki-vault page under the configured pagePrefix (W only).',
+            description: 'Write a wiki-vault page under projects/<repoSlug>/ namespaces (W only). pagePath must match: ' + KB_PAGE_NAMESPACES_HINT,
             parameters: {
                 pagePath: { type: 'string', required: true },
                 content: { type: 'string', required: true },
@@ -43,11 +44,11 @@ export function buildWikiTools(wiki, getCaller) {
             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 无法跳转。
+                // 工具边界强校验——只允许 projects/<repoSlug>/ 白名单命名空间（KB_PAGE_NAMESPACES_HINT 五类，
+                // 见 page-path.ts），杜绝 LLM 自造路径/拼错层级导致 kb_url 无法跳转。
                 assertAllowedWikiPagePath(args.pagePath);
                 const out = await wiki.write(args.pagePath, args.content);
-                // Q4：工具直接拼完整 kb_url（host 用 config.wikiVault.baseUrl，杜绝 LLM 手写错域名）。
+                // 工具直接拼完整 kb_url（host 用 config.wikiVault.baseUrl，杜绝 LLM 手写错域名）。
                 // W 角色交付闸（kanban_complete w:kb）同时校验 host 前缀，双保险。
                 const base = wiki.baseUrl.replace(/\/$/, '');
                 return { path: out.path, kb_url: `${base}/#/page/${args.pagePath}` };

package/lib/wiki/kb-linkage.d.ts

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

package/lib/wiki/kb-linkage.js

@@ -49,9 +49,9 @@ export async function syncKbLinks(wiki, state, taskId) {
     if (!chain?.specCardId)
         return;
     const spec = state.specCards.get(chain.specCardId);
-    // 清单页 ref：kind:'kb' 附件；仅接受 projects/ 命名空间（临时目录兜底路径不是 KB 页，跳过）
+    // 清单页 ref：kind:'kb' 附件；接受 projects/（remote）或 wiki/（local）命名空间（临时目录兜底路径不是 KB 页，跳过）
     const checklistRef = spec?.attachments.find((a) => a.kind === 'kb')?.ref ?? null;
-    const checklistPath = checklistRef && checklistRef.startsWith('projects/') ? checklistRef : null;
+    const checklistPath = checklistRef && (checklistRef.startsWith('projects/') || checklistRef.startsWith('wiki/')) ? 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')
@@ -61,7 +61,7 @@ export async function syncKbLinks(wiki, state, taskId) {
             ? state.handoffs.get(t.id).metadata.page_path
             : null,
     }))
-        .filter((p) => p.pagePath !== null && p.pagePath.startsWith('projects/'));
+        .filter((p) => p.pagePath !== null && (p.pagePath.startsWith('projects/') || p.pagePath.startsWith('wiki/')));
     if (pages.length === 0)
         return;
     // 1) 清单页：登记全部 W2/W3 页链接

package/lib/wiki/local-kb-client.d.ts

@@ -0,0 +1,14 @@
+import { type WikiSearchResult } from './wiki-vault-client.js';
+export declare class LocalWikiClient {
+    readonly baseUrl = "";
+    readonly root: string;
+    constructor(root: string);
+    private abs;
+    write(pagePath: string, content: string): Promise<{
+        path: string;
+    }>;
+    read(pagePath: string): Promise<{
+        rawMd: string;
+    }>;
+    search(q: string): Promise<WikiSearchResult[]>;
+}

package/lib/wiki/local-kb-client.js

@@ -0,0 +1,101 @@
+// src/wiki/local-kb-client.ts
+// 本地 KB 客户端（llm-wiki 目录结构）：与 WikiVaultClient 同构的 search/read/write 面，
+// local 模式下替换注入（planning 工具 / kb-linkage / memory-recall 复用既有逻辑，零分支扩散）。
+// 排序原则：相关性优先 7 : 新鲜度 3（0.7*scoreNorm + 0.3*mtimeNorm）。
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, statSync, existsSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { WikiError } from './wiki-vault-client.js';
+import { isInsideKbRoot } from './local-kb.js';
+import { assertLocalKbPagePath } from './page-path.js';
+export class LocalWikiClient {
+    baseUrl = '';
+    root;
+    constructor(root) { this.root = root; }
+    abs(pagePath) {
+        assertLocalKbPagePath(pagePath); // 白名单单一来源（wiki/**、拒 .. 与绝对路径），勿内联重复
+        const t = resolve(this.root, pagePath);
+        if (!isInsideKbRoot(this.root, t))
+            throw new WikiError('kb-rejected', undefined, `kb-rejected: path escapes local KB root: ${pagePath}`);
+        return t;
+    }
+    async write(pagePath, content) {
+        const t = this.abs(pagePath);
+        try {
+            mkdirSync(dirname(t), { recursive: true });
+            writeFileSync(t, content, 'utf8');
+        }
+        catch (err) {
+            // 降级链依赖：fs 失败归一 kb-unreachable（planning 工具按 code 判定 temp 兜底/软失败）
+            throw new WikiError('kb-unreachable', undefined, `kb-unreachable: local KB write failed: ${String(err)}`);
+        }
+        return { path: pagePath };
+    }
+    async read(pagePath) {
+        const t = this.abs(pagePath);
+        if (!existsSync(t))
+            throw new WikiError('kb-rejected', undefined, `kb-rejected: page not found: ${pagePath}`);
+        try {
+            return { rawMd: readFileSync(t, 'utf8') };
+        }
+        catch (err) {
+            throw new WikiError('kb-unreachable', undefined, `kb-unreachable: local KB read failed: ${String(err)}`);
+        }
+    }
+    async search(q) {
+        const needle = String(q ?? '').toLowerCase().trim();
+        if (!needle)
+            return [];
+        const hits = [];
+        const walk = (dir) => {
+            let entries = [];
+            try {
+                entries = readdirSync(dir);
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                const p = join(dir, e);
+                const st = statSync(p);
+                if (st.isDirectory()) {
+                    walk(p);
+                    continue;
+                }
+                if (!e.endsWith('.md'))
+                    continue;
+                let text = '';
+                try {
+                    text = readFileSync(p, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                const lower = text.toLowerCase();
+                const n = lower.split(needle).length - 1;
+                if (n === 0)
+                    continue;
+                hits.push({
+                    path: p.slice(this.root.length + 1).split(sep).join('/'),
+                    title: text.split('\n')[0]?.replace(/^#\s*/, '').trim() || e,
+                    score: n,
+                    mtime: Math.floor(st.mtimeMs / 1000),
+                    hits: n,
+                });
+            }
+        };
+        walk(this.root);
+        if (hits.length === 0)
+            return [];
+        const maxHits = Math.max(...hits.map((h) => h.hits));
+        const times = hits.map((h) => h.mtime);
+        const minT = Math.min(...times);
+        const maxT = Math.max(...times);
+        const span = maxT - minT || 1;
+        return hits
+            .map((h) => ({
+            ...h,
+            score: Number((0.7 * (h.hits / maxHits) + 0.3 * ((h.mtime - minT) / span)).toFixed(4)),
+        }))
+            .sort((a, b) => b.score - a.score);
+    }
+}

package/lib/wiki/local-kb.d.ts

@@ -0,0 +1,6 @@
+export declare function localKbRoot(): string;
+/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)。 */
+export declare function ensureLocalKbRoot(root?: string): string;
+/** target 须为绝对路径且解析后落在 root 内（resolve 折叠重复斜杠；相对路径 fail-closed，
+ *  因为 bash/fs 里的相对目标语义属会话 cwd 而非库根，护栏不可猜测）。 */
+export declare function isInsideKbRoot(root: string, target: string): boolean;

package/lib/wiki/local-kb.js

@@ -0,0 +1,25 @@
+// src/wiki/local-kb.ts
+// 本地 KB（llm-wiki）库根工具（设计：独立 <DSH_HOME>/storages/kanban/wiki/，隔离用户个人 ~/.llm-wiki-path）。
+import { homedir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { mkdirSync } from 'node:fs';
+export function localKbRoot() {
+    const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(dshHome, 'storages', 'kanban', 'wiki');
+}
+/** 尽力创建库根（幂等）；失败由调用方告警 + block(kb-unreachable)。 */
+export function ensureLocalKbRoot(root = localKbRoot()) {
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+/** target 须为绝对路径且解析后落在 root 内（resolve 折叠重复斜杠；相对路径 fail-closed，
+ *  因为 bash/fs 里的相对目标语义属会话 cwd 而非库根，护栏不可猜测）。 */
+export function isInsideKbRoot(root, target) {
+    if (!target)
+        return false;
+    // 相对路径 fail-closed：不与 root 拼接猜测（相对目标语义属会话 cwd）
+    if (resolve(target) !== target)
+        return false;
+    const r = resolve(root).replace(/\/+$/, '');
+    return resolve(target) === r || resolve(target).startsWith(r + sep);
+}

package/lib/wiki/memory-recall.d.ts

@@ -1,16 +1,24 @@
-import type { WikiVaultClient, WikiSearchResult } from './wiki-vault-client.js';
-export declare function recallLearningIndex(wiki: WikiVaultClient, opts: {
+import type { WikiSearchResult } from './wiki-vault-client.js';
+/** KB 客户端最小检索面（WikiVaultClient / LocalWikiClient 均满足）。 */
+type WikiSearchClient = {
+    search(q: string): Promise<WikiSearchResult[]>;
+};
+export declare function recallLearningIndex(wiki: WikiSearchClient, opts: {
     requirementName: string | null;
     workspaceDir: string | null;
+    kbMode?: 'remote' | 'local';
 }): Promise<WikiSearchResult[]>;
-export declare function recallDocIndex(wiki: WikiVaultClient, opts: {
+export declare function recallDocIndex(wiki: WikiSearchClient, opts: {
     requirementName: string | null;
     workspaceDir: string | null;
+    kbMode?: 'remote' | 'local';
 }): Promise<WikiSearchResult[]>;
-export declare function recallMemoryIndex(wiki: WikiVaultClient, opts: {
+export declare function recallMemoryIndex(wiki: WikiSearchClient, opts: {
     requirementName: string | null;
     workspaceDir: string | null;
     maxEntries: number;
+    kbMode?: 'remote' | 'local';
 }): Promise<string | null>;
-/** /openspec: 恢复路径复用：搜【需求】候选清单页（projects/ 前缀 top5）。 */
-export declare function searchChecklists(wiki: WikiVaultClient, pagePrefix?: string): Promise<string[]>;
+/** /openspec: 恢复路径复用：搜【需求】候选清单页（pagePrefix 前缀 top5；local 调用方传 wiki/queries/checklists/）。 */
+export declare function searchChecklists(wiki: WikiSearchClient, pagePrefix?: string): Promise<string[]>;
+export {};

package/lib/wiki/memory-recall.js

@@ -1,4 +1,5 @@
 import { buildMemoryIndexBlock, weightedRank, buildRepoSlug } from '../domain/memory.js';
+import { isAllowedWikiPagePath } from './page-path.js';
 const TIMEOUT_MS = 6_000;
 async function withTimeout(p) {
     try {
@@ -8,26 +9,26 @@ async function withTimeout(p) {
         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;
+/** 路1 范围：remote = 当前仓库项目级 learnings（workspaceDir 空 → 无范围匹配；全局 learnings 命名空间已断代）；
+ *  local = wiki/synthesis/learnings/。 */
+function isScopedLearning(path, repoSlug, kbMode = 'remote') {
+    if (kbMode === 'local')
+        return path.startsWith('wiki/synthesis/learnings/');
+    return !!repoSlug && path.startsWith(`projects/${repoSlug}/learnings/`);
 }
 export async function recallLearningIndex(wiki, opts) {
     const repoSlug = opts.workspaceDir ? buildRepoSlug(opts.workspaceDir) : null;
+    const kbMode = opts.kbMode ?? 'remote';
     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);
+        return weightedRank(r.filter((x) => isScopedLearning(x.path, repoSlug, kbMode)), (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);
+    return r.filter((x) => isScopedLearning(x.path, repoSlug, kbMode)).sort((a, b) => b.mtime - a.mtime);
 }
 export async function recallDocIndex(wiki, opts) {
     if (!opts.requirementName)
@@ -36,20 +37,23 @@ export async function recallDocIndex(wiki, opts) {
     if (!r)
         return [];
     const repoSlug = opts.workspaceDir ? buildRepoSlug(opts.workspaceDir) : null;
+    const kbMode = opts.kbMode ?? 'remote';
     return r
-        .filter((x) => x.path.startsWith('projects/') && !isScopedLearning(x.path, repoSlug))
+        .filter((x) => kbMode === 'local'
+        ? x.path.startsWith('wiki/') && !isScopedLearning(x.path, repoSlug, 'local')
+        : isAllowedWikiPagePath(x.path) && !isScopedLearning(x.path, repoSlug, 'remote'))
         .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 }),
+        recallLearningIndex(wiki, { requirementName: opts.requirementName, workspaceDir: opts.workspaceDir, kbMode: opts.kbMode }),
+        recallDocIndex(wiki, { requirementName: opts.requirementName, workspaceDir: opts.workspaceDir, kbMode: opts.kbMode }),
     ]);
     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）。 */
+/** /openspec: 恢复路径复用：搜【需求】候选清单页（pagePrefix 前缀 top5；local 调用方传 wiki/queries/checklists/）。 */
 export async function searchChecklists(wiki, pagePrefix = 'projects/') {
     const r = await withTimeout(wiki.search('【需求】'));
     if (!r)

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

@@ -1,9 +1,15 @@
-export declare const CHECKLIST_PAGE_PREFIX = "projects/checklists/";
-export declare const LEARNINGS_PAGE_PREFIX = "projects/learnings/";
+/** 命名空间提示（报错/工具 description 文案单一来源，禁止散落硬编码）。 */
+export declare const KB_PAGE_NAMESPACES_HINT = "projects/<repoSlug>/checklists/\u3001projects/<repoSlug>/learnings/\u3001projects/<repoSlug>/ch_*/learnings/\u3001projects/<repoSlug>/ch_*/t_*.md\u3001projects/<repoSlug>/ch_*/review/\u3001projects/<repoSlug>/reviews/<topic>-<ymd>/";
 /** 从需求名（回退 problem）派生 URL 安全 slug：ASCII 化、空格/特殊字符→-、限长 40；全非 ASCII（如中文）兜底 'req'。 */
 export declare function buildChecklistSlug(name: string): string;
 export declare function isAllowedWikiPagePath(pagePath: string): boolean;
-/** 三级 learnings 路径谓词：全局 / 项目级 / 需求级。 */
+/** learnings 路径谓词：项目级 / 需求级（均在 repoSlug 下）。 */
 export declare function isLearningsPath(pagePath: string): boolean;
 /** 工具边界硬校验：不符白名单直接抛 kb-rejected（wiki_write 用）。 */
 export declare function assertAllowedWikiPagePath(pagePath: string): void;
+export declare const LOCAL_CHECKLIST_PREFIX = "wiki/queries/checklists/";
+export declare const LOCAL_LEARNING_BASE = "wiki/synthesis/learnings/";
+/** 本地模式交付白名单：KB 库根下 wiki/** 相对路径（拒绝对象路径、.. 穿越、空串）。 */
+export declare function isLocalKbPagePath(pagePath: string): boolean;
+/** 本地模式工具边界硬校验：不符直接抛 kb-rejected。 */
+export declare function assertLocalKbPagePath(pagePath: string): void;