@fieldwangai/agentflow 0.1.29 → 0.1.30

package/bin/lib/runtime-context.mjs

@@ -0,0 +1,225 @@
+import path from "path";
+import { getFlowDir } from "./workspace.mjs";
+import { PACKAGE_ROOT, PIPELINES_DIR } from "./paths.mjs";
+import { listSkills, listSkillsFromSources, workspaceSkillSources } from "./skill-registry.mjs";
+
+function parseJsonObject(raw) {
+  if (raw == null) return null;
+  if (typeof raw === "object" && !Array.isArray(raw)) return raw;
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function getPipelineFlowDir(workspaceRoot, flowName, flowJson = null) {
+  if (flowJson?.flowDir && typeof flowJson.flowDir === "string" && flowJson.flowDir.trim()) {
+    return path.isAbsolute(flowJson.flowDir) ? path.resolve(flowJson.flowDir) : path.resolve(workspaceRoot, flowJson.flowDir);
+  }
+  return getFlowDir(workspaceRoot, flowName) || path.join(path.resolve(workspaceRoot), PIPELINES_DIR, flowName);
+}
+
+export function buildDefaultWorkspaceContext(workspaceRoot, flowName, flowJson = null) {
+  const pipelineWorkspace = path.resolve(workspaceRoot);
+  const flowDir = getPipelineFlowDir(workspaceRoot, flowName, flowJson);
+  return {
+    version: 1,
+    label: "pipeline",
+    cwd: pipelineWorkspace,
+    workspaceRoot: pipelineWorkspace,
+    pipelineWorkspace,
+    flowDir,
+    previous: null,
+  };
+}
+
+export function normalizeWorkspaceContext(raw, workspaceRoot, flowName, flowJson = null) {
+  const base = buildDefaultWorkspaceContext(workspaceRoot, flowName, flowJson);
+  const parsed = parseJsonObject(raw);
+  if (!parsed) return base;
+  const cwdRaw = parsed.cwd || parsed.workspaceRoot || parsed.path || "";
+  const cwd = cwdRaw ? path.resolve(String(cwdRaw)) : base.cwd;
+  return {
+    ...base,
+    ...parsed,
+    version: 1,
+    cwd,
+    workspaceRoot: cwd,
+    pipelineWorkspace: path.resolve(parsed.pipelineWorkspace || base.pipelineWorkspace),
+    flowDir: path.resolve(parsed.flowDir || base.flowDir),
+    previous: parsed.previous && typeof parsed.previous === "object" ? parsed.previous : null,
+  };
+}
+
+export function normalizeSkillsContext(raw) {
+  const parsed = parseJsonObject(raw);
+  if (!parsed) return null;
+  return {
+    version: 1,
+    ...parsed,
+    skills: Array.isArray(parsed.skills) ? parsed.skills : [],
+    skillKeys: Array.isArray(parsed.skillKeys) ? parsed.skillKeys : [],
+    sources: Array.isArray(parsed.sources) ? parsed.sources : [],
+    warnings: Array.isArray(parsed.warnings) ? parsed.warnings : [],
+  };
+}
+
+export function expandRuntimePlaceholders(text, workspaceContext, extra = {}) {
+  if (text == null) return "";
+  const raw = String(text).trim();
+  if (!raw) return "";
+  const values = {
+    workspaceRoot: workspaceContext.workspaceRoot || workspaceContext.cwd || "",
+    cwd: workspaceContext.cwd || workspaceContext.workspaceRoot || "",
+    pipelineWorkspace: workspaceContext.pipelineWorkspace || "",
+    flowDir: workspaceContext.flowDir || "",
+    ...extra,
+  };
+  return raw.replace(/\$\{([^}]+)\}/g, (_, key) => {
+    const k = String(key || "").trim();
+    return values[k] != null ? String(values[k]) : "";
+  });
+}
+
+export function resolveWorkspaceTarget(rawTarget, workspaceContext, extra = {}) {
+  const expanded = expandRuntimePlaceholders(rawTarget, workspaceContext, extra).trim();
+  if (!expanded || expanded === "pipeline" || expanded === "pipeline-workspace") {
+    return workspaceContext.pipelineWorkspace;
+  }
+  if (expanded === "current" || expanded === ".") return workspaceContext.cwd;
+  if (expanded === "flowDir") return workspaceContext.flowDir;
+  return path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(workspaceContext.cwd, expanded);
+}
+
+export function scanSkillsFromPaths(paths, opts = {}) {
+  const sources = (paths || []).map((entry, index) => ({
+    source: entry.source || `runtime-${index}`,
+    sourceLabel: entry.sourceLabel || entry.label || entry.dir,
+    dir: path.resolve(entry.dir),
+    installedBy: entry.installedBy || "runtime",
+  }));
+  return listSkillsFromSources(sources, { ...opts, warnMissing: true });
+}
+
+export function parseSkillKeyList(raw) {
+  if (Array.isArray(raw)) return raw.map((x) => String(x || "").trim()).filter(Boolean);
+  return String(raw || "")
+    .split(/[\s,]+/)
+    .map((x) => x.trim())
+    .filter(Boolean);
+}
+
+function skillBodyFromRegistryItem(skill) {
+  return {
+    name: skill.name,
+    key: skill.key,
+    description: skill.description,
+    source: skill.source,
+    sourceLabel: skill.sourceLabel,
+    path: skill.path,
+    body: skill.body,
+  };
+}
+
+export function buildSkillsContextFromRegistry({ workspaceContext, skillKeys = [], mergeMode = "replace" }) {
+  const wc = workspaceContext;
+  const wanted = parseSkillKeyList(skillKeys);
+  const registryWorkspaceRoot = wc.pipelineWorkspace || wc.workspaceRoot || wc.cwd || process.cwd();
+  const registry = listSkills(PACKAGE_ROOT, registryWorkspaceRoot);
+  const skillBodies = [];
+  const warnings = [];
+  const seenKeys = new Set();
+
+  for (const raw of wanted) {
+    const key = String(raw || "").trim();
+    if (!key) continue;
+    const match = registry.find((skill) => skill.key === key || skill.name === key || skill.id === key);
+    if (!match) {
+      warnings.push(`skill not found: ${key}`);
+      continue;
+    }
+    const dedupeKey = match.key || match.path || match.name;
+    if (seenKeys.has(dedupeKey)) continue;
+    seenKeys.add(dedupeKey);
+    skillBodies.push(skillBodyFromRegistryItem(match));
+  }
+
+  return {
+    version: 1,
+    workspaceRoot: wc.workspaceRoot,
+    cwd: wc.cwd,
+    pipelineWorkspace: wc.pipelineWorkspace,
+    flowDir: wc.flowDir,
+    source: "public-registry",
+    mergeMode,
+    requestedSkillKeys: wanted,
+    skills: skillBodies.map(({ body, ...meta }) => meta),
+    skillKeys: skillBodies.map((s) => s.key),
+    sources: [...new Set(skillBodies.map((s) => s.sourceLabel || s.source || "").filter(Boolean))],
+    loadedCount: skillBodies.length,
+    warnings,
+    skillBodies,
+  };
+}
+
+export function buildSkillsContext({ workspaceContext, source = "current-workspace", paths = [], include = [], exclude = [], mergeMode = "replace" }) {
+  const wc = workspaceContext;
+  const sourcePaths = [];
+  const addWorkspace = (root, label) => {
+    sourcePaths.push(...workspaceSkillSources(root, label, label));
+  };
+  if (source === "pipeline-workspace") {
+    addWorkspace(wc.pipelineWorkspace, "pipeline");
+  } else if (source === "explicit-paths") {
+    for (const p of paths) {
+      const resolved = path.isAbsolute(p) ? path.resolve(p) : path.resolve(wc.cwd, p);
+      sourcePaths.push({ dir: resolved, label: "explicit" });
+    }
+  } else if (source === "all") {
+    addWorkspace(wc.cwd, "current");
+    if (path.resolve(wc.cwd) !== path.resolve(wc.pipelineWorkspace)) addWorkspace(wc.pipelineWorkspace, "pipeline");
+  } else {
+    addWorkspace(wc.cwd, "current");
+  }
+  const scanned = scanSkillsFromPaths(sourcePaths, { include, exclude });
+  return {
+    version: 1,
+    workspaceRoot: wc.workspaceRoot,
+    cwd: wc.cwd,
+    source,
+    mergeMode,
+    skills: scanned.skills.map(({ body, ...meta }) => meta),
+    skillKeys: scanned.skills.map((s) => s.key),
+    sources: sourcePaths.map((p) => p.dir),
+    loadedCount: scanned.skills.length,
+    warnings: scanned.warnings,
+    skillBodies: scanned.skills.map((s) => ({
+      name: s.name,
+      key: s.key,
+      description: s.description,
+      sourceLabel: s.sourceLabel,
+      path: s.path,
+      body: s.body,
+    })),
+  };
+}
+
+export function renderSkillsContextForPrompt(skillsContext) {
+  const ctx = normalizeSkillsContext(skillsContext);
+  if (!ctx || !Array.isArray(ctx.skillBodies) || ctx.skillBodies.length === 0) return "";
+  const blocks = ctx.skillBodies.slice(0, 20).map((skill) => {
+    const body = String(skill.body || "").trim();
+    return [
+      `### ${skill.name}`,
+      skill.description ? `说明：${skill.description}` : "",
+      `来源：${skill.path || skill.sourceLabel || ""}`,
+      "",
+      body.slice(0, 16000),
+    ].filter(Boolean).join("\n");
+  });
+  return ["## 已加载 Skills", "", ...blocks].join("\n\n");
+}

