@fieldwangai/agentflow 0.1.34 → 0.1.36

package/bin/lib/agent-runners.mjs

@@ -711,6 +711,14 @@ function truncateComposerLine(s) {
   return t.slice(0, COMPOSER_STATUS_MAX - 1) + "…";
 }
 
+const RAW_TRACE_MAX_CHARS = 4096;
+
+function rawTraceText(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  if (!text) return "";
+  return text.length > RAW_TRACE_MAX_CHARS ? text.slice(0, RAW_TRACE_MAX_CHARS) + "\n...[truncated]" : text;
+}
+
 function normalizeStreamTextChunk(t) {
   if (!t || typeof t !== "string") return "";
   return t.replace(/\\n/g, "\n").replace(/\\t/g, "\t");
@@ -728,6 +736,7 @@ function extractCursorStreamNlText(event) {
   }
   if (typeof event.text === "string" && event.text.trim()) return normalizeStreamTextChunk(event.text);
   if (typeof event.thinking === "string" && event.thinking.trim()) return normalizeStreamTextChunk(event.thinking);
+  if (typeof event.delta === "string" && event.delta.trim()) return normalizeStreamTextChunk(event.delta);
   return "";
 }
 
@@ -864,6 +873,7 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
     for (const line of lines) {
       try {
         const event = JSON.parse(line);
+        emit({ type: "raw", source: "cursor", stream: "stdout", eventType: event?.type || "unknown", text: rawTraceText(event) });
         if (event.type === "assistant" && event.message?.content) {
           const text = extractCursorStreamNlText(event);
           if (text) {
@@ -903,6 +913,7 @@ export function runCursorAgentWithPrompt(cliWorkspace, promptText, options = {})
           emit({ type: "status", line: `${t("runner.event_label")}: ${event.type ?? "unknown"}` });
         }
       } catch (_) {
+        emit({ type: "raw", source: "cursor", stream: "stdout", eventType: "line", text: rawTraceText(line) });
         if (line.includes('"type":"tool_call"') || line.includes('"type": "tool_call"')) {
           let subtype = "?";
           try {
@@ -1017,6 +1028,7 @@ export function runOpenCodeAgentWithPrompt(cliWorkspace, promptText, options = {
       const line = outBuf.slice(0, idx);
       outBuf = outBuf.slice(idx + 1);
       if (line) {
+        emit({ type: "raw", source: "opencode", stream: "stdout", eventType: "line", text: rawTraceText(line) });
         tryEmitOpenCodeLineAsNatural(line, emit);
         emit({ type: "status", line: `[stdout] ${truncateComposerLine(line)}` });
       }
@@ -1032,6 +1044,7 @@ export function runOpenCodeAgentWithPrompt(cliWorkspace, promptText, options = {
       const line = errBuf.slice(0, idx);
       errBuf = errBuf.slice(idx + 1);
       if (line) {
+        emit({ type: "raw", source: "opencode", stream: "stderr", eventType: "line", text: rawTraceText(line) });
         tryEmitOpenCodeLineAsNatural(line, emit);
         emit({ type: "status", line: `[stderr] ${truncateComposerLine(line)}` });
       }
@@ -1051,10 +1064,12 @@ export function runOpenCodeAgentWithPrompt(cliWorkspace, promptText, options = {
       child.stderr.removeAllListeners();
       child.removeAllListeners();
       if (outBuf.trim()) {
+        emit({ type: "raw", source: "opencode", stream: "stdout", eventType: "tail", text: rawTraceText(outBuf.trim()) });
         tryEmitOpenCodeLineAsNatural(outBuf.trim(), emit);
         emit({ type: "status", line: truncateComposerLine(outBuf.trim()) });
       }
       if (errBuf.trim()) {
+        emit({ type: "raw", source: "opencode", stream: "stderr", eventType: "tail", text: rawTraceText(errBuf.trim()) });
         tryEmitOpenCodeLineAsNatural(errBuf.trim(), emit);
         emit({ type: "status", line: `[opencode_stderr] ${truncateComposerLine(errBuf.trim())}` });
       }
@@ -1151,6 +1166,7 @@ export function runClaudeCodeAgentWithPrompt(cliWorkspace, promptText, options =
     for (const line of lines) {
       try {
         const event = JSON.parse(line);
+        emit({ type: "raw", source: "claude-code", stream: "stdout", eventType: event?.type || "unknown", text: rawTraceText(event) });
         if (event.type === "assistant" && event.message && Array.isArray(event.message.content)) {
           for (const block of event.message.content) {
             if (!block || typeof block !== "object") continue;
@@ -1196,6 +1212,7 @@ export function runClaudeCodeAgentWithPrompt(cliWorkspace, promptText, options =
           emit({ type: "status", line: `${t("runner.event_label")}: ${event.type ?? "unknown"}` });
         }
       } catch (_) {
+        emit({ type: "raw", source: "claude-code", stream: "stdout", eventType: "line", text: rawTraceText(line) });
         emit({ type: "status", line: truncateComposerLine(line) });
       }
     }

package/bin/lib/auth.mjs

@@ -23,6 +23,10 @@ function sessionsPath() {
   return path.join(authRoot(), "sessions.json");
 }
 
+function userAllowlistPath() {
+  return path.join(authRoot(), "user-allowlist.json");
+}
+
 function readJsonObject(filePath) {
   try {
     if (!fs.existsSync(filePath)) return {};
@@ -82,6 +86,57 @@ export function authSetupRequired() {
   return Object.keys(readAuthUsers()).length === 0;
 }
 
+function normalizeUserAllowlistInput(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || "").trim()).filter(Boolean);
+  if (typeof value === "string") {
+    return value
+      .split(/[\s,;]+/g)
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+export function readUserAllowlist() {
+  const fromEnv = normalizeUserAllowlistInput(process.env.AGENTFLOW_USER_WHITELIST || process.env.AGENTFLOW_ALLOWED_USERS || "");
+  let fromFile = [];
+  try {
+    const p = userAllowlistPath();
+    if (fs.existsSync(p)) {
+      const data = JSON.parse(fs.readFileSync(p, "utf-8"));
+      fromFile = normalizeUserAllowlistInput(Array.isArray(data) ? data : data?.users);
+    }
+  } catch {
+    fromFile = [];
+  }
+  const users = Array.from(new Set([...fromFile, ...fromEnv].map((item) => String(item || "").trim()).filter(Boolean)));
+  return { enabled: users.length > 0, users, path: userAllowlistPath() };
+}
+
+function userAllowlistMatchSet(users) {
+  const out = new Set();
+  for (const user of users) {
+    const raw = String(user || "").trim().toLowerCase();
+    if (raw) out.add(raw);
+    const safe = sanitizeAgentflowUserId(user);
+    if (safe) out.add(safe);
+  }
+  return out;
+}
+
+export function isAuthUserAllowed(user) {
+  const allowlist = readUserAllowlist();
+  if (!allowlist.enabled) return true;
+  const allowed = userAllowlistMatchSet(allowlist.users);
+  const candidates = [
+    String(user?.userId || "").trim().toLowerCase(),
+    String(user?.username || "").trim().toLowerCase(),
+    sanitizeAgentflowUserId(user?.userId),
+    sanitizeAgentflowUserId(user?.username),
+  ].filter(Boolean);
+  return candidates.some((candidate) => allowed.has(candidate));
+}
+
 function listFlowDirs(root) {
   try {
     if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) return [];
@@ -184,6 +239,9 @@ export function loginOrCreateUser(username, password) {
   if (!userId) {
     return { ok: false, error: "用户名须以字母开头，仅可使用字母、数字、下划线与连字符，最多 64 字符" };
   }
+  if (!isAuthUserAllowed({ userId, username: String(username || "").trim() })) {
+    return { ok: false, forbidden: true, error: "用户不在白名单中，请联系管理员开通访问权限" };
+  }
   const pwd = String(password || "");
   if (pwd.length < 4) return { ok: false, error: "密码至少 4 位" };
 

package/bin/lib/catalog-flows.mjs

@@ -257,11 +257,13 @@ export function listNodesJson(workspaceRoot, flowId, flowSource, opts = {}) {
   addFromDir(path.join(root, PROJECT_NODES_DIR), "project");
   for (const manifest of listMarketplaceNodes(root, marketplaceFlowData)) {
     let type = "agent";
-    const runtimeType = String(manifest.runtime?.type || manifest.type || "").toLowerCase();
+    const runtimeType = String(manifest.baseDefinitionId || manifest.runtime?.type || manifest.type || "").toLowerCase();
     if (runtimeType.startsWith("control")) type = "control";
     else if (runtimeType.startsWith("provide")) type = "provide";
     byId.set(manifest.definitionId, {
       id: manifest.definitionId,
+      baseDefinitionId: manifest.baseDefinitionId || manifest.runtime?.type || "",
+      marketplaceDefinitionId: manifest.definitionId,
       packageId: manifest.id,
       version: manifest.version,
       type,

package/bin/lib/composer-agent.mjs

@@ -106,6 +106,7 @@ export function buildScriptContentBlockForInstances(flowYamlAbs, instanceIds) {
  * @param {string} [opts.modelKey]
  * @param {boolean} [opts.force]
  * @param {(ev: object) => void} [opts.onStreamEvent]
+ * @param {(subtype: string, toolName: string) => void} [opts.onToolCall]
  * @returns {{ child: import('child_process').ChildProcess, finished: Promise<void> }}
  */
 export function startComposerAgent(opts) {
@@ -123,6 +124,7 @@ export function startComposerAgent(opts) {
 
   const common = {
     onStreamEvent: opts.onStreamEvent,
+    onToolCall: opts.onToolCall,
     force: Boolean(opts.force),
     env,
   };
@@ -267,6 +269,8 @@ function buildAgentStepPrompt(step, flowContext) {
     parts.push(
       "## 上下文已就绪（禁止 forage）\n" +
       "- 节点定义见上方 schema 表，**禁止** Glob/Read `builtin/nodes/`、`.workspace/agentflow/nodes/`、历史 `runBuild/` 来推断节点结构。\n" +
+      "- 默认不要读取、搜索或 Glob 历史运行产物；除非用户明确要求分析历史 run/log，否则检索时必须排除 `**/runBuild/**`、`**/logs/**`、`.workspace/agentflow/**/runBuild/**`、`~/agentflow/runBuild/**`、`node_modules/**`、`dist/**`。\n" +
+      "- 不要从历史 runBuild/logs 中推断业务事实、指标资产或 skill 文档；优先读取当前 workspace 的源文件、analytics-docs、skills、配置与用户给出的上下文。\n" +
       "- 目标 instance 的当前 YAML 已附上（若 instanceId 已知）；tool_nodejs 节点引用的 .mjs 脚本内容也已附上（若存在）。\n" +
       "- 如需查看整份 flow，仅在确实需要时读取一次。"
     );

package/bin/lib/composer-skill-router.mjs

@@ -13,7 +13,11 @@
  */
 import fs from "fs";
 import path from "path";
-import { listSkills as registryListSkills, readSkillDetail as registryReadSkillDetail } from "./skill-registry.mjs";
+import {
+  listSkills as registryListSkills,
+  listUniqueSkills as registryListUniqueSkills,
+  readSkillDetail as registryReadSkillDetail,
+} from "./skill-registry.mjs";
 
 // ─── 意图模式定义 ─────────────────────────────────────────────────────────
 
@@ -126,7 +130,7 @@ function readFileCached(absPath) {
 }
 
 export function listComposerSkills(packageRoot, workspaceRoot) {
-  return registryListSkills(packageRoot, workspaceRoot).map(({ body, content, ...skill }) => skill);
+  return registryListUniqueSkills(packageRoot, workspaceRoot).map(({ body, content, ...skill }) => skill);
 }
 
 export function readComposerSkillDetail(packageRoot, workspaceRoot, keyOrName) {
@@ -140,9 +144,24 @@ export function loadResourcesForSkillKeys(skillKeys, packageRoot, workspaceRoot)
   const wanted = new Set(skillKeys.map((x) => String(x || "").trim()).filter(Boolean));
   if (wanted.size === 0) return { skills: [], references: [], skillsHint: "", hasContext: false };
 
-  const skills = [];
-  for (const item of registryListSkills(packageRoot, workspaceRoot)) {
+  const exactByKey = new Map(registryListSkills(packageRoot, workspaceRoot).map((item) => [item.key, item]));
+  const candidateItems = [];
+  const seenKeys = new Set();
+  for (const item of registryListUniqueSkills(packageRoot, workspaceRoot)) {
     if (!wanted.has(item.key) && !wanted.has(item.name)) continue;
+    candidateItems.push(item);
+    seenKeys.add(item.key);
+  }
+  for (const key of wanted) {
+    const exact = exactByKey.get(key);
+    if (exact && !seenKeys.has(exact.key)) {
+      candidateItems.push(exact);
+      seenKeys.add(exact.key);
+    }
+  }
+
+  const skills = [];
+  for (const item of candidateItems) {
     skills.push({
       id: item.name,
       content: item.body,

package/bin/lib/git-worktree.mjs

@@ -165,8 +165,42 @@ export function listGitWorktrees(repoRoot) {
 }
 
 export function findRegisteredWorktree(repoRoot, worktreePath) {
-  const target = path.resolve(worktreePath);
-  return listGitWorktrees(repoRoot).find((entry) => path.resolve(entry.path) === target) || null;
+  const target = canonicalPathForCompare(worktreePath);
+  return listGitWorktrees(repoRoot).find((entry) => canonicalPathForCompare(entry.path) === target) || null;
+}
+
+function canonicalPathForCompare(rawPath) {
+  const abs = path.resolve(String(rawPath || ""));
+  try {
+    return fs.realpathSync.native(abs);
+  } catch {
+    /* missing path: canonicalize the nearest existing parent */
+  }
+  const missingParts = [];
+  let cursor = abs;
+  while (cursor && !fs.existsSync(cursor)) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    missingParts.unshift(path.basename(cursor));
+    cursor = parent;
+  }
+  try {
+    return path.join(fs.realpathSync.native(cursor), ...missingParts);
+  } catch {
+    return abs;
+  }
+}
+
+function pruneGitWorktrees(repoRoot) {
+  const result = runGit(["worktree", "prune", "--expire", "now"], repoRoot);
+  if (result.status !== 0) {
+    throw new Error(`git worktree prune failed: ${result.stderr || result.stdout}`);
+  }
+}
+
+function isMissingRegisteredWorktreeError(result) {
+  const text = String(result?.stderr || result?.stdout || "");
+  return /missing but already registered worktree/i.test(text);
 }
 
 function branchExists(repoRoot, branch) {
@@ -187,7 +221,7 @@ function actualWorktreeBranch(worktreePath) {
   return branch === "HEAD" ? "DETACHED" : branch;
 }
 
-export function loadGitWorktree({ repoPath, branch = "", worktreePath = "", pipelineWorkspace }) {
+export function loadGitWorktree({ repoPath, branch = "", worktreePath = "", pipelineWorkspace, force = false, pruneMissing = true }) {
   const repoRoot = resolveGitRepoRoot(repoPath);
   const wantedBranch = String(branch || "").trim();
   const target = path.resolve(worktreePath || defaultWorktreePath(pipelineWorkspace || repoRoot, repoRoot, wantedBranch));
@@ -196,7 +230,7 @@ export function loadGitWorktree({ repoPath, branch = "", worktreePath = "", pipe
     throw new Error(`branch does not exist in repoPath: ${wantedBranch}`);
   }
 
-  const registered = findRegisteredWorktree(repoRoot, target);
+  let registered = findRegisteredWorktree(repoRoot, target);
   if (fs.existsSync(target)) {
     if (!registered) {
       throw new Error(`worktreePath exists but is not registered for repoPath: ${target}`);
@@ -205,11 +239,26 @@ export function loadGitWorktree({ repoPath, branch = "", worktreePath = "", pipe
       throw new Error(`worktreePath branch mismatch: expected ${wantedBranch}, got ${registered.branch || "DETACHED"}`);
     }
   } else {
+    if (registered && pruneMissing) {
+      pruneGitWorktrees(repoRoot);
+      registered = findRegisteredWorktree(repoRoot, target);
+    }
+    if (registered && !force) {
+      throw new Error(`worktreePath is missing but still registered: ${target}; set pruneMissing=true or force=true`);
+    }
     fs.mkdirSync(path.dirname(target), { recursive: true });
-    const args = wantedBranch
-      ? ["worktree", "add", target, wantedBranch]
-      : ["worktree", "add", "--detach", target, "HEAD"];
-    const result = runGit(args, repoRoot);
+    const args = ["worktree", "add"];
+    if (force) args.push("--force");
+    if (wantedBranch) {
+      args.push(target, wantedBranch);
+    } else {
+      args.push("--detach", target, "HEAD");
+    }
+    let result = runGit(args, repoRoot);
+    if (result.status !== 0 && pruneMissing && isMissingRegisteredWorktreeError(result)) {
+      pruneGitWorktrees(repoRoot);
+      result = runGit(args, repoRoot);
+    }
     if (result.status !== 0) {
       throw new Error(`git worktree add failed: ${result.stderr || result.stdout}`);
     }

package/bin/lib/locales/en.json

@@ -329,6 +329,10 @@
       "displayName": "Image Display",
       "description": "Preview an image URL, data URL, or image path on the Workspace canvas and pass the source downstream"
     },
+    "display_chart": {
+      "displayName": "Chart Display",
+      "description": "Render ChartSpec/ECharts JSON on the Workspace canvas and pass the JSON downstream"
+    },
     "provide_str": {
       "displayName": "Text",
       "description": "Provide a text value directly, value will be passed to downstream as-is"

package/bin/lib/locales/zh.json

@@ -329,6 +329,10 @@
       "displayName": "图片展示",
       "description": "在 Workspace 画布中预览图片 URL、data URL 或图片路径，并将来源继续传给下游"
     },
+    "display_chart": {
+      "displayName": "图表展示",
+      "description": "在 Workspace 画布中渲染 ChartSpec/ECharts JSON，并将 JSON 继续传给下游"
+    },
     "provide_str": {
       "displayName": "文本",
       "description": "直接提供一段文本，value 会原样供下游引用"

package/bin/lib/marketplace.mjs

@@ -85,12 +85,21 @@ function normalizeManifest(raw, packageDir, source = "workspace") {
   const version = raw.version != null ? String(raw.version).trim() : "";
   if (!id || !version) return null;
   const runtime = raw.runtime && typeof raw.runtime === "object" ? raw.runtime : {};
+  const baseDefinitionId =
+    raw.baseDefinitionId != null && String(raw.baseDefinitionId).trim() !== ""
+      ? String(raw.baseDefinitionId).trim()
+      : raw.sourceDefinitionId != null && String(raw.sourceDefinitionId).trim() !== ""
+        ? String(raw.sourceDefinitionId).trim()
+        : runtime.type != null && String(runtime.type).trim() !== ""
+          ? String(runtime.type).trim()
+          : "";
   return {
     ...raw,
     id,
     version,
     packageDir,
     definitionId: `marketplace:${id}@${version}`,
+    baseDefinitionId,
     displayName: raw.displayName != null ? String(raw.displayName) : raw.name != null ? String(raw.name) : id,
     description: raw.description != null ? String(raw.description) : "",
     input: normalizeSlotList(raw.input || raw.inputs),
@@ -176,8 +185,11 @@ function depMatchesNode(dep, id, version) {
 }
 
 function instanceMatchesNode(inst, id, version) {
-  const parsed = parseMarketplaceDefinitionId(inst?.definitionId);
-  return Boolean(parsed && parsed.id === id && (!parsed.version || parsed.version === version));
+  const parsed =
+    parseMarketplaceDefinitionId(inst?.definitionId) ||
+    parseMarketplaceDefinitionId(inst?.marketplaceRef);
+  if (parsed) return Boolean(parsed.id === id && (!parsed.version || parsed.version === version));
+  return inst?.marketplacePackageId === id && (inst?.marketplaceVersion == null || String(inst.marketplaceVersion) === version);
 }
 
 export function listMarketplaceNodeUsages(workspaceRoot, id, version, opts = {}) {
@@ -349,6 +361,7 @@ export function listMarketplacePackages(workspaceRoot, opts = {}) {
     id: n.id,
     version: n.version,
     definitionId: n.definitionId,
+    baseDefinitionId: n.baseDefinitionId,
     displayName: n.displayName,
     description: n.description,
     inputs: n.input,
@@ -440,7 +453,7 @@ export function writeFlowMarketplaceLock(workspaceRoot, flowDir, flowData) {
   if (!flowData || !flowData.instances || typeof flowData.instances !== "object") return null;
   const nodes = {};
   for (const inst of Object.values(flowData.instances)) {
-    const defId = inst && inst.definitionId;
+    const defId = inst && (inst.marketplaceRef || inst.definitionId);
     const resolved = resolveMarketplaceNodePackage(workspaceRoot, flowDir, defId, flowData);
     if (!resolved) continue;
     nodes[resolved.id] = {
@@ -630,6 +643,7 @@ export function publishNodeFromInstance(workspaceRoot, payload = {}, options = {
   const label = String(payload.label || payload.instanceId || "node").trim();
   const id = safePackageId(payload.id || payload.packageId || label);
   const version = normalizeVersion(payload.version || "1.0.0");
+  const sourceDefinitionId = String(payload.definitionId || "").trim();
   if (!id) return { ok: false, error: "Invalid package id" };
 
   const inputs = normalizeSlotList(payload.inputs || payload.input).map((slot) => ({
@@ -667,7 +681,7 @@ export function publishNodeFromInstance(workspaceRoot, payload = {}, options = {
           command: script,
         }
       : {
-          type: "agent_subAgent",
+          type: sourceDefinitionId || "agent_subAgent",
         }
   );
   const manifest = {
@@ -675,6 +689,7 @@ export function publishNodeFromInstance(workspaceRoot, payload = {}, options = {
     version,
     name: label,
     description,
+    baseDefinitionId: sourceDefinitionId || runtime.type || "agent_subAgent",
     runtime,
     inputs,
     outputs,
@@ -693,6 +708,8 @@ export function publishNodeFromInstance(workspaceRoot, payload = {}, options = {
     version,
     packageDir: dest,
     definitionId: `marketplace:${id}@${version}`,
+    baseDefinitionId: manifest.baseDefinitionId,
+    marketplaceDefinitionId: `marketplace:${id}@${version}`,
     packagedFiles: packagedScript?.packagedFiles || [],
   };
 }

package/bin/lib/runtime-context.mjs

@@ -1,4 +1,5 @@
 import path from "path";
+import yaml from "js-yaml";
 import { getFlowDir } from "./workspace.mjs";
 import { PACKAGE_ROOT, PIPELINES_DIR } from "./paths.mjs";
 import { listSkills, listSkillsFromSources, workspaceSkillSources } from "./skill-registry.mjs";
@@ -118,6 +119,7 @@ function skillBodyFromRegistryItem(skill) {
     name: skill.name,
     key: skill.key,
     description: skill.description,
+    frontmatter: skill.frontmatter,
     source: skill.source,
     sourceLabel: skill.sourceLabel,
     path: skill.path,
@@ -201,6 +203,7 @@ export function buildSkillsContext({ workspaceContext, source = "current-workspa
       name: s.name,
       key: s.key,
       description: s.description,
+      frontmatter: s.frontmatter,
       sourceLabel: s.sourceLabel,
       path: s.path,
       body: s.body,
@@ -208,18 +211,33 @@ export function buildSkillsContext({ workspaceContext, source = "current-workspa
   };
 }
 
+function renderSkillFrontmatter(frontmatter) {
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) return "";
+  const extra = Object.fromEntries(
+    Object.entries(frontmatter).filter(([key, value]) => {
+      if (key === "name" || key === "description") return false;
+      if (value == null) return false;
+      if (typeof value === "string" && value.trim() === "") return false;
+      return true;
+    }),
+  );
+  if (Object.keys(extra).length === 0) return "";
+  return yaml.dump(extra, { lineWidth: 100, noRefs: true }).trim();
+}
+
 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 [
+    const frontmatter = renderSkillFrontmatter(skill.frontmatter);
+    const header = [
       `### ${skill.name}`,
       skill.description ? `说明：${skill.description}` : "",
       `来源：${skill.path || skill.sourceLabel || ""}`,
-      "",
-      body.slice(0, 16000),
+      frontmatter ? `元数据：\n${frontmatter}` : "",
     ].filter(Boolean).join("\n");
+    return [header, body.slice(0, 16000)].filter(Boolean).join("\n\n");
   });
-  return ["## 已加载 Skills", "", ...blocks].join("\n\n");
+  return ["## 已加载 Skills", ...blocks].join("\n\n");
 }

package/bin/lib/skill-registry.mjs

@@ -5,6 +5,15 @@ import yaml from "js-yaml";
 
 const fileCache = new Map();
 const CACHE_TTL_MS = 60_000;
+const SOURCE_PRIORITY = new Map([
+  ["workspace-agents", 100],
+  ["workspace-codex", 95],
+  ["workspace-cursor", 90],
+  ["builtin", 80],
+  ["global-agents", 70],
+  ["global-codex", 65],
+  ["global-cursor", 60],
+]);
 
 function readFileCached(absPath) {
   const now = Date.now();
@@ -29,7 +38,8 @@ function parseSkillFrontmatter(content) {
   const match = String(content || "").match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
   if (!match) return {};
   try {
-    return yaml.load(match[1]) || {};
+    const parsed = yaml.load(match[1]) || {};
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
   }
@@ -49,6 +59,7 @@ export function parseSkillFile(absPath, source = {}) {
     id: name,
     name,
     description: String(meta.description || "").trim(),
+    frontmatter: meta,
     source: sourceId,
     sourceLabel,
     path: absPath,
@@ -62,7 +73,15 @@ export function listSkillFiles(dir) {
   try {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
     return fs.readdirSync(dir, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
+      .filter((entry) => {
+        if (entry.isDirectory()) return true;
+        if (!entry.isSymbolicLink()) return false;
+        try {
+          return fs.statSync(path.join(dir, entry.name)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
       .map((entry) => path.join(dir, entry.name, "SKILL.md"))
       .filter((skillPath) => fs.existsSync(skillPath));
   } catch {
@@ -132,14 +151,41 @@ export function listSkillsFromSources(sources, opts = {}) {
   return { skills, warnings };
 }
 
+function skillPriority(skill) {
+  return SOURCE_PRIORITY.get(String(skill?.source || "")) ?? 0;
+}
+
+export function dedupeSkillsByName(skills) {
+  const byName = new Map();
+  for (const skill of Array.isArray(skills) ? skills : []) {
+    const name = String(skill?.name || skill?.id || "").trim();
+    if (!name) continue;
+    const existing = byName.get(name);
+    if (!existing || skillPriority(skill) > skillPriority(existing)) {
+      byName.set(name, skill);
+    }
+  }
+  return Array.from(byName.values()).sort((a, b) => {
+    const bySource = String(a.sourceLabel || "").localeCompare(String(b.sourceLabel || ""));
+    if (bySource !== 0) return bySource;
+    return String(a.name || "").localeCompare(String(b.name || ""));
+  });
+}
+
 export function listSkills(packageRoot, workspaceRoot, opts = {}) {
   return listSkillsFromSources(defaultSkillSources(packageRoot, workspaceRoot), opts).skills;
 }
 
+export function listUniqueSkills(packageRoot, workspaceRoot, opts = {}) {
+  return dedupeSkillsByName(listSkills(packageRoot, workspaceRoot, opts));
+}
+
 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);
+  const all = listSkills(packageRoot, workspaceRoot);
+  const item = all.find((skill) => skill.key === wanted)
+    || dedupeSkillsByName(all).find((skill) => skill.name === wanted);
   if (!item) return null;
   return item;
 }