@downcity/plugins 1.0.174 → 1.0.193

package/src/skill/Plugin.ts

@@ -3,7 +3,8 @@
  *
  * 关键点（中文）
  * - skill 不再作为 service 存在，而是作为显式 action + system 提供者接入 plugin 体系。
- * - `find/install/list/lookup` 全部通过 plugin actions 暴露。
+ * - `find/install` action 只返回 Shell 操作提示，不执行命令或修改文件。
+ * - `list/lookup` action 负责读取当前可发现的本地 skill。
  * - skills overview 文本通过 `plugin.system` 注入，不再依赖 plugin.system。
  */
 
@@ -21,14 +22,15 @@ import type {
 } from "@/skill/types/SkillPlugin.js";
 import { SKILL_PLUGIN_ACTIONS } from "@/skill/types/SkillPlugin.js";
 import { resolveSkillPluginOptions } from "@/skill/Config.js";
-import { skillFindCommand, skillInstallCommand } from "@/skill/Command.js";
 import {
-  findLearnedSkillExact,
   listSkills,
   lookupSkill,
-  searchLearnedSkills,
 } from "@/skill/Action.js";
 import { buildSkillsSystemText } from "@/skill/runtime/SystemProvider.js";
+import {
+  render_skill_find_prompt,
+  render_skill_install_prompt,
+} from "@/skill/runtime/Prompt.js";
 import { SKILL_PLUGIN_PROMPT } from "@/skill/SkillPromptAssets.js";
 
 /**
@@ -41,28 +43,6 @@ function readJsonObject(value: JsonValue): JsonObject {
   return value as JsonObject;
 }
 
-/**
- * 读取字符串选项。
- */
-function getStringOpt(
-  opts: Record<string, JsonValue>,
-  key: string,
-): string | undefined {
-  const value = opts[key];
-  return typeof value === "string" ? value.trim() : undefined;
-}
-
-/**
- * 读取布尔选项。
- */
-function getBooleanOpt(
-  opts: Record<string, JsonValue>,
-  key: string,
-): boolean | undefined {
-  const value = opts[key];
-  return typeof value === "boolean" ? value : undefined;
-}
-
 /**
  * XML 属性转义。
  */
@@ -74,61 +54,49 @@ function sanitizeXmlAttr(value: string): string {
     .replace(/>/g, "&gt;");
 }
 
-/**
- * 从 install spec 推断候选 skill 标识。
- */
-function inferSkillQueryFromSpec(spec: string): string {
-  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 "";
-}
-
 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.",
