@joekytc/dsh-swarm 0.3.8 → 0.3.10

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

@@ -1,6 +1,8 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import {} from '@deepseek-ai/dsh-util-values';
-import { tmpdir } from 'node:os';
+import { readdirSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { KanbanProvider } from '../services/kanban-provider.js';
 import { buildKanbanTools } from './kanban-tools.js';
 import { buildSpecCardTools } from './spec-card-tools.js';
@@ -12,6 +14,7 @@ import { buildPlanningGuidance } from '../routes/planning-driver.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from '../dispatcher/workspace-attach.js';
 import { sessionPresetOf } from '../dispatcher/session-preset.js';
 import { PREFETCH_MANIFEST_SCHEMA } from '../domain/prefetch-manifest.js';
+import { extractChecklistJson } from '../domain/planning-checklist.js';
 import { WikiVaultClient } from '../wiki/wiki-vault-client.js';
 import { LocalWikiClient } from '../wiki/local-kb-client.js';
 import { ensureLocalKbRoot } from '../wiki/local-kb.js';
@@ -19,9 +22,9 @@ import { LOCAL_CHECKLIST_PREFIX } from '../wiki/page-path.js';
 export const planningBySession = new Map();
 export const KANBAN_HANDOFF_RULE = (routes, opts) => {
     const confirmLine = opts?.swarm
-        ? `- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单。
-- 确认闸：清单落库后向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链；模糊、岔开话题、只提修改意见 = 未确认，继续澄清。禁止未确认建链。`
-        : `- 澄清期：调 planning_prefetch（只读子代理）采集仓库事实 → 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单 → 提醒用户 ${routes.openspec} 确认。`;
+        ? `- 澄清期：用户给了 PRD/需求文档链接 → 先 planning_prd_collect 逐条采集（blocked 即停，按返回 guidance 转告用户解决后重采，禁猜禁跳）→ planning_prefetch（只读子代理）采集仓库事实 → （绿地：目标目录无 .git → 清单声明 greenfield:true）→ 逐问用户收敛 → planning_checklist_save 存需求澄清清单（每条问答完整决策正文，禁缩写），每条决策可追溯（问答/源码/文档位置至少其一，冲突值标【已调整】/【已确认】）。
+- 确认闸：清单落库后向用户征求确认；仅当用户回复包含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链；模糊、岔开话题、只提修改意见 = 未确认，继续澄清。禁止未确认建链。`
+        : `- 澄清期：用户给了 PRD/需求文档链接 → 先 planning_prd_collect 逐条采集（blocked 即停，按返回 guidance 转告用户解决后重采，禁猜禁跳）→ planning_prefetch（只读子代理）采集仓库事实 → （绿地：目标目录无 .git → 清单声明 greenfield:true）→ 逐问用户收敛 → 调 planning_checklist_save 存需求澄清清单（每条问答完整决策正文，禁缩写），每条决策可追溯（问答/源码/文档位置至少其一，冲突值标【已调整】/【已确认】）→ 提醒用户 ${routes.openspec} 确认。`;
     const nextLine = opts?.swarm
         ? `- 用户确认后你调 kanban_route{intent:'openspec'}；链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。`
         : `- ${routes.openspec} 后链路进入 executing，V 自动串行建卡 p→(pt)→w2→d→dt→w3；你不要自己执行。`;
@@ -61,21 +64,25 @@ const RECOVERY_KB_GUIDANCE = (routes, candidates) => `
 ${candidates.map((c) => '- ' + c).join('\n')}
 恢复步骤（严格顺序）：
 1. 读取候选页内容，对照当前需求判定哪一页是本次需求的需求澄清清单（页首行标题为「# 【需求】<需求名>」）；
-2. 消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；
-3. 调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页）；
-4. 回存成功后提示用户重新发送 ${routes.openspec} 确认。
+2. 若页尾含 <!-- dsh-swarm:checklist-json ... --> 机读段：不要手动重建、不要调 planning_checklist_save——直接提示用户重新发送 ${routes.openspec}（路由会自动机读恢复并当场建链，LLM 零参与）；
+3. 仅 legacy 页（无机读段）才执行本步：消化该页内容，重建结构化 PlanningChecklist（spec 六段 + manifest + clarifications + doubts + risks（风险点，若有），requirementName 取页标题中【需求】后的名称；恢复重建时 clarifications 允许登记单条无澄清说明，如 {"q": "本轮无澄清（恢复重建）", "a": "<来源页或原因>"}，其余场景 clarifications 禁止为空）；重建时旧页若无来源信息，sources 录 [{type:'其他', url:'', note:'恢复重建，原页无来源'}]；无 PRD 采集记录则 prdCollection 录 []；
+4. legacy 页重建后调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页），成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
 `;
 const RECOVERY_NONE_GUIDANCE = (routes) => `
 两条获取路由均无本需求的需求澄清清单（内存为空，知识库亦无匹配页）。
 处理步骤（严格顺序）：
 1. 消化当前对话上下文，判断需求澄清（grill-me 逐问收敛 + planning_prefetch 仓库事实）是否已完成但漏了保存动作；
-2. 若已完成澄清——立即调 planning_checklist_save 保存清单；若尚未完成——先完成澄清（缺仓库事实则先 planning_prefetch），再保存；
+2. 若已完成澄清——立即调 planning_checklist_save 保存清单；若尚未完成——先完成澄清（缺仓库事实则先 planning_prefetch），再保存；重建时旧页若无来源信息，sources 录 [{type:'其他', url:'', note:'恢复重建，原页无来源'}]；无 PRD 采集记录则 prdCollection 录 []；
 3. 保存成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：在清单落库前建链建卡；编造"先重试 / 查服务进程是否重启"之类与清单无关的诊断。
 `;
 /** 预取子代理禁用的写能力工具（官方全局工具名；deny = 从 prompt 消失 + 拒绝执行，"one visibility"）。 */
 const PREFETCH_DENIED_TOOLS = ['bash', 'edit', 'write'];
+/** 采集缝白名单：采集类工具放行 + skill 工具放行（子代理经 skill 工具加载 ~/.agents/skills/ 枚举出的采集技能正文——
+ *  技能名按目录动态枚举注入 prompt，配合放行 skill 工具，枚举出的技能才能加载其实现正文）。
+ *  写盘边界：子代理只许写临时目录，产物入 KB 由 planning_prd_collect 工具侧收口。 */
+const PRD_COLLECT_ALLOWED_TOOLS = ['web_fetch', 'read', 'glob', 'grep', 'skill'];
 export function buildSpawnPrefetch(ctx) {
     const subagents = ctx.get('subagents');
     if (!subagents?.start)
@@ -119,6 +126,58 @@ export function buildSpawnPrefetch(ctx) {
         }
     };
 }
+export function buildSpawnPrdCollect(ctx, listSkills = defaultSkillNames) {
+    const subagents = ctx.get('subagents');
+    if (!subagents?.start)
+        return undefined;
+    return async (prompt, workspaceDir, parentAgent, signal) => {
+        if (!parentAgent)
+            throw new Error('planning_prd_collect: missing parent agent — 工具运行时未注入 exec.agent');
+        // 无规划会话工作区 = fail-loud：拒绝回退 process.cwd()（会把子会话归组到插件进程目录，污染工作区边界）
+        if (!workspaceDir)
+            throw new Error('planning_prd_collect: missing workspace dir — 无活跃规划会话工作区，拒绝回退 process.cwd()');
+        const cwd = workspaceDir;
+        const skills = listSkills();
+        const fullPrompt = prompt + '\n\n可用采集技能（~/.agents/skills/ 实测枚举）：' + (skills.length > 0 ? skills.join('、') : '（无——采集能力不足，如实报 blocked:缺技能）');
+        let run;
+        try {
+            run = await subagents.start('spawn', {
+                label: 'prd-collect',
+                prompt: [{ type: 'text', text: fullPrompt }],
+                parent: parentAgent,
+                signal: signal ?? new AbortController().signal,
+                maxDepth: 1,
+                toolFilter: { allow: [...PRD_COLLECT_ALLOWED_TOOLS] },
+            });
+        }
+        catch (err) {
+            throw new Error('planning_prd_collect: subagent start failed: ' + String(err));
+        }
+        try {
+            await attachSessionToWorkspace(ctx, run.id, cwd, 'prd-collect');
+            const result = await run.result;
+            if (result.stopReason !== 'completed') {
+                throw new Error(`planning_prd_collect: subagent ended with stopReason=${result.stopReason}${result.error ? ' — ' + result.error : ''}`);
+            }
+            if (result.structured !== undefined)
+                return JSON.stringify(result.structured);
+            return (result.output ?? []).map((b) => b.text ?? '').join('');
+        }
+        finally {
+            await run.dispose().catch(() => undefined);
+        }
+    };
+}
+/** ~/.agents/skills/ 目录名枚举（技能发现与 DSH 同源）；读失败返回空数组（降级为「无技能」引导）。 */
+function defaultSkillNames() {
+    try {
+        return readdirSync(join(homedir(), '.agents', 'skills'), { withFileTypes: true })
+            .filter((d) => d.isDirectory()).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+}
 /** 自由投递 guidance：三步教学（实查基准 → 生成正文 → sms_send 投递）+ 红线分界。 */
 function buildFreeSendGuidance(routes, query, dm) {
     return [
@@ -165,11 +224,12 @@ export function registerMainSessionTools(ctx, configProvider) {
         if (tool.name === 'spec_card_view')
             registry.register(tool);
     }
-    // planning 工具（清单落库 + 只读预取）——spawnPrefetch 由模块级 buildSpawnPrefetch 提供（可单测）
+    // planning 工具（清单落库 + 只读预取 + PRD 采集）——spawnPrefetch/spawnPrdCollect 由模块级 builder 提供（可单测）
     for (const tool of buildPlanningTools({
         service, wiki: wiki, // local 模式为 LocalWikiClient（write/read/search 同面，双模式客户端）
         getCaller: caller,
         spawnPrefetch: buildSpawnPrefetch(ctx),
+        spawnPrdCollect: buildSpawnPrdCollect(ctx),
         tempDir: () => `${tmpdir()}/dsh-swarm-checklists`, // KB 不可达时的临时兜底，放系统临时目录（不落插件源码/核心存储目录）
         pagePrefix: configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/', // 生成的清单页路径保持在该客户端配置的命名空间内（避免 kb-rejected）
         kbMode: configProvider.mode, // 双模式：local 时 checklist/learning 落本地库命名空间（wiki/queries/checklists/、wiki/synthesis/learnings/）
@@ -270,13 +330,9 @@ export function registerMainSessionTools(ctx, configProvider) {
             }
             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（不吞错、不猜测路径）。
+            // 建链共用段（2026-09-21 从路由1 提取）：恢复补捕① + workspace-mismatch 闸2 + handleOpenspecRoute。
+            // 路由1（内存命中）与路由2（KB 机读恢复命中）同走此函数，建链语义单一事实源。
+            const openChainFromContext = async (pctx) => {
                 if (!pctx.workspaceDir) {
                     const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
                     const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
@@ -303,11 +359,18 @@ export function registerMainSessionTools(ctx, configProvider) {
                     kind: 'openspec', chainId: r.chainId, specCardId: r.specCardId, approved: true, firstCard: r.firstCard,
                     guidance: KANBAN_HANDOFF_RULE(configProvider.getEffective().prefixRoutes, { swarm: planningBySession.get('session_main')?.mode === 'swarm' }) + '\n\n' + buildOpenspecNarrationRule({ chainId: r.chainId, specCardId: r.specCardId, firstCard: r.firstCard }),
                 };
+            };
+            // 路由1（内存）：planningBySession 命中 → 直接建链
+            const pctx = planningBySession.get('session_main');
+            if (pctx?.checklist && pctx.checklistRef) {
+                // 恢复补捕①：内存有清单但 workspaceDir=null（主 agent 重启后清单经 KB 恢复、异常态）→
+                // 从 exec.agent.session.header.cwd 捡回工作区（已有值绝不重解析，不重复弹 ask）。
+                return await openChainFromContext({ ...pctx, checklist: pctx.checklist, checklistRef: pctx.checklistRef });
             }
-            // 路由2（知识库）：内存丢失（插件重启）→ 搜 KB 候选清单页供 LLM 读页重建；搜不到/不可达 → 两条路皆空
-            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession（checklist 等
-            // 字段保持 cur 或空缺省），后续 planning_checklist_save 触发 onChecklistSaved 的 { ...cur } 展开自然
-            // 带上 workspaceDir。解析失败不阻塞恢复 guidance 返回（行为同现状，只是少捕一次）。
+            // 路由2（知识库）：内存丢失（插件重启）→ 优先机读恢复（2026-09-21 矫正）：候选页尾含无损 JSON 段
+            // → extractChecklistJson 提取 → 灌内存 → 当场建链（LLM 零参与，杜绝读页重建的失真/双重编码/回存绕路）；
+            // 无段/损坏/校验不过（legacy 页）→ 回退既有 LLM 读页重建+回存流程。搜不到/不可达 → 两条路皆空。
+            // 恢复补捕②：无内存条目或工作区未捕获 → 从 header.cwd 捡回，写入 planningBySession。
             if (!planningBySession.get('session_main')?.workspaceDir) {
                 const headerCwd = exec?.agent?.session?.header?.cwd ?? null;
                 const workspaceDir = await resolveOrCreateWorkspace(ctx, headerCwd, '主 agent 会话（/openspec: 恢复）');
@@ -321,6 +384,24 @@ export function registerMainSessionTools(ctx, configProvider) {
                 candidates = await searchChecklists(wiki, kbMode === 'local' ? LOCAL_CHECKLIST_PREFIX : (configProvider.getEffective().wikiVault?.pagePrefix ?? 'projects/'));
             }
             catch { /* KB 不可达/搜索失败 → 候选为空，走两条路皆空分支 */ }
+            let machineRestored = null;
+            for (const cpath of candidates) {
+                try {
+                    const d = await wiki.read(cpath);
+                    const c = extractChecklistJson(d.rawMd);
+                    if (c) {
+                        machineRestored = { path: cpath, checklist: c };
+                        break;
+                    }
+                }
+                catch { /* 单页读取失败 → 试下一候选 */ }
+            }
+            if (machineRestored) {
+                const cur = planningBySession.get('session_main') ?? { workspaceDir: null, sessionId: 'session_main', checklist: null, checklistRef: null, checklistSource: null, requirementName: null };
+                const rpctx = { ...cur, checklist: machineRestored.checklist, checklistRef: machineRestored.path, checklistSource: 'kb', requirementName: machineRestored.checklist.requirementName ?? null };
+                planningBySession.set('session_main', rpctx);
+                return await openChainFromContext(rpctx);
+            }
             return {
                 kind: 'openspec', approved: false, reason: 'no-checklist',
                 recovery: candidates.length > 0 ? 'kb' : 'none',

package/lib/tools/ocr-review-tools.d.ts

@@ -2,7 +2,9 @@
  * 依赖全注入可换 fake（tests），缺省用 ocr-cli 真实现。 */
 import { type ToolDefinition as ToolDef } from '@deepseek-ai/dsh-tools';
 import { managedProviderReady, probeOcr, runOcr } from '../services/ocr-cli.js';
-/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。 */
+/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。
+ *  deps.cwd = 会话工作目录兜底注入（测试/特殊宿主）；生产不注入——目标仓库只来自
+ *  repo 参数或 exec.agent.session.header.cwd，绝不隐式用插件进程 cwd（非仓库）。 */
 export declare function buildOcrReviewTool(deps: {
     runOcrFn?: typeof runOcr;
     probeFn?: typeof probeOcr;

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

@@ -5,9 +5,21 @@ 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 MANAGED_FALLBACK_TEXT = '托管模式未配置 LLM——本次按委托模式执行：改调 sub=\'preview\' 获取评审范围后自行评审'
+    + '（如需启用托管：GUI 配置面板「评审引擎（ocr）」卡选好提供方/模型后点「应用到 ocr」）';
 const SUBS = ['preview', 'rule', 'managed'];
-/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。 */
+/** 会话工作目录读取（官方链路 ToolRunContext.agent → Agent.session → Session.header.cwd，
+ *  dsh-session SessionHeader.cwd = "Absolute working directory the session was created in"）。
+ *  主会话/独立评审 = 用户打开的工作区（仓库目录）；链上角色会话 = agent-runner 创建时的
+ *  meta.cwd（chain.workspaceDir）。鸭子类型读取，取不到返回 undefined。 */
+function sessionCwdOf(agent) {
+    const a = agent;
+    const cwd = a?.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd.trim() ? cwd.trim() : undefined;
+}
+/** 构造 ocr_review 工具定义（defineTool 返回形态，与 kanban-tools 一致）。
+ *  deps.cwd = 会话工作目录兜底注入（测试/特殊宿主）；生产不注入——目标仓库只来自
+ *  repo 参数或 exec.agent.session.header.cwd，绝不隐式用插件进程 cwd（非仓库）。 */
 export function buildOcrReviewTool(deps) {
     const runOcrFn = deps.runOcrFn ?? runOcr;
     const probeFn = deps.probeFn ?? probeOcr;
@@ -23,7 +35,7 @@ export function buildOcrReviewTool(deps) {
             + "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: '仓库根绝对路径；缺省用当前工作目录' },
+            repo: { type: 'string', description: '目标仓库根绝对路径；缺省用当前会话工作目录（会话创建时的 cwd）。评审非当前会话目录的仓库（如临时 clone）时必须显式传' },
             from: { type: 'string', description: 'base 分支/引用（range 模式）' },
             to: { type: 'string', description: '目标分支/引用（range 模式，默认 HEAD）' },
             commit: { type: 'string', description: '单次提交审查' },
@@ -31,7 +43,7 @@ export function buildOcrReviewTool(deps) {
             background: { type: 'string', description: '业务上下文，托管评审时提升评审质量' },
         },
         output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String(v) }] },
-        async execute(args) {
+        async execute(args, exec) {
             const probe = await probeFn();
             if (!probe.installed)
                 return INSTALL_GUIDANCE;
@@ -43,9 +55,15 @@ export function buildOcrReviewTool(deps) {
                 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)");
+            // 目标仓库：显式 repo（跨仓库评审，如临时 clone）优先，其次当前会话工作目录
+            // （exec.agent.session.header.cwd）；两处都没有则 fail-loud——绝不隐式兜底进程 cwd
+            // （插件进程 cwd 实测 ~/.codebuddy，非 git 仓库，ocr 必报 not a git repository）。
+            const repo = args.repo?.trim() || sessionCwdOf(exec?.agent) || deps.cwd?.()?.trim() || '';
+            if (!repo)
+                throw new Error('ocr_review: 无法确定目标仓库——请显式传 repo=<仓库绝对路径>（当前会话未记录工作目录）');
             // 托管评审走 ocr 自带 LLM（官方预算 15min×2 rounds），超时须远大于 preview/rule 的本地 git 操作
             const timeoutMs = args.sub === 'managed' ? 2_400_000 : 600_000;
-            const res = await runOcrFn(buildOcrArgs(args.sub, { repo: args.repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths, background: args.background }), { cwd: deps.cwd?.() ?? process.cwd(), timeoutMs });
+            const res = await runOcrFn(buildOcrArgs(args.sub, { repo, from: args.from, to: args.to, commit: args.commit, paths: args.paths, background: args.background }), { cwd: repo, timeoutMs });
             // 失败不抛错：结果附 error 摘要（error + stderr 前 500 字符），模型拿得到部分结果与原因后自行降级/重试
             const errSummary = res.error ? `${res.error} ${res.stderr.slice(0, 500)}`.trim() : '';
             if (args.sub === 'preview') {

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

@@ -18,6 +18,9 @@ export interface PlanningToolDeps {
     /** 真实实现：经官方子代理缝（ctx.subagents.start）启动只读预取子代理并返回其文本输出；测试注入 stub。
      *  parentAgent = 发起调用的主 agent（血缘/模型继承源），由 planning_prefetch 的 exec.agent 透传。 */
     spawnPrefetch?(prompt: string, workspaceDir: string, parentAgent?: Agent, signal?: AbortSignal): Promise<string>;
+    /** 采集子代理缝（白名单工具面）：启动 PRD 采集子代理并返回其文本输出；测试注入 stub。
+     *  parentAgent = 发起调用的主 agent（血缘/模型继承源），由 planning_prd_collect 的 exec.agent 透传。 */
+    spawnPrdCollect?(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。 */

package/lib/tools/planning-tools.js

@@ -1,9 +1,9 @@
 // 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 { validatePlanningChecklist, formatChecklistBody, routePrdPlatform, slicePrdMarkdown } from '../domain/planning-checklist.js';
 import { validatePrefetchManifest } from '../domain/prefetch-manifest.js';
-import { buildChecklistSlug, KB_PAGE_NAMESPACES_HINT, LOCAL_CHECKLIST_PREFIX, LOCAL_LEARNING_BASE, assertAllowedWikiPagePath, assertLocalKbPagePath } from '../wiki/page-path.js';
+import { buildChecklistSlug, KB_PAGE_NAMESPACES_HINT, LOCAL_CHECKLIST_PREFIX, LOCAL_SOURCE_DOCS_PREFIX, LOCAL_LEARNING_BASE, assertAllowedWikiPagePath, assertLocalKbPagePath } from '../wiki/page-path.js';
 import { validateLearning, formatLearningBody, buildRepoSlug, countLearningSignals } from '../domain/memory.js';
 const isWikiError = (e) => e instanceof Error && e.code === 'kb-unreachable';
 /** 主 agent 规划期工具：需求澄清清单落库（KB 优先/临时目录兜底）+ 只读仓库预取（子代理）。 */
@@ -20,7 +20,134 @@ 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: {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' } },
+            // 参数用官方类型化 schema（dsh-tools DSL：显式 object 必须声明 additionalProperties）在运行时
+            // 强制形状（ToolArgsError/INVALID_ARGS 带"路径+期望+enum"violation）；{type:'json'} 仅注解不
+            // 约束，曾致 spec 数组/双重编码/expected 词表错三连发（2026-09-21 销服一体清单案例，7 轮失败）。
+            // schema 表达不了的语义（非空、确切键名、expected 语义映射）仍由 description + validatePlanningChecklist 承担。
+            parameters: {
+                checklist: {
+                    type: 'object', required: true, additionalProperties: true,
+                    description: 'Structured PlanningChecklist. Shape is runtime-enforced by this schema; semantics not expressible in schema live in the description below.',
+                    properties: {
+                        requirementName: { type: 'string', description: 'Optional; page title 【需求】 source, same as task-card title' },
+                        spec: {
+                            type: 'object', required: true, additionalProperties: true,
+                            description: 'Six sections, all required.',
+                            properties: {
+                                problem: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                solution: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                testing: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                out_of_scope: { type: 'string', required: true, description: 'ONE coherent multi-line text (non-empty), never an array' },
+                                user_stories: { type: 'array', required: true, items: { type: 'string' }, description: 'Plain strings only; each element ONE sentence "As a <role>, I want <capability>, so that <benefit>"; never objects/nested' },
+                                impl_decisions: { type: 'array', required: true, items: { type: 'string' }, description: 'Plain strings only; one decision per element; never objects' },
+                            },
+                        },
+                        manifest: {
+                            type: 'object', required: true, additionalProperties: true,
+                            description: 'Repo-baseline facts (same shape as planning_prefetch output manifest).',
+                            properties: {
+                                repo: {
+                                    type: 'object', required: true, additionalProperties: true,
+                                    properties: {
+                                        localPath: { type: 'string', required: true, description: 'Absolute path of the target repo' },
+                                        remoteUrl: { type: 'string' },
+                                        branch: { type: 'string' },
+                                        dirtyFiles: { type: 'array', required: true, items: { type: 'string' }, description: 'Uncommitted changes; [] when clean' },
+                                    },
+                                },
+                                files: {
+                                    type: 'array', required: true,
+                                    description: 'File baseline; [] when not prefetched.',
+                                    items: {
+                                        type: 'object', additionalProperties: true,
+                                        properties: {
+                                            path: { type: 'string', required: true },
+                                            expected: { type: 'string', required: true, enum: ['exists', 'absent', 'content-hash'], description: 'What the file IS in the repo, NOT your change intent — never "modify"/"create": plan-to-edit file → "exists" + note「计划修改」; plan-to-create file → "absent" + note「计划新建」' },
+                                            note: { type: 'string' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        clarifications: {
+                            type: 'array', required: true,
+                            description: 'Record EVERY Q&A of this planning round; array must be non-empty (recovery rebuild may use {"q":"本轮无澄清（恢复重建）","a":"<来源页>"}).',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    q: { type: 'string', required: true, description: 'Key is exactly "q", not "question"' },
+                                    a: { type: 'string', required: true, description: 'Key is exactly "a", not "answer"' },
+                                },
+                            },
+                        },
+                        doubts: {
+                            type: 'array', required: true,
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    q: { type: 'string', required: true },
+                                    resolved: { type: 'boolean', required: true },
+                                    answer: { type: 'string' },
+                                },
+                            },
+                        },
+                        risks: {
+                            type: 'array',
+                            description: 'Optional; register real risks/non-blocking concerns surfaced during clarification; omit or [] when none.',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    description: { type: 'string', required: true },
+                                    source: { type: 'string', required: true },
+                                    mitigation: { type: 'string', required: true },
+                                },
+                            },
+                        },
+                        sources: {
+                            type: 'array', required: true,
+                            description: 'REQUIRED — requirement source links; if genuinely none, record exactly [{"type":"其他","url":"","note":"无来源+原因"}]',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    type: { type: 'string', required: true, enum: ['TAPD', 'Jira', '其他'], description: 'Source platform' },
+                                    url: { type: 'string', description: 'Source link; may be "" when genuinely none (note must then state why)' },
+                                    note: { type: 'string', description: 'Why this source / absence reason' },
+                                },
+                            },
+                        },
+                        prdCollection: {
+                            type: 'array', required: true,
+                            description: 'REQUIRED — register EVERY PRD link the user provided; [] only when no PRD link was given; blocked requires blockedReason (登录态|缺技能|404|其他)',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    url: { type: 'string', required: true, description: 'PRD link the user provided' },
+                                    platform: { type: 'string', enum: ['feishu', 'wecom', 'modao'], description: 'Optional; auto-routed by domain or LLM-judged' },
+                                    status: { type: 'string', required: true, enum: ['collected', 'blocked'], description: 'collection status' },
+                                    summary: { type: 'string', required: true, description: 'what was collected + key info + gaps' },
+                                    pages: { type: 'array', items: { type: 'string' }, description: 'optional; KB page paths of PRD slices' },
+                                    blockedReason: { type: 'string', description: 'required when status="blocked": 登录态 | 缺技能 | 404 | 其他' },
+                                    degraded: { type: 'boolean', description: 'optional; screenshot>5MB or write failed → degraded trace' },
+                                },
+                            },
+                        },
+                        placeholders: {
+                            type: 'array',
+                            description: 'Optional; centralized placeholder strategy for backend-not-ready items; omit or [] when none.',
+                            items: {
+                                type: 'object', additionalProperties: true,
+                                properties: {
+                                    target: { type: 'string', required: true },
+                                    value: { type: 'string', required: true },
+                                    replace: { type: 'string', required: true },
+                                },
+                            },
+                        },
+                        greenfield: { type: 'boolean', description: 'Optional; true=greenfield (target dir has no .git), D-phase pre-req to git init; false/absent=existing repo' },
+                    },
+                },
+                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();
@@ -98,6 +225,94 @@ export function buildPlanningTools(deps) {
                 return { ok: true, manifest };
             },
         }),
+        defineTool({
+            name: 'planning_prd_collect',
+            description: 'Dispatch a collection sub-agent to fetch ONE PRD link (login-state browser / doc skills). One call per link; for multiple links call once per link (parallel allowed). On success writes PRD source slices to KB source-docs namespace with screenshots base64-inlined (≤5MB each; screenshot oversized/embed-failure → degraded mark, never blocks collection; KB unreachable → blocked with re-collect guidance). Returns {ok, url, status, summary, pages, blockedReason?, degraded?, guidance?}. blocked = STOP and relay the returned guidance to the user by category (登录态/缺技能/404); never guess content, never skip, resolve then re-collect.',
+            parameters: {
+                url: { type: 'string', required: true, description: 'PRD link (modao.cc / feishu.cn / doc.weixin.qq.com / TAPD / Jira / other)' },
+                platform: { type: 'string', description: 'Optional platform hint when the domain is not recognized (feishu|wecom|modao|other); omit to auto-route by domain' },
+            },
+            output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
+            async execute(args, exec) {
+                const caller = deps.getCaller();
+                if (caller.actor !== 'human')
+                    throw new Error('permission denied: planning_prd_collect');
+                if (typeof args.url !== 'string' || !args.url.trim())
+                    throw new Error('url required');
+                const platform = args.platform?.trim() || routePrdPlatform(args.url) || null;
+                const prompt = [
+                    '# PRD 采集（planning_prd_collect）',
+                    `链接: ${args.url}`,
+                    `平台: ${platform ?? '未知（自行判定）'}`,
+                    '规则：带登录态抓全文（正文+截图）；只写临时目录，禁止写任何仓库文件；抓不到就如实报 blocked 与原因（登录态|缺技能|404|其他），禁止猜测内容。',
+                    '输出：仅一个 JSON 对象（无前后缀）：{"status":"collected","summary":"<采了什么+关键信息+缺口>","markdown":"<全文>","screenshots":[{"name":"x.png","base64":"<...>"}]} 或 {"status":"blocked","blockedReason":"登录态|缺技能|404|其他","summary":"<失败现场>"}',
+                ].join('\n');
+                // 官方子代理缝要求 parent（血缘/模型继承）+ signal（取消通道），由 ToolRunContext 透传；
+                // 缝未注入 = 集成缺口，硬失败而非静默跳过
+                if (!deps.spawnPrdCollect)
+                    throw new Error('planning_prd_collect: spawnPrdCollect not wired — main-session-tools 必须注入采集子代理缝');
+                // 无规划会话工作区（/plan: 未捕获或插件重启丢失）= fail-loud：
+                // 静默落 projects/unknown-repo/ 或回退 process.cwd() 会造成页面归组错位，必须先恢复工作区
+                const wsDir = deps.resolveWorkspaceDir?.() ?? null;
+                if (!wsDir) {
+                    throw new Error(`[workspace-missing] planning_prd_collect 需要活跃规划会话的工作区（当前未捕获 workspaceDir）。请先执行 ${deps.prefixRoutes.plan} 捕获工作区后再采集（不可跳过）。`);
+                }
+                const output = await deps.spawnPrdCollect(prompt, wsDir, exec?.agent, exec?.signal);
+                const parsed = parsePrdCollectOutput(output);
+                if (parsed.status === 'blocked') {
+                    const reason = parsed.blockedReason ?? '其他';
+                    return {
+                        ok: true, url: args.url, status: 'blocked', blockedReason: reason, summary: parsed.summary ?? '',
+                        guidance: PRD_BLOCKED_GUIDANCE[reason] ?? `采集失败（${reason}）。请用户排除原因后重新采集；不要猜测内容或跳过。`,
+                    };
+                }
+                // collected：切片 + 截图内嵌 + 写 KB（source-docs 命名空间）
+                const markdown = parsed.markdown ?? '';
+                const parts = slicePrdMarkdown(markdown);
+                const slug = buildChecklistSlug(args.url.replace(/^https?:\/\//, '').slice(0, 40));
+                let degraded = false;
+                const images = [];
+                for (const s of parsed.screenshots ?? []) {
+                    const img = embedScreenshot(s.name, s.base64);
+                    if (img === null) {
+                        degraded = true;
+                        images.push(`> degraded: 截图 ${s.name} 超 5MB 或无法内嵌，已降级为文字描述（内容见摘要）`);
+                    }
+                    else {
+                        images.push(img);
+                    }
+                }
+                const pages = [];
+                for (let i = 0; i < parts.length; i++) {
+                    const pagePath = local
+                        ? `${LOCAL_SOURCE_DOCS_PREFIX}${slug}-part-${String(i + 1).padStart(2, '0')}.md`
+                        : `${pagePrefix}${buildRepoSlug(wsDir)}/source-docs/${slug}-part-${String(i + 1).padStart(2, '0')}.md`;
+                    const body = [
+                        `# PRD 原文切片 ${i + 1}/${parts.length}`,
+                        `- 来源链接: ${args.url}`,
+                        `- 平台: ${platform ?? '未知'}`,
+                        `- 采集摘要: ${parsed.summary ?? ''}`,
+                        '',
+                        parts[i],
+                        ...(i === parts.length - 1 && images.length > 0 ? ['', '## 截图', '', ...images] : []),
+                    ].join('\n');
+                    try {
+                        await deps.wiki.write(pagePath, body);
+                        pages.push(pagePath);
+                    }
+                    catch (err) {
+                        if (!isWikiError(err))
+                            throw err;
+                        // KB 不可达：截图/原文无处落 → 整条采集降级为 blocked 引导（不产生半截状态）
+                        return {
+                            ok: true, url: args.url, status: 'blocked', blockedReason: '其他', summary: 'KB 不可达，采集产物无法落库',
+                            guidance: '知识库不可达，PRD 采集产物无法落库。请确认 wiki-vault 服务可用后重新采集。',
+                        };
+                    }
+                }
+                return { ok: true, url: args.url, status: 'collected', summary: parsed.summary ?? '', pages, degraded };
+            },
+        }),
         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).',
@@ -224,3 +439,33 @@ function parseManifestOutput(output) {
         throw new Error('planning_prefetch: invalid manifest from sub-agent: ' + errors.join('; '));
     return raw;
 }
+const SCREENSHOT_MAX_BYTES = 5 * 1024 * 1024; // 单图 base64 ≤5MB 内嵌；超限记 degraded
+function parsePrdCollectOutput(output) {
+    const text = output.trim();
+    const jsonText = text.startsWith('{') ? text : text.slice(text.indexOf('{'), text.lastIndexOf('}') + 1);
+    let raw;
+    try {
+        raw = JSON.parse(jsonText);
+    }
+    catch {
+        throw new Error('planning_prd_collect: sub-agent did not return valid JSON');
+    }
+    const o = raw;
+    if (o.status !== 'collected' && o.status !== 'blocked')
+        throw new Error('planning_prd_collect: sub-agent status must be collected|blocked');
+    return o;
+}
+/** blocked 分类引导（按 blockedReason 精确匹配；未匹配走调用方兜底文案）。 */
+const PRD_BLOCKED_GUIDANCE = {
+    '登录态': '采集被登录态拦截。请用户自行在浏览器登录对应平台后，重新调用本工具采集；不要猜测页面内容。',
+    '缺技能': '当前环境缺少可采集该链接的技能。请用户安装对应技能（带登录态浏览器：huashu-chrome；CDP 兜底：web-access；企微文档：wecom-docs；飞书：lark）后重新采集。',
+    '404': '链接无效或已失效（404）。请用户提供有效的 PRD 链接后重新采集。',
+};
+/** 截图内嵌：≤5MB 转 markdown data URI；超限返回 null（调用方记 degraded）。 */
+function embedScreenshot(name, base64) {
+    if (Buffer.byteLength(base64, 'utf8') > SCREENSHOT_MAX_BYTES)
+        return null;
+    const ext = (name.split('.').pop() ?? 'png').toLowerCase();
+    const mime = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : ext === 'gif' ? 'image/gif' : ext === 'webp' ? 'image/webp' : 'image/png';
+    return `![${name}](data:${mime};base64,${base64})`;
+}

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

@@ -6,9 +6,13 @@ function guard(action, caller) {
     if (!can(action, caller.actor, null))
         throw new Error('permission denied: ' + action);
 }
-/** 逐字段校验 spec card sections：数组进 string 段（如 testing）会在下游 .trim() 崩溃。 */
+/** 逐字段校验 spec card sections：数组进 string 段（如 testing）会在下游 .trim() 崩溃；
+ *  非对象（双重编码字符串）先报真因，不产生六字段误导性 undefined 墙。 */
 function validateSections(sections) {
     const errors = [];
+    if (sections !== undefined && (typeof sections !== 'object' || Array.isArray(sections))) {
+        return [`sections must be a JSON object (got ${Array.isArray(sections) ? 'array' : typeof sections}) — pass the object itself, never a JSON-encoded string`];
+    }
     const s = (sections ?? {});
     const strFields = [
         ['problem', 'problem'], ['solution', 'solution'], ['testing', 'testing'], ['out_of_scope', 'out_of_scope'],
@@ -47,7 +51,9 @@ export function buildSpecCardTools(service, getCaller) {
             description: 'Edit a draft spec card sections (human only).',
             parameters: {
                 cardId: { type: 'string', required: true },
-                sections: { type: 'json', required: true, description: 'Six-section spec card body' },
+                // 官方 object schema（2026-09-21）：{type:'json'} 不约束，双重编码字符串穿透 validateSections
+                // 产出六字段误导性 undefined 墙；open object 运行时拦字符串。
+                sections: { type: 'object', required: true, additionalProperties: true, description: 'Six-section spec card body (object with problem/solution/testing/out_of_scope strings + user_stories/impl_decisions string arrays). Pass the object itself — never a JSON-encoded string.' },
             },
             output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: JSON.stringify(v) }] },
             async execute(args) {

package/lib/tools/wiki-tools.js

@@ -44,7 +44,7 @@ export function buildWikiTools(wiki, getCaller) {
             async execute(args) {
                 const caller = getCaller();
                 guard('wiki-write', caller);
-                // 工具边界强校验——只允许 projects/<repoSlug>/ 白名单命名空间（KB_PAGE_NAMESPACES_HINT 五类，
+                // 工具边界强校验——只允许 projects/<repoSlug>/ 白名单命名空间（KB_PAGE_NAMESPACES_HINT 六类，
                 // 见 page-path.ts），杜绝 LLM 自造路径/拼错层级导致 kb_url 无法跳转。
                 assertAllowedWikiPagePath(args.pagePath);
                 const out = await wiki.write(args.pagePath, args.content);