@tokenbuddy/tokenbuddy 1.0.12 → 1.0.13

package/src/seller-routing-strategy.ts

@@ -0,0 +1,316 @@
+/**
+ * seller 路由模式：
+ * - `fixed`：强制使用单个 seller（`sellerId`）
+ * - `fixedSet`：在指定 seller 集合内挑选
+ * - `fullAuto`：根据指标和 scorer 自动排序
+ */
+export type SellerRoutingMode = "fixed" | "fixedSet" | "fullAuto";
+/**
+ * 评分器：决定如何把候选的健康/延迟/折扣分折算成总分。
+ * - `speed`：TTFT / 推理延迟优先
+ * - `discount`：折扣系数优先
+ * - `balanced`：三方面加权均衡
+ */
+export type SellerRoutingScorer = "speed" | "discount" | "balanced";
+
+/**
+ * seller 路由策略配置：模式 + 可选的目标 seller 列表 + 可选评分器。
+ * 策略层不强制 `scorer` 必填（缺省走 `balanced`）；buyer 配置层
+ * `BuyerSellerRoutingConfig` 会进一步收紧。
+ */
+export interface SellerRoutingStrategyConfig {
+  /** 路由模式 */
+  mode: SellerRoutingMode;
+  /** `fixed` 模式下唯一允许的 seller ID */
+  sellerId?: string;
+  /** `fixedSet` 模式下的候选 seller ID 列表（去重） */
+  sellerIds?: string[];
+  /** 评分器；省略时按 `balanced` 处理 */
+  scorer?: SellerRoutingScorer;
+}
+
+/**
+ * 路由规划阶段的中间数据结构：聚合了"兼容性 + 健康画像 + 折扣"。
+ * `supportsModel/Protocol/Payment` 由 `sellerSupports*` 系列函数计算，
+ * 任一为 `false` 的 candidate 都会被策略层过滤。
+ */
+export interface RoutingCandidate {
+  /** seller ID */
+  sellerId: string;
+  /** 去掉尾部斜杠的 seller URL */
+  url: string;
+  /** 是否在 seller 的 `models` 列表里 */
+  supportsModel: boolean;
+  /** 是否在 seller 的 `supportedProtocols` 列表里（含 `messages` alias） */
+  supportsProtocol: boolean;
+  /** 是否在 seller 的 `paymentMethods` 列表里 */
+  supportsPayment: boolean;
+  /** 综合健康分 0-100，可选 */
+  healthScore?: number;
+  /** 平均延迟（毫秒），可选 */
+  avgLatencyMs?: number;
+  /** health probe 延迟（毫秒），可选 */
+  healthProbeLatencyMs?: number;
+  /** TTFT（毫秒），可选 */
+  ttftMs?: number;
+  /** 平均推理延迟（毫秒），可选 */
+  avgInferenceMs?: number;
+  /** 折扣系数 0-1，可选；缺省视为"无折扣信息" */
+  discountRatio?: number;
+  /** 上游状态，可选 */
+  upstreamStatus?: "healthy" | "degraded" | "unhealthy" | "unknown";
+  /** 上游错误类名，可选 */
+  upstreamErrorClass?: string;
+  /** 在 registry 里的声明顺序（0-based），用于打分平局时的 deterministic 兜底 */
+  registryOrder: number;
+}
+
+/**
+ * `planSellerRoutes()` 的输出：选中的候选列表（已按 scorer 排序）+ 决策溯源。
+ */
+export interface SellerRoutingPlan {
+  /** 已按策略排序的候选 seller 列表 */
+  routes: RoutingCandidate[];
+  /** 路由模式（来自 config） */
+  mode: SellerRoutingMode;
+  /** 实际生效的评分器（config 缺省时为 `balanced`） */
+  scorer: SellerRoutingScorer;
+  /** 决策原因，例：`fullAuto:balanced:routes_3`、`fixed_seller_not_compatible` */
+  reason: string;
+}
+
+/**
+ * 单个 candidate 在某 scorer 下的打分拆解：总分 + 各维度分量 + 缺失的输入。
+ * 用于路由诊断 / `tb doctor` 面板展示。
+ */
+export interface CandidateScoreBreakdown {
+  /** 评分器 */
+  scorer: SellerRoutingScorer;
+  /** 总分（按 scorer 权重加和） */
+  totalScore: number;
+  /** 健康分量（仅 `speed` / `balanced` 有意义） */
+  healthComponent?: number;
+  /** TTFT 分量（仅 `speed` / `balanced` 有意义） */
+  ttftComponent?: number;
+  /** 平均推理延迟分量（仅 `speed` / `balanced` 有意义） */
+  avgInferenceComponent?: number;
+  /** 折扣分量（仅 `discount` / `balanced` 有意义） */
+  discountComponent?: number;
+  /** 打分时缺失的输入项；缺越多则越说明"无依据" */
+  missingInputs: Array<"healthScore" | "ttftMs" | "avgInferenceMs" | "discountRatio">;
+}
+
+type SortableCandidate = RoutingCandidate & { score: number };
+
+const DEFAULT_SCORER: SellerRoutingScorer = "balanced";
+
+/**
+ * 根据 `config.mode` 和 `config.scorer` 把候选 seller 过滤、排序并返回路由计划。
+ * - `fixed` / `fixedSet` 模式只保留命中的 seller（命中为空时返回空 routes + 决策原因）
+ * - `fullAuto` 模式使用所有兼容候选
+ * - 排序时按 scorer 计算分数，分数相同时按 `registryOrder` 兜底
+ *
+ * @param candidates 候选列表（已包含兼容性布尔位）
+ * @param config 路由策略配置
+ * @returns 路由计划，含 routes / mode / scorer / reason
+ */
+export function planSellerRoutes(
+  candidates: RoutingCandidate[],
+  config: SellerRoutingStrategyConfig
+): SellerRoutingPlan {
+  const scorer = config.scorer ?? DEFAULT_SCORER;
+  const compatible = candidates.filter(isCompatibleCandidate);
+  const selected = selectCandidates(compatible, config);
+
+  if (selected.reason !== "ok") {
+    return {
+      routes: [],
+      mode: config.mode,
+      scorer,
+      reason: selected.reason
+    };
+  }
+
+  return {
+    routes: sortCandidates(selected.candidates, scorer),
+    mode: config.mode,
+    scorer,
+    reason: routeReason(config.mode, scorer, selected.candidates.length)
+  };
+}
+
+function selectCandidates(
+  compatible: RoutingCandidate[],
+  config: SellerRoutingStrategyConfig
+): { candidates: RoutingCandidate[]; reason: string } {
+  if (config.mode === "fixed") {
+    const sellerId = normalizeSellerId(config.sellerId);
+    if (!sellerId) {
+      return { candidates: [], reason: "fixed_seller_missing" };
+    }
+    const matched = compatible.filter((candidate) => normalizeSellerId(candidate.sellerId) === sellerId);
+    return matched.length > 0
+      ? { candidates: matched, reason: "ok" }
+      : { candidates: [], reason: "fixed_seller_not_compatible" };
+  }
+
+  if (config.mode === "fixedSet") {
+    const sellerIds = normalizedSellerIdSet(config.sellerIds);
+    if (sellerIds.size === 0) {
+      return { candidates: [], reason: "fixed_set_empty" };
+    }
+    const matched = compatible.filter((candidate) => sellerIds.has(normalizeSellerId(candidate.sellerId)));
+    return matched.length > 0
+      ? { candidates: matched, reason: "ok" }
+      : { candidates: [], reason: "fixed_set_no_compatible_seller" };
+  }
+
+  if (config.mode === "fullAuto") {
+    return compatible.length > 0
+      ? { candidates: compatible, reason: "ok" }
+      : { candidates: [], reason: "no_compatible_seller" };
+  }
+
+  return { candidates: [], reason: "unsupported_routing_mode" };
+}
+
+function isCompatibleCandidate(candidate: RoutingCandidate): boolean {
+  return candidate.supportsModel && candidate.supportsProtocol && candidate.supportsPayment;
+}
+
+function normalizedSellerIdSet(ids: string[] | undefined): Set<string> {
+  return new Set((ids ?? []).map(normalizeSellerId).filter(Boolean));
+}
+
+function normalizeSellerId(id: string | undefined): string {
+  return id?.trim().toLowerCase() ?? "";
+}
+
+function sortCandidates(candidates: RoutingCandidate[], scorer: SellerRoutingScorer): RoutingCandidate[] {
+  return candidates
+    .map((candidate) => ({ ...candidate, score: scoreCandidateBreakdown(candidate, scorer).totalScore }))
+    .sort((a, b) => compareCandidates(a, b, scorer))
+    .map(({ score: _score, ...candidate }) => candidate);
+}
+
+function compareCandidates(a: SortableCandidate, b: SortableCandidate, scorer: SellerRoutingScorer): number {
+  const scoreDiff = b.score - a.score;
+  if (scoreDiff !== 0) {
+    return scoreDiff;
+  }
+
+  if (scorer === "speed") {
+    return compareFiniteAsc(effectiveTtftMs(a), effectiveTtftMs(b))
+      || compareFiniteAsc(effectiveAvgInferenceMs(a), effectiveAvgInferenceMs(b))
+      || compareFiniteDesc(a.healthScore, b.healthScore)
+      || compareRegistryOrder(a, b);
+  }
+
+  if (scorer === "discount") {
+    return compareFiniteAsc(a.discountRatio, b.discountRatio)
+      || compareFiniteDesc(a.healthScore, b.healthScore)
+      || compareRegistryOrder(a, b);
+  }
+
+  return compareRegistryOrder(a, b);
+}
+
+/**
+ * 计算单个 candidate 在指定 scorer 下的完整打分拆解（含各维度分量和缺失项）。
+ * 不会修改输入 candidate，常用于 doctor 面板和调试日志。
+ *
+ * @param candidate 待打分的候选
+ * @param scorer 评分器：`speed` / `discount` / `balanced`
+ * @returns 打分拆解
+ */
+export function scoreCandidateBreakdown(candidate: RoutingCandidate, scorer: SellerRoutingScorer): CandidateScoreBreakdown {
+  const missingInputs = missingScoreInputs(candidate);
+  if (scorer === "speed") {
+    const ttftComponent = latencyScore(effectiveTtftMs(candidate)) * 0.65;
+    const avgInferenceComponent = latencyScore(effectiveAvgInferenceMs(candidate)) * 0.25;
+    const healthComponent = finiteOr(candidate.healthScore, 0) * 0.1;
+    return {
+      scorer,
+      totalScore: ttftComponent + avgInferenceComponent + healthComponent,
+      healthComponent,
+      ttftComponent,
+      avgInferenceComponent,
+      missingInputs
+    };
+  }
+
+  if (scorer === "discount") {
+    const totalScore = -finiteOr(candidate.discountRatio, Number.POSITIVE_INFINITY);
+    return {
+      scorer,
+      totalScore,
+      discountComponent: totalScore,
+      missingInputs
+    };
+  }
+
+  const healthComponent = finiteOr(candidate.healthScore, 0) * 0.35;
+  const ttftComponent = latencyScore(effectiveTtftMs(candidate)) * 0.2;
+  const avgInferenceComponent = latencyScore(effectiveAvgInferenceMs(candidate)) * 0.2;
+  const discountComponent = discountScore(candidate.discountRatio) * 0.25;
+  return {
+    scorer,
+    totalScore: healthComponent + ttftComponent + avgInferenceComponent + discountComponent,
+    healthComponent,
+    ttftComponent,
+    avgInferenceComponent,
+    discountComponent,
+    missingInputs
+  };
+}
+
+function latencyScore(latencyMs: number | undefined): number {
+  if (!Number.isFinite(latencyMs)) {
+    return 0;
+  }
+  return Math.max(0, 100 - Math.max(0, latencyMs as number) / 10);
+}
+
+function discountScore(discountRatio: number | undefined): number {
+  if (!Number.isFinite(discountRatio)) {
+    return 0;
+  }
+  return Math.max(0, 100 * (1 - Math.max(0, discountRatio as number)));
+}
+
+function finiteOr(value: number | undefined, fallback: number): number {
+  return Number.isFinite(value) ? value as number : fallback;
+}
+
+function compareFiniteAsc(a: number | undefined, b: number | undefined): number {
+  return finiteOr(a, Number.POSITIVE_INFINITY) - finiteOr(b, Number.POSITIVE_INFINITY);
+}
+
+function compareFiniteDesc(a: number | undefined, b: number | undefined): number {
+  return finiteOr(b, Number.NEGATIVE_INFINITY) - finiteOr(a, Number.NEGATIVE_INFINITY);
+}
+
+function effectiveTtftMs(candidate: RoutingCandidate): number | undefined {
+  return candidate.ttftMs ?? candidate.healthProbeLatencyMs ?? candidate.avgLatencyMs;
+}
+
+function effectiveAvgInferenceMs(candidate: RoutingCandidate): number | undefined {
+  return candidate.avgInferenceMs ?? candidate.avgLatencyMs ?? candidate.healthProbeLatencyMs;
+}
+
+function compareRegistryOrder(a: RoutingCandidate, b: RoutingCandidate): number {
+  return a.registryOrder - b.registryOrder;
+}
+
+function routeReason(mode: SellerRoutingMode, scorer: SellerRoutingScorer, count: number): string {
+  return `${mode}:${scorer}:routes_${count}`;
+}
+
+function missingScoreInputs(candidate: RoutingCandidate): CandidateScoreBreakdown["missingInputs"] {
+  const missing: CandidateScoreBreakdown["missingInputs"] = [];
+  if (!Number.isFinite(candidate.healthScore)) missing.push("healthScore");
+  if (!Number.isFinite(candidate.ttftMs)) missing.push("ttftMs");
+  if (!Number.isFinite(candidate.avgInferenceMs)) missing.push("avgInferenceMs");
+  if (!Number.isFinite(candidate.discountRatio)) missing.push("discountRatio");
+  return missing;
+}

