openclaw-sc 5.38.0

package/lib/log-manager.js

@@ -0,0 +1,258 @@
+/**
+ * 🦞 sc 独立日志系统 + hippocampus集成
+ *
+ * 日志目录: plugins/sc/logs/
+ * 分文件: worker-pool.log / error.log / access.log
+ * 轮转: 单文件最大5MB, 超限自动切割, 滚动保留5个历史
+ * hippocampus: 日志缓冲后每15min写入 memory/hippocampus/logs.jsonl
+ */
+
+import { mkdir, appendFile, stat, rename, unlink } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+// 🔧 移除未使用的 existsSync/constants 导入
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ====== 路径常量 ======
+const LOG_DIR = join(__dirname, '..', 'logs');
+const HIPPOCAMPUS_DIR = join(__dirname, '..', '..', '..', 'memory', 'hippocampus');
+const LOGS_JSONL = join(HIPPOCAMPUS_DIR, 'logs.jsonl');
+
+// ====== 轮转常量 ======
+const MAX_LOG_SIZE = 5 * 1024 * 1024;  // 5MB
+const MAX_LOG_FILES = 5;                // 保留5个历史文件
+
+// ====== 日志文件路径 ======
+const LOG_FILES = {
+  worker: join(LOG_DIR, 'worker-pool.log'),
+  error: join(LOG_DIR, 'error.log'),
+  access: join(LOG_DIR, 'access.log'),
+};
+
+// ====== hippocampus缓冲 ======
+let hippocampusBuffer = [];
+let hippocampusTimer = null;
+const HIPPOCAMPUS_FLUSH_INTERVAL = 15 * 60 * 1000; // 15min
+const MAX_BUFFER_LINES = 10000; // 最大缓冲行数，超出丢弃最旧数据，防OOM
+
+// ====== 轮转锁：防止并发 rotateIfNeeded 的 TOCTOU 竞态 ======
+const rotateLocks = new Map();
+
+/**
+ * 获取文件粒度的互斥锁（promise-based）
+ * @param {string} key - 文件路径
+ * @returns {Promise<() => void>} 解锁函数
+ */
+async function acquireRotateLock(key) {
+  while (rotateLocks.has(key)) {
+    await rotateLocks.get(key);
+  }
+  let unlock;
+  const promise = new Promise(resolve => { unlock = resolve; });
+  rotateLocks.set(key, promise);
+  return unlock;
+}
+
+// ====== 初始化标记 ======
+let _initialized = false;
+
+// ====== 格式化时间戳 ======
+function ts() {
+  const now = new Date();
+  return now.toISOString().replace('T', ' ').substring(0, 19) + '.' +
+    String(now.getMilliseconds()).padStart(3, '0');
+}
+
+// ====== 确保日志目录存在 ======
+async function ensureLogDir() {
+  try {
+    await mkdir(LOG_DIR, { recursive: true });
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+}
+
+// ====== 日志轮转：检查文件大小，超限则滚动（带锁防TOCTOU竞态） ======
+async function rotateIfNeeded(filePath) {
+  const unlock = await acquireRotateLock(filePath);
+  try {
+    let stats;
+    try {
+      stats = await stat(filePath);
+    } catch (err) {
+      // ENOENT = 文件还不存在，无需轮转
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+    if (stats.size < MAX_LOG_SIZE) return;
+
+    // 删除最旧的备份
+    const oldest = `${filePath}.${MAX_LOG_FILES}`;
+    try { await unlink(oldest); } catch { /* 可能不存在 */ }
+
+    // 移位：.4 → .5, .3 → .4, ..., .1 → .2
+    for (let i = MAX_LOG_FILES - 1; i >= 1; i--) {
+      const src = `${filePath}.${i}`;
+      const dst = `${filePath}.${i + 1}`;
+      try { await rename(src, dst); } catch { /* 可能不存在 */ }
+    }
+
+    // 当前文件 → .1
+    await rename(filePath, `${filePath}.1`);
+  } catch (err) {
+    // 只抛出非预期错误
+    if (err.code !== 'ENOENT') throw err;
+  } finally {
+    // 释放锁
+    rotateLocks.delete(filePath);
+    unlock();
+  }
+}
+
+// ====== 写入一行到日志文件（含自动轮转） ======
+async function writeLog(filePath, line) {
+  try {
+    await rotateIfNeeded(filePath);
+    await appendFile(filePath, line + '\n', 'utf-8');
+  } catch (err) {
+    console.error(`[log-manager] ⚠️ 写入日志失败 [${filePath}]: ${err.message}`);
+  }
+}
+
+// ====== Worker 日志 ======
+async function logWorker(workerId, message) {
+  const line = `[${ts()}] [Worker-${workerId}] ${message}`;
+  await writeLog(LOG_FILES.worker, line);
+}
+
+// ====== 错误日志 ======
+async function logError(source, message, stack) {
+  const stackPart = stack ? `\n${stack}` : '';
+  const line = `[${ts()}] [${source}] ${message}${stackPart}`;
+  await writeLog(LOG_FILES.error, line);
+}
+
+// ====== 访问日志 ======
+async function logAccess(tool, params, durationMs, resultStatus) {
+  const paramSummary = params
+    ? (typeof params === 'string' ? params : JSON.stringify(params).substring(0, 200))
+    : '';
+  const line = `[${ts()}] [ACCESS] tool=${tool} duration=${durationMs}ms status=${resultStatus || 'ok'} params=${paramSummary}`;
+  await writeLog(LOG_FILES.access, line);
+}
+
+// ====== Worker 事件日志 ======
+async function logWorkerEvent(workerId, event, details) {
+  const line = `[${ts()}] [Worker-${workerId}] [${event}] ${details}`;
+  await writeLog(LOG_FILES.worker, line);
+}
+
+// ====== 通用日志（供 console 拦截使用） ======
+async function log(level, source, message) {
+  const line = `[${ts()}] [${level.toUpperCase()}] [${source}] ${message}`;
+  await writeLog(LOG_FILES.worker, line);
+  if (level === 'error' || level === 'warn') {
+    await writeLog(LOG_FILES.error, line);
+  }
+}
+
+// ====== 将缓冲日志刷入hippocampus ======
+async function flushToHippocampus() {
+  if (hippocampusBuffer.length === 0) return;
+  const batch = hippocampusBuffer.splice(0, hippocampusBuffer.length);
+  try {
+    const lines = batch.map(entry => JSON.stringify(entry)).join('\n') + '\n';
+    await appendFile(LOGS_JSONL, lines, 'utf-8');
+  } catch (err) {
+    console.error(`[log-manager] ⚠️ hippocampuswrite failed: ${err.message}`);
+    // 失败时回放缓冲，不丢数据
+    hippocampusBuffer.unshift(...batch);
+  }
+}
+
+// ====== 将日志目加入hippocampus缓冲（队列模式，防OOM） ======
+function bufferForHippocampus(entry) {
+  hippocampusBuffer.push({
+    timestamp: ts(),
+    ...entry,
+  });
+  // 队列模式：超出上限则丢弃最旧数据
+  if (hippocampusBuffer.length > MAX_BUFFER_LINES) {
+    hippocampusBuffer.splice(0, hippocampusBuffer.length - MAX_BUFFER_LINES);
+  }
+}
+
+// ====== 启动hippocampus定时刷入 ======
+function startHippocampusFlush() {
+  if (hippocampusTimer) return;
+  hippocampusTimer = setInterval(() => {
+    flushToHippocampus().catch(err => {
+      console.error(`[log-manager] ⚠️ hippocampus定时刷入失败: ${err.message}`);
+    });
+  }, HIPPOCAMPUS_FLUSH_INTERVAL);
+
+  // 进程退出前刷一次
+  process.on('beforeExit', () => {
+    flushToHippocampus().catch(() => {});
+  });
+}
+
+// ====== 停止hippocampus定时刷入 ======
+function stopHippocampusFlush() {
+  if (hippocampusTimer) {
+    clearInterval(hippocampusTimer);
+    hippocampusTimer = null;
+  }
+  // 最终刷一次
+  flushToHippocampus().catch(() => {});
+}
+
+// ====== 初始化日志系统 ======
+async function initLogger() {
+  if (_initialized) return getLogger();
+  _initialized = true;
+
+  await ensureLogDir();
+  startHippocampusFlush();
+
+  const initMsg = `===== sc 日志系统初始化 [${new Date().toISOString()}] =====`;
+  await writeLog(LOG_FILES.worker, initMsg);
+  await writeLog(LOG_FILES.error, initMsg);
+  await writeLog(LOG_FILES.access, initMsg);
+
+  // TODO: 移除调试日志 console.log('[sc] 📋 日志系统已初始化 (目录: logs/, 轮转: 5MB×5, hippocampus: 15min)');
+
+  return getLogger();
+}
+
+// ====== 获取日志 API 引用 ======
+function getLogger() {
+  return {
+    logWorker,
+    logError,
+    logAccess,
+    logWorkerEvent,
+    log,
+    flush: flushToHippocampus,
+    bufferForHippocampus,
+    stop: stopHippocampusFlush,
+    LOG_DIR,
+    initialized: _initialized,
+  };
+}
+
+export {
+  initLogger,
+  getLogger,
+  logWorker,
+  logError,
+  logAccess,
+  logWorkerEvent,
+  log,
+  flushToHippocampus,
+  bufferForHippocampus,
+  startHippocampusFlush,
+  stopHippocampusFlush,
+};

package/lib/preemption.js

@@ -0,0 +1,278 @@
+/**
+ * ⚡ 高优任务抢占模块 — 高优任务抢占
+ *
+ * 当所有Worker忙碌 + 队列深度 > PREEMPT_QUEUE_THRESHOLD（26）时触发preempt评估：
+ * 1. 计算每个活跃任务的优先级分 = f(紧急度 × 价值 × (1 - 运行占比))
+ * 2. 最低分任务被抢占，状态序列化到 shared/preempt/
+ * 3. 被抢任务在队列头部等待恢复（恢复到原角色的stemcell）
+ *
+ * 与 Worker 分化协作：stemcell 优先接手被抢占任务（因原Worker可能已满负荷）
+ */
+
+import crypto from "crypto";
+import { join } from "path";
+import { readFile, writeFile, rename, unlink, mkdir, readdir, stat } from "fs/promises";
+import { SHARED_DIR, PREEMPT_TASK_TIMEOUT_MS, PREEMPT_MAX_AGE_MS, PREEMPT_QUEUE_THRESHOLD } from './constants.js';
+
+const PREEMPT_DIR = join(SHARED_DIR, 'preempt');
+
+/**
+ * 确保 preempt 目录存在
+ */
+export async function ensurePreemptDir() {
+  try { await mkdir(PREEMPT_DIR, { recursive: true }); } catch (err) {
+    console.warn(`[sc] ⚠️ mkdir PREEMPT_DIR失败: ${err?.message || '未知错误'}`);
+  }
+}
+
+/**
+ * 计算任务优先级分
+ * score = urgency × value × (1 - runtimeRatio)
+ *   - urgency: high=1.0, normal=0.6, low=0.3
+ *   - value: 任务预估值 [0.1, 1.0]（未设定=0.5）
+ *   - runtimeRatio: 已运行时间/超时阈值 [0, 1]
+ * 分数越低 → 越容易被preempt
+ *
+ * 🧠 [设计决策] 高优任务抢占策略：当所有Worker忙碌且队列深度>26（PREEMPT_QUEUE_THRESHOLD）时触发，
+ * 按优先级分抢占最低分任务，保持系统响应性。被抢任务序列化到shared/preempt/，
+ * 由stemcell兜底恢复。
+ * （详见 memory/known-design-decisions.md — 架构设计）
+ *
+ * @param {object} task - 任务对象
+ * @param {object} workerEntry - 正在执行该任务的Worker
+ * @param {number} taskTimeoutMs - 该任务类型的超时阈值
+ * @returns {number} 优先级分 [0, 1]
+ */
+function calculatePriorityScore(task, workerEntry, taskTimeoutMs) {
+  const priority = task.priority || 'normal';
+  const urgency = priority === 'high' ? 1.0 : priority === 'normal' ? 0.6 : 0.3;
+  const runtime = Date.now() - (workerEntry.currentJobStartTime || workerEntry.idleSince || Date.now());
+  const timeout = taskTimeoutMs || 60000;
+  const runtimeRatio = Math.min(1, Math.max(0, runtime / timeout));
+  const estimatedValue = task._estimatedValue ?? 0.5;
+  const finalScore = urgency * estimatedValue * (1 - runtimeRatio);
+  return finalScore;
+}
+
+/**
+ * 评估是否需要触发preempt
+ *
+ * @param {object} pool - Worker 池实例（用于 getStats）
+ * @param {object} taskQueues - {high, normal, low} 队列
+ * @param {Array} workers - Worker 列表
+ * @returns {{ shouldPreempt: boolean, target: object|null, reason: string }}
+ */
+export function evaluatePreemption(pool, taskQueues, workers) {
+  const stats = pool.getStats();
+  const totalQueued = (taskQueues.high?.length || 0) +
+                      (taskQueues.normal?.length || 0) +
+                      (taskQueues.low?.length || 0);
+
+  // 阈值检查：所有Worker忙碌 + 队列深度 >= PREEMPT_QUEUE_THRESHOLD 才触发preempt
+  if (totalQueued < PREEMPT_QUEUE_THRESHOLD) {
+    return { shouldPreempt: false, target: null, reason: `队列深度 ${totalQueued} < ${PREEMPT_QUEUE_THRESHOLD}，无需preempt` };
+  }
+
+  const aliveBusy = workers.filter(w => w.alive && w.busy && !w.terminating && w.currentJobId);
+  if (aliveBusy.length === 0) {
+    return { shouldPreempt: false, target: null, reason: '没有活跃的忙碌Worker' };
+  }
+
+  // 遍历所有活跃任务，计算最低分
+  let lowestScore = Infinity;
+  let targetTask = null;
+  let targetWorker = null;
+
+  for (const we of aliveBusy) {
+    const jobId = we.currentJobId;
+    if (!jobId) continue;
+
+    // 从 pendingJobs 中找原始任务（通过jobId）
+    const pendingJob = pool._pendingJobs?.get?.(jobId);
+    if (!pendingJob) continue;
+
+    const task = pendingJob._task || pendingJob.task;
+    if (!task) continue;
+
+    const taskType = task.type || 'default';
+    const typeConfig = pool._taskTimeoutMap?.[taskType] || pool._taskTimeoutMap?.default || {};
+    const killTimeout = typeConfig.kill || 120;
+    const taskTimeoutMs = (killTimeout || 120) * 1000;
+
+    const score = calculatePriorityScore(task, we, taskTimeoutMs);
+    if (score < lowestScore) {
+      lowestScore = score;
+      targetTask = { task, jobId, workerEntry: we, pendingJob, timeoutMs: taskTimeoutMs, score };
+    }
+  }
+
+  if (!targetTask) {
+    return { shouldPreempt: false, target: null, reason: '未找到可评估的活跃任务' };
+  }
+
+  return {
+    shouldPreempt: true,
+    target: targetTask,
+    reason: `preempt评估完成: 最低分=${targetTask.score.toFixed(3)} (任务=${targetTask.task.type}, Worker=${targetTask.workerEntry.id})`,
+  };
+}
+
+/**
+ * 序列化被抢占任务的状态到 shared/preempt/
+ *
+ * @param {object} target - evaluatePreemption 返回的 target
+ * @returns {Promise<string|null>} 状态文件路径，失败返回 null
+ */
+export async function savePreemptState(target) {
+  try {
+    await ensurePreemptDir();
+    const jobId = target.jobId;
+    const state = {
+      jobId,
+      task: target.task,
+      preemptedAt: Date.now(),
+      preemptedFromWorker: target.workerEntry.id,
+      workerRole: target.workerEntry.role,
+      score: target.score,
+      partialResult: target.workerEntry.partialResult || null,
+      pendingJobResolve: null,  // 不序列化函数引用
+      pendingJobReject: null,
+    };
+    const fp = join(PREEMPT_DIR, `${jobId}.json`);
+    const tmp = join(PREEMPT_DIR, `${jobId}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+    await writeFile(tmp, JSON.stringify(state, null, 2), 'utf-8');
+    await rename(tmp, fp);
+    return fp;
+  } catch (err) {
+    console.warn(`[sc] ⚠️ 保存preempt状态失败: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * 读取被抢占任务的状态
+ *
+ * @param {string} jobId - 被抢占任务的 jobId
+ * @returns {Promise<object|null>} 任务状态
+ */
+export async function readPreemptState(jobId) {
+  try {
+    await ensurePreemptDir();
+    const fp = join(PREEMPT_DIR, `${jobId}.json`);
+    const content = await readFile(fp, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    console.warn(`[sc] ⚠️ 读取preempt状态失败(jobId=${jobId}): ${err?.message || '未知错误'}`);
+    return null;
+  }
+}
+
+/**
+ * 清除指定的抢占状态文件（恢复或超时删除后调用）
+ *
+ * @param {string} jobId
+ */
+export async function clearPreemptState(jobId) {
+  try {
+    const fp = join(PREEMPT_DIR, `${jobId}.json`);
+    await unlink(fp).catch(() => {});
+  } catch (err) {
+    console.warn(`[sc] ⚠️ 清理preempt状态失败(jobId=${jobId}): ${err?.message || '未知错误'}`);
+  }
+}
+
+/**
+ * 列出所有被抢占但尚未恢复的任务
+ * 会过滤掉超过 PREEMPT_MAX_AGE_MS 的失效率任务
+ *
+ * @returns {Promise<Array>} 待恢复任务列表（按被抢时间升序）
+ */
+export async function listPreemptedTasks() {
+  try {
+    await ensurePreemptDir();
+    const files = await readdir(PREEMPT_DIR).catch(() => []);
+    const tasks = [];
+    const now = Date.now();
+    let cleaned = 0;
+
+    for (const f of files) {
+      if (!f.endsWith('.json') || f.endsWith('.tmp')) continue;
+      const fp = join(PREEMPT_DIR, f);
+      try {
+        const content = await readFile(fp, 'utf-8');
+        const state = JSON.parse(content);
+        const age = now - (state.preemptedAt || now);
+        if (age > PREEMPT_MAX_AGE_MS) {
+          await unlink(fp);
+          cleaned++;
+          continue;
+        }
+        tasks.push({
+          ...state,
+          stateFilePath: fp,
+          ageMs: age,
+          ageSec: Math.round(age / 1000),
+        });
+      } catch (err) {
+        // 损坏的文件也清理
+        console.warn(`[sc] ⚠️ 读取preempt文件失败 ${f}: ${err?.message || '未知错误'}`);
+        try { await unlink(fp); cleaned++; } catch (e2) {
+          console.warn(`[sc] ⚠️ 删除损坏preempt文件失败 ${f}: ${e2?.message || '未知错误'}`);
+        }
+      }
+    }
+
+    if (cleaned > 0) {
+      // TODO: 移除调试日志 console.log(`[sc] 🧹 清理了 ${cleaned} 个过期/损坏的抢占状态文件`);
+    }
+
+    // 按被抢时间升序（最老的优先恢复）
+    tasks.sort((a, b) => (a.preemptedAt || 0) - (b.preemptedAt || 0));
+    return tasks;
+  } catch (err) {
+    console.warn(`[sc] ⚠️ list preempted tasks failed: ${err.message}`);
+    return [];
+  }
+}
+
+/**
+ * 清理超时的抢占状态文件
+ */
+export async function cleanupExpiredPreemptStates() {
+  try {
+    await ensurePreemptDir();
+    const files = await readdir(PREEMPT_DIR).catch(() => []);
+    const now = Date.now();
+    let cleaned = 0;
+    for (const f of files) {
+      if (!f.endsWith('.json') || f.endsWith('.tmp')) continue;
+      const fp = join(PREEMPT_DIR, f);
+      try {
+        const content = await readFile(fp, 'utf-8');
+        const state = JSON.parse(content);
+        if (now - (state.preemptedAt || now) > PREEMPT_MAX_AGE_MS) {
+          await unlink(fp);
+          cleaned++;
+        }
+      } catch (err) {
+        console.warn(`[sc] ⚠️ 清理过期preempt文件失败 ${f}: ${err?.message || '未知错误'}`);
+        try { await unlink(fp); cleaned++; } catch (e2) {
+          console.warn(`[sc] ⚠️ 删除过期preempt文件失败 ${f}: ${e2?.message || '未知错误'}`);
+        }
+      }
+    }
+    if (cleaned > 0) console.log(`[sc] 🧹 清理了 ${cleaned} 个过期抢占状态`);
+  } catch (err) {
+    console.warn(`[sc] ⚠️ cleanupExpiredPreemptStates失败: ${err?.message || '未知错误'}`);
+  }
+}
+
+export default {
+  ensurePreemptDir,
+  evaluatePreemption,
+  savePreemptState,
+  readPreemptState,
+  clearPreemptState,
+  listPreemptedTasks,
+  cleanupExpiredPreemptStates,
+};

package/lib/priority-calc.js

@@ -0,0 +1,134 @@
+/**
+ * 🦞 sc — 三维优先级计算
+ *
+ * priority = 紧急度(U) × 0.4 + 重要度(I) × 0.4 + CPU消耗(C) × 0.2
+ *
+ * 输出：0-10 的分数
+ *
+ * 参数来源（可根据需要扩展）：
+ *   - 紧急度 U: 用户在等回复(10) / 后台任务(1)
+ *   - 重要度 I: 核心功能(10) / 锦上添花(1)
+ *   - CPU消耗 C: 搜索类(8) / 代码类(2)
+ *
+ * 按任务类型自动计算默认值，同时支持手动覆盖。
+ */
+
+/**
+ * 任务类型 → (紧急度, 重要度, CPU消耗) 默认映射
+ *
+ * 紧急度 U ∈ [1, 10] — 1=完全不急, 10=立刻要
+ * 重要度 I ∈ [1, 10] — 1=可做可不做, 10=核心功能
+ * CPU消耗 C ∈ [1, 10] — 1=几乎不耗CPU, 10=重度计算
+ */
+const TYPE_PRIORITY_DEFAULTS = {
+  // 用户交互类
+  chat:       { urgency: 10, importance: 10, cpuCost: 1, label: '聊天回复' },
+  dialog:     { urgency: 10, importance: 9,  cpuCost: 2, label: '对话记忆检索' },
+
+  // 搜索查询类
+  search:     { urgency: 7,  importance: 7,  cpuCost: 8,  label: '搜索查询' },
+  scan:       { urgency: 6,  importance: 6,  cpuCost: 7,  label: '目录扫描' },
+  'semantic-search': { urgency: 7, importance: 7, cpuCost: 9, label: '语义搜索' },
+  'dialog-recall': { urgency: 8, importance: 7, cpuCost: 6, label: '对话日记检索' },
+
+  // 编解码类
+  code:       { urgency: 7,  importance: 8,  cpuCost: 2,  label: '编码任务' },
+  'code-edit': { urgency: 7, importance: 8,  cpuCost: 3,  label: '代码编辑' },
+  'code-review': { urgency: 6, importance: 7, cpuCost: 3, label: '代码审查' },
+  'bug-fix':  { urgency: 8,  importance: 9,  cpuCost: 4,  label: 'Bug修复' },
+
+  // 分析类
+  analysis:   { urgency: 6,  importance: 7,  cpuCost: 6,  label: '数据分析' },
+  research:   { urgency: 6,  importance: 8,  cpuCost: 7,  label: '深度调研' },
+  orchestrate: { urgency: 7, importance: 8,  cpuCost: 5,  label: '任务编排' },
+  diagnose:   { urgency: 7,  importance: 8,  cpuCost: 5,  label: '系统诊断' },
+  diff:       { urgency: 5,  importance: 6,  cpuCost: 4,  label: '差异分析' },
+  'process-log': { urgency: 6, importance: 6, cpuCost: 5, label: '日志分析' },
+
+  // 系统管理类
+  system:     { urgency: 6,  importance: 7,  cpuCost: 3,  label: '系统管理' },
+  sync:       { urgency: 5,  importance: 6,  cpuCost: 4,  label: '同步任务' },
+  stats:      { urgency: 4,  importance: 5,  cpuCost: 2,  label: '状态查询' },
+  config:     { urgency: 5,  importance: 6,  cpuCost: 2,  label: '配置管理' },
+
+  // 批量/调度类
+  batch:      { urgency: 7,  importance: 7,  cpuCost: 8,  label: '批量处理' },
+  dispatch:   { urgency: 6,  importance: 7,  cpuCost: 4,  label: '任务调度' },
+
+  // 视觉类
+  vision:     { urgency: 6,  importance: 7,  cpuCost: 9,  label: '视觉分析' },
+  'image-batch': { urgency: 6, importance: 7, cpuCost: 9, label: '图片批量分析' },
+
+  // 运维/维护类
+  maintenance: { urgency: 3, importance: 4,  cpuCost: 3,  label: '系统维护' },
+  cleanup:    { urgency: 2,  importance: 3,  cpuCost: 2,  label: '清理任务' },
+  learn:      { urgency: 1,  importance: 7,  cpuCost: 6,  label: '后台学习' },
+  // 🧠 设计决策：sleep-learn 已删除（管理员2026-05-31要求移除后台学习）
+  'route-audit': { urgency: 2, importance: 6, cpuCost: 4, label: '路由审计' },
+
+  // 通用兜底
+  general:    { urgency: 5,  importance: 5,  cpuCost: 5,  label: '通用任务' },
+};
+
+/**
+ * 计算三维优先级
+ *
+ * @param {string} type - 任务类型（如 'search', 'code', 'system'）
+ * @param {Object} [overrides] - 手动覆盖 { urgency?, importance?, cpuCost? }
+ * @returns {Promise<number>} 0-10 的优先级分数
+ */
+export async function calculatePriority(type, overrides = {}) {
+  const defaults = TYPE_PRIORITY_DEFAULTS[type] || TYPE_PRIORITY_DEFAULTS.general;
+
+  const urgency = overrides?.urgency !== undefined ? overrides.urgency : defaults.urgency;
+  const importance = overrides?.importance !== undefined ? overrides.importance : defaults.importance;
+  const cpuCost = overrides?.cpuCost !== undefined ? overrides.cpuCost : defaults.cpuCost;
+
+  // 确保范围 [1, 10]
+  const u = Math.max(1, Math.min(10, Number(urgency) || 5));
+  const i = Math.max(1, Math.min(10, Number(importance) || 5));
+  const c = Math.max(1, Math.min(10, Number(cpuCost) || 5));
+
+  // priority = U × 0.4 + I × 0.4 + C × 0.2
+  const priority = Math.round((u * 0.4 + i * 0.4 + c * 0.2) * 10) / 10;
+
+  // 钳制到 [0, 10]
+  return Math.max(0, Math.min(10, priority));
+}
+
+/**
+ * 获取任务类型的默认三维参数
+ * @param {string} type
+ * @returns {Object} { urgency, importance, cpuCost, label }
+ */
+export function getTypeDefaults(type) {
+  return { ...(TYPE_PRIORITY_DEFAULTS[type] || TYPE_PRIORITY_DEFAULTS.general) };
+}
+
+/**
+ * 获取所有任务类型默认参数
+ * @returns {Object}
+ */
+export function getAllTypeDefaults() {
+  return { ...TYPE_PRIORITY_DEFAULTS };
+}
+
+/**
+ * 获取优先级等级标签
+ * @param {number} score - 0-10
+ * @returns {string}
+ */
+export function getPriorityLabel(score) {
+  if (score >= 9) return '紧急';
+  if (score >= 7) return '高优先';
+  if (score >= 5) return '中优先';
+  if (score >= 3) return '低优先';
+  return '空闲';
+}
+
+export default {
+  calculatePriority,
+  getTypeDefaults,
+  getAllTypeDefaults,
+  getPriorityLabel,
+};