@aipanel/core 1.3.8 → 1.3.9

package/es/common/constants.d.ts

@@ -56,7 +56,7 @@ export declare const NOTIFICATION_DURATION = 3000;
 export declare const INIT_MARKER = "__AIPANEL_INITIALIZED__";
 /** 选中元素存储键 */
 export declare const SELECTED_ELEMENTS_KEY = "__aipanel_selected_elements__";
-/** 页面会话标识键（sessionStorage，跨导航标识同一 Tab 的页面上下文） */
+/** 页内会话标识键（sessionStorage，跨导航标识同一 Tab 的页面上下文） */
 export declare const SESSION_ID_KEY = "_aipanel_pk";
 /** ==================== 缓存目录 ==================== */
 /**
@@ -64,6 +64,18 @@ export declare const SESSION_ID_KEY = "_aipanel_pk";
  * 存放 opencode.json、dsh overlay 等运行时状态，不污染项目根目录。
  */
 export declare const AIPANEL_CACHE_DIR = "node_modules/.cache/aipanel";
+/** ==================== 源码路径 ==================== */
+/**
+ * 依赖安装目录名（判定文件是否来自依赖包的唯一依据）。
+ * 宿主侧上下文归一化与两个 Provider 的注入文案共用，避免各写一份 magic string。
+ */
+export declare const DEPENDENCY_DIR_NAME = "node_modules";
+/**
+ * 依赖内部文件的归属提示（注入给 agent 的上下文文案）。
+ * 两个 Provider 共用同一措辞：agent 拿到 node_modules 路径时最容易顺着它去改第三方实现，
+ * 归属必须显式声明，而不是让「源码文件路径」这行字暗示它是项目源码。
+ */
+export declare const DEPENDENCY_SOURCE_NOTE = "\u4F9D\u8D56\u5305\u5185\u6587\u4EF6\uFF08node_modules\uFF09\uFF1A\u901A\u5E38\u4E0D\u5E94\u76F4\u63A5\u4FEE\u6539\uFF0C\u9875\u9762\u884C\u4E3A\u8BF7\u6539\u9879\u76EE\u5185\u6E90\u7801";
 /** ==================== Chrome DevTools ==================== */
 /** Chrome DevTools Protocol 默认端口 */
 export declare const CHROME_DEVTOOLS_PORT = 9222;
