// Command = 一个 slash command 的定义。
// Command 是程序确定性执行的控制面，不应该让模型自由发挥。
type Command = {
  name: string;        // 命令名，例如 /help、/cost、/mcp。
  description: string; // 给 /help 展示的人类说明。
  usage: string;       // 用法示例，例如 "/mcp list"。
  run(args: string[], ctx: CommandContext): Promise<void>; // 命令真正执行的函数。
};

// CommandContext = 命令执行时能看到的运行时信息。
// 不要把整个 AppRuntime 暴露给命令，避免命令乱改内部状态。
type CommandContext = {
  cwd: string;       // 当前工作目录。
  sessionId: string; // 当前会话 ID，用于查询成本、历史等。
  config: AppConfig; // 已加载配置。
};

// commands = 命令注册表。
// key 是命令名，value 是命令处理器。
const commands = new Map<string, Command>();

// registerCommand = 注册一个 slash command。
// 真实系统里这里还要检查重名，尤其不能让插件覆盖内置命令。
export function registerCommand(command: Command) {
  commands.set(command.name, command);
}

// runCommand = 执行用户输入的 slash command。
export async function runCommand(line: string, ctx: CommandContext) {
  // 简化解析：按空白切分。真实系统要支持 flags、引号、子命令。
  const [name, ...args] = line.trim().split(/\s+/);

  // 根据命令名查注册表。
  const command = commands.get(name);

  if (!command) {
    // 命令不存在时直接给确定性错误，不要交给模型编答案。
    console.log(`Unknown command: ${name}`);
    return;
  }

  // 执行命令。这里不经过模型。
  await command.run(args, ctx);
}

// 注册一个 /cost 命令。
// 它只是读取当前 session 的 token/cost 统计，不需要模型参与。
registerCommand({
  name: "/cost",
  description: "Show token usage and estimated cost.",
  usage: "/cost",
  async run(_args, ctx) {
    // 根据 sessionId 找到这次会话的成本统计。
    const report = await loadCostReport(ctx.sessionId);

    // 格式化后直接打印到终端。
    console.log(formatCostReport(report));
  }
});

下面两个类型体现了 Skill 的两阶段设计:discovery(发现)阶段只扫描出有哪些 skill,用轻量的 manifest(清单,只含名字、描述这类元数据);等某个 skill 真被选中了,才加载完整内容。
provenance 字段记录 skill 从哪来,代码里一共列了六种:builtin 是 CLI 自带的;
user 来自用户个人目录(比如 `~/.claude/skills`);
project 来自当前项目目录;
plugin 由插件带进来;
managed 指托管配置,也就是公司或团队管理员统一下发、个人改不了的那种,类似公司统一推的 IDE 配置;

// SkillManifest = discovery 阶段使用的轻量元数据。
type SkillManifest = {
  name: string;
  description: string;
  sourcePath: string;
  provenance: "builtin" | "user" | "project" | "plugin" | "managed" | "mcp";
  enabled: boolean;
};

// LoadedSkill = 选中后才读取的完整内容。
type LoadedSkill = SkillManifest & {
  instructions: string;
  references: string[];
  scripts: string[];
};

---
name: code-review
description: Review a code diff for concrete bugs, regressions, and missing tests. Use when the user asks for code review; do not use for general explanation or implementation.
---

When reviewing code:
1. Inspect git diff first.
2. Focus on bugs, regressions, missing tests.
3. Report findings with file and line references.
4. Do not summarize before findings.

// discoverSkills = 扫描约定目录，只返回 discovery 元数据。
export async function discoverSkills(roots: string[]): Promise<SkillManifest[]> {
  const files = (await Promise.all(
    roots.map(root => glob("*/SKILL.md", { cwd: root, absolute: true }))
  )).flat();

  return Promise.all(files.map(async file => {
    const text = await readFile(file, "utf8");
    const { frontmatter } = parseMarkdownWithFrontmatter(text);

    return {
      name: frontmatter.name,
      description: frontmatter.description,
      sourcePath: file,
      provenance: inferProvenance(file),
      enabled: true
    };
  }));
}

