@aipanel/core 1.2.8 → 1.2.10

package/es/{logger.d.ts → client/logger.d.ts}

@@ -1,4 +1,4 @@
-import { type LogContext } from "./logger-core";
+import { type LogContext } from "../common/logger-core";
 export declare const logger: {
     debug(message: string, context?: LogContext, ...args: unknown[]): void;
     info(message: string, context?: LogContext, ...args: unknown[]): void;

package/es/{logger.mjs → client/logger.mjs}

@@ -1,18 +1,12 @@
-import { LOG_PREFIX } from "./constants.mjs";
+import { LOG_PREFIX } from "../common/constants.mjs";
 import {
+  LEVEL_NAMES,
   LogLevel,
   getConfig,
   getTimestamp,
   formatContext,
   formatValue
-} from "./logger-core.mjs";
-const LEVEL_NAMES = {
-  [LogLevel.DEBUG]: "DEBUG",
-  [LogLevel.INFO]: "INFO ",
-  [LogLevel.WARN]: "WARN ",
-  [LogLevel.ERROR]: "ERROR",
-  [LogLevel.NONE]: "NONE "
-};
+} from "../common/logger-core.mjs";
 const C = {
   dim: "color: #888",
   bright: "font-weight: bold",
@@ -39,7 +33,7 @@ function log(level, message, context, ...args) {
     segments.push("%c%s");
     styles.push(C.dim, getTimestamp());
   }
-  segments.push(`%c${LEVEL_NAMES[level]}`);
+  segments.push(`%c${LEVEL_NAMES[level].padEnd(5)}`);
   styles.push(LEVEL_COLORS[level]);
   segments.push(`%c${LOG_PREFIX}`);
   styles.push(C.bright);

package/es/client/storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 浏览器存储辅助（window.localStorage/sessionStorage，仅 client 端；通过 @aipanel/core/client 导出）
+ */
+/**
+ * 安全读取浏览器存储（JSON 解码；不可用/异常返回 null）
+ */
+export declare function storageGet<T>(area: "local" | "session", key: string): T | null;
+/**
+ * 安全写入浏览器存储（JSON 序列化；异常忽略）
+ */
+export declare function storageSet(area: "local" | "session", key: string, value: unknown): void;
+/**
+ * 安全删除浏览器存储项
+ */
+export declare function storageRemove(area: "local" | "session", key: string): void;

package/es/client/storage.mjs

@@ -0,0 +1,33 @@
+function storageArea(area) {
+  try {
+    if (typeof window === "undefined") return void 0;
+    return area === "local" ? window.localStorage : window.sessionStorage;
+  } catch {
+    return void 0;
+  }
+}
+function storageGet(area, key) {
+  try {
+    const raw = storageArea(area)?.getItem(key);
+    return raw == null ? null : JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function storageSet(area, key, value) {
+  try {
+    storageArea(area)?.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function storageRemove(area, key) {
+  try {
+    storageArea(area)?.removeItem(key);
+  } catch {
+  }
+}
+export {
+  storageGet,
+  storageRemove,
+  storageSet
+};

package/es/client/theme.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 浏览器主题辅助（依赖 window.matchMedia，仅 client 端使用；通过 @aipanel/core/client 导出）
+ */
+import type { AIPanelWidgetTheme } from "../common/types";
+/**
+ * 当前系统主题（仅浏览器有效；SSR/无 window 环境返回 light）
+ */
+export declare function getSystemTheme(): "light" | "dark";
+/**
+ * 挂件主题偏好解析：auto 按系统主题折算为 light/dark
+ * @param theme - 挂件主题偏好（AIPanelWidgetTheme）
+ * @param system - 系统主题（默认当前系统）
+ * @returns 实际应用主题
+ */
+export declare function resolveWidgetTheme(theme: AIPanelWidgetTheme, system?: "light" | "dark"): "light" | "dark";

package/es/client/theme.mjs

@@ -0,0 +1,11 @@
+function getSystemTheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveWidgetTheme(theme, system = getSystemTheme()) {
+  return theme === "auto" ? system : theme;
+}
+export {
+  getSystemTheme,
+  resolveWidgetTheme
+};

package/es/client.d.ts

@@ -0,0 +1,3 @@
+export * from "./client/logger";
+export * from "./client/storage";
+export * from "./client/theme";

package/es/client.mjs

@@ -0,0 +1,3 @@
+export * from "./client/logger.mjs";
+export * from "./client/storage.mjs";
+export * from "./client/theme.mjs";

package/es/{constants.d.ts → common/constants.d.ts}

@@ -56,6 +56,8 @@ export declare const NOTIFICATION_DURATION = 3000;
 export declare const INIT_MARKER = "__AIPANEL_INITIALIZED__";
 /** 选中元素存储键 */
 export declare const SELECTED_ELEMENTS_KEY = "__aipanel_selected_elements__";
+/** 页面会话标识键（sessionStorage，跨导航标识同一 Tab 的页面上下文） */
+export declare const SESSION_ID_KEY = "_aipanel_pk";
 /** ==================== 缓存目录 ==================== */
 /**
  * AIPanel 项目级资源/缓存目录（相对于项目根目录，各 Provider 统一使用）。
@@ -83,6 +85,8 @@ export declare const EXT_MSG: {
     readonly SELECTION_START: "SELECTION_START";
     readonly SELECTION_STOP: "SELECTION_STOP";
     readonly CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__";
+    /** Side Panel → Background：立即轮询一次并回传当前服务信息 */
+    readonly FORCE_POLL: "FORCE_POLL";
     readonly PAGE_CONTEXT: "PAGE_CONTEXT";
     readonly THEME_CHANGE: "THEME_CHANGE";
     readonly SERVICE_APPEARED: "SERVICE_APPEARED";
@@ -118,6 +122,8 @@ export declare const BRIDGE_SCRIPT_PATH = "/__aipanel_bridge__.js";
 export declare const LOGS_API_PATH = "/__aipanel_process_logs__";
 /** Widget 样式路径 */
 export declare const WIDGET_STYLE_PATH = "/__aipanel_widget__.css";
+/** Vue DevTools API 路径 */
+export declare const VUE_DEVTOOLS_API_PATH = "/__aipanel_vue_devtools__";
 /** ==================== 文本处理 ==================== */
 /** 元素文本最大显示长度 */
 export declare const MAX_TEXT_LENGTH = 100;
@@ -134,12 +140,6 @@ export declare const PAGE_CONTEXT_MAX_TEXT_LENGTH = 10000;
  */
 export declare const SEVERITY_ERROR = 1;
 export declare const SEVERITY_WARN = 2;
-/** ==================== VS Code 扩展桥接 ==================== */
-/** VS Code 扩展 HTTP 服务端口（vscode-extension ↔ provider 通信协议） */
-export declare const VSCODE_EXTENSION_PORT = 51939;
-/** VS Code 扩展相关环境变量名 */
-export declare const ENV_VSCODE_MODE = "AIPANEL_VSCODE_MODE";
-export declare const ENV_VSCODE_PORT = "AIPANEL_VSCODE_PORT";
 /** ==================== Vue DevTools API ==================== */
 /** Vue DevTools API action 名称 */
 export declare const VUE_DEVTOOLS_ACTIONS: {
@@ -151,3 +151,31 @@ export declare const VUE_DEVTOOLS_ACTIONS: {
     readonly GET_ROUTER_INFO: "getRouterInfo";
 };
 export type VueDevtoolsAction = (typeof VUE_DEVTOOLS_ACTIONS)[keyof typeof VUE_DEVTOOLS_ACTIONS];
+/** ==================== 写类工具名单 ==================== */
+/** 会修改文件的工具名（host 插件与编辑后自动诊断共用的单一来源） */
+export declare const MUTATING_TOOLS: ReadonlySet<string>;
+/** ==================== 挂件主题 ==================== */
+/** 挂件主题可选值（对应 AIPanelWidgetTheme） */
+export declare const WIDGET_THEME_MODES: readonly ["auto", "light", "dark"];
+/** ==================== OpenCode 环境变量名 ==================== */
+/** OpenCode 相关环境变量名（opencode provider 写、es/plugins 与 dsh-plugin 读，统一引用防止字面量漂移） */
+export declare const OPENCODE_ENV: {
+    readonly CONFIG_DIR: "OPENCODE_CONFIG_DIR";
+    readonly CONTEXT_API_URL: "OPENCODE_CONTEXT_API_URL";
+    readonly VITE_LOGS_API_URL: "OPENCODE_VITE_LOGS_API_URL";
+    readonly LOG_FILES_JSON: "OPENCODE_LOG_FILES_JSON";
+    readonly VERBOSE: "OPENCODE_VERBOSE";
+    readonly ENABLE_LINT: "OPENCODE_ENABLE_LINT";
+    readonly VUE_DEVTOOLS_API_URL: "OPENCODE_VUE_DEVTOOLS_API_URL";
+    readonly WORKSPACE: "OPENCODE_WORKSPACE";
+};
+/** ==================== SSE 事件流消息类型 ==================== */
+/** 服务端 → 客户端 SSE 信封 type 字段（vite endpoints 写、client useServerSSE 读） */
+export declare const SSE_EVENT_TYPES: {
+    readonly CONNECTED: "CONNECTED";
+    readonly STATUS_SYNC: "STATUS_SYNC";
+    readonly TASK_UPDATE: "TASK_UPDATE";
+    readonly SESSION_EVENT: "SESSION_EVENT";
+    readonly CLEAR_ELEMENTS: "CLEAR_ELEMENTS";
+};
+export type SSEEventType = (typeof SSE_EVENT_TYPES)[keyof typeof SSE_EVENT_TYPES];

package/es/{constants.mjs → common/constants.mjs}

@@ -22,6 +22,7 @@ const AUTO_OPEN_DELAY = 1e3;
 const NOTIFICATION_DURATION = 3e3;
 const INIT_MARKER = "__AIPANEL_INITIALIZED__";
 const SELECTED_ELEMENTS_KEY = "__aipanel_selected_elements__";
+const SESSION_ID_KEY = "_aipanel_pk";
 const AIPANEL_CACHE_DIR = "node_modules/.cache/aipanel";
 const CHROME_DEVTOOLS_PORT = 9222;
 const CHROME_DEVTOOLS_CHECK_TIMEOUT = 2e3;
@@ -38,7 +39,9 @@ const EXT_MSG = {
   REQUEST_PAGE_CONTEXT: "REQUEST_PAGE_CONTEXT",
   SELECTION_START: "SELECTION_START",
   SELECTION_STOP: "SELECTION_STOP",
-  CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__"
+  CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__",
+  /** Side Panel → Background：立即轮询一次并回传当前服务信息 */
+  FORCE_POLL: "FORCE_POLL"
 };
 const WIDGET_MSG = {
   READY: "AIPANEL_READY",
@@ -63,15 +66,13 @@ const WARMUP_API_PATH = "/__aipanel_warmup__";
 const BRIDGE_SCRIPT_PATH = "/__aipanel_bridge__.js";
 const LOGS_API_PATH = "/__aipanel_process_logs__";
 const WIDGET_STYLE_PATH = "/__aipanel_widget__.css";
+const VUE_DEVTOOLS_API_PATH = "/__aipanel_vue_devtools__";
 const MAX_TEXT_LENGTH = 100;
 const CONTEXT_MARKER = "[\u5143\u7D20\u4E0A\u4E0B\u6587]";
 const PAGE_CONTEXT_MARKER = "__AIPANEL_CONTEXT__";
 const PAGE_CONTEXT_MAX_TEXT_LENGTH = 1e4;
 const SEVERITY_ERROR = 1;
 const SEVERITY_WARN = 2;
-const VSCODE_EXTENSION_PORT = 51939;
-const ENV_VSCODE_MODE = "AIPANEL_VSCODE_MODE";
-const ENV_VSCODE_PORT = "AIPANEL_VSCODE_PORT";
 const VUE_DEVTOOLS_ACTIONS = {
   GET_COMPONENT_TREE: "getComponentTree",
   GET_COMPONENT_STATE: "getComponentState",
@@ -80,6 +81,25 @@ const VUE_DEVTOOLS_ACTIONS = {
   TOGGLE_APP: "toggleApp",
   GET_ROUTER_INFO: "getRouterInfo"
 };
+const MUTATING_TOOLS = /* @__PURE__ */ new Set(["write", "edit", "apply_patch"]);
+const WIDGET_THEME_MODES = ["auto", "light", "dark"];
+const OPENCODE_ENV = {
+  CONFIG_DIR: "OPENCODE_CONFIG_DIR",
+  CONTEXT_API_URL: "OPENCODE_CONTEXT_API_URL",
+  VITE_LOGS_API_URL: "OPENCODE_VITE_LOGS_API_URL",
+  LOG_FILES_JSON: "OPENCODE_LOG_FILES_JSON",
+  VERBOSE: "OPENCODE_VERBOSE",
+  ENABLE_LINT: "OPENCODE_ENABLE_LINT",
+  VUE_DEVTOOLS_API_URL: "OPENCODE_VUE_DEVTOOLS_API_URL",
+  WORKSPACE: "OPENCODE_WORKSPACE"
+};
+const SSE_EVENT_TYPES = {
+  CONNECTED: "CONNECTED",
+  STATUS_SYNC: "STATUS_SYNC",
+  TASK_UPDATE: "TASK_UPDATE",
+  SESSION_EVENT: "SESSION_EVENT",
+  CLEAR_ELEMENTS: "CLEAR_ELEMENTS"
+};
 export {
   AIPANEL_CACHE_DIR,
   AUTO_OPEN_DELAY,
@@ -94,8 +114,6 @@ export {
   DEFAULT_PROXY_PORT,
   DEFAULT_RETRIES,
   DEFAULT_WEB_PORT,
-  ENV_VSCODE_MODE,
-  ENV_VSCODE_PORT,
   EXT_BROADCAST,
   EXT_MSG,
   HOST_EVENTS_API_PATH,
@@ -106,7 +124,9 @@ export {
   MAX_PORT_TRIES,
   MAX_TEXT_LENGTH,
   MCP_API_PATH,
+  MUTATING_TOOLS,
   NOTIFICATION_DURATION,
+  OPENCODE_ENV,
   PAGE_CONTEXT_MARKER,
   PAGE_CONTEXT_MAX_TEXT_LENGTH,
   RETRY_DELAY,
@@ -115,14 +135,17 @@ export {
   SERVER_START_TIMEOUT,
   SERVER_SYNC_INTERVAL,
   SESSIONS_API_PATH,
+  SESSION_ID_KEY,
   SEVERITY_ERROR,
   SEVERITY_WARN,
   SSE_EVENTS_PATH,
+  SSE_EVENT_TYPES,
   START_API_PATH,
-  VSCODE_EXTENSION_PORT,
   VUE_DEVTOOLS_ACTIONS,
+  VUE_DEVTOOLS_API_PATH,
   WARMUP_API_PATH,
   WIDGET_MSG,
   WIDGET_SCRIPT_PATH,
-  WIDGET_STYLE_PATH
+  WIDGET_STYLE_PATH,
+  WIDGET_THEME_MODES
 };

package/{lib → es/common}/options.d.ts

@@ -3,6 +3,44 @@
  * Provider 专属配置通过泛型 P 注入，核心层不感知具体 schema。
  */
 import type { DisplayMode, LogFileConfig, SplitModeOptions } from "./types";
+/**
+ * chrome-devtools-mcp 进程的用户透传配置。
+ * 只允许“追加”，不允许覆盖核心受保护参数（由 McpProxy 统一过滤）。
+ */
+export interface ChromeMcpOptions {
+    /**
+     * 追加的 CLI 参数（先于核心参数注入）。
+     * 与核心受保护项（auto-connect / usage-statistics / performance-crux /
+     * page-id-routing 及其反义）冲突的参数会被剔除并告警。
+     */
+    args?: string[];
+    /** 透传给 chrome-devtools-mcp 进程的额外环境变量（合并到 process.env 之上） */
+    env?: Record<string, string>;
+    /** 项目边界策略（默认缺失 = 现状行为） */
+    project?: ChromeProjectOptions;
+}
+/**
+ * 项目边界策略（chrome-devtools-mcp 工具层的“本项目内操作”可配选项，默认均为现状）。
+ * 所有项只会收窄/放宽我们的边界判定，不改变白名单的权威性。
+ */
+export interface ChromeProjectOptions {
+    /**
+     * 白名单条目：除自动项目页外，可开启/可见/可操作的额外页面。每条三种写法：
+     * - 精确 origin："https://example.com"（前缀匹配该 origin 下任意路径）
+     * - glob 通配符："https://*.example.com/**"（picomatch，* 不跨 /，放开路径需 /**）
+     * - 正则字面量："/^https:\\/\\/app\\.example\\.com\\//"（以 / 起止、可带 flags，对完整 URL 匹配）
+     */
+    allowOrigins?: string[];
+    /** 是否允许扩展页（chrome-extension://）纳入可操作页面；启用时自动注入 --experimental-include-all-pages */
+    includeExtensionPages?: boolean;
+    /** 工具面选择：在默认白名单上按名字调整 */
+    tools?: {
+        /** 从默认白名单隐藏（如 ["upload_file"]） */
+        deny?: string[];
+        /** 仅可开启官方二级目录中的工具（如 click_at）；非目录名将被忽略并告警 */
+        extra?: string[];
+    };
+}
 /**
  * 插件配置选项
  * @typeParam P - 当前 Provider 的专属配置段（schema 由具体 Provider 声明）
@@ -34,6 +72,8 @@ export interface PluginOptions<P extends Record<string, unknown> = Record<string
     warmupChromeMcp?: boolean;
     /** Chrome DevTools Protocol 端口，默认 9222 */
     chromeDevtoolsPort?: number;
+    /** chrome-devtools-mcp 进程透传配置（只可追加，不可覆盖核心受保护参数） */
+    chromeMcp?: ChromeMcpOptions;
     /** 展示模式，默认 'bubble' */
     displayMode?: DisplayMode;
     /** 分屏模式配置 */

package/{lib → es/common}/types.d.ts

@@ -2,6 +2,7 @@
  * 通用类型（Provider 无关）
  * Provider 专属类型已下沉至 @aipanel/provider-opencode。
  */
+import type { SessionStatus } from "./provider";
 /**
  * 展示模式类型
  */
@@ -84,6 +85,8 @@ export interface SelectedElement {
     innerText: string;
     /** 元素描述（标签名+选择器） */
     description?: string;
+    /** 用户选中节点时的页面 URL（AIPanel 附加；host 端上下文注入用） */
+    previewPageUrl?: string;
 }
 /**
  * 页面上下文数据
@@ -121,9 +124,9 @@ export type AIPanelWidgetTheme = "light" | "dark" | "auto";
  */
 export type ServiceStatus = "idle" | "starting" | "ready" | "partial" | "failed";
 /**
- * Session 状态类型
+ * Session 状态类型（别名：以 ./provider 的 SessionStatus 为单一来源）
  */
-export type AIPanelSessionStatusType = "idle" | "running" | "streaming" | "completed";
+export type AIPanelSessionStatusType = SessionStatus;
 /**
  * Session 思考状态
  */
@@ -144,16 +147,22 @@ export interface AIPanelWidgetSession {
     url?: string;
 }
 /**
- * 挂件选中的元素
+ * 挂件选中的元素（别名：与 host 端 SelectedElement 同构，单一来源为本文件上方的 SelectedElement）
  */
-export interface AIPanelSelectedElement {
-    /** 节点唯一 id（与 SelectedElement.id 同源，`@节点[n<id>]` 标记与上下文注入共用） */
-    id?: string;
-    filePath: string | null;
-    line: number | null;
-    column: number | null;
-    innerText: string;
-    description?: string;
+export type AIPanelSelectedElement = SelectedElement;
+/**
+ * 单条代码诊断（1-based 行列坐标）——AIPanel 诊断工具（run_diagnostics 等）的
+ * canonical 持久化/展示共用协议：宿主插件写 tool/result.meta，client 插件据此渲染卡片。
+ */
+export interface AIPanelDiagnosticEntry {
+    /** 所属文件（绝对路径） */
+    file: string;
+    /** 1-based 行号 */
+    line: number;
+    /** 1-based 列号 */
+    column: number;
+    severity: "error" | "warning";
+    message: string;
 }
 /**
  * 删除选中节点的载荷
@@ -185,6 +194,22 @@ export interface AIPanelSelectedElementItem {
     panelFileText: string;
     element: AIPanelSelectedElement;
 }
+/**
+ * 服务实例信息（Chrome 扩展 Background ↔ Side Panel 共享的服务载荷；
+ * 由 widget 的 SERVICE_INFO 上报与 vite start 端点探测归一化而来）。
+ */
+export interface AIPanelServiceInfo {
+    /** 代理端口 */
+    proxyPort: number;
+    /** Vite 开发服务端口（字符串；可能来自 widget 上报或探测 origin） */
+    vitePort: string;
+    /** 项目根目录 */
+    projectRoot: string;
+    /** 服务实例唯一 id（多实例隔离） */
+    serviceInstanceId: string;
+    /** 是否开启 verbose（可选） */
+    verbose?: boolean;
+}
 /**
  * 挂件组件 Props
  */

package/es/{utils.d.ts → common/utils.d.ts}

@@ -1,6 +1,3 @@
-/**
- * @fileoverview 通用工具函数
- */
 /**
  * 取（或生成）元素的节点唯一 id：优先复用已赋值的 id，否则生成随机 id 并写回元素。
  * 同一引用在会话标记（`@节点[n<id>]`）与上下文注入里使用同一个 id；
@@ -42,3 +39,29 @@ export declare function base64Decode(base64: string): string;
  * 支持多种常见响应格式
  */
 export declare function extractTextFromResponse(data: unknown): string | null;
+/**
+ * 生成节点提及标记 `@节点[n<id>]`（与 ensureNodeId 分配的 n<hex> id 体系一致）
+ */
+export declare function toNodeMention(id: string): string;
+/**
+ * 从文本中提取全部节点提及 id（去重、保序）
+ */
+export declare function parseNodeMentions(text: string): string[];
+/**
+ * 构造 iframe postMessage 信封：{ type, ...data }（AIPanel 挂件与 dsh-client 共用同一形状）
+ */
+export declare function widgetEnvelope(type: string, data?: Record<string, unknown>): Record<string, unknown>;
+/** 重试配置 */
+export interface RetryOptions {
+    /** 总尝试次数（默认 core DEFAULT_RETRIES） */
+    attempts?: number;
+    /** 失败后连续尝试间隔毫秒（默认 core RETRY_DELAY） */
+    delayMs?: number;
+    /** 每次失败、重试前回调（attempt 为 1-based） */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * 带线性重试的执行包裹：执行 fn 直到成功或尝试完毕；最后一次失败原样抛出。
+ * 环境无关（仅使用 setTimeout），放于 common 供浏览器与 node 共用。
+ */
+export declare function withRetries<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;

package/es/{utils.mjs → common/utils.mjs}

@@ -1,3 +1,4 @@
+import { DEFAULT_RETRIES, RETRY_DELAY } from "./constants.mjs";
 function ensureNodeId(element) {
   if (element.id) return element.id;
   const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID().replace(/-/g, "").slice(0, 8) : Math.random().toString(36).slice(2, 10);
@@ -50,11 +51,51 @@ function extractTextFromResponse(data) {
   }
   return null;
 }
+const NODE_MENTION_RE = /@节点\[(n[0-9a-z]+)\]/g;
+function toNodeMention(id) {
+  return `@\u8282\u70B9[${id}]`;
+}
+function parseNodeMentions(text) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(NODE_MENTION_RE)) {
+    const id = m[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+function widgetEnvelope(type, data) {
+  return { type, ...data };
+}
+async function withRetries(fn, options = {}) {
+  const attempts = options.attempts ?? DEFAULT_RETRIES;
+  const delayMs = options.delayMs ?? RETRY_DELAY;
+  let lastError;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn(i);
+    } catch (e) {
+      lastError = e;
+      if (i < attempts - 1) {
+        options.onRetry?.(i + 1, e);
+        if (delayMs > 0) await sleep(delayMs);
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
 export {
   base64Decode,
   base64Encode,
   ensureNodeId,
   extractTextFromResponse,
+  parseNodeMentions,
   sleep,
-  truncate
+  toNodeMention,
+  truncate,
+  widgetEnvelope,
+  withRetries
 };

package/es/index.d.ts

@@ -1,7 +1,6 @@
-export * from "./constants";
-export * from "./logger-core";
-export * from "./logger";
-export * from "./options";
-export * from "./provider";
-export * from "./types";
-export * from "./utils";
+export * from "./common/constants";
+export * from "./common/logger-core";
+export * from "./common/options";
+export * from "./common/provider";
+export * from "./common/types";
+export * from "./common/utils";

package/es/index.mjs

@@ -1,7 +1,6 @@
-export * from "./constants.mjs";
-export * from "./logger-core.mjs";
-export * from "./logger.mjs";
-export * from "./options.mjs";
-export * from "./provider.mjs";
-export * from "./types.mjs";
-export * from "./utils.mjs";
+export * from "./common/constants.mjs";
+export * from "./common/logger-core.mjs";
+export * from "./common/options.mjs";
+export * from "./common/provider.mjs";
+export * from "./common/types.mjs";
+export * from "./common/utils.mjs";

package/es/node/diagnostics.d.ts

@@ -1,5 +1,10 @@
 /** 是否为可诊断的源码文件（供宿主钩子过滤 edit/write 目标） */
 export declare function isJsFile(filePath: string): boolean;
+/**
+ * run_diagnostics 工具描述（单一来源，供 opencode / dsh 两侧插件引用）：
+ * 只声明能力与支持的文件类型，不涉及内部使用的检查工具。
+ */
+export declare const DIAGNOSTICS_TOOL_DESCRIPTION: string;
 /** LSP 风格诊断项（供宿主写入 metadata.diagnostics 等结构化输出） */
 export interface DiagnosticItem {
     /** 所属文件路径（相对/绝对，按来源解析）；跨文件诊断（全量模式）时必有 */

package/es/node/diagnostics.mjs

@@ -2,8 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { exec } from "node:child_process";
 import { createRequire } from "node:module";
-import { SEVERITY_ERROR, SEVERITY_WARN } from "../constants.mjs";
-import { createLogger } from "../node-logger.mjs";
+import { SEVERITY_ERROR, SEVERITY_WARN } from "../common/constants.mjs";
+import { createLogger } from "./node-logger.mjs";
 const log = createLogger("Diagnostics");
 const JS_EXTENSIONS = /* @__PURE__ */ new Set([
   ".js",
@@ -19,6 +19,19 @@ const JS_EXTENSIONS = /* @__PURE__ */ new Set([
 function isJsFile(filePath) {
   return JS_EXTENSIONS.has(path.extname(filePath));
 }
+const DIAGNOSTICS_TOOL_DESCRIPTION = [
+  "\u8FD0\u884C ESLint \u4E0E TypeScript \u7C7B\u578B\u8BCA\u65AD\uFF0C\u8FD4\u56DE\u8BCA\u65AD\u7ED3\u679C\u3002",
+  "",
+  "**\u652F\u6301\u7684\u6587\u4EF6\u7C7B\u578B**\uFF1A",
+  `- ESLint\uFF1AJavaScript / TypeScript / Vue \u6E90\u7801\uFF08${[...JS_EXTENSIONS].map((e) => `*${e}`).join(" ")}\uFF09`,
+  "- TypeScript \u7C7B\u578B\u68C0\u67E5\uFF1A*.ts *.tsx *.vue",
+  "",
+  "**\u4F55\u65F6\u4F7F\u7528\u6B64\u5DE5\u5177**\uFF1A",
+  "- \u521A\u5B8C\u6210\u4EE3\u7801\u4FEE\u6539\uFF0C\u60F3\u9A8C\u8BC1\u662F\u5426\u6709 ESLint \u9519\u8BEF\u6216\u7C7B\u578B\u9519\u8BEF",
+  "- \u5728\u63D0\u4EA4\u4EE3\u7801\u524D\u8FDB\u884C\u8D28\u91CF\u68C0\u67E5",
+  "- \u6392\u67E5\u7F16\u8F91\u5668\u672A\u663E\u793A\u4F46\u5B9E\u9645\u5B58\u5728\u7684\u7C7B\u578B\u95EE\u9898",
+  "- \u4E0D\u4F20\u53C2\u6570\u53EF\u5168\u91CF\u8BCA\u65AD\u6574\u4E2A\u9879\u76EE"
+].join("\n");
 let ESLintClass;
 function loadESLint(workspace) {
   if (ESLintClass) return;
@@ -34,7 +47,12 @@ function loadESLint(workspace) {
 }
 async function lintFiles(pattern, cwd, warnLimit = 5) {
   loadESLint(cwd);
-  if (!ESLintClass) return {};
+  if (!ESLintClass) {
+    return {
+      text: `[ESLint] \u672A\u8FD0\u884C\uFF1A\u65E0\u6CD5\u5728 workspace "${cwd}" \u89E3\u6790\u5230 eslint\uFF08\u4EC5\u663E\u793A TypeScript \u8BCA\u65AD\uFF09`,
+      diagnostics: []
+    };
+  }
   try {
     const eslint = new ESLintClass({ cwd });
     const results = await eslint.lintFiles(pattern);
@@ -82,7 +100,10 @@ async function lintFiles(pattern, cwd, warnLimit = 5) {
     return { text: lines.length > 0 ? lines.join("\n") : void 0, diagnostics };
   } catch (err) {
     log.warn("ESLint failed", { pattern, error: err.message });
-    return {};
+    return {
+      text: `[ESLint] \u8FD0\u884C\u5931\u8D25\uFF1A${err.message}\uFF08\u4EC5\u663E\u793A TypeScript \u8BCA\u65AD\uFF09`,
+      diagnostics: []
+    };
   }
 }
 let _vueTscBin;
@@ -255,6 +276,7 @@ function formatDiagnosticsSections(title, eslintOutput, tscOutput) {
 ` + parts.join("\n\n");
 }
 export {
+  DIAGNOSTICS_TOOL_DESCRIPTION,
   findAllTsconfigDirs,
   findTsconfigDir,
   formatDiagnosticsSections,

package/es/{file-log-watcher.mjs → node/file-log-watcher.mjs}

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { createLogger } from "./logger.mjs";
+import { createLogger } from "../client/logger.mjs";
 const log = createLogger("FileLogReader");
 function detectLogLevel(line) {
   const lowerLine = line.toLowerCase();

package/{lib → es/node}/node-logger.d.ts

@@ -1,4 +1,4 @@
-import { type LogContext } from "./logger-core";
+import { type LogContext } from "../common/logger-core";
 export declare const nodeLogger: {
     debug(message: string, context?: LogContext, ...args: unknown[]): void;
     info(message: string, context?: LogContext, ...args: unknown[]): void;