@tnnevol/dsh-zcode 0.0.0-stage → 6.0.0

package/lib/console-client-54wUcPDA.d.ts

@@ -0,0 +1,220 @@
+//#region src/contracts/identity.d.ts
+/**
+ * ZCode 供应商身份与网关地址：host 与 client 共用的契约。
+ *
+ * 本插件只注册**一个** DSH 供应商 `ZCode`（路由 `dsh-zcode`），承载 ZCode
+ * Start Plan 的模型。账号体系有两个「家族」（BigModel 国内 / Z.ai 海外），
+ * 两者的登录入口、额度与网关完全相同，仅授权页域名不同；模型清单由账号
+ * 权益动态决定，因此不在这里枚举。
+ *
+ * 路由 id 带 `dsh-` 前缀是刻意的：`zcode` / `zhipu` 可能已被用户在内置目录里
+ * 手工声明，带前缀的 id 不会与用户配置撞名。
+ *
+ * @module dsh-zcode/identity
+ */
+/** 账号家族：BigModel（国内）与 Z.ai（海外）。 */
+type ZCodeFamily = 'bigmodel' | 'zai';
+/** 两个家族按固定顺序排列，用于界面与目录的稳定展示。 */
+declare const ZCODE_FAMILIES: readonly ZCodeFamily[];
+/** 本插件注册的唯一供应商路由。 */
+declare const ZCODE_PROVIDER = "dsh-zcode";
+/** 模型选择器分组与设置页显示的供应商名称。 */
+declare const ZCODE_PROVIDER_NAME = "zcode";
+/** 家族显示名。 */
+declare const ZCODE_FAMILY_LABELS: Readonly<Record<ZCodeFamily, string>>;
+/** ZCode 控制面根地址（OAuth、额度、客户端配置都在这个域下）。 */
+declare const ZCODE_ORIGIN = "https://zcode.z.ai";
+/**
+ * 推理端点的两种策略。
+ *
+ * 官方开源项目（`zai-org/ZCode` 的 `official-coding-plan-gateway.ts`）把
+ * `open.bigmodel.cn/api/anthropic/v1/messages` 改写成
+ * `<origin>/api/v1/ultra/anthropic/v1/messages`——官方模型流量走 `ultra`。
+ *
+ * 两条端点的差异（2026-10-25 实测）：
+ * - `start-plan`（`zcode-plan/anthropic`）：消耗 Start Plan 套餐额度，用账号 JWT。
+ *   网关会校验请求的 `system` 是否为官方 agent 原文，未注入前缀时返回
+ *   HTTP 405 + 业务码 `3012`；按 `start-plan-prefix.ts` 注入后正常放行。
+ * - `ultra`（`ultra/anthropic`）：用家族 MaaS 令牌，按量计费；
+ *   余额为 0 时返回 HTTP 429 + 业务码 `1113`。
+ *
+ * 默认走 `start-plan`：只订套餐、没有按量余额的账号只有这条路可用。
+ */
+type ZCodeEndpointPlan = 'start-plan' | 'ultra';
+/** 两种策略对应的端点前缀。 */
+declare const ZCODE_ANTHROPIC_BASE_URLS: Readonly<Record<ZCodeEndpointPlan, string>>;
+/** 默认策略：Start Plan（账号若只有套餐额度，这是唯一有意义的选择）。 */
+declare const DEFAULT_ZCODE_ENDPOINT_PLAN: ZCodeEndpointPlan;
+/** Start Plan 的 Anthropic 兼容推理端点前缀（默认策略，保留旧名便于引用）。 */
+declare const ZCODE_ANTHROPIC_BASE_URL: string;
+/** 端点策略的展示名。 */
+declare const ZCODE_ENDPOINT_PLAN_LABELS: Readonly<Record<ZCodeEndpointPlan, string>>;
+/**
+ * 请求 user-agent。
+ *
+ * ZCode 网关按客户端身份做来源归因，`ZCode/` 前缀与官方客户端保持同一形态；
+ * 版本号取本插件跟踪的客户端版本（见 {@link ZCODE_CLIENT_VERSION}）。
+ */
+declare const ZCODE_CLIENT_VERSION = "3.16.3";
+/** 完整 user-agent 串。 */
+declare const ZCODE_USER_AGENT = "ZCode/3.16.3 ai-sdk/provider-utils/4.0.27 runtime/node.js/24";
+//#endregion
+//#region src/host/console-client.d.ts
+/** 上游业务错误。 */
+declare class ZCodeConsoleError extends Error {
+  /** 上游业务码（`code` 字段），HTTP 层失败时为 undefined。 */
+  readonly code: number | undefined;
+  /** HTTP 状态码。 */
+  readonly status: number;
+  /** 上游原始响应片段，便于排查。 */
+  readonly detail?: string | undefined;
+  constructor(message: string,
+  /** 上游业务码（`code` 字段），HTTP 层失败时为 undefined。 */
+  code: number | undefined,
+  /** HTTP 状态码。 */
+  status: number,
+  /** 上游原始响应片段，便于排查。 */
+  detail?: string | undefined);
+}
+/** 授权码换取结果。 */
+interface ZCodeOAuthInit {
+  readonly flowId: string;
+  readonly authorizeUrl: string;
+  /** 过期时间（epoch ms）。 */
+  readonly expiresAt: number;
+  readonly intervalSeconds: number;
+}
+/** 授权码换取的凭据载体。 */
+type ZCodeOAuthPoll = {
+  readonly status: 'pending';
+} | {
+  readonly status: 'ready';
+  readonly zcodeJwt: string;
+  readonly accessToken?: string;
+  readonly refreshToken?: string;
+  readonly expiresAt?: number;
+  readonly user?: {
+    readonly userId?: string | undefined;
+    readonly email?: string | undefined;
+    readonly name?: string | undefined;
+    readonly avatar?: string | undefined;
+  };
+} | {
+  readonly status: 'failed';
+  readonly message: string;
+};
+/** 额度接口的原始条目。 */
+interface ZCodeRawBalance {
+  readonly capability?: string | undefined;
+  readonly showName: string;
+  readonly totalUnits: number;
+  readonly usedUnits: number;
+  readonly remainingUnits: number;
+  /** 上游没有 period 字段；周期由窗口时长推导（见宽松度推导）。 */
+  readonly periodStartSeconds?: number | undefined;
+  readonly periodEndSeconds?: number | undefined;
+  readonly expiresAtSeconds?: number | undefined;
+  /** 已用尽额度里也可能是 0，用它区分「未发放」与「已用完」。 */
+  readonly availableUnits?: number | undefined;
+  /** 该额度条目所属套餐 id。 */
+  readonly planId?: string | undefined;
+}
+/** 额度接口的原始套餐条目。 */
+interface ZCodeRawPlan {
+  readonly planId: string;
+  readonly name?: string | undefined;
+  readonly status?: string | undefined;
+  readonly endsAt?: string | undefined;
+}
+/** 额度快照（业务层聚合结果）。 */
+interface ZCodeBalanceSnapshot {
+  readonly plans: readonly ZCodeRawPlan[];
+  readonly balances: readonly ZCodeRawBalance[];
+}
+/** 客户端配置里的模型能力。 */
+interface ZCodeClientModel {
+  readonly modelId: string;
+  readonly name: string;
+  readonly contextWindow?: number | undefined;
+  readonly maxCompletionTokens?: number | undefined;
+  readonly reasoningLevels?: readonly string[] | undefined;
+  readonly defaultReasoningLevel?: string | undefined;
+  readonly supportsImage?: boolean | undefined;
+  readonly description?: string | undefined;
+}
+/** 客户端配置快照。 */
+interface ZCodeClientConfigSnapshot {
+  readonly models: readonly ZCodeClientModel[];
+  /** 验证码配置；`skipModelRequest` 为 true 表示模型请求不做人机校验。 */
+  readonly captcha?: {
+    readonly enabled: boolean;
+    readonly skipModelRequest: boolean;
+    readonly region?: string | undefined;
+  };
+  /** Start Plan 预览权益（未订阅时的展示口径）。 */
+  readonly startPlanEntitlements?: readonly {
+    readonly showName: string;
+    readonly grantUnits: number;
+  }[];
+}
+/** 代理端点映射（官方客户端把家族端点改写到 ZCode 域）。 */
+interface ZCodeAgentConfigSnapshot {
+  readonly proxyMapping: readonly {
+    readonly from: string;
+    readonly to: string;
+    readonly zcodeAuthorizationHeader?: string;
+  }[];
+  readonly codingPlanSignatureEnabled?: boolean;
+}
+/** 请求选项。 */
+interface ZCodeClientOptions {
+  /** 网络实现；默认 `globalThis.fetch`，便于测试注入。 */
+  readonly fetch?: typeof globalThis.fetch;
+  /** 每请求超时（毫秒）。 */
+  readonly timeoutMs?: number;
+  /** 生成稳定的设备标识；默认随机 UUID。 */
+  readonly deviceMid?: () => string;
+}
+/**
+ * ZCode 客户端身份头。
+ *
+ * `x-client-language` / `x-client-timezone` / `x-os-*` 参与网关的来源归因，
+ * 固定成稳定值比"跟随运行环境"更可靠：服务端对同一账号看到一致指纹。
+ */
+declare function zcodeSourceHeaders(deviceMid: string): Record<string, string>;
+/** 推理请求头：在客户端身份头上补 Anthropic 协议头与凭据。 */
+declare function zcodeModelHeaders(deviceMid: string, token: string): Record<string, string>;
+/** ZCode 控制面客户端。 */
+declare class ZCodeConsoleClient {
+  private readonly fetchImpl;
+  private readonly timeoutMs;
+  private readonly deviceMidFactory;
+  private cachedDeviceMid;
+  constructor(options?: ZCodeClientOptions);
+  /** 当前设备标识；首次调用时生成并缓存，保证同一进程内稳定。 */
+  deviceMid(): string;
+  /** 注入固定设备标识（从磁盘恢复时使用）。 */
+  setDeviceMid(value: string): void;
+  private request;
+  /**
+   * 用桌面端授权码换取凭据。
+   *
+   * 浏览器授权完成后由上游回跳带授权码，这里用 code 换取 `data.token` 与
+   * `data.<family>.access_token`。`redirect_uri` 与 `state` 必须与授权时逐字一致。
+   */
+  exchangeDesktopCode(family: ZCodeFamily, code: string, redirectUri: string, state: string): Promise<ZCodeOAuthPoll>;
+  /**
+   * 读取 Start Plan 额度。
+   *
+   * 这里是目录的真源：`balances[].capabilities` 决定账号此刻能用哪些模型。
+   */
+  balance(zcodeJwt: string): Promise<ZCodeBalanceSnapshot>;
+  /** 读取客户端配置：模型能力、验证码策略、Start Plan 预览权益。 */
+  clientConfigs(zcodeJwt: string): Promise<ZCodeClientConfigSnapshot>;
+  /** 读取 agent 运行时配置（官方客户端的端点改写映射）。 */
+  agentConfigs(zcodeJwt: string): Promise<ZCodeAgentConfigSnapshot>;
+}
+/** 推理端点完整地址。 */
+declare function zcodeMessagesUrl(baseURL?: string): string;
+//#endregion
+export { ZCODE_PROVIDER as C, ZCodeFamily as D, ZCodeEndpointPlan as E, ZCODE_ORIGIN as S, ZCODE_USER_AGENT as T, ZCODE_ANTHROPIC_BASE_URLS as _, ZCodeClientOptions as a, ZCODE_FAMILIES as b, ZCodeOAuthInit as c, ZCodeRawPlan as d, zcodeMessagesUrl as f, ZCODE_ANTHROPIC_BASE_URL as g, DEFAULT_ZCODE_ENDPOINT_PLAN as h, ZCodeClientModel as i, ZCodeOAuthPoll as l, zcodeSourceHeaders as m, ZCodeBalanceSnapshot as n, ZCodeConsoleClient as o, zcodeModelHeaders as p, ZCodeClientConfigSnapshot as r, ZCodeConsoleError as s, ZCodeAgentConfigSnapshot as t, ZCodeRawBalance as u, ZCODE_CLIENT_VERSION as v, ZCODE_PROVIDER_NAME as w, ZCODE_FAMILY_LABELS as x, ZCODE_ENDPOINT_PLAN_LABELS as y };