// loadSkill = 只有 Skill 真正被选中后才加载完整正文和资源清单。
export async function loadSkill(manifest: SkillManifest): Promise<LoadedSkill> {
  const text = await readFile(manifest.sourcePath, "utf8");
  const { body } = parseMarkdownWithFrontmatter(text);
  const baseDir = dirname(manifest.sourcePath);

  return {
    ...manifest,
    instructions: body,
    references: await glob("references/**/*", { cwd: baseDir }),
    scripts: await glob("scripts/**/*", { cwd: baseDir })
  };
}

const discovery = manifests.map(s => `${s.name}: ${s.description}`).join("\n");
const system = `Available skills:\n${discovery}`;

handlers.load_skill = async ({ name }) => {
  const manifest = manifests.find(s => s.name === name);
  if (!manifest) return { error: "unknown_skill", name };
  return await loadSkill(manifest);
};

// Plugin = 一个插件包暴露出来的对象。
// 插件是程序加载的代码，能注册工具、命令、skill，因此风险比 skill 高。
type Plugin = {
  name: string;                         // 插件名，例如 github-tools。
  version: string;                      // 插件版本，用于兼容和排错。
  register(api: PluginApi): Promise<void>; // 插件入口：向 CLI 注册能力。
};

// PluginApi = CLI 暴露给插件的最小注册接口。
// 这里只允许“注册能力”，不直接给插件内部全局对象。
type PluginApi = {
  registerTool(tool: Tool<any, any>): void; // 注册新工具，但执行时仍要过权限系统。
  registerCommand(command: Command): void;  // 注册新 slash command。
  registerSkill(skill: Skill): void;        // 注册新 skill。
};

// loadPlugin = 加载一个插件入口文件。
// 注意：import 插件代码本身就有风险，所以真实系统要先检查 manifest 和权限。
export async function loadPlugin(path: string, api: PluginApi) {
  // 动态加载插件模块。
  const mod = await import(path);

  // 约定插件 default export 是 Plugin 对象。
  const plugin: Plugin = mod.default;

  // 校验插件结构、版本、名称、能力声明。
  validatePlugin(plugin);

  // 让插件注册工具/命令/skill。
  await plugin.register(api);
}

// ParsedCommand = 更完整的命令解析结果。
// 适合 /mcp add github --transport stdio 这种带子命令和 flag 的命令。
type ParsedCommand = {
  name: string;                            // 主命令，例如 /mcp。
  subcommands: string[];                   // 子命令链，例如 ["add", "github"]。
  flags: Record<string, string | boolean>; // --transport stdio 解析成 { transport: "stdio" }。
  args: string[];                          // 普通位置参数。
};

// formatCommandError = 命令错误提示。
// 目标：用户输错时给可恢复建议，而不是让模型猜。
function formatCommandError(input: string, registry: CommandRegistry) {
  // 根据编辑距离找最接近的命令，例如 /hlep -> /help。
  const nearest = findNearestCommand(input, registry.names());

  return [
    `Unknown command: ${input}`,
    nearest ? `Did you mean: ${nearest}?` : "",
    `Run /help to list commands.`
  ]
    // 过滤掉空字符串。
    .filter(Boolean)
    // 每条提示单独一行。
    .join("\n");
}

---
name: code-review
description: Review an existing code diff for bugs, regressions, and missing tests. Use for review requests; do not use when the user asks to implement the change.
---

When reviewing:
1. Inspect git diff first.
2. Prioritize correctness bugs over style.
3. Report findings first with file and line.
4. If no findings, say so and mention residual risk.

input.includes(trigger)

