dsh-connect-modelscope-token-plan 0.2.0 → 0.3.0

package/cordis.patch.yml

@@ -54,5 +54,32 @@
         # 次数计费」的口径这反而是对的）。详见 src/host/usage-observer.ts 文件头
         # 与 README「诚实声明」。
         registerProvider: false
+        # ------------------------------------------------------------------
+        # 给 agent 注册出图工具（`modelscope_draw_image`）。**与上面的
+        # registerProvider 是两条独立开关**：那个管「魔搭作为 chat provider」，
+        # 这个管「agent 能不能出图」。默认同样关（opt-in）。
+        #
+        # 实测要点（docs/SPIKE-image-gen.md）：
+        #   · 上游是**异步两段式**：提交拿 task_id，再带
+        #     `X-ModelScope-Task-Type: image_generation` 轮询到终态；
+        #   · 提交响应里的 task_status 恒为 SUCCEED 且**不可信**，成功只看轮询终态；
+        #   · 耗时不稳（实测 61s–537s，免费池排队），故超时取 15 分钟；
+        #   · 出图**不扣**魔粒（chat 才扣，1 次 = 1 魔粒），所以面板刻意**不显示**
+        #     出图计数——那会变成拿 chat 的口径给生图记账。
+        #
+        # 生效时机：开关值立即保存，但**工具的挂载发生在下次 Host 启动**——
+        # peer 的 tools registry 没有 unregister，工具一旦注册就摘不下来。
+        # 面板会就这一点给出提示（draw.restartHint）。
+        drawEnabled: false
+        # 出图默认模型（空 = 自动取目录里第一个出图模型）。
+        # 注意只有目录内**平台声明**出图能力的模型才进候选：实测目录 35 条里
+        # 只有 2 条 image-to-image（Qwen/Qwen-Image-Edit、MusePublic/…），
+        # 没有任何 text-to-image。官方示例里的 Qwen/Qwen-Image-2.1-Turbo 与
+        # black-forest-labs/FLUX.1-Kontext-dev **都不在目录内**，后者实测 FAILED。
+        drawModelId: ""
+        # 单次出图总预算（毫秒），含提交与全部轮询。上界 900000（15 分钟）。
+        # 别调小：实测最慢一次 859s 才成功，而超时放弃**不等于**任务死亡
+        # （上游会继续跑），把预算压到 5 分钟曾实测击穿。
+        drawTimeoutMs: 900000
         # 追加可信 Host 名（默认 localhost / 127.0.0.1 / ::1，只增不替）。
         # allowedHosts: []

package/lib/{host-config-C4bWNPWU.js → host-config.js}