package/bin/lib/scheduler.mjs

@@ -9,7 +9,7 @@ import {
   readScheduleState,
   writeScheduleState,
 } from "./schedule-config.mjs";
-import { getRunDir, PACKAGE_ROOT } from "./paths.mjs";
+import { getAgentflowUserContexts, getRunDir, PACKAGE_ROOT } from "./paths.mjs";
 import { isApplyProcessAlive } from "./run-apply-active-lock.mjs";
 import { log } from "./log.mjs";
 import { writeResult } from "../pipeline/write-result.mjs";
@@ -92,13 +92,13 @@ function buildCliInputArgs(flowDir, presetName) {
   return args;
 }
 
-function hasHigherPriorityDuplicate(workspaceRoot, flow) {
+function hasHigherPriorityDuplicate(workspaceRoot, flow, opts = {}) {
   if ((flow.source || "user") !== "workspace") return false;
-  return listFlowsJson(workspaceRoot).some((f) => f.id === flow.id && !f.archived && (f.source || "user") === "user");
+  return listFlowsJson(workspaceRoot, opts).some((f) => f.id === flow.id && !f.archived && (f.source || "user") === "user");
 }
 
-function getLatestRunUuidForFlow(workspaceRoot, flowId) {
-  const runRoot = path.dirname(getRunDir(workspaceRoot, flowId, "00000000000000"));
+function getLatestRunUuidForFlow(workspaceRoot, flowId, opts = {}) {
+  const runRoot = path.dirname(getRunDir(workspaceRoot, flowId, "00000000000000", opts));
   if (!fs.existsSync(runRoot)) return null;
   try {
     const dirs = fs.readdirSync(runRoot, { withFileTypes: true })
@@ -209,13 +209,13 @@ function readNodeResultStatus(runDir, instanceId) {
   }
 }
 
-function isFlowCurrentlyRunning(workspaceRoot, flowId, state) {
+function isFlowCurrentlyRunning(workspaceRoot, flowId, state, opts = {}) {
   const candidates = [];
   if (state && typeof state.lastRunUuid === "string") candidates.push(state.lastRunUuid);
-  const latest = getLatestRunUuidForFlow(workspaceRoot, flowId);
+  const latest = getLatestRunUuidForFlow(workspaceRoot, flowId, opts);
   if (latest) candidates.push(latest);
   for (const uuid of candidates) {
-    const runDir = getRunDir(workspaceRoot, flowId, uuid);
+    const runDir = getRunDir(workspaceRoot, flowId, uuid, opts);
     if (isApplyProcessAlive(runDir)) return true;
   }
   return false;
@@ -231,7 +231,7 @@ function baseState(flow, schedule, previousState) {
   };
 }
 
-function ensureNextRunAt(workspaceRoot, flow, schedule, state) {
+function ensureNextRunAt(workspaceRoot, flow, schedule, state, opts = {}) {
   const identity = scheduleIdentity(schedule);
   if (state.scheduleIdentity === identity && state.nextRunAt) return state;
   const nextRunAt = schedule.enabled && schedule.cron ? computeNextRunAtFromSchedule(schedule) : null;
@@ -240,11 +240,11 @@ function ensureNextRunAt(workspaceRoot, flow, schedule, state) {
     nextRunAt,
     lastError: "",
   };
-  writeScheduleState(workspaceRoot, flow.id, flow.source || "user", next);
+  writeScheduleState(workspaceRoot, flow.id, flow.source || "user", next, opts);
   return next;
 }
 
-function startScheduledRun(workspaceRoot, flow, schedule, state) {
+function startScheduledRun(workspaceRoot, flow, schedule, state, opts = {}) {
   const flowDir = flow.path || "";
   const agentflowBin = path.join(PACKAGE_ROOT, "bin", "agentflow.mjs");
   const args = [agentflowBin, "apply", flow.id, "--machine-readable", "--workspace-root", path.resolve(workspaceRoot), "--force"];
@@ -252,7 +252,7 @@ function startScheduledRun(workspaceRoot, flow, schedule, state) {
   const child = spawn(process.execPath, args, {
     cwd: path.resolve(workspaceRoot),
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env, FORCE_COLOR: "0" },
+    env: { ...process.env, FORCE_COLOR: "0", AGENTFLOW_USER_ID: opts.userId || "" },
     detached: true,
   });
 
@@ -276,7 +276,7 @@ function startScheduledRun(workspaceRoot, flow, schedule, state) {
             lastRunUuid,
             lastPid: child.pid || null,
             lastError: "",
-          });
+          }, opts);
         }
       } catch {
         /* ignore non-json lines */
@@ -290,7 +290,7 @@ function startScheduledRun(workspaceRoot, flow, schedule, state) {
   });
 
   child.on("exit", (code, signal) => {
-    const prev = readScheduleState(workspaceRoot, flow.id, flow.source || "user").state || state;
+    const prev = readScheduleState(workspaceRoot, flow.id, flow.source || "user", opts).state || state;
     writeScheduleState(workspaceRoot, flow.id, flow.source || "user", {
       ...baseState(flow, schedule, prev),
       nextRunAt: prev.nextRunAt || computeNextRunAtFromSchedule(schedule),
@@ -300,14 +300,14 @@ function startScheduledRun(workspaceRoot, flow, schedule, state) {
       lastExitSignal: signal || "",
       lastFinishedAt: new Date().toISOString(),
       lastError: code === 0 ? "" : `scheduled run exited with code ${code}${signal ? ` signal ${signal}` : ""}`,
-    });
+    }, opts);
   });
 
   child.unref();
   return child;
 }
 
