AI 与大模型 · Claude Code 子页

Claude Code Agent / Tool / Prompt 细节

基于 2026-04-25 对 Anthropic 官方 Claude Code 文档、工具参考、Hooks、MCP、Subagents、SDK 与公开仓库 README 的核验，细化 Claude Code 的 agent 编排、内置工具、权限、hook 和可公开说明的提示词入口。

官方工具参考：16 类内置工具 + MCP 动态工具 公开边界：内部系统提示词未公开 重点：权限、Hook、Subagent、SDK

0. 真实边界

Claude Code 的完整 CLI 内部源码、托管模型路由、精确系统提示词和服务端策略没有以稳定公开接口形式发布。本文只把官方文档能确认的工具、权限、用户可配置 prompt 表面和可观察 agent loop 写成结构化说明。

因此，“实现细节”在这里分两类：能从官方工具表和文档确认的行为会直接写明；未公开的内部策略会标注为 CLI runtime 管理，不把社区逆向或猜测写成事实。

1. Agent Loop 与工具生命周期

User prompt
  |
  v
Claude Code CLI builds context
  |  CLAUDE.md / settings / memory / cwd / git / selected files
  v
Claude model receives messages + available tool definitions
  |
  +-- answer directly -----------------------------> final response
  |
  +-- emits tool_use
        |
        v
  Permission rules + hooks
        |
        +-- deny/block -----------> tool_result with denial
        |
        +-- ask user -------------> allow / deny
        |
        +-- allow
              |
              v
        Local runtime executes tool
              |
              v
        tool_result appended to conversation
              |
              v
        next model turn

Claude Code 的核心不是一条长提示词，而是“模型输出结构化工具调用，CLI harness 执行并把结果回传”的循环。权限、hooks、MCP 和 subagent 都挂在这个循环上。

2. 内置工具清单与实现边界

Agent / 编排

Task 否

职能：启动一个子 agent 处理复杂、多步骤任务。

架构：主会话把目标、上下文摘要和可用工具策略交给子 agent；子 agent 使用独立上下文窗口完成研究或专项工作，再把结果压缩回主会话。

实现细节：官方 subagents 文档确认子 agent 可以有独立 system prompt、工具白名单和模型选择。公开资料没有暴露内部 Task 调度源码，因此只能确认 CLI harness 负责创建隔离执行单元并回填结果。

TodoWrite 否

职能：维护结构化任务清单，追踪当前复杂任务的状态。

架构：Todo 状态属于会话编排层，不是文件系统写入；模型用它把探索、修改、验证拆成可见步骤。

实现细节：官方工具清单列为内置工具且不需批准；真实实现细节未公开，页面只按可观察 CLI 行为解释。

ExitPlanMode 是

职能：从计划模式退出并进入执行修改阶段。

架构：Plan mode 把“研究/规划”和“写文件/运行高风险动作”分开；退出计划模式前需要显式确认。

实现细节：官方工具清单标记需要批准。它体现的是编排状态迁移，而不是普通文件工具。

Shell / 执行

Bash 是

职能：执行 shell 命令，用于测试、构建、搜索、git、脚本和本地工具链。

架构：模型只产生结构化命令请求；CLI harness 负责权限匹配、用户确认、hook 拦截、运行命令、截断/整理输出并作为 tool_result 回传。

实现细节：权限可以通过 settings 的 allow/deny/ask 规则、trusted workspace 和 hooks 控制。后台命令结果由 BashOutput 读取，必要时由 KillBash 停止。

BashOutput 否

职能：读取后台或长运行 shell 命令的输出。

架构：把长任务从一次性阻塞输出变成可轮询观察结果，便于模型在后续 turn 继续判断。

实现细节：官方工具清单列为后台 shell 输出检索工具；具体缓冲、截断和进程管理策略未公开。

KillBash 否

职能：终止后台 shell 命令。

架构：为长运行任务提供取消路径，避免 agent loop 被无穷进程拖住。

实现细节：官方工具清单列为不需批准；真实进程标识和终止策略由 CLI runtime 管理。

文件发现 / 读取

Glob 否

职能：按 glob 模式查找文件路径。

架构：低成本收集候选文件，常用于“先找入口，再读内容”的探索阶段。

实现细节：本地文件系统查询工具；不会修改文件，官方清单标记不需批准。

Grep 否

职能：按文本或正则搜索文件内容。

架构：把代码库变成可查询索引，帮助模型定位符号、错误文本、路由、配置和测试。

实现细节：公开文档只确认能力和权限；具体底层是否调用系统 grep、ripgrep 或内部搜索未作为稳定 API 公开。

LS 否

职能：列出目录内容。

架构：用于建立项目结构视图，常和 Glob/Grep/Read 组合。

实现细节：只读文件系统操作，官方工具清单标记不需批准。

Read 否

职能：读取文件内容。

架构：把真实代码片段放进上下文，避免模型凭文件名猜测。

实现细节：只读工具；是否截断、分页、二进制处理等细节属于 CLI runtime 行为，官方未承诺为公开接口。

文件修改 / Notebook

Edit 是

职能：对文件做定点修改。

架构：模型提出目标位置和替换内容；CLI runtime 负责落盘、diff 展示、权限审批和 hook 检查。

实现细节：适合小范围编辑。PreToolUse/PostToolUse hooks 可在写入前后阻断或审计。

MultiEdit 是

职能：在同一文件中原子化执行多处编辑。

架构：降低多次独立写入造成的中间不一致，适合同文件重构、批量替换和格式调整。

