@joekytc/dsh-swarm 0.3.8 → 0.3.10

package/lib/domain/planning-checklist.js

@@ -4,6 +4,8 @@ const STR_FIELDS = [
     ['problem', 'problem'], ['solution', 'solution'], ['testing', 'testing'], ['out_of_scope', 'out_of_scope'],
 ];
 const ARR_FIELDS = [['user_stories', 'user_stories'], ['impl_decisions', 'impl_decisions']];
+/** 闸2 禁词表：澄清答案中指代不明的缩写；宁窄后扩，避免误伤正常表述。 */
+export const FORBIDDEN_SHORTHANDS = ['按推荐', '同上', '见上', '同前', '如前所述', 'same as above', 'ditto', 'see above'];
 /** 需求澄清清单 schema 硬校验：返回错误列表（空数组=合法）。清单缺段即拒绝保存（硬闸，主 agent 会话内修正）。 */
 export function validatePlanningChecklist(raw) {
     const errors = [];
@@ -62,6 +64,13 @@ export function validatePlanningChecklist(raw) {
                 const got = typeof o === 'object' && o !== null ? Object.keys(o).join(',') : JSON.stringify(el);
                 errors.push(`checklist.clarifications[${i}] must be {"q": string, "a": string} with both non-empty (got keys: ${got}) — use keys "q" and "a", not "question"/"answer"`);
             }
+            if (ok) {
+                const answer = o['a'].toLowerCase();
+                const hit = FORBIDDEN_SHORTHANDS.find((w) => answer.includes(w.toLowerCase()));
+                if (hit) {
+                    errors.push(`checklist.clarifications[${i}].a contains forbidden shorthand "${hit}" — 每条问答必须含完整决策正文（字段名/接口路径/枚举值/组件名/位置规则），禁止指代不明缩写，展开写全`);
+                }
+            }
         });
     }
     const dbs = c['doubts'];
@@ -101,6 +110,79 @@ export function validatePlanningChecklist(raw) {
             });
         }
     }
