@joekytc/dsh-swarm 0.5.0 → 0.5.1

package/lib/dispatcher/model-chain.js

@@ -0,0 +1,110 @@
+import { buildModelCandidates } from './model-candidates.js';
+import { agentPresetSelected } from './session-events.js';
+const chainStates = new WeakMap();
+export function registerModelChain(agent, state) {
+    chainStates.set(agent, state);
+    const session = agent.session;
+    if (session && typeof session === 'object')
+        chainStates.set(session, state);
+}
+export function isSwitchableModelFailure(failure) {
+    const code = String(failure.code ?? '').toLowerCase();
+    const msg = String(failure.message ?? '').toLowerCase();
+    if (code.includes('quota'))
+        return true;
+    if (failure.status === 402 || failure.status === 429)
+        return true;
+    if (/insufficient balance|quota|rate.?limit|\b429\b/.test(msg))
+        return true;
+    if (code === 'unknown_model' || code === 'unsupported_reasoning_effort')
+        return true;
+    if (code.includes('credential') || code.includes('login'))
+        return true;
+    if (msg.includes('adapter'))
+        return true;
+    if (msg.includes('missing_credential') || msg.includes('credentials') || msg.includes('login') || msg.includes('登录'))
+        return true;
+    if (msg.includes('provider') && (msg.includes('unavailable') || msg.includes('not') || msg.includes('fail')))
+        return true;
+    return msg.includes('model') && (msg.includes('unavailable') || msg.includes('not found') || msg.includes('no adapter'));
+}
+const ROLE_IDS = new Set(['v', 'p', 'w', 'd', 'pt', 'dt']);
+function sessionEventsOf(session) {
+    const s = session;
+    if (typeof s?.snapshotEvents === 'function')
+        return s.snapshotEvents();
+    return s?.events ?? [];
+}
+function detectManualChain(agent, config) {
+    const session = agent.session;
+    const preset = agentPresetSelected(sessionEventsOf(session))
+        ?? (session?.header?.agentPreset ?? null);
+    const role = typeof preset === 'string' && preset.startsWith('kanban-') ? preset.slice('kanban-'.length) : '';
+    let state = null;
+    if (ROLE_IDS.has(role)) {
+        const m = config.roles?.models?.[role];
+        if (m?.provider && m?.model) {
+            const candidates = buildModelCandidates(config, role);
+            if (candidates.length > 0)
+                state = { candidates, index: 0 };
+        }
+    }
+    chainStates.set(agent, state);
+    return state;
+}
+function resolveState(agent, config) {
+    const session = agent.session;
+    for (const key of [agent, session]) {
+        if (key && typeof key === 'object' && chainStates.has(key))
+            return chainStates.get(key) ?? null;
+    }
+    return detectManualChain(agent, config);
+}
+export function installModelChainHooks(scope, deps) {
+    const scoped = scope;
+    const disposeRequest = scoped.on('agent/request', async (payload, next) => {
+        const resolved = (await next());
+        const agent = payload.agent;
+        if (!agent || typeof agent !== 'object')
+            return resolved;
+        const state = resolveState(agent, deps.getConfig());
+        const cur = state?.candidates[state.index];
+        if (!cur)
+            return resolved;
+        return { ...resolved, provider: cur.provider, model: cur.model, reasoningEffort: cur.reasoningEffort ?? 'high' };
+    });
+    const disposeError = scoped.on('agent/request-error', async (payload, next) => {
+        const p = payload;
+        const agent = p.agent;
+        if (!agent || typeof agent !== 'object')
+            return next();
+        const state = resolveState(agent, deps.getConfig());
+        if (!state)
+            return next();
+        if (!isSwitchableModelFailure(p.failure ?? {}))
+            return next();
+        const nextIndex = state.index + 1;
+        if (nextIndex >= state.candidates.length)
+            return next();
+        const prev = state.candidates[state.index];
+        state.index = nextIndex;
+        const cur = state.candidates[nextIndex];
+        const detail = String(p.failure?.code ?? '') + ' ' + String(p.failure?.message ?? '');
+        const line = '[model-fallback] ' + prev.provider + '/' + prev.model + ' → ' + cur.provider + '/' + cur.model
+            + '（reasoningEffort=' + (cur.reasoningEffort ?? 'high') + '）: ' + detail;
+        console.error('[dsh-swarm][debug] ' + line);
+        deps.log?.(line);
+        if (state.taskId && state.comment) {
+            try {
+                await state.comment('[model-fallback] 主模型不可用，静默切换 ' + cur.provider + '/' + cur.model
+                    + '（reasoningEffort=' + (cur.reasoningEffort ?? 'high') + '）');
+            }
+            catch { /* 证据记录失败不影响切换 */ }
+        }
+        return { kind: 'retry' };
+    });
+    return () => {
+        disposeRequest();
+        disposeError();
+    };
+}

