@downcity/agent 1.1.1

package/bin/plugins/skill/Plugin.js

@@ -0,0 +1,315 @@
+/**
+ * Skill Plugin。
+ *
+ * 关键点（中文）
+ * - skill 不再作为 service 存在，而是作为显式 action + system 提供者接入 plugin 体系。
+ * - `find/install/list/lookup` 全部通过 plugin actions 暴露。
+ * - skills overview 文本通过 `plugin.system` 注入，不再依赖 service.system。
+ */
+import { readFileSync } from "node:fs";
+import { isPluginEnabled } from "../../plugin/Activation.js";
+import { SKILL_PLUGIN_ACTIONS } from "../../shared/types/SkillPlugin.js";
+import { DEFAULT_SKILL_PLUGIN_CONFIG, } from "../../plugins/skill/Config.js";
+import { skillFindCommand, skillInstallCommand } from "../../plugins/skill/Command.js";
+import { findLearnedSkillExact, listSkills, lookupSkill, searchLearnedSkills, } from "../../plugins/skill/Action.js";
+import { buildSkillsSystemText } from "../../plugins/skill/runtime/SystemProvider.js";
+const SKILL_PLUGIN_PROMPT_FILE_URL = new URL("./PROMPT.txt", import.meta.url);
+/**
+ * 加载 skill plugin 稳定提示词。
+ */
+function loadSkillPluginPrompt() {
+    try {
+        return readFileSync(SKILL_PLUGIN_PROMPT_FILE_URL, "utf-8").trim();
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to load skill plugin prompt from ${SKILL_PLUGIN_PROMPT_FILE_URL.pathname}: ${reason}`);
+    }
+}
+const SKILL_PLUGIN_PROMPT = loadSkillPluginPrompt();
+/**
+ * 读取 JSON object。
+ */
+function readJsonObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid JSON body");
+    }
+    return value;
+}
+/**
+ * 读取字符串选项。
+ */
+function getStringOpt(opts, key) {
+    const value = opts[key];
+    return typeof value === "string" ? value.trim() : undefined;
+}
+/**
+ * 读取布尔选项。
+ */
+function getBooleanOpt(opts, key) {
+    const value = opts[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+/**
+ * XML 属性转义。
+ */
+function sanitizeXmlAttr(value) {
+    return String(value || "")
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * 从 install spec 推断候选 skill 标识。
+ */
+function inferSkillQueryFromSpec(spec) {
+    const raw = String(spec || "").trim();
+    if (!raw)
+        return "";
+    const normalized = raw.split(/[?#]/, 1)[0]?.trim() || raw;
+    const atIndex = normalized.lastIndexOf("@");
+    if (atIndex > 0 && atIndex < normalized.length - 1) {
+        return normalized.slice(atIndex + 1).trim();
+    }
+    if (!normalized.includes("/"))
+        return normalized;
+    return "";
+}
+/**
+ * skillPlugin：技能发现、安装、读取与 system 注入。
+ */
+export const skillPlugin = {
+    name: "skill",
+    title: "Skill Catalog And Loader",
+    description: "Finds, installs, lists, and reads local skills, and injects the current skill overview into system prompts so the agent knows what capabilities are available.",
+    config: {
+        plugin: "skill",
+        scope: "project",
+        defaultValue: {
+            ...DEFAULT_SKILL_PLUGIN_CONFIG,
+        },
+    },
+    availability() {
+        if (!isPluginEnabled({ plugin: skillPlugin })) {
+            return {
+                enabled: false,
+                available: false,
+                reasons: ["skill plugin disabled in city config"],
+            };
+        }
+        return {
+            enabled: true,
+            available: true,
+            reasons: [],
+        };
+    },
+    async system(context) {
+        const dynamicText = String(await buildSkillsSystemText(context)).trim();
+        return [SKILL_PLUGIN_PROMPT, dynamicText].filter(Boolean).join("\n\n");
+    },
+    actions: {
+        [SKILL_PLUGIN_ACTIONS.find]: {
+            command: {
+                description: "查找 `list` 中不存在的未学会 skills（缺失时再 install）",
+                configure(command) {
+                    command.argument("<query>");
+                },
+                mapInput({ args }) {
+                    const query = String(args[0] || "").trim();
+                    if (!query)
+                        throw new Error("Missing query");
+                    return { query };
+                },
+            },
+            async execute(params) {
+                const payload = params.payload;
+                const rootPath = params.context.rootPath;
+                const exactLearned = findLearnedSkillExact(rootPath, payload.query);
+                if (exactLearned) {
+                    return {
+                        success: true,
+                        data: {
+                            query: payload.query,
+                            message: "该技能已在 list 中，无需 install。使用前请先执行 lookup。",
+                            workflow: ["list", "lookup"],
+                            nextAction: "lookup",
+                            learnedSkill: exactLearned,
+                            learnedHints: [],
+                        },
+                    };
+                }
+                const learnedHints = searchLearnedSkills(rootPath, payload.query, 5);
+                await skillFindCommand(payload.query);
+                return {
+                    success: true,
+                    data: {
+                        query: payload.query,
+                        message: "已执行缺失技能检索；若目标不在 list 中，可 install 后再 lookup。",
+                        workflow: ["find", "install", "lookup"],
+                        nextAction: "install",
+                        learnedSkill: null,
+                        learnedHints,
+                    },
+                };
+            },
+        },
+        [SKILL_PLUGIN_ACTIONS.install]: {
+            command: {
+                description: "安装 `list` 中不存在的 skill（完成后请先 lookup）",
+                configure(command) {
+                    command
+                        .argument("<spec>")
+                        .option("-g, --global", "全局安装（默认 true）", true)
+                        .option("-y, --yes", "跳过确认（默认 true）", true)
+                        .option("--agent <agent>", "指定 agent", "claude-code");
+                },
+                mapInput({ args, opts }) {
+                    const spec = String(args[0] || "").trim();
+                    if (!spec)
+                        throw new Error("Missing spec");
+                    return {
+                        spec,
+                        global: getBooleanOpt(opts, "global"),
+                        yes: getBooleanOpt(opts, "yes"),
+                        agent: getStringOpt(opts, "agent"),
+                    };
+                },
+            },
+            async execute(params) {
+                const payload = params.payload;
+                const rootPath = params.context.rootPath;
+                const queryFromSpec = inferSkillQueryFromSpec(payload.spec);
+                const beforeList = listSkills(rootPath).skills;
+                const beforeIds = new Set(beforeList.map((item) => item.id));
+                const learnedBefore = findLearnedSkillExact(rootPath, queryFromSpec) ||
+                    findLearnedSkillExact(rootPath, payload.spec);
+                if (learnedBefore) {
+                    return {
+                        success: true,
+                        data: {
+                            spec: payload.spec,
+                            skipped: true,
+                            message: "技能已在 list 中，无需 install。使用前请先执行 lookup。",
+                            workflow: ["list", "lookup"],
+                            nextAction: "lookup",
+                            queryFromSpec,
+                            addedSkills: [],
+                            learnedSkill: learnedBefore,
+                        },
+                    };
+                }
+                await skillInstallCommand(payload.spec, {
+                    global: payload.global,
+                    yes: payload.yes,
+                    agent: payload.agent,
+                });
+                const afterList = listSkills(rootPath).skills;
+                const addedSkills = afterList.filter((item) => !beforeIds.has(item.id));
+                const learnedAfter = findLearnedSkillExact(rootPath, queryFromSpec) ||
+                    findLearnedSkillExact(rootPath, payload.spec) ||
+                    (addedSkills.length === 1 ? addedSkills[0] : undefined);
+                return {
+                    success: true,
+                    data: {
+                        spec: payload.spec,
+                        message: "技能学习完成。使用技能前请先执行 lookup 读取该技能的 SKILL.md 内容。",
+                        workflow: ["find", "install", "lookup"],
+                        nextAction: "lookup",
+                        skipped: false,
+                        queryFromSpec,
+                        addedSkills,
+                        learnedSkill: learnedAfter || null,
+                    },
+                };
+            },
+        },
+        [SKILL_PLUGIN_ACTIONS.list]: {
+            command: {
+                description: "列出当前已学会（本地可发现）的 skills",
+                mapInput() {
+                    return {};
+                },
+            },
+            api: {
+                method: "GET",
+            },
+            execute(params) {
+                return {
+                    success: true,
+                    data: listSkills(params.context.rootPath),
+                };
+            },
+        },
+        [SKILL_PLUGIN_ACTIONS.lookup]: {
+            command: {
+                description: "读取已学会 skill 内容（SKILL.md）",
+                configure(command) {
+                    command.argument("<name>");
+                },
+                mapInput({ args }) {
+                    const name = String(args[0] || "").trim();
+                    if (!name)
+                        throw new Error("Missing name");
+                    return { name };
+                },
+            },
+            api: {
+                method: "POST",
+                async mapInput(c) {
+                    const body = readJsonObject(await c.req.json());
+                    const name = String(body.name || "").trim();
+                    if (!name)
+                        throw new Error("Missing name");
+                    return { name };
+                },
+            },
+            async execute(params) {
+                const payload = params.payload;
+                const result = await lookupSkill({
+                    projectRoot: params.context.rootPath,
+                    request: {
+                        name: payload.name,
+                    },
+                });
+                if (!result.success) {
+                    return {
+                        success: false,
+                        error: result.error || "skill lookup failed",
+                    };
+                }
+                const skillName = String(result.skill?.name || result.skill?.id || "").trim();
+                const openingTag = skillName
+                    ? `<skill name="${sanitizeXmlAttr(skillName)}">`
+                    : "<skill>";
+                const skillUserMessage = [
+                    openingTag,
+                    String(result.content || "").trim(),
+                    "</skill>",
+                ]
+                    .filter(Boolean)
+                    .join("\n")
+                    .trim();
+                return {
+                    success: true,
+                    data: {
+                        success: true,
+                        ...(result.skill ? { skill: result.skill } : {}),
+                        message: "技能内容已准备，下一步将以 `<skill>...</skill>` user message 注入。",
+                        __ship: {
+                            injectUserMessages: [
+                                {
+                                    text: skillUserMessage,
+                                    note: "skill_lookup",
+                                },
+                            ],
+                            suppressToolOutput: true,
+                            toolOutputMessage: "skill lookup success; content injected as <skill> user message.",
+                        },
+                    },
+                };
+            },
+        },
+    },
+};
+//# sourceMappingURL=Plugin.js.map

package/bin/plugins/skill/Plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.js","sourceRoot":"","sources":["../../../src/plugins/skill/Plugin.ts"],"names":[],"mappings":"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"}

package/bin/plugins/skill/runtime/Discovery.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Skills discovery：扫描可用 skills 并生成索引。
+ *
+ * 关键点（中文）
+ * - 扫描范围由 `paths.ts` 决定（项目、用户目录、可选外部目录）。
+ * - 同名 skill 按根目录优先级“先到先得”。
+ */
+import type { DowncityConfig } from "../../../config/Config.js";
+import type { ClaudeSkill } from "../../../shared/types/ClaudeSkill.js";
+/**
+ * 扫描并发现 Claude Code-compatible skills。
+ *
+ * 关键点（中文）
+ * - skills 的扫描根目录与 projectRoot 强相关（默认 `.agents/skills`）
+ * - 这里做成同步函数：启动时扫描一次，产出 prompt section 与 tools 索引
+ */
+/**
+ * 发现技能算法（中文）
+ * 1) 计算扫描根目录列表
+ * 2) 逐目录读取 `SKILL.md` 与 frontmatter
+ * 3) 按 id 去重并构造 ClaudeSkill
+ * 4) 最终按 name 排序，保证输出稳定
+ */
+export declare function discoverClaudeSkillsSync(projectRoot: string, config: DowncityConfig): ClaudeSkill[];
+//# sourceMappingURL=Discovery.d.ts.map

package/bin/plugins/skill/runtime/Discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Discovery.d.ts","sourceRoot":"","sources":["../../../../src/plugins/skill/runtime/Discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAGjE;;;;;;GAMG;AACH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,cAAc,GACrB,WAAW,EAAE,CAuGf"}

package/bin/plugins/skill/runtime/Discovery.js

@@ -0,0 +1,130 @@
+/**
+ * Skills discovery：扫描可用 skills 并生成索引。
+ *
+ * 关键点（中文）
+ * - 扫描范围由 `paths.ts` 决定（项目、用户目录、可选外部目录）。
+ * - 同名 skill 按根目录优先级“先到先得”。
+ */
+import fs from "fs-extra";
+import yaml from "js-yaml";
+import path from "path";
+import { readSkillPluginConfig } from "../Config.js";
+import { parseFrontMatter } from "./Frontmatter.js";
+import { getClaudeSkillSearchRoots } from "./Paths.js";
+import { isSubpath } from "./Utils.js";
+/**
+ * 扫描并发现 Claude Code-compatible skills。
+ *
+ * 关键点（中文）
+ * - skills 的扫描根目录与 projectRoot 强相关（默认 `.agents/skills`）
+ * - 这里做成同步函数：启动时扫描一次，产出 prompt section 与 tools 索引
+ */
+/**
+ * 发现技能算法（中文）
+ * 1) 计算扫描根目录列表
+ * 2) 逐目录读取 `SKILL.md` 与 frontmatter
+ * 3) 按 id 去重并构造 ClaudeSkill
+ * 4) 最终按 name 排序，保证输出稳定
+ */
+export function discoverClaudeSkillsSync(projectRoot, config) {
+    const root = String(projectRoot || "").trim();
+    if (!root)
+        return [];
+    const allowExternal = readSkillPluginConfig(config).allowExternalPaths;
+    const roots = getClaudeSkillSearchRoots(root, config);
+    const outById = new Map();
+    for (const r of roots) {
+        const sourceRoot = r.resolved;
+        // allowExternalPaths 只影响 config 外部路径；home 默认可扫描
+        if (r.source === "config" &&
+            !allowExternal &&
+            !isSubpath(root, sourceRoot)) {
+            continue;
+        }
+        if (!fs.existsSync(sourceRoot))
+            continue;
+        let stat;
+        try {
+            stat = fs.statSync(sourceRoot);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(sourceRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            let isDirectory = entry.isDirectory();
+            if (!isDirectory && entry.isSymbolicLink()) {
+                try {
+                    isDirectory = fs
+                        .statSync(path.join(sourceRoot, entry.name))
+                        .isDirectory();
+                }
+                catch {
+                    isDirectory = false;
+                }
+            }
+            if (!isDirectory)
+                continue;
+            const id = entry.name;
+            if (!id || id.startsWith("."))
+                continue;
+            // 去重：同 id 以 roots 优先级顺序为准（先遇到的 wins）
+            if (outById.has(id))
+                continue;
+            const directoryPath = path.join(sourceRoot, id);
+            const skillMdPath = path.join(directoryPath, "SKILL.md");
+            if (!fs.existsSync(skillMdPath))
+                continue;
+            let content = "";
+            try {
+                content = fs.readFileSync(skillMdPath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const { frontMatterYaml } = parseFrontMatter(content);
+            let meta = null;
+            if (frontMatterYaml && frontMatterYaml.trim()) {
+                try {
+                    const loaded = yaml.load(frontMatterYaml);
+                    if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
+                        meta = loaded;
+                    }
+                    else {
+                        meta = null;
+                    }
+                }
+                catch {
+                    meta = null;
+                }
+            }
+            const name = typeof meta?.name === "string" && meta.name.trim()
+                ? meta.name.trim()
+                : id;
+            const description = typeof meta?.description === "string" ? meta.description.trim() : "";
+            const allowedTools = meta?.["allowed-tools"] ?? meta?.allowedTools ?? meta?.allowed_tools;
+            outById.set(id, {
+                id,
+                name,
+                description,
+                sourceRoot,
+                source: r.source,
+                directoryPath,
+                skillMdPath,
+                allowedTools,
+            });
+        }
+    }
+    const out = Array.from(outById.values());
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return out;
+}
+//# sourceMappingURL=Discovery.js.map

package/bin/plugins/skill/runtime/Discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Discovery.js","sourceRoot":"","sources":["../../../../src/plugins/skill/runtime/Discovery.ts"],"names":[],"mappings":"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"}

package/bin/plugins/skill/runtime/Frontmatter.d.ts

@@ -0,0 +1,6 @@
+export type FrontMatterParseResult = {
+    frontMatterYaml: string | null;
+    body: string;
+};
+export declare function parseFrontMatter(markdown: string): FrontMatterParseResult;
+//# sourceMappingURL=Frontmatter.d.ts.map

package/bin/plugins/skill/runtime/Frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Frontmatter.d.ts","sourceRoot":"","sources":["../../../../src/plugins/skill/runtime/Frontmatter.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAUzE"}

package/bin/plugins/skill/runtime/Frontmatter.js

@@ -0,0 +1,12 @@
+export function parseFrontMatter(markdown) {
+    const text = String(markdown ?? "");
+    if (!text.startsWith("---"))
+        return { frontMatterYaml: null, body: text };
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match)
+        return { frontMatterYaml: null, body: text };
+    const frontMatterYaml = match[1] ?? "";
+    const body = text.slice(match[0].length);
+    return { frontMatterYaml, body };
+}
+//# sourceMappingURL=Frontmatter.js.map

package/bin/plugins/skill/runtime/Frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Frontmatter.js","sourceRoot":"","sources":["../../../../src/plugins/skill/runtime/Frontmatter.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAE1E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEzD,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC"}

package/bin/plugins/skill/runtime/Paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Skills roots resolution.
+ *
+ * 关键点（中文）
+ * - roots 分三类：项目内（project）、用户目录（home），以及配置外部路径（config）
+ * - allowExternalPaths 只控制“配置外部路径（config）”是否可扫描；home 默认始终可扫描
+ * - 兼容 `<any>/skills` 这种布局：如果 root basename 不是 `skills` 且其子目录 `skills/` 存在，则优先扫描 `<root>/skills`
+ */
+import type { DowncityConfig } from "../../../config/Config.js";
+import type { SkillRoot } from "../../../shared/types/SkillRoot.js";
+export declare function getClaudeSkillSearchRoots(projectRoot: string, config: DowncityConfig): SkillRoot[];
+export declare function getClaudeSkillSearchPaths(projectRoot: string, config: DowncityConfig): {
+    raw: string[];
+    resolved: string[];
+};
+//# sourceMappingURL=Paths.d.ts.map

package/bin/plugins/skill/runtime/Paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../../../../src/plugins/skill/runtime/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAyB7D,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,cAAc,GACrB,SAAS,EAAE,CA4Eb;AAGD,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,cAAc,GACrB;IAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAMvC"}

package/bin/plugins/skill/runtime/Paths.js

@@ -0,0 +1,111 @@
+/**
+ * Skills roots resolution.
+ *
+ * 关键点（中文）
+ * - roots 分三类：项目内（project）、用户目录（home），以及配置外部路径（config）
+ * - allowExternalPaths 只控制“配置外部路径（config）”是否可扫描；home 默认始终可扫描
+ * - 兼容 `<any>/skills` 这种布局：如果 root basename 不是 `skills` 且其子目录 `skills/` 存在，则优先扫描 `<root>/skills`
+ */
+import fs from "fs-extra";
+import path from "node:path";
+import { readSkillPluginConfig } from "../Config.js";
+import { expandHome, uniqStrings } from "./Utils.js";
+function normalizeSkillRootCandidate(candidate) {
+    const normalized = path.normalize(candidate);
+    const base = path.basename(normalized);
+    const skillsChild = path.join(normalized, "skills");
+    if (base !== "skills" && fs.existsSync(skillsChild)) {
+        try {
+            if (fs.statSync(skillsChild).isDirectory())
+                return path.normalize(skillsChild);
+        }
+        catch {
+            // ignore
+        }
+    }
+    return normalized;
+}
+function resolveSkillRootPath(projectRoot, raw) {
+    const expanded = expandHome(raw);
+    return path.isAbsolute(expanded)
+        ? path.normalize(expanded)
+        : path.resolve(projectRoot, expanded);
+}
+export function getClaudeSkillSearchRoots(projectRoot, config) {
+    const skillPluginConfig = readSkillPluginConfig(config);
+    const configured = skillPluginConfig.paths.map((x) => String(x));
+    const defaultsProject = [];
+    const defaultsHome = ["~/.agents/skills"];
+    const rawConfigured = uniqStrings(configured);
+    const rawProject = uniqStrings(defaultsProject);
+    const rawHome = uniqStrings(defaultsHome);
+    const roots = [];
+    // 1) project roots（最高优先级）
+    for (const raw of rawProject) {
+        const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
+        roots.push({
+            source: "project",
+            raw,
+            resolved,
+            display: raw,
+            priority: 10,
+            trustedWhenExternalDisabled: true,
+        });
+    }
+    // 2) configured roots：如果在项目内，按 project 处理；否则按 config（受 allowExternalPaths 影响）
+    for (const raw of rawConfigured) {
+        const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
+        const rel = path.relative(projectRoot, resolved);
+        const inside = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+        if (inside) {
+            roots.push({
+                source: "project",
+                raw,
+                resolved,
+                display: raw,
+                priority: 12,
+                trustedWhenExternalDisabled: true,
+            });
+        }
+        else {
+            roots.push({
+                source: "config",
+                raw,
+                resolved,
+                display: raw,
+                priority: 40,
+                trustedWhenExternalDisabled: false,
+            });
+        }
+    }
+    // 3) home root（用户目录）
+    for (const raw of rawHome) {
+        const resolved = normalizeSkillRootCandidate(resolveSkillRootPath(projectRoot, raw));
+        roots.push({
+            source: "home",
+            raw,
+            resolved,
+            display: raw,
+            priority: 20,
+            trustedWhenExternalDisabled: true,
+        });
+    }
+    // 去重：同 resolved 只保留优先级更高的那个（display/raw 以优先级更高者为准）
+    const byResolved = new Map();
+    for (const r of roots) {
+        const key = path.normalize(r.resolved);
+        const prev = byResolved.get(key);
+        if (!prev || r.priority < prev.priority)
+            byResolved.set(key, r);
+    }
+    return Array.from(byResolved.values()).sort((a, b) => a.priority - b.priority);
+}
+// Back-compat（内部仅用于 prompt 展示）：保留旧 API 形状，避免外部 import 立刻断裂。
+export function getClaudeSkillSearchPaths(projectRoot, config) {
+    const roots = getClaudeSkillSearchRoots(projectRoot, config);
+    return {
+        raw: roots.map((r) => r.display),
+        resolved: roots.map((r) => r.resolved),
+    };
+}
+//# sourceMappingURL=Paths.js.map