package/lib/identity-DE3rOYuE.js

@@ -0,0 +1,61 @@
+//#region src/contracts/identity.ts
+/** 两个家族按固定顺序排列，用于界面与目录的稳定展示。 */
+const ZCODE_FAMILIES = ["bigmodel", "zai"];
+/** 本插件注册的唯一供应商路由。 */
+const ZCODE_PROVIDER = "dsh-zcode";
+/** 模型选择器分组与设置页显示的供应商名称。 */
+const ZCODE_PROVIDER_NAME = "zcode";
+/** 家族显示名。 */
+const ZCODE_FAMILY_LABELS = {
+	bigmodel: "BigModel",
+	zai: "Z.ai"
+};
+/** ZCode 控制面根地址（OAuth、额度、客户端配置都在这个域下）。 */
+const ZCODE_ORIGIN = "https://zcode.z.ai";
+/**
+* 桌面端登录用的「授权码换令牌」端点。
+*
+* 浏览器授权完成后回跳到插件同源路由，再用本端点换取两份凭据：
+* `data.token`（Start Plan 用）与 `data.<family>.access_token`（家族业务令牌）。
+*/
+const ZCODE_OAUTH_TOKEN_URL = `${ZCODE_ORIGIN}/api/v1/oauth/token`;
+/** Start Plan 额度与权益接口。 */
+const ZCODE_BALANCE_URL = `${ZCODE_ORIGIN}/api/v1/zcode-plan/billing/balance`;
+/** 客户端运行时配置（验证码开关、Start Plan 预览权益、模型能力）。 */
+const ZCODE_CLIENT_CONFIGS_URL = `${ZCODE_ORIGIN}/api/v1/client/configs`;
+/** Agent 运行时配置（代理端点映射、签名开关）。 */
+const ZCODE_AGENT_CONFIGS_URL = `${ZCODE_ORIGIN}/api/v1/agent/configs`;
+/** 两种策略对应的端点前缀。 */
+const ZCODE_ANTHROPIC_BASE_URLS = {
+	"start-plan": `${ZCODE_ORIGIN}/api/v1/zcode-plan/anthropic`,
+	ultra: `${ZCODE_ORIGIN}/api/v1/ultra/anthropic`
+};
+/** 默认策略：Start Plan（账号若只有套餐额度，这是唯一有意义的选择）。 */
+const DEFAULT_ZCODE_ENDPOINT_PLAN = "start-plan";
+/** Start Plan 的 Anthropic 兼容推理端点前缀（默认策略，保留旧名便于引用）。 */
+const ZCODE_ANTHROPIC_BASE_URL = ZCODE_ANTHROPIC_BASE_URLS["start-plan"];
+/** 端点策略的展示名。 */
+const ZCODE_ENDPOINT_PLAN_LABELS = {
+	"start-plan": "Start Plan（套餐额度）",
+	ultra: "Ultra（按量余额）"
+};
+/**
+* 请求 user-agent。
+*
+* ZCode 网关按客户端身份做来源归因，`ZCode/` 前缀与官方客户端保持同一形态；
+* 版本号取本插件跟踪的客户端版本（见 {@link ZCODE_CLIENT_VERSION}）。
+*/
+const ZCODE_CLIENT_VERSION = "3.16.3";
+/** 完整 user-agent 串。 */
+const ZCODE_USER_AGENT = `ZCode/${ZCODE_CLIENT_VERSION} ai-sdk/provider-utils/4.0.27 runtime/node.js/24`;
+/** Anthropic 协议版本头。 */
+const ZCODE_ANTHROPIC_VERSION = "2023-06-01";
+/**
+* 中段 system 注入的 beta 标记。
+*
+* 官方客户端在允许模型接收「对话中插入 system 消息」时带这个头；缺失时
+* 网关仍可用，但中段 system 会被静默忽略，因此固定发送。
+*/
+const ZCODE_ANTHROPIC_BETA = "mid-conversation-system-2026-04-07";
+//#endregion
+export { ZCODE_USER_AGENT as _, ZCODE_ANTHROPIC_BETA as a, ZCODE_CLIENT_CONFIGS_URL as c, ZCODE_FAMILIES as d, ZCODE_FAMILY_LABELS as f, ZCODE_PROVIDER_NAME as g, ZCODE_PROVIDER as h, ZCODE_ANTHROPIC_BASE_URLS as i, ZCODE_CLIENT_VERSION as l, ZCODE_ORIGIN as m, ZCODE_AGENT_CONFIGS_URL as n, ZCODE_ANTHROPIC_VERSION as o, ZCODE_OAUTH_TOKEN_URL as p, ZCODE_ANTHROPIC_BASE_URL as r, ZCODE_BALANCE_URL as s, DEFAULT_ZCODE_ENDPOINT_PLAN as t, ZCODE_ENDPOINT_PLAN_LABELS as u };

