@joekytc/dsh-swarm 0.3.7 → 0.3.9

package/lib/services/evidence-replay.js

@@ -0,0 +1,79 @@
+// src/services/evidence-replay.ts
+/** DT 评审证据三级核验编排（PR2）：L1 缺证标记 → L2 纸面核对（零执行）→ L3 重放（默认关，非沙箱）。
+ * 非阻塞：任何结果只返回留痕数据，不改 verdict、不 throw。 */
+import { readFile } from 'node:fs/promises';
+import { runGateCommands } from './gate-runner.js';
+import { isAllowedCommand, paperCheck, parseIssueEvidence } from '../domain/evidence-check.js';
+/** 沿父链找最近 execute 卡的 worktree_dir（重放 cwd=被评审代码所在处）。 */
+export function resolveTargetWorktree(parents) {
+    for (const p of parents) {
+        if (p.assignee === 'd' && p.mode === 'execute') {
+            const wt = p.metadata?.['worktree_dir'];
+            if (typeof wt === 'string' && wt.trim())
+                return wt;
+        }
+    }
+    return null;
+}
+export async function checkIssueEvidence(input) {
+    const list = Array.isArray(input.issues) ? input.issues : [];
+    const forbidden = input.forbidden ?? ['rm -rf /', 'git push'];
+    const out = [];
+    for (const rawIssue of list) {
+        // 评审 Important：per-issue 容错——被核验者塞 null/标量元素不得让整批核验无痕消失
+        if (typeof rawIssue !== 'object' || rawIssue === null) {
+            out.push({ title: '(invalid issue entry)', severity: 'unknown', state: 'could-not-replay', detail: 'issues 数组含非对象元素 — needs-human 核对' });
+            continue;
+        }
+        const issue = rawIssue;
+        const title = String(issue['title'] ?? '(untitled)');
+        const severity = String(issue['severity'] ?? 'low');
+        const ev = parseIssueEvidence(issue['evidence']);
+        if (!ev) {
+            const serious = severity === 'critical' || severity === 'high';
+            out.push(serious
+                ? { title, severity, state: 'could-not-replay', detail: 'no evidence provided (critical/high) — needs-human 核对' }
+                : { title, severity, state: 'not-provided', detail: 'no evidence attached' });
+            continue;
+        }
+        // L2 纸面核对（零执行）
+        let content = null;
+        try {
+            content = await input.readFile(ev.file);
+        }
+        catch {
+            content = null;
+        }
+        const paper = paperCheck(content, ev.exit);
+        if (paper === 'matches') {
+            out.push({ title, severity, state: 'matches', detail: `paper check ok: ${ev.file}` });
+            continue;
+        }
+        // L3 重放（对不上才动用；默认关）
+        if (!input.replayEnabled) {
+            out.push({ title, severity, state: 'could-not-replay', detail: `paper ${paper}; replay disabled by config — needs-human` });
+            continue;
+        }
+        if (!isAllowedCommand(ev.command, input.allowPrefixes)) {
+            out.push({ title, severity, state: 'could-not-replay', detail: `command not allowlisted: ${ev.command}` });
+            continue;
+        }
+        if (!input.worktreeDir) {
+            out.push({ title, severity, state: 'could-not-replay', detail: 'no target worktree resolved' });
+            continue;
+        }
+        const cmd = { command: ev.command, cwd: input.worktreeDir, source: 'tdd' };
+        const report = await runGateCommands([cmd], { timeoutMs: input.timeoutMs, forbidden }, input.run);
+        // 评审 Important：TIMEOUT/SPAWN_FAIL/FORBIDDEN ≠ 假证据——超时/派生失败/黑名单命中落 could-not-replay，
+        // 仅真实执行（含非零退出）与声明不符才判 differs（四态语义准确性）
+        if (report.failure && report.failure.code !== 'NONZERO') {
+            out.push({ title, severity, state: 'could-not-replay', detail: `replay ${report.failure.code}: ${report.failure.detail} — needs-human` });
+            continue;
+        }
+        const rerun = report.results.at(-1)?.exitCode;
+        out.push(rerun !== null && rerun === ev.exit
+            ? { title, severity, state: 'matches', detail: `replay confirmed exit ${rerun}` }
+            : { title, severity, state: 'differs', detail: `replay exit=${rerun} ≠ claimed ${ev.exit} — 假证据疑点，needs-human` });
+    }
+    return out;
+}