@@ -61,9 +61,11 @@ function pluginError(code, message, extra = {}) {
 *
 * 根因（对照 peer 源码 `@deepseek-ai/dsh-llm-pi-ai` 的 `classifyPiAiError`
 * 与 `@deepseek-ai/dsh-llm` 的 `isQuotaExceededError`，二者均为**非行号锚**
-* 的稳定符号；其判定顺序与措辞命中面由 `test/peer-contract.test.mjs` 在
-* 真 peer 可达时钉死——该契约测试依赖未 vendored 进本仓库的运行时 peer，不在
-* `npm test` 离线门禁内，本模块自身的纠正判定由 `test/error-fix.test.mjs` 钉死）：
+* 的稳定符号。**注意：peer 的判定顺序与措辞命中面目前没有任何测试钉死**——验证
+* 它需要运行时 peer，而 peer 未 vendored 进本仓库，所以进不了 `npm test` 离线
+* 门禁（见 docs/ROADMAP.md 的 Backlog）。本模块自身的纠正判定由
+* `test/error-fix.test.mjs` 钉死；那只能证明「给定这样的 peer 行为，我们的纠正
+* 是对的」，证明不了 peer 的行为本身没有漂移）：
 *   `classifyPiAiError` **先**跑 `isQuotaExceededError`（命中面极宽：`out of
 *   ... budget`、`balance/credits exhausted` 等），**后**才跑纯限频分支
 *   （`\b429\b|rate.?limit`）。凡是魔搭 429 体里带上一两个 “budget/credits/
@@ -256,25 +258,26 @@ async function* reclassifyStream(source) {
 /**
 * 目录条目 → pi-ai model descriptor 的映射层——魔搭 provider 注册的**纯函数半边**。
 *
-* 本模块刻意不 import 任何 Host peer（`@earendil-works/pi-ai`、
-* `@deepseek-ai/dsh-llm-pi-ai`）：它只产普通对象，所以这些映射决策可以在一个
-* 干净的 checkout 上离线测。peer 依赖的另一半（把这些 descriptor 交给
-* `createProvider`）在 `llm-adapter.ts`。
-*
-* 这里携带的三条决策是承重的，不是装饰：
-*
-* 1. `compat.supportsDeveloperRole: false`。pi-ai 在缺省时会**自动探测**这个
-*    标志，对非标准 provider 一律猜 `true`，于是每条请求都用 `developer`
-*    角色——魔搭这个多模型代理不认识，会 400 或 403。qoder 路由证明必须
-*    显式写 false。
-* 2. `maxTokens` 只在目录**声明了**上限时声明。harness 对未声明的 maxTokens
-*    用 `defaultMaxTokens ?? 32768` 兜底，所以「不声明」不是「没有上限」，而是
-*    「平台没说」的诚实处理；别猜数字填。
-* 3. `reasoning: false` + **不设** `thinkingLevelMap`。魔搭 API-Inference 是
-*    多模型代理，是否吃 `reasoning_effort` 取决于背后那个具体模型，本插件
-*    无法离线得知每个 id 的档位表（sensenova 那份是拿真令牌逐模型探测 200/400
-*    才钉出来的）。「宁可不选，不可错发」：发错档位会整条请求 400，比不发
-*    差得多。M4 之后的迭代（探测出档位表）再按模型开启。
+* **TL;DR**：本模块只产普通对象、刻意不 import 任何 Host peer（`@earendil-works/pi-ai`、
+* `@deepseek-ai/dsh-llm-pi-ai`），所以这些映射决策可以在一个干净的 checkout 上
+* 离线测；peer 依赖的另一半（把 descriptor 交给 `createProvider`）在 `llm-adapter.ts`。
+* 下面三条是**当前契约**，改动前请先读文末「演变记录」。
+*
+* 1. `compat.supportsDeveloperRole: false`——pi-ai 缺省会**自动探测**这个标志，
+*    对非标准 provider 一律猜 `true`，于是每条请求都用 `developer` 角色，魔搭这个
+*    多模型代理不认识，会 400 或 403。qoder 路由证明必须显式写 false。
+* 2. `maxTokens` 只在目录**声明了**上限时声明——harness 对未声明的 maxTokens
+*    用 `defaultMaxTokens ?? 32768` 兜底，所以「不声明」是「平台没说」的诚实处理，
+*    别猜数字填。
+* 3. `reasoning: false` + **不设** `thinkingLevelMap`——魔搭 API-Inference 是
+*    多模型代理，是否吃 `reasoning_effort` 取决于背后那个具体模型，本插件无法
+*    离线得知每个 id 的档位表（sensenova 那份是拿真令牌逐模型探测才钉出来的）。
+*
+* ## 演变记录（历史，非契约）
+* 关于第 3 条，真实障碍**不是**「发错档位会整条请求 400」——该理由于 2026-10-05
+* 被真机证伪（`"bogus"` 同样 200，值不被校验）——而是无法区分「参数生效」与
+* 「被静默忽略」（两者都 200），且该端点会在真响应与空壳 200 之间摇摆，档位表
+* 做不出来。理由与实测见 PROVIDER-M4.md §4。
 *
 * @module dsh-connect-modelscope-token-plan/llm-models
 */
@@ -550,6 +553,24 @@ function contextWindowOf(entry) {
 	return FALLBACK_CONTEXT_WINDOW;
 }
 /**
+* 这个条目的窗口数字从真值链哪一级来——与 contextWindowOf 配对的来源标记。
+*
+* catalog = 目录四键声明过（平台真值）；override = fetchModels 打标时写入的
+* 用户覆盖；curated = 打标时写入的策展表值。后两者在归一条目上是不可区分的
+* （都表现为 contextWindow 键有值），所以打标侧各自留指纹：覆盖命中时在
+* source 上放 `__contextSource: "override"`，策展命中放 `"curated"`，本函数
+* 只读指纹。都没有 → "catalog"（含义是「目录说了算」，包括目录没声明、值
+* 就是 pi-ai 兜底 128k 的条目——面板把 128k 徽章留给这个状态，策展命中会
+* 显示自己的数值）。
+* @param {object} entry - 一条归一目录条目。
+* @returns {"catalog"|"override"|"curated"} 来源标记。
+*/
+function contextWindowSourceOf(entry) {
+	const mark = (entry?.raw)?.__contextSource;
+	if (mark === "override" || mark === "curated") return mark;
+	return "catalog";
+}
+/**
 * 读目录声明的单次输出上限，0 = 未声明。
 *
 * 这个数**只用于展示/投影**。descriptor 只在 >0 时声明 `maxTokens`（见模块头注
@@ -645,6 +666,50 @@ function filterByEnabled(entries, enabledIds) {
 	return (Array.isArray(entries) ? entries : []).filter((entry) => allow.has(str(entry?.id, "")));
 }
 /**
+* 面板用的 roster：每条可寻址 chat 条目一行。
+*
+* 刻意是投影而非原始条目：快照只带 picker 需要的（id、展示名、与 descriptor
+* 相同的 vision 判定、以及供能力路由用的 capability），平台将来新增的目录字段
+* 不会为了没理由泄到面板。
+*
+* 去重保留**末次出现**（与 {@link buildDescriptors} 一致）：同 id 更新的读取赢。
+* 这里要是分叉了，面板清单和注册结果就会就「哪些模型存在」说两套话，勾选的模型
+* 可能变成未注册的。
+* @param {object[]} entries - 归一目录条目。
+* @returns {{id: string, name: string, vision: boolean, capability: ModelCapability}[]}
+*/
+/**
+* 构建一份去重 roster 的**共享循环骨架**：过滤 chat 模型 → 取 id → 投 row →
+* position-map 去重（末次出现赢）。两个公开 roster 函数（rosterOf /
+* rosterWithAvailability）只投各自的 row 形状，过滤/取 id/去重不再各写一遍
+* ——它们曾各写一份相同的循环，jscpd 抓到 :493-504 ↔ :568-577。
+*
+* 语义承重，与 {@link buildDescriptors} 一致：同 id 末次出现赢；顺序为目录
+* 首见序。这里分叉了，面板清单和注册结果就会就「哪些模型存在」说两套话。
+* @template T - 一行 roster 的形状（由调用方投）。
+* @param {object[]} entries - 归一目录条目。
+* @param {(entry: CatalogEntry, id: string) => T} project - 条目 → 行。
+* @returns {T[]}
+*/
+function buildRosterRows(entries, project) {
+	const position = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const catalogEntry = entry;
+		if (!isChatModel(catalogEntry)) continue;
+		const id = str(catalogEntry.id, "");
+		if (id === "") continue;
+		const row = project(catalogEntry, id);
+		if (position.has(id)) out[position.get(id)] = row;
+		else {
+			position.set(id, out.length);
+			out.push(row);
+		}
+	}
+	return out;
+}
+/**
 * 为一份目录构建整份 descriptor 列表。
 *
 * 没有 id 的条目丢弃（线上没法寻址），重复 id 保留末次出现，与 `rosterOf` 的
@@ -682,6 +747,81 @@ function buildDescriptors(entries, options = {}) {
 	return out;
 }
 /**
+* 一条目录条目能不能**出图**。
+*
+* 判据是能力枚举里的两个出图档：`text-to-image`（文生图）与 `image-to-image`
+* （图生图/改图）。**只认平台声明的能力**（详情端点 `Tasks[].Name` 或结构化模态
+* 字段），不额外加名字正则——名字启发是 `resolveModelCapability` 里最后才用的兜底，
+* 它把「说不清」的条目标成 `unknown`，那种条目**不**进候选。
+*
+* 与 `isVisionModel` 的严格方向同源：吃图判定宁可漏（漏了报 UNSUPPORTED_CONTENT，
+* 面板看得见），出图判定同理宁可漏（漏了报「目录里没有出图模型」，可诊断）；反过来
+* 猜错会把 agent 的请求发给一个出不了图的模型，换回一个原因不可知的 FAILED。
+*
+* 实测（2026-10-10）：api-inference 的 35 条目录里**没有 `text-to-image`**，只有 2 条
+* `image-to-image`（`Qwen/Qwen-Image-Edit`、`MusePublic/Qwen-Image-Edit`），两者均
+* 经 `/v1/images/generations` 出图成功。详见 docs/SPIKE-image-gen.md。
+* @param {object} entry - 一条归一目录条目。
+* @returns {boolean} 是否可用于出图。
+*/
+function isImageGenModel(entry) {
+	const capability = resolveModelCapability(entry);
+	return capability === "text-to-image" || capability === "image-to-image";
+}
+/**
+* 一份目录里匹配某判定的模型 id，按首见顺序去重。
+*
+* 去重口径与 `buildDescriptors` / `rosterOf` 一致（保留末次出现的值、占首见位置），
+* 这样出图候选列表与 chat roster 不会对「有哪些 id」各说一套。`imageGenModelIds`
+* 与 `textToImageModelIds` 共用这一份骨架，避免两处各自写一份相同的循环。
+* @param {unknown} entries - 归一目录条目。
+* @param {(entry: CatalogEntry) => boolean} isMatch - 条目匹配判定。
+* @returns {string[]} 匹配的模型 id。
+*/
+function idsOf(entries, isMatch) {
+	const position = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+		if (!isMatch(entry)) continue;
+		const id = str(entry.id, "");
+		if (id === "") continue;
+		const seen = position.get(id);
+		if (seen === void 0) {
+			position.set(id, out.length);
+			out.push(id);
+		} else out[seen] = id;
+	}
+	return out;
+}
+/**
+* 一份目录里可用于出图的模型 id，按首见顺序去重。
+*
+* 去重口径见 {@link idsOf}。**注意**：这里只保证「平台声明能出图」，不保证
+* 「能纯文生图」——真实目录里唯一的出图条目是 `image-to-image`，其中
+* `MusePublic/Qwen-Image-Edit` 纯文生图被上游拒绝（见 `draw-runtime.ts` 的
+* `KNOWN_T2I_MODEL_ID`）。挑默认模型要走 `pickDrawModel` 的完整优先级，别直接
+* 取这里的第一个。
+* @param {unknown} entries - 归一目录条目。
+* @returns {string[]} 出图模型 id。
+*/
+function imageGenModelIds(entries) {
+	return idsOf(entries, isImageGenModel);
+}
+/**
+* 一份目录里**平台声明为文生图**（`text-to-image`）的模型 id，按首见顺序去重。
+*
+* 与 `imageGenModelIds` 同一份去重骨架，只筛能力为 `text-to-image` 的条目。
+* 真实目录至今为空集（api-inference 的 36 条里没有 `text-to-image`），但将来
+* 目录补上真文生图模型时，`pickDrawModel` 应当优先挑它们——这个函数就是那个
+* 「平台说了算」的优先通道。
+* @param {unknown} entries - 归一目录条目。
+* @returns {string[]} 文生图模型 id。
+*/
+function textToImageModelIds(entries) {
+	return idsOf(entries, (entry) => resolveModelCapability(entry) === "text-to-image");
+}
+/**
 * 带额度可用性的面板 roster。
 *
 * 与 {@link rosterOf} 一样每 chat 模型 id 一行，但每行还带该模型额度池是否耗尽。
@@ -693,29 +833,17 @@ function buildDescriptors(entries, options = {}) {
 */
 function rosterWithAvailability(entries, unavailableIds) {
 	const blocked = new Set(Array.isArray(unavailableIds) ? unavailableIds : []);
-	const position = /* @__PURE__ */ new Map();
-	const out = [];
-	for (const entry of Array.isArray(entries) ? entries : []) {
-		if (!isChatModel(entry)) continue;
-		const id = str(entry?.id, "");
-		if (id === "") continue;
-		const row = {
-			id,
-			name: str(entry?.name, id),
-			vision: isVisionModel(entry),
-			capability: resolveModelCapability(entry),
-			available: !blocked.has(id),
-			quotaExhausted: blocked.has(id),
-			contextWindow: contextWindowOf(entry),
-			maxOutputLength: maxOutputLengthOf(entry)
-		};
-		if (position.has(id)) out[position.get(id)] = row;
-		else {
-			position.set(id, out.length);
-			out.push(row);
-		}
-	}
-	return out;
+	return buildRosterRows(entries, (entry, id) => ({
+		id,
+		name: str(entry.name, id),
+		vision: isVisionModel(entry),
+		capability: resolveModelCapability(entry),
+		available: !blocked.has(id),
+		quotaExhausted: blocked.has(id),
+		contextWindow: contextWindowOf(entry),
+		contextSource: contextWindowSourceOf(entry),
+		maxOutputLength: maxOutputLengthOf(entry)
+	}));
 }
 
 //#endregion
