@aipanel/core 1.2.9 → 1.2.11

package/lib/common/types.d.ts

@@ -2,6 +2,7 @@
  * 通用类型（Provider 无关）
  * Provider 专属类型已下沉至 @aipanel/provider-opencode。
  */
+import type { SessionPendingKind, SessionStatus } from "./provider";
 /**
  * 展示模式类型
  */
@@ -123,16 +124,27 @@ 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 交互状态（单一来源：./types.ts 定义，事件载荷类型见 ./provider.ts 的 SessionPendingKind）
+ */
+export type AIPanelSessionPendingKind = SessionPendingKind;
 /**
  * Session 思考状态
  */
 export interface AIPanelSessionThinkingState {
     thinking: boolean;
     statusType: AIPanelSessionStatusType;
+    /** 是否存在待用户交互（审批/提问/计划评审）；pending 优先级高于 thinking */
     hasPending: boolean;
+    /** 待交互类型（hasPending=true 时有值；单一来源 ./provider.ts） */
+    pendingKind?: AIPanelSessionPendingKind;
+    /** 是否刚运行完成（client 端由 running→idle 边沿且非当前选中推导；对齐官方 completed 提醒语义） */
+    completed?: boolean;
+    /** 进行中的子代理数（>0 时即使自身 idle 也视为"在跑"；源：session.subagents） */
+    subagentsRunning?: number;
 }
 /**
  * 挂件会话信息
@@ -146,19 +158,9 @@ 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;
-    /** 用户选中节点时的页面 URL（AIPanel 附加；host 端上下文注入用） */
-    previewPageUrl?: string;
-}
+export type AIPanelSelectedElement = SelectedElement;
 /**
  * 单条代码诊断（1-based 行列坐标）——AIPanel 诊断工具（run_diagnostics 等）的
  * canonical 持久化/展示共用协议：宿主插件写 tool/result.meta，client 插件据此渲染卡片。

package/lib/common/utils.cjs

@@ -21,10 +21,15 @@ __export(utils_exports, {
   base64Encode: () => base64Encode,
   ensureNodeId: () => ensureNodeId,
   extractTextFromResponse: () => extractTextFromResponse,
+  parseNodeMentions: () => parseNodeMentions,
   sleep: () => sleep,
-  truncate: () => truncate
+  toNodeMention: () => toNodeMention,
+  truncate: () => truncate,
+  widgetEnvelope: () => widgetEnvelope,
+  withRetries: () => withRetries
 });
 module.exports = __toCommonJS(utils_exports);
+var import_constants = require("./constants.cjs");
 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);
@@ -77,12 +82,52 @@ 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 ?? import_constants.DEFAULT_RETRIES;
+  const delayMs = options.delayMs ?? import_constants.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));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   base64Decode,
   base64Encode,
   ensureNodeId,
   extractTextFromResponse,
+  parseNodeMentions,
   sleep,
-  truncate
+  toNodeMention,
+  truncate,
+  widgetEnvelope,
+  withRetries
 });

package/lib/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/lib/node/diagnostics.cjs

@@ -27,6 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var diagnostics_exports = {};
 __export(diagnostics_exports, {
+  DIAGNOSTICS_TOOL_DESCRIPTION: () => DIAGNOSTICS_TOOL_DESCRIPTION,
   findAllTsconfigDirs: () => findAllTsconfigDirs,
   findTsconfigDir: () => findTsconfigDir,
   formatDiagnosticsSections: () => formatDiagnosticsSections,
@@ -59,6 +60,19 @@ const JS_EXTENSIONS = /* @__PURE__ */ new Set([
 function isJsFile(filePath) {
   return JS_EXTENSIONS.has(import_node_path.default.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;
@@ -74,7 +88,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);
@@ -122,7 +141,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;
@@ -296,6 +318,7 @@ function formatDiagnosticsSections(title, eslintOutput, tscOutput) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DIAGNOSTICS_TOOL_DESCRIPTION,
   findAllTsconfigDirs,
   findTsconfigDir,
   formatDiagnosticsSections,

package/lib/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/lib/node/node-logger.cjs

@@ -49,21 +49,6 @@ const LEVEL_COLORS = {
   [import_logger_core.LogLevel.ERROR]: COLORS.red,
   [import_logger_core.LogLevel.NONE]: COLORS.reset
 };
-const LEVEL_NAMES = {
-  [import_logger_core.LogLevel.DEBUG]: "DEBUG",
-  [import_logger_core.LogLevel.INFO]: "INFO",
-  [import_logger_core.LogLevel.WARN]: "WARN",
-  [import_logger_core.LogLevel.ERROR]: "ERROR",
-  [import_logger_core.LogLevel.NONE]: "NONE"
-};
-function getTimestamp() {
-  const now = /* @__PURE__ */ new Date();
-  const hours = String(now.getHours()).padStart(2, "0");
-  const minutes = String(now.getMinutes()).padStart(2, "0");
-  const seconds = String(now.getSeconds()).padStart(2, "0");
-  const ms = String(now.getMilliseconds()).padStart(3, "0");
-  return `${hours}:${minutes}:${seconds}.${ms}`;
-}
 function getCallerInfo(depth = 3) {
   const stack = new Error().stack;
   if (!stack) return "";
@@ -82,10 +67,10 @@ function log(level, message, context, ...args) {
   const parts = [];
   parts.push(`${COLORS.dim}[${process.pid}]${COLORS.reset}`);
   if ((0, import_logger_core.getConfig)().showTimestamp) {
-    parts.push(`${COLORS.dim}${getTimestamp()}${COLORS.reset}`);
+    parts.push(`${COLORS.dim}${(0, import_logger_core.getTimestamp)()}${COLORS.reset}`);
   }
   const levelColor = LEVEL_COLORS[level];
-  const levelName = LEVEL_NAMES[level].padEnd(5);
+  const levelName = import_logger_core.LEVEL_NAMES[level].padEnd(5);
   parts.push(`${levelColor}${levelName}${COLORS.reset}`);
   parts.push(`${COLORS.bright}${import_constants.LOG_PREFIX}${COLORS.reset}`);
   const contextStr = (0, import_logger_core.formatContext)(context);

package/lib/node/node-utils.cjs

@@ -28,15 +28,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var node_utils_exports = {};
 __export(node_utils_exports, {
   checkChromeDevToolsAvailable: () => checkChromeDevToolsAvailable,
+  checkCliInstalled: () => checkCliInstalled,
   createPackageRequire: () => createPackageRequire,
   findAvailablePort: () => findAvailablePort,
+  findGitRoot: () => findGitRoot,
+  getCliVersion: () => getCliVersion,
   isPortAvailable: () => isPortAvailable,
-  resolvePackageDir: () => resolvePackageDir
+  killOrphanCliProcesses: () => killOrphanCliProcesses,
+  resolvePackageDir: () => resolvePackageDir,
+  waitForServer: () => waitForServer
 });
 module.exports = __toCommonJS(node_utils_exports);
+var import_node_child_process = require("node:child_process");
 var import_node_module = require("node:module");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_http = __toESM(require("node:http"));
 var import_node_path = __toESM(require("node:path"));
 var import_constants = require("../common/constants.cjs");
+var import_node_logger = require("./node-logger.cjs");
+const log = (0, import_node_logger.createLogger)("NodeUtils");
 function createPackageRequire(baseDir = process.cwd()) {
   return (0, import_node_module.createRequire)(import_node_path.default.join(baseDir, "package.json"));
 }
@@ -83,11 +93,237 @@ async function findAvailablePort(startPort, hostname, maxTries = 100) {
   }
   throw new Error(`No available port in range ${startPort}-${startPort + maxTries}`);
 }
+function waitForServer(url, timeout = 1e4, proc) {
+  const timer = new import_node_logger.PerformanceTimer("waitForServer", { url, timeout });
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    let attempts = 0;
+    const check = () => {
+      attempts++;
+      log.debug(`Checking server availability (attempt ${attempts})`, { url });
+      if (proc?.exitCode !== null && proc?.exitCode !== void 0) {
+        timer.end(`\u2716 Process exited with code ${proc.exitCode}`);
+        reject(new Error(`Process exited with code ${proc.exitCode}`));
+        return;
+      }
+      const req = import_node_http.default.get(url, (res) => {
+        if (res.statusCode && res.statusCode < 500) {
+          timer.end(`\u2713 Server ready after ${attempts} attempts`);
+          resolve();
+        } else {
+          log.debug(`Server returned status ${res.statusCode}, retrying...`);
+          retryOrReject();
+        }
+      });
+      req.on("error", (err) => {
+        log.debug(`Server check failed: ${err.message}`);
+        retryOrReject();
+      });
+    };
+    const retryOrReject = () => {
+      const elapsed = Date.now() - startTime;
+      if (elapsed < timeout) {
+        setTimeout(check, import_constants.SERVER_CHECK_INTERVAL);
+      } else {
+        timer.end("\u2716 Timeout");
+        reject(new Error(`Server not ready after ${timeout}ms (${attempts} attempts)`));
+      }
+    };
+    check();
+  });
+}
+function findGitRoot(startDir, maxDepth = 10) {
+  const timer = new import_node_logger.PerformanceTimer("findGitRoot", { startDir, maxDepth });
+  let currentDir = startDir;
+  let depth = 0;
+  while (depth < maxDepth) {
+    const gitDir = import_node_path.default.join(currentDir, ".git");
+    try {
+      if (import_node_fs.default.existsSync(gitDir)) {
+        timer.end(`\u2713 Found git root at depth ${depth}: ${currentDir}`);
+        return currentDir;
+      }
+    } catch (err) {
+      log.debug(`Error checking .git directory at ${currentDir}`, {
+        error: err.message
+      });
+    }
+    const parentDir = import_node_path.default.dirname(currentDir);
+    if (parentDir === currentDir) {
+      log.debug("Reached filesystem root");
+      break;
+    }
+    currentDir = parentDir;
+    depth++;
+  }
+  timer.end(`\u2716 No git root found after ${depth} levels, using start directory`);
+  return startDir;
+}
+async function checkCliInstalled(bin) {
+  const timer = new import_node_logger.PerformanceTimer(`checkCliInstalled:${bin}`);
+  return new Promise((resolve) => {
+    const proc = (0, import_node_child_process.spawn)(bin, ["--version"], { stdio: "ignore", shell: true });
+    proc.on("close", (code) => {
+      const installed = code === 0;
+      timer.end(installed ? `\u2713 ${bin} is installed` : `\u2716 ${bin} not found`);
+      resolve(installed);
+    });
+    proc.on("error", (err) => {
+      log.debug(`Failed to check ${bin} installation`, { error: err.message });
+      timer.end("\u2716 Check failed");
+      resolve(false);
+    });
+  });
+}
+function getCliVersion(bin) {
+  return new Promise((resolve) => {
+    const proc = (0, import_node_child_process.spawn)(bin, ["--version"], { stdio: "pipe", shell: true });
+    let output = "";
+    proc.stdout?.on("data", (data) => {
+      output += data.toString();
+    });
+    proc.on("close", (code) => {
+      resolve(code === 0 && output.trim() ? output.trim() : null);
+    });
+    proc.on("error", () => resolve(null));
+  });
+}
+function killOrphanCliProcesses(bin, options) {
+  const label = options.label ?? bin;
+  const timeoutMs = options.timeout ?? 5e3;
+  const timer = new import_node_logger.PerformanceTimer(`killOrphanCliProcesses:${label}`);
+  log.debug(`Looking for orphan ${label} processes (PPID=1)`);
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (count) => {
+      if (!settled) {
+        settled = true;
+        resolve(count);
+      }
+    };
+    const timeout = setTimeout(() => {
+      log.warn(`Kill orphan ${label} processes timed out, skipping`);
+      timer.end("\u26A0 Timeout, skipped");
+      done(0);
+    }, timeoutMs);
+    const wrappedResolve = (count) => {
+      clearTimeout(timeout);
+      done(count);
+    };
+    if (process.platform === "win32") {
+      killOrphansOnWindows(wrappedResolve, options, label, timer);
+    } else {
+      killOrphansOnUnix(wrappedResolve, options, label, timer);
+    }
+  });
+}
+function killOrphansOnWindows(resolve, options, label, timer) {
+  log.debug(`Using Windows method to find orphan ${label} processes`);
+  const proc = (0, import_node_child_process.spawn)(
+    "wmic",
+    ["process", "where", `name="${options.winName}"`, "get", "processid,parentprocessid,commandline"],
+    { stdio: "pipe" }
+  );
+  let output = "";
+  proc.stdout?.on("data", (data) => {
+    output += data.toString();
+  });
+  proc.on("close", () => {
+    const pidsToKill = [];
+    output.split("\n").forEach((rawLine) => {
+      const line = rawLine.trim();
+      if (!line.includes(options.match)) return;
+      const parts = line.split(/\s+/);
+      if (parts.length >= 3) {
+        const ppid = parts[0];
+        const pid = parts[1];
+        if (ppid === "1" && pid && !Number.isNaN(Number(pid))) pidsToKill.push(pid);
+      }
+    });
+    finishOrphanKillWindows(pidsToKill, resolve, label, timer);
+  });
+  proc.on("error", (err) => {
+    log.debug(`Failed to find orphan ${label} processes`, { error: err.message });
+    timer.end("\u2716 Failed to find orphan processes");
+    resolve(0);
+  });
+}
+function finishOrphanKillWindows(pidsToKill, resolve, label, timer) {
+  if (pidsToKill.length === 0) {
+    log.debug("No orphan processes found");
+    timer.end("No orphan processes found");
+    resolve(0);
+    return;
+  }
+  log.debug(`Found ${pidsToKill.length} orphan processes`, { pids: pidsToKill });
+  let killedCount = 0;
+  let completedCount = 0;
+  pidsToKill.forEach((pid) => {
+    const killProc = (0, import_node_child_process.spawn)("taskkill", ["/F", "/PID", pid], { stdio: "ignore" });
+    killProc.on("close", (code) => {
+      completedCount++;
+      if (code === 0) killedCount++;
+      if (completedCount === pidsToKill.length) {
+        timer.end(`\u2713 Killed ${killedCount} orphan ${label} processes`);
+        resolve(killedCount);
+      }
+    });
+  });
+}
+function killOrphansOnUnix(resolve, options, label, timer) {
+  log.debug(`Using Unix method to find orphan ${label} processes`);
+  const proc = (0, import_node_child_process.spawn)("ps", ["-e", "-o", "pid,ppid,args"], { stdio: "pipe" });
+  let output = "";
+  proc.stdout?.on("data", (data) => {
+    output += data.toString();
+  });
+  proc.on("close", () => {
+    const pidsToKill = [];
+    output.split("\n").forEach((line) => {
+      if (!line.includes(options.match)) return;
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 3) {
+        const pid = parts[0];
+        const ppid = parts[1];
+        if (ppid === "1" && pid && !Number.isNaN(Number(pid))) pidsToKill.push(pid);
+      }
+    });
+    if (pidsToKill.length === 0) {
+      log.debug("No orphan processes found");
+      timer.end("No orphan processes found");
+      resolve(0);
+      return;
+    }
+    log.debug(`Found ${pidsToKill.length} orphan processes`, { pids: pidsToKill });
+    const killProc = (0, import_node_child_process.spawn)("kill", ["-9", ...pidsToKill], { stdio: "ignore" });
+    killProc.on("close", (code) => {
+      const killedCount = code === 0 ? pidsToKill.length : 0;
+      timer.end(
+        killedCount > 0 ? `\u2713 Killed ${killedCount} orphan ${label} processes` : "\u2716 Failed to kill processes"
+      );
+      resolve(killedCount);
+    });
+    killProc.on("error", () => {
+      timer.end("\u2716 Failed to kill processes");
+      resolve(0);
+    });
+  });
+  proc.on("error", (err) => {
+    log.debug(`Failed to find orphan ${label} processes`, { error: err.message });
+    timer.end("\u2716 Failed to find orphan processes");
+    resolve(0);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   checkChromeDevToolsAvailable,
+  checkCliInstalled,
   createPackageRequire,
   findAvailablePort,
+  findGitRoot,
+  getCliVersion,
   isPortAvailable,
-  resolvePackageDir
+  killOrphanCliProcesses,
+  resolvePackageDir,
+  waitForServer
 });