// SkillMatch = 一次 skill 匹配的评分结果。
// 不只返回是否命中，还记录为什么命中，方便 trace 和调试。
type SkillMatch = {
  skill: SkillManifest; // 被评估的 skill manifest。
  score: number;     // 匹配分数，越高越应该注入。
  reasons: string[]; // 命中原因，例如 explicit trigger、semantic match。
};

// matchSkill = 比 includes 更稳的 skill 选择函数。
function matchSkill(skill: Skill, turn: TurnInput): SkillMatch {
  let score = 0;
  const reasons: string[] = [];

  // description 的明确使用场景命中，给较高分。
  if (matchesDeclaredUseCase(skill.description, turn.userText)) {
    score += 10;
    reasons.push("declared use case");
  }

  // 可选的自建语义匹配器；这是实现选择，不是产品事实。
  if (matchesDescriptionEmbedding(skill, turn.userText)) {
    score += 4;
    reasons.push("semantic match");
  }

  // 用户显式写 $skillName，说明一定要用这个 skill。
  if (turn.userText.includes(`$${skill.name}`)) {
    score += 100;
    reasons.push("explicit skill mention");
  }

  // 如果用户说“不要 review”，触发词附近有否定词，要降分。
  if (matchesExclusionBoundary(skill.description, turn.userText)) {
    score -= 20;
    reasons.push("exclusion boundary");
  }

  return { skill, score, reasons };
}

// SkillPolicy = skill 的选择策略。
// 用来处理多个 skill 同时命中时的优先级和互斥关系。
type SkillPolicy = {
  priority: number;        // 优先级，安全/流程类通常更高。
  exclusiveGroup?: string; // 互斥组，同组只选一个，例如多种 planning 流程。
  maxConcurrent?: number;  // 最多允许同时注入几个同类 skill。
};

Selected skills:
- code-review: explicit user requested "review"
- verification-before-completion: completion requires verification

Skipped:
- brainstorming: user asked for review, not design work

// SkillInjection = 最终注入模型的 skill 形态。
// 因为上下文有限，有时不能注入全文，只能注入摘要或引用。
type SkillInjection = {
  skillName: string;                      // skill 名。
  mode: "full" | "summary" | "reference"; // 注入全文、摘要，还是只放引用。
  tokenCost: number;                      // 估算 token 成本。
};

{
  "name": "github-tools",                  // 插件稳定 ID，命令/工具注册时用它做命名空间。
  "version": "1.2.0",                      // 插件版本，用于兼容性检查和升级回滚。
  "entry": "./dist/index.js",              // 入口文件，PluginManager 会 import 这个模块。
  "capabilities": {
    "tools": ["github.searchIssues", "github.createIssue"], // 暴露给模型的可调用工具。
    "commands": ["/github"],                                // 暴露给用户的斜杠命令。
    "skills": ["github-workflow"]                           // 可被 skill matcher 注入的工作流能力。
  },
  "permissions": {
    "network": ["api.github.com"],          // 网络白名单，避免插件随意访问外部地址。
    "filesystem": "none",                  // 文件系统权限；none 表示不允许读写本地文件。
    "secrets": ["GITHUB_TOKEN"]             // 允许读取的密钥名，运行时仍应脱敏审计。
  },
  "engines": {
    "agentCli": ">=0.8.0"                   // 最低 CLI 版本，避免旧 runtime 加载不兼容插件。
  }
}

// PluginApi = 暴露给插件的最小 API。
// 设计原则：只给插件注册能力的入口，不把内部 runtime 全交出去。
type PluginApi = {
  registerTool(tool: ToolDefinition): void;          // 注册工具，执行仍走统一 Tool Executor。
  registerCommand(command: CommandDefinition): void; // 注册 slash command。
  registerSkill(skill: SkillDefinition): void;       // 注册 skill。
  getConfig<T>(key: string): T | undefined;          // 读取插件自己的配置。
  log(event: PluginLogEvent): void;                  // 写插件日志，便于排错。
};

