@downcity/plugins 1.0.56 → 1.0.59

package/src/chat/runtime/ChatChannelCore.ts

@@ -15,16 +15,30 @@ import { getStoredChannelAccountSync } from "@/chat/accounts/Store.js";
 
 const CHAT_CHANNEL_NAMES: ChatChannelName[] = ["telegram", "feishu", "qq"];
 
-type ChatRuntimeBindings = {
+export type ChatRuntimeBindings = {
   getChannelAccountId?(context: AgentContext, channel: ChatChannelName): string;
   resolveChannelAccount?(
     context: AgentContext,
     channel: ChatChannelName,
   ): StoredChannelAccount | null;
   isChannelEnabled?(context: AgentContext, channel: ChatChannelName): boolean;
+  applyChannelRuntimePatch?(params: {
+    /**
+     * 目标渠道。
+     */
+    channel: ChatChannelName;
+    /**
+     * 是否启用该渠道。
+     */
+    enabled?: boolean;
+    /**
+     * 绑定的账号池记录 ID；传入 null 表示清空绑定。
+     */
+    channelAccountId?: string | null;
+  }): void;
 };
 
-function resolveChatPluginBindings(
+export function resolveChatPluginBindings(
   context: AgentContext,
 ): ChatRuntimeBindings | null {
   const candidate = context.agent?.pluginInstances?.get?.("chat") as
@@ -78,10 +92,7 @@ export function resolveChannelAccountId(
   const plugin = resolveChatPluginBindings(context);
   const explicit = String(plugin?.getChannelAccountId?.(context, channel) || "").trim();
   if (explicit) return explicit;
-  const config = context.config.plugins?.chat?.channels?.[channel] as
-    | { channelAccountId?: unknown }
-    | undefined;
-  return String(config?.channelAccountId || "").trim();
+  return "";
 }
 
 /**
@@ -89,7 +100,8 @@ export function resolveChannelAccountId(
  *
  * 关键点（中文）
  * - 优先使用 ChatPlugin 实例上的显式解析逻辑。
- * - 若未命中，再回退到默认全局账号池 `~/.downcity/downcity.db`。
+ * - 若实例只提供 channelAccountId，再从默认全局账号池读取对应账号。
+ * - 不再从 downcity.json 隐式推断运行时账号。
  */
 export function resolveChannelAccount(
   context: AgentContext,
@@ -132,7 +144,7 @@ export function isChatChannelEnabled(
   if (typeof plugin?.isChannelEnabled === "function") {
     return plugin.isChannelEnabled(context, channel);
   }
-  return context.config.plugins?.chat?.channels?.[channel]?.enabled === true;
+  return false;
 }
 
 /**

package/src/chat/runtime/ChatPluginActionRegistry.ts

@@ -198,7 +198,7 @@ export function createChatPluginActions(params: {
     },
     configure: {
       command: {
-        description: "更新 chat 渠道参数（写入 downcity.json，可选立即重载）",
+        description: "更新 chat 渠道运行态参数（可选立即重载）",
         configure(command: Command) {
           command
             .requiredOption("--channel <name>", "指定渠道（telegram|feishu|qq）")

package/src/chat/runtime/PluginPoints.ts

@@ -56,7 +56,7 @@ export const CHAT_PLUGIN_POINTS = {
    *
    * 说明（中文）
    * - 仅做副作用记录，不返回值。
-   * - 典型实现方是 chat-authorization plugin。
+   * - ChatPlugin 内置授权能力会使用该点记录主体快照。
    */
   observePrincipal: "chat.observePrincipal",
   /**
@@ -64,7 +64,7 @@ export const CHAT_PLUGIN_POINTS = {
    *
    * 说明（中文）
    * - 由 chat plugin runtime 在 ingress 阶段显式调用。
-   * - 典型实现方是 chat-authorization plugin。
+   * - ChatPlugin 内置授权能力会使用该点执行角色与权限判定。
    */
   authorizeIncoming: "chat.authorizeIncoming",
   /**
@@ -72,7 +72,7 @@ export const CHAT_PLUGIN_POINTS = {
    *
    * 说明（中文）
    * - 主要用于在 history / queue metadata 中补齐授权上下文。
-   * - 典型实现方是 chat-authorization plugin。
+   * - ChatPlugin 内置授权能力会使用该点补齐用户角色。
    */
   resolveUserRole: "chat.resolveUserRole",
 } as const;

package/src/chat/types/ChannelStatus.ts

@@ -42,7 +42,7 @@ export type ChatChannelStateSnapshot = {
    */
   channel: ChatChannelName;
   /**
-   * 是否在配置中启用（`downcity.json` 的 `plugins.chat.channels.<channel>.enabled`）。
+   * 当前运行态是否启用该渠道。
    */
   enabled: boolean;
   /**

package/src/chat/types/ChatPluginOptions.ts

@@ -0,0 +1,79 @@
+/**
+ * ChatPlugin SDK / runtime 配置类型。
+ *
+ * 关键点（中文）
+ * - ChatPlugin 只接收 queue 行为与 channels 列表。
+ * - 每个 channel 对象自己负责 env / 凭据 / 账号池绑定解析。
+ * - 这样 ChatPlugin 不再理解 Telegram、Feishu、QQ 的具体配置字段。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { StoredChannelAccount } from "@downcity/agent/internal/types/platform/Store.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+
+/**
+ * Chat channel 运行态 patch。
+ */
+export interface ChatChannelRuntimePatch {
+  /**
+   * 是否启用该 channel。
+   */
+  enabled?: boolean;
+  /**
+   * 绑定的账号池记录 ID。
+   *
+   * 说明（中文）
+   * - 传入字符串表示绑定到该账号池记录。
+   * - 传入 `null` 表示清空账号池绑定。
+   */
+  channelAccountId?: string | null;
+}
+
+/**
+ * Chat channel 对象协议。
+ */
+export interface ChatChannel {
+  /**
+   * channel 名称。
+   */
+  readonly name: ChatChannelName;
+  /**
+   * 当前 channel 是否启用。
+   */
+  isEnabled(context: AgentContext): boolean;
+  /**
+   * 当前 channel 绑定的账号池记录 ID。
+   */
+  getChannelAccountId(context: AgentContext): string;
+  /**
+   * 解析当前 channel 的运行态账号。
+   */
+  getAccount(context: AgentContext): StoredChannelAccount | null;
+  /**
+   * 应用运行态配置 patch。
+   */
+  applyRuntimePatch(patch: ChatChannelRuntimePatch): void;
+}
+
+/**
+ * ChatPlugin 显式构造参数。
+ */
+export interface ChatPluginOptions {
+  /**
+   * Chat queue worker 运行配置。
+   *
+   * 说明（中文）
+   * - 可用于不同 client 定制并发、突发合并等行为。
+   * - 这是 queue 行为的唯一运行配置入口。
+   */
+  queue?: Partial<ChatQueueWorkerConfig>;
+  /**
+   * 当前 agent 持有的 chat channels。
+   *
+   * 说明（中文）
+   * - 每个 channel 对象自己负责 env、凭据与账号池绑定解析。
+   * - 未传入时不启用任何 chat channel。
+   */
+  channels?: ChatChannel[];
+}

package/src/image/ImagePlugin.ts

@@ -177,14 +177,32 @@ export class ImagePlugin extends BasePlugin {
   }
 
   /**
-   * 图片插件给模型的最小使用说明。
+   * 图片插件给模型的使用说明。
    */
   system(_context: AgentContext): string {
     return [
-      "Image generation is available through the plugin_call tool.",
-      `Call plugin "${this.name}" action "generate" when the user asks to create, render, draw, or edit an image.`,
-      "Pass a JSON payload with prompt, optional size/aspect_ratio/quality/n, and optional provider_options.",
-      "The generated image files will be attached to the final assistant message automatically.",
+      "# Image Plugin",
+      "",
+      "Use this plugin only when the user asks to generate, create, draw, render, edit, transform, or stylize an image.",
+      "Do not call it for ordinary image analysis or questions about an existing image unless the user asks for a new/edited image output.",
+      "",
+      "Call through `plugin_call`:",
+      "",
+      "```ts",
+      "plugin_call({",
+      `  plugin: "${this.name}",`,
+      '  action: "generate",',
+      "  payload: {",
+      '    prompt: "...",',
+      "  },",
+      "});",
+      "```",
+      "",
+      "Payload rules:",
+      "- `prompt` is required unless `messages` provides the full multimodal image context.",
+      "- Optional common fields: `messages`, `size`, `aspect_ratio`, `ratio`, `quality`, `n`, `count`, `seed`, `provider_options`.",
+      "- Preserve the user's creative intent; do not over-rewrite the prompt unless clarification is necessary.",
+      "- Generated image file parts are saved under project `.downcity/resources` and attached to the final assistant message automatically.",
     ].join("\n");
   }
 

package/src/index.ts

@@ -13,9 +13,13 @@ export {
 } from "./BuiltinPlugins.js";
 export type { BuiltinPluginClass } from "./BuiltinPlugins.js";
 export { ChatPlugin } from "./chat/ChatPlugin.js";
+export {
+  FeishuChannel,
+  QqChannel,
+  TelegramChannel,
+} from "./chat/channels/RuntimeChannel.js";
 export { ImagePlugin } from "./image/ImagePlugin.js";
 export { ChatChannelAccountManager } from "./chat/accounts/ChannelAccountManager.js";
-export { ChatAuthorizationPlugin } from "./auth/Plugin.js";
 export { SkillPlugin } from "./skill/Plugin.js";
 export { WebPlugin } from "./web/Plugin.js";
 export { AsrPlugin } from "./asr/Plugin.js";
@@ -28,8 +32,9 @@ export {
 } from "./auth/runtime/AuthorizationConfig.js";
 export { resolveAuthorizedUserRole } from "./auth/runtime/AuthorizationPolicy.js";
 export {
+  CHAT_AUTHORIZATION_ACTIONS,
   CHAT_AUTHORIZATION_CHANNELS,
-  CHAT_AUTHORIZATION_PLUGIN_NAME,
+  CHAT_AUTHORIZATION_POINTS,
   createDefaultChatAuthorizationRoles,
   isChatAuthorizationChannel,
 } from "./auth/types/AuthPlugin.js";
@@ -38,11 +43,29 @@ export type {
   ChatChannelAccountListItem,
 } from "./chat/types/ChannelAccount.js";
 export type {
-  ChatPluginFeishuOptions,
+  BaseChatChannelOptions,
+  ChatChannelEnv,
+  FeishuChannelOptions,
+  QqChannelOptions,
+  TelegramChannelOptions,
+} from "./chat/channels/RuntimeChannel.js";
+export type {
+  ChatChannel,
+  ChatChannelRuntimePatch,
   ChatPluginOptions,
-  ChatPluginQqOptions,
-  ChatPluginTelegramOptions,
-} from "./chat/ChatPluginTypes.js";
+} from "./chat/types/ChatPluginOptions.js";
+export type {
+  AsrPluginInput,
+  AsrPluginOptions,
+  AsrPluginResult,
+} from "./asr/types/AsrPlugin.js";
+export type {
+  TtsPluginInput,
+  TtsPluginOptions,
+  TtsPluginResult,
+  TtsPluginSimpleAudioResult,
+  TtsPluginUiMessageResult,
+} from "./tts/types/TtsPlugin.js";
 export type {
   ImagePluginContent,
   ImagePluginFileContent,

package/src/skill/Action.ts

@@ -8,8 +8,8 @@
 
 import fs from "fs-extra";
 import path from "node:path";
-import { discoverClaudeSkillsSync } from "@/skill/runtime/Discovery.js";
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import { discoverSkillsSync } from "@/skill/runtime/Discovery.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type {
   SkillListResponse,
@@ -30,7 +30,7 @@ function normalizeAllowedTools(input: JsonValue | undefined): string[] {
   return Array.from(new Set(values));
 }
 
-function toSkillSummary(skill: ClaudeSkill): SkillSummary {
+function toSkillSummary(skill: SkillDefinition): SkillSummary {
   return {
     id: skill.id,
     name: skill.name,
@@ -41,7 +41,10 @@ function toSkillSummary(skill: ClaudeSkill): SkillSummary {
   };
 }
 
-function findSkillExact(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
+function findSkillExact(
+  skills: SkillDefinition[],
+  name: string,
+): SkillDefinition | null {
   const q = String(name || "").trim().toLowerCase();
   if (!q) return null;
 
@@ -52,7 +55,7 @@ function findSkillExact(skills: ClaudeSkill[], name: string): ClaudeSkill | null
   );
 }
 
-function findSkill(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
+function findSkill(skills: SkillDefinition[], name: string): SkillDefinition | null {
   const q = String(name || "").trim().toLowerCase();
   if (!q) return null;
 
@@ -67,9 +70,9 @@ function findSkill(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
 function getSkills(
   projectRoot: string,
   options?: SkillPluginOptions | null,
-): ClaudeSkill[] {
+): SkillDefinition[] {
   const root = path.resolve(projectRoot);
-  return discoverClaudeSkillsSync(root, options);
+  return discoverSkillsSync(root, options);
 }
 
 /**

package/src/skill/Command.ts

@@ -8,8 +8,8 @@
 
 import path from "node:path";
 import { execa } from "execa";
-import { discoverClaudeSkillsSync } from "@/skill/runtime/Discovery.js";
-import { getClaudeSkillSearchRoots } from "@/skill/runtime/Paths.js";
+import { discoverSkillsSync } from "@/skill/runtime/Discovery.js";
+import { getSkillSearchRoots } from "@/skill/runtime/Paths.js";
 
 async function runNpxSkills(args: string[], opts?: { yes?: boolean }): Promise<number> {
   const yes = opts?.yes !== false;
@@ -57,7 +57,7 @@ export async function skillInstallCommand(
   if (!s) throw new Error("Missing spec");
 
   const args: string[] = ["add", s];
-  const agent = String(options.agent || "claude-code").trim();
+  const agent = String(options.agent || "").trim();
   if (agent) args.push("--agent", agent);
 
   const yes = options.yes !== false;
@@ -74,8 +74,8 @@ export async function skillInstallCommand(
  */
 export async function skillListCommand(cwd: string = "."): Promise<void> {
   const projectRoot = path.resolve(String(cwd || "."));
-  const roots = getClaudeSkillSearchRoots(projectRoot);
-  const skills = discoverClaudeSkillsSync(projectRoot);
+  const roots = getSkillSearchRoots(projectRoot);
+  const skills = discoverSkillsSync(projectRoot);
 
   console.log("Skill roots:");
   for (const root of roots) console.log(`- [${root.source}] ${root.display}`);

package/src/skill/Plugin.ts

@@ -166,7 +166,7 @@ function createSkillPluginDefinition(options: SkillPluginOptions): Plugin {
               .argument("<spec>")
               .option("-g, --global", "全局安装（默认 true）", true)
               .option("-y, --yes", "跳过确认（默认 true）", true)
-              .option("--agent <agent>", "指定 agent", "claude-code");
+              .option("--agent <agent>", "指定 agent");
           },
           mapInput({ args, opts }): SkillPluginInstallPayload {
             const spec = String(args[0] || "").trim();

package/src/skill/runtime/Discovery.ts

@@ -12,15 +12,18 @@ import path from "path";
 import type { Dirent, Stats } from "node:fs";
 import { resolveSkillPluginOptions } from "../Config.js";
 import { parseFrontMatter } from "./Frontmatter.js";
-import { getClaudeSkillSearchRoots } from "./Paths.js";
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import { getSkillSearchRoots } from "./Paths.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type {
   SkillPluginIgnoreRule,
   SkillPluginOptions,
 } from "@/skill/types/SkillPlugin.js";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
-function matchesIgnoreRule(skill: ClaudeSkill, rule: SkillPluginIgnoreRule): boolean {
+function matchesIgnoreRule(
+  skill: SkillDefinition,
+  rule: SkillPluginIgnoreRule,
+): boolean {
   if (typeof rule === "string") {
     const value = rule.trim().toLowerCase();
     if (!value) return false;
@@ -41,7 +44,7 @@ function matchesIgnoreRule(skill: ClaudeSkill, rule: SkillPluginIgnoreRule): boo
 }
 
 function shouldIgnoreSkill(
-  skill: ClaudeSkill,
+  skill: SkillDefinition,
   rules: SkillPluginIgnoreRule[],
 ): boolean {
   for (const rule of rules) {
@@ -51,7 +54,7 @@ function shouldIgnoreSkill(
 }
 
 /**
- * 扫描并发现 Claude Code-compatible skills。
+ * 扫描并发现本地 skills。
  *
  * 关键点（中文）
  * - skills 的扫描根目录与 projectRoot 强相关（默认 `.agents/skills`）
@@ -61,19 +64,19 @@ function shouldIgnoreSkill(
  * 发现技能算法（中文）
  * 1) 计算扫描根目录列表
  * 2) 逐目录读取 `SKILL.md` 与 frontmatter
- * 3) 按 id 去重并构造 ClaudeSkill
+ * 3) 按 id 去重并构造 SkillDefinition
  * 4) 最终按 name 排序，保证输出稳定
  */
-export function discoverClaudeSkillsSync(
+export function discoverSkillsSync(
   projectRoot: string,
   options?: SkillPluginOptions | null,
-): ClaudeSkill[] {
+): SkillDefinition[] {
   const root = String(projectRoot || "").trim();
   if (!root) return [];
   const resolvedOptions = resolveSkillPluginOptions(options);
-  const roots = getClaudeSkillSearchRoots(root, resolvedOptions);
+  const roots = getSkillSearchRoots(root, resolvedOptions);
 
-  const outById = new Map<string, ClaudeSkill>();
+  const outById = new Map<string, SkillDefinition>();
 
   for (const r of roots) {
     const sourceRoot = r.resolved;
@@ -146,7 +149,7 @@ export function discoverClaudeSkillsSync(
       const allowedTools =
         meta?.["allowed-tools"] ?? meta?.allowedTools ?? meta?.allowed_tools;
 
-      const skill: ClaudeSkill = {
+      const skill: SkillDefinition = {
         id,
         name,
         description,

package/src/skill/runtime/Paths.ts

@@ -36,7 +36,7 @@ function resolveSkillRootPath(projectRoot: string, raw: string): string {
     : path.resolve(projectRoot, expanded);
 }
 
-export function getClaudeSkillSearchRoots(
+export function getSkillSearchRoots(
   projectRoot: string,
   options?: SkillPluginOptions | null,
 ): SkillRoot[] {
@@ -105,15 +105,3 @@ export function getClaudeSkillSearchRoots(
 
   return Array.from(byResolved.values()).sort((a, b) => a.priority - b.priority);
 }
-
-// Back-compat（内部仅用于 prompt 展示）：保留旧 API 形状，避免外部 import 立刻断裂。
-export function getClaudeSkillSearchPaths(
-  projectRoot: string,
-  options?: SkillPluginOptions | null,
-): { raw: string[]; resolved: string[] } {
-  const roots = getClaudeSkillSearchRoots(projectRoot, options);
-  return {
-    raw: roots.map((r) => r.display),
-    resolved: roots.map((r) => r.resolved),
-  };
-}

package/src/skill/runtime/Prompt.ts

@@ -7,8 +7,8 @@
  * - 仅做字符串渲染，不做文件 IO。
  */
 
-import { getClaudeSkillSearchRoots } from "./Paths.js";
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import { getSkillSearchRoots } from "./Paths.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
 /**
@@ -18,12 +18,12 @@ import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
  * - 为控制 token 成本，最多展示前 40 个 skill。
  * - roots 会按扫描顺序输出，便于排查冲突覆盖。
  */
-export function renderClaudeSkillsPromptSection(
+export function renderSkillsPromptSection(
   projectRoot: string,
   options: SkillPluginOptions | null | undefined,
-  skills: ClaudeSkill[],
+  skills: SkillDefinition[],
 ): string {
-  const roots = getClaudeSkillSearchRoots(projectRoot, options);
+  const roots = getSkillSearchRoots(projectRoot, options);
 
   const skillsSection =
     skills.length > 0

package/src/skill/runtime/Store.ts

@@ -6,7 +6,7 @@
  * - core 不负责也不感知 skill/memory 业务状态
  */
 
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type {
   SessionSkillStateInternal,
   SessionSkillStateSnapshot,
@@ -50,9 +50,12 @@ function getOrCreateState(sessionId: string): SessionSkillStateInternal {
  * 算法（中文）
  * - 以 id 归一化后整体替换，避免残留脏状态。
  */
-export function setSessionAvailableSkills(sessionId: string, skills: ClaudeSkill[]): void {
+export function setSessionAvailableSkills(
+  sessionId: string,
+  skills: SkillDefinition[],
+): void {
   const state = getOrCreateState(sessionId);
-  const next = new Map<string, ClaudeSkill>();
+  const next = new Map<string, SkillDefinition>();
 
   for (const skill of Array.isArray(skills) ? skills : []) {
     const id = String(skill?.id || "").trim();

package/src/skill/runtime/SystemProvider.ts

@@ -8,8 +8,8 @@
  */
 
 import { getSessionRunContext } from "@downcity/agent/internal/executor/SessionRunScope.js";
-import { discoverClaudeSkillsSync } from "./Discovery.js";
-import { renderClaudeSkillsPromptSection } from "./Prompt.js";
+import { discoverSkillsSync } from "./Discovery.js";
+import { renderSkillsPromptSection } from "./Prompt.js";
 import { setSessionAvailableSkills } from "./Store.js";
 import type { SkillPluginOptions } from "@/skill/types/SkillPlugin.js";
 
@@ -35,7 +35,7 @@ export async function buildSkillsSystemText(
   runtime: SkillSystemRuntime,
 ): Promise<string> {
   const sessionId = getCurrentSessionId();
-  const discoveredSkills = discoverClaudeSkillsSync(
+  const discoveredSkills = discoverSkillsSync(
     runtime.rootPath,
     runtime.options,
   );
@@ -44,7 +44,7 @@ export async function buildSkillsSystemText(
     setSessionAvailableSkills(sessionId, discoveredSkills);
   }
 
-  return renderClaudeSkillsPromptSection(
+  return renderSkillsPromptSection(
     runtime.rootPath,
     runtime.options,
     discoveredSkills,

package/src/skill/runtime/Types.ts

@@ -1,4 +1,4 @@
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 
 /**
  * Session skills state 对外快照。
@@ -9,7 +9,7 @@ import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
  */
 export type SessionSkillStateSnapshot = {
   sessionId: string;
-  allSkills: ClaudeSkill[];
+  allSkills: SkillDefinition[];
   updatedAt: number;
 };
 
@@ -17,6 +17,6 @@ export type SessionSkillStateSnapshot = {
  * Session skills state 内部结构。
  */
 export type SessionSkillStateInternal = {
-  allSkillsById: Map<string, ClaudeSkill>;
+  allSkillsById: Map<string, SkillDefinition>;
   updatedAt: number;
 };

package/src/skill/types/{ClaudeSkill.ts → SkillDefinition.ts}

@@ -1,5 +1,5 @@
 /**
- * Claude Code-compatible skill 模型。
+ * Skill 定义模型。
  *
  * 关键点（中文）
  * - skill 最小单元目录为 `<root>/<skill-id>/SKILL.md`。
@@ -11,9 +11,9 @@ import type { SkillRootSource } from "@/skill/types/SkillRoot.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
 /**
- * Claude Code-compatible skill。
+ * 可被 agent 发现与读取的 skill 定义。
  */
-export interface ClaudeSkill {
+export interface SkillDefinition {
   /**
    * skill 稳定标识。
    *

package/src/skill/types/SkillPlugin.ts

@@ -7,7 +7,7 @@
  * - 该文件只描述插件协议，不承载发现、安装或 system 组装逻辑。
  */
 
-import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { SkillDefinition } from "@/skill/types/SkillDefinition.js";
 import type { SkillRootSource } from "@/skill/types/SkillRoot.js";
 
 /**
@@ -80,7 +80,7 @@ export type SkillPluginLookupPayload = {
 export type SkillPluginIgnoreRule =
   | string
   | RegExp
-  | ((skill: ClaudeSkill) => boolean);
+  | ((skill: SkillDefinition) => boolean);
 
 /**
  * SkillPlugin 构造参数。