minimal-agent 0.12.0 → 0.14.0

package/src/main.js

@@ -36,6 +36,7 @@ import { runPrintMode } from './cli/print.js';
 import { runStreamJsonMode } from './cli/streamJson.js';
 import { extractFlagValue, normalizeArgs } from './cli/args.js';
 import { resolveComputerUseMode, resolveComputerUseTraceDir } from './cli/computerUse.js';
+import { runTeamCommand } from './team/cli.js';
 // re-export：对外保持「main.tsx 提供 extractFlagValue」的语义；实现住在 cli/args.ts，
 // 这样单测可零副作用 import（main.tsx 顶层 main() 自调用会启动整个 app，不可被测试 import）。
 export { extractFlagValue };
@@ -71,6 +72,8 @@ async function main() {
         console.log(`minimal-agent v${pkg.version}`);
         return;
     }
+    if (await runTeamCommand(args))
+        return;
     if (args.includes('--workspace-doctor')) {
         const snapshot = await workspaceIndexService.snapshot();
         console.log(`Workspace Index v${snapshot.version} · revision ${snapshot.revision}`);
@@ -101,7 +104,7 @@ async function main() {
             : rawFormat === 'stream-json'
                 ? 'stream-json'
                 : 'text';
-        // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 50）
+        // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 200）
         const rawMaxTurns = extractFlagValue(args, ['--max-turns']);
         const parsedMaxTurns = rawMaxTurns !== undefined ? Number.parseInt(rawMaxTurns, 10) : Number.NaN;
         const maxTurns = Number.isNaN(parsedMaxTurns) ? undefined : parsedMaxTurns;

package/src/main.tsx

@@ -66,6 +66,7 @@ import { runPrintMode } from './cli/print.js';
 import { runStreamJsonMode } from './cli/streamJson.js';
 import { extractFlagValue, normalizeArgs } from './cli/args.js';
 import { resolveComputerUseMode, resolveComputerUseTraceDir } from './cli/computerUse.js';
+import { runTeamCommand } from './team/cli.js';
 
 // re-export：对外保持「main.tsx 提供 extractFlagValue」的语义；实现住在 cli/args.ts，
 // 这样单测可零副作用 import（main.tsx 顶层 main() 自调用会启动整个 app，不可被测试 import）。
@@ -108,6 +109,8 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (await runTeamCommand(args)) return;
+
   if (args.includes('--workspace-doctor')) {
     const snapshot = await workspaceIndexService.snapshot();
     console.log(`Workspace Index v${snapshot.version} · revision ${snapshot.revision}`);
@@ -143,7 +146,7 @@ async function main(): Promise<void> {
         : rawFormat === 'stream-json'
           ? 'stream-json'
           : 'text';
-    // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 50）
+    // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 200）
     const rawMaxTurns = extractFlagValue(args, ['--max-turns']);
     const parsedMaxTurns = rawMaxTurns !== undefined ? Number.parseInt(rawMaxTurns, 10) : Number.NaN;
     const maxTurns = Number.isNaN(parsedMaxTurns) ? undefined : parsedMaxTurns;

package/src/managedExecution/index.js

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './registry.js';

package/src/managedExecution/index.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './registry.js';

package/src/managedExecution/registry.js

@@ -0,0 +1,15 @@
+import { prepareGoalCommand } from '../goal/workflowController.js';
+const CONTROLLERS = {
+    goal: (inputs, options) => {
+        const context = (options.context ?? {});
+        return prepareGoalCommand(inputs, {
+            ...context,
+            cwd: options.cwd,
+            runtimeContext: options.runtimeContext,
+        });
+    },
+};
+/** 业务运行时注册在内核控制层；Workflow Runner 只按声明请求适配器。 */
+export function managedCommandController(kind) {
+    return CONTROLLERS[kind] ?? null;
+}

package/src/managedExecution/registry.ts

@@ -0,0 +1,20 @@
+import { prepareGoalCommand } from '../goal/workflowController.js';
+import type { ManagedCommandController } from './types.js';
+
+const CONTROLLERS: Readonly<Record<string, ManagedCommandController>> = {
+  goal: (inputs, options) => {
+    const context = (options.context ?? {}) as Partial<
+      Parameters<typeof prepareGoalCommand>[1]
+    >;
+    return prepareGoalCommand(inputs, {
+      ...context,
+      cwd: options.cwd,
+      runtimeContext: options.runtimeContext,
+    });
+  },
+};
+
+/** 业务运行时注册在内核控制层；Workflow Runner 只按声明请求适配器。 */
+export function managedCommandController(kind: string): ManagedCommandController | null {
+  return CONTROLLERS[kind] ?? null;
+}

package/src/managedExecution/types.js

@@ -0,0 +1 @@
+export {};

package/src/managedExecution/types.ts

@@ -0,0 +1,86 @@
+import type { AgentRuntimeContext, LoopEvent } from '../plugin-sdk.js';
+
+export type ManagedAttemptResult = 'stopped' | 'failed' | 'verified';
+
+/** Workflow Runner 只认识这个通用执行租约，不认识 Goal、群任务或业务契约。 */
+export interface ManagedExecutionContext {
+  executionId: string;
+  version: number;
+  runId: string;
+  anchor: string;
+  correlations?: Record<string, string>;
+}
+
+/**
+ * 一次记账之后的累计快照。故意只有「已花多少 / 上限多少」这两件事 ——
+ * 它是**执行租约的资源核算**，不是 Goal 的业务语义，Runner 不需要知道
+ * 后面是 Goal、群任务还是别的什么。
+ */
+export interface ManagedResourceSnapshot {
+  inputTokens: number;
+  outputTokens: number;
+  /** `null` = 没设上限。⚠️ 不要用 0 表示无限，那会被判成「一开始就超了」。 */
+  limit: number | null;
+}
+
+export interface ManagedExecutionBridge {
+  updateContract(input: unknown): Promise<{
+    version: number;
+    anchor: string;
+    value?: unknown;
+  }>;
+  /**
+   * 记一笔资源消耗，返回**累计后**的快照。
+   *
+   * ⚠️ 累计值必须由外层控制器持久化（Goal 侧是 `goal.usage`），不能只存在进程内：
+   * 断点续跑时账本重放**不会重新执行** agent/llm 调用，进程内计数会从 0 开始，
+   * 于是「已经花掉的钱」凭空消失、预算闸永远不触发。
+   *
+   * 可选：没有外层控制器时（普通 `/workflow` 调用）引擎自己在进程内累计。
+   */
+  recordUsage?(input: {
+    inputTokens: number;
+    outputTokens: number;
+  }): Promise<ManagedResourceSnapshot>;
+  /**
+   * 收尾。返回值里的 `status` 是**外层运行时收尾后的生命周期状态**
+   * （Goal 侧就是 `Goal.status`），Runner 只把它原样透出给宿主，不解释含义。
+   *
+   * ⚠️ 它与 Runner 自己传进去的 `status`（attempt 结局）**不是一回事**：
+   * 传进去 `verified` 完全可能得到 `ready_for_acceptance` —— 机器自检通过，
+   * 但还没有人验收。宿主要区分这两者，所以必须原样透出而不是就地丢弃。
+   */
+  finish(input: {
+    status: ManagedAttemptResult;
+    artifacts?: string[];
+    evidence?: string[];
+    blocker?: string;
+    /**
+     * 工作流脚本自己贴的结局标签（如 `'budget_limited'`）。Runner **不解释**它的含义，
+     * 原样透传——具体是谁在解释、精化成什么真实状态是外层业务运行时（Goal 等）的事。
+     * 工作流可在抛出的 Error 上挂一个 `workflowOutcome` 属性，runner 读到后原样
+     * 转发；没有这个属性就是普通失败。该通道与具体工作流业务保持无关。
+     */
+    outcome?: string;
+  }): Promise<{ status?: string } | unknown>;
+}
+
+export interface PreparedManagedCommand {
+  handled: boolean;
+  events: LoopEvent[];
+  inputs: Record<string, unknown>;
+  execution?: ManagedExecutionContext;
+  bridge?: ManagedExecutionBridge;
+}
+
+export interface ManagedCommandOptions {
+  cwd: string;
+  runtimeContext?: AgentRuntimeContext;
+  /** 外层控制器自己的不透明上下文；Runner 不读取其中字段。 */
+  context?: unknown;
+}
+
+export type ManagedCommandController = (
+  inputs: Record<string, unknown>,
+  options: ManagedCommandOptions,
+) => Promise<PreparedManagedCommand>;

package/src/modelRef.js

@@ -0,0 +1,9 @@
+/** Compatibility is kept at the CLI/Web protocol edge only. */
+export function modelRefFromLegacy(value, serverId = 'gateway') {
+    return value.startsWith('online:')
+        ? { source: 'gateway', serverId, modelId: value.slice('online:'.length) }
+        : { source: 'local', modelId: value };
+}
+export function legacyModelId(ref) {
+    return ref.source === 'gateway' ? `online:${ref.modelId}` : ref.modelId;
+}

package/src/modelRef.ts

@@ -0,0 +1,31 @@
+/** Source-aware model identity shared by Desktop, TUI and the local Agent. */
+export type ModelRef =
+  | { source: 'local'; modelId: string }
+  | { source: 'gateway'; serverId: string; modelId: string };
+
+/** Compatibility is kept at the CLI/Web protocol edge only. */
+export function modelRefFromLegacy(value: string, serverId = 'gateway'): ModelRef {
+  return value.startsWith('online:')
+    ? { source: 'gateway', serverId, modelId: value.slice('online:'.length) }
+    : { source: 'local', modelId: value };
+}
+
+export function legacyModelId(ref: ModelRef): string {
+  return ref.source === 'gateway' ? `online:${ref.modelId}` : ref.modelId;
+}
+
+export type ModelFallbackReason =
+  | 'offline'
+  | 'logged_out'
+  | 'grant_revoked'
+  | 'quota_exhausted'
+  | 'model_disabled'
+  | 'credential_expired'
+  | null;
+
+export interface SessionModelPreference {
+  preferred: ModelRef | null;
+  effective: ModelRef | null;
+  fallbackReason: ModelFallbackReason;
+  restoreWhenAvailable: boolean;
+}

package/src/multimodal.js

@@ -7,11 +7,12 @@
  *  Chat Completions 的 content blocks。
  * ============================================================
  */
-import { readFile, stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getWorkingDir } from './bootstrap/workingDir.js';
 import { removeManagedClipboardTemp } from './utils/clipboardImage.js';
+import { detectImageMime, resolveLocalImage, } from './images/imageResolver.js';
 export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
 const IMAGE_MIME_BY_EXT = {
     '.jpg': 'image/jpeg',
@@ -22,8 +23,14 @@ const IMAGE_MIME_BY_EXT = {
     // Read can attach BMP files directly even though inline drag/drop parsing
     // intentionally remains limited to formats accepted by most providers.
     '.bmp': 'image/bmp',
+    '.tif': 'image/tiff',
+    '.tiff': 'image/tiff',
+    '.avif': 'image/avif',
+    '.heic': 'image/heic',
+    '.heif': 'image/heic',
+    '.svg': 'image/svg+xml',
 };
-const IMAGE_EXT_PATTERN = String.raw `(?:png|jpe?g|gif|webp)`;
+const IMAGE_EXT_PATTERN = String.raw `(?:png|jpe?g|gif|webp|bmp|tiff?|avif|hei[cf]|svg)`;
 /**
  * 「路径 token」允许的字符：非空白，或 `\x` 这样的转义对——macOS Terminal / iTerm2
  * 拖入文件时空格默认转义成 `\ `，不认它就会把 `/Users/me/My\ Pic.png` 切成两半。
@@ -231,39 +238,18 @@ export async function imageToContentPart(input) {
  * 仅按扩展名查会误判「不支持」而拒图——魔数嗅探让任意扩展名的真图都能用。
  */
 export function sniffImageMime(buf) {
-    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
-        return 'image/png';
-    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
-        return 'image/jpeg';
-    if (buf.length >= 4 && buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38)
-        return 'image/gif';
-    if (buf.length >= 12 &&
-        buf.toString('ascii', 0, 4) === 'RIFF' &&
-        buf.toString('ascii', 8, 12) === 'WEBP')
-        return 'image/webp';
-    return null;
+    return detectImageMime(buf);
 }
 async function imageSourceToUrl(source) {
     const clean = stripWrappingQuotes(source.trim());
     if (isHttpUrl(clean) || clean.startsWith('data:image/'))
         return clean;
     const filePath = resolveImagePath(clean);
-    const st = await stat(filePath).catch((e) => {
-        throw new Error(`无法读取图片：${source}（${e.message}）`);
+    const resolved = await resolveLocalImage(filePath, {
+        maxOutputBytes: MAX_IMAGE_BYTES,
     });
-    if (!st.isFile())
-        throw new Error(`图片路径不是文件：${source}`);
-    if (st.size > MAX_IMAGE_BYTES) {
-        throw new Error(`图片过大：${source} ${(st.size / 1024 / 1024).toFixed(1)}MB，` +
-            `OpenAI 兼容接口单图上限按 10MB 处理。`);
-    }
-    const data = await readFile(filePath);
-    // 先按扩展名查 MIME；认不出（无扩展名 / .img / 扩展名错）再按文件头魔数嗅探，都不认才拒。
-    const mime = IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? sniffImageMime(data);
-    if (!mime) {
-        throw new Error(`不支持的图片格式：${source}。仅支持 JPEG/PNG/GIF/WEBP（按扩展名与文件头都未识别）。`);
-    }
-    return `data:${mime};base64,${data.toString('base64')}`;
+    const data = await readFile(resolved.path);
+    return `data:${resolved.mime};base64,${data.toString('base64')}`;
 }
 function resolveImagePath(source) {
     if (source.startsWith('file://'))

package/src/multimodal.ts

@@ -8,7 +8,7 @@
  * ============================================================
  */
 
-import { readFile, stat } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -20,6 +20,10 @@ import type {
   Message,
 } from './types.js';
 import { removeManagedClipboardTemp } from './utils/clipboardImage.js';
+import {
+  detectImageMime,
+  resolveLocalImage,
+} from './images/imageResolver.js';
 
 export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
 
@@ -32,9 +36,15 @@ const IMAGE_MIME_BY_EXT: Record<string, string> = {
   // Read can attach BMP files directly even though inline drag/drop parsing
   // intentionally remains limited to formats accepted by most providers.
   '.bmp': 'image/bmp',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.avif': 'image/avif',
+  '.heic': 'image/heic',
+  '.heif': 'image/heic',
+  '.svg': 'image/svg+xml',
 };
 
-const IMAGE_EXT_PATTERN = String.raw`(?:png|jpe?g|gif|webp)`;
+const IMAGE_EXT_PATTERN = String.raw`(?:png|jpe?g|gif|webp|bmp|tiff?|avif|hei[cf]|svg)`;
 
 /**
  * 「路径 token」允许的字符：非空白，或 `\x` 这样的转义对——macOS Terminal / iTerm2
@@ -285,18 +295,7 @@ export async function imageToContentPart(
  * 仅按扩展名查会误判「不支持」而拒图——魔数嗅探让任意扩展名的真图都能用。
  */
 export function sniffImageMime(buf: Buffer): string | null {
-  if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
-    return 'image/png';
-  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
-  if (buf.length >= 4 && buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38)
-    return 'image/gif';
-  if (
-    buf.length >= 12 &&
-    buf.toString('ascii', 0, 4) === 'RIFF' &&
-    buf.toString('ascii', 8, 12) === 'WEBP'
-  )
-    return 'image/webp';
-  return null;
+  return detectImageMime(buf);
 }
 
 async function imageSourceToUrl(source: string): Promise<string> {
@@ -304,26 +303,11 @@ async function imageSourceToUrl(source: string): Promise<string> {
   if (isHttpUrl(clean) || clean.startsWith('data:image/')) return clean;
 
   const filePath = resolveImagePath(clean);
-  const st = await stat(filePath).catch((e) => {
-    throw new Error(`无法读取图片：${source}（${(e as Error).message}）`);
+  const resolved = await resolveLocalImage(filePath, {
+    maxOutputBytes: MAX_IMAGE_BYTES,
   });
-  if (!st.isFile()) throw new Error(`图片路径不是文件：${source}`);
-  if (st.size > MAX_IMAGE_BYTES) {
-    throw new Error(
-      `图片过大：${source} ${(st.size / 1024 / 1024).toFixed(1)}MB，` +
-        `OpenAI 兼容接口单图上限按 10MB 处理。`,
-    );
-  }
-
-  const data = await readFile(filePath);
-  // 先按扩展名查 MIME；认不出（无扩展名 / .img / 扩展名错）再按文件头魔数嗅探，都不认才拒。
-  const mime = IMAGE_MIME_BY_EXT[extname(filePath).toLowerCase()] ?? sniffImageMime(data);
-  if (!mime) {
-    throw new Error(
-      `不支持的图片格式：${source}。仅支持 JPEG/PNG/GIF/WEBP（按扩展名与文件头都未识别）。`,
-    );
-  }
-  return `data:${mime};base64,${data.toString('base64')}`;
+  const data = await readFile(resolved.path);
+  return `data:${resolved.mime};base64,${data.toString('base64')}`;
 }
 
 function resolveImagePath(source: string): string {

package/src/net/lanDiscovery.js

@@ -0,0 +1,65 @@
+/**
+ * 局域网发现的**线上格式**——服务端（响应器）与 Desktop（探测器）共用这一份。
+ *
+ * 为什么共享而不是各写一份：这是跨进程、跨机器的字节协议，两份编解码必然漂移，
+ * 而漂移的表现是"搜不到，但两边日志都正常"，极难排查。
+ * （本仓刚因为"服务端与前端各一份任务状态机"吃过亏，同一个教训。）
+ *
+ * 形态：**响应式**，不是周期广播。
+ *   客户端 ──UDP 广播──▶ :5277   `KAKADEAI-DISCOVER/1`
+ *   服务端 ──UDP 单播──▶ `KAKADEAI-ANNOUNCE/1 {json}`
+ * 没人找的时候零流量，也不需要加入组播组（组播在很多企业交换机上被关掉）。
+ *
+ * **地址由客户端用回包的源 IP 拼**，服务端不自报地址——它不可靠地知道自己
+ * 对外是哪个网卡/哪个地址（多网卡、容器、NAT 都会让自报值是错的）。
+ *
+ * 安全口径：发现只暴露"这里有一台 minimal-server"，**不授予任何访问权**，
+ * 之后仍需邀请码注册 + 登录。所以公告包里**绝不能**出现用户数据、群名、账号数量。
+ */
+/** 与既有端口同族：5274 web / 5276 node 控制面 / 5277 发现。 */
+export const DISCOVERY_PORT = 5277;
+/** UDP 上什么都可能收到，超过这个尺寸一律丢弃，不浪费 CPU 去解析。 */
+export const MAX_PACKET_BYTES = 512;
+const PROBE_MAGIC = 'KAKADEAI-DISCOVER/1';
+const ANNOUNCE_MAGIC = 'KAKADEAI-ANNOUNCE/1';
+export function encodeProbe() {
+    return Buffer.from(PROBE_MAGIC, 'utf8');
+}
+/** 严格相等匹配：魔数带版本号，将来改格式直接换版本，不做模糊兼容。 */
+export function parseProbe(packet) {
+    if (packet.length === 0 || packet.length > MAX_PACKET_BYTES)
+        return false;
+    return packet.toString('utf8') === PROBE_MAGIC;
+}
+export function encodeAnnounce(info) {
+    return Buffer.from(`${ANNOUNCE_MAGIC} ${JSON.stringify(info)}`, 'utf8');
+}
+/** 解析失败一律返回 null，**绝不抛异常**：这是喂给 UDP 回调的，抛了就炸整个进程。 */
+export function parseAnnounce(packet) {
+    if (packet.length === 0 || packet.length > MAX_PACKET_BYTES)
+        return null;
+    const text = packet.toString('utf8');
+    if (!text.startsWith(`${ANNOUNCE_MAGIC} `))
+        return null;
+    try {
+        const parsed = JSON.parse(text.slice(ANNOUNCE_MAGIC.length + 1));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const { name, version, protocolVersion, webPort, instanceId } = parsed;
+        // 逐字段校验：伪造包与版本漂移都会在这里被拦掉，而不是带着 undefined 往下走。
+        if (name !== 'minimal-server')
+            return null;
+        if (typeof version !== 'string' || !version)
+            return null;
+        if (typeof protocolVersion !== 'number' || !Number.isInteger(protocolVersion))
+            return null;
+        if (typeof webPort !== 'number' || !Number.isInteger(webPort) || webPort < 1 || webPort > 65535)
+            return null;
+        if (typeof instanceId !== 'string' || !instanceId)
+            return null;
+        return { name, version, protocolVersion, webPort, instanceId };
+    }
+    catch {
+        return null;
+    }
+}

package/src/net/lanDiscovery.ts

@@ -0,0 +1,82 @@
+/**
+ * 局域网发现的**线上格式**——服务端（响应器）与 Desktop（探测器）共用这一份。
+ *
+ * 为什么共享而不是各写一份：这是跨进程、跨机器的字节协议，两份编解码必然漂移，
+ * 而漂移的表现是"搜不到，但两边日志都正常"，极难排查。
+ * （本仓刚因为"服务端与前端各一份任务状态机"吃过亏，同一个教训。）
+ *
+ * 形态：**响应式**，不是周期广播。
+ *   客户端 ──UDP 广播──▶ :5277   `KAKADEAI-DISCOVER/1`
+ *   服务端 ──UDP 单播──▶ `KAKADEAI-ANNOUNCE/1 {json}`
+ * 没人找的时候零流量，也不需要加入组播组（组播在很多企业交换机上被关掉）。
+ *
+ * **地址由客户端用回包的源 IP 拼**，服务端不自报地址——它不可靠地知道自己
+ * 对外是哪个网卡/哪个地址（多网卡、容器、NAT 都会让自报值是错的）。
+ *
+ * 安全口径：发现只暴露"这里有一台 minimal-server"，**不授予任何访问权**，
+ * 之后仍需邀请码注册 + 登录。所以公告包里**绝不能**出现用户数据、群名、账号数量。
+ */
+
+/** 与既有端口同族：5274 web / 5276 node 控制面 / 5277 发现。 */
+export const DISCOVERY_PORT = 5277;
+
+/** UDP 上什么都可能收到，超过这个尺寸一律丢弃，不浪费 CPU 去解析。 */
+export const MAX_PACKET_BYTES = 512;
+
+const PROBE_MAGIC = 'KAKADEAI-DISCOVER/1';
+const ANNOUNCE_MAGIC = 'KAKADEAI-ANNOUNCE/1';
+
+/**
+ * 公告内容。**只允许放这几个字段**——多一个都可能变成信息泄露。
+ * 尤其不能出现用户数、群名、账号信息：发现只说明"这里有一台服务器"。
+ */
+export interface DiscoveryAnnounce {
+  name: 'minimal-server';
+  version: string;
+  /** 与 /api/health 的 protocolVersion 同义，供客户端判兼容性。 */
+  protocolVersion: number;
+  /** web 协作服务端口；客户端拼 `http://<回包源IP>:<webPort>`。 */
+  webPort: number;
+  /**
+   * 本次进程启动生成的随机实例标识。**唯一用途是让客户端把同一台服务器的多个网卡地址
+   * 归并成一条**——多网卡机器（VPN/VMware/WSL）会从每张网卡各回一次，
+   * 不归并的话 UI 上一台服务器显示成五条。
+   * 它不是凭据、不参与鉴权、每次重启都变，泄露无害。
+   */
+  instanceId: string;
+}
+
+export function encodeProbe(): Buffer {
+  return Buffer.from(PROBE_MAGIC, 'utf8');
+}
+
+/** 严格相等匹配：魔数带版本号，将来改格式直接换版本，不做模糊兼容。 */
+export function parseProbe(packet: Buffer): boolean {
+  if (packet.length === 0 || packet.length > MAX_PACKET_BYTES) return false;
+  return packet.toString('utf8') === PROBE_MAGIC;
+}
+
+export function encodeAnnounce(info: DiscoveryAnnounce): Buffer {
+  return Buffer.from(`${ANNOUNCE_MAGIC} ${JSON.stringify(info)}`, 'utf8');
+}
+
+/** 解析失败一律返回 null，**绝不抛异常**：这是喂给 UDP 回调的，抛了就炸整个进程。 */
+export function parseAnnounce(packet: Buffer): DiscoveryAnnounce | null {
+  if (packet.length === 0 || packet.length > MAX_PACKET_BYTES) return null;
+  const text = packet.toString('utf8');
+  if (!text.startsWith(`${ANNOUNCE_MAGIC} `)) return null;
+  try {
+    const parsed: unknown = JSON.parse(text.slice(ANNOUNCE_MAGIC.length + 1));
+    if (!parsed || typeof parsed !== 'object') return null;
+    const { name, version, protocolVersion, webPort, instanceId } = parsed as Record<string, unknown>;
+    // 逐字段校验：伪造包与版本漂移都会在这里被拦掉，而不是带着 undefined 往下走。
+    if (name !== 'minimal-server') return null;
+    if (typeof version !== 'string' || !version) return null;
+    if (typeof protocolVersion !== 'number' || !Number.isInteger(protocolVersion)) return null;
+    if (typeof webPort !== 'number' || !Number.isInteger(webPort) || webPort < 1 || webPort > 65535) return null;
+    if (typeof instanceId !== 'string' || !instanceId) return null;
+    return { name, version, protocolVersion, webPort, instanceId };
+  } catch {
+    return null;
+  }
+}

package/src/plugin-sdk.js

@@ -44,11 +44,17 @@ export { dlog } from './utils/debugLog.js';
 // <think> 思维链剥离：内核与 workflow-runner 共享（原住 agentCommon.ts，
 // Agent 子任务工具也需要 → 上移内核，插件经此 re-export）。
 export { stripThinkBlocks } from './utils/stripThink.js';
-// buildFullSystemPrompt is retained for compatibility. New long-running hosts should keep
-// buildBaseSystemPrompt stable and pass buildTransientContext separately for each turn.
-export { buildBaseSystemPrompt, buildTransientContext, buildTransientPromptBundle, } from './prompts/system.js';
+// 长驻宿主保持 buildBaseSystemPrompt 稳定，每回合单独传 transient bundle。
+// （`buildTransientContext` 曾也在这里 re-export，唯一消费者是已删除的 yaml 引擎；
+// 门面每多一个导出就多一条不能自由重构的边，没消费者就先不导出。）
+export { buildBaseSystemPrompt, buildTransientPromptBundle, } from './prompts/system.js';
+export { refreshStableSystemPrompt, upsertStableSystemMessage, } from './prompts/stableSystemPrompt.js';
 export { createAgentRuntimeContext, filterToolsForRuntime, } from './runtime/agentRuntimeContext.js';
 export { getResourceSearchPaths } from './utils/resourcePaths.js';
+// 「这个路径在不在那个目录里」的唯一实现——已经被手写错过好几次（含
+// workflow-runner 自己的两份，Windows 跨盘符时会误判成"在目录内"）。插件凡是要
+// 做路径包含判定，一律经这里，不要再手写一遍。
+export { pathContains } from './utils/pathContains.js';
 // 确定性检查设施：verify 步（shell/file_exists/file_contains/test_count）经此跑校验。
 export { parseCheckString, runVerification } from './infra/verification.js';
 export { triggerHook } from './plugins/hookEngine.js';
@@ -57,3 +63,22 @@ export { createSessionState } from './session/sessionState.js';
 // cron-runner 等需要在发起回合前判断"绑定的 session 是否还在"时用它，
 // 不要绕过 legacy 回退逻辑自己拼路径。
 export { resolveSessionFile } from './context/sessionPath.js';
+/**
+ * 按模型 id 解析出一个 Provider（工作流的 `agent(..., { model })` 用）。
+ *
+ * ⚠️ 门面只暴露这一个**语义明确的解析函数**，不暴露整个 ConfigService ——
+ * 后者带着读写配置、草稿、顾问设置一大堆能力，插件不该拿到，而门面每多一个
+ * 导出就多一条不能自由重构的边（`test/pluginSdkSurface.test.ts` 守这条）。
+ *
+ * 解析不到（id 不存在 / 该条目没填 apiKey）返回 null —— 调用方**必须**回落到
+ * 基座 provider 并如实告警，不能静默换模型。
+ */
+export async function resolveProviderForModel(modelId) {
+    const { configService } = await import('./config/configService.js');
+    return configService.providerForModel(modelId);
+}
+/** Resolve a portable workflow capability role through this machine's config. */
+export async function resolveProviderForWorkflowRole(role) {
+    const { configService } = await import('./config/configService.js');
+    return configService.providerForWorkflowRole(role);
+}