@joekytc/dsh-swarm 0.3.1 → 0.3.6

package/lib/domain/ocr-review.js

@@ -1,11 +1,17 @@
-/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review 并恒带 JSON 输出。 */
+/** 构造 OCR CLI 参数：preview/rule 走 delegate，managed 走 review。
+ * preview 默认输出 text，必须显式 --format json 才能拿到可解析输出；
+ * managed 恒带 --audience agent（agent 场景标准参数，抑制 progress 输出）。 */
 export function buildOcrArgs(sub, a) {
     if (sub === 'preview') {
-        const args = ['delegate', 'preview'];
-        if (a.from)
-            args.push('--from', a.from);
-        if (a.to)
-            args.push('--to', a.to);
+        const args = ['delegate', 'preview', '--format', 'json'];
+        if (a.commit)
+            args.push('--commit', a.commit);
+        else if (a.from || a.to) {
+            if (a.from)
+                args.push('--from', a.from);
+            if (a.to)
+                args.push('--to', a.to);
+        }
         if (a.repo)
             args.push('--repo', a.repo);
         return args;
@@ -22,7 +28,9 @@ export function buildOcrArgs(sub, a) {
         if (a.to)
             args.push('--to', a.to);
     }
-    args.push('--format', 'json');
+    args.push('--format', 'json', '--audience', 'agent');
+    if (a.background)
+        args.push('--background', a.background);
     return args;
 }
 /** 解析失败的兜底结果。 */
@@ -37,7 +45,7 @@ function pathOf(el) {
 function asArray(v) {
     return Array.isArray(v) ? v.filter(isRecord) : [];
 }
-/** 解析 delegate preview 的 JSON 输出，失败或结构异常时回退 unknown。 */
+/** 解析 delegate preview 的 JSON 输出（官方字段 reviewable_files/excluded_files/exclude_reason），失败或结构异常时回退 unknown。 */
 export function parsePreviewJson(stdout) {
     let obj;
     try {
@@ -51,8 +59,8 @@ export function parsePreviewJson(stdout) {
     const mergeBase = obj.merge_base ?? obj.mergeBase;
     return {
         mode: String(obj.mode ?? 'unknown'),
-        files: asArray(obj.files).map((el) => ({ path: pathOf(el), status: String(el.status ?? '') })),
-        excluded: asArray(obj.excluded).map((el) => ({ path: pathOf(el), reason: String(el.reason ?? '') })),
+        files: asArray(obj.reviewable_files).map((el) => ({ path: pathOf(el), status: String(el.status ?? '') })),
+        excluded: asArray(obj.excluded_files).map((el) => ({ path: pathOf(el), reason: String(el.exclude_reason ?? '') })),
         mergeBase: mergeBase == null ? null : String(mergeBase),
     };
 }
@@ -68,7 +76,8 @@ export function parseManagedJson(stdout) {
     if (!isRecord(obj))
         return { status: 'unknown', comments: [] };
     const comments = asArray(obj.comments).map((el) => {
-        const rawLine = el.line ?? el.startLine;
+        // 官方 schema 行号字段为 snake_case start_line，line/startLine 仅作容错别名
+        const rawLine = el.start_line ?? el.line ?? el.startLine;
         const line = Number(rawLine);
         const message = String(el.content ?? el.message ?? el.body ?? '');
         return {

package/lib/domain/permissions.d.ts

@@ -1,5 +1,5 @@
 import type { Role, Task } from './types.js';
-export type KanbanAction = 'create-task' | 'create-chain' | 'claim' | 'complete' | 'block' | 'unblock' | 'comment' | 'heartbeat' | 'archive' | 'spec-approve' | 'spec-edit' | 'spec-attach' | 'wiki-write' | 'wiki-read' | 'prefetch' | 'audit-confirm' | 'update-title' | 'delete-chain' | 'create-rework-task';
+export type KanbanAction = 'create-task' | 'create-chain' | 'claim' | 'complete' | 'block' | 'unblock' | 'comment' | 'heartbeat' | 'archive' | 'spec-approve' | 'spec-edit' | 'spec-attach' | 'wiki-write' | 'wiki-read' | 'prefetch' | 'audit-confirm' | 'update-title' | 'delete-chain' | 'create-rework-task' | 'reopen-chain' | 'waive-review';
 export type Actor = Role | 'human' | 'system';
 export declare function can(action: KanbanAction, actor: Actor, task: Task | null, opts?: {
     isOwnTask?: boolean;

package/lib/domain/permissions.js

@@ -50,5 +50,9 @@ export function can(action, actor, task, opts = {}) {
         case 'create-rework-task':
             // 评审失败返工卡创建：仅系统（V 建执行卡、system 建返工卡，防角色伪造返工链）
             return actor === 'system';
+        case 'reopen-chain':
+        case 'waive-review':
+            // 人工恢复/豁免：仅 human（人工为信任锚；角色与 system 一律拒，防角色越权恢复）
+            return actor === 'human';
     }
 }

package/lib/domain/projection.js

@@ -13,7 +13,8 @@ export function applyTo(state, ev) {
         case 'chain/executing':
         case 'chain/completed':
         case 'chain/aborted':
-        case 'chain/blocked': {
+        case 'chain/blocked':
+        case 'chain/reopened': {
             const c = state.chains.get(ev.chainId);
             if (!c)
                 throw new Error('projection: unknown chain ' + ev.chainId);
@@ -128,12 +129,16 @@ export function applyTo(state, ev) {
         // 评审事件（交付质量链）：非状态转换——按 payload.targetTaskId 更新被评审任务 reviewStatus
         case 'review/passed':
         case 'review/failed':
-        case 'review/gave-up': {
+        case 'review/gave-up':
+        case 'review/waived': {
             const targetId = String(ev.payload['targetTaskId'] ?? '');
             const t = state.tasks.get(targetId);
             if (!t)
                 throw new Error('projection: unknown review target ' + targetId);
-            const status = ev.kind === 'review/passed' ? 'passed' : ev.kind === 'review/failed' ? 'failed' : 'gave-up';
+            const status = ev.kind === 'review/passed' ? 'passed'
+                : ev.kind === 'review/failed' ? 'failed'
+                    : ev.kind === 'review/waived' ? 'waived'
+                        : 'gave-up';
             next.tasks = new Map(state.tasks).set(targetId, { ...t, reviewStatus: status });
             break;
         }

package/lib/domain/review-evidence.js

@@ -20,6 +20,15 @@ export function validateReviewEvidence(role, handoff) {
         missing.push('review_evidence.verdict');
     if (!Array.isArray(ev.issues))
         missing.push('review_evidence.issues');
+    // 2026-09-15 口径锁死（P1-7，仅 PT）：fail 必须至少一条未解决的 critical/high——
+    // persona 口径「fail = 存在 critical/high」机械落地，防 medium 冒充阻断（ch_1_mu235xfz R3 summary 实录）。
+    // 全为非阻断项时应输出 pass（issues 作为非阻塞建议留档）。DT 不适用：其实证失败（test/build/diff）
+    // 未必伴随 high issue，用 severity 门槛会误放行真问题。
+    if (role === 'pt' && ev.verdict === 'fail' && Array.isArray(ev.issues)) {
+        const blocking = ev.issues.some((i) => i.resolved !== true && (i.severity === 'critical' || i.severity === 'high'));
+        if (!blocking)
+            missing.push('review_evidence.issues (verdict=fail 需至少一条未解决的 critical/high；否则应判 pass)');
+    }
     if (role === 'pt') {
         // 计划结构字段：评审须给出被评审计划产物引用（如 artifacts_path/page 结构）——缺则视为证据不足
         const planRef = ev.reviewPage ?? (handoff.metadata ?? {})['artifacts_path'];

package/lib/domain/review-target.d.ts

@@ -0,0 +1,10 @@
+import type { BoardState, Task } from './types.js';
+/** 评审目标推导（PT/DT 共用，2026-09-15 由 v-orchestrator 内联逻辑下沉）：
+ *  - currentTarget = 该评审卡实际评审的任务（复审卡经 reworkOfTaskId 指向返工卡；首评回退 parents[0] → 阶段源任务）；
+ *  - root = 沿 reworkOfTaskId 链到顶（原任务），reviewStatus 落点。
+ *  返回 null = 无法推导（调用方按原语义处理，如 gave-up）。
+ *  编排层与恢复 service 共用同一份推导，消除双份逻辑漂移。 */
+export declare function resolveReviewTarget(state: BoardState, reviewTask: Task, chainId: string): {
+    currentTarget: Task;
+    root: Task;
+} | null;

package/lib/domain/review-target.js

@@ -0,0 +1,24 @@
+/** 评审目标推导（PT/DT 共用，2026-09-15 由 v-orchestrator 内联逻辑下沉）：
+ *  - currentTarget = 该评审卡实际评审的任务（复审卡经 reworkOfTaskId 指向返工卡；首评回退 parents[0] → 阶段源任务）；
+ *  - root = 沿 reworkOfTaskId 链到顶（原任务），reviewStatus 落点。
+ *  返回 null = 无法推导（调用方按原语义处理，如 gave-up）。
+ *  编排层与恢复 service 共用同一份推导，消除双份逻辑漂移。 */
+export function resolveReviewTarget(state, reviewTask, chainId) {
+    const role = reviewTask.assignee === 'dt' ? 'dt' : 'pt';
+    const srcAssignee = role === 'pt' ? 'p' : 'd';
+    const srcMode = role === 'pt' ? 'openspec' : 'execute';
+    let currentTarget = reviewTask.reworkOfTaskId
+        ? state.tasks.get(reviewTask.reworkOfTaskId)
+        : reviewTask.parents[0]
+            ? state.tasks.get(reviewTask.parents[0])
+            : undefined;
+    if (!currentTarget) {
+        currentTarget = [...state.tasks.values()].find((t) => t.chainId === chainId && t.assignee === srcAssignee && t.mode === srcMode && t.status === 'done');
+    }
+    if (!currentTarget)
+        return null;
+    let root = currentTarget;
+    while (root.reworkOfTaskId && state.tasks.get(root.reworkOfTaskId))
+        root = state.tasks.get(root.reworkOfTaskId);
+    return { currentTarget, root };
+}

package/lib/domain/state-machine.js

@@ -11,7 +11,7 @@ const TASK_TRANSITIONS = {
 const CHAIN_TRANSITIONS = {
     planning: { 'chain/executing': 'executing' },
     executing: { 'chain/completed': 'completed', 'chain/aborted': 'aborted', 'chain/blocked': 'blocked' },
-    blocked: {},
+    blocked: { 'chain/reopened': 'executing' }, // 人工恢复唯一出边（其余事件对 blocked 仍非法）
     completed: {},
     aborted: {},
 };

package/lib/domain/types.d.ts

@@ -3,8 +3,8 @@ export type TaskMode = 'file' | 'external' | 'kb' | 'openspec' | 'mattpocock' |
 export type TaskStatus = 'triage' | 'todo' | 'ready' | 'running' | 'blocked' | 'done' | 'failed' | 'archived';
 export type ChainStatus = 'planning' | 'executing' | 'blocked' | 'completed' | 'aborted';
 export type SpecCardStatus = 'draft' | 'approved';
-/** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃。 */
-export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up';
+/** 评审状态（交付质量链）：not-required 普通卡 / pending 等待评审 / passed 通过 / failed 失败待返工 / gave-up 超限放弃 / waived 人工豁免。 */
+export type ReviewStatus = 'not-required' | 'pending' | 'passed' | 'failed' | 'gave-up' | 'waived';
 /** 评审结论：pass=通过 / fail=不通过。 */
 export type ReviewVerdict = 'pass' | 'fail';
 /** 评审问题条目（PT/DT 交接 evidence.issues）。 */
@@ -14,6 +14,14 @@ export interface ReviewIssue {
     detail: string;
     location?: string;
     resolved: boolean;
+    /** 依据（上游声明引用或计划内部矛盾点）——评审方运行时扩展字段，注入返工时保留。 */
+    basis?: string;
+    /** 问题说明（违反什么）。 */
+    problem?: string;
+    /** 可执行修改建议（怎么改）——返工方最需要的字段。 */
+    fix?: string;
+    /** 对账标记：true=上一轮遗留 issue 的对账条目；false/缺省=本轮新问题。收敛闸据此判定旧账是否清零（漏标=false=视为新问题，方向安全）。 */
+    legacy?: boolean;
 }
 /** TDD 硬要求证据（评审时收集的测试相关元信息）。 */
 export interface TddEvidence {
@@ -27,6 +35,11 @@ export interface TddEvidence {
 export interface ReviewEvidence {
     verdict: ReviewVerdict;
     issues: ReviewIssue[];
+    /** 收敛闸降级留痕（2026-09-15）：verdict 由 fail 降级为 pass 时记录原判定与原因，审计可查。 */
+    downgraded?: {
+        from: ReviewVerdict;
+        reason: string;
+    };
     tdd?: TddEvidence;
     test?: Record<string, unknown>;
     build?: Record<string, unknown>;
@@ -40,7 +53,7 @@ export interface ReviewEvidence {
         kbUrl: string;
     };
 }
-export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up';
+export type EventKind = 'chain/created' | 'chain/executing' | 'chain/completed' | 'chain/aborted' | 'chain/blocked' | 'chain/root-task-set' | 'chain/audit-warning' | 'chain/audit-confirmed' | 'chain/title-updated' | 'chain/im-delivery-failed' | 'spec-card/created' | 'spec-card/edited' | 'spec-card/approved' | 'task/created' | 'task/claimed' | 'task/heartbeat' | 'task/commented' | 'task/completed' | 'task/blocked' | 'task/unblocked' | 'task/archived' | 'task/gate-passed' | 'task/gate-failed' | 'task/failed' | 'task/renamed' | 'review/passed' | 'review/failed' | 'review/gave-up' | 'review/waived' | 'chain/reopened';
 export interface SpecCardSections {
     problem: string;
     solution: string;

package/lib/routes/kanban-http.js

@@ -1,9 +1,11 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
 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';
+import { resolveReviewTarget } from '../domain/review-target.js';
 function json(res, status, body) {
     res.statusCode = status;
     res.setHeader('content-type', 'application/json; charset=utf-8');
@@ -72,13 +74,17 @@ const OCR_WIRE_DEGRADED = '未能从 dsh 解析该提供方的接入信息（bas
  * 从宿主设置解析所选提供方的接入信息（baseUrl/协议/apiKey）。
  * 事实核查结论（实现期探查）：llm 服务的公开 API 不暴露连接事实，但同进程可经
  * settings 服务的 describe() 读到模型适配器的 provider profile——形如
- * { providers: { <id>: { baseURL, api, apiKey | apiKeyEnv } } }（apiKeyEnv 指向进程环境变量名）。
+ * { providers: { <id>: { baseURL, api, apiKey | apiKeyEnv } } }（apiKeyEnv 指向凭据引用名）。
+ * 踩坑：apiKeyEnv 名下的 key 不一定在进程 env——Models 页写入的凭据存在
+ * credentials 服务的 managed store（ctx.credentials）里；解析顺序须先进程 env、
+ * 再 ctx.credentials.resolve（env → managed store → $DSH_HOME/.env，per-call 不缓存）。
  * 命中 profile 但字段不全时跳过该 descriptor 继续尝试下一个（多 descriptor 场景勿误降级），
  * 绝不回传半套配置；全部不合才返回 null 走降级。apiKey 只透传给 ocr config，不落日志。
  */
-function resolveDshProviderAccess(ctx, providerId) {
+async function resolveDshProviderAccess(ctx, providerId) {
     try {
         const settings = ctx.get('settings');
+        const creds = ctx.get('credentials');
         const descriptors = settings?.describe?.() ?? [];
         for (const d of descriptors) {
             const providers = d.value?.providers;
@@ -89,8 +95,13 @@ function resolveDshProviderAccess(ctx, providerId) {
             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')
+            if (!apiKey && typeof profile.apiKeyEnv === 'string') {
                 apiKey = process.env[profile.apiKeyEnv] ?? '';
+                if (!apiKey && creds?.resolve) {
+                    const r = await creds.resolve(credentialRef(profile.apiKeyEnv));
+                    apiKey = r?.value ?? '';
+                }
+            }
             if (baseUrl && protocol && apiKey)
                 return { baseUrl, protocol, apiKey };
             continue; // 字段不全：换下一个 descriptor，勿在此误降级
@@ -160,6 +171,25 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         json(res, 200, { ok: true });
                         return;
                     }
+                    // 人工恢复被 blocked 的链（2026-09-15 恢复能力，仅 human）：链级 action，在 taskId 守卫前分流。
+                    // 非 blocked 链 → 409（fail-closed）；reason 必填（审计留痕）。
+                    if (body.type === 'reopen-chain') {
+                        const chainId = String(body.chainId ?? '').trim();
+                        const reason = String(body.reason ?? '').trim();
+                        if (!chainId || !reason) {
+                            json(res, 400, { error: 'chainId and reason required' });
+                            return;
+                        }
+                        try {
+                            await provider.service.reopenChain(chainId, reason, 'human');
+                        }
+                        catch (err) {
+                            json(res, 409, { error: String(err instanceof Error ? err.message : err) });
+                            return;
+                        }
+                        json(res, 200, { ok: true });
+                        return;
+                    }
                     // rename 是链级或任务级 action（chainId 或 taskId 二选一），在 taskId 守卫前分流
                     if (body.type === 'rename') {
                         const title = String(body.title ?? '').trim();
@@ -196,6 +226,34 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         case 'unblock':
                             await provider.service.unblockTask(t, 'human');
                             break;
+                        case 'waive-review': {
+                            // 人工评审豁免（2026-09-15 恢复能力，仅 human）：目标根卡由 resolveReviewTarget 推导
+                            //（评审卡→返工链→root），前端无需重复实现；非 failed/gave-up 目标 → 409（防误豁免）。
+                            const reason = String(body.reason ?? '').trim();
+                            if (!reason) {
+                                json(res, 400, { error: 'reason required' });
+                                return;
+                            }
+                            const state = await provider.service.snapshot();
+                            const reviewTask = state.tasks.get(t);
+                            if (!reviewTask) {
+                                json(res, 404, { error: 'unknown task: ' + t });
+                                return;
+                            }
+                            const target = resolveReviewTarget(state, reviewTask, reviewTask.chainId);
+                            if (!target) {
+                                json(res, 409, { error: 'review target not resolvable for ' + t });
+                                return;
+                            }
+                            try {
+                                await provider.service.waiveReview(t, target.root.id, reason, 'human');
+                            }
+                            catch (err) {
+                                json(res, 409, { error: String(err instanceof Error ? err.message : err) });
+                                return;
+                            }
+                            break;
+                        }
                         case 'retry': {
                             // retry 走 runner（failed→claim→spawn/resume），而非只 claim 造成 running 悬挂
                             const state = await provider.service.snapshot();
@@ -250,8 +308,9 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                 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;
+                    // reviewEngine/imDelivery 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带这些字段时保存不清空既有配置。
+                    const cur = configProvider.getEffective();
+                    const fb = cur.reviewEngine;
                     const snapshot = {
                         wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
                         roles: { models: raw.roles?.models ?? {} },
@@ -262,6 +321,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                                 model: raw.reviewEngine?.managed?.model ?? fb?.managed?.model ?? '',
                             },
                         },
+                        imDelivery: { fallbackBotId: raw.imDelivery?.fallbackBotId ?? cur.imDelivery?.fallbackBotId ?? '' },
                     };
                     const r = configProvider.applyOverride(snapshot);
                     if (!r.ok) {
@@ -330,7 +390,7 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                         json(res, 200, { ok: false, log: INSTALL_GUIDANCE });
                         return;
                     }
-                    const access = resolveDshProviderAccess(ctx, providerId);
+                    const access = await resolveDshProviderAccess(ctx, providerId);
                     if (!access) {
                         json(res, 200, { ok: false, log: OCR_WIRE_DEGRADED });
                         return;

package/lib/services/config-provider.js

@@ -87,6 +87,8 @@ export class ConfigProvider extends Service {
             if (prev.reviewEngine?.managed?.[f] !== next.reviewEngine?.managed?.[f])
                 keys.add('reviewEngine.managed.' + f);
         }
+        if ((prev.imDelivery?.fallbackBotId ?? '') !== (next.imDelivery?.fallbackBotId ?? ''))
+            keys.add('imDelivery.fallbackBotId');
         return [...keys];
     }
 }

package/lib/services/im-bot-probe.d.ts

@@ -0,0 +1,36 @@
+/** 一个企微机器人的探针视图（字段取自 connection.status 的 bots[]，缺失值归一为空/离线）。 */
+export interface BotCandidate {
+    botId: string;
+    /** 该机器人的默认 dsh 模式（dsh-im 设置页的 agentPreset）；未设置时为空串。 */
+    agentPreset: string;
+    connected: boolean;
+    /** 展示名（appIdMasked，脱敏 id），仅用于交互提示。 */
+    label: string;
+}
+export type ProbeResult = {
+    ok: true;
+    bots: BotCandidate[];
+} | {
+    ok: false;
+    error: string;
+};
+/** 探针依赖（全部注入，便于测试与惰性读取）。 */
+export interface ProbeDeps {
+    /** 监听端口；未就绪（webServer 未挂载/未 listen）返回 null。 */
+    port: () => number | null;
+    /** 进程 token 换 cookie 的入口（ctx.connection.authenticatedUrl）；服务缺失返回 null。 */
+    authenticatedUrl: (base: string) => string | null;
+    fetchImpl: typeof fetch;
+    /** 时钟（缓存 TTL 测试用）。 */
+    now?: () => number;
+}
+/** connection.status 响应信封 → 候选数组。形状不符返回 null（上游改形状即降级，不猜字段）。 */
+export declare function parseBotCandidates(raw: unknown): BotCandidate[] | null;
+/** Set-Cookie 头 → `name=value` 片段（剥属性）。无 dsh-auth 前缀项返回 null。 */
+export declare function pickAuthCookie(lines: readonly string[]): string | null;
+/** 探针工厂：同一实例内结果短期缓存（连发 /sms 不重复握手），失败同样缓存以免每次重试打满超时。 */
+export declare function createBotProbe(deps: ProbeDeps): () => Promise<ProbeResult>;
+/** 从 cordis ctx 装配探针依赖（惰性：每次调用才读端口与 connection，避免 apply 期缓存未就绪的值）。 */
+export declare function probeDepsFromCtx(ctx: {
+    get(name: string): unknown;
+}): ProbeDeps;

package/lib/services/im-bot-probe.js

@@ -0,0 +1,128 @@
+// src/services/im-bot-probe.ts
+// 多机器人消歧探针：读 dsh-im 侧每个企微机器人的 agentPreset（默认 dsh 模式）与连接态。
+//
+// 数据源是 dsh-im 的管理 RPC `/wecom/connection.status`（WECOM_ENDPOINTS.status）。该通道只对浏览器开放
+// （loopback authority + dsh-auth cookie），宿主插件侧没有本地 invoke 面（HostConnectionRpc 只有
+// handle/intercept），故这里走「进程 token 换 cookie 再自调用」的公开路径：
+//   ctx.connection.authenticatedUrl(base) → GET `/` 拿 Set-Cookie → 带 cookie POST 该 RPC。
+// launchToken 只存在于进程内存（WeakMap），不落盘；cookie 是自包含 HMAC，重铸成本极低。
+//
+// 红线（本模块唯一允许接触 cookie 的地方）：
+//   1. cookie / token / URL / 请求头绝不进任何日志、错误消息或链事件（dispatcher.log 与 events.jsonl 都长期留盘）；
+//   2. 探针失败一律降级（返回 {ok:false}），绝不让投递整体失败——调用方退化到默认机器人/交互选择；
+//   3. 上游改 RPC 形状 → parseBotCandidates 返回 null → fail-closed 同样走降级，不静默投错对象。
+const PROBE_TIMEOUT_MS = 1_500;
+const CACHE_TTL_MS = 30_000;
+const STATUS_PATH = '/wecom/connection.status';
+const COOKIE_PREFIX = 'dsh-auth-';
+/** connection.status 响应信封 → 候选数组。形状不符返回 null（上游改形状即降级，不猜字段）。 */
+export function parseBotCandidates(raw) {
+    const bots = raw?.result?.value?.bots;
+    if (!Array.isArray(bots))
+        return null;
+    const out = [];
+    for (const entry of bots) {
+        const botId = entry?.botId;
+        if (typeof botId !== 'string' || !botId)
+            return null;
+        const preset = entry.agentPreset;
+        const label = entry?.bot?.appIdMasked;
+        out.push({
+            botId,
+            agentPreset: typeof preset === 'string' ? preset : '',
+            connected: entry.connected === true,
+            label: typeof label === 'string' ? label : '',
+        });
+    }
+    return out;
+}
+/** Set-Cookie 头 → `name=value` 片段（剥属性）。无 dsh-auth 前缀项返回 null。 */
+export function pickAuthCookie(lines) {
+    for (const line of lines) {
+        const pair = line.split(';')[0]?.trim() ?? '';
+        if (pair.startsWith(COOKIE_PREFIX))
+            return pair;
+    }
+    return null;
+}
+function setCookieLines(headers) {
+    const multi = headers.getSetCookie?.();
+    if (Array.isArray(multi) && multi.length > 0)
+        return multi;
+    const single = headers.get('set-cookie');
+    return single ? [single] : [];
+}
+/** 错误归一：只取错误码/名，绝不带 URL、请求头或 cookie（日志红线）。 */
+function errorCode(err) {
+    const code = err?.code;
+    if (typeof code === 'string' && code)
+        return code;
+    const name = err?.name;
+    return typeof name === 'string' && name ? name : 'probe-failed';
+}
+async function runProbe(deps) {
+    const port = deps.port();
+    if (typeof port !== 'number' || !Number.isInteger(port) || port <= 0) {
+        return { ok: false, error: 'probe-unavailable: web-server-port' };
+    }
+    const base = `http://127.0.0.1:${port}`;
+    const exchangeUrl = deps.authenticatedUrl(`${base}/`);
+    if (!exchangeUrl)
+        return { ok: false, error: 'probe-unavailable: connection' };
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, PROBE_TIMEOUT_MS);
+    try {
+        // 进程 token → cookie：GET 应用根，白拿 Set-Cookie（不跟随重定向，避免多一次无用请求）。
+        const index = await deps.fetchImpl(exchangeUrl, { redirect: 'manual', signal: controller.signal });
+        const cookie = pickAuthCookie(setCookieLines(index.headers));
+        if (!cookie)
+            return { ok: false, error: `probe-unauthorized: ${index.status}` };
+        const res = await deps.fetchImpl(base + STATUS_PATH, {
+            method: 'POST',
+            redirect: 'manual',
+            signal: controller.signal,
+            headers: { 'content-type': 'application/json', origin: base, cookie },
+            body: JSON.stringify({ type: 'client-request', rpcId: 'dsh-swarm-bot-probe', method: 'connection.status', payload: {} }),
+        });
+        if (!res.ok)
+            return { ok: false, error: `probe-http: ${res.status}` };
+        const bots = parseBotCandidates(await res.json());
+        if (bots === null)
+            return { ok: false, error: 'probe-shape-mismatch' };
+        return { ok: true, bots };
+    }
+    catch (err) {
+        return { ok: false, error: `probe-failed: ${errorCode(err)}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 探针工厂：同一实例内结果短期缓存（连发 /sms 不重复握手），失败同样缓存以免每次重试打满超时。 */
+export function createBotProbe(deps) {
+    const now = deps.now ?? Date.now;
+    let cached = null;
+    return async () => {
+        if (cached && now() - cached.at < CACHE_TTL_MS)
+            return cached.result;
+        const result = await runProbe(deps);
+        cached = { at: now(), result };
+        return result;
+    };
+}
+/** 从 cordis ctx 装配探针依赖（惰性：每次调用才读端口与 connection，避免 apply 期缓存未就绪的值）。 */
+export function probeDepsFromCtx(ctx) {
+    return {
+        port: () => {
+            const ws = ctx.get('webServer');
+            return typeof ws?.port === 'number' ? ws.port : null;
+        },
+        authenticatedUrl: (base) => {
+            const conn = ctx.get('connection');
+            if (typeof conn?.authenticatedUrl !== 'function')
+                return null;
+            return conn.authenticatedUrl(base);
+        },
+        fetchImpl: ((...args) => fetch(...args)),
+    };
+}