ppxans-harness 2.6.0 → 3.2.1

package/src/llm/pricing.js

@@ -0,0 +1,93 @@
+// src/llm/pricing.js - 模型价格表 + 成本折算 (增强框架第 8 条: "预算控制"的最后一环)
+// 背景: usageStats 已聚合 token 数 (calls/tokens/byModel), 但没有金额折算与支出上限 —— 
+//       token 数不等于成本, 不同模型价差 100 倍, "预算控制"必须落在金额上。
+// 设计:
+//   - 内置常用模型价格表 (USD / 1M tokens, prompt + completion), 前缀匹配取最长者
+//   - 云厂商价格随时变动: 内置表只是"开箱即用的估算快照", 精确控费用 config.budget.model_prices 覆盖
+//   - 未知模型 → 返回 null (cost 记 0), **不编数字**; 想纳入预算控制就显式配置价格
+//   - 只有 total_tokens 无拆分时, 全部按 completion 价计 (预算取保守侧, 宁高估不高估)
+// 零依赖, 纯函数, 可独立测试。
+
+// USD per 1M tokens。数字为各厂商公开目录价的历史快照 (2026-10), 仅供预算估算。
+// 匹配规则: model 小写后按前缀匹配, 取最长命中 (如 glm-4-flash 命中 flash 行而非 glm-4 行)。
+const PRICES = [
+  // 智谱
+  { prefix: "glm-4-flash", prompt: 0, completion: 0 },      // 免费档
+  { prefix: "glm-4.5", prompt: 0.6, completion: 2.2 },
+  { prefix: "glm-4.6", prompt: 0.6, completion: 2.2 },
+  { prefix: "glm-4", prompt: 0.5, completion: 1.5 },
+  // DeepSeek
+  { prefix: "deepseek-chat", prompt: 0.27, completion: 1.1 },
+  { prefix: "deepseek-reasoner", prompt: 0.55, completion: 2.19 },
+  // OpenAI
+  { prefix: "gpt-4o-mini", prompt: 0.15, completion: 0.6 },
+  { prefix: "gpt-4o", prompt: 2.5, completion: 10 },
+  { prefix: "gpt-4.1-mini", prompt: 0.4, completion: 1.6 },
+  { prefix: "gpt-4.1", prompt: 2, completion: 8 },
+  // Anthropic (前缀族: 3.x 与 4.x 同档从宽)
+  { prefix: "claude-opus", prompt: 15, completion: 75 },
+  { prefix: "claude-sonnet", prompt: 3, completion: 15 },
+  { prefix: "claude-haiku", prompt: 1, completion: 5 },
+  // Gemini
+  { prefix: "gemini-2.5-pro", prompt: 1.25, completion: 10 },
+  { prefix: "gemini-2.5-flash", prompt: 0.3, completion: 2.5 },
+  // 阿里 / 月之暗面
+  { prefix: "qwen-flash", prompt: 0.05, completion: 0.4 },
+  { prefix: "qwen-plus", prompt: 0.4, completion: 1.2 },
+  { prefix: "qwen-max", prompt: 1.6, completion: 6.4 },
+  { prefix: "kimi-k2", prompt: 0.6, completion: 2.5 },
+];
+
+// 规范化一条价格: {prompt, completion} 均为非负有限数字, 否则视为无效 (返回 null)
+function normPrice(v) {
+  if (!v || typeof v !== "object") return null;
+  const p = Number(v.prompt), c = Number(v.completion);
+  if (!Number.isFinite(p) || !Number.isFinite(c) || p < 0 || c < 0) return null;
+  return { prompt: p, completion: c };
+}
+
+// 解析某模型的价格。overrides: config.budget?.model_prices, 形如
+//   { "glm-4-flash": { prompt: 0, completion: 0 }, "my-private-model": { prompt: 1, completion: 3 } }
+// 优先级: overrides 精确命中 > overrides 前缀命中(最长) > 内置表前缀命中(最长) > null
+export function resolvePrice(model, overrides) {
+  const m = String(model || "").toLowerCase().trim();
+  if (!m) return null;
+  if (overrides && typeof overrides === "object" && !Array.isArray(overrides)) {
+    // 精确命中最优先
+    const exact = normPrice(overrides[m]) || normPrice(overrides[String(model || "").trim()]);
+    if (exact) return exact;
+    // 前缀命中取最长
+    let best = null, bestLen = -1;
+    for (const k of Object.keys(overrides)) {
+      const kk = String(k).toLowerCase();
+      if (kk && m.startsWith(kk) && kk.length > bestLen) {
+        const v = normPrice(overrides[k]);
+        if (v) { best = v; bestLen = kk.length; }
+      }
+    }
+    if (best) return best;
+  }
+  let hit = null, hitLen = -1;
+  for (const e of PRICES) {
+    if (m.startsWith(e.prefix) && e.prefix.length > hitLen) { hit = e; hitLen = e.prefix.length; }
+  }
+  return hit ? { prompt: hit.prompt, completion: hit.completion } : null;
+}
+
+// 折算一笔 usage 的成本 (USD)。usage: { prompt_tokens, completion_tokens } 或仅 { total_tokens }。
+// 无价格 → 0 (调用方无从区分"免费"与"未知", 需要区分时自行调 resolvePrice)。
+export function estimateCost(model, usage, overrides) {
+  const p = resolvePrice(model, overrides);
+  if (!p) return 0;
+  const pt = usage?.prompt_tokens, ct = usage?.completion_tokens;
+  let prompt, completion;
+  if (pt == null && ct == null) {
+    // 只有总量 (部分本地推理后端不拆分): 全按 completion 价计 —— 预算保守侧
+    prompt = 0;
+    completion = Number(usage?.total_tokens) || 0;
+  } else {
+    prompt = Number(pt) || 0;
+    completion = Number(ct) || 0;
+  }
+  return (prompt * p.prompt + completion * p.completion) / 1e6;
+}