package/lib/dispatcher/session-events.d.ts

@@ -48,6 +48,8 @@ export interface TurnEndInfo {
     message: string | null;
 }
 export declare function turnEndOf(e: unknown): TurnEndInfo | null;
+/** 会话内最后一次 agent-preset/selected 的 preset id（如 'kanban-w'）；无该事件返回 null。 */
+export declare function agentPresetSelected(events: ReadonlyArray<unknown>): string | null;
 /** 本轮增量（seq > fromSeq）内最后一轮 turn/end——拒答重试会产生第二轮，取 seq 最大者。
  *  无 turn/end（测试桩/宿主变体）→ null，调用方按「无轮信息」回退原判据，不改变既有行为。 */
 export declare function lastTurnEnd(events: ReadonlyArray<unknown>, fromSeq: number): TurnEndInfo | null;

package/lib/dispatcher/session-events.js

@@ -86,6 +86,19 @@ export function turnEndOf(e) {
         message: typeof reason?.error?.message === 'string' ? reason.error.message : null,
     };
 }
+/** 会话内最后一次 agent-preset/selected 的 preset id（如 'kanban-w'）；无该事件返回 null。 */
+export function agentPresetSelected(events) {
+    let found = null;
+    for (const e of events) {
+        if (eventType(e) !== 'agent-preset/selected')
+            continue;
+        const rec = e;
+        const p = rec?.agentPreset ?? rec?.data?.agentPreset;
+        if (typeof p === 'string')
+            found = p;
+    }
+    return found;
+}
 /** 本轮增量（seq > fromSeq）内最后一轮 turn/end——拒答重试会产生第二轮，取 seq 最大者。
  *  无 turn/end（测试桩/宿主变体）→ null，调用方按「无轮信息」回退原判据，不改变既有行为。 */
 export function lastTurnEnd(events, fromSeq) {

package/lib/dispatcher/v-orchestrator.js

@@ -6,6 +6,7 @@ import { missingParentDelivery } from '../domain/delivery-contract.js';
 import { buildRepoSlug } from '../domain/memory.js';
 import { toolArgs, toolName, replayModel } from './session-events.js';
 import { buildModelCandidates, isModelUnavailableError } from './model-candidates.js';
+import { registerModelChain } from './model-chain.js';
 import { attachSessionToWorkspace, resolveOrCreateWorkspace } from './workspace-attach.js';
 export const R20_PHASE_ORDER = ['p', 'pt', 'w2', 'd', 'dt', 'w3', 'summary'];
 /** 每 phase 的期望建卡（pt 由 P 交付 pt_decision.needed=true 触发；dt 固定）。 */
@@ -697,9 +698,11 @@ export class VOrchestrator {
         if (candidates.length === 0)
             return spawnWith({});
         let lastErr = null;
-        for (const candidate of candidates) {
+        for (const [candidateIndex, candidate] of candidates.entries()) {
             try {
-                return await spawnWith({ agentOptions: candidate });
+                const spawned = await spawnWith({ agentOptions: candidate });
+                registerModelChain(spawned, { candidates, index: candidateIndex });
+                return spawned;
             }
             catch (err) {
                 lastErr = err;

package/lib/domain/config-override.d.ts

@@ -1,10 +1,16 @@
 import type { KanbanConfig } from '../config.js';
 import type { Role } from './types.js';
 export declare const ROLES: readonly Role[];
+export interface ModelFallbackInput {
+    provider?: string;
+    model?: string;
+    reasoningEffort?: string;
+}
 export interface EditableModelInput {
     provider?: string;
     model?: string;
     reasoningEffort?: string;
+    fallbacks?: ModelFallbackInput[];
 }
 export interface EditableOverride {
     wikiVault?: {
@@ -25,10 +31,16 @@ export interface EditableOverride {
         fallbackBotId?: string;
     };
 }
+export interface ModelFallbackSnapshot {
+    provider: string;
+    model: string;
+    reasoningEffort: string;
+}
 export interface EditableModelSnapshot {
     provider: string;
     model: string;
     reasoningEffort: string;
+    fallbacks: ModelFallbackSnapshot[];
 }
 export interface EditableSnapshot {
     wikiVault: {
@@ -38,6 +50,12 @@ export interface EditableSnapshot {
     roles: {
         models: Partial<Record<Role, EditableModelSnapshot>>;
     };
+    /** 官方兜底（全局）——只读投影：编辑入口在部署配置（bundle patch），面板仅展示链尾。 */
+    chainFallback: {
+        provider: string;
+        model: string;
+        reasoningEffort: string;
+    };
     reviewEngine: {
         mode: 'delegate' | 'managed';
         managed: {
@@ -51,6 +69,8 @@ export interface EditableSnapshot {
 }
 export type ConfigSource = 'override' | 'inherited';
 export type SourceMap = Record<string, ConfigSource>;
+/** 单角色降级候选上限（与 config schema .max(2)、GUI 上限同口径）。 */
+export declare const MAX_FALLBACKS = 2;
 export declare function mergeConfig(baseline: KanbanConfig, override: EditableOverride | undefined): KanbanConfig;
 export declare function computeSources(override: EditableOverride | undefined): SourceMap;
 export declare function projectEditable(effective: KanbanConfig): EditableSnapshot;

package/lib/domain/config-override.js

@@ -2,6 +2,18 @@ export const ROLES = ['v', 'p', 'w', 'd', 'pt', 'dt'];
 /** botId 形态（与 dsh-im 的 id 校验同口径）：非空时只允许 id 安全字符。 */
 const BOT_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 const MODEL_FIELDS = ['provider', 'model', 'reasoningEffort'];
+/** 单角色降级候选上限（与 config schema .max(2)、GUI 上限同口径）。 */
+export const MAX_FALLBACKS = 2;
+/** 降级候选归一化：全空行丢弃（GUI 占位行）、effort 空白补 'high'、部分填写行保留（交校验报错）。 */
+function normalizeFallbacks(list) {
+    return (list ?? [])
+        .filter((f) => (f?.provider ?? '').trim() || (f?.model ?? '').trim())
+        .map((f) => ({
+        provider: (f.provider ?? '').trim(),
+        model: (f.model ?? '').trim(),
+        reasoningEffort: f.reasoningEffort?.trim() ? f.reasoningEffort : 'high',
+    }));
+}
 export function mergeConfig(baseline, override) {
     const wiki = { ...baseline.wikiVault };
     if (override?.wikiVault?.baseUrl !== undefined)
@@ -32,12 +44,15 @@ export function mergeConfig(baseline, override) {
         // 防御：空字符串 reasoningEffort 视为"未设置"，永不覆盖 baseline/默认（读点回退 'high'）。
         if (over.reasoningEffort !== undefined && over.reasoningEffort.trim() !== '')
             cur.reasoningEffort = over.reasoningEffort;
+        if (over.fallbacks !== undefined)
+            cur.fallbacks = normalizeFallbacks(over.fallbacks);
         if (cur.provider && cur.model)
             models[role] = cur;
     }
     const imDelivery = { ...baseline.imDelivery };
     if (override?.imDelivery?.fallbackBotId !== undefined)
         imDelivery.fallbackBotId = override.imDelivery.fallbackBotId;
+    // chainFallback 只属 baseline（部署配置），override 不触碰。
     return { ...baseline, wikiVault: wiki, roles: { ...baseline.roles, models }, reviewEngine, imDelivery };
 }
 export function computeSources(override) {
@@ -51,6 +66,7 @@ export function computeSources(override) {
             const hit = override?.roles?.models?.[role]?.[f] !== undefined;
             src[`roles.models.${role}.${f}`] = hit ? 'override' : 'inherited';
         }
+        src[`roles.models.${role}.fallbacks`] = override?.roles?.models?.[role]?.fallbacks !== undefined ? 'override' : 'inherited';
     }
     src['reviewEngine.mode'] = override?.reviewEngine?.mode !== undefined ? 'override' : 'inherited';
     src['reviewEngine.managed.provider'] = override?.reviewEngine?.managed?.provider !== undefined ? 'override' : 'inherited';
@@ -62,12 +78,21 @@ export function projectEditable(effective) {
     const models = {};
     for (const role of ROLES) {
         const m = effective.roles.models?.[role];
-        if (m?.provider && m?.model)
-            models[role] = { provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high' };
+        if (m?.provider && m?.model) {
+            models[role] = {
+                provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort ?? 'high',
+                fallbacks: normalizeFallbacks(m.fallbacks),
+            };
+        }
     }
+    const cf = effective.roles.chainFallback;
     return {
         wikiVault: { baseUrl: effective.wikiVault.baseUrl, pagePrefix: effective.wikiVault.pagePrefix },
         roles: { models },
+        chainFallback: {
+            provider: cf?.provider ?? '', model: cf?.model ?? '',
+            reasoningEffort: cf?.reasoningEffort?.trim() ? cf.reasoningEffort : 'high',
+        },
         reviewEngine: {
             mode: effective.reviewEngine?.mode ?? 'delegate',
             managed: { provider: effective.reviewEngine?.managed?.provider ?? '', model: effective.reviewEngine?.managed?.model ?? '' },
@@ -95,6 +120,18 @@ export function validateConfig(snapshot) {
             errs.push(`roles.models.${role}.provider`);
         if (!m.model?.trim())
             errs.push(`roles.models.${role}.model`);
+        const fbs = m.fallbacks ?? [];
+        if (fbs.length > MAX_FALLBACKS)
+            errs.push(`roles.models.${role}.fallbacks`);
+        fbs.forEach((f, i) => {
+            const p = (f?.provider ?? '').trim();
+            const mm = (f?.model ?? '').trim();
+            // 全空行 = GUI 占位（合法）；部分填写 = 未完成编辑，报错阻断。
+            if (!p && !mm)
+                return;
+            if (!p || !mm)
+                errs.push(`roles.models.${role}.fallbacks.${i}`);
+        });
     }
     // 默认机器人：留空=未设默认（合法，语义为「未命中就交互」）；非空必须形如 dsh-im 的 botId。
     const fb = (snapshot.imDelivery?.fallbackBotId ?? '').trim();
@@ -124,6 +161,13 @@ export function diffOverride(baseline, snapshot) {
         const snapEffort = snap?.reasoningEffort?.trim() ? snap.reasoningEffort : undefined;
         if (snapEffort !== undefined && snapEffort !== (base?.reasoningEffort ?? 'high'))
             cur.reasoningEffort = snapEffort;
+        // 降级链按归一化后整体比较：变化才整组写入。缺字段=显式空链（清空语义）；
+        // 旧客户端兼容由 HTTP 保存口回填 effective 链，不在此特判。
+        if (snap) {
+            const snapFbs = normalizeFallbacks(snap.fallbacks);
+            if (JSON.stringify(snapFbs) !== JSON.stringify(normalizeFallbacks(base?.fallbacks)))
+                cur.fallbacks = snapFbs;
+        }
         if (Object.keys(cur).length)
             models[role] = cur;
     }

package/lib/index.js

@@ -6,6 +6,8 @@ import { installRolePresets } from './roles/preset-installer.js';
 import { installLlWikiSkill } from './roles/skill-installer.js';
 import { registerKanbanHttp } from './routes/kanban-http.js';
 import { startDispatcher } from './dispatcher/dispatcher.js';
+import { installModelChainHooks } from './dispatcher/model-chain.js';
+import { logToDispatcherLog } from './dispatcher/agent-runner.js';
 import { ConfigProvider } from './services/config-provider.js';
 import { wireImDelivery } from './services/im-delivery.js';
 export const name = 'dsh-swarm';
@@ -47,6 +49,11 @@ export function apply(ctx, config) {
     // imDelivery.enabled=false（默认）时事件处理器零开销早退；dshIm 服务缺失显式降级留痕。
     const disposeImDelivery = wireImDelivery(ctx, provider.service, configProvider);
     ctx.on('dispose', disposeImDelivery);
+    const disposeModelChain = installModelChainHooks(ctx, {
+        getConfig: () => configProvider.getEffective(),
+        log: (line) => logToDispatcherLog(configProvider, line),
+    });
+    ctx.on('dispose', disposeModelChain);
     // LLM 运行时延迟取用：registerKanbanHttp 内部消费（llm-catalog 枚举），接线时 llm 服务已就绪。
     const llm = () => ctx.get('llm');
     // 可选服务接线均延迟到服务可用后：

package/lib/routes/kanban-http.js

@@ -309,12 +309,27 @@ 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/imDelivery 缺省时回退当前 effective（再兜底默认）：旧客户端 bundle 不带这些字段时保存不清空既有配置。
+                    // reviewEngine/imDelivery/chainFallback 缺省时回退当前 effective（再兜底默认）：旧客户端
+                    // bundle 不带这些字段时保存不清空既有配置；chainFallback 属部署配置只读，原样回填。
                     const cur = configProvider.getEffective();
                     const fb = cur.reviewEngine;
+                    const cfb = cur.roles.chainFallback;
                     const snapshot = {
                         wikiVault: { baseUrl: raw.wikiVault?.baseUrl ?? '', pagePrefix: raw.wikiVault?.pagePrefix ?? '' },
-                        roles: { models: raw.roles?.models ?? {} },
+                        roles: {
+                            models: Object.fromEntries(Object.entries(raw.roles?.models ?? {}).map(([k, m]) => [
+                                k,
+                                // 旧客户端 bundle 不带 fallbacks 字段：回填当前 effective 链，避免保存时误清降级链。
+                                m.fallbacks === undefined
+                                    ? { ...m, fallbacks: cur.roles.models?.[k]?.fallbacks ?? [] }
+                                    : m,
+                            ])),
+                        },
+                        chainFallback: {
+                            provider: raw.chainFallback?.provider ?? cfb?.provider ?? '',
+                            model: raw.chainFallback?.model ?? cfb?.model ?? '',
+                            reasoningEffort: raw.chainFallback?.reasoningEffort ?? cfb?.reasoningEffort ?? 'high',
+                        },
                         reviewEngine: {
                             mode: raw.reviewEngine?.mode ?? fb?.mode ?? 'delegate',
                             managed: {
@@ -331,8 +346,14 @@ export function registerKanbanHttp(ctx, provider, configProvider, llm, config, o
                     const toProbe = [];
                     for (const role of ROLES) {
                         const m = snapshot.roles.models[role];
-                        if (m?.provider?.trim() && m?.model?.trim())
+                        if (m?.provider?.trim() && m?.model?.trim()) {
                             toProbe.push({ provider: m.provider, model: m.model, reasoningEffort: m.reasoningEffort });
+                            // 降级候选同口径预检：死组合保存时拦下，不流入派发。
+                            for (const f of m.fallbacks ?? []) {
+                                if (f.provider?.trim() && f.model?.trim())
+                                    toProbe.push({ provider: f.provider, model: f.model, reasoningEffort: f.reasoningEffort });
+                            }
+                        }
                     }
                     if (snapshot.reviewEngine.mode === 'managed' && snapshot.reviewEngine.managed.provider.trim() && snapshot.reviewEngine.managed.model.trim()) {
                         toProbe.push({ provider: snapshot.reviewEngine.managed.provider, model: snapshot.reviewEngine.managed.model });

package/lib/services/config-provider.js

@@ -80,6 +80,11 @@ export class ConfigProvider extends Service {
                 if (a !== b)
                     keys.add(`roles.models.${role}.${f}`);
             }
+            // 降级链整组审计（实例必不同，按内容比较）。
+            const af = prev.roles?.models?.[role]?.fallbacks;
+            const bf = next.roles?.models?.[role]?.fallbacks;
+            if (JSON.stringify(af ?? []) !== JSON.stringify(bf ?? []))
+                keys.add(`roles.models.${role}.fallbacks`);
         }
         if (prev.reviewEngine?.mode !== next.reviewEngine?.mode)
             keys.add('reviewEngine.mode');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joekytc/dsh-swarm",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A governed swarm of six specialist DSH agents (orchestrator, planner, knowledge-base bridge, developer and two reviewers) that turns a requirement into a strict phase pipeline with machine-verified delivery evidence, review-gated merges, a full audit-log event stream and a live kanban tab; design inspired by the Hermes Agent kanban",
   "license": "MIT",
   "author": "joekytc",
@@ -96,4 +96,4 @@
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
   }
-}
+}