+    // 闸1：需求来源必挂。恢复重建旧页无来源时按错误文案中的逃生口录「无来源+原因」条目
+    const sources = c['sources'];
+    if (!Array.isArray(sources) || sources.length === 0) {
+        errors.push('checklist.sources must be a non-empty array — record requirement source links (TAPD/Jira/其他). If genuinely no source exists, record exactly [{type:"其他", url:"", note:"无来源+原因"}]');
+    }
+    else {
+        sources.forEach((el, i) => {
+            const o = el;
+            const typeOk = o !== null && typeof o === 'object' && (o['type'] === 'TAPD' || o['type'] === 'Jira' || o['type'] === '其他');
+            const urlOk = typeof o?.['url'] === 'string';
+            const noteOk = typeof o?.['note'] === 'string';
+            if (!typeOk || !urlOk || !noteOk) {
+                const got = typeof o === 'object' && o !== null ? Object.keys(o).join(',') : JSON.stringify(el);
+                errors.push(`checklist.sources[${i}] must be {"type": "TAPD"|"Jira"|"其他", "url": string, "note": string} (got keys: ${got})`);
+                return;
+            }
+            if (o['url'].trim() === '' && o['note'].trim() === '') {
+                errors.push(`checklist.sources[${i}] url 为空（无来源）时 note 必须写明无来源原因`);
+            }
+        });
+    }
+    // 闸3：PRD 采集凭证。登记链接必须落到 collected（含摘要/页路径）或 blocked（含原因）；
+    // 其余状态（含漏填）= 登记了却没采 → 拒收
+    const prd = c['prdCollection'];
+    if (!Array.isArray(prd)) {
+        errors.push('checklist.prdCollection must be an array — register every PRD link the user provided (empty [] only when the user gave no PRD link)');
+    }
+    else {
+        prd.forEach((el, i) => {
+            const o = el;
+            const urlOk = typeof o?.['url'] === 'string' && o['url'].trim().length > 0;
+            const status = o?.['status'];
+            if (typeof o !== 'object' || o === null || !urlOk) {
+                errors.push(`checklist.prdCollection[${i}] must be an object with non-empty "url"`);
+                return;
+            }
+            if (status !== 'collected' && status !== 'blocked') {
+                errors.push(`checklist.prdCollection[${i}].status must be "collected" or "blocked" (got: ${JSON.stringify(status)}) — 链接已登记就必须完成采集或记录阻塞原因，禁止悬空`);
+                return;
+            }
+            if (typeof o['summary'] !== 'string' || o['summary'].trim() === '') {
+                errors.push(`checklist.prdCollection[${i}].summary must be a non-empty string（采了什么+关键信息+缺口）`);
+            }
+            if (status === 'blocked' && (typeof o['blockedReason'] !== 'string' || o['blockedReason'].trim() === '')) {
+                errors.push(`checklist.prdCollection[${i}].blockedReason required when status="blocked"（登录态 | 缺技能 | 404 | 其他）`);
+            }
+        });
+    }
+    // 占位策略（可选）：存在则三要素非空
+    const phs = c['placeholders'];
+    if (phs !== undefined) {
+        if (!Array.isArray(phs)) {
+            errors.push('checklist.placeholders must be an array when present');
+        }
+        else {
+            phs.forEach((el, i) => {
+                const o = el;
+                const ok = typeof o === 'object' && o !== null &&
+                    typeof o['target'] === 'string' && o['target'].trim() !== '' &&
+                    typeof o['value'] === 'string' &&
+                    typeof o['replace'] === 'string' && o['replace'].trim() !== '';
+                if (!ok) {
+                    const got = typeof o === 'object' && o !== null ? Object.keys(o).join(',') : JSON.stringify(el);
+                    errors.push(`checklist.placeholders[${i}] must be {"target": string, "value": string, "replace": string} with target/replace non-empty (got keys: ${got})`);
+                }
+            });
+        }
+    }
+    // greenfield（可选）：存在即须布尔。true=绿地（无 .git 全新项目），D 阶段建仓前置；false/缺省=既有仓库
+    const gf = c['greenfield'];
+    if (gf !== undefined && typeof gf !== 'boolean') {
+        errors.push(`checklist.greenfield must be a boolean when present (got: ${JSON.stringify(gf)})`);
+    }
     return errors;
 }
 /** 需求澄清清单页标题：与任务卡 title 同源同逻辑（buildChainTitle），保证 KB 可检索。 */