-    async system(context) {
+      "Lists and reads local skills, and injects scan-aware discovery and installation guidance into system prompts.",
+    async system(context, run_context) {
       const dynamicText = String(
         await buildSkillsSystemText({
           rootPath: context.rootPath,
           options,
-        }),
+        }, run_context),
       ).trim();
       return [SKILL_PLUGIN_PROMPT, dynamicText].filter(Boolean).join("\n\n");
     },
     actions: {
       [SKILL_PLUGIN_ACTIONS.find]: createAction({
-        description: "Find unlearned skills that are not in `list`; install only if missing.",
+        description:
+          "Return shell instructions for finding a skill. This action does not execute the search.",
         input_schema: {
           zod: z.object({
-            query: z.string(),
+            query: z.string().trim().min(1),
           }),
           json_schema: {
             type: "object",
             required: ["query"],
             properties: {
-              query: { type: "string", description: "Skill search query." },
+              query: {
+                type: "string",
+                description: "Skill search query.",
+              },
             },
           },
         },
         examples: [
           {
-            title: "Find skill",
-            payload: { query: "web-search" },
+            title: "Get skill search instructions",
+            payload: { query: "web access" },
           },
         ],
         command: {
-          description: "Find unlearned skills that are not in `list`; install only if missing.",
+          description:
+            "Return shell instructions for finding a skill without executing the search.",
           configure(command) {
             command.argument("<query>");
           },
@@ -138,144 +106,69 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
             return { query };
           },
         },
-        async execute(params): Promise<PluginActionResult<JsonObject>> {
+        execute(params): PluginActionResult<JsonObject> {
           const payload = params.input as SkillPluginFindPayload;
-          const rootPath = params.context.rootPath;
-          const exactLearned = findLearnedSkillExact(
-            rootPath,
-            payload.query,
-            options,
-          );
-          if (exactLearned) {
-            return {
-              success: true,
-              data: {
-                query: payload.query,
-                message: "This skill is already in list; installation is not needed. Run lookup before using it.",
-                workflow: ["list", "lookup"],
-                nextAction: "lookup",
-                learnedSkill: exactLearned,
-                learnedHints: [],
-              } as JsonObject,
-            };
-          }
-
-          const learnedHints = searchLearnedSkills(
-            rootPath,
-            payload.query,
-            5,
-            options,
-          );
-          await skillFindCommand(payload.query);
           return {
             success: true,
+            message: "Skill search instructions ready; no search was executed.",
             data: {
+              kind: "instructions",
               query: payload.query,
-              message: "Missing-skill search completed. If the target is not in list, install it and then run lookup.",
-              workflow: ["find", "install", "lookup"],
-              nextAction: "install",
-              learnedSkill: null,
-              learnedHints,
-            } as JsonObject,
+              prompt: render_skill_find_prompt(payload.query),
+            },
           };
         },
       }),
       [SKILL_PLUGIN_ACTIONS.install]: createAction({
-        description: "Install a skill that is not in `list`; run lookup after installation.",
+        description:
+          "Return scan-aware shell instructions for installing a skill. This action does not install anything.",
         input_schema: {
           zod: z.object({
-            spec: z.string(),
-            global: z.boolean().optional(),
-            yes: z.boolean().optional(),
-            agent: z.string().optional(),
+            spec: z.string().trim().min(1),
           }),
           json_schema: {
             type: "object",
             required: ["spec"],
             properties: {
-              spec: { type: "string", description: "Skill installation spec." },
-              global: { type: "boolean", description: "Whether to install globally." },
-              yes: { type: "boolean", description: "Skip confirmation." },
-              agent: { type: "string", description: "Target agent." },
+              spec: {
+                type: "string",
+                description: "Skill installation source or spec.",
+              },
             },
           },
         },
         examples: [
           {
-            title: "Install skill",
-            payload: { spec: "web-search", global: true, yes: true },
+            title: "Get skill installation instructions",
+            payload: { spec: "owner/repository@skill-name" },
           },
         ],
         command: {
-          description: "Install a skill that is not in `list`; run lookup after installation.",
+          description:
+            "Return scan-aware shell instructions without installing a skill.",
           configure(command) {
-            command
-              .argument("<spec>")
-              .option("-g, --global", "全局安装（默认 true）", true)
-              .option("-y, --yes", "跳过确认（默认 true）", true)
-              .option("--agent <agent>", "指定 agent");
+            command.argument("<spec>");
           },
-          mapInput({ args, opts }): SkillPluginInstallPayload {
+          mapInput({ args }): 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"),
-            };
+            return { spec };
           },
         },
-        async execute(params): Promise<PluginActionResult<JsonObject>> {
+        execute(params): PluginActionResult<JsonObject> {
           const payload = params.input 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: "The skill is already in list; installation is not needed. Run lookup before using it.",
-                workflow: ["list", "lookup"],
-                nextAction: "lookup",
-                queryFromSpec,
-                addedSkills: [],
-                learnedSkill: learnedBefore,
-              } as JsonObject,
-            };
-          }
-
-          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);
-
           return {
             success: true,
+            message: "Skill installation instructions ready; no files were changed.",
             data: {
+              kind: "instructions",
               spec: payload.spec,
-              message: "Skill learning completed. Before using the skill, run lookup to read its SKILL.md content.",
-              workflow: ["find", "install", "lookup"],
-              nextAction: "lookup",
-              skipped: false,
-              queryFromSpec,
-              addedSkills,
-              learnedSkill: learnedAfter || null,
-            } as JsonObject,
+              prompt: render_skill_install_prompt(
+                params.context.rootPath,
+                options,
+                payload.spec,
+              ),
+            },
           };
         },
       }),
