@downcity/plugins 1.0.52 → 1.0.57

package/src/skill/PROMPT.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/skill/PROMPT.ts.txt
-const TEXT_MODULE_CONTENT = "# Skill Plugin\n\nskill 是你拥有的技能。用户的提出的需求和任务，你都需要先考虑利用相关的skill来高质量的完成。\n\n\n## 使用\n\n使用技能时需要首先通过 `town skill lookup <name>` 命令载入对应的技能内容。\n\n你也可以使用 `town skill --help` 命令对skill进行其他操作。比如 `list`, `find`, `install`等等。\n";
+const TEXT_MODULE_CONTENT = "# Skill Plugin\n\nskill 是你拥有的技能。用户的提出的需求和任务，你都需要先考虑利用相关的skill来高质量的完成。\n\n\n## 使用\n\n使用技能时需要首先通过 `skill` plugin 的 `lookup` action 载入对应的技能内容。\n\n如果当前工具集中存在 `plugin_call`，使用：\n\n```ts\nplugin_call({\n  plugin: \"skill\",\n  action: \"lookup\",\n  payload: {\n    name: \"<skill-name>\",\n  },\n});\n```\n\n可用 action 包括 `list`、`find`、`install`、`lookup`。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/skill/PROMPT.ts.txt

@@ -5,6 +5,18 @@ skill 是你拥有的技能。用户的提出的需求和任务，你都需要
 
 ## 使用
 
-使用技能时需要首先通过 `town skill lookup <name>` 命令载入对应的技能内容。
+使用技能时需要首先通过 `skill` plugin 的 `lookup` action 载入对应的技能内容。
 
-你也可以使用 `town skill --help` 命令对skill进行其他操作。比如 `list`, `find`, `install`等等。
+如果当前工具集中存在 `plugin_call`，使用：
+
+```ts
+plugin_call({
+  plugin: "skill",
+  action: "lookup",
+  payload: {
+    name: "<skill-name>",
+  },
+});
+```
+
+可用 action 包括 `list`、`find`、`install`、`lookup`。

package/src/skill/Plugin.ts

@@ -7,21 +7,17 @@
  * - skills overview 文本通过 `plugin.system` 注入，不再依赖 plugin.system。
  */
 
-import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
-import { isPluginEnabled } from "@downcity/agent/internal/plugin/core/Activation.js";
 import type {
   SkillPluginFindPayload,
   SkillPluginInstallPayload,
   SkillPluginLookupPayload,
+  SkillPluginOptions,
 } from "@/skill/types/SkillPlugin.js";
 import { SKILL_PLUGIN_ACTIONS } from "@/skill/types/SkillPlugin.js";