@@ -126,9 +208,16 @@ export function formatChecklistBody(c) {
     if (repo.branch)
         lines.push('- 当前分支: ' + repo.branch);
     lines.push('- 未提交改动: ' + (repo.dirtyFiles.length ? repo.dirtyFiles.map((f) => `\`${f}\``).join(', ') : '无'));
+    if (c.greenfield === true)
+        lines.push('- greenfield: true（全新项目，D 阶段 git init 建仓前置）');
     lines.push('', '### 文件基线', '', '| 路径 | 期望 | 备注 |', '| --- | --- | --- |');
     for (const f of files)
         lines.push(`| ${f.path} | ${f.expected} | ${f.note ?? '-'} |`);
+    lines.push('## 需求来源', '');
+    for (const s of c.sources) {
+        lines.push(`- [${s.type}] ${s.url || '(无来源)'}${s.note ? ` — ${s.note}` : ''}`);
+    }
+    lines.push('');
     lines.push('', '## 澄清问答', '');
     clarifications.forEach((qa, i) => {
         lines.push(`### Q${i + 1}. ${qa.q}`, `- **A**: ${qa.a}`, '');
@@ -151,5 +240,113 @@ export function formatChecklistBody(c) {
     }
     if (doubts.length === 0)
         lines.push('（无）');
+    lines.push('', '## PRD 采集记录', '');
+    const prd = c.prdCollection ?? [];
+    if (prd.length === 0) {
+        lines.push('（用户未提供 PRD 链接）');
+    }
+    else {
+        for (const p of prd) {
+            lines.push(`- ${p.url} — ${p.status}${p.platform ? `（${p.platform}）` : ''}${p.degraded ? ' — degraded（截图超限或写入失败，已降级为文字描述）' : ''}`);
+            lines.push(`  - 摘要: ${p.summary}`);
+            if (p.status === 'blocked' && p.blockedReason)
+                lines.push(`  - 阻塞原因: ${p.blockedReason}`);
+            for (const pg of p.pages ?? [])
+                lines.push(`  - 原文页: ${pg}`);
+        }
+    }
+    lines.push('', '## 占位策略', '');
+    const phs = c.placeholders ?? [];
+    if (phs.length === 0) {
+        lines.push('（无后端未就绪项）');
+    }
+    else {
+        lines.push('| 占位对象 | 占位值 | 替换方式 |', '| --- | --- | --- |');
+        for (const p of phs)
+            lines.push(`| ${p.target} | ${p.value} | ${p.replace} |`);
+    }
+    // 机读段（2026-09-21 恢复流程矫正）：页正文是人读 markdown（有损），重启恢复若让 LLM 读页重建
+    // 再回存 = 有损再创作 + 双重编码风险（销服一体清单 7 轮失败即发生在恢复场景）。页尾内嵌无损
+    // JSON 单行段，/openspec: 路由2 直接提取灌内存建链，LLM 零参与；HTML 注释对人读零干扰。
+    const machine = JSON.stringify({ requirementName: c.requirementName ?? null, spec: c.spec, manifest: c.manifest, clarifications: c.clarifications, doubts: c.doubts, risks: c.risks ?? [], sources: c.sources, prdCollection: c.prdCollection ?? [], placeholders: c.placeholders ?? [], greenfield: c.greenfield ?? false });
+    lines.push('', `<!-- dsh-swarm:checklist-json ${machine} -->`);
     return lines.join('\n').replace(/\n{3,}/g, '\n\n');
 }
+const CHECKLIST_JSON_MARK = '<!-- dsh-swarm:checklist-json ';
+/** 从清单页原文提取机读 PlanningChecklist（无损恢复路径）：无段/损坏/校验不过一律返回 null，
+ *  由调用方回退 legacy LLM 重建流程。domain 纯函数，无副作用。 */
+export function extractChecklistJson(pageMd) {
+    const start = pageMd.indexOf(CHECKLIST_JSON_MARK);
+    if (start < 0)
+        return null;
+    const jsonStart = start + CHECKLIST_JSON_MARK.length;
+    const end = pageMd.indexOf('-->', jsonStart);
+    if (end < 0)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(pageMd.slice(jsonStart, end).trim());
+    }
+    catch {
+        return null;
+    }
+    if (validatePlanningChecklist(raw).length > 0)
+        return null;
+    return raw;
+}
+/** PRD 链接域名路由：已知平台直接判定，其余返回 null 交 LLM 自判。 */
+export function routePrdPlatform(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    if (host === 'feishu.cn' || host.endsWith('.feishu.cn'))
+        return 'feishu';
+    if (host === 'doc.weixin.qq.com')
+        return 'wecom';
+    if (host === 'modao.cc' || host.endsWith('.modao.cc'))
+        return 'modao';
+    return null;
+}
+/** PRD 原文切片：优先按一级标题（# 开头）切章，单片超 maxBytes 按行硬切。
+ *  默认 45KB/片（wiki 大文档拆页惯例，低于服务端 body 上限留余量）。 */
+export function slicePrdMarkdown(md, maxBytes = 45_000) {
+    const chapters = [];
+    let cur = [];
+    for (const line of md.split('\n')) {
+        if (/^#\s/.test(line) && cur.length > 0) {
+            chapters.push(cur.join('\n'));
+            cur = [line];
+        }
+        else {
+            cur.push(line);
+        }
+    }
+    if (cur.length > 0)
+        chapters.push(cur.join('\n'));
+    const parts = [];
+    for (const ch of chapters) {
+        if (Buffer.byteLength(ch, 'utf8') <= maxBytes) {
+            parts.push(ch);
+            continue;
+        }
+        let buf = [];
+        let size = 0;
+        for (const line of ch.split('\n')) {
+            const lb = Buffer.byteLength(line + '\n', 'utf8');
+            if (size + lb > maxBytes && buf.length > 0) {
+                parts.push(buf.join('\n'));
+                buf = [];
+                size = 0;
+            }
+            buf.push(line);
+            size += lb;
+        }
+        if (buf.length > 0)
+            parts.push(buf.join('\n'));
+    }
+    return parts.length > 0 ? parts : [''];
+}

package/lib/domain/prefetch-manifest.js

@@ -52,22 +52,33 @@ export function validatePrefetchManifest(raw) {
         errors.push('manifest.files must be an array');
     }
     else {
+        // files[] 逐条错误先收集再聚合（2026-09-21：26 条同文错误墙稀释有效信息，模型只见截断前几条）。
+        // 完全相同的消息合并为 "<msg> ×N"，不同消息保持原样与原序。
+        const fileErrors = [];
         for (const f of m['files']) {
             if (typeof f !== 'object' || f === null) {
-                errors.push('manifest.files entry must be an object');
+                fileErrors.push('manifest.files entry must be an object');
                 continue;
             }
             const e = f;
             if (typeof e['path'] !== 'string' || e['path'].trim().length === 0) {
-                errors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
+                fileErrors.push(`manifest.files[].path (got: ${JSON.stringify(e['path'])})`);
             }
             if (typeof e['expected'] !== 'string' || !EXPECTED_VALUES.has(e['expected'])) {
-                errors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
+                fileErrors.push(`manifest.files[].expected (got: ${JSON.stringify(e['expected'])})`);
             }
             if (e['expected'] === 'content-hash' && (typeof e['note'] !== 'string' || e['note'].trim().length === 0)) {
-                errors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
+                fileErrors.push(`manifest.files[].note required for content-hash (got: ${JSON.stringify(e['note'])})`);
             }
         }
+        errors.push(...tallyIdentical(fileErrors));
     }
     return errors;
 }