package/lib/services/gate-evidence.d.ts

@@ -0,0 +1,2 @@
+import type { GateRunReport } from './gate-runner.js';
+export declare function writeGateLog(dir: string, taskId: string, report: GateRunReport): Promise<string>;

package/lib/services/gate-evidence.js

@@ -0,0 +1,21 @@
+// src/services/gate-evidence.ts
+/** gate 实测日志落盘（PR1 P3 存档）：pass 也留原始输出，事后可翻账对质（issue #2 verify.sh 模式的 D 侧落点）。
+ * 追加写（每轮一条时间戳头），单文件 per task，路径进 gate detail 供 agent/human 引用。 */
+import { mkdir, appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function writeGateLog(dir, taskId, report) {
+    const logDir = join(dir, 'gate-logs');
+    await mkdir(logDir, { recursive: true });
+    const path = join(logDir, `${taskId}.log`);
+    const lines = [`== ${new Date().toISOString()} ok=${report.ok}`];
+    for (const r of report.results) {
+        lines.push(`-- ${r.command}`);
+        lines.push(`exit=${r.exitCode} durationMs=${r.durationMs} truncated=${r.truncated}`);
+        if (r.output)
+            lines.push(r.output);
+    }
+    if (report.failure)
+        lines.push(`-- failure: ${report.failure.code}: ${report.failure.detail}`);
+    await appendFile(path, lines.join('\n') + '\n');
+    return path;
+}

package/lib/services/im-delivery.d.ts

@@ -72,6 +72,10 @@ export interface BotChoice {
     via: BotVia;
     fallbackSaved?: boolean;
 }
+/** 应答 → 候选 botId（宽松匹配，宁缺勿错）：
+ *  ① 令牌精确相等；② 与令牌互相包含（仅当令牌足够长，防 3~5 字符误命中）。
+ *  多义（>=2 个候选命中）或无法识别 → 空串（调用方 fail-closed 不投，绝不猜）。 */
+export declare function matchBotAnswer(options: BotAskOption[], raw: string): string;
 /** 机器人决策链：显式配置 → 唯一机器人 → 会话 preset 命中 → 默认机器人 → 交互选择。
  *  每环都 fail-closed（宁可不投也不投错对象）；探针不可用只失去自动匹配能力，不阻断投递。 */
 export declare function chooseBot(im: DshImLike, cfg: {

package/lib/services/im-delivery.js

@@ -32,6 +32,33 @@ function resolveDshIm(ctx, log) {
 function askLabel(o) {
     return o.label ? `${o.label}（${o.botId}）` : o.botId;
 }
+/** 归一：去空白（含全角空格）+ 小写（GUI 可能回传带装饰/大小写变化的文本）。 */
+function normAnswer(s) {
+    return s.replace(/[\s\u3000]/g, '').toLowerCase();
+}
+/** 一个候选的全部可识别令牌：botId / 展示 label 全文 / label 的展示名段（去 ·模式·离线 与 （botId）后缀）。 */
+function idTokens(o) {
+    const out = [normAnswer(o.botId)];
+    if (o.label) {
+        const n = normAnswer(o.label);
+        out.push(n.split('（')[0], n.split('·')[0]);
+    }
+    return [...new Set(out.filter((t) => t.length > 0))];
+}
+/** 应答 → 候选 botId（宽松匹配，宁缺勿错）：
+ *  ① 令牌精确相等；② 与令牌互相包含（仅当令牌足够长，防 3~5 字符误命中）。
+ *  多义（>=2 个候选命中）或无法识别 → 空串（调用方 fail-closed 不投，绝不猜）。 */
+export function matchBotAnswer(options, raw) {
+    const target = normAnswer(raw);
+    if (!target)
+        return '';
+    const exact = options.find((o) => idTokens(o).includes(target));
+    if (exact)
+        return exact.botId;
+    const partial = options.filter((o) => idTokens(o).some((t) => t.length >= 6 && (t.includes(target) || target.includes(t))));
+    const uniq = [...new Set(partial.map((o) => o.botId))];
+    return uniq.length === 1 ? uniq[0] : '';
+}
 /** 多机器人且无法自动决策时的 fail-closed 报错：列候选（有探针数据则带模式与连接态）。 */
 function botCandidatesError(ids, probed) {
     const byId = new Map(probed.map((b) => [b.botId, b]));
@@ -212,10 +239,11 @@ function buildBotAsk(ctx, agent, log) {
             const pick = ans.answers?.find((a) => a.id === 'im-bot');
             const typed = pick?.custom?.trim() ?? '';
             const selected = pick?.selected?.[0]?.trim() ?? '';
-            // 自由文本也接受，但必须是候选之一——防手写错 id 投到未知对象。
-            const botId = options.find((o) => askLabel(o) === selected || o.botId === selected || o.botId === typed)?.botId ?? '';
+            // 选中标签与自由文本都接受，但必须唯一落到候选之一——防手写错 id 投到未知对象。
+            const botId = matchBotAnswer(options, selected) || matchBotAnswer(options, typed);
             if (!botId) {
-                log('[im-delivery] 机器人交互已应答但未映射到候选（selected 与候选不符）');
+                // 只记候选 id 与用户可见文本（公开标识，无敏感载荷），便于下次定位映射失败。
+                log(`[im-delivery] 机器人交互已应答但未映射到候选: selected=${JSON.stringify(selected).slice(0, 120)} custom=${JSON.stringify(typed).slice(0, 120)} candidates=${options.map((o) => o.botId).join(',')}`);
                 return null;
             }
             const setDefault = (ans.answers?.find((a) => a.id === 'im-bot-default')?.selected ?? []).includes(ASK_SET_DEFAULT_LABEL);

package/lib/services/kanban-provider.d.ts

@@ -16,5 +16,6 @@ export declare class KanbanProvider extends Service {
     /** 整链硬删除后的联动钩子（由 startDispatcher 装配注入）：dispatcher 游标同步 + V 编排 entry 清理。
      *  purge 物理重排 events seq，若不同步则删链后新建链的可唤醒事件被运行中实例永久跳过。 */
     onChainDeleted: ((chainId: string) => Promise<void> | void) | null;
+    private readonly gateLogDir;
     constructor(ctx: Context, config: KanbanConfig, configProvider: ConfigProvider);
 }

package/lib/services/kanban-provider.js

@@ -1,10 +1,13 @@
 import { Service } from '@deepseek-ai/cordis';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
 import { KanbanService } from '../domain/kanban-service.js';
 import { FileEventStore } from '../domain/event-store.js';
-import { deriveGatePlan, isGatePlan, branchMatches } from '../domain/gate-policy.js';
+import { deriveGatePlan, branchMatches, resolveDiffBase } from '../domain/gate-policy.js';
 import { runGateCommands } from './gate-runner.js';
+import { writeGateLog } from './gate-evidence.js';
+import { checkIssueEvidence, resolveTargetWorktree } from './evidence-replay.js';
 export class KanbanProvider extends Service {
     service;
     /** GUI retry 的任务执行器（由 startDispatcher 装配后注入；webServer 先于 agents 就绪时可为 null）。 */
@@ -13,34 +16,49 @@ export class KanbanProvider extends Service {
      *  purge 物理重排 events seq，若不同步则删链后新建链的可唤醒事件被运行中实例永久跳过。 */
     onChainDeleted = null;
     // 经 configProvider getter 读 effective 配置——配置面板改 wikiVault.baseUrl 后 kb_url 前缀校验热生效。
+    gateLogDir;
     constructor(ctx, config, configProvider) {
         super(ctx, 'kanban');
         const dir = config.storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? homedir());
+        this.gateLogDir = dir;
         this.service = new KanbanService(new FileEventStore(dir), () => configProvider.getEffective().wikiVault?.baseUrl);
-        // P1 实测闸装配（组合根）：complete 前派生 GatePlan → 分支一致性核对 → 实测执行。
-        // hook 绝不 throw：意外异常记日志并返回 null（零感知 skip，fail-open 与分支不一致语义一致）。
+        // P1 实测闸装配（组合根）：complete 前派生 GateOutcome → 分支核对 → 实测执行/打回/警报。
+        // hook 绝不 throw：意外异常记日志并返回 null（基建故障静默，既有决议）。
+        // diff 实况：base=D 卡 body 的 TARGET_BRANCH（gate-policy resolveDiffBase）；git 失败或无 base → null（派生层保守放行）。
         this.service.setGateHook(async (task, handoff) => {
             try {
                 // 热读取（同 wikiVault.baseUrl 先例，getEffective）：配置面板改 gates 后无需重建即生效。
                 const cfg = configProvider.getEffective().gates ?? { enabled: true, timeoutMs: 600000, forbidden: ['rm -rf /', 'git push'] };
-                const plan = deriveGatePlan({ assignee: task.assignee, mode: task.mode, handoff, config: { enabled: cfg.enabled } });
-                if (!isGatePlan(plan))
-                    return null; // skip：disabled/非 D/旧卡/路径违规
-                const wt = plan.commands[0].cwd;
-                // 分支一致性核对（防报假 worktree 绕闸）：查询失败或与 metadata.branch 不一致 → skip 零感知。
-                const current = await new Promise((resolve) => {
-                    const child = spawn('git', ['-C', wt, 'rev-parse', '--abbrev-ref', 'HEAD'], { stdio: ['ignore', 'pipe', 'pipe'] });
-                    let out = '';
-                    child.stdout.on('data', (c) => { out += c.toString('utf8'); });
-                    child.on('error', () => resolve(null));
-                    child.on('close', (code) => resolve(code === 0 ? out.trim() || null : null));
+                const metadata = (handoff.metadata ?? {});
+                const wt = typeof metadata['worktree_dir'] === 'string' ? metadata['worktree_dir'] : '';
+                const base = resolveDiffBase(task.body ?? '');
+                const diffFiles = wt.trim() && base ? await gitDiffNames(wt, base) : null;
+                const outcome = deriveGatePlan({
+                    assignee: task.assignee, mode: task.mode, handoff,
+                    config: { enabled: cfg.enabled }, diffFiles,
                 });
-                if (!branchMatches(current, handoff.metadata?.['branch']))
-                    return null;
-                const report = await runGateCommands(plan.commands, { timeoutMs: cfg.timeoutMs, forbidden: cfg.forbidden });
+                if (outcome.kind === 'silent-skip')
+                    return null; // 不适用：零事件（旧语义）
+                if (outcome.kind === 'alarm-skip')
+                    return { skipped: true, reason: outcome.reason };
+                if (outcome.kind === 'bounce')
+                    return { ok: false, detail: outcome.reason };
+                // run：分支一致性核对（⑦ 不一致由静默 skip 升级为 bounce 打回）
+                const current = await gitCurrentBranch(outcome.commands[0].cwd);
+                if (!branchMatches(current, metadata['branch']))
+                    return { ok: false, detail: `分支不一致：声明 ${String(metadata['branch'] ?? '')}，实际 ${current ?? 'unknown'}——先同步分支再重交` };
+                const report = await runGateCommands(outcome.commands, { timeoutMs: cfg.timeoutMs, forbidden: cfg.forbidden });
+                // 落盘失败不吞实测结果（评审 Minor）：测量已做，结论必须保住——仅降级 evidence 路径
+                let evidencePath = '(log write failed)';
+                try {
+                    evidencePath = await writeGateLog(this.gateLogDir, task.id, report);
+                }
+                catch (logError) {
+                    console.error('[dsh-swarm] gate log write failed (result kept): ' + String(logError));
+                }
                 const detail = report.ok
-                    ? plan.commands.map((c) => c.command).join(' && ') + ' exit 0'
-                    : `${report.failure.code}: ${report.failure.command} — ${report.failure.detail}\n${(report.results.at(-1)?.output ?? '').slice(-2000)}`;
+                    ? outcome.commands.map((c) => c.command).join(' && ') + ' exit 0\nevidence: ' + evidencePath
+                    : `${report.failure.code}: ${report.failure.command} — ${report.failure.detail}\n${(report.results.at(-1)?.output ?? '').slice(-2000)}\nevidence: ${evidencePath}`;
                 return { ok: report.ok, detail };
             }
             catch (error) {
@@ -48,5 +66,60 @@ export class KanbanProvider extends Service {
                 return null;
             }
         });
+        // PR2 评审证据核验装配：DT 卡 complete 时三级核验（缺证标记/纸面核对/白名单重放）。
+        // 非阻塞：结果只发 review/evidence-check 事件；重放开关默认关（真执行 AI 命令=非沙箱）。
+        this.service.setEvidenceCheckHook(async (task, handoff) => {
+            try {
+                const cfg = configProvider.getEffective().evidenceReplay;
+                const state = await this.service.snapshot();
+                const parentTasks = task.parents
+                    .map((pid) => state.tasks.get(pid))
+                    .filter((t) => Boolean(t));
+                const parentsWithMeta = parentTasks.map((t) => ({
+                    assignee: t.assignee, mode: t.mode,
+                    metadata: (state.handoffs.get(t.id)?.metadata ?? {}),
+                }));
+                const issues = handoff.metadata?.['review_evidence']?.issues;
+                if (!Array.isArray(issues) || issues.length === 0)
+                    return null;
+                // worktree 解析边界（评审 Minor 固化）：一层 parents 解析覆盖现网全部建卡路径
+                //（首评卡 parents=d:execute；复审卡 parents=[rework 卡] 直接命中）；
+                // rework source 为 DT 卡等未命中场景 fail-safe → could-not-replay 不执行。
+                return { results: await checkIssueEvidence({
+                        issues,
+                        replayEnabled: cfg.enabled, timeoutMs: cfg.timeoutMs, allowPrefixes: cfg.allowPrefixes,
+                        forbidden: configProvider.getEffective().gates?.forbidden,
+                        worktreeDir: resolveTargetWorktree(parentsWithMeta),
+                        readFile: (p) => readFile(p, 'utf8').catch(() => null),
+                    }) };
+            }
+            catch (error) {
+                console.error('[dsh-swarm] evidence check hook failed (non-blocking): ' + String(error));
+                return null;
+            }
+        });
     }
 }
+function gitCurrentBranch(wt) {
+    return new Promise((resolve) => {
+        const child = spawn('git', ['-C', wt, 'rev-parse', '--abbrev-ref', 'HEAD'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        child.stdout.on('data', (c) => { out += c.toString('utf8'); });
+        child.on('error', () => resolve(null));
+        child.on('close', (code) => resolve(code === 0 ? out.trim() || null : null));
+    });
+}
+/** git diff --name-only base...HEAD；任何失败 → null（gate-policy 保守放行）。 */
+function gitDiffNames(wt, base) {
+    return new Promise((resolve) => {
+        const child = spawn('git', ['-C', wt, 'diff', '--name-only', `${base}...HEAD`], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        child.stdout.on('data', (c) => { out += c.toString('utf8'); });
+        child.on('error', () => resolve(null));
+        child.on('close', (code) => {
+            if (code !== 0)
+                return resolve(null);
+            resolve(out.split('\n').map((s) => s.trim()).filter(Boolean));
+        });
+    });
+}

package/lib/tools/kanban-tools.js

@@ -93,12 +93,20 @@ export function buildKanbanTools(service, getCaller) {
             parameters: {
                 taskId: { type: 'string', required: true },
                 summary: { type: 'string', required: true, description: 'Human-readable completion summary' },
-                metadata: { type: 'json', description: 'Machine-readable handoff: changed_files/verification/kb_url... W3/kb may add report = { requirement, status, branch, tasks: [{ text, done }], acceptance, verification, leftovers?, todos? } (delivery-report fields; tasks mirrors the OpenSpec plan checklist openspec/changes/<id>/tasks.md verbatim, done = checked)' },
+                // metadata 用官方 object schema（2026-09-21：{type:'json'} 不施加约束，模型双重编码字符串静默
+                // 穿透到 delivery 闸才爆出误导性 "delivery required"——open object = 必须对象、键值任意，字符串
+                // 由运行时 ToolArgsError "must be an object" 单轮拦截。additionalProperties 必填（DSL 硬规则）。
+                metadata: { type: 'object', additionalProperties: true, description: 'Machine-readable handoff: changed_files/verification/kb_url... W3/kb may add report = { requirement, status, branch, tasks: [{ text, done }], acceptance, verification, leftovers?, todos? } (delivery-report fields; tasks mirrors the OpenSpec plan checklist openspec/changes/<id>/tasks.md verbatim, done = checked). 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) {
                 const caller = getCaller();
-                const done = await service.completeTask(args.taskId, { summary: args.summary, metadata: args.metadata ?? {}, completedAt: Date.now() }, caller.actor, { boundTaskId: caller.boundTaskId });
+                // 运行时诚实检查（纵深）：schema 已强制 object，此处拦截直调/回归路径——绝不静默强转字符串
+                const meta = args.metadata;
+                if (meta !== undefined && (typeof meta !== 'object' || Array.isArray(meta))) {
+                    throw new Error(`metadata must be a JSON object (got ${Array.isArray(meta) ? 'array' : typeof meta}) — pass the object itself, never a JSON-encoded string`);
+                }
+                const done = await service.completeTask(args.taskId, { summary: args.summary, metadata: (meta ?? {}), completedAt: Date.now() }, caller.actor, { boundTaskId: caller.boundTaskId });
                 return done;
             },
         }),

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

@@ -2,7 +2,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { PrefixRoutes } from '../config.js';
 import type { ConfigProvider } from '../services/config-provider.js';
 import { type PlanningToolDeps } from './planning-tools.js';
-import type { PlanningChecklist } from '../domain/planning-checklist.js';
+import { type PlanningChecklist } from '../domain/planning-checklist.js';
 /** v2 规划上下文（/plan: 捕获 → planning_checklist_save 回写 → /openspec: 建链）。模块级内存，随插件进程存活。 */
 export interface PlanningContext {
     workspaceDir: string | null;

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

@@ -10,7 +10,9 @@ import { sendChainReport, createSender, parseSendRequest, resolveReportChainId,
 import { recallMemoryIndex, searchChecklists } from '../wiki/memory-recall.js';
 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';
@@ -60,9 +62,9 @@ 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 禁止为空）；
+4. legacy 页重建后调 planning_checklist_save(checklist, restoreRef=<该候选页路径>) 回存（覆盖原页，勿产生重复页），成功后提示用户重新发送 ${routes.openspec} 确认。
 禁止：跳过恢复直接建链建卡；猜测清单内容；把恢复失败归因于"重试/进程检查"之外的任何原因。
 `;
 const RECOVERY_NONE_GUIDANCE = (routes) => `
@@ -131,16 +133,6 @@ function buildFreeSendGuidance(routes, query, dm) {
         '投递结果只向用户确认成功与目标，不复述正文；失败时把 error/guidance 原样转告，勿编造原因。',
     ].join('\n');
 }
-/** 当前会话 preset（多机器人投递按它匹配机器人的默认 dsh 模式）。
- *  header.agentPreset 缺省（用默认模式创建的会话可能不落该字段）→ 回落到 agentPresets.defaultId；
- *  两者都拿不到返回空串，调用方按「无模式匹配」处理（走默认机器人/交互，绝不猜）。 */
-function sessionPresetOf(ctx, exec) {
-    const fromHeader = exec?.agent?.session?.header?.agentPreset;
-    if (typeof fromHeader === 'string' && fromHeader.trim())
-        return fromHeader.trim();
-    const presets = ctx.get?.('agentPresets');
-    return typeof presets?.defaultId === 'string' ? presets.defaultId : '';
-}
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */
@@ -247,7 +239,7 @@ export function registerMainSessionTools(ctx, configProvider) {
                 const targetOpts = {
                     retryDelaysMs: [], manual: true,
                     targetKind: (parsed.dm ? 'user' : 'group'),
-                    sessionPreset: sessionPresetOf(ctx, exec),
+                    sessionPreset: sessionPresetOf(ctx, exec?.agent),
                     agent: exec?.agent,
                 };
                 const deliver = async (variant, query) => {
@@ -279,13 +271,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: 恢复）');
@@ -312,11 +300,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: 恢复）');
@@ -330,6 +325,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',
@@ -360,13 +373,15 @@ export function registerMainSessionTools(ctx, configProvider) {
             const dm = args.dm === true;
             const deliver = createSender(ctx, service, configProvider, {
                 retryDelaysMs: [], manual: true, targetKind: dm ? 'user' : 'group',
-                sessionPreset: sessionPresetOf(ctx, exec), agent: exec?.agent,
+                sessionPreset: sessionPresetOf(ctx, exec?.agent), agent: exec?.agent,
             });
             const r = await deliver('free-send', text);
             if (!r.ok) {
+                // 注意：返回对象不得带 undefined 值——工具输出要过 lossless-JSON 校验，undefined 会让模型只看到
+                // 「value is not lossless JSON」而看不到真实错误（实测踩过）。
                 return {
                     kind: 'send', mode: 'free', dm, error: r.error,
-                    guidance: r.error.startsWith(DSH_IM_MISSING_PREFIX) ? DSH_IM_MISSING_GUIDANCE : undefined,
+                    ...(r.error.startsWith(DSH_IM_MISSING_PREFIX) ? { guidance: DSH_IM_MISSING_GUIDANCE } : {}),
                 };
             }
             return {

package/lib/tools/planning-tools.js

@@ -20,7 +20,93 @@ 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 },
+                                },
+                            },
+                        },
+                    },
+                },
+                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();

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