@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/lib/roles/wiki-worker.d.ts

@@ -8,6 +8,7 @@ export declare class WikiWorker {
     private readonly cfg;
     constructor(kanban: KanbanService, wiki: WikiVaultClient, cfg: {
         pagePrefix: string;
+        kbMode?: 'remote' | 'local';
     });
     executePrefetch(task: Task, mode: 'file' | 'external' | 'kb', source: string): Promise<{
         ref: string;

package/lib/roles/wiki-worker.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { buildRepoSlug } from '../domain/memory.js';
 function workspaceOf(chainId, taskId) {
     return join(process.env.DSH_HOME ?? process.cwd(), 'storages', 'kanban', 'workspaces', chainId, taskId);
 }
@@ -11,7 +12,7 @@ export class WikiWorker {
     constructor(kanban, wiki, cfg) { this.kanban = kanban; this.wiki = wiki; this.cfg = cfg; }
     async executePrefetch(task, mode, source) {
         const ws = workspaceOf(task.chainId, task.id);
-        // P1-6：三模式全部落地；产物一律写入任务工作区（原汁原味，禁压缩/蒸馏）
+        // 三模式全部落地；产物一律写入任务工作区（原汁原味，禁压缩/蒸馏）
         if (mode === 'file') {
             // 只读命令由角色 agent 的 terminal 白名单执行；此处仅登记产物引用
             if (!source.startsWith(ws))
@@ -26,19 +27,26 @@ export class WikiWorker {
                 throw new Error('prefetch source outside workspace: ' + source);
             return { ref: source || ref };
         }
-        // kb 模式：知识库查询产物（wiki-vault search/read 由 wiki 工具执行，agent 落盘 ws/prefetch-kb.md）
+        // kb 模式：知识库查询产物。local 模式不走 wiki 工具——明确指引改用 skill 加载 llm-wiki。
+        if (this.cfg.kbMode === 'local') {
+            throw new Error('prefetch_kb unavailable in local KB mode: use the skill tool to load llm-wiki for KB search instead');
+        }
+        // remote：知识库查询产物（wiki-vault search/read 由 wiki 工具执行，agent 落盘 ws/prefetch-kb.md）
         const ref = join(ws, 'prefetch-kb.md');
         if (!source.startsWith(ws) && source !== '')
             throw new Error('prefetch source outside workspace: ' + source);
         return { ref: source || ref };
     }
     async syncToWiki(task, sourceRef) {
+        const chain = (await this.kanban.snapshot()).chains.get(task.chainId);
+        if (!chain?.workspaceDir)
+            throw new Error('syncToWiki requires chain.workspaceDir: ' + task.chainId);
         const content = readFileSync(sourceRef, 'utf8'); // 原汁原味：不压缩不蒸馏
-        const pagePath = this.cfg.pagePrefix + task.chainId + '/' + task.id + '.md';
+        const pagePath = `${this.cfg.pagePrefix}${buildRepoSlug(chain.workspaceDir)}/${task.chainId}/${task.id}.md`;
         await this.wiki.write(pagePath, content);
         return { kb_url: this.wikiBase() + '/#/page/' + pagePath, page_path: pagePath };
     }
     wikiBase() {
-        return this.wiki.baseUrl; // P2：用 WikiVaultClient 公开 getter，不做类型强转
+        return this.wiki.baseUrl; // 用 WikiVaultClient 公开 getter，不做类型强转
     }
 }

package/lib/routes/kanban-http.d.ts

@@ -1,6 +1,32 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { KanbanConfig } from '../config.js';
 import type { KanbanProvider } from '../services/kanban-provider.js';
-/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作。
+import type { ConfigProvider } from '../services/config-provider.js';
+import type { LlmRuntimeLike } from '../services/llm-catalog.js';
+import { managedProviderReady, probeOcr } from '../services/ocr-cli.js';
+/** ocr 全局安装器：回调式 npm install -g，onSpawn 转交子进程句柄供取消。 */
+export type OcrInstaller = (onSpawn?: (child: {
+    kill(sig?: string): boolean;
+}) => void) => Promise<{
+    ok: boolean;
+    version?: string;
+    log: string;
+}>;
+/** ocr HTTP 分支可注入依赖（测试用）；缺省走真实现。 */
+export interface KanbanOcrDeps {
+    installer?: OcrInstaller;
+    probeFn?: typeof probeOcr;
+    managedReadyFn?: typeof managedProviderReady;
+    wirer?: (a: {
+        provider: string;
+        model: string;
+    }) => Promise<{
+        ok: boolean;
+        log: string;
+    }>;
+}
+/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作；
+ *  GET/PUT /kanban/config 配置读写（无 reset：各用户模型配置不同，无公共默认值）；GET /kanban/llm-catalog 模型目录；
+ *  GET /kanban/ocr/status + POST /kanban/ocr/install(/cancel) + GET install/state + POST /kanban/ocr/wire ocr 评审引擎运维。
  *  仅在 webServer 服务存在时挂载（CLI/headless/测试裸 Context 不挂）。 */
-export declare function registerKanbanHttp(ctx: Context, provider: KanbanProvider, config?: Pick<KanbanConfig, 'ui'>): void;
+export declare function registerKanbanHttp(ctx: Context, provider: KanbanProvider, configProvider: ConfigProvider, llm: LlmRuntimeLike, config?: Pick<KanbanConfig, 'ui'>, ocrDeps?: KanbanOcrDeps): void;

package/lib/routes/kanban-http.js

@@ -1,3 +1,8 @@
+import { execFile } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildLlmCatalog } from '../services/llm-catalog.js';
+import { INSTALL_GUIDANCE, OCR_PACKAGE, managedProviderReady, probeOcr, wireManagedProvider } from '../services/ocr-cli.js';
 import { serveKanbanEvents } from './kanban-sse.js';
 function json(res, status, body) {
     res.statusCode = status;
@@ -12,9 +17,95 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
-/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作。
+const defaultOcrInstaller = (onSpawn) => new Promise((resolve) => {
+    const child = execFile('npm', ['install', '-g', OCR_PACKAGE], { timeout: 600_000 }, (err, stdout, stderr) => {
+        if (err)
+            resolve({ ok: false, log: `${err.message}\n${String(stderr ?? '')}`.trim() });
+        else
+            resolve({ ok: true, log: String(stdout ?? '') });
+    });
+    onSpawn?.(child);
+});
+/** 模块级单飞安装任务态：同一插件进程同时只允许一个 npm 全局安装在跑。 */
+let installJob = null;
+/** 安装关键事件落盘（与 dispatcher.log 同文件同格式，写失败静默——日志只是观测面）。 */
+function logOcrEvent(configProvider, msg) {
+    try {
+        const storageDir = configProvider.getEffective().storageDir.replace('$DSH_HOME', process.env.DSH_HOME ?? process.cwd());
+        writeFileSync(join(storageDir, 'dispatcher.log'), new Date().toISOString() + ' ' + msg + '\n', { flag: 'a' });
+    }
+    catch { /* 忽略写失败 */ }
+}
+async function runOcrInstall(deps, configProvider) {
+    const job = installJob;
+    if (!job)
+        return;
+    try {
+        const r = await (deps?.installer ?? defaultOcrInstaller)((child) => { job.child = child; });
+        if (!job.running)
+            return; // 已取消：cancelled 是终态，迟到的安装结果不覆盖
+        job.running = false;
+        job.log = r.log;
+        if (r.ok) {
+            job.result = 'ok';
+            const probe = await (deps?.probeFn ?? probeOcr)();
+            job.version = probe.version;
+            logOcrEvent(configProvider, '[ocr-install] ok' + (probe.version ? ' version=' + probe.version : ''));
+        }
+        else {
+            job.result = 'failed';
+            logOcrEvent(configProvider, '[ocr-install] failed');
+        }
+    }
+    catch (err) {
+        if (!job.running)
+            return;
+        job.running = false;
+        job.result = 'failed';
+        job.log = String(err);
+        logOcrEvent(configProvider, '[ocr-install] failed: ' + String(err));
+    }
+}
+/** wire 降级文案：解析不到该提供方接入信息时，引导终端手动配置（不写半套 ocr 配置）。 */
+const OCR_WIRE_DEGRADED = '未能从 dsh 解析该提供方的接入信息（baseUrl/apiKey）——请在终端手动执行 ocr config provider 完成托管配置；委托模式不受影响';
+/**
+ * 从宿主设置解析所选提供方的接入信息（baseUrl/协议/apiKey）。
+ * 事实核查结论（实现期探查）：llm 服务的公开 API 不暴露连接事实，但同进程可经
+ * settings 服务的 describe() 读到模型适配器的 provider profile——形如
+ * { providers: { <id>: { baseURL, api, apiKey | apiKeyEnv } } }（apiKeyEnv 指向进程环境变量名）。
+ * 命中 profile 但字段不全时跳过该 descriptor 继续尝试下一个（多 descriptor 场景勿误降级），
+ * 绝不回传半套配置；全部不合才返回 null 走降级。apiKey 只透传给 ocr config，不落日志。
+ */
+function resolveDshProviderAccess(ctx, providerId) {
+    try {
+        const settings = ctx.get('settings');
+        const descriptors = settings?.describe?.() ?? [];
+        for (const d of descriptors) {
+            const providers = d.value?.providers;
+            const profile = providers?.[providerId];
+            if (!profile || typeof profile !== 'object')
+                continue;
+            const baseUrl = typeof profile.baseURL === 'string' ? profile.baseURL : '';
+            const api = typeof profile.api === 'string' ? profile.api : '';
+            const protocol = api.startsWith('openai') ? 'openai' : api.includes('anthropic') ? 'anthropic' : '';
+            let apiKey = typeof profile.apiKey === 'string' ? profile.apiKey : '';
+            if (!apiKey && typeof profile.apiKeyEnv === 'string')
+                apiKey = process.env[profile.apiKeyEnv] ?? '';
+            if (baseUrl && protocol && apiKey)
+                return { baseUrl, protocol, apiKey };
+            continue; // 字段不全：换下一个 descriptor，勿在此误降级
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 看板 HTTP 桥（Web GUI 浏览器半消费）：GET /kanban/board 读快照；POST /kanban/action 执行状态操作；
+ *  GET/PUT /kanban/config 配置读写（无 reset：各用户模型配置不同，无公共默认值）；GET /kanban/llm-catalog 模型目录；
+ *  GET /kanban/ocr/status + POST /kanban/ocr/install(/cancel) + GET install/state + POST /kanban/ocr/wire ocr 评审引擎运维。
  *  仅在 webServer 服务存在时挂载（CLI/headless/测试裸 Context 不挂）。 */
-export function registerKanbanHttp(ctx, provider, config) {
+export function registerKanbanHttp(ctx, provider, configProvider, llm, config, ocrDeps) {
     // 可选服务：经 ctx.get 读取（cordis 4 直接属性读取需 inject；get 不需要）
     const webServer = ctx.get('webServer');
     if (!webServer)
@@ -44,7 +135,7 @@ export function registerKanbanHttp(ctx, provider, config) {
                 }
                 if (req.method === 'POST' && req.url?.startsWith('/kanban/action')) {
                     const body = JSON.parse((await readBody(req)) || '{}');
-                    // D23：confirm-audit 是链级 action（无 taskId），提前分流处理
+                    // confirm-audit 是链级 action（无 taskId），提前分流处理
                     if (body.type === 'confirm-audit') {
                         const chainId = String(body.chainId ?? '').trim();
                         if (!chainId) {
@@ -55,7 +146,8 @@ export function registerKanbanHttp(ctx, provider, config) {
                         json(res, 200, { ok: true });
                         return;
                     }
-                    // 整链硬删除（仅 human；GUI 二次确认）：purge 无事件流，客户端需自行 resync
+                    // 整链硬删除（仅 human；GUI 二次确认）：purge 无事件流，客户端需自行 resync。
+                    // E/F：删链后联动 dispatcher（游标同步钳回）+ V 编排 entry 清理，防运行中实例跳过后续新链事件。
                     if (body.type === 'delete') {
                         const chainId = String(body.chainId ?? '').trim();
                         if (!chainId) {
@@ -63,10 +155,12 @@ export function registerKanbanHttp(ctx, provider, config) {
                             return;
                         }
                         await provider.service.deleteChain(chainId, 'human');
+                        if (provider.onChainDeleted)
+                            await provider.onChainDeleted(chainId);
                         json(res, 200, { ok: true });
                         return;
                     }
-                    // T7：rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
+                    // rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
                     if (body.type === 'rename') {
                         const title = String(body.title ?? '').trim();
                         if (!title) {
@@ -103,7 +197,7 @@ export function registerKanbanHttp(ctx, provider, config) {
                             await provider.service.unblockTask(t, 'human');
                             break;
                         case 'retry': {
-                            // T32 fix：retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
+                            // retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
                             const state = await provider.service.snapshot();
                             const task = state.tasks.get(t);
                             if (!task) {
@@ -149,6 +243,105 @@ export function registerKanbanHttp(ctx, provider, config) {
                     json(res, 200, { ok: true });
                     return;
                 }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/config')) {
+                    json(res, 200, configProvider.snapshot());
+                    return;
+                }
+                if (req.method === 'PUT' && req.url?.startsWith('/kanban/config')) {
+                    const raw = JSON.parse((await readBody(req)) || '{}');
+                    // 归一化缺省字段，保证缺字段走 400 校验失败而非 500。
+                    // reviewEngine 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带该字段时保存不清空既有评审引擎配置。
+                    const fb = configProvider.getEffective().reviewEngine;
+                    const snapshot = {
+                        wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
+                        roles: { models: raw.roles?.models ?? {} },
+                        reviewEngine: {
+                            mode: raw.reviewEngine?.mode ?? fb?.mode ?? 'delegate',
+                            managed: {
+                                provider: raw.reviewEngine?.managed?.provider ?? fb?.managed?.provider ?? '',
+                                model: raw.reviewEngine?.managed?.model ?? fb?.managed?.model ?? '',
+                            },
+                        },
+                    };
+                    const r = configProvider.applyOverride(snapshot);
+                    if (!r.ok) {
+                        json(res, 400, { error: 'validation failed', fields: r.errors });
+                        return;
+                    }
+                    json(res, 200, { ok: true, effective: r.effective, sources: r.sources });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/llm-catalog')) {
+                    json(res, 200, await buildLlmCatalog(llm));
+                    return;
+                }
+                // ocr 运维面：cancel 前置于 install（POST 前缀匹配防遮蔽），install/state 与 install 以 method 区分
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/ocr/install/cancel')) {
+                    if (!installJob?.running) {
+                        json(res, 200, { ok: false, error: 'no-install-running' });
+                        return;
+                    }
+                    installJob.child?.kill('SIGTERM');
+                    installJob.running = false;
+                    installJob.result = 'cancelled';
+                    logOcrEvent(configProvider, '[ocr-install] cancelled');
+                    json(res, 200, { ok: true });
+                    return;
+                }
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/ocr/install')) {
+                    if (installJob?.running) {
+                        json(res, 409, { error: 'install-in-progress' });
+                        return;
+                    }
+                    installJob = { id: 'ocr-install-' + Date.now(), running: true, child: null, log: '' };
+                    logOcrEvent(configProvider, '[ocr-install] start');
+                    void runOcrInstall(ocrDeps, configProvider);
+                    json(res, 200, { ok: true, id: installJob.id });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/ocr/install/state')) {
+                    json(res, 200, installJob
+                        ? { running: installJob.running, result: installJob.result, version: installJob.version, log: installJob.log }
+                        : { running: false, log: '' });
+                    return;
+                }
+                if (req.method === 'GET' && req.url?.startsWith('/kanban/ocr/status')) {
+                    const probe = await (ocrDeps?.probeFn ?? probeOcr)();
+                    json(res, 200, {
+                        installed: probe.installed,
+                        version: probe.version,
+                        mode: configProvider.getEffective().reviewEngine.mode,
+                        // kbMode 随状态端点透出：前端据此显示 local 模式下独立评审不落 wiki 的提示
+                        kbMode: configProvider.mode,
+                        managedReady: ocrDeps?.managedReadyFn ? ocrDeps.managedReadyFn() : managedProviderReady(),
+                    });
+                    return;
+                }
+                if (req.method === 'POST' && req.url?.startsWith('/kanban/ocr/wire')) {
+                    const body = JSON.parse((await readBody(req)) || '{}');
+                    const providerId = String(body.provider ?? '').trim();
+                    const model = String(body.model ?? '').trim();
+                    if (!providerId || !model) {
+                        json(res, 400, { error: 'provider and model required' });
+                        return;
+                    }
+                    const probe = await (ocrDeps?.probeFn ?? probeOcr)();
+                    if (!probe.installed) {
+                        json(res, 200, { ok: false, log: INSTALL_GUIDANCE });
+                        return;
+                    }
+                    const access = resolveDshProviderAccess(ctx, providerId);
+                    if (!access) {
+                        json(res, 200, { ok: false, log: OCR_WIRE_DEGRADED });
+                        return;
+                    }
+                    const r = ocrDeps?.wirer
+                        ? await ocrDeps.wirer({ provider: providerId, model })
+                        : await wireManagedProvider({ baseUrl: access.baseUrl, protocol: access.protocol, apiKey: access.apiKey, model });
+                    logOcrEvent(configProvider, '[ocr-wire] ' + (r.ok ? 'ok' : 'fail'));
+                    json(res, 200, { ok: r.ok, log: r.log });
+                    return;
+                }
                 json(res, 404, { error: 'not found' });
             }
             catch (err) {

package/lib/routes/kanban-sse.d.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { KanbanService } from '../domain/kanban-service.js';
 import type { KanbanEvent } from '../domain/types.js';
 export declare function writeSseEvent(res: ServerResponse, event: KanbanEvent): void;
-/** T23：SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
+/** SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
 export declare function serveKanbanEvents(req: IncomingMessage, res: ServerResponse, service: Pick<KanbanService, 'subscribe' | 'eventsSince'>, options: {
     heartbeatMs: number;
 }): Promise<void>;

package/lib/routes/kanban-sse.js

@@ -10,7 +10,7 @@ function lastSeen(req) {
     const header = Number(headerValue ?? -1);
     return Math.max(Number.isFinite(query) ? query : -1, Number.isFinite(header) ? header : -1);
 }
-/** T23：SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
+/** SSE 事件桥。先订阅并缓存 live 事件，再补发补偿事件，握手窗口不丢事件。 */
 export async function serveKanbanEvents(req, res, service, options) {
     res.statusCode = 200;
     res.setHeader('content-type', 'text/event-stream; charset=utf-8');

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

@@ -1,8 +1,12 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import type { SpecCard, SpecCardAttachment } from '../domain/types.js';
 import { type PrefixRoutes } from '../config.js';
-/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。 */
-export declare function buildPlanningGuidance(routes: PrefixRoutes): string;
+/** 阶段 0 规划引导：命令串从 config 派生，/openspec: 改名时文案自动跟随。
+ *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
+ *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
+export declare function buildPlanningGuidance(routes: PrefixRoutes, opts?: {
+    swarm?: boolean;
+}): string;
 export declare function validateSpecCardForApproval(card: SpecCard): string[];
 export declare function buildPlanningContext(chainId: string, card: SpecCard, attachments: SpecCardAttachment[], routes?: PrefixRoutes): string;
 export declare function approveIfReady(message: string, service: KanbanService, cfg: PrefixRoutes, chainId: string, specCardId: string): Promise<{

package/lib/routes/planning-driver.js

@@ -1,14 +1,22 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import { parsePrefix } from './prefix-router.js';
 import { DEFAULT_PREFIX_ROUTES } from '../config.js';
-/** 阶段 0 规划引导：命令串从 config 派生（决策12），/openspec: 改名时文案自动跟随。 */
-export function buildPlanningGuidance(routes) {
+/** 阶段 0 规划引导：命令串从 config 派生，/openspec: 改名时文案自动跟随。
+ *  提问节奏与 skills/grill-me/SKILL.md 对齐：官方 frontier 分轮制（整批问 + 推荐答案 + 答复后解锁下一轮）；
+ *  增强项：人话硬规则 + 过程风险登记；收敛产物仍为 planning_checklist_save（KB 清单是建链数据源）。 */
+export function buildPlanningGuidance(routes, opts) {
+    // 第 6 条按形态分叉：前缀 = 教学旧命令收尾（逐字节不变）；swarm = 确认闸语义（不提旧命令，与 KANBAN_HANDOFF_RULE swarm 确认闸对齐）。
+    const finish = opts?.swarm
+        ? `6. 收尾（确认闸）：清单落库后向用户征求确认；仅当用户回复含明确肯定语义（确认/开干/开跑/开始/go 等）才调 kanban_route{intent:'openspec'} 建链开跑；模糊回复视为未确认，继续澄清。`
+        : `6. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。`;
     return `
-# 阶段 0 规划对话（v2：需求澄清前置化）
-1. 需求澄清（grill-me）：一次只问一个问题，先澄清目的、约束、成功标准；逐项拷问假设直至用户"没有任何疑问"。
-2. 仓库事实（planning_prefetch）：调只读子代理采集目标仓库/资料/知识库事实（本地路径/分支/目标文件基线/既有实现），不凭空假设。
-3. 收敛（planning_checklist_save）：把结论写成结构化需求澄清清单（spec 六段 + manifest repo.files + 澄清问答 + 疑问点）存入 KB（KB 不可达自动兜底临时目录）。
-4. 收尾：提醒用户以 ${routes.openspec} 确认执行结束规划阶段——${routes.openspec} 会从清单建链并自动串行执行。
+# 阶段 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 不可达自动兜底临时目录）。
+${finish}
 护栏：规划期只读仓库，禁止任何 git/源码写入；只写 KB 与临时目录。
 `;
 }

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

@@ -1,14 +1,30 @@
 import { KanbanService } from '../domain/kanban-service.js';
 import type { PlanningChecklist } from '../domain/planning-checklist.js';
 import type { PrefixRoutes } from '../config.js';
+/** 防线D：/openspec: 建链后同步等待首张任务卡的最长时长与轮询间隔（fail-open：超时返回 pending，
+ *  由链级看门狗接管）。可变对象供测试注入短值（vitest 文件级隔离）。 */
+export declare const OPENSPEC_FIRST_CARD: {
+    timeoutMs: number;
+    pollIntervalMs: number;
+};
 export interface PrefixRouteResult {
-    kind: 'plan' | 'openspec' | 'learning' | 'none';
+    kind: 'plan' | 'openspec' | 'learning' | 'send' | 'none';
     chainId?: string;
     specCardId?: string;
     rest: string;
     brief?: string;
     guidance?: string;
     error?: string;
+    /** /openspec: 建链结果；false=被护栏拦截（reason 说明原因），未建任何链/卡。 */
+    approved?: boolean;
+    reason?: string;
+    /** 防线D：建链后同步等待的首卡结果。{taskId,status}=V 已建卡；{pending:true}=等待超时（fail-open，看门狗接管）。 */
+    firstCard?: {
+        taskId: string;
+        status: string;
+    } | {
+        pending: true;
+    };
 }
 export declare function parsePrefix(message: string, cfg: PrefixRoutes): PrefixRouteResult;
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
@@ -17,12 +33,12 @@ export interface OpenspecPlanningInput {
     workspaceDir: string | null;
     checklist: PlanningChecklist;
     checklistRef: string;
-    /** T7：/plan: rest 原始需求描述；null=无 /plan: 捕获（回退 checklist.problem 首句/未命名需求）。 */
+    /** /plan: rest 原始需求描述；null=无 /plan: 捕获（回退 checklist.problem 首句/未命名需求）。 */
     requirementName?: string | null;
 }
 /** v2：/openspec: 建链——从清单机械映射规格卡六段 → 挂 file-prefetch(仓库 localPath)+kb(清单页) → 批准 → executing。 */
 export declare function handleOpenspecRoute(message: string, service: KanbanService, cfg: PrefixRoutes, planning: OpenspecPlanningInput, ownerSessionId: string): Promise<PrefixRouteResult>;
-/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+/** /learning 零副作用引导文案：命令串从 config 派生，歧义/未找到时注入主 agent。 */
 export declare function buildLearningGuidance(routes: PrefixRoutes): string;
 /** v2：/learning 零副作用——不建链建卡，仅机械提取证据包供主 agent 蒸馏。歧义返回候选列表，链不存在返回错误文本（不 throw）。 */
 export declare function handleLearningRoute(message: string, service: KanbanService, cfg: PrefixRoutes, _ownerSessionId: string): Promise<PrefixRouteResult>;

package/lib/routes/prefix-router.js

@@ -1,5 +1,8 @@
 import { KanbanService, buildChainTitle } from '../domain/kanban-service.js';
 import { buildLearningBrief, resolveLearningChainId } from '../domain/memory.js';
+/** 防线D：/openspec: 建链后同步等待首张任务卡的最长时长与轮询间隔（fail-open：超时返回 pending，
+ *  由链级看门狗接管）。可变对象供测试注入短值（vitest 文件级隔离）。 */
+export const OPENSPEC_FIRST_CARD = { timeoutMs: 120_000, pollIntervalMs: 1_000 };
 export function parsePrefix(message, cfg) {
     const trimmed = message.trim();
     if (trimmed.startsWith(cfg.plan))
@@ -8,6 +11,8 @@ export function parsePrefix(message, cfg) {
         return { kind: 'openspec', rest: trimmed.slice(cfg.openspec.length).trim() };
     if (trimmed.startsWith(cfg.learning))
         return { kind: 'learning', rest: trimmed.slice(cfg.learning.length).trim() };
+    if (trimmed.startsWith(cfg.send))
+        return { kind: 'send', rest: trimmed.slice(cfg.send.length).trim() };
     return { kind: 'none', rest: trimmed };
 }
 /** v2：/plan: 零副作用——不建链/规格卡/任务卡，仅返回路由结果（workspaceDir/sessionId 由 main-session-tools 捕获）。 */
@@ -19,6 +24,23 @@ export async function handleOpenspecRoute(message, service, cfg, planning, owner
     const parsed = parsePrefix(message, cfg);
     if (parsed.kind !== 'openspec')
         return parsed;
+    // 护栏前移（fail-fast）：无 workspaceDir 的链会让 V 在 getVAgent 抛 workspace-unknown
+    // 且被 dispatcher 静默吞掉（链上零任务 → 无任何后续事件重试）→ 空壳链死锁。
+    // 典型成因：主 agent 进程重启后 planningBySession 重建，仅重存清单未重走 /plan:，
+    // workspaceDir 为 null。此处禁止建链建卡，引导用户先 /plan: 重新捕获工作区。
+    if (!planning.workspaceDir || !planning.workspaceDir.trim()) {
+        return {
+            kind: 'openspec', approved: false, reason: 'workspace-unknown', rest: parsed.rest,
+            guidance: [
+                '## 建链被拦截：workspaceDir 缺失（workspace-unknown）',
+                '当前规划上下文没有目标仓库工作区（多为主 agent 重启后清单内存重建所致）。',
+                '处理步骤（严格顺序）：',
+                '1. 重新发送 ' + cfg.plan + ' <需求描述> 让主 agent 捕获工作区（必要时按提示注册工作区）；',
+                '2. 清单仍在时重发 ' + cfg.openspec + ' 确认即可建链；清单丢失则重新澄清后再确认。',
+                '禁止：在无工作区时建链建卡；猜测工作区路径。',
+            ].join('\n'),
+        };
+    }
     const chain = await service.createChain({
         title: buildChainTitle(planning.checklist.requirementName ?? planning.requirementName ?? null, parsed.rest, planning.checklist.spec.problem),
         ownerSessionId, workspaceDir: planning.workspaceDir,
@@ -27,15 +49,30 @@ export async function handleOpenspecRoute(message, service, cfg, planning, owner
     await service.addSpecCardAttachment(card.id, { name: '需求澄清清单(仓库事实)', kind: 'file-prefetch', ref: planning.checklist.manifest.repo.localPath }, 'v');
     await service.addSpecCardAttachment(card.id, { name: '需求澄清清单(完整资料)', kind: 'kb', ref: planning.checklistRef }, 'v');
     await service.approveSpecCard(card.id, 'human');
-    return { kind: 'openspec', chainId: chain.id, specCardId: card.id, rest: parsed.rest };
+    const firstCard = await waitFirstCard(service, chain.id);
+    return { kind: 'openspec', chainId: chain.id, specCardId: card.id, rest: parsed.rest, firstCard };
+}
+/** 防线D：轮询看板等首张任务卡（任意 assignee/mode，V 首轮建 p 卡）。成功即返；
+ *  超时 fail-open 返回 {pending:true}——不挂死工具调用，失败面由链级看门狗兜底。 */
+async function waitFirstCard(service, chainId) {
+    const deadline = Date.now() + OPENSPEC_FIRST_CARD.timeoutMs;
+    for (;;) {
+        const state = await service.snapshot();
+        const t = [...state.tasks.values()].filter((x) => x.chainId === chainId).at(-1);
+        if (t)
+            return { taskId: t.id, status: t.status };
+        if (Date.now() >= deadline)
+            return { pending: true };
+        await new Promise((r) => setTimeout(r, Math.min(OPENSPEC_FIRST_CARD.pollIntervalMs, Math.max(1, deadline - Date.now()))));
+    }
 }
-/** /learning 零副作用引导文案：命令串从 config 派生（决策12），歧义/未找到时注入主 agent。 */
+/** /learning 零副作用引导文案：命令串从 config 派生，歧义/未找到时注入主 agent。 */
 export function buildLearningGuidance(routes) {
     return [
         '## 经验蒸馏指令（' + routes.learning + '）',
         '消化上方「链上下文 + 机械信号证据包」，蒸馏 1-3 条可复用经验（返工根因 / 阻塞原因 / 审计教训）。',
         '每条约成 LearningEntry（title 一句话≤80 字符；lesson 教训；evidence 必须填本链 chain id 作机械证据；tags 自由标签）。',
-        '调 planning_learning_save：scope=chain 存需求级 projects/<chainId>/learnings/；仓库通用经验用 scope=project（自动归入目标仓库项目级）。',
+        '调 planning_learning_save：scope=chain 存需求级 projects/<repoSlug>/<chainId>/learnings/；仓库通用经验用 scope=project（projects/<repoSlug>/learnings/，repoSlug 由链 workspaceDir 派生）。',
         '无值得沉淀的经验时，明确回复「无新经验」，不要硬凑。',
     ].join('\n');
 }

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

@@ -0,0 +1,38 @@
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { EditableSnapshot, SourceMap } from '../domain/config-override.js';
+import type { KanbanConfig } from '../config.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        swarmConfig: ConfigProvider;
+    }
+}
+export type ApplyResult = {
+    ok: true;
+    effective: EditableSnapshot;
+    sources: SourceMap;
+    changed: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare class ConfigProvider extends Service {
+    private readonly baseline;
+    private readonly overrideFile;
+    private readonly auditFile;
+    private override;
+    private effective;
+    private sources;
+    constructor(ctx: Context, baseline: KanbanConfig, storageDir: string);
+    getEffective(): KanbanConfig;
+    getSources(): SourceMap;
+    get mode(): 'remote' | 'local';
+    snapshot(): {
+        effective: EditableSnapshot;
+        sources: SourceMap;
+    };
+    applyOverride(snapshot: EditableSnapshot): ApplyResult;
+    private readOverride;
+    private writeOverride;
+    private appendAudit;
+    private diffKeys;
+}