@@ -405,7 +298,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
 }
 
 /**
- * SkillPlugin：技能发现、安装、读取与 system 注入。
+ * SkillPlugin：技能发现、读取与扫描感知的 system 注入。
  */
 export class SkillPlugin extends BasePlugin {
   readonly name = "skill";

package/src/skill/runtime/Prompt.ts

@@ -2,30 +2,119 @@
  * Skill plugin prompt section 渲染器。
  *
  * 关键点（中文）
- * - 仅负责渲染运行时动态清单（已发现 skills + 扫描根目录）。
+ * - 负责渲染运行时动态清单，以及 find/install action 返回的纯提示词。
  * - 稳定规则放在 `SkillPromptAssets.ts`，避免分散在代码里维护。
  * - 仅做字符串渲染，不做文件 IO。
  */
 
 import { getSkillSearchRoots } from "./Paths.js";
 import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
+import type { SkillRoot } from "@/skill/types/SkillRoot.js";
 import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
+/**
+ * 把外部输入编码为单个 POSIX Shell 参数。
+ *
+ * 关键点（中文）：action 只返回提示词，但提示中的命令仍需避免把 query/spec 解释为额外 Shell 语法。
+ */
+function quote_shell_argument(value: string): string {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * 根据已配置扫描根生成安装位置提示。
+ */
+function render_install_root_instructions(
+  roots: SkillRoot[],
+  spec_argument: string,
+): string {
+  if (roots.length === 0) {
+    return [
+      "- No scan roots are configured.",
+      "  Do not install a skill until the SkillPlugin configuration provides a discoverable root.",
+    ].join("\n");
+  }
+
+  return roots
+    .map((root) => {
+      if (root.source === "project") {
+        return [
+          `- [project] Install from the project root with \`npx -y skills add ${spec_argument} -y\`.`,
+          `  The installed skill must end up under \`${root.resolved}/<skill-id>/SKILL.md\`.`,
+        ].join("\n");
+      }
+      if (root.source === "home") {
+        return [
+          `- [home] Install globally with \`npx -y skills add ${spec_argument} -g -y\`.`,
+          `  The installed skill must end up under \`${root.resolved}/<skill-id>/SKILL.md\`.`,
+        ].join("\n");
+      }
+      return [
+        `- [custom] Install or copy the skill into \`${root.resolved}/<skill-id>/SKILL.md\`.`,
+        "  The skills CLI has no generic custom-root flag, so verify the final path instead of assuming installation succeeded.",
+      ].join("\n");
+    })
+    .join("\n");
+}
+
+/**
+ * 生成 find action 返回的纯提示词。
+ */
+export function render_skill_find_prompt(query: string): string {
+  const query_argument = quote_shell_argument(query);
+  return [
+    "# Find Skill Instructions",
+    "",
+    "This action only returns instructions. It has not searched for or installed anything.",
+    "Use the available web or browser capability to search these Skill catalogs:",
+    "- https://www.skills.sh/",
+    "- https://app.lobehub.com/community/skill",
+    `Use the available shell tool to run \`npx -y skills find ${query_argument}\`.`,
+    "Compare the catalog and CLI results, then choose an installation spec before calling the `skill.install` action.",
+  ].join("\n");
+}
+
+/**
+ * 生成 install action 返回的扫描感知纯提示词。
+ */
+export function render_skill_install_prompt(
+  project_root: string,
+  options: SkillPluginOptions | null | undefined,
+  spec: string,
+): string {
+  const roots = getSkillSearchRoots(project_root, options);
+  const spec_argument = quote_shell_argument(spec);
+  return [
+    "# Install Skill Instructions",
+    "",
+    "This action only returns instructions. It has not installed or changed any files.",
+    "Install only into one of the configured scan roots:",
+    render_install_root_instructions(roots, spec_argument),
+    "",
+    [
+      "After the shell installation command completes, call",
+      "`plugin_call({ plugin: \"skill\", action: \"list\", payload: {} })`",
+      "and check whether the new skill appears. Then call `skill.lookup` before using it.",
+    ].join(" "),
+  ].join("\n");
+}
+
 /**
  * 渲染 skills 系统提示片段。
  *
  * 约束（中文）
  * - 为控制 token 成本，最多展示前 40 个 skill。
  * - roots 会按扫描顺序输出，便于排查冲突覆盖。
+ * - 查找与安装指引必须根据实际 roots 生成，不能假设固定安装范围。
  */
-export function renderSkillsPromptSection(
-  projectRoot: string,
+export function render_skills_prompt_section(
+  project_root: string,
   options: SkillPluginOptions | null | undefined,
   skills: SkillDefinition[],
 ): string {
-  const roots = getSkillSearchRoots(projectRoot, options);
+  const roots = getSkillSearchRoots(project_root, options);
 
-  const skillsSection =
+  const skills_section =
     skills.length > 0
       ? skills
           .map((skill) => {
@@ -35,15 +124,20 @@ export function renderSkillsPromptSection(
           .join("\n")
       : "- (none)";
 
-  const rootsSection =
+  const roots_section =
     roots.length > 0
       ? roots
           .map((root) => {
-            return `- [${root.source}] ${root.display}`;
+            return `- [${root.source}] ${root.display} -> ${root.resolved}`;
           })
           .join("\n")
       : "- (none)";
 
+  const ignore_notice =
+    Array.isArray(options?.ignore) && options.ignore.length > 0
+      ? "Configured ignore rules are active. A matching skill will not appear in `list`, even if its files exist in a scan root."
+      : "";
+
   return [
     "# Runtime Skills Inventory",
     "",
@@ -51,10 +145,16 @@ export function renderSkillsPromptSection(
     "All skills in `Available Skills` are already available locally.",
     "",
     "## Available Skills",
-    skillsSection,
+    skills_section,
     "",
     "## Skill Roots (scan order, higher wins on conflicts)",
-    rootsSection,
+    roots_section,
+    "",
+    "## Missing Skill Workflow",
+    "Call `skill.find` with the search query to receive Shell search instructions.",
+    "After choosing a spec, call `skill.install` to receive scan-aware installation instructions.",
+    "Both actions return prompts only. They do not execute commands or change files.",
+    ignore_notice,
   ]
     .filter(Boolean)
     .join("\n");

package/src/skill/runtime/SystemProvider.ts

@@ -7,9 +7,9 @@
  * - `lookup` 行为为无状态：由 action 读取 SKILL.md 后通过协议注入 user message
  */
 
-import { getSessionRunContext } from "@downcity/agent";
+import type { PluginRunContext } from "@downcity/agent";
 import { discoverSkillsSync } from "./Discovery.js";
-import { renderSkillsPromptSection } from "./Prompt.js";
+import { render_skills_prompt_section } from "./Prompt.js";
 import { setSessionAvailableSkills } from "./Store.js";
 import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
@@ -18,11 +18,6 @@ type SkillSystemRuntime = {
   options?: SkillPluginOptions | null;
 };
 
-function getCurrentSessionId(): string {
-  const run_context = getSessionRunContext();
-  return String(run_context?.sessionId || "").trim();
-}
-
 /**
  * 构建 skill plugin system 文本。
  *
@@ -33,8 +28,9 @@ function getCurrentSessionId(): string {
  */
 export async function buildSkillsSystemText(
   runtime: SkillSystemRuntime,
+  run_context?: PluginRunContext,
 ): Promise<string> {
-  const sessionId = getCurrentSessionId();
+  const sessionId = String(run_context?.sessionId || "").trim();
   const discoveredSkills = discoverSkillsSync(
     runtime.rootPath,
     runtime.options,
@@ -44,7 +40,7 @@ export async function buildSkillsSystemText(
     setSessionAvailableSkills(sessionId, discoveredSkills);
   }
 
-  return renderSkillsPromptSection(
+  return render_skills_prompt_section(
     runtime.rootPath,
     runtime.options,
     discoveredSkills,

package/src/skill/types/SkillPlugin.ts

@@ -15,11 +15,11 @@ import type { SkillRootSource } from "@/skill/types/SkillRoot.js";
  */
 export const SKILL_PLUGIN_ACTIONS = {
   /**
-   * 查找 skill。
+   * 返回查找 skill 的 Shell 操作提示。
    */
   find: "find",
   /**
-   * 安装 skill。
+   * 返回扫描感知的安装提示。
    */
   install: "install",
   /**
@@ -33,35 +33,23 @@ export const SKILL_PLUGIN_ACTIONS = {
 } as const;
 
 /**
- * skill 查找输入。
+ * skill 查找提示 action 输入。
  */
 export type SkillPluginFindPayload = {
   /**
-   * 用户输入的 skill 查询词。
+   * 需要查找的 skill 关键词。
    */
   query: string;
 };
 
 /**
- * skill 安装输入。
+ * skill 安装提示 action 输入。
  */
 export type SkillPluginInstallPayload = {
   /**
-   * skill 安装 spec。
+   * `skills` CLI 接受的安装来源或 skill spec。
    */
   spec: string;
-  /**
-   * 是否全局安装。
-   */
-  global?: boolean;
-  /**
-   * 是否跳过确认。
-   */
-  yes?: boolean;
-  /**
-   * 安装目标 agent 名称。
-   */
-  agent?: string;
 };
 
 /**