package/src/llm/retry.js

@@ -1,73 +1,73 @@
-// src/llm/retry.js - 错误重试内核 (吸收 OpenClaw retry/operation-retry 精华)
-// 设计要点:
-//  - 瞬态分类: 429/5xx/timeout/网络错误 才重试; 400/401/403/404 等客户端错误立即失败
-//  - 指数退避 + full jitter (避免惊群); 尊重 Retry-After 头
-//  - 可取消 (AbortSignal)
-//  - LLM 失败不 throw 的契约由上层 (provider 回退) 承担, 本模块只负责"单次调用内"的重试
-
-// 从错误对象/消息提取 HTTP 状态码
-export function httpStatusOf(err) {
-  if (!err) return null;
-  if (typeof err.status === "number") return err.status;
-  if (typeof err.statusCode === "number") return err.statusCode;
-  const m = String(err.message || err).match(/\b(4\d\d|5\d\d)\b/);
-  return m ? Number(m[1]) : null;
-}
-
-// 瞬态分类: 值得重试的错误 (openclaw operation-retry: 429/5xx/ENOTFOUND/timeout/fetch failed)
-export function isTransientError(err) {
-  // v1.0.9: AbortError (用户主动取消 / 内部超时中止) 一律不重试 — 原把 message "aborted" 判瞬态, 取消后仍退避重试
-  if (err && (err.name === "AbortError" || err.code === "ABORT_ERR")) return false;
-  const status = httpStatusOf(err);
-  if (status) {
-    if (status === 429 || status >= 500) return true;
-    if (status >= 400 && status < 500) return false; // 客户端错误不重试
-  }
-  const msg = String(err?.message || err || "");
-  if (/timeout|timed?\s*out|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|fetch failed|network|socket hang up|undici/i.test(msg)) return true;
-  return false;
-}
-
-// Retry-After (秒), 无则 null (上限 30s 防恶意长退避)
-export function retryAfterSeconds(err) {
-  const raw = err?.headers?.get?.("retry-after") ?? err?.retryAfter ?? err?.retry_after;
-  const n = Number(raw);
-  if (Number.isFinite(n) && n > 0) return Math.min(n, 30);
-  return null;
-}
-
-// 指数退避 + full jitter
-export function backoffMs(attempt, { baseMs = 500, factor = 2, maxMs = 10000 } = {}) {
-  const exp = Math.min(maxMs, baseMs * Math.pow(factor, attempt));
-  return Math.floor(exp * (0.5 + Math.random() * 0.5));
-}
-
-// 可取消 sleep (AbortSignal)
-export function sleep(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(abortError());
-    const t = setTimeout(() => { cleanup(); resolve(); }, ms);
-    const onAbort = () => { clearTimeout(t); cleanup(); reject(abortError()); };
-    if (signal) signal.addEventListener("abort", onAbort, { once: true });
-    function cleanup() { if (signal) signal.removeEventListener("abort", onAbort); }
-  });
-}
-
-function abortError() { const e = new Error("aborted"); e.name = "AbortError"; return e; }
-
-// 重试执行器: fn 抛瞬态错误时按退避重试, 非瞬态直接抛
-export async function withRetry(fn, { maxRetries = 3, baseMs = 500, factor = 2, maxMs = 10000, signal = null, shouldRetry = isTransientError } = {}) {
-  let lastErr;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (e) {
-      lastErr = e;
-      if (attempt >= maxRetries || !shouldRetry(e)) throw e;
-      const ra = retryAfterSeconds(e);
-      const ms = ra != null ? ra * 1000 : backoffMs(attempt, { baseMs, factor, maxMs });
-      await sleep(ms, signal);
-    }
-  }
-  throw lastErr;
-}
+// src/llm/retry.js - 错误重试内核 (吸收 OpenClaw retry/operation-retry 精华)
+// 设计要点:
+//  - 瞬态分类: 429/5xx/timeout/网络错误 才重试; 400/401/403/404 等客户端错误立即失败
+//  - 指数退避 + full jitter (避免惊群); 尊重 Retry-After 头
+//  - 可取消 (AbortSignal)
+//  - LLM 失败不 throw 的契约由上层 (provider 回退) 承担, 本模块只负责"单次调用内"的重试
+
+// 从错误对象/消息提取 HTTP 状态码
+export function httpStatusOf(err) {
+  if (!err) return null;
+  if (typeof err.status === "number") return err.status;
+  if (typeof err.statusCode === "number") return err.statusCode;
+  const m = String(err.message || err).match(/\b(4\d\d|5\d\d)\b/);
+  return m ? Number(m[1]) : null;
+}
+
+// 瞬态分类: 值得重试的错误 (openclaw operation-retry: 429/5xx/ENOTFOUND/timeout/fetch failed)
+export function isTransientError(err) {
+  // v1.0.9: AbortError (用户主动取消 / 内部超时中止) 一律不重试 — 原把 message "aborted" 判瞬态, 取消后仍退避重试
+  if (err && (err.name === "AbortError" || err.code === "ABORT_ERR")) return false;
+  const status = httpStatusOf(err);
+  if (status) {
+    if (status === 429 || status >= 500) return true;
+    if (status >= 400 && status < 500) return false; // 客户端错误不重试
+  }
+  const msg = String(err?.message || err || "");
+  if (/timeout|timed?\s*out|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|fetch failed|network|socket hang up|undici/i.test(msg)) return true;
+  return false;
+}
+
+// Retry-After (秒), 无则 null (上限 30s 防恶意长退避)
+export function retryAfterSeconds(err) {
+  const raw = err?.headers?.get?.("retry-after") ?? err?.retryAfter ?? err?.retry_after;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n > 0) return Math.min(n, 30);
+  return null;
+}
+
+// 指数退避 + full jitter
+export function backoffMs(attempt, { baseMs = 500, factor = 2, maxMs = 10000 } = {}) {
+  const exp = Math.min(maxMs, baseMs * Math.pow(factor, attempt));
+  return Math.floor(exp * (0.5 + Math.random() * 0.5));
+}
+
+// 可取消 sleep (AbortSignal)
+export function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError());
+    const t = setTimeout(() => { cleanup(); resolve(); }, ms);
+    const onAbort = () => { clearTimeout(t); cleanup(); reject(abortError()); };
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+    function cleanup() { if (signal) signal.removeEventListener("abort", onAbort); }
+  });
+}
+
+function abortError() { const e = new Error("aborted"); e.name = "AbortError"; return e; }
+
+// 重试执行器: fn 抛瞬态错误时按退避重试, 非瞬态直接抛
+export async function withRetry(fn, { maxRetries = 3, baseMs = 500, factor = 2, maxMs = 10000, signal = null, shouldRetry = isTransientError } = {}) {
+  let lastErr;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      lastErr = e;
+      if (attempt >= maxRetries || !shouldRetry(e)) throw e;
+      const ra = retryAfterSeconds(e);
+      const ms = ra != null ? ra * 1000 : backoffMs(attempt, { baseMs, factor, maxMs });
+      await sleep(ms, signal);
+    }
+  }
+  throw lastErr;
+}

