Skip to content

08-command-system.md

Latest commit

 

History

History
138 lines (99 loc) · 3.02 KB

08-command-system.md

File metadata and controls

138 lines (99 loc) · 3.02 KB

08. 命令系统教程

命令系统负责处理用户显式输入的 /xxx 操作。它和 Tool System 是并行体系，不应混为一谈。

1. 关键模块

  • src/commands.ts 命令总注册表
  • src/types/command.ts 或相关命令类型定义 命令 contract
  • src/commands/* 各个命令的具体实现
  • src/skills/loadSkillsDir.ts skill 命令加载
  • src/utils/plugins/loadPluginCommands.ts plugin 命令加载

2. Command 与 Tool 的区别

2.1 Command

  • 面向用户显式输入
  • 由 /commit、/review、/memory 之类触发
  • 更像“交互入口”或“操作模式切换”

2.2 Tool

  • 面向模型内部推理
  • 由 tool_use 触发
  • 更像“执行能力”

这两个体系并行存在，是 Claude Code 架构里最容易被误解的点之一。

3. 架构图

flowchart LR
    User[/用户输入 /]
    Parser[命令解析]
    Registry[commands.ts]
    Builtin[内建命令]
    Skills[skill dir commands]
    Plugins[plugin commands]
    Result[本地执行 / 生成 prompt / 模式切换]

    User --> Parser
    Parser --> Registry
    Registry --> Builtin
    Registry --> Skills
    Registry --> Plugins
    Builtin --> Result
    Skills --> Result
    Plugins --> Result
Loading

4. commands.ts 在做什么

它不只是 import 所有命令，更重要的是把多种来源统一进一套注册体系：

  • builtin commands
  • feature-gated commands
  • skills 派生命令
  • plugin 派生命令

并且存在大量 lazy import，用来降低冷启动成本。

5. 命令类型

从结构上看，命令大致有几类：

  • 本地执行类
  • 生成 prompt 类
  • 模式切换类
  • 配置类
  • 会话管理类

例如：

  • /compact
  • /memory
  • /resume
  • /mcp
  • /permissions

6. 流程图

sequenceDiagram
    participant U as User
    participant R as REPL
    participant C as commands.ts
    participant CMD as specific command

    U->>R: /command args
    R->>C: 根据名字查找命令
    C->>CMD: 执行命令 contract
    CMD-->>R: 本地结果 / prompt / 状态更新
Loading

7. 为什么要支持动态命令

Claude Code 不把命令固定死，是因为它希望这几个体系都能扩展：

  • skills
  • plugins
  • 产品 feature
  • 环境差异

因此 commands.ts 更像一个“命令聚合器”，不是单纯索引。

8. 核心源码入口

8.1 src/commands.ts

重点观察：

  • 哪些命令是同步 import
  • 哪些命令走 lazy require
  • skills/plugins 如何并入

8.2 src/commands/memory/、src/commands/mcp/、src/commands/review/

这几个命令很适合作为代表样本：

  • 一个偏状态管理
  • 一个偏外部集成
  • 一个偏 agent 工作流

9. 设计亮点

  • 命令和工具明确分层
  • 注册中心能融合 builtin、skill、plugin 三种来源
  • 大量使用延迟加载控制启动成本
  • 很多命令本质上是“切换运行时行为”，不是单纯输出文本

10. 阅读建议

先看 src/commands.ts，再挑 memory / mcp / resume / review / permissions 几组命令深入。