架构概览 — Claude Code 代码仓库的真实内容

如果你打开 github.com/anthropics/claude-code，期望找到 Claude Code 终端界面、上下文窗口管理或工具执行引擎的源代码，那你会扑空。这是关于这个仓库最常见的误解，也是真正理解它的起点。

这个仓库是 Claude Code 对外开放的可扩展性与运维层。它包含官方插件生态、管理数千个 issue 的 GitHub 自动化基础设施、DevContainer 沙箱配置，以及企业级部署示例。这是 Claude Code 与外部世界交汇的地方。

这个仓库是什么（以及不是什么）

Claude Code 产品以闭源 npm 包（@anthropic-ai/claude-code）和原生安装包的形式分发。README 对此说得很清楚 — 它引导用户前往安装方式和官方文档，而非源代码文件：

README.md#L7

上下文窗口管理、终端界面、工具执行沙箱、模型路由，以及让 Claude Code 真正运转的一切代码，都在别处。这个仓库是配套部分 — 它展示可扩展性、自动化运维，并提供参考配置。

打个比方：如果 Claude Code 是一套操作系统，这个仓库就是应用商店目录、系统管理脚本、容器配置和企业部署指南。而不是内核本身。

仓库地图：四个功能区

整个仓库清晰地划分为四个功能区，结构如下：

graph TD
    ROOT["anthropics/claude-code"] --> PLUGINS["plugins/<br/>Extension Ecosystem"]
    ROOT --> AUTOMATION[".github/workflows/ + scripts/<br/>Automation Infrastructure"]
    ROOT --> SANDBOX[".devcontainer/<br/>Sandbox Environment"]
    ROOT --> EXAMPLES["examples/<br/>Enterprise Configuration"]
    ROOT --> COMMANDS[".claude/commands/<br/>Repo-Level Commands"]

    PLUGINS --> P1["13 official plugins"]
    PLUGINS --> P2["Commands, agents, skills, hooks"]

    AUTOMATION --> A1["12 GitHub Actions workflows"]
    AUTOMATION --> A2["TypeScript lifecycle scripts"]
    AUTOMATION --> A3["Sandboxed CLI wrappers"]

    SANDBOX --> S1["Dockerfile + firewall"]
    SANDBOX --> S2["Network restrictions"]

    EXAMPLES --> E1["3 enterprise settings profiles"]
    EXAMPLES --> E2["Hook examples"]

    style PLUGINS fill:#4CAF50,color:#fff
    style AUTOMATION fill:#2196F3,color:#fff
    style SANDBOX fill:#FF9800,color:#fff
    style EXAMPLES fill:#9C27B0,color:#fff
    style COMMANDS fill:#607D8B,color:#fff

功能区	路径	内容说明
插件	plugins/	13 个官方插件，包含命令、agent、技能、钩子
插件市场	.claude-plugin/	用于发现插件的注册表 manifest
自动化	.github/workflows/ + scripts/	12 个工作流、生命周期脚本、沙箱化 CLI 封装
沙箱	.devcontainer/	Docker + iptables 防火墙，用于隔离执行
企业配置	examples/settings/	三种部署配置（宽松、严格、bash 沙箱）
仓库命令	.claude/commands/	专属于本仓库运维的斜杠命令

提示： .claude/commands/ 目录存放的是本仓库自身使用的命令（如 issue 分类、去重），而非插件命令。插件命令位于各插件自己的 commands/ 目录中。搭建自己的项目时，这个区别很重要。

插件市场

位于 .claude-plugin/marketplace.json 的市场 manifest 注册了全部 13 个官方插件，分为四大类别：

类别	插件	用途
development	agent-sdk-dev、claude-opus-4-5-migration、feature-dev、frontend-design、plugin-dev、ralph-wiggum	功能开发、代码迁移、插件创建
productivity	code-review、commit-commands、hookify、pr-review-toolkit	工作流自动化、PR 审查、git 操作
learning	explanatory-output-style、learning-output-style	注入教学上下文的教育模式
security	security-guidance	运行时安全模式监控

manifest 中每条插件记录包含 name、description、source 路径、category，以及可选的 version/author 元数据。source 字段使用相对路径（如 ./plugins/feature-dev），将插件市场注册表与目录结构紧密绑定：