package/src/llm/router.js

@@ -1,90 +1,93 @@
-// src/llm/router.js - 模型路由 (provider 选择中枢, 唯一真相源, 自研底座)
-// 目标: "本地默认优先, 云端可自由接入"
-//   - 占位死配置过滤: model 含 REPLACE_WITH_YOUR_ENDPOINT 等占位符的 provider 视为不可用(省得误选+报噪音警告)
-//   - 本地优先(默认): 本地测试直接用本地模型 (lmstudio/ollama, 127.0.0.1 即零配置可用), 配真实云端 key 也先走本地
-//   - 云端优先(可选): 设 agent.model_preference=cloud → 配真 key 的云端排前 (深度/智谱/千问/火山/OpenAI), 本地兜底
-//   - 健康排序: 启动时异步探测各 provider /models, 能连的排前, 连不上自动降级
-// 全部 provider 均为自研 http 底座 (OpenAI 兼容 API 直连), 无外部引擎依赖。
-// 用法 (与旧 builtin.resolveLLM 同签名, 向后兼容):
-//   const llm = resolveLLM(config);            // 同步选择主 LLM
-//   const all = resolveAllLLMs(config);        // 全量可用 provider
-//   const ok  = isUsableProvider(prov);         // 是否可用(过滤占位符)
-//   const candid = await orderByHealth(all);    // 异步健康排序(可选, 给启动探测用)
-import { LLMClient } from "./client.js";
-
-// 占位符识别: 用户没填的 model/endpoint/key 标记 (OpenAI-cli 模板常留 REPLACE_WITH_YOUR_*)
-const PLACEHOLDER_RE = /REPLACE_WITH_YOUR_|YOUR_ENDPOINT|YOUR_API_KEY|sk-xxx|<your_/i;
-// 本地推理服务地址特征
-const LOCAL_HOST_RE = /127\.0\.0\.1|localhost|lm-studio|ollama/i;
-
-function hasRealKey(p) {
-  // 显式 api_key 且非占位 -> 真 key
-  if (p.api_key && !PLACEHOLDER_RE.test(String(p.api_key))) return true;
-  // env 引用且 env 里设了非空值 -> 真 key
-  if (p.api_key_env && process.env[p.api_key_env]) {
-    const v = String(process.env[p.api_key_env]);
-    return !!v && !PLACEHOLDER_RE.test(v);
-  }
-  return false;
-}
-
-function isLocal(p) {
-  return LOCAL_HOST_RE.test(String(p.base_url || ""));
-}
-
-// 占位符过滤 + 可用判定 (与旧 isUsableProvider 同语义, 增加占位符排除)
-export function isUsableProvider(prov) {
-  if (!prov) return false;
-  // 占位 model 的死配置直接判不可用 (volcengine 的 REPLACE_WITH_YOUR_ENDPOINT 等)
-  if (PLACEHOLDER_RE.test(String(prov.model || ""))) return false;
-  if (hasRealKey(prov)) return true;          // 云端真 key
-  if (isLocal(prov)) return true;              // 本地推理零配置可用
-  return false;
-}
-
-// 排序: 按 agent.model_preference 决定本地/云端谁优先 (默认 local)
-//   - local:  本地优先(lmstudio/ollama) > 云端真key   [本地测试默认]
-//   - cloud:  云端真key优先 > 本地兜底              [正式发布可配]
-// 健康状态排序由 orderByHealth 异步完成; 这里是"无探测时代理"的基础排序
-function orderProviders(provs, preference) {
-  const cloud = provs.filter((p) => hasRealKey(p) && !isLocal(p));
-  const local = provs.filter((p) => isLocal(p)); // 本地服务都收 (lmstudio 常带字面 api_key, 仍零配置)
-  return preference === "cloud" ? [...cloud, ...local] : [...local, ...cloud];
-}
-
-export function resolvePreference(config) {
-  return (config?.agent?.model_preference === "cloud") ? "cloud" : "local";
-}
-
-export function resolveAllLLMs(config) {
-  const provs = (config && config.providers) || [];
-  const pref = resolvePreference(config);
-  return orderProviders(provs.filter(isUsableProvider), pref).map((p) => new LLMClient(p));
-}
-
-export function resolveLLM(config) {
-  const provs = (config && config.providers) || [];
-  // 强制指定: PPX_PROVIDER=<id> (测试/用户显式选择)
-  const forced = process.env.PPX_PROVIDER;
-  if (forced) {
-    const t = provs.find((x) => x.id === forced || x.id === String(forced).toLowerCase());
-    if (t && isUsableProvider(t)) return new LLMClient(t);
-  }
-  const pref = resolvePreference(config);
-  const ordered = orderProviders(provs.filter(isUsableProvider), pref);
-  return ordered.length ? new LLMClient(ordered[0]) : null;
-}
-
-// 异步健康排序: 启动时探测各候选 /models, 能连的排前 (只读, 不改配置)
-// returns: [{ client, health }] 按健康排序; 全部失败则保持原顺序 (兜底不报死)
-export async function orderByHealth(clients, { probeMs = 4000 } = {}) {
-  if (!clients || !clients.length) return [];
-  const states = await Promise.all(clients.map(async (c) => {
-    try { return { client: c, ok: typeof c.health === "function" ? await c.health() : true }; }
-    catch { return { client: c, ok: false }; }
-  }));
-  const healthy = states.filter((s) => s.ok).map((s) => s.client);
-  const unwell = states.filter((s) => !s.ok).map((s) => s.client);
-  // 健康的保持原云/本地顺序, 不健康排最后 (不丢弃, 让运行时 fallback 继续尝试)
-  return [...healthy, ...unwell];
+// src/llm/router.js - 模型路由 (provider 选择中枢, 唯一真相源, 自研底座)
+// 目标: "本地默认优先, 云端可自由接入"
+//   - 占位死配置过滤: model 含 REPLACE_WITH_YOUR_ENDPOINT 等占位符的 provider 视为不可用(省得误选+报噪音警告)
+//   - 本地优先(默认): 本地测试直接用本地模型 (lmstudio/ollama, 127.0.0.1 即零配置可用), 配真实云端 key 也先走本地
+//   - 云端优先(可选): 设 agent.model_preference=cloud → 配真 key 的云端排前 (深度/智谱/千问/火山/OpenAI), 本地兜底
+//   - 健康排序: 启动时异步探测各 provider /models, 能连的排前, 连不上自动降级
+// 全部 provider 均为自研 http 底座 (OpenAI 兼容 API 直连), 无外部引擎依赖。
+// 用法 (与旧 builtin.resolveLLM 同签名, 向后兼容):
+//   const llm = resolveLLM(config);            // 同步选择主 LLM
+//   const all = resolveAllLLMs(config);        // 全量可用 provider
+//   const ok  = isUsableProvider(prov);         // 是否可用(过滤占位符)
+//   const candid = await orderByHealth(all);    // 异步健康排序(可选, 给启动探测用)
+import { LLMClient } from "./client.js";
+// 占位符判定收敛到 config/placeholder.js (唯一真相源) —— v1.0.8 修复 P2-3:
+// 原先此处自带一份正则且漏了 `YOUR_*_MODEL` 形态, 导致模板里的 lmstudio
+// (model=YOUR_LOCAL_MODEL_NAME, base_url=127.0.0.1) 被判为"零配置可用"并选为主模型。
+import { isPlaceholder } from "../config/placeholder.js";
+
+// 本地推理服务地址特征
+const LOCAL_HOST_RE = /127\.0\.0\.1|localhost|lm-studio|ollama/i;
+
+function hasRealKey(p) {
+  // 显式 api_key 且非占位 -> 真 key
+  if (p.api_key && !isPlaceholder(String(p.api_key))) return true;
+  // env 引用且 env 里设了非空值 -> 真 key
+  if (p.api_key_env && process.env[p.api_key_env]) {
+    const v = String(process.env[p.api_key_env]);
+    return !!v && !isPlaceholder(v);
+  }
+  return false;
+}
+
+function isLocal(p) {
+  return LOCAL_HOST_RE.test(String(p.base_url || ""));
+}
+
+// 占位符过滤 + 可用判定 (与旧 isUsableProvider 同语义, 增加占位符排除)
+export function isUsableProvider(prov) {
+  if (!prov) return false;
+  // 占位 model/base_url 的死配置直接判不可用
+  // (volcengine 的 REPLACE_WITH_YOUR_ENDPOINT, 以及模板里 lmstudio 的 YOUR_LOCAL_MODEL_NAME)
+  if (isPlaceholder(prov.model) || isPlaceholder(prov.base_url)) return false;
+  if (hasRealKey(prov)) return true;          // 云端真 key
+  if (isLocal(prov)) return true;              // 本地推理零配置可用
+  return false;
+}
+
+// 排序: 按 agent.model_preference 决定本地/云端谁优先 (默认 local)
+//   - local:  本地优先(lmstudio/ollama) > 云端真key   [本地测试默认]
+//   - cloud:  云端真key优先 > 本地兜底              [正式发布可配]
+// 健康状态排序由 orderByHealth 异步完成; 这里是"无探测时代理"的基础排序
+function orderProviders(provs, preference) {
+  const cloud = provs.filter((p) => hasRealKey(p) && !isLocal(p));
+  const local = provs.filter((p) => isLocal(p)); // 本地服务都收 (lmstudio 常带字面 api_key, 仍零配置)
+  return preference === "cloud" ? [...cloud, ...local] : [...local, ...cloud];
+}
+
+export function resolvePreference(config) {
+  return (config?.agent?.model_preference === "cloud") ? "cloud" : "local";
+}
+
+export function resolveAllLLMs(config) {
+  const provs = (config && config.providers) || [];
+  const pref = resolvePreference(config);
+  return orderProviders(provs.filter(isUsableProvider), pref).map((p) => new LLMClient(p));
+}
+
+export function resolveLLM(config) {
+  const provs = (config && config.providers) || [];
+  // 强制指定: PPX_PROVIDER=<id> (测试/用户显式选择)
+  const forced = process.env.PPX_PROVIDER;
+  if (forced) {
+    const t = provs.find((x) => x.id === forced || x.id === String(forced).toLowerCase());
+    if (t && isUsableProvider(t)) return new LLMClient(t);
+  }
+  const pref = resolvePreference(config);
+  const ordered = orderProviders(provs.filter(isUsableProvider), pref);
+  return ordered.length ? new LLMClient(ordered[0]) : null;
+}
+
+// 异步健康排序: 启动时探测各候选 /models, 能连的排前 (只读, 不改配置)
+// returns: [{ client, health }] 按健康排序; 全部失败则保持原顺序 (兜底不报死)
+export async function orderByHealth(clients, { probeMs = 4000 } = {}) {
+  if (!clients || !clients.length) return [];
+  const states = await Promise.all(clients.map(async (c) => {
+    try { return { client: c, ok: typeof c.health === "function" ? await c.health() : true }; }
+    catch { return { client: c, ok: false }; }
+  }));
+  const healthy = states.filter((s) => s.ok).map((s) => s.client);
+  const unwell = states.filter((s) => !s.ok).map((s) => s.client);
+  // 健康的保持原云/本地顺序, 不健康排最后 (不丢弃, 让运行时 fallback 继续尝试)
+  return [...healthy, ...unwell];
 }

package/src/mcp/admin.js

@@ -8,7 +8,7 @@ import {
 import { getSettings, updateSettings } from "../config/settings.js";
 import { createTaskBoard } from "./tasks.js";
 import { ensureDir } from "../utils/store.js";
-import { warn } from "../utils/logger.js";
+import { warn, debug } from "../utils/logger.js";
 import path from "node:path";
 
 // 任务面板技能模板库: 按技能预置步骤列表, 新建任务时可选 (供 web 前端渲染下拉)
@@ -79,7 +79,7 @@ export const TASK_TEMPLATES = [
 // 写配置前确保 config 目录存在 (空 root / 首次启动时 agent 自愈建目录是异步的,
 // 若目录缺失, withFileLock 的 openSync(wx) 抛 ENOENT 会被误判为"锁冲突"并超时)
 function ensureConfigDir(root) {
-  try { ensureDir(path.join(root, "config")); } catch {}
+  try { ensureDir(path.join(root, "config")); } catch (e) { debug(`[mcp/admin] 已忽略异常: ${e && e.message ? e.message : e}`); }
 }
 
 const str = (v, d = "") => (v == null ? d : String(v));
@@ -101,12 +101,26 @@ function wrap(fn) {
  * @param {object} agent - PPXAgent 实例
  * @returns {{ tools: object[], taskBoard: object }}
  */
+// 2026-09-18 重构: 原先是一个 189 行的方法体, 内含 20 个工具定义字面量。
+//   现按「会话 / 提供方 / 设置 / 任务」四个域拆成独立工厂函数, 每个域可单独阅读与修改;
+//   createAdminTools 的签名与返回结构 ({ tools, taskBoard }) 完全不变。
 export function createAdminTools(agent) {
   const root = agent.root;
   const taskBoard = createTaskBoard(root);
+  return {
+    tools: [
+      ...sessionTools(agent),
+      ...providerTools(agent, root),
+      ...settingsTools(agent, root),
+      ...taskTools(agent, taskBoard),
+    ],
+    taskBoard,
+  };
+}
 
-  const tools = [
-    // ---- 会话管理 ----
+// ---- 域 1: 会话管理 (5 个工具) ----
+function sessionTools(agent) {
+  return [
     {
       name: "ppx.sessions.list",
       title: "会话列表",
@@ -143,7 +157,12 @@ export function createAdminTools(agent) {
       execute: wrap((args) => { agent.resetSession(String(args.sessionId || "default")); return { ok: true }; }),
     },
 
-    // ---- 提供方 CRUD (模型配置) ----
+  ];
+}
+
+// ---- 域 2: 提供方 CRUD (模型配置, 6 个工具) ----
+function providerTools(agent, root) {
+  return [
     {
       name: "ppx.providers.list",
       title: "模型提供方列表",
@@ -206,7 +225,12 @@ export function createAdminTools(agent) {
       execute: wrap(async (args) => { ensureConfigDir(root); const providers = reorderProviders(root, args.order || []); agent.reloadProviders(); return { ok: true, providers }; }),
     },
 
-    // ---- 设置 ----
+  ];
+}
+
+// ---- 域 3: 设置读写 (2 个工具) ----
+function settingsTools(agent, root) {
+  return [
     {
       name: "ppx.settings.get",
       title: "读取设置",
@@ -222,7 +246,12 @@ export function createAdminTools(agent) {
       execute: wrap(async (args) => { ensureConfigDir(root); const settings = updateSettings(root, args.patch || {}); agent.reloadSettings(); return { ok: true, settings }; }),
     },
 
-    // ---- 任务面板 ----
+  ];
+}
+
+// ---- 域 4: 任务面板 (7 个工具) ----
+function taskTools(agent, taskBoard) {
+  return [
     {
       name: "ppx.task.templates",
       title: "任务模板列表",
@@ -280,13 +309,18 @@ export function createAdminTools(agent) {
         if (!t) throw new Error("任务不存在");
         taskBoard.update({ id, status: "running" });
         const prompt = str(args.prompt) || `执行任务「${t.title}」: ${t.description || ""}`;
-        const reply = await agent.chat(prompt, { sessionKey: "task:" + id });
+        let reply;
+        try {
+          reply = await agent.chat(prompt, { sessionKey: "task:" + id });
+        } catch (e) {
+          // 2026-10-03 修复 (P1): chat 抛错时任务永久卡 running (僵尸运行态), 回滚为 failed
+          try { taskBoard.update({ id, status: "failed" }); } catch { /* 状态回滚失败不再抛 */ }
+          throw e;
+        }
         // 全部步骤置 done, 任务置 done
         taskBoard.complete(id, reply);
         return { ok: true, id, result: reply };
       }),
     },
   ];
-
-  return { tools, taskBoard };
 }