@downcity/plugins 1.0.4

package/src/skill/Command.ts

@@ -0,0 +1,98 @@
+/**
+ * `city skill` 命令 helper。
+ *
+ * 设计目标（中文）
+ * - 尽量不自建 registry：直接复用社区的 `npx skills` 生态（find/install）。
+ * - 同时提供本地视角的 `list`：列出 Downcity 当前能发现的 skills（含 project/home）。
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import { execa } from "execa";
+import { discoverClaudeSkillsSync } from "@/skill/runtime/Discovery.js";
+import { getClaudeSkillSearchRoots } from "@/skill/runtime/Paths.js";
+import { loadDowncityConfig } from "@downcity/agent/internal/config/Config.js";
+
+async function runNpxSkills(args: string[], opts?: { yes?: boolean }): Promise<number> {
+  const yes = opts?.yes !== false;
+  const result = await execa("npx", [yes ? "-y" : "", "skills", ...args].filter(Boolean), {
+    stdio: "inherit",
+  });
+  return result.exitCode ?? 0;
+}
+
+/**
+ * 执行远程 skill 查找。
+ */
+export async function skillFindCommand(query: string): Promise<void> {
+  const q = String(query || "").trim();
+  if (!q) throw new Error("Missing query");
+  await runNpxSkills(["find", q], { yes: true });
+}
+
+/**
+ * skill 安装选项。
+ */
+export interface SkillInstallOptions {
+  /**
+   * 是否执行全局安装。
+   */
+  global?: boolean;
+  /**
+   * 是否跳过交互确认。
+   */
+  yes?: boolean;
+  /**
+   * 安装目标 agent 名称。
+   */
+  agent?: string;
+}
+
+/**
+ * 安装指定 skill。
+ */
+export async function skillInstallCommand(
+  spec: string,
+  options: SkillInstallOptions = {},
+): Promise<void> {
+  const s = String(spec || "").trim();
+  if (!s) throw new Error("Missing spec");
+
+  const args: string[] = ["add", s];
+  const agent = String(options.agent || "claude-code").trim();
+  if (agent) args.push("--agent", agent);
+
+  const yes = options.yes !== false;
+  if (yes) args.push("-y");
+
+  const globalInstall = options.global !== false;
+  if (globalInstall) args.push("-g");
+
+  await runNpxSkills(args, { yes });
+}
+
+/**
+ * 输出当前项目的本地 skill 列表。
+ */
+export async function skillListCommand(cwd: string = "."): Promise<void> {
+  const projectRoot = path.resolve(String(cwd || "."));
+  const shipJson = path.join(projectRoot, "downcity.json");
+  if (!fs.existsSync(shipJson)) {
+    throw new Error(
+      `downcity.json not found at ${shipJson}. Run "city agent create" first or pass the correct path.`,
+    );
+  }
+
+  const config = loadDowncityConfig(projectRoot);
+  const roots = getClaudeSkillSearchRoots(projectRoot, config);
+  const skills = discoverClaudeSkillsSync(projectRoot, config);
+
+  console.log("Skill roots:");
+  for (const root of roots) console.log(`- [${root.source}] ${root.display}`);
+
+  console.log(`\nFound: ${skills.length}`);
+  for (const skill of skills) {
+    const desc = skill.description ? ` — ${skill.description}` : "";
+    console.log(`- [${skill.source}] ${skill.id}: ${skill.name}${desc}`);
+  }
+}

package/src/skill/Config.ts

@@ -0,0 +1,51 @@
+/**
+ * skill plugin 配置读取工具。
+ *
+ * 关键点（中文）
+ * - skill 已迁到 plugin 体系，因此发现路径等配置统一从 `plugins.skill` 读取。
+ * - 这里负责把原始 JSON 配置归一化成 runtime 可直接消费的稳定结构。
+ */
+
+import type { DowncityConfig } from "@downcity/agent/internal/types/config/DowncityConfig.js";
+import type {
+  ResolvedSkillPluginConfig,
+  SkillPluginConfig,
+} from "@/skill/types/SkillPlugin.js";
+
+/**
+ * skill plugin 默认配置。
+ */
+export const DEFAULT_SKILL_PLUGIN_CONFIG: ResolvedSkillPluginConfig = {
+  paths: [".agents/skills"],
+  allowExternalPaths: false,
+};
+
+/**
+ * 读取并归一化 skill plugin 配置。
+ */
+export function readSkillPluginConfig(
+  config?: DowncityConfig | null,
+): ResolvedSkillPluginConfig {
+  const raw = config?.plugins?.skill;
+  const skillConfig =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as SkillPluginConfig)
+      : null;
+
+  const normalizedPaths = Array.isArray(skillConfig?.paths)
+    ? skillConfig.paths
+        .map((item) => String(item || "").trim())
+        .filter(Boolean)
+    : [];
+
+  return {
+    paths:
+      normalizedPaths.length > 0
+        ? normalizedPaths
+        : [...DEFAULT_SKILL_PLUGIN_CONFIG.paths],
+    allowExternalPaths:
+      typeof skillConfig?.allowExternalPaths === "boolean"
+        ? skillConfig.allowExternalPaths
+        : DEFAULT_SKILL_PLUGIN_CONFIG.allowExternalPaths,
+  };
+}