-import {
-  DEFAULT_SKILL_PLUGIN_CONFIG,
-  readSkillPluginConfig,
-} from "@/skill/Config.js";
+import { resolveSkillPluginOptions } from "@/skill/Config.js";
 import { skillFindCommand, skillInstallCommand } from "@/skill/Command.js";
 import {
   findLearnedSkillExact,
@@ -92,245 +88,239 @@ function inferSkillQueryFromSpec(spec: string): string {
   return "";
 }
 
-function createSkillPluginDefinition(plugin: Plugin): Plugin {
+function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
   return {
     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,
+    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.",
+    async system(context) {
+      const dynamicText = String(
+        await buildSkillsSystemText({
+          rootPath: context.rootPath,
+          options,
+        }),
+      ).trim();
+      return [SKILL_PLUGIN_PROMPT, dynamicText].filter(Boolean).join("\n\n");
     },
-  },
-  availability(context) {
-    if (!isPluginEnabled({ plugin, context })) {
-      return {
-        enabled: false,
-        available: false,
-        reasons: ["skill plugin disabled in project 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 }): SkillPluginFindPayload {
-          const query = String(args[0] || "").trim();
-          if (!query) throw new Error("Missing query");
-          return { query };
+    actions: {
+      [SKILL_PLUGIN_ACTIONS.find]: {
+        command: {
+          description: "查找 `list` 中不存在的未学会 skills（缺失时再 install）",
+          configure(command) {
+            command.argument("<query>");
+          },
+          mapInput({ args }): SkillPluginFindPayload {
+            const query = String(args[0] || "").trim();
+            if (!query) throw new Error("Missing query");
+            return { query };
+          },
         },
-      },
-      async execute(params) {
-        const payload = params.payload as SkillPluginFindPayload;
-        const rootPath = params.context.rootPath;
-        const exactLearned = findLearnedSkillExact(rootPath, payload.query);
-        if (exactLearned) {
+        async execute(params) {
+          const payload = params.payload as SkillPluginFindPayload;
+          const rootPath = params.context.rootPath;
+          const exactLearned = findLearnedSkillExact(
+            rootPath,
+            payload.query,
+            options,
+          );
+          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,
+            options,
+          );
+          await skillFindCommand(payload.query);
           return {
             success: true,
             data: {
               query: payload.query,
-              message: "该技能已在 list 中，无需 install。使用前请先执行 lookup。",
-              workflow: ["list", "lookup"],
-              nextAction: "lookup",
-              learnedSkill: exactLearned,
-              learnedHints: [],
+              message: "已执行缺失技能检索；若目标不在 list 中，可 install 后再 lookup。",
+              workflow: ["find", "install", "lookup"],
+              nextAction: "install",
+              learnedSkill: null,
+              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 }): SkillPluginInstallPayload {
-          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 as SkillPluginInstallPayload;
-        const rootPath = params.context.rootPath;
-        const queryFromSpec = inferSkillQueryFromSpec(payload.spec);
-        const beforeList = listSkills(rootPath).skills;
-        const beforeIds = new Set(beforeList.map((item) => item.id));
+      [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 }): SkillPluginInstallPayload {
+            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 as SkillPluginInstallPayload;
+          const rootPath = params.context.rootPath;
+          const queryFromSpec = inferSkillQueryFromSpec(payload.spec);
+          const beforeList = listSkills(rootPath, options).skills;
+          const beforeIds = new Set(beforeList.map((item) => item.id));
+
+          const learnedBefore =
+            findLearnedSkillExact(rootPath, queryFromSpec, options) ||
+            findLearnedSkillExact(rootPath, payload.spec, options);
+          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, options).skills;
+          const addedSkills = afterList.filter((item) => !beforeIds.has(item.id));
+          const learnedAfter =
+            findLearnedSkillExact(rootPath, queryFromSpec, options) ||
+            findLearnedSkillExact(rootPath, payload.spec, options) ||
+            (addedSkills.length === 1 ? addedSkills[0] : undefined);
 
-        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"],
+              message: "技能学习完成。使用技能前请先执行 lookup 读取该技能的 SKILL.md 内容。",
+              workflow: ["find", "install", "lookup"],
               nextAction: "lookup",
+              skipped: false,
               queryFromSpec,
-              addedSkills: [],
-              learnedSkill: learnedBefore,
+              addedSkills,
+              learnedSkill: learnedAfter || null,
             },
           };
-        }
-
-        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>");
+      [SKILL_PLUGIN_ACTIONS.list]: {
+        command: {
+          description: "列出当前已学会（本地可发现）的 skills",
+          mapInput() {
+            return {};
+          },
         },
-        mapInput({ args }): SkillPluginLookupPayload {
-          const name = String(args[0] || "").trim();
-          if (!name) throw new Error("Missing name");
-          return { name };
+        api: {
+          method: "GET",
         },
-      },
-      api: {
-        method: "POST",
-        async mapInput(c): Promise<SkillPluginLookupPayload> {
-          const body = readJsonObject(await c.req.json());
-          const name = String(body.name || "").trim();
-          if (!name) throw new Error("Missing name");
-          return { name };
+        execute(params) {
+          return {
+            success: true,
+            data: listSkills(params.context.rootPath, options),
+          };
         },
       },
-      async execute(params) {
-        const payload = params.payload as SkillPluginLookupPayload;
-        const result = await lookupSkill({
-          projectRoot: params.context.rootPath,
-          request: {
-            name: payload.name,
+      [SKILL_PLUGIN_ACTIONS.lookup]: {
+        command: {
+          description: "读取已学会 skill 内容（SKILL.md）",
+          configure(command) {
+            command.argument("<name>");
           },
-        });
-        if (!result.success) {
-          return {
-            success: false,
-            error: result.error || "skill lookup failed",
-          };
-        }
+          mapInput({ args }): SkillPluginLookupPayload {
+            const name = String(args[0] || "").trim();
+            if (!name) throw new Error("Missing name");
+            return { name };
+          },
+        },
+        api: {
+          method: "POST",
+          async mapInput(c): Promise<SkillPluginLookupPayload> {
+            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 as SkillPluginLookupPayload;
+          const result = await lookupSkill({
+            projectRoot: params.context.rootPath,
+            request: {
+              name: payload.name,
+            },
+            options,
+          });
+          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();
+          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: {
+          return {
             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.",
+            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.",
+              },
             },
-          },
-        };
+          };
+        },
       },
     },
-  },
   };
 }
 
@@ -340,8 +330,9 @@ function createSkillPluginDefinition(plugin: Plugin): Plugin {
 export class SkillPlugin extends BasePlugin {
   readonly name = "skill";
 
-  constructor(agent: AgentRuntime | null = null) {
-    super(agent);
-    Object.assign(this, createSkillPluginDefinition(this));
+  constructor(options: SkillPluginOptions = {}) {
+    super();
+    const resolvedOptions = resolveSkillPluginOptions(options);
+    Object.assign(this, createSkillPluginDefinition(resolvedOptions));
   }
 }

package/src/skill/runtime/Discovery.ts

@@ -2,7 +2,7 @@
  * Skills discovery：扫描可用 skills 并生成索引。
  *
  * 关键点（中文）
- * - 扫描范围由 `paths.ts` 决定（项目、用户目录、可选外部目录）。
+ * - 扫描范围由 `paths.ts` 决定（项目、用户目录、构造参数路径）。
  * - 同名 skill 按根目录优先级“先到先得”。
  */
 
@@ -10,14 +10,46 @@ import fs from "fs-extra";
 import yaml from "js-yaml";
 import path from "path";
 import type { Dirent, Stats } from "node:fs";
-import type { DowncityConfig } from "@downcity/agent/internal/config/Config.js";
-import { readSkillPluginConfig } from "../Config.js";
+import { resolveSkillPluginOptions } from "../Config.js";
 import { parseFrontMatter } from "./Frontmatter.js";
 import { getClaudeSkillSearchRoots } from "./Paths.js";
-import { isSubpath } from "./Utils.js";
 import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type {
+  SkillPluginIgnoreRule,
+  SkillPluginOptions,
+} from "@/skill/types/SkillPlugin.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
+function matchesIgnoreRule(skill: ClaudeSkill, rule: SkillPluginIgnoreRule): boolean {
+  if (typeof rule === "string") {
+    const value = rule.trim().toLowerCase();
+    if (!value) return false;
+    return skill.id.toLowerCase() === value || skill.name.toLowerCase() === value;
+  }
+  if (rule instanceof RegExp) {
+    rule.lastIndex = 0;
+    const matchesId = rule.test(skill.id);
+    rule.lastIndex = 0;
+    const matchesName = rule.test(skill.name);
+    rule.lastIndex = 0;
+    return matchesId || matchesName;
+  }
+  if (typeof rule === "function") {
+    return rule(skill);
+  }
+  return false;
+}
+
+function shouldIgnoreSkill(
+  skill: ClaudeSkill,
+  rules: SkillPluginIgnoreRule[],
+): boolean {
+  for (const rule of rules) {
+    if (matchesIgnoreRule(skill, rule)) return true;
+  }
+  return false;
+}
+
 /**
  * 扫描并发现 Claude Code-compatible skills。
  *
@@ -34,26 +66,18 @@ import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/commo
  */
 export function discoverClaudeSkillsSync(
   projectRoot: string,
-  config: DowncityConfig,
+  options?: SkillPluginOptions | null,
 ): ClaudeSkill[] {
   const root = String(projectRoot || "").trim();
   if (!root) return [];
-  const allowExternal = readSkillPluginConfig(config).allowExternalPaths;
-  const roots = getClaudeSkillSearchRoots(root, config);
+  const resolvedOptions = resolveSkillPluginOptions(options);
+  const roots = getClaudeSkillSearchRoots(root, resolvedOptions);
 
   const outById = new Map<string, ClaudeSkill>();
 
   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: Stats;
     try {
@@ -122,7 +146,7 @@ export function discoverClaudeSkillsSync(
       const allowedTools =
         meta?.["allowed-tools"] ?? meta?.allowedTools ?? meta?.allowed_tools;
 
-      outById.set(id, {
+      const skill: ClaudeSkill = {
         id,
         name,
         description,
@@ -131,7 +155,9 @@ export function discoverClaudeSkillsSync(
         directoryPath,
         skillMdPath,
         allowedTools,
-      });
+      };
+      if (shouldIgnoreSkill(skill, resolvedOptions.ignore)) continue;
+      outById.set(id, skill);
     }
   }