@armadra/agent 0.7.4 → 0.7.6

package/dist/ai/json-body.js

@@ -11,6 +11,10 @@
  * 键、`[`）与已验证无需转义的大字符串（需要转义的大字符串整个交给原生）；`toJSON`、`undefined` /
  * 函数 / symbol 的跳过与 `null`、数字格式、转义全部由原生处理（带 `toJSON` 的值经单键容器序列化，
  * 保证 `toJSON(key)` 收到与原生相同的键）。
+ *
+ * 图片由转换器包成 {@link LargeString}（`prefix + text`）：片段路径直接写转录里的原字符串，不经模板串
+ * 拼接后的扁平化；无需转义的结论与字节数按 ImageBlock 缓存，同一张图每进程只扫一次。流式发送时大片段
+ * 按 {@link STREAM_CHUNK_CHARS} 切块编码。
  */
 /** 达到这个长度（UTF-16 码元）的字符串才走片段路径。 */
 export const LARGE_STRING_BYTES = 64 * 1024;
@@ -23,6 +27,7 @@ const CHECK_CHUNK = 16 * 1024;
  * 每个大字符串每次序列化只查这一次。
  */
 function isPlain(value) {
+    plainScans.count++;
     for (let i = 0; i < value.length; i += CHECK_CHUNK) {
         const chunk = value.slice(i, i + CHECK_CHUNK);
         if (JSON.stringify(chunk).length !== chunk.length + 2)
@@ -30,6 +35,54 @@ function isPlain(value) {
     }
     return true;
 }
+/** 短字符串无需转义（`LargeString.prefix` 用）。 */
+const isShortPlain = (value) => JSON.stringify(value).length === value.length + 2;
+/** `isPlain` 的调用次数（测试用：同一块图片第二次序列化不应再扫）。 */
+export const plainScans = { count: 0 };
+/**
+ * 请求体里的大字符串叶子 `prefix + text`（data URL 或裸 base64），用来代替模板串拼接：拼接得到的
+ * cons string 在每次序列化时都会被扁平化成一份新的整图字符串。片段路径直接写 `prefix` 与 `text`
+ * （`text` 是转录里的原字符串，不拷贝）；`text` 无需转义的结论按 `key`（转录里身份稳定的 ImageBlock）
+ * 缓存，同一块每进程只扫一次。约定：同一 `key` 的 `text` 不变。其它遍历者看到的是一个带 `toJSON`
+ * 的对象，原生 `JSON.stringify` 得到相同字符串。由 {@link largeString} 构造。
+ */
+export class LargeString {
+    prefix;
+    key;
+    text;
+    constructor(prefix, key, text) {
+        this.prefix = prefix;
+        this.key = key;
+        this.text = text;
+    }
+    toJSON() {
+        return this.prefix + this.text;
+    }
+}
+/**
+ * `prefix + text` 作为请求体的值：`text` 够大且 `prefix` 自身无需转义时给 {@link LargeString}，
+ * 否则就是拼好的字符串（小图与以前完全相同）。
+ */
+export function largeString(prefix, key, text) {
+    if (text.length < LARGE_STRING_BYTES || !isShortPlain(prefix))
+        return prefix + text;
+    return new LargeString(prefix, key, text);
+}
+/** 已确认无需转义的 `LargeString.text`：键是 `key`，值是当时的 UTF-8 字节数（同时省掉再数一遍）。 */
+const plainBytes = new WeakMap();
+/** `LargeString.text` 可原样写入时返回其 UTF-8 字节数，否则 undefined。 */
+function plainLargeBytes(value) {
+    if (!isShortPlain(value.prefix))
+        return undefined;
+    const known = plainBytes.get(value.key);
+    if (known !== undefined && known.length === value.text.length)
+        return known.bytes;
+    if (!isPlain(value.text))
+        return undefined;
+    const bytes = Buffer.byteLength(value.text, "utf8");
+    plainBytes.set(value.key, { length: value.text.length, bytes });
+    return bytes;
+}
 /** 结构遍历的深度上限：更深（或有环）时整棵子树交给原生，环由原生照常抛 TypeError。 */
 const MAX_DEPTH = 64;
 const isLargeString = (value) => typeof value === "string" && value.length >= LARGE_STRING_BYTES;
@@ -48,6 +101,8 @@ function isContainer(value) {
 function collectLarge(value, marked, depth) {
     if (isLargeString(value))
         return true;
+    if (value instanceof LargeString)
+        return value.text.length >= LARGE_STRING_BYTES;
     if (depth >= MAX_DEPTH || !isContainer(value))
         return false;
     let found = false;
@@ -81,18 +136,24 @@ function nativeValue(key, value) {
 /** 片段：已拼好的 JSON 文本与大字符串交替；连续的小文本先在字符串里累积。 */
 class Pieces {
     parts = [];
+    /** 已推入 `parts` 的 UTF-8 字节数。 */
+    bytes = 0;
     pending = "";
     text(chunk) {
         this.pending += chunk;
     }
-    /** 大字符串原样写入（引号进相邻的小片段）。 */
-    large(value) {
-        this.parts.push(`${this.pending}"`, value);
+    /** 大字符串原样写入（引号与 `head` 进前一个小片段）；`bytes` 已知时不再数一遍。 */
+    large(value, head = "", bytes = Buffer.byteLength(value, "utf8")) {
+        const before = `${this.pending}"${head}`;
+        this.parts.push(before, value);
+        this.bytes += Buffer.byteLength(before, "utf8") + bytes;
         this.pending = '"';
     }
     finish() {
-        if (this.pending.length > 0)
+        if (this.pending.length > 0) {
             this.parts.push(this.pending);
+            this.bytes += Buffer.byteLength(this.pending, "utf8");
+        }
         this.pending = "";
         return this.parts;
     }
@@ -109,6 +170,15 @@ function writeEntry(key, value, marked, out, prefix, depth) {
         }
         return true;
     }
+    if (value instanceof LargeString && value.text.length >= LARGE_STRING_BYTES) {
+        const bytes = plainLargeBytes(value);
+        out.text(prefix);
+        if (bytes !== undefined)
+            out.large(value.text, value.prefix, bytes);
+        else
+            out.text(JSON.stringify(value.toJSON())); // 需要转义：交给原生
+        return true;
+    }
     // 深度与 collectLarge 一致；有环时越过上限交给原生，由它抛 TypeError
     if (depth < MAX_DEPTH && isContainer(value) && marked.has(value)) {
         out.text(prefix);
@@ -150,18 +220,9 @@ function jsonParts(body) {
     if (!collectLarge(body, marked, 0))
         return undefined;
     const out = new Pieces();
-    if (isLargeString(body)) {
-        if (!isPlain(body))
-            return undefined;
-        out.large(body);
-    }
-    else
-        writeContainer(body, marked, out, 0);
+    writeEntry("", body, marked, out, "", 0); // 顶层：键为 ""，与原生调用 toJSON 的键相同
     const parts = out.finish();
-    let length = 0;
-    for (const part of parts)
-        length += Buffer.byteLength(part, "utf8");
-    return { parts, length };
+    return { parts, length: out.bytes };
 }
 /** 与 `Buffer.from(JSON.stringify(body), "utf8")` 逐字节相同；大字符串不经中间字符串。 */
 export function serializeJsonBody(body) {
@@ -178,11 +239,16 @@ export function serializeJsonBody(body) {
     }
     return buf;
 }
+/**
+ * 流式请求体每块最多编码的码元数：大片段（一整张图）按游标切片（V8 切片串不拷贝）逐块编码，
+ * 发送期间只多出一块的 UTF-8 字节，而不是一整张图。
+ */
+export const STREAM_CHUNK_CHARS = 256 * 1024;
 /**
  * 给 fetch 的请求体。不含大字符串时就是 `JSON.stringify(body)`（与以前完全相同）；含大字符串时是
  * 逐片段编码的流，并给出总字节数。不交给 fetch 一个 Buffer：Node 的 fetch 会把 BufferSource
  * 请求体再复制两份（实测 mock 300 步带图峰值反而从约 1.0 GB 升到 1.85 GB），流则按片段边读边发，
- * 同一时刻只多出一个片段的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
+ * 同一时刻只多出一块（≤ {@link STREAM_CHUNK_CHARS} 码元）的 UTF-8 字节。字节序列与 `serializeJsonBody` 相同。
  */
 export function jsonFetchBody(body) {
     const split = jsonParts(body);
@@ -190,6 +256,7 @@ export function jsonFetchBody(body) {
         return { body: JSON.stringify(body) };
     const { parts } = split;
     let next = 0;
+    let offset = 0; // 当前片段已发出的码元数
     const stream = new ReadableStream({
         pull(controller) {
             const part = parts[next];
@@ -197,8 +264,19 @@ export function jsonFetchBody(body) {
                 controller.close();
                 return;
             }
-            parts[next++] = ""; // 发出即放手，片段（拼出来的小文本）可尽早回收
-            controller.enqueue(Buffer.from(part, "utf8"));
+            let end = Math.min(part.length, offset + STREAM_CHUNK_CHARS);
+            // 不把成对代理项切开（片段里只有成对的：孤立代理项已被原生转义）
+            const last = part.charCodeAt(end - 1);
+            if (end < part.length && last >= 0xd800 && last <= 0xdbff)
+                end--;
+            const piece = offset === 0 && end === part.length ? part : part.slice(offset, end);
+            if (end === part.length) {
+                parts[next++] = ""; // 发完即放手，片段（拼出来的小文本）可尽早回收
+                offset = 0;
+            }
+            else
+                offset = end;
+            controller.enqueue(Buffer.from(piece, "utf8"));
         },
         cancel() {
             parts.length = 0;

package/dist/ai/providers/enrich.d.ts

@@ -25,6 +25,8 @@ export interface ModelMetadata {
     toolCall?: boolean;
     /** [ME-D] 按 id 继承的内置目录条目 `provider/id`。 */
     catalog?: string;
+    /** 显式 `catalog` / `modelsDev` 引用不命中时的告警（注册表转成 warnings，#154）。 */
+    warnings?: string[];
 }
 export type ModelsDevSource = ModelsDevIndex | (() => ModelsDevIndex | undefined) | undefined;
 /** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
@@ -32,9 +34,11 @@ export declare function lazyIndex(source: ModelsDevSource): () => ModelsDevIndex
 type EnrichedEntry = Omit<ModelConfig, "modelsDev" | "channels" | "catalog">;
 /**
  * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
- * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。
+ * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。显式 `catalog: "provider/id"`
+ * 或 `modelsDev` 引用不命中时记入 `metadata.warnings`（`providerId` 用于告警文案）；写错的 `catalog`
+ * 不回落按 id 继承——用户显式指定，按指定失败处理。
  */
-export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined): {
+export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined, providerId?: string): {
     entry: EnrichedEntry;
     metadata: ModelMetadata;
 };

package/dist/ai/providers/enrich.js

@@ -79,9 +79,11 @@ function fillLimits(out, hit, sources) {
 }
 /**
  * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
- * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。
+ * `modelsDev` / `channels` / `catalog` 这些配置专用键）与每个字段的来源。显式 `catalog: "provider/id"`
+ * 或 `modelsDev` 引用不命中时记入 `metadata.warnings`（`providerId` 用于告警文案）；写错的 `catalog`
+ * 不回落按 id 继承——用户显式指定，按指定失败处理。
  */
-export function enrichEntry(entry, index) {
+export function enrichEntry(entry, index, providerId) {
     const { modelsDev, channels: _channels, catalog: _catalog, ...rest } = entry;
     const sources = {};
     for (const field of ENRICHABLE_FIELDS) {
@@ -89,11 +91,16 @@ export function enrichEntry(entry, index) {
     }
     const metadata = { sources, looked: false };
     const out = { ...rest };
+    const warnings = [];
+    const ref = `${providerId ?? "?"}/${entry.id}`;
     const hit = catalogHit(entry);
     if (hit !== undefined) {
         metadata.catalog = hit.ref;
         inheritIntrinsic(out, hit, sources);
     }
+    else if (typeof entry.catalog === "string") {
+        warnings.push(`catalog "${entry.catalog}" for "${ref}" not found; ignored`);
+    }
     const explicit = typeof modelsDev === "string" ? modelsDev : hit?.snapshotRef;
     const lookup = modelsDev !== false && (needsLookup(out) || modelsDev !== undefined);
     const idx = lookup ? index() : undefined;
@@ -127,8 +134,12 @@ export function enrichEntry(entry, index) {
             }
         }
     }
+    if (typeof modelsDev === "string" && metadata.looked && metadata.match === undefined)
+        warnings.push(`modelsDev "${modelsDev}" for "${ref}" not found`);
     if (hit !== undefined && modelsDev !== false)
         fillLimits(out, hit, sources);
+    if (warnings.length > 0)
+        metadata.warnings = warnings;
     return { entry: out, metadata };
 }
 /**

package/dist/ai/providers/max-tokens-cache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `max_tokens` 上限的跨进程缓存：`<dataDir>/models/max-tokens-caps.json`（#152）。
+ *
+ * 被动修正（apis/max-tokens.ts）学到的 `provider/model` 上限原本只在进程内，重启后每个模型的首个请求仍被
+ * 400 拒一次。这里把它写进数据目录：组装注册表时载回进程内的表（进程内已有的键优先），学到新上限就把文件里
+ * 未过期的条目加上这一条原子写回（临时文件 + 改名；并发进程后写者赢，丢的一条下次再学）。条目 30 天过期，
+ * 过期后重新探测（中转放宽上限时不会一直压低输出）；删掉文件即重测。只存模型引用、上限与时间，没有凭据。
+ */
+export declare const MAX_TOKENS_CACHE_VERSION = 1;
+/** 条目有效期：30 天。 */
+export declare const MAX_TOKENS_CACHE_TTL_MS: number;
+/** 缓存文件位置。 */
+export declare function maxTokensCachePath(dataDir: string): string;
+/** 载入未过期的上限到进程内的表（已有的键不覆盖）；返回载入条数。 */
+export declare function loadMaxTokensCaps(dataDir: string, now?: () => number): number;
+/** 把一条新上限并入文件（顺带清掉过期条目）；写失败不抛（缓存只是省一次 400）。 */
+export declare function recordMaxTokensCap(dataDir: string, key: string, cap: number, now?: () => number): void;
+/**
+ * 载入并订阅：之后学到的上限写回该数据目录。按 `dataDir` 幂等（同一进程重复组装注册表不重复订阅）；
+ * 返回取消函数（取消后可重新 attach）。
+ */
+export declare function attachMaxTokensCache(dataDir: string, now?: () => number): () => void;

package/dist/ai/providers/max-tokens-cache.js

@@ -0,0 +1,95 @@
+/**
+ * `max_tokens` 上限的跨进程缓存：`<dataDir>/models/max-tokens-caps.json`（#152）。
+ *
+ * 被动修正（apis/max-tokens.ts）学到的 `provider/model` 上限原本只在进程内，重启后每个模型的首个请求仍被
+ * 400 拒一次。这里把它写进数据目录：组装注册表时载回进程内的表（进程内已有的键优先），学到新上限就把文件里
+ * 未过期的条目加上这一条原子写回（临时文件 + 改名；并发进程后写者赢，丢的一条下次再学）。条目 30 天过期，
+ * 过期后重新探测（中转放宽上限时不会一直压低输出）；删掉文件即重测。只存模型引用、上限与时间，没有凭据。
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { maxTokensCaps, onMaxTokensCap } from "../apis/max-tokens.js";
+export const MAX_TOKENS_CACHE_VERSION = 1;
+/** 条目有效期：30 天。 */
+export const MAX_TOKENS_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** 缓存文件位置。 */
+export function maxTokensCachePath(dataDir) {
+    return join(dataDir, "models", "max-tokens-caps.json");
+}
+/** 读文件里未过期的条目；不存在、坏 JSON、版本不符或形状不对的条目一律忽略。 */
+function readEntries(dataDir, now) {
+    const out = new Map();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(maxTokensCachePath(dataDir), "utf8"));
+    }
+    catch {
+        return out;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return out;
+    const file = parsed;
+    if (file.version !== MAX_TOKENS_CACHE_VERSION)
+        return out;
+    if (typeof file.caps !== "object" || file.caps === null)
+        return out;
+    for (const [key, value] of Object.entries(file.caps)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { cap, learnedAt } = value;
+        if (typeof cap !== "number" || !Number.isInteger(cap) || cap < 1)
+            continue;
+        if (typeof learnedAt !== "number" || !Number.isFinite(learnedAt))
+            continue;
+        if (now - learnedAt > MAX_TOKENS_CACHE_TTL_MS)
+            continue;
+        out.set(key, { cap, learnedAt });
+    }
+    return out;
+}
+/** 载入未过期的上限到进程内的表（已有的键不覆盖）；返回载入条数。 */
+export function loadMaxTokensCaps(dataDir, now = Date.now) {
+    let loaded = 0;
+    for (const [key, entry] of readEntries(dataDir, now())) {
+        if (maxTokensCaps.has(key))
+            continue;
+        maxTokensCaps.set(key, entry.cap);
+        loaded++;
+    }
+    return loaded;
+}
+/** 把一条新上限并入文件（顺带清掉过期条目）；写失败不抛（缓存只是省一次 400）。 */
+export function recordMaxTokensCap(dataDir, key, cap, now = Date.now) {
+    const at = now();
+    const entries = readEntries(dataDir, at);
+    entries.set(key, { cap, learnedAt: at });
+    const path = maxTokensCachePath(dataDir);
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const caps = Object.fromEntries([...entries].sort(([a], [b]) => (a < b ? -1 : 1)));
+        writeFileSync(tmp, `${JSON.stringify({ version: MAX_TOKENS_CACHE_VERSION, caps }, null, 2)}\n`);
+        renameSync(tmp, path);
+    }
+    catch {
+        // 只读数据目录等：本进程内的表仍有效
+    }
+}
+const attached = new Map();
+/**
+ * 载入并订阅：之后学到的上限写回该数据目录。按 `dataDir` 幂等（同一进程重复组装注册表不重复订阅）；
+ * 返回取消函数（取消后可重新 attach）。
+ */
+export function attachMaxTokensCache(dataDir, now = Date.now) {
+    const existing = attached.get(dataDir);
+    if (existing !== undefined)
+        return existing;
+    loadMaxTokensCaps(dataDir, now);
+    const unsubscribe = onMaxTokensCap((key, cap) => recordMaxTokensCap(dataDir, key, cap, now));
+    const detach = () => {
+        unsubscribe();
+        attached.delete(dataDir);
+    };
+    attached.set(dataDir, detach);
+    return detach;
+}

package/dist/ai/providers/registry.js

@@ -256,9 +256,9 @@ export class ProviderRegistry {
         const channelsOf = (wanted, modelId) => modelChannels(wanted, provider.channels ?? [], provider.defaultChannel ?? "", (name) => this.warn(`model "${id}/${modelId}" channel "${name}" not found; ignored`));
         for (const entry of config.models ?? []) {
             // 模型级 api（第三波 §2.3）：同一中转下不同模型走不同协议；缺省沿用供应商（或渠道）的。
-            const { entry: filled, metadata } = enrichEntry(entry, this.modelsDev);
-            if (typeof entry.modelsDev === "string" && metadata.looked && metadata.match === undefined)
-                this.warn(`modelsDev "${entry.modelsDev}" for "${id}/${entry.id}" not found`);
+            const { entry: filled, metadata } = enrichEntry(entry, this.modelsDev, id);
+            for (const warning of metadata.warnings ?? [])
+                this.warn(warning);
             const model = withCustomDefaults(filled, id, entry.api ?? provider.api);
             // 内置供应商上没写 channels 的模型：定渠道时挂全部渠道（settleBuiltinChannels）
             if (provider.channels !== undefined && (entry.channels !== undefined || !provider.builtin))