-function startWaitingRunResume(workspaceRoot, flow, waitState) {
+function startWaitingRunResume(workspaceRoot, flow, waitState, opts = {}) {
   const agentflowBin = path.join(PACKAGE_ROOT, "bin", "agentflow.mjs");
   const uuid = String(waitState.uuid || "");
   const instanceId = String(waitState.instanceId || "");
@@ -325,7 +325,7 @@ function startWaitingRunResume(workspaceRoot, flow, waitState) {
   const child = spawn(process.execPath, args, {
     cwd: path.resolve(workspaceRoot),
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env, FORCE_COLOR: "0" },
+    env: { ...process.env, FORCE_COLOR: "0", AGENTFLOW_USER_ID: opts.userId || "" },
     detached: true,
   });
   child.stdout.on("data", () => {});
@@ -411,17 +411,17 @@ export function cancelScheduledRun(workspaceRoot, flowId, uuid) {
   return { ok: true, flowId, uuid, cancelledAt, updatedWaits: updated, propagatedWaits: propagated, resumePid };
 }
 
-export function listScheduleStatuses(workspaceRoot) {
+export function listScheduleStatuses(workspaceRoot, opts = {}) {
   const rows = [];
-  for (const flow of listFlowsJson(workspaceRoot)) {
+  for (const flow of listFlowsJson(workspaceRoot, opts)) {
     if (flow.archived || flow.source === "builtin") continue;
-    const scheduleRes = readFlowSchedule(workspaceRoot, flow.id, flow.source || "user");
+    const scheduleRes = readFlowSchedule(workspaceRoot, flow.id, flow.source || "user", opts);
     if (!scheduleRes.success) {
       rows.push({ flowId: flow.id, flowSource: flow.source || "user", enabled: false, error: scheduleRes.error });
       continue;
     }
     const schedule = scheduleRes.schedule;
-    const stateRes = readScheduleState(workspaceRoot, flow.id, flow.source || "user");
+    const stateRes = readScheduleState(workspaceRoot, flow.id, flow.source || "user", opts);
     const state = stateRes.success ? stateRes.state : {};
     rows.push({
       flowId: flow.id,
@@ -433,10 +433,10 @@ export function listScheduleStatuses(workspaceRoot) {
       nextRunAt: state.nextRunAt || schedule.nextRunAt || null,
       lastTriggeredAt: state.lastTriggeredAt || null,
       lastRunUuid: state.lastRunUuid || null,
-      lastError: hasHigherPriorityDuplicate(workspaceRoot, flow)
+      lastError: hasHigherPriorityDuplicate(workspaceRoot, flow, opts)
         ? "workspace flow is shadowed by a user flow with the same id"
         : state.lastError || "",
-      running: isFlowCurrentlyRunning(workspaceRoot, flow.id, state),
+      running: isFlowCurrentlyRunning(workspaceRoot, flow.id, state, opts),
       waiting: countActiveWaitsForFlow(flow),
     });
   }
@@ -454,7 +454,9 @@ export async function startScheduler(workspaceRoot, opts = {}) {
   log.info(`AgentFlow scheduler started. workspace=${path.resolve(workspaceRoot)} poll=${pollMs}ms`);
   while (true) {
     const now = Date.now();
-    for (const flow of listFlowsJson(workspaceRoot)) {
+    const contexts = opts.userId ? [{ userId: opts.userId }] : getAgentflowUserContexts();
+    for (const scheduleCtx of contexts) {
+    for (const flow of listFlowsJson(workspaceRoot, scheduleCtx)) {
       if (flow.archived || flow.source === "builtin") continue;
       const flowSource = flow.source || "user";
       let resumedWaitingRun = false;
@@ -462,7 +464,7 @@ export async function startScheduler(workspaceRoot, opts = {}) {
         if (resumedWaitingRun) break;
         for (const waitState of readWaitStates(run.runDir)) {
           if (!waitState || !waitState.wakeAt || !waitState.instanceId) continue;
-          if (waitState.status === "resuming" && !isFlowCurrentlyRunning(workspaceRoot, flow.id, { lastRunUuid: run.uuid })) {
+          if (waitState.status === "resuming" && !isFlowCurrentlyRunning(workspaceRoot, flow.id, { lastRunUuid: run.uuid }, scheduleCtx)) {
             const nodeStatus = readNodeResultStatus(run.runDir, String(waitState.instanceId));
             writeWaitState(waitState, {
               status: nodeStatus === "pending" ? "waiting" : "resumed",
@@ -472,7 +474,7 @@ export async function startScheduler(workspaceRoot, opts = {}) {
           }
           if (waitState.status !== "waiting") continue;
           if (Date.parse(waitState.wakeAt) > now) continue;
-          if (isFlowCurrentlyRunning(workspaceRoot, flow.id, { lastRunUuid: run.uuid })) continue;
+          if (isFlowCurrentlyRunning(workspaceRoot, flow.id, { lastRunUuid: run.uuid }, scheduleCtx)) continue;
           const nextState = {
             ...waitState,
             status: "resuming",
@@ -480,7 +482,7 @@ export async function startScheduler(workspaceRoot, opts = {}) {
             resumeStartedAt: new Date().toISOString(),
           };
           try {
-            const child = startWaitingRunResume(workspaceRoot, flow, { ...waitState, uuid: run.uuid, runDir: run.runDir });
+            const child = startWaitingRunResume(workspaceRoot, flow, { ...waitState, uuid: run.uuid, runDir: run.runDir }, scheduleCtx);
             nextState.resumePid = child.pid || null;
             writeWaitState(waitState, nextState);
             resumedWaitingRun = true;
@@ -497,41 +499,41 @@ export async function startScheduler(workspaceRoot, opts = {}) {
         }
       }
 
-      const scheduleRes = readFlowSchedule(workspaceRoot, flow.id, flowSource);
+      const scheduleRes = readFlowSchedule(workspaceRoot, flow.id, flowSource, scheduleCtx);
       if (!scheduleRes.success) {
         log.debug(`[scheduler] ${flow.id}: ${scheduleRes.error}`);
         continue;
       }
       const schedule = scheduleRes.schedule;
       if (!schedule.enabled || !schedule.cron) continue;
-      if (hasHigherPriorityDuplicate(workspaceRoot, flow)) {
-        const stateRes = readScheduleState(workspaceRoot, flow.id, flowSource);
+      if (hasHigherPriorityDuplicate(workspaceRoot, flow, scheduleCtx)) {
+        const stateRes = readScheduleState(workspaceRoot, flow.id, flowSource, scheduleCtx);
         writeScheduleState(workspaceRoot, flow.id, flowSource, {
           ...baseState(flow, schedule, stateRes.success ? stateRes.state : {}),
           nextRunAt: null,
           lastError: "workspace flow is shadowed by a user flow with the same id; scheduled run skipped",
           lastErrorAt: new Date().toISOString(),
-        });
+        }, scheduleCtx);
         continue;
       }
-      const stateRes = readScheduleState(workspaceRoot, flow.id, flowSource);
-      let state = ensureNextRunAt(workspaceRoot, flow, schedule, stateRes.success ? stateRes.state : {});
+      const stateRes = readScheduleState(workspaceRoot, flow.id, flowSource, scheduleCtx);
+      let state = ensureNextRunAt(workspaceRoot, flow, schedule, stateRes.success ? stateRes.state : {}, scheduleCtx);
       if (!state.nextRunAt || Date.parse(state.nextRunAt) > now) continue;
 
-      if (isFlowCurrentlyRunning(workspaceRoot, flow.id, state)) {
+      if (isFlowCurrentlyRunning(workspaceRoot, flow.id, state, scheduleCtx)) {
         const nextRunAt = computeNextRunAtFromSchedule(schedule);
         writeScheduleState(workspaceRoot, flow.id, flowSource, {
           ...baseState(flow, schedule, state),
           nextRunAt,
           lastSkippedAt: new Date().toISOString(),
           lastSkipReason: "running",
-        });
+        }, scheduleCtx);
         log.info(`[scheduler] skip ${flow.id}: already running; next=${nextRunAt}`);
         continue;
       }
 
       try {
-        const child = startScheduledRun(workspaceRoot, flow, schedule, state);
+        const child = startScheduledRun(workspaceRoot, flow, schedule, state, scheduleCtx);
         const nextRunAt = computeNextRunAtFromSchedule(schedule);
         writeScheduleState(workspaceRoot, flow.id, flowSource, {
           ...baseState(flow, schedule, state),
@@ -539,7 +541,7 @@ export async function startScheduler(workspaceRoot, opts = {}) {
           lastTriggeredAt: new Date().toISOString(),
           lastPid: child.pid || null,
           lastError: "",
-        });
+        }, scheduleCtx);
         log.info(`[scheduler] triggered ${flow.id}; pid=${child.pid || "?"}; next=${nextRunAt}`);
       } catch (e) {
         const nextRunAt = computeNextRunAtFromSchedule(schedule);
@@ -548,10 +550,11 @@ export async function startScheduler(workspaceRoot, opts = {}) {
           nextRunAt,
           lastError: e && e.message ? e.message : String(e),
           lastErrorAt: new Date().toISOString(),
-        });
+        }, scheduleCtx);
         log.info(`[scheduler] failed ${flow.id}: ${e && e.message ? e.message : String(e)}`);
       }
     }
+    }
     if (once) return;
     await sleep(pollMs);
   }

package/bin/lib/skill-registry.mjs

@@ -0,0 +1,145 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import yaml from "js-yaml";
+
+const fileCache = new Map();
+const CACHE_TTL_MS = 60_000;
+
+function readFileCached(absPath) {
+  const now = Date.now();
+  const cached = fileCache.get(absPath);
+  if (cached && now - cached.ts < CACHE_TTL_MS) return cached.content;
+  try {
+    const content = fs.readFileSync(absPath, "utf-8");
+    fileCache.set(absPath, { content, ts: now });
+    return content;
+  } catch {
+    return null;
+  }
+}
+
+export function stripSkillFrontmatter(content) {
+  const raw = String(content || "");
+  const match = raw.match(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/);
+  return match ? raw.slice(match[0].length).trim() : raw.trim();
+}
+
+function parseSkillFrontmatter(content) {
+  const match = String(content || "").match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    return {};
+  }
+}
+
+export function parseSkillFile(absPath, source = {}) {
+  const content = readFileCached(absPath);
+  if (!content) return null;
+  const meta = parseSkillFrontmatter(content);
+  const name = String(meta.name || path.basename(path.dirname(absPath))).trim();
+  if (!name) return null;
+  const body = stripSkillFrontmatter(content);
+  const sourceId = String(source.source || source.id || "unknown").trim() || "unknown";
+  const sourceLabel = String(source.sourceLabel || source.label || sourceId).trim() || sourceId;
+  return {
+    key: `${sourceId}:${name}`,
+    id: name,
+    name,
+    description: String(meta.description || "").trim(),
+    source: sourceId,
+    sourceLabel,
+    path: absPath,
+    body,
+    content,
+    installedBy: source.installedBy || "",
+  };
+}
+
+export function listSkillFiles(dir) {
+  try {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(dir, entry.name, "SKILL.md"))
+      .filter((skillPath) => fs.existsSync(skillPath));
+  } catch {
+    return [];
+  }
+}
+
+export function workspaceSkillSources(root, prefix, labelPrefix) {
+  if (!root) return [];
+  const abs = path.resolve(root);
+  return [
+    { source: `${prefix}-agents`, sourceLabel: `${labelPrefix}/.agents`, dir: path.join(abs, ".agents", "skills"), installedBy: "filesystem" },
+    { source: `${prefix}-cursor`, sourceLabel: `${labelPrefix}/.cursor`, dir: path.join(abs, ".cursor", "skills"), installedBy: "filesystem" },
+    { source: `${prefix}-codex`, sourceLabel: `${labelPrefix}/.codex`, dir: path.join(abs, ".codex", "skills"), installedBy: "filesystem" },
+  ];
+}
+
+export function defaultSkillSources(packageRoot, workspaceRoot) {
+  const sources = [
+    {
+      source: "builtin",
+      sourceLabel: "AgentFlow",
+      dir: path.join(path.resolve(packageRoot), "skills"),
+      installedBy: "agentflow",
+    },
+  ];
+  if (workspaceRoot) sources.push(...workspaceSkillSources(workspaceRoot, "workspace", "工作区"));
+  const home = os.homedir();
+  sources.push(
+    { source: "global-agents", sourceLabel: "全局 .agents", dir: path.join(home, ".agents", "skills"), installedBy: "global" },
+    { source: "global-cursor", sourceLabel: "全局 .cursor", dir: path.join(home, ".cursor", "skills"), installedBy: "global" },
+    { source: "global-codex", sourceLabel: "全局 .codex", dir: path.join(home, ".codex", "skills"), installedBy: "skillhub" },
+  );
+  return sources;
+}
+
+export function listSkillsFromSources(sources, opts = {}) {
+  const include = new Set((opts.include || []).map((x) => String(x).trim()).filter(Boolean));
+  const exclude = new Set((opts.exclude || []).map((x) => String(x).trim()).filter(Boolean));
+  const skills = [];
+  const warnings = [];
+  const seenKeys = new Set();
+  const seenPaths = new Set();
+  for (const source of sources || []) {
+    const dir = path.resolve(source.dir || "");
+    if (!fs.existsSync(dir)) {
+      if (opts.warnMissing) warnings.push(`skills path not found: ${dir}`);
+      continue;
+    }
+    for (const skillPath of listSkillFiles(dir)) {
+      const skill = parseSkillFile(skillPath, source);
+      if (!skill) continue;
+      if (include.size > 0 && !include.has(skill.name) && !include.has(skill.key)) continue;
+      if (exclude.has(skill.name) || exclude.has(skill.key)) continue;
+      if (seenPaths.has(skill.path)) continue;
+      if (seenKeys.has(skill.key)) continue;
+      seenPaths.add(skill.path);
+      seenKeys.add(skill.key);
+      skills.push(skill);
+    }
+  }
+  skills.sort((a, b) => {
+    const bySource = a.sourceLabel.localeCompare(b.sourceLabel);
+    if (bySource !== 0) return bySource;
+    return a.name.localeCompare(b.name);
+  });
+  return { skills, warnings };
+}
+
+export function listSkills(packageRoot, workspaceRoot, opts = {}) {
+  return listSkillsFromSources(defaultSkillSources(packageRoot, workspaceRoot), opts).skills;
+}
+
+export function readSkillDetail(packageRoot, workspaceRoot, keyOrName) {
+  const wanted = String(keyOrName || "").trim();
+  if (!wanted) return null;
+  const item = listSkills(packageRoot, workspaceRoot).find((skill) => skill.key === wanted || skill.name === wanted);
+  if (!item) return null;
+  return item;
+}