// 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 = 一份可复用任务规程。
// Skill 不直接执行动作，而是被注入给模型，影响模型怎么做事。
type Skill = {
  name: string;         // 稳定名字，例如 code-review。
  description: string;  // 说明适用场景，用于匹配和展示。
  triggers: string[];   // 关键词触发器，例如 review、code review。
  instructions: string; // 真正注入给模型的流程规则。
  sourcePath: string;   // skill 文件路径，方便调试和溯源。
};

---
name: code-review
description: Review code changes for bugs and regressions.
triggers:
  - review
  - code review
---

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.

// loadSkills = 从目录中加载 skill markdown 文件。
// 这里读的是可信 skill 目录，不应该从项目任意文件里加载。
export async function loadSkills(root: string): Promise<Skill[]> {
  // 找到 skills 目录下所有 markdown。
  const files = await glob("skills/**/*.md", { cwd: root });

  return Promise.all(files.map(async file => {
    // 读取 skill 文件正文。
    const text = await readFile(resolve(root, file), "utf8");

    // 拆 frontmatter 和正文。
    // frontmatter 放 name/description/triggers，body 放执行规程。
    const { frontmatter, body } = parseMarkdownWithFrontmatter(text);

    return {
      name: frontmatter.name,               // skill 名。
      description: frontmatter.description, // 适用场景。
      triggers: frontmatter.triggers ?? [], // 没写 triggers 就给空数组。
      instructions: body,                   // 规则正文。
      sourcePath: file                      // 来源路径。
    };
  }));
}

// selectSkills = 根据用户输入选择要注入的 skill。
// 这是入门版：只做关键词匹配。
export function selectSkills(skills: Skill[], userInput: string) {
  // 统一小写，做大小写不敏感匹配。
  const lower = userInput.toLowerCase();

  return skills.filter(skill =>
    // 只要任一 trigger 出现在用户输入中，就选择该 skill。
    skill.triggers.some(trigger => lower.includes(trigger.toLowerCase()))
  );
}

// formatSkills = 把选中的 skill 转成 system prompt 片段。
// 用 XML-like 标签包起来，是为了让模型看清不同 skill 的边界。
function formatSkills(skills: Skill[]) {
  return skills.map(skill => `
<skill name="${skill.name}">
${skill.instructions}
</skill>
`).join("\n");
}

// 把 skill 作为 system message 注入，而不是作为普通 user message。
// 这样它更像行为规则，而不是用户随口说的一段话。
messages.push({
  role: "system",
  content: `Relevant skills:\n${formatSkills(selectedSkills)}`
});

// 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);
}

Command = 程序自己的确定性操作
Skill   = 给模型看的任务流程说明
Plugin  = 给程序加载的扩展包

// 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[];                          // 普通位置参数。
};

/mcp list
/mcp add github --transport stdio
/permissions allow shell --scope session
/cost --since last-compact

// 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 code changes for bugs, regressions, and missing tests.
triggers:
  - review
  - code review
---

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: Skill;      // 被评估的 skill。
  score: number;     // 匹配分数，越高越应该注入。
  reasons: string[]; // 命中原因，例如 explicit trigger、semantic match。
};

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

  // 明确关键词命中，给较高分。
  if (matchesExplicitTrigger(skill, turn.userText)) {
    score += 10;
    reasons.push("explicit trigger");
  }

  // 语义相近但没直接命中关键词，给较低分。
  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 (hasNegationAroundTrigger(skill, turn.userText)) {
    score -= 20;
    reasons.push("negated trigger");
  }

  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
    });
  }
}

runThing
doStuff
tool1

read_file
edit_file
search_text
github_search_issues

// 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 白名单。
  };
};