@tokenbuddy/tokenbuddy 1.0.11 → 1.0.13

package/src/doctor-clawtip-wallet.ts

@@ -4,14 +4,26 @@ import {
   type ClawtipWalletStatus,
 } from "./init-payment-options.js";
 
+/**
+ * `tb doctor` 视角的 ClawTip 钱包就绪摘要：把 readiness 拍平成 boolean + 关键路径。
+ * `printDoctorClawtipWallet()` 负责渲染它。
+ */
 export interface DoctorClawtipWalletSummary {
+  /** 综合就绪状态（同 `inspectClawtipWalletReadiness().status`） */
   status: ClawtipWalletStatus;
+  /** `status === "ready"` 的便利布尔，UI 据此选择图标 */
   ready: boolean;
+  /** buyer-store 里是否保存了 ClawTip 支付 metadata */
   paymentMetadataPresent: boolean;
+  /** `~/.openclaw/configs/config.json` 是否存在 */
   walletConfigPresent: boolean;
+  /** `~/.openclaw/configs/` 目录是否存在 */
   configsDirExists: boolean;
+  /** 期望的 wallet config 绝对路径 */
   expectedPath: string;
+  /** 同目录里其它文件列表（按字典序） */
   alternatePaths: string[];
+  /** 人类可读说明（来自 readiness.message） */
   message: string;
 }
 
@@ -28,6 +40,12 @@ function clawtipWalletStatusIcon(status: ClawtipWalletStatus): string {
   return "🔘";
 }
 