@@ -744,7 +872,7 @@ const inject = ["webServer"];
 * 产物反而引入第二份真源；这里用常量、由 test/config.test.mjs 钉住与
 * package.json 一致。
 */
-const PLUGIN_VERSION = "0.2.0";
+const PLUGIN_VERSION = "0.3.0";
 /**
 * 默认值。刻意不含额度常数——理由见本文件头。
 * 面板头条是官方魔粒余额，次数口径的推算已在面板收敛时删除，这里若留着
@@ -767,6 +895,31 @@ const CONFIG_DEFAULTS = Object.freeze({
 	maxEvents: 50,
 	/** provider 注册的 patch 默认值（面板保存值优先于它）。 */
 	registerProvider: false,
+	/**
+	* 出图工具的 patch 默认值（面板保存值优先于它）。
+	*
+	* **与 `registerProvider` 是两个独立开关**：前者是「把魔搭当 chat provider」，
+	* 后者是「给 agent 一个出图工具」。默认同为 false（opt-in），但互不牵连。
+	* 实测依据见 docs/SPIKE-image-gen.md。
+	*/
+	drawEnabled: false,
+	/** 出图默认模型（空 = 自动挑目录里第一个出图模型）。 */
+	drawModelId: "",
+	/**
+	* 单次出图的总预算（毫秒），含提交与全部轮询。
+	*
+	* 默认 **15 分钟**。这是本字段第三次调整，每次都有实测依据：
+	*  1. 最初据「任务慢」定 10 分钟，后归因为「轮询太密」，改为 5 分钟；
+	*  2. 该归因**已被推翻**——2026-10-10 同一模型、同样 15s 轮询连测三次，
+	*     耗时 61s → 261s → **537s**，单调恶化。是上游免费池的**排队时长在波动**，
+	*     与轮询间隔无关（那次 5s 轮询的 >185s 观测不能再当作证据）；
+	*  3. 5 分钟预算因此**实测被击穿**：一次真实 e2e 在 300s 处放弃，而任务仍活着。
+	*
+	* 取 15 分钟：覆盖已观测到的最慢一次（537s）并留一倍余量。**注意超时放弃不等于
+	* 任务死亡**——上游任务会继续跑（且记录最终会被回收，见 docs/SPIKE-image-gen.md
+	* §坑 5）。宁可多等，不要把一张已经在生成的图扔掉。
+	*/
+	drawTimeoutMs: 9e5,
 	/** Host 应答的默认主机名；操作者的列表是「只增不替」。 */
 	admittedHosts: [
 		"localhost",
@@ -816,6 +969,9 @@ function resolveSettings(config) {
 				inferenceTimeoutMs: clampInt(source.inferenceTimeoutMs, CONFIG_DEFAULTS.inferenceTimeoutMs, 1e3, 6e5),
 				maxEvents: clampInt(source.maxEvents, CONFIG_DEFAULTS.maxEvents, 1, 1e3),
 				registerProvider: source.registerProvider === true,
+				drawEnabled: source.drawEnabled === true,
+				drawModelId: str(source.drawModelId, CONFIG_DEFAULTS.drawModelId),
+				drawTimeoutMs: clampInt(source.drawTimeoutMs, CONFIG_DEFAULTS.drawTimeoutMs, 3e4, 9e5),
 				allowedHosts: resolveAllowedHosts(source)
 			},
 			configError: null
@@ -831,6 +987,9 @@ function resolveSettings(config) {
 				inferenceTimeoutMs: CONFIG_DEFAULTS.inferenceTimeoutMs,
 				maxEvents: CONFIG_DEFAULTS.maxEvents,
 				registerProvider: false,
+				drawEnabled: false,
+				drawModelId: CONFIG_DEFAULTS.drawModelId,
+				drawTimeoutMs: CONFIG_DEFAULTS.drawTimeoutMs,
 				allowedHosts: new Set(CONFIG_DEFAULTS.admittedHosts)
 			},
 			configError: redactSecrets(errMsg(error))
@@ -897,4 +1056,4 @@ function isAdmitted(request, allowedHosts) {
 }
 
 //#endregion
-export { redactSecrets as C, pluginError as S, verbatim as T, reclassifyStream as _, resolveSettings as a, obj as b, LLM_PROVIDER_ID as c, normalizeEntry as d, resolveAllowedList as f, looksLikeRateLimit as g, hasHardQuotaWordingIn as h, name as i, buildDescriptors as l, CODE as m, inject as n, LLM_API_KEY_NAME as o, rosterWithAvailability as p, isAdmitted as r, LLM_DISPLAY_NAME as s, PLUGIN_VERSION as t, isVisionModel as u, degrade as v, str as w, optional as x, errMsg as y };
+export { optional as C, verbatim as D, str as E, obj as S, redactSecrets as T, hasHardQuotaWordingIn as _, resolveSettings as a, degrade as b, LLM_PROVIDER_ID as c, isVisionModel as d, normalizeEntry as f, CODE as g, textToImageModelIds as h, name as i, buildDescriptors as l, rosterWithAvailability as m, inject as n, LLM_API_KEY_NAME as o, resolveAllowedList as p, isAdmitted as r, LLM_DISPLAY_NAME as s, PLUGIN_VERSION as t, imageGenModelIds as u, looksLikeRateLimit as v, pluginError as w, errMsg as x, reclassifyStream as y };