package/src/stream-failover.ts

@@ -16,19 +16,42 @@ const logger = createModuleLogger("tb-proxyd:stream-failover");
  * doc) because that would double-charge and would require non-trivial
  * idempotency re-design. v1.2 = abort + retry; v2 may revisit.
  */
+/**
+ * v1.2 §6 / §18.10：stream-failover 策略。
+ * buyer 端遵循"abort + client retry"契约：一旦首字节 SSE 写入客户端，上游流失败只能 abrupt close
+ * 并附带 `X-TokenBuddy-Retry-Hint: 1` trailer；由 OpenAI / Anthropic SDK 重新发起请求，
+ * buyer 切到健康的 seller 重发。
+ *
+ * 该模块的决策是单向的：buyer 不会把两条流拼接（design doc 里的 option B），
+ * 因为会双重计费且需要重做幂等。v1.2 = abort + retry；v2 再考虑。
+ */
 export interface StreamFailoverOptions {
+  /** abort 响应中携带的 retry hint 响应头名，默认 `X-TokenBuddy-Retry-Hint` */
   retryHintHeader?: string;
+  /** 时间源，默认 `Date.now`；测试可注入 */
   now?: () => number;
 }
 
+/**
+ * `StreamFailover.decideOnStreamAbort` 的返回结果。
+ */
 export interface StreamFailoverDecision {
+  /** 决策动作：abort_with_retry_hint（已写首字节，abrupt close） / let_stream_complete（路由层可换 seller） */
   action: "abort_with_retry_hint" | "let_stream_complete";
+  /** 决策原因（用于日志和稳定事件断言） */
   reason: string;
+  /** retry hint 头的取值（`"0"` 或 `"1"`） */
   retryHintValue: string;
+  /** 决策时是否已写过首字节（决策的输入状态） */
   firstChunkCommitted: boolean;
+  /** 决策时已写入客户端的字节数 */
   bytesFlushed: number;
 }
 
