@downcity/agent 1.1.35 → 1.1.43

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

@@ -1,98 +0,0 @@
-/**
- * `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 "@/plugin/builtins/skill/runtime/Discovery.js";
-import { getClaudeSkillSearchRoots } from "@/plugin/builtins/skill/runtime/Paths.js";
-import { loadDowncityConfig } from "@/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/plugin/builtins/skill/Config.ts

@@ -1,51 +0,0 @@
-/**
- * skill plugin 配置读取工具。
- *
- * 关键点（中文）
- * - skill 已迁到 plugin 体系，因此发现路径等配置统一从 `plugins.skill` 读取。
- * - 这里负责把原始 JSON 配置归一化成 runtime 可直接消费的稳定结构。
- */
-
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type {
-  ResolvedSkillPluginConfig,
-  SkillPluginConfig,
-} from "@/plugin/builtins/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/plugin/builtins/skill/PROMPT.ts

@@ -1,9 +0,0 @@
-/**
- * 自动生成文件，请勿手改。
- * 源文件：由同路径 `*.ts.txt` 生成。
- */
-
-// Source: src/plugin/builtins/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/plugin/builtins/skill/PROMPT.ts.txt

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

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

@@ -1,347 +0,0 @@
-/**
- * Skill Plugin。
- *
- * 关键点（中文）
- * - skill 不再作为 service 存在，而是作为显式 action + system 提供者接入 plugin 体系。
- * - `find/install/list/lookup` 全部通过 plugin actions 暴露。
- * - skills overview 文本通过 `plugin.system` 注入，不再依赖 plugin.system。
- */
-
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
-import { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type { Plugin } from "@/plugin/types/Plugin.js";
-import type { JsonObject, JsonValue } from "@/types/common/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 "";
-}
-
-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 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.",
-            },
-          },
-        };
-      },
-    },
-  },
-  };
-}
-
-/**
- * SkillPlugin：技能发现、安装、读取与 system 注入。
- */
-export class SkillPlugin extends BasePlugin {
-  readonly name = "skill";
-
-  constructor(agent: AgentRuntime | null = null) {
-    super(agent);
-    Object.assign(this, createSkillPluginDefinition(this));
-  }
-}

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

@@ -1,14 +0,0 @@
-/**
- * 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

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

@@ -1,17 +0,0 @@
-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 };
-}
-