@downcity/agent 1.1.7 → 1.1.10

package/src/plugin/builtins/skill/Plugin.ts

@@ -0,0 +1,334 @@
+/**
+ * Skill Plugin。
+ *
+ * 关键点（中文）
+ * - skill 不再作为 service 存在，而是作为显式 action + system 提供者接入 plugin 体系。
+ * - `find/install/list/lookup` 全部通过 plugin actions 暴露。
+ * - skills overview 文本通过 `plugin.system` 注入，不再依赖 service.system。
+ */
+
+import type { Plugin } from "@/plugin/types/Plugin.js";
+import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import { isPluginEnabled } from "@/plugin/core/Activation.js";
+import type {
+  SkillPluginFindPayload,
+  SkillPluginInstallPayload,
+  SkillPluginLookupPayload,
+} from "@/plugin/builtins/skill/types/SkillPlugin.js";
+import { SKILL_PLUGIN_ACTIONS } from "@/plugin/builtins/skill/types/SkillPlugin.js";
+import {
+  DEFAULT_SKILL_PLUGIN_CONFIG,
+  readSkillPluginConfig,
+} from "@/plugin/builtins/skill/Config.js";
+import { skillFindCommand, skillInstallCommand } from "@/plugin/builtins/skill/Command.js";
+import {
+  findLearnedSkillExact,
+  listSkills,
+  lookupSkill,
+  searchLearnedSkills,
+} from "@/plugin/builtins/skill/Action.js";
+import { buildSkillsSystemText } from "@/plugin/builtins/skill/runtime/SystemProvider.js";
+import { SKILL_PLUGIN_PROMPT } from "@/plugin/builtins/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 "";
+}
+
+/**
+ * skillPlugin：技能发现、安装、读取与 system 注入。
+ */
+export const skillPlugin: Plugin = {
+  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: skillPlugin, context })) {
+      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 }): 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.",
+            },
+          },
+        };
+      },
+    },
+  },
+};

package/src/plugin/builtins/skill/SkillPromptAssets.ts

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

package/src/plugin/builtins/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 "@/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 "@/plugin/builtins/skill/types/ClaudeSkill.js";
+import type { JsonObject, JsonValue } from "@/utils/types/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/plugin/builtins/skill/runtime/Paths.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 type { DowncityConfig } from "@/config/Config.js";
+import { readSkillPluginConfig } from "../Config.js";
+import type { SkillRoot } from "@/plugin/builtins/skill/types/SkillRoot.js";
+import { expandHome, uniqStrings } from "./Utils.js";
+
+function normalizeSkillRootCandidate(candidate: string): string {
+  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: string, raw: string): string {
+  const expanded = expandHome(raw);
+  return path.isAbsolute(expanded)
+    ? path.normalize(expanded)
+    : path.resolve(projectRoot, expanded);
+}
+
+export function getClaudeSkillSearchRoots(
+  projectRoot: string,
+  config: DowncityConfig,
+): SkillRoot[] {
+  const skillPluginConfig = readSkillPluginConfig(config);
+  const configured = skillPluginConfig.paths.map((x) => String(x));
+
+  const defaultsProject: string[] = [];
+  const defaultsHome = ["~/.agents/skills"];
+
+  const rawConfigured = uniqStrings(configured);
+  const rawProject = uniqStrings(defaultsProject);
+  const rawHome = uniqStrings(defaultsHome);
+
+  const roots: SkillRoot[] = [];
+
+  // 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<string, SkillRoot>();
+  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: string,
+  config: DowncityConfig,
+): { raw: string[]; resolved: string[] } {
+  const roots = getClaudeSkillSearchRoots(projectRoot, config);
+  return {
+    raw: roots.map((r) => r.display),
+    resolved: roots.map((r) => r.resolved),
+  };
+}

package/src/plugin/builtins/skill/runtime/Prompt.ts

@@ -0,0 +1,67 @@
+/**
+ * Skill plugin prompt section 渲染器。
+ *
+ * 关键点（中文）
+ * - 仅负责渲染运行时动态清单（已发现 skills + 扫描根目录）。
+ * - 稳定规则放在 `SkillPromptAssets.ts`，避免分散在代码里维护。
+ * - 仅做字符串渲染，不做文件 IO。
+ */
+
+import type { DowncityConfig } from "@/config/Config.js";
+import { readSkillPluginConfig } from "../Config.js";
+import { getClaudeSkillSearchRoots } from "./Paths.js";
+import type { ClaudeSkill } from "@/plugin/builtins/skill/types/ClaudeSkill.js";
+
+/**
+ * 渲染 skills 系统提示片段。
+ *
+ * 约束（中文）
+ * - 为控制 token 成本，最多展示前 40 个 skill。
+ * - roots 会按扫描顺序输出，便于排查冲突覆盖。
+ */
+export function renderClaudeSkillsPromptSection(
+  projectRoot: string,
+  config: DowncityConfig,
+  skills: ClaudeSkill[],
+): string {
+  const roots = getClaudeSkillSearchRoots(projectRoot, config);
+  const allowExternal = readSkillPluginConfig(config).allowExternalPaths;
+
+  const skillsSection =
+    skills.length > 0
+      ? skills
+          .map((skill) => {
+            const desc = skill.description ? ` - ${skill.description}` : "";
+            return `- **${skill.name}**${desc}`;
+          })
+          .join("\n")
+      : "- (none)";
+
+  const rootsSection =
+    roots.length > 0
+      ? roots
+          .map((root) => {
+            const externalNote =
+              root.source === "config" && !allowExternal
+                ? " (disabled: allowExternalPaths=false)"
+                : "";
+            return `- [${root.source}] ${root.display}${externalNote}`;
+          })
+          .join("\n")
+      : "- (none)";
+
+  return [
+    "# Runtime Skills Inventory",
+    "",
+    `Discovered ${skills.length} learned/installed skill(s).`,
+    "All skills in `Available Skills` are already available locally.",
+    "",
+    "## Available Skills",
+    skillsSection,
+    "",
+    "## Skill Roots (scan order, higher wins on conflicts)",
+    rootsSection,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}