package/src/skill/PROMPT.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/skill/PROMPT.ts.txt
+const TEXT_MODULE_CONTENT = "# Skill Plugin\n\nskill 是你拥有的技能。用户的提出的需求和任务，你都需要先考虑利用相关的skill来高质量的完成。\n\n\n## 使用\n\n使用技能时需要首先通过 `city skill lookup <name>` 命令载入对应的技能内容。\n\n你也可以使用 `city skill --help` 命令对skill进行其他操作。比如 `list`, `find`, `install`等等。\n";
+
+export default TEXT_MODULE_CONTENT;

package/src/skill/PROMPT.ts.txt

@@ -0,0 +1,10 @@
+# Skill Plugin
+
+skill 是你拥有的技能。用户的提出的需求和任务，你都需要先考虑利用相关的skill来高质量的完成。
+
+
+## 使用
+
+使用技能时需要首先通过 `city skill lookup <name>` 命令载入对应的技能内容。
+
+你也可以使用 `city skill --help` 命令对skill进行其他操作。比如 `list`, `find`, `install`等等。

package/src/skill/Plugin.ts

@@ -0,0 +1,347 @@
+/**
+ * Skill Plugin。
+ *
+ * 关键点（中文）
+ * - skill 不再作为 service 存在，而是作为显式 action + system 提供者接入 plugin 体系。
+ * - `find/install/list/lookup` 全部通过 plugin actions 暴露。
+ * - 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,
+} 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 { skillFindCommand, skillInstallCommand } from "@/skill/Command.js";
+import {
+  findLearnedSkillExact,
+  listSkills,
+  lookupSkill,
+  searchLearnedSkills,
+} from "@/skill/Action.js";
+import { buildSkillsSystemText } from "@/skill/runtime/SystemProvider.js";
+import { SKILL_PLUGIN_PROMPT } from "@/skill/SkillPromptAssets.js";
+
+/**
+ * 读取 JSON object。
+ */
+function readJsonObject(value: JsonValue): JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid JSON body");
+  }
+  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 属性转义。
+ */
+function sanitizeXmlAttr(value: string): string {
+  return String(value || "")
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .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(plugin: Plugin): 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,
+    },
+  },
+  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 };
+        },
+      },
+      async execute(params) {
+        const payload = params.payload as SkillPluginFindPayload;
+        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 }): 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));
+
+        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 }): 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,
+          },
+        });
+        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.",
+            },
+          },
+        };
+      },
+    },
+  },
+  };
+}
+
+/**
+ * SkillPlugin：技能发现、安装、读取与 system 注入。
+ */
+export class SkillPlugin extends BasePlugin {
+  readonly name = "skill";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createSkillPluginDefinition(this));
+  }
+}

package/src/skill/SkillPromptAssets.ts

@@ -0,0 +1,14 @@
+/**
+ * SkillPromptAssets：skill plugin 静态提示词资产。
+ *
+ * 关键点（中文）
+ * - skill prompt 文本真实来源是 `PROMPT.ts.txt`。
+ * - 这里统一做 `trim()`，避免 prompt 裁剪规则散落到运行时逻辑。
+ */
+
+import skillPromptText from "@/skill/PROMPT.js";
+
+/**
+ * skill plugin 稳定提示词。
+ */
+export const SKILL_PLUGIN_PROMPT = skillPromptText.trim();

package/src/skill/runtime/Discovery.ts

@@ -0,0 +1,141 @@
+/**
+ * Skills discovery：扫描可用 skills 并生成索引。
+ *
+ * 关键点（中文）
+ * - 扫描范围由 `paths.ts` 决定（项目、用户目录、可选外部目录）。
+ * - 同名 skill 按根目录优先级“先到先得”。
+ */
+
+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 { parseFrontMatter } from "./Frontmatter.js";
+import { getClaudeSkillSearchRoots } from "./Paths.js";
+import { isSubpath } from "./Utils.js";
+import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.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: string,
+  config: DowncityConfig,
+): ClaudeSkill[] {
+  const root = String(projectRoot || "").trim();
+  if (!root) return [];
+  const allowExternal = readSkillPluginConfig(config).allowExternalPaths;
+  const roots = getClaudeSkillSearchRoots(root, config);
+
+  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 {
+      stat = fs.statSync(sourceRoot);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+
+    let entries: Dirent[] = [];
+    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: JsonObject | null = null;
+      if (frontMatterYaml && frontMatterYaml.trim()) {
+        try {
+          const loaded = yaml.load(frontMatterYaml) as JsonValue;
+          if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
+            meta = loaded as JsonObject;
+          } 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;
+}

package/src/skill/runtime/Frontmatter.ts

@@ -0,0 +1,17 @@
+export type FrontMatterParseResult = {
+  frontMatterYaml: string | null;
+  body: string;
+};
+
+export function parseFrontMatter(markdown: string): FrontMatterParseResult {
+  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 };
+}
+