实现细节：官方工具清单确认“single file atomically”；具体冲突检测策略未公开。

Write 是

职能：创建或覆盖文件。

架构：高风险写入路径，通常比 Edit 更需要明确用户意图。

实现细节：权限层必须确认；hook 可拦截敏感路径、配置文件或生成文件写入。

NotebookEdit 是

职能：修改 Jupyter notebook 单元格。

架构：把 notebook 当成结构化文档处理，而不是直接把 `.ipynb` 当普通 JSON 文本粗暴替换。

实现细节：官方工具清单确认 notebook cell 修改能力；细粒度 cell 操作内部未公开。

Web / 外部信息

WebFetch 是

职能：抓取指定 URL 内容。

架构：把用户给出的页面作为外部上下文注入 agent loop。

实现细节：需要网络和权限边界；企业环境可通过权限配置或 hooks 控制外部访问。

WebSearch 是

职能：执行网页搜索。

架构：用于当前信息、文档定位和跨站检索；结果仍需由模型阅读、筛选和引用。

实现细节：官方工具清单确认能力；搜索供应链、排序和地区策略不是公开接口。

MCP 扩展工具

mcp__server__tool 取决于配置

职能：由外部 MCP server 动态提供工具、资源和 prompt。

架构：Claude Code 是 MCP client；server 暴露 tools/resources/prompts 后，CLI 把它们纳入同一套工具选择、权限和结果回传路径。

实现细节：工具名采用 server 与 tool 的命名隔离。实际输入 schema、执行逻辑、鉴权和副作用由 MCP server 定义，Claude Code 侧负责连接、展示、授权和回传。

3. 可公开说明的提示词层

Non-public base system prompt
  |
  +-- Official product behavior and safety policy
  +-- Tool schemas currently available in this session
  +-- Permission state and current interaction mode
  |
  +-- User-visible prompt surfaces
        |
        +-- User request in terminal / IDE / GitHub workflow
        +-- CLAUDE.md project and user memory instructions
        +-- Custom slash command prompt bodies
        +-- Subagent system prompt configured by user
        +-- Hook output that blocks or amends execution
        +-- MCP tool/resource/prompt metadata
        +-- SDK options and session history
  |
  v
Model-visible task context for this turn
提示词入口真实作用
CLAUDE.md / memory项目级、用户级或目录级长期说明。适合编码规范、测试命令、架构约束和团队习惯。
Slash commands把重复工作流写成可调用提示词模板。它是用户可见的 prompt 入口，不等同于内部系统提示词。
Subagent system prompt每个子 agent 可配置独立 system prompt、工具白名单和模型，适合 review、test、research 等角色。
Hooks在 UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStop、PreCompact、SessionStart、SessionEnd 等事件运行确定性命令，能阻断或约束流程。
MCP prompts/resources外部 MCP server 可提供可发现的 prompt 与资源，让 Claude Code 获得服务侧知识和操作入口。
SDK options把 CLI agent runtime 嵌入自动化脚本时，SDK 传入 prompt、session、permission 与输出流配置。

注意：Claude Code 的精确系统提示词不是公开稳定文档。可以真实讨论的是用户和团队能控制的 prompt surface，例如 CLAUDE.md、slash command、subagent prompt、MCP prompt/resource 与 hook 输出。

4. Hooks 作为确定性编排层

Hook触发点典型用途
UserPromptSubmit用户提交后、模型处理前注入团队规则、记录审计、阻断敏感请求。
PreToolUse工具执行前检查 Bash、Edit、Write、MCP 等动作，允许、拒绝或要求确认。
PostToolUse工具执行后验证文件、运行格式检查、记录工具结果。
Stop主 agent 准备停止时如果缺少测试、说明或交付物，可阻止停止并要求继续。
SubagentStop子 agent 准备停止时对子 agent 的结果做完成度检查。
PreCompact上下文压缩前在摘要前保存关键状态、日志或外部记录。
SessionStart / SessionEnd会话开始或结束初始化环境、加载约束、记录会话结果。

Hook 的工程价值在于把“必须执行的团队策略”从自然语言提示词移到确定性命令：例如阻止危险 Bash、检查生成文件、强制测试通过、或在停止前要求补齐验证结果。

5. 复杂任务编排

Complex coding task
  |
  +-- Explore
  |     +-- Glob / Grep / LS / Read
  |     +-- Task delegates isolated research to a subagent
  |
  +-- Plan
  |     +-- TodoWrite records work items
  |     +-- ExitPlanMode asks for approval before implementation
  |
  +-- Change
  |     +-- Edit / MultiEdit / Write / NotebookEdit
  |     +-- PreToolUse and PostToolUse hooks can enforce policy
  |
  +-- Verify
  |     +-- Bash starts command or background job
  |     +-- BashOutput polls long-running output
  |     +-- KillBash stops runaway jobs
  |
  +-- Extend
        +-- MCP tools call external systems
        +-- SDK embeds the same agent flow in automation
主 agent 负责用户目标、全局上下文、最终交付和权限确认。
Task / Subagent 负责隔离研究、专项审查或测试分析，减少主上下文污染。
Hook 负责把安全、合规和质量门禁变成可执行规则。
MCP 负责把本地仓库之外的系统接入工具层，例如 issue、数据库、文档、内部服务。

6. 与主页面的关系

主页面解释 Claude Code CLI 的总体架构；本页是工具、prompt surface 和编排机制的明细表。生产判断建议以本页“真实边界”和官方文档为准。

返回 Claude Code 架构总览

资料来源