+/** 相同消息聚合计数：["a","a","b"] → ["a ×2","b"]。domain 纯函数，无副作用。 */
+function tallyIdentical(messages) {
+    const counts = new Map();
+    for (const msg of messages)
+        counts.set(msg, (counts.get(msg) ?? 0) + 1);
+    return [...counts.entries()].map(([msg, n]) => (n > 1 ? `${msg} ×${n}` : msg));
+}

package/lib/roles/preset-installer.d.ts

@@ -6,3 +6,17 @@ export declare function userPresetsRoot(): string;
  *  尽力而为：单 preset 写失败（用户预设根不可写等）仅告警不抛出，
  *  后续 agentPresets.mount('kanban-<role>') 失败由 runner 降级日志兜底。 */
 export declare function installRolePresets(): string[];
+/** 角色 preset 挂载的容器面（dsh-agent-presets roster 的最小结构类型）。 */
+export interface PresetMountLike {
+    mount(ctx: unknown, id: string): Promise<unknown>;
+    /** 官方重链入口（0.1.2-rc.1 起提供）：已绑定 → binding.rebind；未绑定 → bind。 */
+    recompose?(ctx: unknown, id: string): Promise<unknown>;
+}
+/**
+ * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程
+ * 生命周期内一次性（bindScopeParent 重复调用抛 "already bound to a parent"），官方重链
+ * 入口是 recompose（已绑 → binding.rebind）。同 agentKey 的二次 setup（P/W/D 卡 blocked/
+ * unblock 多轮唤醒 resume 同一 session、live 复用 re-setup 补挂）此前直接二次 mount 必炸。
+ * 收敛语义：mount 失败且系 already-bound → recompose 重链；其余错误（组合不可用等）原样上抛。
+ */
+export declare function mountOrRecompose(presets: PresetMountLike, agentCtx: unknown, presetId: string): Promise<void>;

