@co0ontty/wand 4.83.1 → 4.84.0

package/dist/harness-engine.d.ts

@@ -0,0 +1,110 @@
+import type { HarnessConfig, SessionProvider } from "./types.js";
+import type { Model, Api } from "@earendil-works/pi-ai";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+/** core = Wand 进程内跑 agent loop；cli = 既有 CLI runner。 */
+export type RunEngine = "core" | "cli";
+/** core 引擎首期只服务 pi：只有它的事件流与 Pi 官方 harness 同源。 */
+export declare const CORE_HARNESS_PROVIDERS: readonly SessionProvider[];
+export interface CoreHarnessStatus {
+    available: boolean;
+    /** 不可用或降级原因（人类可读，可直接给客户端展示）。 */
+    reason: string;
+    /** 已认证的 Pi provider 数。 */
+    providerCount: number;
+    /** 可用 chat 模型数。 */
+    modelCount: number;
+    /**
+     * 实际使用的 agent 目录。
+     */
+    agentDir: string;
+}
+export interface EngineResolution {
+    engine: RunEngine;
+    /** 选这个引擎的原因（降级时可直接给用户看）。 */
+    reason: string;
+}
+export declare class CoreHarnessUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface ResolvedCoreModel {
+    model: Model<Api>;
+    /** Pi 侧 provider id（anthropic / openai-codex / xai …），不是 Wand 的 session provider。 */
+    providerId: string;
+    modelId: string;
+    /** 该 provider 是否走订阅（用于 UI 提示与默认挑选偏好）。 */
+    subscription: boolean;
+}
+type PiAiModule = typeof import("@earendil-works/pi-ai");
+export declare function defaultCoreHarnessAgentDir(): string;
+export declare function coreHarnessAgentDir(config: Pick<HarnessConfig, "agentDir"> | undefined): string;
+/** 测试与配置热更新用：清掉懒加载句柄与状态缓存。 */
+export declare function resetCoreHarnessRuntime(): void;
+/** pi-ai 只在真正跑 core 会话时加载，纯 CLI 部署不付这份启动成本。 */
+export declare function loadPiAi(): Promise<PiAiModule>;
+type PiAgentCoreModule = typeof import("@earendil-works/pi-agent-core");
+type PiCodingAgentModule = typeof import("@earendil-works/pi-coding-agent");
+/** pi-agent-core 的 agent loop 只在第一次 core 回合时加载。 */
+export declare function loadPiAgentCore(): Promise<PiAgentCoreModule>;
+/** pi-coding-agent 提供已发布的工具实现、模型运行时与压缩原语。 */
+export declare function loadPiCodingAgent(): Promise<PiCodingAgentModule>;
+/** 已就绪的模型运行时（认证 + 模型目录）；失败抛错，由调用方决定降级。 */
+export declare function coreHarnessRuntime(config: Pick<HarnessConfig, "agentDir"> | undefined): Promise<ModelRuntime>;
+/**
+ * 读取 core 引擎可用性。失败不抛错：不可用时回退 CLI 是常态，
+ * 只有显式 `harness.engine = "core"` 才由调用方升级成错误。
+ */
+export declare function coreHarnessStatus(config: Pick<HarnessConfig, "agentDir"> | undefined, options?: {
+    force?: boolean;
+}): Promise<CoreHarnessStatus>;
+export interface EngineResolutionOptions {
+    forceStatus?: boolean;
+    /** 宿主已注入 core runner：视为 core 能力可用（测试与嵌入式宿主用）。 */
+    coreRunnerSupplied?: boolean;
+    /** 宿主已注入 pi 的 CLI runner：`auto` 不覆盖这个明确决定。 */
+    cliRunnerSupplied?: boolean;
+}
+export declare function decideHarnessEngine(config: Pick<HarnessConfig, "engine" | "agentDir"> | undefined, provider: SessionProvider | null | undefined, options: EngineResolutionOptions, status: CoreHarnessStatus | null): EngineResolution;
+/**
+ * 同步裁决执行引擎。
+ * `sendMessage` 必须在一个 tick 内完成 runner 注册，所以这里不做任何 await；
+ * 可用性来自后台预热的缓存，缓存未就绪时先走 CLI（下一轮自动切回 core）。
+ */
+export declare function resolveHarnessEngineSync(config: Pick<HarnessConfig, "engine" | "agentDir"> | undefined, provider: SessionProvider | null | undefined, options?: EngineResolutionOptions): EngineResolution;
+/**
+ * 异步裁决：需要等探测结果、或需要强制刷新时用（测试、运维接口）。
+ * 语义与 resolveHarnessEngineSync 一致。
+ */
+export declare function resolveHarnessEngine(config: Pick<HarnessConfig, "engine" | "agentDir"> | undefined, provider: SessionProvider | null | undefined, options?: EngineResolutionOptions): Promise<EngineResolution>;
+/**
+ * 缓存状态：**过期也照旧返回最后一次已知结果**，只在后台刷新。
+ * 引擎裁决是同步的（sendMessage 必须同 tick 注册 runner），如果过期就当“不可用”，
+ * 用户每隔一会儿发第一句就会被退回 CLI：那会让同一个会话在两个引擎之间跳。
+ */
+export declare function coreHarnessCachedStatus(config: Pick<HarnessConfig, "agentDir"> | undefined): CoreHarnessStatus | null;
+/** 后台预热：只读本地认证与模型目录，不联网，不阻塞调用方。 */
+export declare function primeCoreHarnessStatus(config: Pick<HarnessConfig, "agentDir"> | undefined): void;
+/**
+ * 启动预热：在服务开始接收输入前把能力探完，避免第一轮引擎裁决靠运气。
+ * 失败/超时都不影响启动（只是这一轮会按不可用处理）。
+ */
+export declare function warmCoreHarness(config: Pick<HarnessConfig, "engine" | "agentDir"> | undefined): Promise<CoreHarnessStatus | null>;
+/** 去掉 `provider/` 前缀，兼容 Wand 的 `provider/model` 选择器与裸模型 id。 */
+export declare function splitModelSelector(selector: string): {
+    providerId: string | null;
+    modelId: string;
+};
+/**
+ * 把 Wand 的模型选择器解析成 core 引擎真正要调的 Pi 模型。
+ * - 空 / `default`：先看 Pi settings 的 defaultModel，再退回可用模型（优先订阅）
+ * - `provider/model`：直接查；查不到再按 `provider/model` 全等匹配
+ * - 裸 id：在可用模型里按 id 匹配
+ * 不可用返回 null，由调用方降级或报错（订阅档位可能拒绝某个模型，那是运行期错误，不在这里过滤）。
+ */
+export declare function resolveCoreModel(config: Pick<HarnessConfig, "agentDir"> | undefined, selector: string | null | undefined, options?: {
+    cwd?: string;
+}): Promise<ResolvedCoreModel | null>;
+/** settings.json 的 defaultModel 允许带 `:<thinking>` 后缀，这里只取模型部分。 */
+export declare function coreModelSelector(config: Pick<HarnessConfig, "agentDir"> | undefined, selector: string | null | undefined): string;
+/** 上一次探测到的不可用原因；用于日志与降级提示，没有则返回空串。 */
+export declare function lastCoreHarnessFailure(): string;
+export {};