package/lib/index.d.ts

@@ -0,0 +1,263 @@
+import { C as ZCODE_PROVIDER, D as ZCodeFamily, E as ZCodeEndpointPlan, S as ZCODE_ORIGIN, T as ZCODE_USER_AGENT, _ as ZCODE_ANTHROPIC_BASE_URLS, a as ZCodeClientOptions, b as ZCODE_FAMILIES, c as ZCodeOAuthInit, d as ZCodeRawPlan, f as zcodeMessagesUrl, g as ZCODE_ANTHROPIC_BASE_URL, h as DEFAULT_ZCODE_ENDPOINT_PLAN, i as ZCodeClientModel, l as ZCodeOAuthPoll, m as zcodeSourceHeaders, n as ZCodeBalanceSnapshot, o as ZCodeConsoleClient, p as zcodeModelHeaders, r as ZCodeClientConfigSnapshot, s as ZCodeConsoleError, t as ZCodeAgentConfigSnapshot, u as ZCodeRawBalance, v as ZCODE_CLIENT_VERSION, w as ZCODE_PROVIDER_NAME, x as ZCODE_FAMILY_LABELS, y as ZCODE_ENDPOINT_PLAN_LABELS } from "./console-client-54wUcPDA.js";
+import { a as zcodeAuthPath, c as ZCodeCredentialRecord, i as ZCodeCredentialStore, l as ZCodeLoginChallenge, n as ZCodeAuthServiceOptions, o as ZCodeAccountInfo, r as ZCODE_AUTH_FILENAME, s as ZCodeAuthStatus, t as ZCodeAuthService } from "./auth-B99K5y4S.js";
+import { C as selectableModels, S as normalizeModelId, _ as ZCodePlanEntry, a as ZCodeCatalogServiceOptions, b as findModel, c as modelIdsFromBalances, d as toModel, f as ZCODE_REASONING_LEVELS, g as ZCodeModel, h as ZCodeCatalog, i as ZCodeCatalogService, l as thinkingLevelMapOf, m as ZCodeBalanceEntry, n as ZCODE_FALLBACK_CONTEXT_WINDOW, p as ZCodeApiKind, r as ZCODE_FALLBACK_MAX_TOKENS, t as ZCODE_BUILTIN_MODEL_IDS, u as toBalanceEntries, v as ZCodeReasoningLevel, x as modelIdOfCapability, y as ZCodeThinkingLevelMap } from "./catalog-CnI_VsFm.js";
+import { C as zcodePreferencesPath, D as ZCodeUsageVisibility, E as ZCodePreferences, O as normalizePreferences, S as ZCodePreferencesStore, T as ZCODE_REFRESH_MINUTES, _ as ZCodeRouteStatus, a as trustedRequest, b as toPiModel, c as ZCodeUsageService, d as ZCodeUsageWindow, f as remainingPercent, g as ZCodeProviderRuntimeOptions, h as ZCodeProviderRuntime, i as registerZCodeRoutes, l as ZCodeUsageServiceOptions, m as usagePercent, n as ZCODE_ORIGIN_NOT_TRUSTED, o as ZCodeUsageFailure, p as resetAfterMs, r as ZCodeRoutesOptions, s as ZCodeUsageResult, t as ZCODE_CATALOG_UNAVAILABLE, u as ZCodeUsage, v as createZCodeProfile, w as DEFAULT_ZCODE_PREFERENCES, x as ZCODE_PREFERENCES_FILENAME, y as createZCodeProvider } from "./routes-DhHLL5UC.js";
+import { ContentBlock, GenerateOptions, LlmAdapter, LlmModelInfo, LlmResolvedModelInfo, ReasoningEffortId, RequestMessage, StreamChunk, TokenUsage, ToolSchema } from "@deepseek-ai/dsh-llm";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/host/start-plan-prefix.d.ts
+/**
+ * Start Plan 端点的准入前缀。
+ *
+ * 实测结论（2026-10-25，抓包 + 逐项二分）：`/api/v1/zcode-plan/anthropic`
+ * 会在网关侧校验 `system` 是否为官方 agent 原文——两段内容必须逐字一致，
+ * `system[0]` 少一个字母都会被判 `3012`；`system[1]` 必须作为完整前缀出现，
+ * 其后可以继续追加内容。除此之外请求头只需要三个，工具声明、metadata、
+ * device_id 与各类 `x-zcode-*` 头都与放行无关。
+ *
+ * 这两段文字是 ZCode 官方 agent 的系统提示词。插件把它们作为**前缀**放在
+ * 自己构造的 system 之前，以满足该校验；DSH 自己的指令接在其后。
+ * 上游若改动提示词，这里会失配并退回 `3012`，届时需要重新采集。
+ *
+ * @module dsh-zcode/start-plan-prefix
+ */
+/** 第一段：固定 42 字符的 agent 身份行，必须逐字一致。 */
+declare const START_PLAN_PREFIX_HEAD: string;
+/**
+ * 第二段：官方 agent 的行为提示词，必须作为完整前缀出现。
+ *
+ * 只做前缀匹配，因此可以在它之后追加插件自己的约束。
+ */
+declare const START_PLAN_PREFIX_BODY: string;
+/** 注入到 system 最前面的两段前缀。 */
+declare function startPlanSystemPrefix(): readonly {
+  readonly type: 'text';
+  readonly text: string;
+}[];
+//#endregion
+//#region src/host/http/translate.d.ts
+/** 一条 Anthropic 消息。 */
+interface AnthropicMessage {
+  role: 'user' | 'assistant';
+  content: readonly unknown[];
+}
+/** 从消息里取出纯文本（system 消息或拼接用）。 */
+declare function messageText(message: RequestMessage): string;
+/** 取出首条 system 消息的文本；没有则返回 undefined。 */
+declare function leadingSystem(messages: readonly RequestMessage[]): string | undefined;
+/**
+ * 把 DSH 消息转换成 Anthropic 消息数组。
+ *
+ * - system 消息由调用方单独放进 `system` 字段，这里跳过；
+ * - `tool-call` 块转成 `tool_use`；
+ * - 工具结果消息转成带 `tool_result` 块的 user 消息（Anthropic 要求如此）；
+ * - 图片块转成 base64 image 块（由调用方提供读取字节的能力）。
+ */
+declare function toAnthropicMessages(messages: readonly RequestMessage[], readImage?: (block: Extract<ContentBlock, {
+  type: 'image';
+}>) => Promise<{
+  mediaType: string;
+  data: string;
+} | undefined>): Promise<AnthropicMessage[]>;
+/** DSH 工具声明 → Anthropic tools。 */
+declare function toAnthropicTools(tools: readonly ToolSchema[] | undefined): readonly unknown[] | undefined;
+/** DSH 思考等级 → Anthropic `output_config.effort`。 */
+declare function toEffort(level: string | undefined, map?: Readonly<Record<string, string | null>>): string;
+//#endregion
+//#region src/host/http/adapter.d.ts
+/** 一个可执行模型。 */
+interface ZCodeHttpModel {
+  readonly id: string;
+  readonly name: string;
+  readonly contextWindow: number;
+  readonly maxTokens: number;
+  readonly reasoning: boolean;
+  readonly efforts?: readonly {
+    readonly id: ReturnType<typeof ReasoningEffortId>;
+    readonly name: string;
+  }[];
+  /** 等级 → 上游字符串；与 efforts 同源，用于把所选等级翻译成请求字段。 */
+  readonly thinkingLevelMap?: Readonly<Record<string, string | null>>;
+  readonly inputModalities?: readonly ('text' | 'image')[];
+}
+/** 通道依赖。 */
+interface ZCodeHttpAdapterOptions {
+  /** 当前模型清单（每次调用读取，目录刷新后立刻生效）。 */
+  readonly models: () => readonly ZCodeHttpModel[];
+  /** 当前端点策略与凭据。 */
+  readonly baseUrl: () => string;
+  readonly apiKey: () => Promise<string | undefined>;
+  /** 设备标识，写入 metadata 与请求头。 */
+  readonly deviceId: () => string;
+  /** 客户端身份头。 */
+  readonly headers?: () => Record<string, string>;
+  /** 读取图片附件为 base64；不支持图片时返回 undefined。 */
+  /**
+   * 把图片附件读成 base64。
+   *
+   * 必须是异步：附件字节由宿主的附件服务异步读取并按路由上限压缩。
+   * 返回 undefined 表示该图跳过（例如读取失败），不影响整条请求。
+   */
+  readonly readImage?: (block: Extract<ContentBlock, {
+    type: 'image';
+  }>) => Promise<{
+    mediaType: string;
+    data: string;
+  } | undefined>;
+  readonly logger?: {
+    warn(message: string): void;
+  };
+  /** 便于测试注入。 */
+  readonly fetchImpl?: typeof fetch;
+}
+/** 自行发送的适配器。 */
+declare class ZCodeHttpAdapter extends LlmAdapter {
+  private readonly options;
+  constructor(options: ZCodeHttpAdapterOptions);
+  providerInfo(provider: string): {
+    readonly id: string;
+    readonly name: string;
+  };
+  listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+  resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+  stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+  /** 端点策略（诊断用）。 */
+  planOf(baseUrl: string): ZCodeEndpointPlan;
+}
+//#endregion
+//#region src/host/http/messages-client.d.ts
+/** 官方 agent 的两段 system 前缀在发出前的固定形态。 */
+interface SystemPrefix {
+  readonly head: string;
+  readonly body: string;
+}
+/** 一次请求所需的全部输入。 */
+interface MessagesRequest {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly model: string;
+  readonly maxTokens: number;
+  /** DSH 自己的系统提示词；会接在官方前缀之后。 */
+  readonly system: string | undefined;
+  /** Anthropic 格式的消息数组（已转换）。 */
+  readonly messages: readonly unknown[];
+  /** 工具声明（已转换为 Anthropic 格式）。 */
+  readonly tools: readonly unknown[] | undefined;
+  /** 思考强度；开启推理时写入 `output_config.effort`。 */
+  readonly effort?: string;
+  /** 是否启用思考。 */
+  readonly thinking?: boolean;
+  readonly temperature?: number;
+  readonly signal?: AbortSignal;
+  /** 设备标识：写入 `metadata.user_id`，与请求头同源。 */
+  readonly deviceId: string;
+  readonly sessionId?: string;
+  /** 请求头（客户端身份）。 */
+  readonly extraHeaders?: Record<string, string>;
+  /** 发生限流重试时的观察回调（用于日志与诊断）。 */
+  readonly onRateLimit?: (info: {
+    readonly attempt: number;
+    readonly status: number;
+    readonly businessCode: string | undefined;
+    readonly delayMs: number;
+  }) => void;
+}
+/** 解析后的流事件。 */
+type MessagesEvent = {
+  readonly kind: 'message-start';
+  readonly model: string;
+  readonly usage?: TokenUsage;
+} | {
+  readonly kind: 'block-start';
+  readonly index: number;
+  readonly blockType: 'text' | 'thinking' | 'tool_use';
+  readonly id?: string;
+  readonly name?: string;
+} | {
+  readonly kind: 'text-delta';
+  readonly index: number;
+  readonly text: string;
+} | {
+  readonly kind: 'thinking-delta';
+  readonly index: number;
+  readonly text: string;
+} | {
+  readonly kind: 'signature-delta';
+  readonly index: number;
+  readonly signature: string;
+} | {
+  readonly kind: 'tool-delta';
+  readonly index: number;
+  readonly id: string;
+  readonly name?: string;
+  readonly argumentsDelta: string;
+} | {
+  readonly kind: 'block-stop';
+  readonly index: number;
+} | {
+  readonly kind: 'message-delta';
+  readonly stopReason: string;
+  readonly usage?: TokenUsage;
+} | {
+  readonly kind: 'error';
+  readonly message: string;
+  readonly errorType?: string;
+};
+/** 把上游 usage 投影成 DSH 计数（字段互斥）。 */
+declare function toUsage(raw: unknown): TokenUsage;
+/** 组装请求体：把 DSH system 接在官方前缀之后，并补齐官方附加字段。 */
+declare function buildMessagesBody(request: MessagesRequest, prefix: SystemPrefix): Record<string, unknown>;
+/** 解析一条 SSE `data:` 载荷；无法识别时返回 undefined。 */
+declare function parseEvent(payload: string): MessagesEvent | undefined;
+/**
+ * 发出请求并按行解析流。
+ *
+ * 用 `for await` 逐块读，遇到 `data:` 行就解析；`[DONE]` 与空行跳过。
+ */
+declare function streamMessages(request: MessagesRequest, prefix: SystemPrefix, fetchImpl?: typeof fetch): AsyncIterable<MessagesEvent>;
+//#endregion
+//#region src/contracts/routes.d.ts
+/**
+ * 插件同源 Web 路由：宿主注册、浏览器调用，两端引用同一份常量。
+ *
+ * 不用 Remote API 命名空间，是因为这里只有低频率、无状态的读写；同源 HTTP
+ * 路由的信任边界由宿主侧 `trustedRequest` 把关，与其他账号插件一致。
+ *
+ * @module dsh-zcode/routes
+ */
+/** 本插件 Web 路由的前缀。 */
+declare const ZCODE_ROUTE_PREFIX = "/plugins/dsh-zcode";
+declare const ZCODE_ROUTES: {
+  /** 账号状态（含进行中的登录挑战）。 */
+  readonly status: "/plugins/dsh-zcode/auth/status";
+  /** 开始授权；响应带授权地址。 */
+  readonly login: "/plugins/dsh-zcode/auth/login";
+  /** 桌面授权码流程的回调地址：浏览器登录后回跳到这里完成换取。 */
+  readonly callback: "/plugins/dsh-zcode/auth/callback";
+  /** 取消进行中的登录，不删除已保存凭据。 */
+  readonly cancel: "/plugins/dsh-zcode/auth/cancel";
+  /** 退出登录并删除凭据。 */
+  readonly logout: "/plugins/dsh-zcode/auth/logout";
+  /** Start Plan 额度。 */
+  readonly usage: "/plugins/dsh-zcode/usage";
+  /** 当前模型目录快照。 */
+  readonly catalog: "/plugins/dsh-zcode/catalog";
+  /** 强制刷新模型目录。 */
+  readonly catalogRefresh: "/plugins/dsh-zcode/catalog/refresh";
+  /** 插件偏好设置。 */
+  readonly preferences: "/plugins/dsh-zcode/preferences";
+};
+//#endregion
+//#region src/index.d.ts
+/** 稳定的宿主插件名。 */
+declare const name = "dsh-zcode-plugin";
+/**
+ * 模型层是硬依赖；Web 路由是可选增强。
+ *
+ * headless / tui 一类的 profile 没有 `webServer`，插件仍应提供服务；
+ * 详情页与同源路由通过 `ctx.inject(['webServer'], …)` 只在 Web 装配下注册。
+ * 否则插件会停在 pending，模型路由也不会注册（表现为 `NO_ADAPTER`）。
+ */
+declare const inject: string[];
+declare function apply(ctx: Context): void;
+//#endregion
+export { DEFAULT_ZCODE_ENDPOINT_PLAN, DEFAULT_ZCODE_PREFERENCES, type MessagesEvent, type MessagesRequest, START_PLAN_PREFIX_BODY, START_PLAN_PREFIX_HEAD, type SystemPrefix, ZCODE_ANTHROPIC_BASE_URL, ZCODE_ANTHROPIC_BASE_URLS, ZCODE_AUTH_FILENAME, ZCODE_BUILTIN_MODEL_IDS, ZCODE_CATALOG_UNAVAILABLE, ZCODE_CLIENT_VERSION, ZCODE_ENDPOINT_PLAN_LABELS, ZCODE_FALLBACK_CONTEXT_WINDOW, ZCODE_FALLBACK_MAX_TOKENS, ZCODE_FAMILIES, ZCODE_FAMILY_LABELS, ZCODE_ORIGIN, ZCODE_ORIGIN_NOT_TRUSTED, ZCODE_PREFERENCES_FILENAME, ZCODE_PROVIDER, ZCODE_PROVIDER_NAME, ZCODE_REASONING_LEVELS, ZCODE_REFRESH_MINUTES, ZCODE_ROUTES, ZCODE_ROUTE_PREFIX, ZCODE_USER_AGENT, type ZCodeAccountInfo, type ZCodeAgentConfigSnapshot, type ZCodeApiKind, ZCodeAuthService, type ZCodeAuthServiceOptions, type ZCodeAuthStatus, type ZCodeBalanceEntry, type ZCodeBalanceSnapshot, type ZCodeCatalog, ZCodeCatalogService, type ZCodeCatalogServiceOptions, type ZCodeClientConfigSnapshot, type ZCodeClientModel, type ZCodeClientOptions, ZCodeConsoleClient, ZCodeConsoleError, type ZCodeCredentialRecord, ZCodeCredentialStore, type ZCodeEndpointPlan, type ZCodeFamily, ZCodeHttpAdapter, type ZCodeHttpAdapterOptions, type ZCodeHttpModel, type ZCodeLoginChallenge, type ZCodeModel, type ZCodeOAuthInit, type ZCodeOAuthPoll, type ZCodePlanEntry, type ZCodePreferences, ZCodePreferencesStore, ZCodeProviderRuntime, type ZCodeProviderRuntimeOptions, type ZCodeRawBalance, type ZCodeRawPlan, type ZCodeReasoningLevel, type ZCodeRouteStatus, type ZCodeRoutesOptions, type ZCodeThinkingLevelMap, type ZCodeUsage, type ZCodeUsageFailure, type ZCodeUsageResult, ZCodeUsageService, type ZCodeUsageServiceOptions, type ZCodeUsageVisibility, type ZCodeUsageWindow, apply, buildMessagesBody, createZCodeProfile, createZCodeProvider, findModel, inject, leadingSystem, messageText, modelIdOfCapability, modelIdsFromBalances, name, normalizeModelId, normalizePreferences, parseEvent, registerZCodeRoutes, remainingPercent, resetAfterMs, selectableModels, startPlanSystemPrefix, streamMessages, thinkingLevelMapOf, toAnthropicMessages, toAnthropicTools, toBalanceEntries, toEffort, toModel, toPiModel, toUsage, trustedRequest, usagePercent, zcodeAuthPath, zcodeMessagesUrl, zcodeModelHeaders, zcodePreferencesPath, zcodeSourceHeaders };