package/lib/node/node-utils.d.ts

@@ -26,3 +26,44 @@ export declare function isPortAvailable(port: number, hostname?: string): Promis
  * 从 startPort 开始寻找可用端口
  */
 export declare function findAvailablePort(startPort: number, hostname?: string, maxTries?: number): Promise<number>;
+/**
+ * 可等待的进程接口（ResultPromise 等匹配就够）
+ */
+export interface WaitableProcess {
+    exitCode: number | null | undefined;
+}
+/**
+ * 轮询等待服务准备就绪（HTTP 状态码 < 500 即当作 ready）；超时或进程退出时 reject
+ * @param url - 检查的服务 URL
+ * @param timeout - 超时毫秒数
+ * @param proc - 可选进程，提前退出时直接失败
+ */
+export declare function waitForServer(url: string, timeout?: number, proc?: WaitableProcess): Promise<void>;
+/**
+ * 从指定目录往上查找 .git 根目录（找不到时返回起始目录）
+ */
+export declare function findGitRoot(startDir: string, maxDepth?: number): string;
+/**
+ * 检查某 CLI 是否安装（运行 <bin> --version，退出码 0 即存在）
+ */
+export declare function checkCliInstalled(bin: string): Promise<boolean>;
+/**
+ * 获取某 CLI 版本号（<bin> --version 的第一行，败路返回 null）
+ */
+export declare function getCliVersion(bin: string): Promise<string | null>;
+/** 孤儿进程清理配置（提供商的 check/kill 统一实现） */
+export interface KillOrphanCliOptions {
+    /** 进程命令行/参数中需匹配的子串（如 opencode / dsh） */
+    match: string;
+    /** Windows wmic 按名称查询的进程名（如 opencode.exe / node.exe） */
+    winName: string;
+    /** 超时毫秒（默认 5000） */
+    timeout?: number;
+    /** 运行名（仅用于日志，默认等于 match） */
+    label?: string;
+}
+/**
+ * 清理被 reparent 到 init（PPID=1）的孤儿进程（win: wmic+taskkill；unix: ps+kill）
+ * @returns 被成功结束的进程数
+ */
+export declare function killOrphanCliProcesses(bin: string, options: KillOrphanCliOptions): Promise<number>;

package/package.json

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