package/lib/roles/preset-installer.js

@@ -51,3 +51,20 @@ export function installRolePresets() {
     }
     return installed;
 }
+/**
+ * preset 挂载收敛入口（2026-09-21 事故修复）：宿主 dsh-scope 的 scope key 绑定在进程
+ * 生命周期内一次性（bindScopeParent 重复调用抛 "already bound to a parent"），官方重链
+ * 入口是 recompose（已绑 → binding.rebind）。同 agentKey 的二次 setup（P/W/D 卡 blocked/
+ * unblock 多轮唤醒 resume 同一 session、live 复用 re-setup 补挂）此前直接二次 mount 必炸。
+ * 收敛语义：mount 失败且系 already-bound → recompose 重链；其余错误（组合不可用等）原样上抛。
+ */
+export async function mountOrRecompose(presets, agentCtx, presetId) {
+    try {
+        await presets.mount(agentCtx, presetId);
+    }
+    catch (err) {
+        if (!String(err).includes('already bound to a parent') || typeof presets.recompose !== 'function')
+            throw err;
+        await presets.recompose(agentCtx, presetId);
+    }
+}

package/lib/roles/toolsets.d.ts

@@ -110,7 +110,7 @@ export declare function buildSwarmSessionGuard(deps?: SubagentGuardDeps): (execu
 /** wiki_write 会话级放行 preset 默认白名单：与 config.ts wikiWritePresets 默认值同源，
  *  仅供 guard deps 未接线（测试/裸调用）时兜底；生产经 dispatcher 注入热读配置。
  *  'ptc'：普通（PTC 模式）会话亦可写 wiki 命名空间——写面本身由 wiki_write 工具内的
- *  五类命名空间白名单硬约束；2026-09-17 起 preset 判定走统一读面（session-preset.ts），
+ *  六类命名空间白名单硬约束；2026-09-17 起 preset 判定走统一读面（session-preset.ts），
  *  'ptc' 不再是「蜂群会话被误读成 ptc」的兜底，而是显式放行普通会话。 */
 export declare const DEFAULT_WIKI_WRITE_PRESETS: ReadonlyArray<string>;
 export interface StandaloneDtGuardDeps {

package/lib/roles/toolsets.js

@@ -405,8 +405,10 @@ export async function installRoleTools(agentCtx, role, deps) {
                     registry.register(tool);
             }
         }
-        // ocr_review：ocr CLI 三子命令（preview/rule/managed）；未安装/托管未配置在 execute 内降级引导，注册无条件
-        registry.register(buildOcrReviewTool({ cwd: () => process.cwd() }));
+        // ocr_review：ocr CLI 三子命令（preview/rule/managed）；未安装/托管未配置在 execute 内降级引导，注册无条件。
+        // 目标仓库由 execute 内解析（repo 参数 → exec.agent.session.header.cwd）——不注入 cwd，
+        // 避免回退到插件进程目录（非仓库，ocr 必报 not a git repository）。
+        registry.register(buildOcrReviewTool({}));
     }
     else if (role === 'v') {
         for (const tool of buildSpecCardTools(deps.kanban, caller)) {
@@ -595,7 +597,7 @@ function dualVerbGitDenyReason(verb, rest, deny) {
 /** wiki_write 会话级放行 preset 默认白名单：与 config.ts wikiWritePresets 默认值同源，
  *  仅供 guard deps 未接线（测试/裸调用）时兜底；生产经 dispatcher 注入热读配置。
  *  'ptc'：普通（PTC 模式）会话亦可写 wiki 命名空间——写面本身由 wiki_write 工具内的
- *  五类命名空间白名单硬约束；2026-09-17 起 preset 判定走统一读面（session-preset.ts），
+ *  六类命名空间白名单硬约束；2026-09-17 起 preset 判定走统一读面（session-preset.ts），
  *  'ptc' 不再是「蜂群会话被误读成 ptc」的兜底，而是显式放行普通会话。 */
 export const DEFAULT_WIKI_WRITE_PRESETS = ['swarm', 'kanban-w', 'ptc'];
 export function buildStandaloneDtGuard(deps = {}) {
@@ -665,7 +667,7 @@ export function buildStandaloneDtGuard(deps = {}) {
             if (isRoleComposed(execution?.agent) || isDtChainSubagent)
                 return undefined;
             // 放宽（2026-09-16）：swarm 主会话与 W preset 会话可写 wiki——can('wiki-write') 本就含 w
-            // （permissions.ts），写面由 wiki_write 工具内 assertAllowedWikiPagePath 五类命名空间
+            // （permissions.ts），写面由 wiki_write 工具内 assertAllowedWikiPagePath 六类命名空间
             // 白名单硬约束；local 模式 wiki_write 未全局注册，无工具面即无暴露面。
             // 放行面配置化（硬规则 6）：白名单经 deps 热读 config.wikiWritePresets，宿主 preset
             // 体系演化/部署自定义模式 id 时改配置即可；config 缺字段回 []（fail-closed，仅内置默认兜底测试）。
@@ -694,7 +696,7 @@ export function registerStandaloneReviewerTools(ctx, configProvider) {
     const registry = ctx.get('tools');
     if (!registry)
         return; // 测试裸 Context 无 tools 服务，跳过注册
-    registry.register(buildOcrReviewTool({ cwd: () => process.cwd() }));
+    registry.register(buildOcrReviewTool({})); // 目标仓库同链上路径：repo 参数 → 会话工作目录（见 ocr-review-tools）
     const kbMode = configProvider.mode;
     const wiki = (kbMode === 'local'
         ? new LocalWikiClient(ensureLocalKbRoot())

package/lib/routes/planning-driver.d.ts

@@ -3,7 +3,8 @@ import type { SpecCard, SpecCardAttachment } from '../domain/types.js';
 import { type PrefixRoutes } from '../config.js';
 /** 阶段 0 规划引导：命令串从 config 派生，/openspec: 改名时文案自动跟随。
  *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
- *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
+ *  需求澄清十规则：来源必挂 + PRD 采集 + 范围边界 + 人话 + 仓库事实/缺口暂停 + 收敛录入铁律（含决策可追溯）；
+ *  收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
 export declare function buildPlanningGuidance(routes: PrefixRoutes, opts?: {
     swarm?: boolean;
 }): string;

package/lib/routes/planning-driver.js

@@ -3,19 +3,22 @@ import { parsePrefix } from './prefix-router.js';
 import { DEFAULT_PREFIX_ROUTES } from '../config.js';
 /** 阶段 0 规划引导：命令串从 config 派生，/openspec: 改名时文案自动跟随。
  *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
- *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
+ *  需求澄清十规则：来源必挂 + PRD 采集 + 范围边界 + 人话 + 仓库事实/缺口暂停 + 收敛录入铁律（含决策可追溯）；
+ *  收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
 export function buildPlanningGuidance(routes, opts) {
-    // 第 6 条按形态分叉：前缀 = 教学旧命令收尾（逐字节不变）；swarm = 确认闸语义（不提旧命令，与 KANBAN_HANDOFF_RULE swarm 确认闸对齐）。
+    // 第 8 条按形态分叉：前缀 = 教学旧命令收尾（收尾句不变）；swarm = 确认闸语义（不提旧命令，与 KANBAN_HANDOFF_RULE swarm 确认闸对齐）。
     const finish = opts?.swarm
-        ? `6. 收尾（确认闸）：清单落库后向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链开跑；模糊回复视为未确认，继续澄清。`
-        : `6. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。`;
+        ? `8. 收尾（确认闸）：清单落库后向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链开跑；模糊回复视为未确认，继续澄清。`
+        : `8. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。`;
     return `
-# 阶段 0 规划对话（v4：grill-me frontier 分轮，与 skills/grill-me 对齐）
-1. 需求澄清（grill-me，frontier 分轮）：把计划映射为设计决策树——每轮只问当前前提已就绪的问题（frontier），整批问出：编号 + 每问附推荐答案；等用户全部答复后重算 frontier（已定决定向外推进、解锁依赖它的问题）再发下一轮，本轮答不了的依赖问题留到后续轮。先澄清目的、约束、成功标准，逐支拷问直至用户"没有任何疑问"。
-2. 人话硬规则：问题正文与选项必须通俗；术语避不开时首次出现括号一句话解释；发问前自检「不懂本仓库的人能直接回答吗」，不能就重写。
-3. 仓库事实（planning_prefetch）：事实自查是规划者的职责——调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设、不拿可自查的问题问用户；只把真正的决定留给用户。
-4. 风险登记：每轮答复中若发现真实风险或非阻塞关注点，随手记一行（描述 + 来源决定 + 缓解思路），收敛时并入澄清清单；没有就不写，禁止硬凑。
-5. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点 + 风险点（若有））存入 KB（KB 不可达自动兜底临时目录）。
+# 阶段 0 规划对话（v5：grill-me frontier 分轮 + 需求澄清十规则）
+1. 需求来源必挂：起手记录需求来源（TAPD/Jira/其他链接）；确无来源也要显式记录「无来源+原因」，不许空。同时判定是否绿地（目标目录不存在或尚无 .git）：是 → 清单声明 greenfield:true（D 阶段将 git init 建仓），否则不声明。
+2. PRD 链接必采集：用户给了 PRD/需求文档链接，必须先调 planning_prd_collect 逐条采集（一条链接一次调用，多条可并行），采集完成前不得进入 grill-me 提问。采集失败（blocked）立即停下，把工具返回的 guidance 按类转告用户：登录态→请用户自行登录后重采；缺技能→引导安装（带登录态浏览器 huashu-chrome / CDP 兜底 web-access / 企微 wecom-docs / 飞书 lark）；404→请用户提供有效链接。用户解决后继续未完成的采集。禁止盲猜页面内容、禁止跳过、禁止自行探索浪费时间。
+3. 范围边界：起手明确「范围内/范围外」清单，尤其需求文档中标注多但用户未点名的部分，逐条确认纳入与否。
+4. 需求澄清（grill-me，frontier 分轮）：把计划映射为设计决策树——每轮只问当前前提已就绪的问题（frontier），整批问出：编号 + 每问附推荐答案；等用户全部答复后重算 frontier 再发下一轮。先澄清目的、约束、成功标准，逐支拷问直至用户"没有任何疑问"。
+5. 人话硬规则：问题正文与选项必须通俗；术语避不开时首次出现括号一句话解释；发问前自检「不懂本仓库的人能直接回答吗」，不能就重写。
+6. 仓库事实（planning_prefetch）与缺口暂停：事实自查是规划者的职责——涉筛选字段/列表字段/取数 hook/组件选型，先调只读子代理查证仓库（存在/可复用/复用+转化），推荐答案言出有据，不拿可自查的问题问用户；澄清中发现信息缺口 → 停止提问 → 先调 planning_prefetch 补齐 → 再继续，不边猜边问。每功能点先查仓库同类实现，可复用优先复用。
+7. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单存入 KB（KB 不可达自动兜底临时目录）。录入铁律：每条问答含完整决策正文（字段名/接口路径/枚举值/组件名/位置规则），禁止「按推荐」「同上」等指代不明缩写（代码硬闸会拒收）；sources（需求来源）/ prdCollection（每条 PRD 链接的采集状态）必填；后端未就绪项统一登记 placeholders（占位对象/占位值/替换方式），集中声明避免逐点重复讨论。每条决策可追溯（问答编号/仓库源码路径/接口文档位置至少其一）；原始文档值与确认决策冲突处必须标【已调整】/【已确认】，未确认值不录或显式标「待确认」——无来源记录的决策会被视为 agent 自行默认。
 ${finish}
 护栏：规划期只读仓库，禁止任何 git/源码写入；只写 KB 与临时目录。
 `;

package/lib/services/ocr-cli.d.ts

@@ -23,6 +23,11 @@ export declare function runOcr(args: string[], opts: {
     stderr: string;
     error?: string;
 }>;
+/** 托管就绪探测：provider 为 dsh-managed 且模型非空。
+ * 踩坑：`ocr config set model <m>` 的落盘位置随当前 provider 类型分流——内置 provider 写顶层
+ * `model`，自定义 provider（本插件的 dsh-managed）写 `custom_providers.dsh-managed.model`
+ * （沙箱 HOME 实测）。只读顶层 model 会把已接好的托管配置判成未就绪，工具层随即返回
+ * 「托管模式未配置 LLM」而永不真正调用 `ocr review`（两处都算就绪）。 */
 export declare function managedProviderReady(deps?: OcrCliDeps): boolean;
 export declare function wireManagedProvider(a: {
     baseUrl: string;

package/lib/services/ocr-cli.js

@@ -99,11 +99,20 @@ export async function runOcr(args, opts, deps = {}) {
         };
     }
 }
+/** 托管就绪探测：provider 为 dsh-managed 且模型非空。
+ * 踩坑：`ocr config set model <m>` 的落盘位置随当前 provider 类型分流——内置 provider 写顶层
+ * `model`，自定义 provider（本插件的 dsh-managed）写 `custom_providers.dsh-managed.model`
+ * （沙箱 HOME 实测）。只读顶层 model 会把已接好的托管配置判成未就绪，工具层随即返回
+ * 「托管模式未配置 LLM」而永不真正调用 `ocr review`（两处都算就绪）。 */
 export function managedProviderReady(deps = {}) {
     try {
         const home = deps.homedirFn ? deps.homedirFn() : homedir();
         const cfg = JSON.parse(readFileSync(join(home, '.opencodereview', 'config.json'), 'utf8'));
-        return cfg.provider === OCR_MANAGED_PROVIDER_NAME && typeof cfg.model === 'string' && cfg.model.length > 0;
+        if (cfg.provider !== OCR_MANAGED_PROVIDER_NAME)
+            return false;
+        const top = typeof cfg.model === 'string' ? cfg.model : '';
+        const nested = cfg.custom_providers?.[OCR_MANAGED_PROVIDER_NAME]?.model;
+        return (top || (typeof nested === 'string' ? nested : '')).length > 0;
     }
     catch {
         return false; // 文件不存在/解析失败/字段缺失一律视为未就绪

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;
@@ -33,6 +33,7 @@ export declare function buildOpenspecNarrationRule(r: {
     };
 }): string;
 export declare function buildSpawnPrefetch(ctx: Context): PlanningToolDeps['spawnPrefetch'] | undefined;
+export declare function buildSpawnPrdCollect(ctx: Context, listSkills?: () => string[]): PlanningToolDeps['spawnPrdCollect'] | undefined;
 /** v2 主会话工具面：/plan: 捕获规划上下文（零副作用）→ planning_checklist_save 回写 → /openspec: 建链。
  *  工具面 = kanban_route + 只读 kanban 子集 + spec_card_view + planning 工具；
  *  无 spec_card_edit/approve、无 kanban_create/complete/block（主会话越权写由工具面裁剪 + prefetch 子代理只读护栏双保险）。 */