// PluginLifecycle = 插件生命周期钩子。
// 钩子越多，能力越强，风险也越高。
type PluginLifecycle = {
  onLoad?(api: PluginApi): Promise<void>;               // 插件加载时执行，最危险。
  onSessionStart?(session: SessionInfo): Promise<void>; // 新会话开始时执行。
  onSessionEnd?(session: SessionInfo): Promise<void>;   // 会话结束时执行。
  onUnload?(): Promise<void>;                           // 插件卸载时清理资源。
};

// Capability = 插件能力声明。
// 不是简单“插件启用/禁用”，而是细到网络、文件、secret、工具名。
type Capability =
  | { kind: "tool"; names: string[] } // 能注册/调用哪些工具。
  | { kind: "command"; names: string[] } // 能注册哪些命令。
  | { kind: "network"; hosts: string[] } // 能访问哪些域名。
  | { kind: "filesystem"; scope: "none" | "workspace" | "custom"; paths?: string[] } // 文件访问范围。
  | { kind: "secret"; names: string[] }; // 能读取哪些密钥。

// assertCapability = 插件执行敏感动作前的能力检查。
// 插件声明和用户授予的能力必须覆盖这次请求，否则拒绝。
function assertCapability(plugin: PluginIdentity, requested: CapabilityRequest) {
  // 读取这个插件已经被授予的能力。
  const granted = loadGrantedCapabilities(plugin.name);

  // 判断已授予能力是否覆盖本次请求。
  if (!capabilityCovers(granted, requested)) {
    throw new AgentError("PLUGIN_PERMISSION_DENIED", "Plugin lacks capability.", {
      plugin: plugin.name,
      requested
    });
  }
}

// Compatibility = 插件/skill/schema 的兼容性版本。
// 用来防止 CLI 升级后旧插件悄悄失效。
type Compatibility = {
  cliVersion: string;        // CLI 主程序版本。
  pluginApiVersion: string;  // 插件 API 版本。
  toolSchemaVersion: string; // 工具 schema 版本。
  skillSchemaVersion: string;// skill frontmatter/body 规范版本。
};

// CapabilityProvenance = 能力来源记录。
// 当工具失败或行为异常时，要能看出它来自内置、插件、MCP 还是用户配置。
type CapabilityProvenance = {
  name: string;                                  // 能力名，例如 github.createIssue。
  kind: "command" | "tool" | "skill";            // 能力类型。
  source: "builtin" | "plugin" | "mcp" | "user"; // 来源。
  packageName?: string;                          // 如果来自插件/MCP，记录包名。
  version?: string;                              // 来源版本。
  path?: string;                                 // 本地来源路径。
};

Tool github.createIssue failed
source: plugin github-tools@1.2.0
permission: network api.github.com allowed
error: 401 Bad credentials

// PluginSecurityProfile = 插件安全画像。
// 安装、加载、运行三阶段都围绕这个对象做判断。
type PluginSecurityProfile = {
  pluginId: string;                    // 插件稳定 ID，不随展示名变化。
  version: string;                     // 插件版本，用于回滚和兼容判断。
  source: {
    registry: string;                  // 来源仓库或 marketplace。
    packageHash: string;               // 安装包 hash，防止同版本内容漂移。
    signature?: string;                // 可选签名，成熟平台应要求签名。
  };
  declaredCapabilities: Array<
    | "read_workspace"                 // 读取工作区文件。
    | "write_workspace"                // 修改工作区文件。
    | "network"                        // 访问网络。
    | "spawn_process"                  // 启动子进程。
    | "register_tool"                  // 注册工具。
    | "register_skill"                 // 注册 skill。
  >;
  runtimeLimits: {
    maxStartupMs: number;              // 加载超时，防止插件卡住 CLI。
    maxMemoryMb: number;               // 内存上限。
    allowedHosts: string[];            // network capability 的 host 白名单。
  };
};