.claude-plugin/marketplace.json#L62-L71

市场 schema（"$schema": "https://anthropic.com/claude-code/marketplace.schema.json"）暗示着一套超出本仓库范围的更完整插件市场基础设施。用户通过 Claude Code 内的 /plugin 命令安装插件，而这个 manifest 是其中一个发现来源。

插件组件模型

每个插件遵循"约定优于配置"的架构，提供五种可选的组件类型。插件只需包含自己实际用到的部分：

flowchart LR
    MANIFEST[".claude-plugin/<br/>plugin.json"] --> DISCOVERY["Auto-Discovery<br/>Engine"]
    COMMANDS["commands/<br/>*.md"] --> DISCOVERY
    AGENTS["agents/<br/>*.md"] --> DISCOVERY
    SKILLS["skills/<br/>*/SKILL.md"] --> DISCOVERY
    HOOKS["hooks/<br/>hooks.json"] --> DISCOVERY
    MCP[".mcp.json"] --> DISCOVERY

    DISCOVERY --> REGISTER["Component<br/>Registration"]

    style MANIFEST fill:#FF5722,color:#fff
    style DISCOVERY fill:#3F51B5,color:#fff

标准插件结构记录于 plugin-dev 技能文件 plugins/plugin-dev/skills/plugin-structure/SKILL.md#L22-L37，如下所示：

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities

一个最小可用插件只需要一个包含 name 字段的 plugin.json。以 feature-dev 插件的 manifest 为例，总共只有九行：

plugins/feature-dev/.claude-plugin/plugin.json#L1-L9

有一个关键的设计细节：插件内部的所有路径引用使用 ${CLAUDE_PLUGIN_ROOT} 而非硬编码路径。这个环境变量会解析为插件实际安装的位置，让插件在不同安装方式和操作系统之间保持可移植性。在钩子配置和脚本引用中，这一模式随处可见。

组件类型速览

在下一篇文章深入每种组件类型之前，先做一个快速定向：

组件	格式	发现机制	调用方式
Commands	带 YAML frontmatter 的 .md	commands/ 下的所有 .md	用户输入 /command-name
Agents	带 YAML frontmatter 的 .md	agents/ 下的所有 .md	由命令或 Claude 编排调用
Skills	子目录中的 SKILL.md	skills/*/ 下的所有 SKILL.md	由上下文自动激活
Hooks	hooks/hooks.json 中的 JSON	插件启用时加载	事件驱动（PreToolUse、Stop 等）
MCP Servers	.mcp.json 中的 JSON	插件启用时加载	Claude 发起工具调用

这五种类型构成一个从显式用户控制（命令）到全自动行为（技能与钩子）的连续谱系。这种分层设计让插件作者可以为每项能力选择合适的用户参与程度。

文档中常见的误区

一些文档来源 — 包括自动生成的 wiki — 将这个仓库与 Claude Code 的内部实现混为一谈。明确说明，以下内容不在本仓库中：

• 没有上下文窗口管理代码 — 那部分在闭源 npm 包中
• 没有终端界面实现 — 同上
• 没有工具执行引擎 — 沙箱与权限系统属于内部实现
• 没有模型路由逻辑 — Claude Code 如何在 Haiku、Sonnet 和 Opus 之间选择，不在这里
• 没有对话状态管理 — 会话处理属于内部实现

你能找到的，是 Claude Code 对外暴露的扩展接口：如何编写 Claude Code 加载的插件、如何配置 Claude Code 执行的钩子、如何设置 Claude Code 执行的企业策略。边界是清晰的：本仓库定义的是 Claude Code 在特定场景下应该做什么；闭源核心定义的是它如何做到。

接下来

地图已经画好，接下来让我们深入探索每一片区域。在第 2 篇中，我们将拆解插件系统，逐一审视每种组件类型 — 配置命令与 agent 的 YAML frontmatter、驱动技能的自动激活机制，以及基于退出码协议的事件驱动钩子系统。我们将结合 13 个官方插件中的真实案例进行分析，从 feature-dev 工作流开始 — 它通过七个开发阶段编排多个并行 AI agent 协同工作。