+/**
+ * buyer 端 SSE 流失败决策器。
+ * 跟踪"首字节是否已写客户端"和"累计写入字节数"，在 upstream 中断时决定是 abort+retry 还是切 seller 重试。
+ */
 export class StreamFailover {
   private readonly retryHintHeader: string;
   private readonly now: () => number;

package/src/tb-proxyd.ts

@@ -1,6 +1,7 @@
 import { TokenbuddyDaemon } from "./daemon.js";
 import { createModuleLogger } from "@tokenbuddy/logging";
 import { resolveBuyerStorePath } from "./buyer-store.js";
+import { normalizeSellerRoutingConfig, parseSellerRoutingEnv } from "./seller-routing-config.js";
 
 const logger = createModuleLogger("tb-proxyd");
 
@@ -8,16 +9,15 @@ const dbPath = resolveBuyerStorePath();
 const controlPort = parsePortEnv("TB_PROXYD_CONTROL_PORT", 17820);
 const proxyPort = parsePortEnv("TB_PROXYD_PROXY_PORT", 17821);
 const sellerRegistryUrl = process.env.TB_PROXYD_SELLER_REGISTRY_URL || "https://tb-wallet-bootstrap.fly.dev/registry/sellers";
-const selectionMode = parseSelectionModeEnv();
-const selectedSellerId = parseSelectedSellerIdEnv();
+const sellerRoutingEnv = parseSellerRoutingEnv();
+const sellerRouting = sellerRoutingEnv ? normalizeSellerRoutingConfig(sellerRoutingEnv) : undefined;
 
 const daemon = new TokenbuddyDaemon({
   controlPort,
   proxyPort,
   dbPath,
   sellerRegistryUrl,
-  selectionMode,
-  selectedSellerId
+  ...(sellerRouting ? { sellerRouting } : {})
 });
 
 logger.info("proxy.process.initializing", "tb-proxyd process initializing", {
@@ -25,8 +25,9 @@ logger.info("proxy.process.initializing", "tb-proxyd process initializing", {
   controlPort,
   proxyPort,
   sellerRegistryUrl,
-  selectionMode,
-  selectedSellerId
+  sellerRoutingEnvOverride: Boolean(sellerRouting),
+  sellerRoutingMode: sellerRouting?.mode,
+  sellerRoutingScorer: sellerRouting?.scorer
 });
 daemon.start();
 
@@ -53,20 +54,3 @@ function parsePortEnv(name: string, fallback: number): number {
   }
   return port;
 }
-
-function parseSelectionModeEnv(): "auto" | "manual" {
-  const rawValue = process.env.TB_PROXYD_SELECTION_MODE || "auto";
-  if (rawValue === "auto" || rawValue === "manual") {
-    return rawValue;
-  }
-  throw new Error("TB_PROXYD_SELECTION_MODE must be auto or manual");
-}
-
-function parseSelectedSellerIdEnv(): string | undefined {
-  const rawValue = process.env.TB_PROXYD_SELECTED_SELLER_ID;
-  if (!rawValue) {
-    return undefined;
-  }
-  const trimmed = rawValue.trim();
-  return trimmed || undefined;
-}

package/src/terminal-detect.ts

@@ -2,23 +2,44 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 
+/**
+ * `detectTerminals()` 的输出单元：描述一个可被 rewrite 的 coding terminal。
+ * `detected=false` 时仍会返回，UI 用其渲染"未安装"标签而不是直接跳过。
+ */
 export interface TerminalCandidate {
+  /** terminal 内部 ID，例：`claude-code` / `claude-desktop` / `openclaw` / `hermes` */
   id: string;
+  /** 人类可读名称，例：`Claude Code CLI` */
   name: string;
+  /** 本机是否检测到该 terminal 的配置文件 */
   detected: boolean;
+  /** 配置文件绝对路径（即使未检测到也会拼出预期路径） */
   configPath: string;
+  /** 检测结果的说明，用于 UI 展示 */
   reason: string;
 }
 
 const PLACEHOLDER_API_KEY = "TOKENBUDDY_PROXY";
 const DESKTOP_PROFILE_ID = "00000000-0000-4000-8000-000000178210";
 
+/**
+ * 获取当前用户的 home 目录，作为拼装 terminal 配置路径的基准。
+ *
+ * @returns `os.homedir()` 返回的 home 路径
+ */
 export function getHomeDir(): string {
   return os.homedir();
 }
 
 /**
  * Detect which coding terminals are installed on the local system.
+ *
+ * 通过 `~/.claude/settings.json`、`Library/Application Support/Claude/...`、
+ * `~/.openclaw/config.json`、`~/.hermes/settings.json` 等约定路径判断。
+ * Claude Desktop 在非 macOS 平台上 `configPath` 可能为空字符串，
+ * 调用方需以 `detected` 字段为准。
+ *
+ * @returns terminal 候选列表（固定四个 ID 顺序）
  */
 export function detectTerminals(): TerminalCandidate[] {
   const home = getHomeDir();
@@ -79,6 +100,14 @@ export function detectTerminals(): TerminalCandidate[] {
 
 /**
  * Safely rewrite Claude Code settings to route requests through our proxy.
+ *
+ * 写入 `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN`（占位 `TOKENBUDDY_PROXY`）/
+ * `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL`。失败时仅打印日志，
+ * 不会抛出异常；调用方无需 try/catch。
+ *
+ * @param configPath `~/.claude/settings.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Claude Code 默认模型 ID
  */
 export function rewriteClaudeCode(configPath: string, proxyUrl: string, model: string): void {
   try {
@@ -112,6 +141,14 @@ export function rewriteClaudeCode(configPath: string, proxyUrl: string, model: s
 
 /**
  * Safely rewrite Claude Desktop configuration.
+ *
+ * 写入 `deploymentMode = "3p"` 到 Claude 与 Claude-3p 两个目录，
+ * 并在 `configLibrary/<DESKTOP_PROFILE_ID>.json` 写入 TokenBuddy profile。
+ * 最后更新 `_meta.json` 把 `appliedId` 指向该 profile。
+ *
+ * @param configPath Claude Desktop 主配置（`claude_desktop_config.json`）绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Claude Desktop 默认模型 ID
  */
 export function rewriteClaudeDesktop(configPath: string, proxyUrl: string, model: string): void {
   try {
@@ -175,6 +212,13 @@ export function rewriteClaudeDesktop(configPath: string, proxyUrl: string, model
 
 /**
  * Rewrite Openclaw settings.
+ *
+ * 写入 `api_url` / `api_key`（占位 `TOKENBUDDY_PROXY`）/`model`。
+ * 失败仅打印日志，不抛出。
+ *
+ * @param configPath `~/.openclaw/config.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Openclaw 默认模型 ID
  */
 export function rewriteOpenclaw(configPath: string, proxyUrl: string, model: string): void {
   try {
@@ -199,6 +243,13 @@ export function rewriteOpenclaw(configPath: string, proxyUrl: string, model: str
 
 /**
  * Rewrite Hermes settings.
+ *
+ * 在 `openai` 块下写入 `base_url` / `api_key`（占位 `TOKENBUDDY_PROXY`）/`model`。
+ * 失败仅打印日志，不抛出。
+ *
+ * @param configPath `~/.hermes/settings.json` 的绝对路径
+ * @param proxyUrl TokenBuddy proxy 的 base URL
+ * @param model Hermes 默认模型 ID
  */
 export function rewriteHermes(configPath: string, proxyUrl: string, model: string): void {
   try {

package/src/terminal-image.ts

@@ -4,26 +4,52 @@ import * as path from "path";
 
 type TerminalEnv = Readonly<Record<string, string | undefined>>;
 
+/**
+ * 终端图片的展示方式：
+ * - `inline-iterm`：iTerm2 / WezTerm 等支持的 OSC 1337 内嵌图片
+ * - `inline-kitty`：Kitty 图形协议内嵌图片
+ * - `system-open`：调系统 `open` / `xdg-open` / `cmd /c start` 打开图片
+ * - `manual`：都不可用时让用户手动打开（通常附 fallbackCommand 提示）
+ */
 export type TerminalImageDisplayMethod =
   | "inline-iterm"
   | "inline-kitty"
   | "system-open"
   | "manual";
 
+/**
+ * `displayTerminalImage()` 的返回：成功/失败 + 用的方法 + 提示消息。
+ * `displayed=false` 时调用方应回退到 `fallbackCommand` 提示用户。
+ */
 export interface TerminalImageDisplayResult {
+  /** 实际使用的展示方法 */
   method: TerminalImageDisplayMethod;
+  /** 是否真的把图片写到终端/打开了 */
   displayed: boolean;
+  /** 人类可读结果描述（给 init / doctor 用） */
   message: string;
+  /** 仅在 `displayed=false` 时存在：建议用户手动执行的命令 */
   fallbackCommand?: string;
 }
 
+/**
+ * `displayTerminalImage()` / `detectTerminalImageDisplay()` 的可注入依赖。
+ * 全部可选，缺省时使用真实 `process.env` / `process.platform` / `process.stdout`。
+ */
 export interface DisplayTerminalImageOptions {
+  /** 环境变量（默认 `process.env`） */
   env?: TerminalEnv;
+  /** 平台（默认 `process.platform`） */
   platform?: NodeJS.Platform;
+  /** stdout 是否为 TTY（默认 `process.stdout.isTTY`） */
   stdoutIsTTY?: boolean;
+  /** 写入 escape sequence 的方法（默认 `process.stdout.write`） */
   write?: (chunk: string) => void;
+  /** 调起子进程执行 system-open 命令的方法（默认 `child_process.spawn`） */
   runCommand?: (command: string, args: string[]) => Promise<void>;
+  /** 文件存在性检查（默认 `fs.existsSync`） */
   fileExists?: (filePath: string) => boolean;
+  /** 文件读取方法（默认 `fs.readFileSync`） */
   readFile?: (filePath: string) => Buffer;
 }
 
@@ -105,6 +131,13 @@ function openCommandForPlatform(platform: NodeJS.Platform, filePath: string): {
   return undefined;
 }
 
+/**
+ * 仅检测当前终端是否支持某种内嵌图片协议（Kitty / iTerm2）。
+ * 用于上层在展示前先决策"要不要走内嵌"而不直接写入任何输出。
+ *
+ * @param options 可注入依赖（env / platform / stdoutIsTTY）
+ * @returns 支持的内嵌协议；不支持时返回 `undefined`
+ */
 export function detectTerminalImageDisplay(
   options: DisplayTerminalImageOptions = {},
 ): InlineImageProtocol | undefined {
@@ -114,6 +147,14 @@ export function detectTerminalImageDisplay(
   );
 }
 
+/**
+ * 把本地图片文件展示到终端：优先内嵌（Kitty / iTerm2），其次 system-open，最后 manual。
+ * 不会抛异常；任何错误都会转成 `TerminalImageDisplayResult { displayed: false }`。
+ *
+ * @param filePath 本地图片绝对路径
+ * @param options 可注入依赖
+ * @returns 展示结果（含 method / displayed / message / fallbackCommand）
+ */
 export async function displayTerminalImage(
   filePath: string,
   options: DisplayTerminalImageOptions = {},