+/**
+ * 从 `BuyerStore` 读取当前 ClawTip 支付 metadata，再叠加 wallet config 探查结果，
+ * 生成 `tb doctor` 面板用的就绪摘要。
+ *
+ * @returns doctor 面板用的就绪摘要
+ */
 export function readDoctorClawtipWallet(): DoctorClawtipWalletSummary {
   const store = new BuyerStore();
   try {
@@ -47,6 +65,13 @@ export function readDoctorClawtipWallet(): DoctorClawtipWalletSummary {
   }
 }
 
+/**
+ * 把 doctor 摘要渲染成多行人类可读输出，包含状态图标、metadata/config 缺失标记、
+ * 期望路径、同目录其它文件，以及按状态分支的"接下来怎么做"提示。
+ *
+ * @param wallet `readDoctorClawtipWallet()` 的输出
+ * @param writeLine 注入的单行写入函数（默认 `console.log`）
+ */
 export function printDoctorClawtipWallet(
   wallet: DoctorClawtipWalletSummary,
   writeLine: (line: string) => void,

package/src/doctor-diagnostics.ts

@@ -19,11 +19,21 @@ import {
   type DoctorClawtipWalletSummary,
 } from "./doctor-clawtip-wallet.js";
 
+/**
+ * `tb doctor` 输出里 provider 行的形状。
+ * 在 `ProviderCandidate` 之上叠加 buyer 端持久化的 runtime config（如果存在）。
+ */
 export interface DoctorProviderView extends ProviderCandidate {
+  /** 持久化的 provider runtime config（opencode 的 `defaultModel` 等） */
   runtimeConfig?: ProviderRuntimeConfig;
+  /** runtime config 的最近更新时间 */
   runtimeConfigUpdatedAt?: string;
 }
 
+/**
+ * `tb doctor` 输出里 seller 行的形状。
+ * 字段命名与 `RegistrySeller` 对齐，但额外包含状态、错误信息、manifest sellerId 等。
+ */
 export interface DoctorSellerEntry {
   id: string;
   name?: string;
@@ -37,11 +47,19 @@ export interface DoctorSellerEntry {
   errorMessage?: string;
 }
 
+/**
+ * `tb doctor` 完整诊断结果，由 `collectDoctorDiagnostics` 返回。
+ */
 export interface DoctorDiagnostics {
+  /** 控制面 / 代理端点可达性 */
   access: DoctorAccessSummary;
+  /** Clawtip 钱包信息 */
   clawtipWallet: DoctorClawtipWalletSummary;
+  /** 模型目录汇总 */
   models: DoctorModelsSummary;
+  /** provider 安装 / 配置状态 */
   providers: DoctorProviderView[];
+  /** seller 注册表 + 探测结果 */
   sellers: DoctorSellersSummary;
 }
 
@@ -90,6 +108,9 @@ interface DoctorModelsResponse {
   sellers?: DoctorSellerEntry[];
 }
 
+/**
+ * `tb doctor` 模型表的单行：按 model id 聚合 seller 的折扣 / 价格区间。
+ */
 export interface DoctorModelSummaryEntry {
   id: string;
   sellerCount: number;
@@ -163,6 +184,9 @@ type DoctorSellersSummary = {
   error?: string;
 };
 
+/**
+ * `tb doctor` 模型目录汇总：原始 `data` + 聚合后的 `grouped`（按 model id 分组）。
+ */
 export type DoctorModelsSummary = {
   available: boolean;
   count: number;
@@ -235,7 +259,6 @@ function providerRuntimeSummary(runtimeConfig?: ProviderRuntimeConfig): string |
     return [
       runtimeConfig.protocolPreference,
       runtimeConfig.defaultModel,
-      runtimeConfig.sellerId ? `seller=${runtimeConfig.sellerId}` : undefined,
     ].filter(Boolean).join(" · ");
   }
 
@@ -647,6 +670,12 @@ function printDoctorSellers(sellers: DoctorSellersSummary, writeLine: (line: str
   }
 }
 
+/**
+ * 打印模型目录汇总（写到 `writeLine`，默认 stdout）。
+ *
+ * @param models 模型汇总
+ * @param writeLine 自定义输出函数（测试可注入）
+ */
 export function printDoctorModelsSummary(
   models: DoctorModelsSummary,
   writeLine: (line: string) => void = defaultWriter,
@@ -676,6 +705,11 @@ export function printDoctorModelsSummary(
   writeLine(table.toString());
 }
 
+/**
+ * 读取 buyer 端已知的 provider 列表，把 runtime config（如果有）合并到 `DoctorProviderView`。
+ *
+ * @returns 每个 provider 的 view（数组）
+ */
 export function readDoctorProviders(): DoctorProviderView[] {
   const store = new BuyerStore();
   try {
@@ -703,6 +737,12 @@ export function readDoctorProviders(): DoctorProviderView[] {
   }
 }
 
+/**
+ * 打印 provider 列表（"Programming Terminals" 段）。
+ *
+ * @param providers provider view 列表
+ * @param writeLine 自定义输出函数
+ */
 export function printDoctorProviders(
   providers: DoctorProviderView[],
   writeLine: (line: string) => void = defaultWriter,
@@ -725,6 +765,15 @@ export function printDoctorProviders(
   }
 }
 
+/**
+ * 收集 `tb doctor` 需要的全部诊断信息。
+ * 1. 并发拉取 daemon health / sellers / models / proxy models / registry 五个端点。
+ * 2. 合并 registry 配置 + 探测结果 + catalog 拉取结果。
+ * 3. 返回完整 `DoctorDiagnostics`（供 JSON 消费者或自定义渲染使用）。
+ *
+ * @param options 收集选项（端口 / daemon 状态 / registry URL / providers）
+ * @returns 完整诊断结果
+ */
 export async function collectDoctorDiagnostics(options: DoctorCollectOptions): Promise<DoctorDiagnostics> {
   const fetches = startDoctorFetches(
     options.controlPort,
@@ -762,6 +811,13 @@ export async function collectDoctorDiagnostics(options: DoctorCollectOptions): P
   };
 }
 
+/**
+ * 单独收集 `tb models` 需要的模型汇总（不包含 providers）。
+ * daemon 拉到的数据缺价格时，回退用 `discoverSellerBackedModels` 重新拉 catalog。
+ *
+ * @param options 同 `collectDoctorDiagnostics`（去掉 providers）
+ * @returns 模型汇总
+ */
 export async function collectDoctorModelsSummary(options: Omit<DoctorCollectOptions, "providers">): Promise<DoctorModelsSummary> {
   const diagnostics = await collectDoctorDiagnostics({
     ...options,
@@ -789,6 +845,12 @@ export async function collectDoctorModelsSummary(options: Omit<DoctorCollectOpti
 
 }
 
+/**
+ * 渐进式渲染 `tb doctor`：分阶段打印（clawtip → access → sellers → models），边等边输出，避免用户长时间看不到输出。
+ *
+ * @param options 渲染选项（含写入函数）
+ * @returns 完整 `DoctorDiagnostics`
+ */
 export async function renderDoctorDiagnosticsProgressively(options: DoctorRenderOptions): Promise<DoctorDiagnostics> {
   const writeLine = options.writeLine || defaultWriter;
   const clawtipWallet = readDoctorClawtipWallet();

package/src/index.ts

@@ -1,5 +1,9 @@
 import { buildCli } from "./cli.js";
 
+/**
+ * CLI 入口：构造 commander program、解析 `process.argv`、异步执行。
+ * 异常通过 `process.exitCode = 1` 透传，避免在 daemon 未启动等情况下刷红 stderr（已通过 `code` 字段分类）。
+ */
 export function run() {
   const program = buildCli();
   program.parseAsync(process.argv).catch((error: unknown) => {

package/src/init-clawtip-activation.ts

@@ -13,43 +13,86 @@ const SLEEP_SLICE_MS = 200;
 const CLAWTIP_MIN_CLI_VERSION = "1.0.4";
 const CLAWTIP_MIN_SKILL_VERSION = "1.0.12";
 
+/**
+ * 一次 ClawTip 引导支付的输入参数（由上游 service / wallet-bootstrap 解析后传入）。
+ * 用来写本地 order 文件并触发 `npx @clawtip/clawtip-cli pay` 流程。
+ */
 export interface ClawtipBootstrapPayment {
+  /** 订单号（也是 order JSON 文件名） */
   orderNo: string;
+  /** 金额（分） */
   amountFen: number;
+  /** 收款方标识，可选 */
   payTo?: string;
+  /** 上游加密负载，可选 */
   encryptedData?: string;
+  /** 上游分配的 indicator（用于切到正确目录） */
   indicator: string;
+  /** 上游 slug，可选 */
   slug?: string;
+  /** skill ID（写入 order 的 `skill-id` 字段） */
   skillId?: string;
+  /** 订单描述，可选 */
   description?: string;
+  /** 资源 URL（写入 order 的 `resource_url` 字段） */
   resourceUrl?: string;
 }
 
+/**
+ * `parseClawtipCliOutput()` 的输出：从 ClawTip CLI 文本输出中提取的结构化字段。
+ * 字段都为"尽力推断"：缺失时为 undefined，由调用方决定如何处理。
+ */
 export interface ParsedClawtipOutput {
+  /** 鉴权 URL（可被扫码或浏览器打开） */
   authUrl?: string;
+  /** 设备 ID（用于 check-register 轮询） */
   clawtipId?: string;
+  /** QR 图片本地路径 */
   mediaPath?: string;
+  /** 下游/上游的失败信息（已 sanitize 过的中文提示） */
   failureMessage?: string;
+  /** 是否需要用户做钱包授权（含 QR、authUrl、扫码关键字等） */
   requiresWalletAuth: boolean;
+  /** 钱包是否已就绪（register success / tokeninfo / config.json 等关键字） */
   walletReady: boolean;
 }
 
+/**
+ * `waitForClawtipActivationConfirmation()` 的可注入依赖与可调参数。
+ * 默认实现使用 `@clack/prompts` 的 `cancel`、本机 `~/.openclaw/configs/` 探查和 npx `check-register`。
+ */
 export interface WaitForClawtipActivationOptions {
+  /** wallet config 探查函数（默认 `inspectOpenClawWalletConfig`） */
   inspectWalletConfig?: () => OpenClawWalletConfigState;
+  /** 外部取消信号（与 SIGINT 监听器互不冲突） */
   isCancelled?: () => boolean;
+  /** check-register 用的 ClawTip 设备 ID（必填才会触发轮询） */
   clawtipId?: string;
+  /** check-register 命令执行函数（默认 `npx @clawtip/clawtip-cli check-register`） */
   checkRegister?: (clawtipId: string) => Promise<void>;
+  /** 取消时的回调（默认 `@clack/prompts.cancel`） */
   cancel?: (message?: string) => void;
+  /** 轮询间隔（毫秒），默认 2000 */
   pollIntervalMs?: number;
+  /** sleep 实现（测试可注入） */
   sleep?: (ms: number) => Promise<void>;
 }
 
+/**
+ * `startClawtipWalletBootstrap()` 的可注入依赖。
+ */
 export interface StartClawtipWalletBootstrapOptions {
+  /** 注入的 home 目录（默认 `process.env.HOME` / `os.homedir()`） */
   home?: string;
+  /** 注入的 ClawTip CLI 执行函数（默认 `npx @clawtip/clawtip-cli`） */
   runClawtipCommand?: (args: string[]) => Promise<string>;
 }
 
+/**
+ * `checkOpenClawRuntime()` 的可注入依赖。
+ */
 export interface CheckOpenClawRuntimeOptions {
+  /** 注入的 OpenClaw CLI 执行函数（默认 `openclaw --version`） */
   runOpenClawCommand?: (args: string[]) => Promise<string>;
 }
 
@@ -286,6 +329,13 @@ function extractClawtipIdFromUrl(value: string): string | undefined {
   return undefined;
 }
 
+/**
+ * 从 ClawTip CLI 的 stdout/stderr 合并文本中提取关键信息。
+ * 同时识别 authUrl / clawtipId / mediaPath / 失败关键字 / 是否需要钱包授权 / 钱包是否就绪。
+ *
+ * @param output 合并后的 ClawTip CLI 输出
+ * @returns 结构化解析结果
+ */
 export function parseClawtipCliOutput(output: string): ParsedClawtipOutput {
   const authUrl = findValueAfterKeys(output, ["authUrl", "auth_url", "auth url"]) || findUrlInOutput(output);
   const mediaPath = findMediaPathInOutput(output);
@@ -314,6 +364,15 @@ export function parseClawtipCliOutput(output: string): ParsedClawtipOutput {
   };
 }
 
+/**
+ * 取得 ClawTip 引导流程中要展示给用户的 QR 图片本地路径：
+ * 优先用 `parsedOutput.mediaPath`；缺省时抛错（因为首次绑定必须先走 wallet QR 流程）。
+ *
+ * @param parsedOutput `parseClawtipCliOutput()` 的结果
+ * @param orderFile 当前订单的 JSON 文件路径（用于错误消息）
+ * @returns QR 图片绝对路径
+ * @throws 当 `parsedOutput.mediaPath` 缺失时
+ */
 export function resolveClawtipQrMediaPath(parsedOutput: ParsedClawtipOutput, orderFile: string): string {
   if (parsedOutput.mediaPath) {
     return parsedOutput.mediaPath;
@@ -327,6 +386,13 @@ export function resolveClawtipQrMediaPath(parsedOutput: ParsedClawtipOutput, ord
   );
 }
 
+/**
+ * 读 order JSON 里的 `payCredential`（snake/camel 兼容）。
+ * 用于在 `startClawtipWalletBootstrap()` 之后回传给上游 service。
+ *
+ * @param orderFile order JSON 的绝对路径
+ * @returns 非空 `payCredential` 字符串；文件不存在 / 字段缺失时返回 `undefined`
+ */
 export function readClawtipPayCredential(orderFile: string): string | undefined {
   if (!fs.existsSync(orderFile)) {
     return undefined;
@@ -336,6 +402,15 @@ export function readClawtipPayCredential(orderFile: string): string | undefined
   return typeof credential === "string" && credential.trim() ? credential : undefined;
 }
 
+/**
+ * 把 ClawTip 引导支付所需的所有字段写成本地 order JSON：
+ * `~/.openclaw/skills/orders/<indicator>/<orderNo>.json`。
+ * 自动创建父目录。
+ *
+ * @param payment 引导支付参数
+ * @param home 用户 home 目录（默认 `process.env.HOME` / `os.homedir()`）
+ * @returns 写入的 order JSON 绝对路径
+ */
 export function writeClawtipOrderFile(
   payment: ClawtipBootstrapPayment,
   home: string = defaultHomeDir(),
@@ -357,6 +432,19 @@ export function writeClawtipOrderFile(
   return orderFile;
 }
 
+/**
+ * 启动 ClawTip 钱包引导流程：
+ * 1. 写本地 order JSON
+ * 2. 调用 `npx @clawtip/clawtip-cli pay` 完成下单
+ * 3. 解析输出；若无 `mediaPath` 会在 `~/.openclaw/workspace/clawtip/qrcode/` 里
+ *    找最近生成的 QR 图作为兜底
+ * 4. 返回 order 文件路径 + 解析结果 + 回读到的 `payCredential`
+ *
+ * @param payment 引导支付参数
+ * @param options 可注入的 home / runClawtipCommand
+ * @returns 引导结果
+ * @throws 当 `parsedOutput.failureMessage` 非空时（即 ClawTip 下单失败）
+ */
 export async function startClawtipWalletBootstrap(
   payment: ClawtipBootstrapPayment,
   options: StartClawtipWalletBootstrapOptions = {},
@@ -394,6 +482,13 @@ export async function startClawtipWalletBootstrap(
   };
 }
 
+/**
+ * 校验本机 `openclaw` CLI 可用：执行 `openclaw --version` 并返回去空白的版本字符串。
+ *
+ * @param options 可注入的 runOpenClawCommand
+ * @returns OpenClaw 版本字符串
+ * @throws 当 CLI 缺失或退出码非 0 时
+ */
 export async function checkOpenClawRuntime(
   options: CheckOpenClawRuntimeOptions = {},
 ): Promise<string> {
@@ -439,6 +534,14 @@ async function sleepUntilNextPoll(
   return !isCancelled();
 }
 
+/**
+ * 阻塞等待 ClawTip 钱包激活完成：轮询 `~/.openclaw/configs/config.json` 是否出现；
+ * 拿到 `clawtipId` 时还会调 `check-register` 主动推一次。
+ * 监听 `SIGINT` 与外部 `isCancelled` 触发取消。
+ *
+ * @param options 可注入的 inspect / checkRegister / cancel / sleep / pollInterval
+ * @returns 钱包就绪返回 `true`；被取消返回 `false`
+ */
 export async function waitForClawtipActivationConfirmation(
   options: WaitForClawtipActivationOptions = {},
 ): Promise<boolean> {

package/src/init-payment-options.ts

@@ -5,63 +5,121 @@ import * as path from "path";
 import type { PaymentConfig } from "./buyer-store.js";
 import type { ProviderCandidate } from "./provider-install.js";
 
+/** 当前 init 流程已支持的支付方式。当前仅 JD ClawTip 扫码支付。 */
 export type InitPaymentMethod = "clawtip";
 
+/**
+ * `INIT_PAYMENT_OPTIONS` 里的单条目，喂给 `@clack/prompts` 的 select 组件。
+ */
 export interface InitPaymentOption {
+  /** 选项值，对应 `InitPaymentMethod` */
   value: InitPaymentMethod;
+  /** 展示给用户的标签 */
   label: string;
+  /** 选段下方的小字提示，可选 */
   hint?: string;
 }
 
+/**
+ * `INIT_COMING_SOON_PAYMENT_OPTIONS` 里的单条目：未上线的支付方式占位。
+ * 仅用于"更多支付方式"提示框展示，不可被选中。
+ */
 export interface ComingSoonPaymentOption {
+  /** 选项 ID（仅作展示和未来上线时引用） */
   id: string;
+  /** 人类可读名称 */
   label: string;
 }
 
+/**
+ * buyer-store 里 ClawTip 支付的已有绑定（持久化的关键字段）。
+ * `resourceUrl` / `orderNo` 至少存在一个才视为"可复用绑定"。
+ */
 export interface ExistingClawtipBinding {
+  /** 原始 config 对象（透传回 buyer-store 时用） */
   config: Record<string, unknown>;
+  /** 资源 URL（可选） */
   resourceUrl?: string;
+  /** 订单号（可选） */
   orderNo?: string;
 }
 
+/**
+ * `buildInitTerminalSelectionState()` 的输出单条，喂给 `@clack/prompts` 的多选组件。
+ */
 export interface InitTerminalOption {
+  /** 选项值（通常是 `provider.id` 或 `"other"`） */
   value: string;
+  /** 展示给用户的标签 */
   label: string;
+  /** 选段下方的小字提示，可选 */
   hint?: string;
 }
 
+/**
+ * `buildInitTerminalSelectionState()` 的输出：已配置 / 待配置 两个分组。
+ * `options` 末尾会追加 `OTHER_TERMINAL_OPTION`，给"我自己接"留口。
+ */
 export interface InitTerminalSelectionState {
+  /** 已配置完成的 provider（`status === "configured"`） */
   installed: InitTerminalOption[];
+  /** 待配置的 provider，末尾追加 `OTHER_TERMINAL_OPTION` */
   options: InitTerminalOption[];
 }
 
+/**
+ * `inspectOpenClawWalletConfig()` 的输出：本地 OpenClaw 钱包目录的探查结果。
+ * `alternatePaths` 是 `~/.openclaw/configs/` 里除 `config.json` 之外的文件，
+ * 用于在 missing 状态下提示用户"目录里其实有别的东西"。
+ */
 export interface OpenClawWalletConfigState {
+  /** `~/.openclaw/configs/config.json` 的预期路径 */
   expectedPath: string;
+  /** `~/.openclaw/configs/` 目录是否存在 */
   configsDirExists: boolean;
+  /** `expectedPath` 是否真实存在 */
   exists: boolean;
+  /** 同目录里其它文件路径（按文件名字典序） */
   alternatePaths: string[];
 }
 
+/**
+ * ClawTip 钱包就绪状态四象限：
+ * - `ready`：saved binding + 本地 wallet config 同时存在
+ * - `metadata_missing_wallet`：只 saved binding，wallet 缺
+ * - `wallet_missing_metadata`：只 wallet config，metadata 缺
+ * - `missing`：都缺
+ */
 export type ClawtipWalletStatus =
   | "ready"
   | "metadata_missing_wallet"
   | "wallet_missing_metadata"
   | "missing";
 
+/**
+ * `inspectClawtipWalletReadiness()` 的输出：状态枚举 + 物证 + 给用户看的说明。
+ */
 export interface ClawtipWalletReadiness {
+  /** 综合状态 */
   status: ClawtipWalletStatus;
+  /** 本地 OpenClaw wallet config 探查结果 */
   walletConfig: OpenClawWalletConfigState;
+  /** buyer-store 里的 saved binding（如果有） */
   savedBinding?: ExistingClawtipBinding;
+  /** 既 saved 又本地存在的可复用 binding（如果有） */
   reusableBinding?: ExistingClawtipBinding;
+  /** 面向 init 面板 / doctor 的人类可读说明 */
   message: string;
 }
 
+/** init 流程里"我自己接"的兜底选项 */
 export const OTHER_TERMINAL_OPTION: InitTerminalOption = {
   value: "other",
   label: "Other",
   hint: "I will configure my own terminal using the TokenBuddy proxy endpoints."
 };
 
+/** init 流程已支持的可选支付方式（喂给 `@clack/prompts` 的 select 组件） */
 export const INIT_PAYMENT_OPTIONS: InitPaymentOption[] = [
   {
     value: "clawtip",
@@ -70,6 +128,7 @@ export const INIT_PAYMENT_OPTIONS: InitPaymentOption[] = [
   }
 ];
 
+/** init 流程"更多支付方式"占位列表（仅展示用，不可选） */
 export const INIT_COMING_SOON_PAYMENT_OPTIONS = [
   {
     id: "wechat-pay",
@@ -85,6 +144,11 @@ export const INIT_COMING_SOON_PAYMENT_OPTIONS = [
   }
 ] satisfies ReadonlyArray<ComingSoonPaymentOption>;
 
+/**
+ * 在 init 流程的支付选择面板下追加"更多支付方式（接入中）"提示。
+ *
+ * @param note 注入的 note 函数（默认 `@clack/prompts.note`，测试可替换）
+ */
 export function noteInitComingSoonPayments(
   note: (message?: string, title?: string) => void = p.note
 ): void {
@@ -94,6 +158,13 @@ export function noteInitComingSoonPayments(
   );
 }
 
+/**
+ * 把 provider-install 阶段的探测结果转成 `InitTerminalSelectionState`：
+ * 已配置完成的归 `installed`；已检测到但未配置的归 `options`，末尾追加 `OTHER_TERMINAL_OPTION`。
+ *
+ * @param providers provider-install 的探测结果
+ * @returns init 流程的多选状态
+ */
 export function buildInitTerminalSelectionState(providers: ProviderCandidate[]): InitTerminalSelectionState {
   const installed = providers
     .filter((provider) => provider.detected && provider.status === "configured")
@@ -117,6 +188,12 @@ export function buildInitTerminalSelectionState(providers: ProviderCandidate[]):
   };
 }
 
+/**
+ * 校验 init 多选面板的返回值：必须至少选一个 terminal 或选择 `Other`。
+ *
+ * @param selected `@clack/prompts` 多选返回值
+ * @returns 错误消息字符串；合法时返回 `undefined`
+ */
 export function validateInitTerminalSelection(selected: string[] | undefined): string | undefined {
   if (!selected || selected.length === 0) {
     return "Select at least one terminal or choose Other.";
@@ -124,6 +201,12 @@ export function validateInitTerminalSelection(selected: string[] | undefined): s
   return undefined;
 }
 
+/**
+ * 把"已配置完成的 terminal"列表渲染成 init 面板顶部的摘要文案。
+ *
+ * @param installed 已配置完成的 terminal 列表
+ * @returns 多行 markdown 摘要；空列表时返回 `undefined`
+ */
 export function buildInstalledTerminalMessage(installed: InitTerminalOption[]): string | undefined {
   if (installed.length === 0) {
     return undefined;
@@ -137,6 +220,15 @@ function defaultHomeDir(): string {
   return process.env.HOME || os.homedir();
 }
 
+/**
+ * 探查 `~/.openclaw/configs/` 目录及其默认 wallet 配置：
+ * - 是否存在 configs 目录
+ * - `config.json` 是否存在
+ * - 同目录里其它文件列表（用于 missing 状态下的提示）
+ *
+ * @param home 用户 home 目录（默认读 `process.env.HOME` 或 `os.homedir()`）
+ * @returns 探查结果
+ */
 export function inspectOpenClawWalletConfig(home: string = defaultHomeDir()): OpenClawWalletConfigState {
   const configsDir = path.join(home, ".openclaw", "configs");
   const expectedPath = path.join(configsDir, "config.json");
@@ -168,6 +260,13 @@ function stringField(value: unknown): string | undefined {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
 
+/**
+ * 从 `PaymentConfig` 里识别 ClawTip 已保存的关键字段（`resourceUrl` / `orderNo`）。
+ * 两者都没有时返回 `undefined`。
+ *
+ * @param payment buyer-store 读到的 payment 配置
+ * @returns 识别出的 binding；无关键字段时返回 `undefined`
+ */
 export function detectExistingClawtipBinding(payment: PaymentConfig | undefined): ExistingClawtipBinding | undefined {
   if (!payment || payment.method !== "clawtip" || !payment.config || typeof payment.config !== "object") {
     return undefined;
@@ -185,6 +284,14 @@ export function detectExistingClawtipBinding(payment: PaymentConfig | undefined)
   };
 }
 
+/**
+ * 判断已保存的 ClawTip binding 能否被本地 OpenClaw wallet config 复用：
+ * wallet config 必须存在并且 saved binding 至少有一个关键字段。
+ *
+ * @param payment buyer-store 读到的 payment 配置
+ * @param walletConfig `inspectOpenClawWalletConfig()` 的结果
+ * @returns 可复用 binding；不可复用时返回 `undefined`
+ */
 export function detectReusableClawtipBinding(
   payment: PaymentConfig | undefined,
   walletConfig: OpenClawWalletConfigState
@@ -195,6 +302,14 @@ export function detectReusableClawtipBinding(
   return detectExistingClawtipBinding(payment);
 }
 
+/**
+ * 综合判断 ClawTip 钱包的就绪状态：把 saved binding、wallet config 和 reuse 关系
+ * 合并成 `ClawtipWalletReadiness`，供 init 面板、doctor 和激活流程共同消费。
+ *
+ * @param payment buyer-store 读到的 payment 配置
+ * @param walletConfig 本地 wallet 探查结果（默认 `inspectOpenClawWalletConfig()`）
+ * @returns 就绪状态 + 物证 + 人类可读说明
+ */
 export function inspectClawtipWalletReadiness(
   payment: PaymentConfig | undefined,
   walletConfig: OpenClawWalletConfigState = inspectOpenClawWalletConfig(),
@@ -236,6 +351,15 @@ export function inspectClawtipWalletReadiness(
   };
 }
 
+/**
+ * 把 init 流程的若干条摘要拼成"成功"提示：
+ * - 顶部一行 emoji + 成功消息
+ * - 中间每条摘要 `- ` 开头
+ * - 末尾附 `tb doctor` 提示
+ *
+ * @param summaryLines 摘要行（会先 trim，空行会被跳过）
+ * @returns 多行 markdown 摘要
+ */
 export function buildInitSuccessMessage(summaryLines: string[] = []): string {
   const lines = ["✅ TokenBuddy setup completed successfully."];
   for (const line of summaryLines) {

package/src/model-index.ts

@@ -21,10 +21,19 @@ function normalizeModelId(modelId: string): string {
  * - `sellers` is a snapshot array of the matching registry entries. Order
  *   follows the registry's `defaultSeller` preference then declaration order.
  */
+/**
+ * `ModelIndex.resolve()` 的返回结果。
+ * - `empty` 等价于 `matched = false && sellers = []`，路由层应当视为"无可用 seller"。
+ * - `sellers` 是按 `defaultSeller` 优先 + 声明顺序排序后的快照数组。
+ */
 export interface ModelIndexResolution {
+  /** 原始请求的模型 ID（未归一化） */
   modelId: string;
+  /** 索引里是否至少有一个 seller 命中（已归一化匹配） */
   matched: boolean;
+  /** 命中的 seller 列表（已按 default + 声明顺序排序的快照） */
   sellers: RegistrySeller[];
+  /** 当前索引里 `models` 字段缺失的 seller 数（用于诊断和告警） */
   missingModelsFlag: number;
 }