@downcity/agent 1.1.7 → 1.1.10

package/src/plugins/skill/Plugin.ts

@@ -1,355 +0,0 @@
-/**
- * Skill Plugin。
- *
- * 关键点（中文）
- * - skill 不再作为 service 存在，而是作为显式 action + system 提供者接入 plugin 体系。
- * - `find/install/list/lookup` 全部通过 plugin actions 暴露。
- * - skills overview 文本通过 `plugin.system` 注入，不再依赖 service.system。
- */
-
-import type { Plugin } from "@/shared/types/Plugin.js";
-import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
-import { readFileSync } from "node:fs";
-import { isPluginEnabled } from "@/plugin/Activation.js";
-import type {
-  SkillPluginFindPayload,
-  SkillPluginInstallPayload,
-  SkillPluginLookupPayload,
-} from "@/shared/types/SkillPlugin.js";
-import { SKILL_PLUGIN_ACTIONS } from "@/shared/types/SkillPlugin.js";
-import {
-  DEFAULT_SKILL_PLUGIN_CONFIG,
-  readSkillPluginConfig,
-} 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(): string {
-  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: 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() {
-    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 }): 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/plugins/skill/runtime/Discovery.ts

@@ -1,141 +0,0 @@
-/**
- * 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 "@/shared/types/ClaudeSkill.js";
-import type { JsonObject, JsonValue } from "@/shared/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/plugins/skill/runtime/Paths.ts

@@ -1,130 +0,0 @@
-/**
- * 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 "@/shared/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/plugins/skill/runtime/Prompt.ts

@@ -1,67 +0,0 @@
-/**
- * Skill plugin prompt section 渲染器。
- *
- * 关键点（中文）
- * - 仅负责渲染运行时动态清单（已发现 skills + 扫描根目录）。
- * - 稳定规则放在 `plugins/skill/PROMPT.txt`，避免分散在代码里维护。
- * - 仅做字符串渲染，不做文件 IO。
- */
-
-import type { DowncityConfig } from "@/config/Config.js";
-import { readSkillPluginConfig } from "../Config.js";
-import { getClaudeSkillSearchRoots } from "./Paths.js";
-import type { ClaudeSkill } from "@/shared/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");
-}