package/dist/harness-engine.js

@@ -0,0 +1,331 @@
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getErrorMessage } from "./error-utils.js";
+/** core 引擎首期只服务 pi：只有它的事件流与 Pi 官方 harness 同源。 */
+export const CORE_HARNESS_PROVIDERS = ["pi"];
+export class CoreHarnessUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CoreHarnessUnavailableError";
+    }
+}
+let piAiPromise = null;
+let handlePromise = null;
+let handleError = null;
+let cachedAgentDir = "";
+let statusCache = null;
+/** 正在进行的探测：并发调用共享同一次探测，不重复起多个。 */
+let refreshing = null;
+/** 状态缓存窗口：认证/模型目录变化由 Pi 自己写入磁盘，这里只避免高频探测。 */
+const STATUS_TTL_MS = 10 * 60 * 1000;
+/** 探测超时：core 预热不能拖住服务启动。 */
+const STATUS_PROBE_TIMEOUT_MS = 15_000;
+export function defaultCoreHarnessAgentDir() {
+    return process.env.PI_CODING_AGENT_DIR?.trim() || path.join(os.homedir(), ".pi", "agent");
+}
+export function coreHarnessAgentDir(config) {
+    const configured = config?.agentDir?.trim();
+    return configured ? configured : defaultCoreHarnessAgentDir();
+}
+/** 测试与配置热更新用：清掉懒加载句柄与状态缓存。 */
+export function resetCoreHarnessRuntime() {
+    handlePromise = null;
+    handleError = null;
+    statusCache = null;
+    refreshing = null;
+    cachedAgentDir = "";
+}
+/** pi-ai 只在真正跑 core 会话时加载，纯 CLI 部署不付这份启动成本。 */
+export function loadPiAi() {
+    if (!piAiPromise)
+        piAiPromise = import("@earendil-works/pi-ai");
+    return piAiPromise;
+}
+let piAgentCorePromise = null;
+let piCodingAgentPromise = null;
+/** pi-agent-core 的 agent loop 只在第一次 core 回合时加载。 */
+export function loadPiAgentCore() {
+    if (!piAgentCorePromise)
+        piAgentCorePromise = import("@earendil-works/pi-agent-core");
+    return piAgentCorePromise;
+}
+/** pi-coding-agent 提供已发布的工具实现、模型运行时与压缩原语。 */
+export function loadPiCodingAgent() {
+    if (!piCodingAgentPromise)
+        piCodingAgentPromise = import("@earendil-works/pi-coding-agent");
+    return piCodingAgentPromise;
+}
+/** 已就绪的模型运行时（认证 + 模型目录）；失败抛错，由调用方决定降级。 */
+export async function coreHarnessRuntime(config) {
+    const handle = await loadHandle(coreHarnessAgentDir(config));
+    return handle.runtime;
+}
+async function loadHandle(agentDir) {
+    if (handlePromise && cachedAgentDir === agentDir)
+        return handlePromise;
+    cachedAgentDir = agentDir;
+    handlePromise = (async () => {
+        const { ModelRuntime } = await import("@earendil-works/pi-coding-agent");
+        const runtime = await ModelRuntime.create({
+            authPath: path.join(agentDir, "auth.json"),
+            modelsPath: path.join(agentDir, "models.json"),
+        });
+        return { runtime, agentDir };
+    })();
+    return handlePromise;
+}
+/**
+ * 读取 core 引擎可用性。失败不抛错：不可用时回退 CLI 是常态，
+ * 只有显式 `harness.engine = "core"` 才由调用方升级成错误。
+ */
+export function coreHarnessStatus(config, options = {}) {
+    const agentDir = coreHarnessAgentDir(config);
+    const now = Date.now();
+    if (!options.force && statusCache && statusCache.agentDir === agentDir && now - statusCache.at < STATUS_TTL_MS) {
+        return Promise.resolve(statusCache.status);
+    }
+    if (!options.force && refreshing && refreshing.agentDir === agentDir)
+        return refreshing.promise;
+    const promise = probeCoreHarness(agentDir).then((status) => {
+        statusCache = { at: Date.now(), agentDir, status };
+        if (refreshing?.promise === promise)
+            refreshing = null;
+        return status;
+    });
+    refreshing = { agentDir, promise };
+    return promise;
+}
+async function probeCoreHarness(agentDir) {
+    let handle;
+    try {
+        handle = await loadHandle(agentDir);
+    }
+    catch (error) {
+        const reason = `无法初始化进程内 harness：${getErrorMessage(error)}`;
+        handleError = { at: Date.now(), reason, agentDir };
+        return { available: false, reason, providerCount: 0, modelCount: 0, agentDir };
+    }
+    try {
+        const available = await handle.runtime.getAvailable();
+        const providers = new Set(available.map((model) => model.provider));
+        if (available.length === 0) {
+            const reason = `Pi 侧没有可用认证（${path.join(agentDir, "auth.json")}）：先在 Pi 里 /login，或改 harness.engine 为 cli`;
+            handleError = { at: Date.now(), reason, agentDir };
+            return { available: false, reason, providerCount: 0, modelCount: 0, agentDir };
+        }
+        handleError = null;
+        return {
+            available: true,
+            reason: "",
+            providerCount: providers.size,
+            modelCount: available.length,
+            agentDir,
+        };
+    }
+    catch (error) {
+        const reason = `读取 core 引擎模型目录失败：${getErrorMessage(error)}`;
+        handleError = { at: Date.now(), reason, agentDir };
+        return { available: false, reason, providerCount: 0, modelCount: 0, agentDir };
+    }
+}
+export function decideHarnessEngine(config, provider, options, status) {
+    const engine = config?.engine ?? "auto";
+    if (engine === "cli")
+        return { engine: "cli", reason: "配置为 cli 引擎" };
+    if (!provider || !CORE_HARNESS_PROVIDERS.includes(provider)) {
+        if (engine === "core") {
+            throw new CoreHarnessUnavailableError(`core 引擎首期只支持 ${CORE_HARNESS_PROVIDERS.join(" / ")}，当前 provider 是 ${String(provider)}。`);
+        }
+        return { engine: "cli", reason: "core 引擎暂不支持该 provider" };
+    }
+    if (options.coreRunnerSupplied)
+        return { engine: "core", reason: "宿主注入了 core runner" };
+    if (engine !== "core" && options.cliRunnerSupplied) {
+        return { engine: "cli", reason: "宿主注入了 pi runner，auto 不覆盖" };
+    }
+    if (status?.available)
+        return { engine: "core", reason: "" };
+    // 上次探测的失败原因只在该 agentDir 下才有意义，不能把别处的错误当成这里的结论。
+    const shareableFailure = handleError && handleError.agentDir === coreHarnessAgentDir(config) ? handleError.reason : "";
+    const reason = status?.reason || shareableFailure || "core 引擎状态尚未就绪（已开始探测，下一轮会自动用上）";
+    if (engine === "core")
+        throw new CoreHarnessUnavailableError(reason);
+    return { engine: "cli", reason };
+}
+/**
+ * 同步裁决执行引擎。
+ * `sendMessage` 必须在一个 tick 内完成 runner 注册，所以这里不做任何 await；
+ * 可用性来自后台预热的缓存，缓存未就绪时先走 CLI（下一轮自动切回 core）。
+ */
+export function resolveHarnessEngineSync(config, provider, options = {}) {
+    const status = coreHarnessCachedStatus(config);
+    if (!status)
+        primeCoreHarnessStatus(config);
+    return decideHarnessEngine(config, provider, options, status);
+}
+/**
+ * 异步裁决：需要等探测结果、或需要强制刷新时用（测试、运维接口）。
+ * 语义与 resolveHarnessEngineSync 一致。
+ */
+export async function resolveHarnessEngine(config, provider, options = {}) {
+    const engine = config?.engine ?? "auto";
+    const needsStatus = engine !== "cli"
+        && !!provider && CORE_HARNESS_PROVIDERS.includes(provider)
+        && !options.coreRunnerSupplied
+        && !(engine !== "core" && options.cliRunnerSupplied);
+    const status = needsStatus ? await coreHarnessStatus(config, { force: options.forceStatus }) : coreHarnessCachedStatus(config);
+    return decideHarnessEngine(config, provider, options, status);
+}
+/**
+ * 缓存状态：**过期也照旧返回最后一次已知结果**，只在后台刷新。
+ * 引擎裁决是同步的（sendMessage 必须同 tick 注册 runner），如果过期就当“不可用”，
+ * 用户每隔一会儿发第一句就会被退回 CLI：那会让同一个会话在两个引擎之间跳。
+ */
+export function coreHarnessCachedStatus(config) {
+    const agentDir = coreHarnessAgentDir(config);
+    if (!statusCache || statusCache.agentDir !== agentDir)
+        return null;
+    if (Date.now() - statusCache.at >= STATUS_TTL_MS)
+        primeCoreHarnessStatus(config);
+    return statusCache.status;
+}
+/** 后台预热：只读本地认证与模型目录，不联网，不阻塞调用方。 */
+export function primeCoreHarnessStatus(config) {
+    void coreHarnessStatus(config).catch(() => undefined);
+}
+/**
+ * 启动预热：在服务开始接收输入前把能力探完，避免第一轮引擎裁决靠运气。
+ * 失败/超时都不影响启动（只是这一轮会按不可用处理）。
+ */
+export async function warmCoreHarness(config) {
+    if ((config?.engine ?? "auto") === "cli")
+        return null;
+    let timer = null;
+    try {
+        return await Promise.race([
+            coreHarnessStatus(config, { force: true }),
+            new Promise((resolve) => { timer = setTimeout(() => resolve(null), STATUS_PROBE_TIMEOUT_MS); }),
+        ]);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** 去掉 `provider/` 前缀，兼容 Wand 的 `provider/model` 选择器与裸模型 id。 */
+export function splitModelSelector(selector) {
+    const trimmed = selector.trim();
+    const separator = trimmed.indexOf("/");
+    if (separator <= 0)
+        return { providerId: null, modelId: trimmed };
+    // Bedrock / gateway 的模型 id 里带 `/`：只认第一段是已知 provider 前缀的情况由调用方兜底。
+    return { providerId: trimmed.slice(0, separator), modelId: trimmed.slice(separator + 1) };
+}
+function preferSubscription(runtime, models) {
+    for (const model of models) {
+        try {
+            if (runtime.isUsingSubscription(model.provider))
+                return model;
+        }
+        catch {
+            // 单个 provider 的订阅探测失败不影响挑选。
+        }
+    }
+    return models[0] ?? null;
+}
+/**
+ * 把 Wand 的模型选择器解析成 core 引擎真正要调的 Pi 模型。
+ * - 空 / `default`：先看 Pi settings 的 defaultModel，再退回可用模型（优先订阅）
+ * - `provider/model`：直接查；查不到再按 `provider/model` 全等匹配
+ * - 裸 id：在可用模型里按 id 匹配
+ * 不可用返回 null，由调用方降级或报错（订阅档位可能拒绝某个模型，那是运行期错误，不在这里过滤）。
+ */
+export async function resolveCoreModel(config, selector, options = {}) {
+    const handle = await loadHandle(coreHarnessAgentDir(config));
+    const runtime = handle.runtime;
+    const available = await runtime.getAvailable();
+    if (available.length === 0)
+        return null;
+    const wrap = (model) => ({
+        model,
+        providerId: model.provider,
+        modelId: model.id,
+        subscription: safeIsSubscription(runtime, model.provider),
+    });
+    const raw = (selector ?? "").trim();
+    if (!raw || raw === "default") {
+        const settingsDefault = readPiDefaultModel(handle);
+        if (settingsDefault) {
+            const match = await matchSelector(runtime, available, settingsDefault);
+            if (match)
+                return wrap(match);
+        }
+        const preferred = preferSubscription(runtime, available);
+        return preferred ? wrap(preferred) : null;
+    }
+    const match = await matchSelector(runtime, available, raw);
+    return match ? wrap(match) : null;
+}
+function safeIsSubscription(runtime, providerId) {
+    try {
+        return runtime.isUsingSubscription(providerId);
+    }
+    catch {
+        return false;
+    }
+}
+/** settings.json 的 defaultModel 允许带 `:<thinking>` 后缀，这里只取模型部分。 */
+export function coreModelSelector(config, selector) {
+    const raw = selector?.trim();
+    return raw && raw !== "default" ? raw : readPiDefaultModel({ agentDir: coreHarnessAgentDir(config) });
+}
+function readPiDefaultModel(handle) {
+    try {
+        const settingsPath = path.join(handle.agentDir, "settings.json");
+        const raw = readJsonIfExists(settingsPath);
+        const value = raw?.defaultModel;
+        if (typeof value !== "string")
+            return "";
+        const trimmed = value.trim();
+        const separator = trimmed.indexOf(":");
+        const id = (separator > 0 ? trimmed.slice(0, separator) : trimmed).trim();
+        const provider = typeof raw?.defaultProvider === "string" ? raw.defaultProvider.trim() : "";
+        return provider && !id.startsWith(`${provider}/`) ? `${provider}/${id}` : id;
+    }
+    catch {
+        return "";
+    }
+}
+function readJsonIfExists(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function matchSelector(runtime, available, selector) {
+    const { providerId, modelId } = splitModelSelector(selector);
+    if (providerId) {
+        const direct = runtime.getModel(providerId, modelId);
+        if (direct)
+            return direct;
+    }
+    const exact = available.find((model) => `${model.provider}/${model.id}` === selector);
+    if (exact)
+        return exact;
+    const byId = available.find((model) => model.id === modelId || model.id === selector);
+    if (byId)
+        return byId;
+    const bySuffix = available.find((model) => model.id.toLowerCase().endsWith(`/${modelId.toLowerCase()}`));
+    return bySuffix ?? null;
+}
+/** 上一次探测到的不可用原因；用于日志与降级提示，没有则返回空串。 */
+export function lastCoreHarnessFailure() {
+    return handleError?.reason ?? "";
+}

package/dist/mission-diff.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { buildChildEnv } from "./env-utils.js";
 import { runGit, runGitRaw } from "./git-utils.js";
 const DEFAULT_MAX_PATCH_BYTES = 2 * 1024 * 1024;
 function appendBounded(current, next, maxBytes) {
@@ -21,7 +22,7 @@ function untrackedPatch(cwd, relativePath) {
         cwd,
         encoding: "utf8",
         maxBuffer: DEFAULT_MAX_PATCH_BYTES,
-        env: { ...process.env, GIT_PAGER: "cat", PAGER: "cat", GIT_TERMINAL_PROMPT: "0" },
+        env: { ...buildChildEnv(true), GIT_PAGER: "cat", PAGER: "cat", GIT_TERMINAL_PROMPT: "0" },
     });
     if (result.status !== 0 && result.status !== 1) {
         throw new Error(result.stderr?.trim() || `无法读取未跟踪文件 diff：${relativePath}`);

package/dist/model-auto-assign.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 「智能分配」的结算：把选择器 + 第一条提示词变成这一次真正使用的模型分组。
+ *
+ * 顺序固定，每一步都可解释：
+ *   1. 该工具只有一个分组 → 直接用它（不需要判断）；
+ *   2. 系统运维员工的一次性文本调用（有窗口上限）：实测命中率明显高于本地模型，
+ *      而且只输出一个分组名，所以放在第一位；
+ *   3. 拿不到 AI 结论（没接入/超时/说不清）时，用本地决策模型（`localDecision`，
+ *      离线、毫秒级）在最多 4 个候选里选一个，并且必须**同一道题正反两种选项顺序
+ *      结论一致**才算数——这个离线模型有明确位置偏好（总挑最后一个选项）；
+ *   4. 都拿不到结论 → 用该工具的默认分组。
+ *
+ * 这里只做有界选择，不执行任何工具、不改会话历史、不写配置。
+ */
+import type { DecisionResult } from "./decision-types.js";
+import { type QuickCommitAiOptions } from "./git-quick-commit.js";
+import { type ModelGroup } from "./model-groups.js";
+import type { SessionProvider } from "./provider-catalog.js";
+import type { AiTextRequest } from "./types.js";
+export interface AutoAssignRequest {
+    provider: SessionProvider;
+    /** 第一条真实用户提示词；空串表示拿不到提示词，只能回落默认分组。 */
+    prompt: string;
+    groups: readonly ModelGroup[] | undefined;
+    /** 本地决策入口：生产用 DecisionService.evaluate，测试注入替身。 */
+    evaluate?: (value: unknown, caller: string, signal?: AbortSignal) => Promise<DecisionResult>;
+    /** 系统运维员工的一次性文本调用上下文；没给就不做 AI 回退。 */
+    ai?: QuickCommitAiOptions;
+    /** AI 回退的实际调用入口（测试注入替身）；默认走系统运维员工的 CLI 候选链。 */
+    aiCall?: (request: AiTextRequest, options: QuickCommitAiOptions) => Promise<string>;
+    cwd?: string;
+    language?: string;
+    signal?: AbortSignal;
+}
+export interface AutoAssignResult {
+    /** 本次实际使用的分组选择器；空串表示没有可用分组，仍用工具自己的默认模型。 */
+    selector: string;
+    group: ModelGroup | null;
+    strategy: "only" | "local" | "ai" | "default";
+    /** 决策模型给出的概率（选中项的 P）；仅作参考。 */
+    probability?: number;
+    calls: number;
+}
+/** AI 输出的分组名 → 候选分组。名称必须能唯一对上，否则抛错（让候选链继续，而不是猜）。 */
+export declare function parseGroupChoice(raw: string, candidates: readonly ModelGroup[], names: readonly string[]): ModelGroup;
+/**
+ * 把「智能分配」结算成本次使用的分组。任何失败都退化成默认分组，绝不抛错：
+ * 第一条消息不能因为选分组失败而被挡住。
+ */
+export declare function resolveAutoAssign(request: AutoAssignRequest): Promise<AutoAssignResult>;

package/dist/model-auto-assign.js

@@ -0,0 +1,163 @@
+import { getErrorMessage } from "./error-utils.js";
+import { callConfiguredAiText } from "./git-quick-commit.js";
+import { findModelGroup, modelGroupSelector } from "./model-groups.js";
+/** 本地决策一次最多比较多少个分组；候选更多就只信 AI 回退（更短的提示才稳）。 */
+const AUTO_ASSIGN_CHOICE_MAX = 4;
+/** 选项里嵌入的任务提示词上限（决策模型总窗口只有 1024 token）。 */
+const AUTO_ASSIGN_STATE_MAX = 600;
+/** 拿不准就别乱换：任一轮低于这个概率视为「没有明确偏好」，回落默认分组。 */
+const AUTO_ASSIGN_MIN_PROBABILITY = 0.4;
+/** AI 回退窗口：第一条消息不能为了选分组等到 CLI 链跑满 150s。 */
+const AUTO_ASSIGN_AI_BUDGET_MS = 15_000;
+const AUTO_ASSIGN_AI_PROMPT_MAX = 1200;
+/** 该工具可分配的分组：顺序即配置顺序，「默认分组」是自然回落项。 */
+function candidatesOf(groups, provider) {
+    return (groups ?? []).filter((group) => group.provider === provider);
+}
+/** 压平空白：提示词、分组名都要先变成单行再截断。 */
+function collapseWhitespace(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function firstModelText(group) {
+    const first = group.models[0]?.trim();
+    if (!first)
+        return "免费池自动顺序";
+    return first.split("/").pop()?.trim() || first;
+}
+/** 分组名可能很长；选项文本必须短，否则决策 worker 直接拒绝这道题。 */
+function shortLabel(value, max) {
+    const flat = value.replace(/\s+/g, " ").trim() || "分组";
+    return flat.length > max ? `${flat.slice(0, Math.max(1, max - 1))}…` : flat;
+}
+function uniqueLabels(groups, max) {
+    const used = new Set();
+    return groups.map((group) => {
+        const base = shortLabel(group.name, max);
+        let label = base;
+        for (let suffix = 2; used.has(label) && suffix < 100; suffix++)
+            label = `${base.slice(0, Math.max(1, max - 4))}·${suffix}`;
+        used.add(label);
+        return label;
+    });
+}
+function defaultGroupOf(groups, provider) {
+    return findModelGroup(groups, provider, "") ?? null;
+}
+function resultForGroup(group, strategy, calls, probability) {
+    return {
+        selector: group ? modelGroupSelector(group) : "",
+        group,
+        strategy,
+        calls,
+        ...(probability === undefined ? {} : { probability }),
+    };
+}
+/**
+ * 本地决策：一次「多选一」，并要求正反两种选项顺序给出同一个分组才算结论。
+ * 拿不准（选中项概率过低 / 两种顺序不一致）返回 null，交给下一层。
+ */
+async function decideLocally(evaluate, prompt, candidates, signal) {
+    if (candidates.length > AUTO_ASSIGN_CHOICE_MAX)
+        return null;
+    const task = collapseWhitespace(prompt).slice(0, AUTO_ASSIGN_STATE_MAX);
+    const askOnce = async (order) => {
+        const labels = uniqueLabels(order, 24);
+        const criteria = {};
+        for (const [index, group] of order.entries()) {
+            criteria[labels[index]] = `首选 ${shortLabel(firstModelText(group), 20)}`;
+        }
+        const result = await evaluate({
+            state: task,
+            questions: { group: { type: "choice", instructions: "按任务类型选一个最合适的模型分组", criteria } },
+        }, "auto-assign", signal);
+        const answer = result.answers?.group;
+        const choice = typeof answer?.choice === "string" ? answer.choice : "";
+        const index = labels.indexOf(choice);
+        if (index < 0)
+            return null;
+        const probability = Number(answer?.probabilities?.[choice] ?? 0);
+        if (!Number.isFinite(probability) || probability < AUTO_ASSIGN_MIN_PROBABILITY)
+            return null;
+        return { group: order[index], probability };
+    };
+    const forward = await askOnce(candidates);
+    if (!forward)
+        return null;
+    const reverse = await askOnce([...candidates].reverse());
+    if (!reverse || reverse.group.id !== forward.group.id)
+        return null;
+    return { group: forward.group, probability: Math.min(forward.probability, reverse.probability), calls: 2 };
+}
+/** AI 输出的分组名 → 候选分组。名称必须能唯一对上，否则抛错（让候选链继续，而不是猜）。 */
+export function parseGroupChoice(raw, candidates, names) {
+    const flat = collapseWhitespace(raw);
+    const exact = candidates.find((_group, index) => flat === names[index]);
+    if (exact)
+        return exact;
+    const matched = candidates.filter((group) => flat.includes(group.name));
+    if (matched.length === 1)
+        return matched[0];
+    throw new Error("AI 没有给出可识别的分组名。");
+}
+/** AI 回退：让系统运维员工的 CLI 候选链只输出一个分组名。 */
+async function decideWithAi(request, candidates) {
+    const ai = request.ai;
+    if (!ai)
+        return null;
+    const call = request.aiCall;
+    // 与 core runner 同一条单测安全约定：测试里没注入替身就不发真实 CLI 请求。
+    if (!call && process.env.NODE_TEST_CONTEXT)
+        return null;
+    const names = uniqueLabels(candidates, 40);
+    const list = candidates
+        .map((group, index) => `- ${names[index]}：首选 ${firstModelText(group)}（共 ${group.models.length} 个模型）`)
+        .join("\n");
+    const task = collapseWhitespace(request.prompt).slice(0, AUTO_ASSIGN_AI_PROMPT_MAX);
+    const system = "你要在若干个模型分组里为一次任务挑一个最合适的。只输出分组名本身，不要解释、不要标点、不要 Markdown。";
+    const message = `任务提示词：\n${task}\n\n可选模型分组：\n${list}\n\n只输出上面列出的分组名之一；都不合适就输出 -。`;
+    const text = call
+        ? await call({ system, prompt: message }, ai)
+        : await callConfiguredAiText({ system, prompt: message }, request.cwd ?? process.cwd(), request.language ?? "", { ...ai, budgetMs: AUTO_ASSIGN_AI_BUDGET_MS }, (raw) => String(raw).trim());
+    const flat = collapseWhitespace(text);
+    if (!flat || flat === "-" || flat === "无")
+        return { group: null, calls: 1 };
+    return { group: parseGroupChoice(flat, candidates, names), calls: 1 };
+}
+/**
+ * 把「智能分配」结算成本次使用的分组。任何失败都退化成默认分组，绝不抛错：
+ * 第一条消息不能因为选分组失败而被挡住。
+ */
+export async function resolveAutoAssign(request) {
+    const candidates = candidatesOf(request.groups, request.provider);
+    if (!candidates.length)
+        return resultForGroup(null, "default", 0);
+    if (candidates.length === 1)
+        return resultForGroup(candidates[0], "only", 0);
+    const prompt = request.prompt?.trim() ?? "";
+    if (prompt) {
+        let aiCalls = 0;
+        if (request.ai) {
+            try {
+                const decided = await decideWithAi(request, candidates);
+                aiCalls = decided?.calls ?? 1;
+                if (decided?.group)
+                    return resultForGroup(decided.group, "ai", aiCalls);
+            }
+            catch (error) {
+                aiCalls = 1;
+                console.warn(`[AutoAssign] 系统员工未能给出分组：${getErrorMessage(error)}`);
+            }
+        }
+        if (request.evaluate) {
+            try {
+                const local = await decideLocally(request.evaluate, prompt, candidates, request.signal);
+                if (local)
+                    return resultForGroup(local.group, "local", local.calls + aiCalls, local.probability);
+            }
+            catch (error) {
+                console.warn(`[AutoAssign] 本地决策未能给出分组：${getErrorMessage(error)}`);
+            }
+        }
+    }
+    return resultForGroup(defaultGroupOf(request.groups, request.provider), "default", 0);
+}

package/dist/model-group-runner.d.ts

@@ -0,0 +1,4 @@
+import type { WandConfig } from "./types.js";
+import type { StructuredRunnerAdapter } from "./structured-runner.js";
+/** Resolve at execution time; persist the selection, normalize attempt facts even without a group. */
+export declare function withModelGroups(runner: StructuredRunnerAdapter, config: WandConfig): StructuredRunnerAdapter;