@@ -84,6 +96,8 @@ export declare const EXT_MSG: {
     readonly REQUEST_PAGE_CONTEXT: "REQUEST_PAGE_CONTEXT";
     readonly SELECTION_START: "SELECTION_START";
     readonly SELECTION_STOP: "SELECTION_STOP";
+    /** Side Panel → 目标 Tab：请目标页定位某个已选节点（跳回其页面并呼吸高亮） */
+    readonly LOCATE_NODE: "LOCATE_NODE";
     readonly CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__";
     /** Side Panel → Background：立即轮询一次并回传当前服务信息 */
     readonly FORCE_POLL: "FORCE_POLL";
@@ -118,6 +132,8 @@ export declare const WIDGET_MSG: {
     readonly FOCUS_SESSION: "AIPANEL_FOCUS_SESSION";
     /** 无 deepLink 能力的 Provider：iframe 确认目标会话已激活且渲染稳定（携带 sessionId） */
     readonly SESSION_READY: "AIPANEL_SESSION_READY";
+    /** iframe → 宿主：点节点 chip 时把该节点交回挂件，跳回它被选中时的页面并闪烁高亮；载荷 { element } */
+    readonly LOCATE_NODE: "AIPANEL_LOCATE_NODE";
 };
 /** ==================== API 路径补充 ==================== */
 /** Provider 预热 API 路径 */

package/es/common/constants.mjs

@@ -24,6 +24,8 @@ 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 DEPENDENCY_DIR_NAME = "node_modules";
+const DEPENDENCY_SOURCE_NOTE = `\u4F9D\u8D56\u5305\u5185\u6587\u4EF6\uFF08${DEPENDENCY_DIR_NAME}\uFF09\uFF1A\u901A\u5E38\u4E0D\u5E94\u76F4\u63A5\u4FEE\u6539\uFF0C\u9875\u9762\u884C\u4E3A\u8BF7\u6539\u9879\u76EE\u5185\u6E90\u7801`;
 const CHROME_DEVTOOLS_PORT = 9222;
 const CHROME_DEVTOOLS_CHECK_TIMEOUT = 2e3;
 const EXT_BROADCAST = {
@@ -39,6 +41,8 @@ const EXT_MSG = {
   REQUEST_PAGE_CONTEXT: "REQUEST_PAGE_CONTEXT",
   SELECTION_START: "SELECTION_START",
   SELECTION_STOP: "SELECTION_STOP",
+  /** Side Panel → 目标 Tab：请目标页定位某个已选节点（跳回其页面并呼吸高亮） */
+  LOCATE_NODE: "LOCATE_NODE",
   CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__",
   /** Side Panel → Background：立即轮询一次并回传当前服务信息 */
   FORCE_POLL: "FORCE_POLL"
@@ -66,7 +70,9 @@ const WIDGET_MSG = {
   /** 无 deepLink 能力的 Provider：通知 iframe 聚焦指定会话 */
   FOCUS_SESSION: "AIPANEL_FOCUS_SESSION",
   /** 无 deepLink 能力的 Provider：iframe 确认目标会话已激活且渲染稳定（携带 sessionId） */
-  SESSION_READY: "AIPANEL_SESSION_READY"
+  SESSION_READY: "AIPANEL_SESSION_READY",
+  /** iframe → 宿主：点节点 chip 时把该节点交回挂件，跳回它被选中时的页面并闪烁高亮；载荷 { element } */
+  LOCATE_NODE: "AIPANEL_LOCATE_NODE"
 };
 const WARMUP_API_PATH = "/__aipanel_warmup__";
 const BRIDGE_SCRIPT_PATH = "/__aipanel_bridge__.js";
@@ -160,6 +166,8 @@ export {
   DEFAULT_PROXY_PORT,
   DEFAULT_RETRIES,
   DEFAULT_WEB_PORT,
+  DEPENDENCY_DIR_NAME,
+  DEPENDENCY_SOURCE_NOTE,
   EXT_BROADCAST,
   EXT_MSG,
   HOST_EVENTS_API_PATH,

package/es/common/diagnostics.mjs

@@ -1,3 +1,4 @@
+import { fileNameOf } from "./utils.mjs";
 const COMMAND_CHECK_TIMEOUT_MS = 6e4;
 const SOURCE_EXTENSIONS = [
   ".js",
@@ -12,7 +13,7 @@ const SOURCE_EXTENSIONS = [
 ];
 function matchesExtensions(filePath, extensions) {
   if (!extensions?.length) return true;
-  const base = filePath.replace(/\\/g, "/").split("/").pop() ?? "";
+  const base = fileNameOf(filePath);
   const dot = base.lastIndexOf(".");
   if (dot <= 0) return false;
   return extensions.includes(base.slice(dot).toLowerCase());

package/es/common/inspector/vue.mjs

@@ -1,4 +1,5 @@
 import { INSPECTOR_ADAPTER_IDS } from "../constants.mjs";
+import { isDependencyPath } from "../utils.mjs";
 import {
   parseSourceLocation
 } from "./types.mjs";
@@ -63,9 +64,8 @@ function resolveFromVueInstance(element) {
 function mergeSourceLocations(markerLocation, instanceLocation) {
   if (!markerLocation?.file && !instanceLocation?.file) return null;
   if (markerLocation?.file && instanceLocation?.file) {
-    const isNodeModules = (path) => path.includes("node_modules");
-    if (!isNodeModules(markerLocation.file)) return markerLocation;
-    if (!isNodeModules(instanceLocation.file)) return instanceLocation;
+    if (!isDependencyPath(markerLocation.file)) return markerLocation;
+    if (!isDependencyPath(instanceLocation.file)) return instanceLocation;
     return markerLocation;
   }
   return markerLocation?.file ? markerLocation : instanceLocation;

package/es/common/types.d.ts

@@ -77,7 +77,11 @@ export interface LogFileConfig {
 export interface SelectedElement {
     /** 节点唯一 id（`@节点[n<id>]` 引用标记与上下文注入共用；由 ensureNodeId 分配） */
     id?: string;
-    /** 文件路径 */
+    /**
+     * 文件路径（绝对路径）。
+     * 浏览器只上报相对路径（各 Inspector 基准不同），由 Vite 端点按宿主基准归一化后落库，
+     * 消费方（Provider 注入、UI 展示）拿到的恒为绝对路径。
+     */
     filePath: string | null;
     /** 行号 */
     line: number | null;
@@ -305,6 +309,8 @@ export type AIPanelWidgetEmits = {
     (e: "select-session", session: AIPanelWidgetSession): void;
     (e: "delete-session", session: AIPanelWidgetSession): void;
     (e: "click-selected-node", element: AIPanelSelectedElement): void;
+    /** 宿主无法在本地定位（扩展模式下页面不在本上下文）：把节点交给宿主转发到目标页 */
+    (e: "locate-node", element: AIPanelSelectedElement): void;
     (e: "remove-selected-node", payload: AIPanelRemoveSelectedPayload): void;
     (e: "clear-selected-nodes"): void;
     (e: "empty-action"): void;

package/es/common/utils.d.ts

@@ -1,3 +1,33 @@
+/**
+ * 路径分隔符归一化（反斜杠 → 正斜杠）。
+ * 浏览器侧没有 node:path，路径处理统一按字符串做；宿主的绝对路径在 Windows 上会带 `\`。
+ * @param filePath - 原始路径
+ * @returns 分隔符统一为正斜杠的路径
+ */
+export declare function normalizePathSeparators(filePath: string): string;
+/**
+ * 取路径的文件名（最后一段），兼容 `/` 与 `\` 分隔。
+ * 挂件气泡/节点卡片（浏览器）与进程日志（node）共用，避免各处自写 split("/").pop()。
+ * @param filePath - 原始路径
+ * @returns 文件名；路径为空或以分隔符结尾时返回空串
+ */
+export declare function fileNameOf(filePath: string): string;
+/**
+ * 路径是否位于依赖安装目录内（含 pnpm 的 `.pnpm/<pkg>@<ver>/node_modules/<pkg>` 真身）。
+ * 按路径分段判定，避免误伤名字里含 node_modules 的项目目录。
+ * @param filePath - 原始路径
+ * @returns 为依赖内部文件时 true
+ */
+export declare function isDependencyPath(filePath: string): boolean;
+/**
+ * 拼「路径:行:列」形式的源码位置（形如 `/proj/src/App.vue:53:11`）。
+ * 节点上下文注入（两个 Provider）与编辑器跳转（launch-editor 的位置格式）共用同一形态。
+ * @param filePath - 文件路径
+ * @param line - 行号（缺省时只返回路径）
+ * @param column - 列号（缺省时只到行）
+ * @returns 源码位置字符串
+ */
+export declare function formatSourceLocation(filePath: string, line?: number | null, column?: number | null): string;
 /**
  * 取（或生成）元素的节点唯一 id：优先复用已赋值的 id，否则生成随机 id 并写回元素。
  * 同一引用在会话标记（`@节点[n<id>]`）与上下文注入里使用同一个 id；

package/es/common/utils.mjs

@@ -1,4 +1,18 @@
-import { DEFAULT_RETRIES, RETRY_DELAY } from "./constants.mjs";
+import { DEFAULT_RETRIES, DEPENDENCY_DIR_NAME, RETRY_DELAY } from "./constants.mjs";
+function normalizePathSeparators(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+function fileNameOf(filePath) {
+  const normalized = normalizePathSeparators(filePath);
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+function isDependencyPath(filePath) {
+  return normalizePathSeparators(filePath).split("/").includes(DEPENDENCY_DIR_NAME);
+}
+function formatSourceLocation(filePath, line, column) {
+  if (!line) return filePath;
+  return column ? `${filePath}:${line}:${column}` : `${filePath}:${line}`;
+}
 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);
@@ -92,6 +106,10 @@ export {
   base64Encode,
   ensureNodeId,
   extractTextFromResponse,
+  fileNameOf,
+  formatSourceLocation,
+  isDependencyPath,
+  normalizePathSeparators,
   parseNodeMentions,
   sleep,
   toNodeMention,

package/es/node/node-logger.mjs

@@ -2,6 +2,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import { LOG_PREFIX } from "../common/constants.mjs";
+import { fileNameOf } from "../common/utils.mjs";
 import {
   LEVEL_NAMES,
   LogLevel,
@@ -39,7 +40,7 @@ function getCallerInfo(depth = 3) {
   const match = targetLine.match(/at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?/);
   if (!match) return "";
   const [, funcName, filePath, line] = match;
-  const fileName = filePath.split("/").pop() || filePath;
+  const fileName = fileNameOf(filePath) || filePath;
   const func = funcName || "<anonymous>";
   return `${fileName}:${line} ${func}`;
 }

package/lib/common/constants.cjs

@@ -30,6 +30,8 @@ __export(constants_exports, {
   DEFAULT_PROXY_PORT: () => DEFAULT_PROXY_PORT,
   DEFAULT_RETRIES: () => DEFAULT_RETRIES,
   DEFAULT_WEB_PORT: () => DEFAULT_WEB_PORT,
+  DEPENDENCY_DIR_NAME: () => DEPENDENCY_DIR_NAME,
+  DEPENDENCY_SOURCE_NOTE: () => DEPENDENCY_SOURCE_NOTE,
   EXT_BROADCAST: () => EXT_BROADCAST,
   EXT_MSG: () => EXT_MSG,
   HOST_EVENTS_API_PATH: () => HOST_EVENTS_API_PATH,
@@ -97,6 +99,8 @@ 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 DEPENDENCY_DIR_NAME = "node_modules";
+const DEPENDENCY_SOURCE_NOTE = `\u4F9D\u8D56\u5305\u5185\u6587\u4EF6\uFF08${DEPENDENCY_DIR_NAME}\uFF09\uFF1A\u901A\u5E38\u4E0D\u5E94\u76F4\u63A5\u4FEE\u6539\uFF0C\u9875\u9762\u884C\u4E3A\u8BF7\u6539\u9879\u76EE\u5185\u6E90\u7801`;
 const CHROME_DEVTOOLS_PORT = 9222;
 const CHROME_DEVTOOLS_CHECK_TIMEOUT = 2e3;
 const EXT_BROADCAST = {
@@ -112,6 +116,8 @@ const EXT_MSG = {
   REQUEST_PAGE_CONTEXT: "REQUEST_PAGE_CONTEXT",
   SELECTION_START: "SELECTION_START",
   SELECTION_STOP: "SELECTION_STOP",
+  /** Side Panel → 目标 Tab：请目标页定位某个已选节点（跳回其页面并呼吸高亮） */
+  LOCATE_NODE: "LOCATE_NODE",
   CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__",
   /** Side Panel → Background：立即轮询一次并回传当前服务信息 */
   FORCE_POLL: "FORCE_POLL"
@@ -139,7 +145,9 @@ const WIDGET_MSG = {
   /** 无 deepLink 能力的 Provider：通知 iframe 聚焦指定会话 */
   FOCUS_SESSION: "AIPANEL_FOCUS_SESSION",
   /** 无 deepLink 能力的 Provider：iframe 确认目标会话已激活且渲染稳定（携带 sessionId） */
-  SESSION_READY: "AIPANEL_SESSION_READY"
+  SESSION_READY: "AIPANEL_SESSION_READY",
+  /** iframe → 宿主：点节点 chip 时把该节点交回挂件，跳回它被选中时的页面并闪烁高亮；载荷 { element } */
+  LOCATE_NODE: "AIPANEL_LOCATE_NODE"
 };
 const WARMUP_API_PATH = "/__aipanel_warmup__";
 const BRIDGE_SCRIPT_PATH = "/__aipanel_bridge__.js";
@@ -234,6 +242,8 @@ const INSPECTOR_ADAPTER_IDS = {
   DEFAULT_PROXY_PORT,
   DEFAULT_RETRIES,
   DEFAULT_WEB_PORT,
+  DEPENDENCY_DIR_NAME,
+  DEPENDENCY_SOURCE_NOTE,
   EXT_BROADCAST,
   EXT_MSG,
   HOST_EVENTS_API_PATH,

package/lib/common/constants.d.ts

@@ -56,7 +56,7 @@ export declare const NOTIFICATION_DURATION = 3000;
 export declare const INIT_MARKER = "__AIPANEL_INITIALIZED__";
 /** 选中元素存储键 */
 export declare const SELECTED_ELEMENTS_KEY = "__aipanel_selected_elements__";
-/** 页面会话标识键（sessionStorage，跨导航标识同一 Tab 的页面上下文） */
+/** 页内会话标识键（sessionStorage，跨导航标识同一 Tab 的页面上下文） */
 export declare const SESSION_ID_KEY = "_aipanel_pk";
 /** ==================== 缓存目录 ==================== */
 /**
@@ -64,6 +64,18 @@ export declare const SESSION_ID_KEY = "_aipanel_pk";
  * 存放 opencode.json、dsh overlay 等运行时状态，不污染项目根目录。
  */
 export declare const AIPANEL_CACHE_DIR = "node_modules/.cache/aipanel";
+/** ==================== 源码路径 ==================== */
+/**
+ * 依赖安装目录名（判定文件是否来自依赖包的唯一依据）。
+ * 宿主侧上下文归一化与两个 Provider 的注入文案共用，避免各写一份 magic string。
+ */
+export declare const DEPENDENCY_DIR_NAME = "node_modules";
+/**
+ * 依赖内部文件的归属提示（注入给 agent 的上下文文案）。
+ * 两个 Provider 共用同一措辞：agent 拿到 node_modules 路径时最容易顺着它去改第三方实现，
+ * 归属必须显式声明，而不是让「源码文件路径」这行字暗示它是项目源码。
+ */
+export declare const DEPENDENCY_SOURCE_NOTE = "\u4F9D\u8D56\u5305\u5185\u6587\u4EF6\uFF08node_modules\uFF09\uFF1A\u901A\u5E38\u4E0D\u5E94\u76F4\u63A5\u4FEE\u6539\uFF0C\u9875\u9762\u884C\u4E3A\u8BF7\u6539\u9879\u76EE\u5185\u6E90\u7801";
 /** ==================== Chrome DevTools ==================== */
 /** Chrome DevTools Protocol 默认端口 */
 export declare const CHROME_DEVTOOLS_PORT = 9222;
@@ -84,6 +96,8 @@ export declare const EXT_MSG: {
     readonly REQUEST_PAGE_CONTEXT: "REQUEST_PAGE_CONTEXT";
     readonly SELECTION_START: "SELECTION_START";
     readonly SELECTION_STOP: "SELECTION_STOP";
+    /** Side Panel → 目标 Tab：请目标页定位某个已选节点（跳回其页面并呼吸高亮） */
+    readonly LOCATE_NODE: "LOCATE_NODE";
     readonly CS_QUERY_WINDOW: "__CS_QUERY_WINDOW__";
     /** Side Panel → Background：立即轮询一次并回传当前服务信息 */
     readonly FORCE_POLL: "FORCE_POLL";
@@ -118,6 +132,8 @@ export declare const WIDGET_MSG: {
     readonly FOCUS_SESSION: "AIPANEL_FOCUS_SESSION";
     /** 无 deepLink 能力的 Provider：iframe 确认目标会话已激活且渲染稳定（携带 sessionId） */
     readonly SESSION_READY: "AIPANEL_SESSION_READY";
+    /** iframe → 宿主：点节点 chip 时把该节点交回挂件，跳回它被选中时的页面并闪烁高亮；载荷 { element } */
+    readonly LOCATE_NODE: "AIPANEL_LOCATE_NODE";
 };
 /** ==================== API 路径补充 ==================== */
 /** Provider 预热 API 路径 */

package/lib/common/diagnostics.cjs

@@ -33,6 +33,7 @@ __export(diagnostics_exports, {
   resolveDiagnosticsPolicy: () => resolveDiagnosticsPolicy
 });
 module.exports = __toCommonJS(diagnostics_exports);
+var import_utils = require("./utils.cjs");
 const COMMAND_CHECK_TIMEOUT_MS = 6e4;
 const SOURCE_EXTENSIONS = [
   ".js",
@@ -47,7 +48,7 @@ const SOURCE_EXTENSIONS = [
 ];
 function matchesExtensions(filePath, extensions) {
   if (!extensions?.length) return true;
-  const base = filePath.replace(/\\/g, "/").split("/").pop() ?? "";
+  const base = (0, import_utils.fileNameOf)(filePath);
   const dot = base.lastIndexOf(".");
   if (dot <= 0) return false;
   return extensions.includes(base.slice(dot).toLowerCase());

package/lib/common/inspector/vue.cjs

@@ -21,6 +21,7 @@ __export(vue_exports, {
 });
 module.exports = __toCommonJS(vue_exports);
 var import_constants = require("../constants.cjs");
+var import_utils = require("../utils.cjs");
 var import_types = require("./types.cjs");
 const SOURCE_LOCATION_ATTRIBUTE = "data-v-inspector";
 const VNODE_SOURCE_KEY = "__v_inspector";
@@ -83,9 +84,8 @@ function resolveFromVueInstance(element) {
 function mergeSourceLocations(markerLocation, instanceLocation) {
   if (!markerLocation?.file && !instanceLocation?.file) return null;
   if (markerLocation?.file && instanceLocation?.file) {
-    const isNodeModules = (path) => path.includes("node_modules");
-    if (!isNodeModules(markerLocation.file)) return markerLocation;
-    if (!isNodeModules(instanceLocation.file)) return instanceLocation;
+    if (!(0, import_utils.isDependencyPath)(markerLocation.file)) return markerLocation;
+    if (!(0, import_utils.isDependencyPath)(instanceLocation.file)) return instanceLocation;
     return markerLocation;
   }
   return markerLocation?.file ? markerLocation : instanceLocation;

package/lib/common/types.d.ts

@@ -77,7 +77,11 @@ export interface LogFileConfig {
 export interface SelectedElement {
     /** 节点唯一 id（`@节点[n<id>]` 引用标记与上下文注入共用；由 ensureNodeId 分配） */
     id?: string;
-    /** 文件路径 */
+    /**
+     * 文件路径（绝对路径）。
+     * 浏览器只上报相对路径（各 Inspector 基准不同），由 Vite 端点按宿主基准归一化后落库，
+     * 消费方（Provider 注入、UI 展示）拿到的恒为绝对路径。
+     */
     filePath: string | null;
     /** 行号 */
     line: number | null;
@@ -305,6 +309,8 @@ export type AIPanelWidgetEmits = {
     (e: "select-session", session: AIPanelWidgetSession): void;
     (e: "delete-session", session: AIPanelWidgetSession): void;
     (e: "click-selected-node", element: AIPanelSelectedElement): void;
+    /** 宿主无法在本地定位（扩展模式下页面不在本上下文）：把节点交给宿主转发到目标页 */
+    (e: "locate-node", element: AIPanelSelectedElement): void;
     (e: "remove-selected-node", payload: AIPanelRemoveSelectedPayload): void;
     (e: "clear-selected-nodes"): void;
     (e: "empty-action"): void;

package/lib/common/utils.cjs

@@ -21,6 +21,10 @@ __export(utils_exports, {
   base64Encode: () => base64Encode,
   ensureNodeId: () => ensureNodeId,
   extractTextFromResponse: () => extractTextFromResponse,
+  fileNameOf: () => fileNameOf,
+  formatSourceLocation: () => formatSourceLocation,
+  isDependencyPath: () => isDependencyPath,
+  normalizePathSeparators: () => normalizePathSeparators,
   parseNodeMentions: () => parseNodeMentions,
   sleep: () => sleep,
   toNodeMention: () => toNodeMention,
@@ -30,6 +34,20 @@ __export(utils_exports, {
 });
 module.exports = __toCommonJS(utils_exports);
 var import_constants = require("./constants.cjs");
+function normalizePathSeparators(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+function fileNameOf(filePath) {
+  const normalized = normalizePathSeparators(filePath);
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+function isDependencyPath(filePath) {
+  return normalizePathSeparators(filePath).split("/").includes(import_constants.DEPENDENCY_DIR_NAME);
+}
+function formatSourceLocation(filePath, line, column) {
+  if (!line) return filePath;
+  return column ? `${filePath}:${line}:${column}` : `${filePath}:${line}`;
+}
 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);
@@ -124,6 +142,10 @@ async function withRetries(fn, options = {}) {
   base64Encode,
   ensureNodeId,
   extractTextFromResponse,
+  fileNameOf,
+  formatSourceLocation,
+  isDependencyPath,
+  normalizePathSeparators,
   parseNodeMentions,
   sleep,
   toNodeMention,

package/lib/common/utils.d.ts

@@ -1,3 +1,33 @@
+/**
+ * 路径分隔符归一化（反斜杠 → 正斜杠）。
+ * 浏览器侧没有 node:path，路径处理统一按字符串做；宿主的绝对路径在 Windows 上会带 `\`。
+ * @param filePath - 原始路径
+ * @returns 分隔符统一为正斜杠的路径
+ */
+export declare function normalizePathSeparators(filePath: string): string;
+/**
+ * 取路径的文件名（最后一段），兼容 `/` 与 `\` 分隔。
+ * 挂件气泡/节点卡片（浏览器）与进程日志（node）共用，避免各处自写 split("/").pop()。
+ * @param filePath - 原始路径
+ * @returns 文件名；路径为空或以分隔符结尾时返回空串
+ */
+export declare function fileNameOf(filePath: string): string;
+/**
+ * 路径是否位于依赖安装目录内（含 pnpm 的 `.pnpm/<pkg>@<ver>/node_modules/<pkg>` 真身）。
+ * 按路径分段判定，避免误伤名字里含 node_modules 的项目目录。
+ * @param filePath - 原始路径
+ * @returns 为依赖内部文件时 true
+ */
+export declare function isDependencyPath(filePath: string): boolean;
+/**
+ * 拼「路径:行:列」形式的源码位置（形如 `/proj/src/App.vue:53:11`）。
+ * 节点上下文注入（两个 Provider）与编辑器跳转（launch-editor 的位置格式）共用同一形态。
+ * @param filePath - 文件路径
+ * @param line - 行号（缺省时只返回路径）
+ * @param column - 列号（缺省时只到行）
+ * @returns 源码位置字符串
+ */
+export declare function formatSourceLocation(filePath: string, line?: number | null, column?: number | null): string;
 /**
  * 取（或生成）元素的节点唯一 id：优先复用已赋值的 id，否则生成随机 id 并写回元素。
  * 同一引用在会话标记（`@节点[n<id>]`）与上下文注入里使用同一个 id；

package/lib/node/node-logger.cjs

@@ -29,6 +29,7 @@ __export(node_logger_exports, {
 });
 module.exports = __toCommonJS(node_logger_exports);
 var import_constants = require("../common/constants.cjs");
+var import_utils = require("../common/utils.cjs");
 var import_logger_core = require("../common/logger-core.cjs");
 const COLORS = {
   reset: "\x1B[0m",
@@ -58,7 +59,7 @@ function getCallerInfo(depth = 3) {
   const match = targetLine.match(/at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?/);
   if (!match) return "";
   const [, funcName, filePath, line] = match;
-  const fileName = filePath.split("/").pop() || filePath;
+  const fileName = (0, import_utils.fileNameOf)(filePath) || filePath;
   const func = funcName || "<anonymous>";
   return `${fileName}:${line} ${func}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipanel/core",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "type": "module",
   "sideEffects": false,
   "main": "lib/index.cjs",