Claude-Code-智能体编程-三-
Claude Code 智能体编程（三）
原文：Agentic Coding with Claude Code
译者：飞龙
-
fix部分编码依赖关系和文件级作用域 -
verify部分定义验证机制 -
metadata部分捕获运营考量
Figure 8.4 – Claude generating a structured task plan in YAML format
YAML 鼓励基于关系和依赖而非顺序步骤进行思考。其层级结构将焦点从有序指令转移到相互关联的组件。
当 Claude Code 以嵌套 YAML 结构输出任务时，它不生成简单的待办清单。相反，它将问题空间的逻辑架构编码在结构本身中。关系、作用域和依赖通过嵌套和键组织来表达。
Figure 8.5 – Human–AI collaboration enabled through customizable output styles
输出风格移除了单一固定交互模型的约束。它们允许通信协议本身被设计和调整。这反映了 Agentic Coding 的本质：主动塑造 AI 表达信息和在开发工作流中协作的方式。
因此，对交互的控制不限于模型提供商改进模型能力。开发者作为大语言模型的用户，通过输出风格定义并控制通信协议。
创建 YAML 输出风格
项目级输出风格可配置为生成简洁的 YAML 响应，无额外冗余。在项目级定义时，该配置仅在该项目内生效。
要创建此风格，请在项目目录下创建文件 .claude/output-styles/yaml-concise.md：
---
description: Concise YAML-formatted responses for structured communication
---
# Response Format
- All responses must be formatted as valid YAML
- Use hierarchy and nesting to express relationships
- Keep values concise — no full sentences unless necessary
# Structure
- Use top-level keys to represent major sections
- Nest subconcepts under their parent context
- Use lists for enumerations and sequences
- Use key-value pairs for properties and attributes
# Tone
- No prose, no filler, no transitional language
- Let the YAML structure carry the meaning
- Prefer short string values over paragraphs
创建文件后，运行 /output-style 时，yaml-concise 风格会出现在可用输出风格列表中。项目的 .claude 文件夹下也会创建一个新目录。其中生成的 YAML 配置文件代表新定义的项目级输出风格。选择它以激活当前会话的风格。
激活 YAML 风格后，发出查询，例如：
What are Claude Code output styles? Give me an elaborate answer.
响应将作为结构化 YAML 返回，而非段落或要点。层级、键和缩进编码了解释的结构。
以下是一个典型示例：
definition:
what: "Custom response formats for Claude Code CLI"
purpose:
- "Control communication style and structure"
- "Support global or project-level configuration"
location:
global: "~/.claude/output-styles/"
project: "./.claude/output-styles/"
precedence: "Project overrides global"
file_structure:
format: "Markdown with YAML frontmatter"
frontmatter:
description: "Brief style explanation"
content: "System prompt modifications"
functionality:
controls:
- "Response formatting (bullets, YAML, prose)"
- "Communication tone (formal, casual, technical)"
- "Information density (concise, detailed)"
- "Task approach (speed vs thoroughness)"
- "Workflow behaviors"
输出结构反映了概念分组，而非线性解释。
响应格式强调以下关系：
-
章节成为顶级键
-
子概念嵌套在其父上下文下
-
配置作用域和优先级在结构上编码
-
行为控制归类在共享功能类别下
此方法映射了 YAML 在 Kubernetes 和 Docker Compose 等配置系统中的用法。结构保持可读性的同时保留了语义层级。
激活项目级 YAML 简洁风格后，响应将始终以此结构化格式返回，强化架构思维而非顺序叙述。
Figure 8.6 – YAML-concise output style applied in Claude Code
创建高级项目级输出样式
本节定义了一个新的项目级输出样式，并通过自动化文件生成行为对其进行了扩展。目标是生成结构为 ASCII 风格博客页面的 HTML 格式响应，并将该行为直接集成到输出样式定义中。
定义自定义 HTML 输出样式
让我们创建并查看输出样式配置文件。该配置的完整示例可在代码仓库中找到。要获取代码仓库链接，请遵循 Preface 中 Download the example code files 部分的步骤。
在以下路径下创建一个新的项目级输出样式文件：
.claude/output-styles/retro-ASCII_blog.md
该样式旨在生成格式化为 ASCII 风格博客页面的 HTML 输出。
输出样式控制响应的格式，还可以嵌入工作流规则。
输出样式的内容如下：
---
description: Format responses as retro HTML pages with ASCII art styling like a vintage blog
---
Format all responses as complete HTML pages with retro ASCII art blog styling. Follow these guidelines:
HTML Structure
Always provide complete HTML5 documents with proper DOCTYPE, head, and body tags
Use semantic HTML elements (header, main, section, article, aside, footer)
Include a proper HTML title that reflects the content
ASCII Art Styling
Use ASCII art for headers, dividers, and decorative elements
Create borders using characters like ═, ║, ╔, ╗, ╚, ╝, -, |, +, *, #
Add ASCII art banners for section headers
Use monospace fonts throughout for consistent ASCII alignment
Include decorative ASCII elements like stars, lines, and boxes
CSS Requirements
Embed CSS in <style> tags in the HTML head
Use monospace fonts (Courier New, Monaco, Consolas, monospace)
Set background to dark colors (#1a1a1a, #2d2d2d) with light text
Use retro color schemes (green on black, amber on black, etc.)
Style ASCII art elements with appropriate spacing and alignment
Add subtle glow effects or text shadows for retro terminal feel
Content Structure
Format content like a blog post with clear sections
Use ASCII art dividers between sections
Create ASCII art headers for major topics
Include a decorative ASCII footer
Structure technical information in readable blocks
Add ASCII navigation or menu elements when appropriate
Example Elements to Include:
ASCII art title banners
Decorative borders around code blocks
ASCII bullet points and lists
Retro-style ASCII progress bars or indicators
Terminal-style prompts and outputs
ASCII art logos or emblems
Remember to maintain readability while embracing the retro ASCII aesthetic. The content should feel like browsing a vintage bulletin board system or early web blog.
此输出样式超越了简单的终端格式化。它不生成要点或 YAML，而是由 Claude Code 生成作为复古 ASCII 艺术博客页面样式的完整 HTML 文档。
说明组织为以下几节：
-
HTML 结构 定义了带有语义元素的完整 HTML5 文档
-
ASCII 艺术样式 通过绘图字符和等宽字体建立视觉标识，以保持一致的对齐
-
CSS 要求 定义了复古终端美学，包括深色背景、绿底黑字或琥珀底黑字配色方案，以及微妙的发光效果
内容组织为博客文章，带有 ASCII 艺术分隔符、横幅和装饰性页脚。
整个行为在单个 Markdown 文件中定义，无需代码或插件。一旦选中该样式并发出提示，Claude Code 将生成 HTML 页面，将其写入磁盘，并在浏览器中打开。
使用 HTML 输出样式
选中 retro‑ASCII_blog.md 作为活动输出样式后，发出以下提示：
-
什么是输出样式？请提供详细答案。
-
向我展示我目前拥有哪些输出样式。
响应将以 HTML 形式生成。内容为有效的 HTML 标记，直接在终端中渲染。因为它作为标记发出，所以在这种情况下不易阅读。
在此阶段，HTML 尚未写入可在浏览器中打开的文件。输出仅存在于生成的标记中。
要使结果可用，需指示 Claude Code 将生成的 HTML 转储到文件中。创建一个名为 output‑styles‑guide.HTML 的文件。
在浏览器中打开时，它将渲染为一个博客风格的页面，显示输出样式的解释。
图 8.7 – 生成的记录 Claude Code 输出样式的 HTML 页面
渲染的页面显示了配置的输出样式，并演示了结构和格式完全可定制。HTML 并非旨在视觉上精致；其目的是说明生成内容拥有完全的自由度。
输出样式不限于静态页面。它可以扩展为将页面写入更大的应用程序中，例如 Next.js 项目，其中每个 Claude Code 生成的响应都在该应用程序中生成一个新页面。输出的结构和行为完全由配置定义，不存在预定义模板施加的固有限制。
自动化文件生成
我们现在将工作流逻辑直接嵌入到输出样式定义中。每次提示 Claude Code 将 HTML 写入文件都很重复。我们不再在每次提示时发出此指令，而是将该行为直接嵌入到输出样式定义中。
retro‑ASCII_blog.md 文件已更新，包含以下代码片段的工作流说明：
Workflow
Save the HTML file after writing it, it should have a descriptive name ending with .html
OPEN the generated file in the default web browser.
输出样式还可以编码工作流行为，允许 Claude Code 自动保存生成的 HTML 文件并在浏览器中打开。
图 8.8 – 输出样式工作流说明
未引入复杂逻辑。提示保持最小化。Claude Code 根据这些说明执行所需的文件生成步骤。
保存更新后的输出样式后，发出如下提示：
What are output styles?
这将导致自动创建一个名为 output‑styles‑quick‑guide.html 的文件。系统请求确认在默认浏览器中打开该文件，一旦批准，渲染的 HTML 即刻可见。
工作流现已嵌入输出样式本身。在此样式下生成的每个响应都会自动写入一个可供浏览器打开的 HTML 文件。
使用多个输出样式
运行单个输出样式演示了如何为特定目的自定义格式。通过同时运行多个 Claude Code 实例，每个实例配置不同的输出样式，可以扩展此配置。以下章节说明了单独的会话如何并行运行，以及这如何在同一代码仓库中实现特定任务的格式化。
启动新的 Claude Code 实例
在仓库内打开一个新的终端实例，并启动 Claude Code。这将创建一个新会话，且尚未选择输出样式。
Figure 8.9 – Launching a new Claude Code session
随后从可用选项中选择一种输出样式。本例中选择了极简要点输出样式。
会话现已配置为使用极简要点格式生成响应。
在同一仓库中打开第二个实例并使用不同的输出样式
在同一仓库中打开第二个终端实例。在该新会话中再次启动 Claude Code。
本例中选择了另一种输出样式 —— YAML 简洁输出样式。
此时，有两个 Claude Code 实例同时运行：
-
一个配置了极简要点样式
-
一个配置了 YAML 简洁输出样式
每个实例维护各自激活的输出样式。
Figure 8.10 – Selecting the YAML-concise output style
并行输出样式的实践
两个实例并行运行时，各终端生成的响应均反映其选定的配置。格式差异取决于当前激活的输出样式。
这确立了一种工作流：多个 Claude Code 会话并行运行，每个会话针对特定输出格式进行优化。
Figure 8.11 – Two Claude Code sessions using different output styles
专用输出样式工作流
两个实例同时可见时，每个会话都清晰地维持着各自的格式化行为。我们不再使用单一的整体环境，而是让每个 Claude Code 会话成为专门针对特定任务配置的专用 AI 助手。
-
面向代码审查的会话可强调代码差异、安全漏洞和架构问题。
-
面向解释的会话可针对教学见解或文档生成进行优化。
-
面向调试的会话可专注于错误分析和故障排查，并使输出与之对齐。
每种输出样式都将 AI 的认知重点调整至当前任务。
在终端窗口间切换时，无法直观得知当前激活的是哪种输出样式。界面并未显著显示此信息。
在跨多会话工作时，这一限制会变得明显。可通过自定义状态行来解决，它能更清晰地标识当前激活的配置。
配置验证通过并按预期工作后，将更改提交至版本控制。
在本节中，你通过定义项目级配置并集成更高级的格式化与行为逻辑，扩展了基础输出样式机制。你见证了输出样式如何超越简单的响应格式化，延伸为 HTML 等结构化输出及自动化工作流行为。这表明输出样式不仅影响响应的外观，还影响其运作方式。奠定此基础后，下一节将从输出格式化转向运行时界面定制 —— 通过修改 Claude Code 状态行。
在 Claude Code 中自定义状态行
状态行允许你运行任意脚本：脚本通过 stdin 接收 Claude Code 的会话数据（模型、上下文用量、费用、Git 信息等 JSON），并将你想要的内容持久打印在终端底部。你可以在 ~/.claude/settings.json 中将 statusLine 键指向你的脚本来配置它，或使用 /statusline 斜杠命令配合自然语言描述自动生成。
本节回顾如何使用专用命令和基于 Python 的实现来配置和实现 Claude Code 的自定义状态行。
定义自定义状态行命令
定义一个新的斜杠命令 /statusline。该命令包含一段描述，指明状态行应显示当前激活的输出样式。提供给该命令的提示词如下：
/statusline I want you to create a statusline that displays the current used output-style.
You should implement it in python and run it through uv
指定了两项实现要求：
-
状态行必须用 Python 实现
-
必须使用 UV 包管理器执行
Claude Code 的状态行可执行 Shell 命令、Shell 脚本、Python 文件和 Node.js 文件，能运行任意可执行逻辑。基于熟悉度和偏好，选择 Python 作为实现语言。
初始化状态行设置
执行 /statusline 命令后，Claude Code 初始化并生成一个子代理，负责协助创建状态行。
子代理执行的首个动作是在主目录中搜索现有的状态行配置：
~/.claude/settings.json
检查该文件是否存在 statusline 条目。由于不存在，配置文件随即更新。
Figure 8.12 – Implementing a custom statusline script
更新配置
settings.json 文件定义了默认模型，此处设为 sonnet。随后在配置中新增一个 statusline 条目。
典型配置如下：
{
"model": "sonnet",
"statusline": {
"type": "command",
"command": "uv run ~/.claude/statusline.py"
}
}
type 设为 command，配置的命令使用 uv 包管理器运行 statusline.py 脚本。
默认情况下，脚本创建于主目录：
~/.claude/statusline.py
脚本可存放在任意位置，只需配置中指定正确的执行路径即可。
实现状态行逻辑
statusline.py 文件包含决定自定义状态行显示内容的逻辑。
Claude Code 通过标准输入（stdin）向脚本提供运行时信息。脚本读取该输入并将其作为 JSON 处理。使用 json.load 将数据加载到字典中，从而访问 Claude Code 提供的所有信息。
Figure 8.13 – Statusline script reading JSON input from Claude Code
最小实现如下：
import json
import sys
input_data = json.load(sys.stdin)
style = input_data.get("output_style", "default")
print(style)
可用键中包含 output_style。脚本从此键提取当前激活输出样式的名称。若未定义输出样式，脚本默认显示 "default" 作为输出样式。
脚本将结果写入标准输出（stdout）。Claude Code 读取脚本打印到 stdout 的内容并将其显示在状态行中。
更改输出样式时，通过 stdin 传递的值会随之变化，状态行也会反映新样式。
ANSI 颜色支持与格式化
状态行支持 ANSI 颜色格式化。修改 Python 脚本可更改输出的视觉外观，包括颜色和文本样式（如粗体）。
例如，print 语句可包含 ANSI 转义序列：
print(f"\033[1;32m{style}\033[0m")
这些数字序列为 ANSI 转义码，用于控制终端格式化。本例中状态行将以绿色粗体文本显示。
当活动输出样式更改时，状态行会随之更新。由于逻辑在脚本中实现，状态行会动态反映当前配置以及脚本应用的任何格式调整。
图 8.14 - 显示活动输出样式的状态行
扩展状态行功能
由于状态行逻辑由可执行脚本驱动，它可以显示运行时环境可用的任何信息。这包括来自外部系统的数据、股票价格、新闻源或其他动态检索的信息。
输出样式的更多高级功能可以通过进一步扩展脚本逻辑来实现。
在本节中，你使用 Python 脚本实现了一个自定义状态行，并将其集成到 Claude Code 的配置中。你学习了运行时信息如何通过标准输入传递，如何提取结构化数据（如活动输出样式），以及如何在界面中显示动态值。这表明 Claude Code 的可扩展性不仅限于输出格式，还允许可执行逻辑塑造开发环境本身。基于此能力，下一节将通过读取记录数据并提取最后的用户提示词来进一步增强状态行。
高级状态行：显示最后的用户提示词
在主目录中，.claude 目录包含一个 projects 子目录。projects 内部的每个子目录对应一个项目，并保存其对话历史和会话数据。目录名称反映了项目路径，其中路径分隔符（如 /）被替换为 ‑。
图 8.15 - 存储会话数据的 Claude projects 目录
在每个项目目录中，JSONL 文件存储对话日志。每个文件由 UUID 标识。这些 JSONL 文件包含会话期间交换的完整消息序列。
检查一个此类 JSONL 文件会发现，每一行代表一个对应消息条目的 JSON 对象。当提交新的用户消息时，一个新的 JSON 对象会被追加到文件中。例如，如果用户发送 "hello"，会出现一个新条目，包含以下内容：
-
"role": "user" -
"content": "hello"
此条目后面跟随的是助手的回复。
图 8.16 - 存储用户提示词的 JSONL 记录
Claude 将所有用户提示词存储在这些 JSONL 文件中。目标是扩展状态行，使其显示当前会话中用户发送的最后一个提示词。此提示词必须从作为输入提供给状态行脚本的 transcript_path 键所引用的记录文件中检索。
只应显示用户提示词。必须排除状态行调用等命令以及助手回复。
所有实现均包含在现有的 statusline.py 文件中。
定义状态行需求
定义了一个 /statusline 指令，用于使用一个额外字段（当前会话中用户的最后一个提示词）来扩展状态行。
当 Claude Code 执行状态行命令时，它会通过标准输入将结构化运行时数据传递给状态行脚本。此 JSON 载荷包含诸如 transcript_path 之类的字段，指向当前会话的 JSONL 记录文件。
脚本从其输入中读取 transcript_path 值，加载引用的 JSONL 文件，并搜索最近的用户消息。该消息即为显示的提示词。仅考虑真实的用户提示词。助手回复和命令调用被排除。
以下 /statusline 指令扩展状态行，使其显示会话记录中最近的用户提示词。
/statusline 我希望你同时显示当前会话中用户的最后一个提示词。
你应该从 transcript_path 中的文件示例获取提示词。 /path/to/transcript.jsonl
请记住用户提示词将是一个 role="user" 的消息。
请记住完全不要有命令回复，在这个示例中只有用户提示词。
在演示案例中，记录文件中最近的用户提示词是 hello，它显示在状态行中。只应显示真实的用户提示词；即，必须排除记录在案的状态行命令和助手回复。因此，脚本会过滤条目，以便仅考虑有效的用户提示词。
该指令明确指出所有逻辑必须在现有的 statusline.py 文件中实现。这防止了创建额外的脚本或 Shell 实用程序，并确保功能保持在状态行实现内部。
访问记录路径
在 statusline.py 内部，结构化输入被加载为字典。脚本访问 transcript_path 键，该键已知存在。该路径被传递给一个负责检索最后用户提示词的函数。状态行脚本检索记录路径并从会话日志中提取最近的用户提示词。
图 8.17 - 读取记录路径以获取最后的用户提示词
函数返回提示词后，它会作为状态行输出的一部分被打印。
实现最后用户提示词的检索
检索函数执行以下操作：
-
确认记录文件路径存在
-
打开并读取该路径下的 JSONL 文件
-
遍历文件的每一行
-
将每一行解析为 JSON 字典对象
-
检查每个条目中的
message键 -
检查
message内部的role字段 -
如果角色是
user，提取content字段
以下 Python 函数读取记录文件，解析 JSONL 条目，并检索最近的有效用户提示词。
import json
import sys
import os
def get_last_user_prompt(transcript_path):
"""
Extract the last user prompt from the transcript file.
"""
try:
if not os.path.exists(transcript_path):
return "No transcript found"
with open(transcript_path, "r") as f:
content = f.read().strip()
if not content:
return "Empty transcript"
# Split by lines and process each JSON object
lines = content.split("\n")
for line in reversed(lines):
try:
entry = json.loads(line)
# Entry has 'message' and not a command
if entry.get("type") == "message" and entry.get("role") == "user":
message_content = entry.get("message", {}).get("content", "")
# Skip command messages starting with /
if message_content.startswith("/"):
continue
return message_content
except json.JSONDecodeError:
continue
return "No user prompt found"
except Exception as e:
return f"Error reading transcript: {e}"
命令式占位符和助手回复会被跳过。仅保留有效的用户提示词。迭代过程中找到的最近的有效用户提示词将作为结果返回。
此时，statusline.py 文件执行三个不同的步骤。首先，它从标准输入读取结构化运行时输入。其次，它从该输入中提取 transcript_path 值。第三，它打开引用的 JSONL 记录文件，扫描最近的有效用户提示词，并将该值打印到标准输出。
测试并完成实现
实现检索和显示最后用户提示词的逻辑后，下一步是确认行为按预期工作。这涉及验证新的记录条目是否正确追加、是否仅提取有效的用户提示词，以及每次交互后状态行是否一致更新。
验证实现
提交新消息时，会在 JSONL 记录文件中追加一个新条目。记录下助手的响应后，状态行会更新以反映新提交的提示词。
重复此过程可确认以下几点：
-
每条新消息都会添加一个新的 JSONL 条目
-
显示的提示词会相应更新
-
脚本能持续检索到最近的有效用户提示词
更改输出样式（例如改为 YAML 简洁样式），以确认新功能保持完好。状态行继续无误地显示最后的提示词。
图 8.18 – 状态行反映记录文件中最新的用户提示词
更新输出标签
在前几节中，我们探讨了如何使用输出样式控制 Claude Code 的行为，以及如何通过状态行监控活动。这两套机制共同为塑造系统在运行时的通信与操作方式奠定了基础。
有了这些能力，我们现在可以展望当它们结合并扩展时，智能体编码的未来可能是什么样子。我们不再依赖单个助手会话，而是可以让多个专业化的智能体协同工作，每个智能体都配置有自己的角色、上下文和输出行为。
AI 编码的未来：专业化智能体团队
随着智能体开发工作流的演进，单个助手会话往往不足以应对复杂任务。取而代之的是，多个专业化智能体可以协作，每个智能体负责特定的角色或领域。通过结合前文介绍的配置技术（如输出样式和运行时状态行），我们可以开始将这些智能体构建为一个协调系统，而非单一的通用助手。
智能体编码与多实例
智能体编码的一种体现是同时运行多个 Claude Code 实例，每个实例拥有以下要素：
-
输出样式
-
上下文
-
角色
我们不再依赖单个通用会话，而是将职责分发到各个专业化实例中。
这映射了一个小型初创团队的结构。
图 8.19 – 智能体角色展示为专业化的初创团队
在小型初创团队模型中，不同类型的工作会路由给不同的专家。UI 变更由前端工程师 Vinay 处理。后端变更由 Rajesh 处理。部署问题由 DevOps 工程师 Alex 处理。每个人都有独特的职责和技能，且倾向于以匹配其工作的方式进行沟通。此处使用的所有姓名均为�构，仅用于演示工作流中的示例角色。以下是一些示例：
-
面向 DevOps 的实例可能使用 YAML 样式输出
-
面向后端的实例可能使用 OpenAPI 规范格式
-
面向文档的实例可能使用结构化学习样式输出
每种输出样式均在系统层面配置，并影响响应的生成方式。一个实例也可能关联不同的命令、智能体和上下文约束。
实例可以按其职责命名，类似于命名的团队成员。
命名与基于角色的上下文
每个 Claude Code 实例可以代表一个命名角色，例如：
-
frontend‑engineer（前端工程师） -
backend‑engineer（后端工程师） -
devops（运维开发） -
security‑review（安全审查）
名称反映了：
-
输出样式
-
上下文
-
处理的任务类型
在终端间切换相当于在专业化团队成员间切换。安全相关任务在安全聚焦的实例中处理。UI 任务在前端聚焦的实例中处理。
这种结构实现了受控的上下文边界和清晰的职责分离。多个专业化的 Claude Code 实例作为协调智能体在开发工作流中运行。
在本最后一节中，你探索了多个 Claude Code 实例如何并行运行，每个实例都配置有独特的输出样式和上下文聚焦。你了解了目录级配置如何影响行为，以及专业化会话如何映射开发团队中基于角色的协作。这巩固了本章的核心观点：Claude Code 不是单一固定的界面，而是一个可配置系统，可被塑造为特定任务的智能体。
总结
在本章中，你学习了 Claude Code 输出样式的工作原理，以及如何在用户或项目范围内创建、审查和应用它们。你还考察了选择输出样式如何改变 Claude Code 的系统提示词行为，以及 YAML 和 HTML 等结构化格式如何改变响应的生成与消费方式。本章通过将文件生成行为嵌入输出样式，并使用读取运行时输入和记录历史的 Python 脚本实现自定义状态行逻辑，将此配置工作扩展到了工作流控制。
这些信息之所以有用，是因为它建立了对 Claude Code 通信方式的直接控制，而不仅仅是它生成的内容。我们不再将模型输出视为固定的散文，输出样式允许将响应结构、语气和工作流行为定义为开发环境的一部分。这使得为不同任务定制 Claude Code 会话、并行运行多个专业化会话，以及将这些配置作为可复现工作流的一部分进行版本控制成为可能。
在下一章中，我们将把目光投向理解智能体技能，作为扩展 AI 智能体能力的一种机制。
获取本书的 PDF 副本、代码包及更多内容
扫描二维码（或访问 packtpub.com/unlock）。按名称搜索本书，确认版次，然后遵循页面上的步骤操作。
注：请准备好发票。直接在 Packt 网站购买的不需要发票。
第三部分：高级智能体与深度系统设计
在本书的最后一部分，你将探讨现代编码智能体如何大规模且长周期地运行。我们将探索智能体技能，如结构化能力扩展，并分析它们如何影响上下文流和执行模式。你将看到 Claude Code 如何跨环境运行、协调并行开发工作，并支持更高级的编排策略。
我们还将深入系统设计。你将探讨什么使智能体具备“深度”，如何维持长时间运行的执行，以及 LangChain 深度智能体等编排框架的内部结构。读完这部分，你将对高级智能体系统的工程实现有实践性和架构层面的理解。
本部分包含以下章节：
-
第 9 章，理解智能体技能
-
第 10 章，使用 Claude Code Desktop
-
第 11 章，理解深度智能体
9 理解智能体技能
智能体技能由 Anthropic 团队于 2025 年 10 月引入，作为扩展 AI 智能体能力的一种机制。技能允许将能力打包为结构化单元，包括自定义工作流和特定任务指令，使智能体能够执行更复杂和协调的任务。通过封装定义好的行为，技能将智能体的成就扩展到了通用推理之外。Claude 可以根据其描述字段与对话上下文的匹配情况，自动调用技能。
Agent 技能
本章深入探讨 Agent 技能的概念，建立清晰的理解，明确它们是什么，以及为何在设计更强大的 Agent 系统时至关重要。
本章通过层层递进的方式探索技能，从基础概念和在Claude Code等环境以及LangChain DeepAgents（docs.langchain.com/oss/python/deepagents/overview）等工具中的实际应用入手。随后我们将深入表层之下，分析调用技能时上下文在 Agent 内部如何流动，阐明系统的内部运作机制。最后，我们将通过在真实 Agent 中对技能的具体实现来整合这些视角。目标不仅是理解如何使用技能，还要掌握其底层设计与动机，从而获得全面且技术扎实的概念理解。
技能背后的核心概念是渐进式披露。技能不会永久加载到 Agent 的活动上下文中。相反，系统仅在技能与当前任务相关时才加载它。这种设计防止了不必要的指令进入工作上下文，有助于在推理过程中保持清晰。本章后面我们将探讨调用技能时这种动态加载是如何工作的，以及它如何影响 Agent 内部的上下文流动。
本章将涵盖以下主题：
-
Agent 技能的要点
-
深入探究 Agent 技能
-
Agent 技能与其他 Agent 原语的对比
Agent 技能的要点
在本节中，我们将见证 Agent 技能的实际运作，并演示如何将其作为工作流的一部分加以使用。我们将对比完成同一任务的两种方法：首先不使用技能，然后使用技能，以便清晰地观察 Agent 在每种情况下的行为表现。
前往代码仓库并切换到hookhub分支，然后打开提交列表。选择标题为improved hookcard and hero with multi agent working的提交。此提交将作为我们的起点。
由于后续会添加更多提交，分支历史可能会向前推进。然而，我们必须从这个确切的提交开始。复制其哈希值，打开 IDE，并切换到该分支和提交：
git switch project/hookhub c125545ca118f51c07eb6defe61ba727dbf05788
切换后，会出现一个新的hookhub目录。该目录包含前几节开发的所有代码。
进入该目录并安装依赖：
cd hookhub
npm install
安装完成后，启动开发服务器：
npm run dev
HookHub 应用现已在端口3000上本地运行。这恢复了演示所需的确切基准环境。
图 9.1 – HookHub 在本地运行
场景 1：不使用技能进行样式设计
图 9.1所示的 UI 有意保持简洁。假设我们希望 HookHub 应用采用特定的视觉形象，并完全匹配 Anthropic 的设计语言。
不使用技能时，我们可以直接提示：
Make this web app Anthropic style.
此时，代码仓库中不包含任何关于 Anthropic 品牌指南的参考。Agent 会扫描项目文件，甚至从anthropic.com获取信息。它从实时网站动态推导设计语言并开始实施更改。
这种方法行之有效。Agent 更新背景颜色、调整排版并应用视觉优化。最终结果非常接近 Anthropic 的美学风格，展现了令人印象深刻的能力。
然而，请考虑其影响。每次重复此任务时，Agent 都会再次获取并推导相同的设计语言。如果我们重复执行此工作流，每次都会重新引入冗余的上下文收集过程。
一种可能的解决方案是将设计语言直接嵌入CLAUDE.md文件。问题在于，该上下文随后会附加到每一个提示中，包括与之无关的后端任务。这会导致不必要的上下文膨胀并最终引起性能下降。
场景 2：使用技能进行样式设计
技能提供了一个更优雅的解决方案。我们可以创建一个指定 Anthropic 主题设计语言的技能。每当我们处理前端工作时，Claude Code即可选择该技能、加以使用，并动态加载所需的设计上下文。让我们看看具体操作方法。
打开官方 Anthropic 示例技能仓库（github.com/anthropics/skills）。每个技能位于各自的目录中。导航到brand‑guidelines技能并检查其SKILL.md文件。
本章中的部分示例改编自 Anthropic Skills 仓库（github.com/anthropics/skills），遵循 Apache License 2.0 许可证。实现和行为可能会随时间演变。
一个技能可能包含多个文件，不仅限于 Markdown。它可以包含脚本、可执行文件和结构化资源。在本例中，SKILL.md文件定义了 Anthropic 的官方品牌颜色、排版和设计资产。
该文件以前言开头。仅此部分在技能被选中时注入 Agent 系统提示词。Markdown 文件的其余部分包含详细的品牌指南，仅在技能被激活时才加载到提示词中。
这反映了我们之前通过子代理探索的选择性加载机制。上下文是有条件地注入，而非全局注入。
来自官方Claude Code市场的技能在启动时若有新的上游版本可用会自动更新。第三方市场技能可能需要手动更新，或通过/plugin进行显式的自动更新配置。
在 Claude Code 中安装技能
要为我们的编码 Agent 装备这些技能，请将 Anthropic 技能仓库作为市场插件添加：
/plugin add marketplace anthropic/skills
Claude Code会将仓库本地克隆到.claude/plugins目录中。
运行/plugins验证安装。浏览可用插件。出现两个类别：
-
文档技能，包含 Excel 和 PowerPoint 等文档处理能力
-
示例技能，包含前面回顾的品牌指南技能
一个值得注意的细节是，当Claude（而非Claude Code）推出创建幻灯片和文档的支持时，是与技能一同宣布的。这是因为那些功能在内部正是使用 Agent 技能构建的。换句话说，生成文档和演示文稿的能力由我们在此讨论的相同技能机制提供支持。
安装示例技能。安装后，重启Claude Code并询问以下内容：
Which skills do you have?
Agent 现在会列出可用技能，包括我们接下来将使用的brand‑guidelines。
图 9.2 – Claude 列出已安装技能，包括 brand-guidelines
启用技能进行样式设计
清除上下文并启动一个全新的Claude实例。询问以下内容：
Can you make sure that the logo is according to Anthropic brand?
Agent 扫描代码仓库，随后请求使用brand‑guidelines技能的权限。技能描述随即显示。批准其使用。
批准后，Claude将brand‑guidelines目录动态加载到上下文中。仅相关的 Markdown 文件被注入。这一额外上下文使 Agent 能够根据官方品牌定义应用设计变更。
关键观察在于此上下文是动态加载的。它不会永久附加到每个提示词上。这种渐进式上下文加载保持了工作上下文窗口的整洁与高效。此过程也称为渐进式披露。
如果你希望仅通过斜杠命令调用技能，请在技能前置元数据中启用 disable‑model‑invocation: true 标志。
应用更改后，运行构建流程：
npm run build
然后，重启开发服务器：
npm run dev
更新后的设计现应呈现细微的优化，包括排版调整和品牌对齐的样式。此处的主要目标并非视觉差异，而是展示通过技能实现的受控上下文注入。
图 9.3 – 通过技能应用品牌指南样式后的 HookHub 界面
技能不限于静态 Markdown 上下文。部分技能包含可执行脚本。
以 skill‑creator 为例。其目录包含多个 Python 脚本。在相应的 SKILL.md 中，智能体被告知可以执行这些脚本。
脚本可用 Python、Bash、JavaScript 或环境支持的任意语言编写。只要在技能定义中清晰描述其行为，智能体即可将其作为确定性工具使用。
这种方法支持结构化工作流。若特定流程可编码为确定性脚本，则可通过技能将其组合为高阶能力。智能体继而可执行脚本序列并组合其输出，以完成复杂任务。
深入探究智能体技能
本节我们将通过引入自定义技能，深入探究智能体技能。我们还将回顾一种技能，它不仅包含 SKILL.md 文件，还包含智能体可执行以协助完成任务的辅助脚本。
我们要考察的技能托管在一个在线仓库中。我们将下载它、在本地集成，随后通过修改和改进来迭代它，以契合我们的需求。这一过程演示了技能在设计结构化智能体工作流时所提供的灵活性。
探索 Claude 技能市场
我们从一个名为 claude‑skills‑marketplace (github.com/mhattingpete/claude-skills-marketplace/tree/main) 的仓库开始，该仓库基于 Apache 2.0 许可证发布。这是包含 Claude Code 技能的众多仓库之一，这些技能可被下载并集成到 Claude Code 或任何其他支持技能的智能体中，例如 Claude Desktop 或 LangChain DeepAgents。
该仓库包含多个可安装的技能。正如上一节所示，它甚至可通过插件系统作为市场添加到 Claude Code 中。
在 Engineering Workflows（工程工作流）文件下，我们找到了一个名为 git‑pushing 的技能。该技能旨在协助将代码推送到 GitHub。
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
---
name: git-pushing
description: Stage, commit, and push git changes with conventional commit messages. Use when user wants to commit and push changes, mentions pushing to remote, or asks to save and push their work. Also activates when user says "push changes", "commit and push", "push this", "push to github", or similar git workflow requests.
---
# Git Push Workflow
Stage all changes, create a conventional commit, and push to the remote branch.
## When to Use
Automatically activate when the user:
- Explicitly asks to push changes ("push this", "commit and push")
- Mentions saving work to remote ("save to github", "push to remote")
- Completes a feature and wants to share it
- Says phrases like "let's push this up" or "commit these changes"
## Workflow
**ALWAYS use the script** - do NOT use manual git commands:
```bash
bash skills/git-pushing/scripts/smart_commit.sh
```
With custom message:
```bash
bash skills/git-pushing/scripts/smart_commit.sh "feat: add feature"
```
Script handles: staging, conventional commit message, Claude footer, push with -u flag
打开该技能的 SKILL.md 文件，可见如下描述：
-
使用规范提交信息暂存、提交并推送 Git 变更
-
当用户想要提交并推送变更、提及推送到远程或要求保存工作时使用
文件顶部的 YAML 前置元数据是唯一加载到 Claude Code 智能体系统提示词中的部分。文件其余部分仅在技能被选中执行时读取。
技能中的既定工作流
在 SKILL.md 的工作流部分，我们看到智能体被指示始终使用名为 smart_commit.sh 的脚本。
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
---
name: git-pushing
description: Stage, commit, and push git changes with conventional commit messages. Use when user wants to commit and push changes, mentions pushing to remote, or asks to save and push their work. Also activates when user says "push changes", "commit and push", "push this", "push to github", or similar git workflow requests.
---
# Git Push Workflow
Stage all changes, create a conventional commit, and push to the remote branch.
## When to Use
Automatically activate when the user:
- Explicitly asks to push changes ("push this", "commit and push")
- Mentions saving work to remote ("save to github", "push to remote")
- Completes a feature and wants to share it
- Says phrases like "let's push this up" or "commit these changes"
## Workflow
**ALWAYS use the script** - do NOT use manual git commands:
```bash
bash skills/git-pushing/scripts/smart_commit.sh
```
With custom message:
```bash
bash skills/git-pushing/scripts/smart_commit.sh "feat: add feature"
```
Script handles: staging, conventional commit message, Claude footer, push with -u flag
该脚本包含实际的 Git 逻辑，包括 git add、git status 和 git commit 操作。技能作者有意限制主智能体发出原始 Git 命令。取而代之，智能体必须使用指定脚本。
这阐释了一个核心概念。技能编码的是既定工作流。若团队希望提交遵循特定结构或流程，可将该逻辑打包进技能。智能体随即以受控方式获得该能力。
审查脚本
在 scripts 目录中，我们找到了 smart_commit.sh。该脚本定义了 Git 执行流程。智能体仅在决定使用 git‑pushing 技能时才能运行此脚本。
此脚本包含实际执行逻辑。它运行一系列 Git 命令，如暂存变更、检查状态、使用特定信息提交。主智能体在使用 git‑pushing 技能时预期运行此脚本。关键在于，智能体仅在决定使用该技能后才知晓此脚本。脚本仅在技能被选中后成为可用上下文的一部分。
与我们之前见到的品牌指南技能相比，此技能不仅提供参考内容。它包含智能体可执行以协助完成任务的辅助脚本，此处任务即提交并推送代码到 GitHub。
这种脚本运行能力赋予了我们极大灵活性。若我们有想要以代码形式确定性定义的工作流，可将其打包进技能。智能体随后可将运行这些脚本作为完成工作流的一部分，而非即兴发出一系列手动命令。
尽管这可能类似于 MCP，但机制不同。MCP 实现 API 调用和与外部服务的通信。技能则通过注入结构化上下文并可选暴露脚本来运作。
创建项目级自定义技能
切换到 project/skills 分支
要创建项目级技能，我们需要在 .claude 目录下定义它，使其作用域限定在该仓库内。
创建以下结构：
.claude/
skills/git-pushing/
scripts/
smart_commit.sh
SKILL.md
结构如下所示：
图 9.4 – git-pushing 技能的本地技能目录结构
这与市场技能的结构相同。
将 GitHub 仓库中 SKILL.md 和 smart_commit.sh 的内容复制到对应的本地文件中。SKILL.md 文件引用了 scripts/smart_commit.sh，因此保持相同的目录结构可确保兼容性。
此时，技能已在本地完全复刻。
图 9.5 – 引用 smart_commit.sh 自动化脚本的本地 SKILL.md
虽然本可通过插件系统安装，但手动复制能提供对定制的完全控制。
使用自定义技能
从项目目录打开 Claude Code 会话并添加以下提示词：
List available skills.
新创建的项目级 git-pushing 技能将与先前安装的市场技能一同显示。
输入以下内容：
push changes
Claude 将询问是否使用 git-pushing 技能。批准后，它会加载 SKILL.md 并确定必须执行 smart_commit.sh。
Agent 不会发出单独的 Git 命令，而是运行该脚本。在某些情况下，脚本可能因 Git 错误而失败。若发生这种情况，Claude 不会停止，而是回退到其默认推理模式。它会分析仓库状态，建议运行 git add -A，使用自己的逻辑创建提交，然后手动推送变更。
这意味着 Claude 能利用其默认行为解决问题并完成推送。这一点很重要，因为技能并不取代 Agent 的推理能力。当技能失败时，Claude 能回退到默认行为并继续任务。
如果脚本执行失败，生成的提交将不是通过技能产生的，而是通过 Claude 的默认行为产生的。这一区别很重要。技能提供结构化工作流，但不会剥夺 Agent 的通用推理能力。如果脚本化工作流失败，Agent 仍可尝试利用其基础能力恢复并完成任务。
澄清这一点后，我们现在可以着手定制技能行为本身。
编辑技能行为
在 SKILL.md 的 When to Use（使用时机）部分添加一个额外的触发短语，例如 "push to remote"。
## When to Use
Automatically activate when the user:
- Explicitly asks to push changes ("push this", "commit and push", "push to remote")
- Mentions saving work to remote ("save to github", "push to remote")
- Completes a feature and wants to share it
- Says phrases like "let's push this up" or "commit these changes"
结束 --- 分隔符上方的所有内容均为 YAML 前言，会被注入到 Agent 的系统提示词中。分隔符下方的内容仅在技能被激活时加载。
---
name: git-pushing
description: Stage, commit, and push git changes with conventional commit messages. Use when user wants to commit and push changes, mentions pushing to remote, or asks to save and push their work. Also activates when user says "push changes", "commit and push", "push this", "push to github", or similar git workflow requests.
---
# Git Push Workflow
Stage all changes, create a conventional commit, and push to the remote branch.
## When to Use
Automatically activate when the user:
- Explicitly asks to push changes ("push this", "commit and push", "push to remote")
- Mentions saving work to remote ("save to github", "push to remote")
- Completes a feature and wants to share it
- Says phrases like "let's push this up" or "commit these changes"
为什么会这样？我们编辑了 SKILL.md 内的 When to Use 部分并添加了 "push to remote" 短语。然而，该部分并不属于 YAML 前言。
只有文件顶部的 YAML 前言会在每次请求时被注入到 Agent 的系统提示词中。除非技能已被选中，否则分隔符下方的所有内容对 Agent 不可见。
这意味着我们所做的修改完全不会影响技能选择决策。
现在我们清除上下文以确保会话全新，并输入以下内容：
push to remote
Claude 仍会询问是否使用 git-pushing 技能。这并非因为我们添加的短语。而是因为原始前言已将该技能描述为处理提交和推送操作。"push to remote" 的意图在语义上足够接近前言中已涵盖的 "push changes" 或 "push to GitHub"。
因此，这里发生的情况非常重要。
技能选择完全由前言驱动。Agent 根据该 YAML 块中的 name 和 description 字段匹配用户意图。文件的其余部分在选择阶段不起任何作用。
只有技能被选中后，Claude 才会加载 SKILL.md 的其余部分，包括工作流指令和脚本引用。
这就是渐进式披露模型：
-
Agent 始终看到前言。
-
基于前言，它决定是否激活技能。
-
只有那时，它才会加载完整的技能上下文和任何辅助指令。
这就是为什么我们的修改是多余的。它被放置在了不参与选择过程的文件部分之外。
澄清这一点后，让我们继续修改脚本本身的行为。
启用自动技能批准
既然我们了解了技能选择的工作原理，请考虑以下场景。
如果技能触发正确，但每次使用时 Claude 都会暂停并请求批准才执行脚本，该怎么办？
在这种情况下，尽管工作流封装在技能内，我们仍引入了摩擦。每次提交和推送操作都需要手动确认。如果目标是创建一个流畅、有主见的工作流，重复的提示将违背初衷。
因此，下一步合乎逻辑的做法是改变的不是技能的选择方式，而是其执行方式。如果允许技能无需每次询问权限即可运行，会怎样？
确认技能触发正确后，选择允许 Claude Code 在无需每次询问批准的情况下使用此技能的选项。
执行此操作时，Claude 会更新 settings.local.json。
这很关键。
实际改变的不是技能本身。技能定义保持不变。取而代之的是，Claude 更新了本地配置，以便在选择该特定技能时，可无需交互式确认即可执行。
这意味着涉及两个独立的权限：
-
激活技能的权限
-
执行技能内定义脚本的权限
通过启用自动批准，我们消除了在未来运行中手动确认这两个步骤的需求。
现在，当我们运行 "push to remote" 时，Claude 将立即加载技能并执行 smart_commit.sh 而无提示。技能内定义的工作流将实现全自动化。
脚本成功运行后，我们检查生成的提交。
图 9.6 – 由 smart_commit.sh 自动化脚本生成的提交信息
如你所见，提交信息极简。它仅报告更新了特定数量的文件。
这并非 AI 生成的信息。
如果我们检查 smart_commit.sh，会发现提交信息是使用静态逻辑构建的。它统计修改过的文件数量，并将该数字插入到一个预定义的信息模板中。脚本内部没有调用 Claude。因此，尽管工作流被包装在一个技能中，但该工作流的智能水平完全由脚本的实现决定。这是一个重要的区别。技能并不自动意味着 AI 驱动的逻辑。技能只是一种打包机制。它可以包含确定性脚本、AI 调用，或两者兼有。
目前，我们的工作流是确定性且简单的。所以，我们要改进它。
修改脚本以使用 Claude CLI
我们现在请求 Claude 编辑 smart_commit.sh，使其调用 Claude CLI 来生成提交信息。
提示词如下：
can u please edit @.claude/skills/git-pushing/scripts/smart_commit.sh to use Claude Code cli to create the commit message like a pirate?
这将改变工作流的性质。
以前，脚本使用静态 shell 逻辑生成提交信息。
现在，它执行以下操作：
-
脚本应使用提示词调用
claude -p。-p标志以提示模式运行 Claude：它发送查询，将响应打印到stdout，然后退出。 -
Claude CLI 将动态生成提交信息。
-
脚本将在
git commit命令中使用该输出。
我们在这里创建了一个分层系统：
-
主 Claude Code 代理选择技能。
-
技能运行
smart_commit.sh。 -
脚本本身调用 Claude CLI。
-
Claude CLI 生成提交信息。
-
脚本完成提交和推送。
这就是组合。技能协调确定性执行。脚本协调 AI 调用。AI 调用生成结构化输出。脚本消费该输出。
我们可以运行以下命令：
push to remote
我们现在可以在提交信息中看到海盗风格的语言。
Figure 9.7 – Skill invoking the Claude CLI to generate an AI commit message
这证实了脚本成功在内部调用了 Claude CLI。
因此，我们已经从静态工作流转移到了混合确定性和 AI 工作流。
破坏预期结构
现在，如果目录结构不再与技能预期的一致，会怎样？为了探究这一点，请考虑此场景。我们回到 IDE 并有意破坏结构。我们将 smart_commit.sh 脚本从 scripts 目录移动到 git-pushing 目录的根目录。然后，我们完全删除 scripts 目录。
此时，结构不再与 SKILL.md 指定的内容匹配。技能定义期望脚本位于 skills/git-pushing/scripts/ 下，但文件现在直接位于 skills/git-pushing/ 下。这创建了一个不一致的设置。技能中描述的路径不再准确，且仓库结构在技术上现在是不正确的。
在结构不匹配后执行技能
清除上下文以确保一个全新的会话。
然后，输入以下内容：
push to remote
Claude Code 选择 git-pushing 技能并继续执行脚本。
即使目录结构不再与 SKILL.md 中描述的路径匹配，脚本仍然成功运行。
Figure 9.8 – Running the git-pushing skill after modifying the directory structure
这种行为很重要。技能之所以仍能工作，是因为技能最终将上下文和指令注入代理。即使 SKILL.md 内部的路径引用不准确，代理也会推理仓库结构并在新位置找到 smart_commit.sh。不匹配并未阻止执行。代理解析运行 smart_commit.sh 的指令，搜索项目，找到文件，并执行它。
因此，即使破坏了声明的结构，工作流仍然成功完成。
但为什么技能仍然有效？
之所以有效，是因为技能不是绑定到确切文件路径的刚性绑定。它们提供上下文指令。即使上下文包含不准确的路径，代理也能通过检查项目结构来解析它。执行之所以成功，是因为文件仍然存在于仓库中的某个位置。代理进行了适应。
现在考虑一个略微不同的场景。如果 smart_commit.sh 被完全删除会怎样？
此时，没有文件供代理定位。工作流无法执行，因为所需的工件不再存在。这说明了边界：如果结构不一致但文件存在，代理可以恢复。如果文件不存在，执行就会失败。
在隔离的子代理上下文中运行技能
默认情况下，技能在当前对话上下文中运行。但是，可以通过设置以下内容在隔离的子代理上下文中执行它：
---
context: fork
agent: Explore
---
当 context 设置为 fork 时，Claude 在单独的执行分支中运行技能。这将中间推理和工具使用与主对话隔离开来。
agent 字段决定哪种子代理类型处理执行（例如，Explore 或 Plan）。
为了确保技能仅通过斜杠命令（例如，/skill-name）触发，而不被 Claude Code 自动调用，请在前置元数据中添加 disable-model-invocation: true。
将代理技能与其他代理基元进行比较
在本节中，我们将代理技能与其他代理基元进行比较，例如 MCP、子代理、记忆和斜杠命令。比较重点关注上下文管理、上下文工程和执行流程。
代理技能与 MCP
代理技能和 MCP 服务器都是现代代理工具包中的重要工具，但它们解决不同的问题，并在上下文架构的不同层面上运行。代理技能是程序性知识容器。它们是包含指令、脚本和资源的文件夹，用于教导 AI 代理如何一致地执行专门任务。一致性是关键思想。通过代理技能，我们打包一个工作流并将其交给代理，以便它以预定义的方式执行任务。从上下文工程的角度来看，技能基于渐进式披露。
当与编码代理（或任何支持技能的代理）的会话开始时，代理仅加载可用技能的简短描述和名称。此阶段的上下文成本很低。通常，无论技能内部多么复杂，每个技能消耗约 100 到 200 个 token。
当技能与任务相关时（此决定由代理做出），从 SKILL.md 文件衍生出的完整指令会被加载到上下文中。只有当技能被主动使用且代理决定执行脚本时，该脚本才会被加载。如果技能包含多个脚本，未被使用的脚本不会被加载到上下文中。由于这种渐进式加载机制，技能具有很高的上下文效率。
现在考虑 MCP。在 MCP 架构中，工具定义和服务器规范在对话开始时预先配置。这影响上下文效率。例如，五个 MCP 服务器可能在发送第一个提示词之前就消耗 50,000 个 token。
MCP 解决不同的问题。它将代理连接到外部资源。这是 MCP 服务器的目的。
技能解决不同的问题。它们赋予代理以一致的方式执行专门任务的能力。
因此，虽然两者都是代理基元，但它们处理系统的不同层面。
调用和执行差异
技能和 MCP 工具都是基于智能体的判断来调用的。智能体会根据各自的描述决定是使用技能还是 MCP 工具。
因此，调用机制是相似的。在两种情况下，智能体都会评估该能力是否与任务相关。
一个有趣的实验是将同一个能力实现两次：一次作为技能，一次作为由 MCP 服务器暴露的 MCP 工具。观察智能体在实践中选择哪一个，将揭示它是如何对这些基元进行推理的。
然而，执行方式有所不同。对于 MCP，执行发生在 MCP 服务器内部。服务器可以在本地运行，也可以部署在云端。对于技能，执行通常发生在主智能体线程的本地环境中。技能中定义的脚本作为智能体主要执行流的一部分来执行。但是，如果技能前置元数据指定了 context: fork，则技能会在隔离的子智能体上下文中运行，而不是在主智能体中。
在推理架构时，这种执行位置的区别非常重要。
智能体技能与子智能体
智能体技能与子智能体的相似之处在于，它们都允许我们为特定任务定义专门的指令。技能包含结构化指令和可选脚本。子智能体也可以定义自己的指令。
关键区别在于上下文隔离。子智能体在其自己隔离且全新的上下文窗口中运行。它们非常适合长时任务，否则这些任务会显著扩展主智能体的上下文窗口。相比之下，技能在智能体的主上下文中运行。当调用技能时，其指令会被加载到现有的上下文窗口中，而不是一个单独的窗口。
技能和子智能体都是由主智能体调用的。主智能体决定是将任务委托给子智能体，还是使用技能来执行。
在灵活性和控制方面，子智能体提供了更多的灵活性。使用子智能体时，系统提示词可以动态调整并针对特定需求进行定制。而使用技能时，系统提示词保持为主智能体的提示词，这通常由供应商管理，不易修改。
作为经验法则，请注意以下几点：
-
如果任务繁重且有膨胀主上下文窗口的风险，子智能体是合适的选择。
-
如果目标是赋予智能体自动专业知识或为重复性任务强制执行特定方法论，技能是更好的选择。
两者都是有价值的基元，但它们在不同的上下文和执行模型下运行。默认情况下，技能在主智能体内联运行，而子智能体在隔离的上下文中执行。然而，技能可以指定 context: fork，这使其在类似子智能体的轻量级隔离上下文中运行，尽管配置控制较少。
为了将技能和子智能体置于更广泛的 Claude Code 模型中，下表将它们与 MCP 服务器和斜杠命令进行了比较。
| 维度 | 技能 | MCP | 子智能体 | 斜杠命令 |
| :--- | :--- | :--- | :--- | :--- |
| 目的 | 标准化任务执行方式 | 连接外部服务 | 将工作委托给隔离智能体 | 用户触发的快捷方式 |
| 上下文加载 | 先加载前置元数据，使用时加载完整内容 | 会话开始时加载工具 | 每次运行全新上下文 | 注入完整提示词 |
| 触发方式 | 智能体决策 | 智能体决策 | 智能体委托 | 用户运行 /command |
| 执行位置 | 主智能体线程 | MCP 服务器（本地或远程） | 隔离的子智能体上下文 | 主智能体线程 |
| 上下文隔离 | 共享主上下文 | 外部执行 | 完全隔离 | 共享主上下文 |
| 脚本支持 | 是 | 否 | 是 | 否 |
| 失败处理 | 智能体回退到推理 | 智能体处理服务器错误 | 主智能体重试或适应 | 无 |
| 最佳用例 | 可重复的工作流 | 外部 API 或服务 | 长时任务 | 快速操作 |
| 上下文效率 | 高（懒加载） | 低（工具预先加载） | 高（工作卸载） | 低（每次全量提示词） |
| 定制化 | 完全控制 | 服务器定义 | 灵活 | 有限 |
表 9.1 – 智能体基元对比
总结
在本章中，我们从实践和架构两个角度探讨了智能体技能。我们首先通过直接提示智能体与使用技能封装结构化行为的实操对比，理解了智能体技能的核心要义。通过 HookHub 示例，我们观察到技能如何实现渐进式上下文加载，使智能体能在需要时动态注入仅相关的指令，而非膨胀主上下文窗口。随后我们通过创建自定义项目级技能、集成辅助脚本、修改其行为，甚至增强其以调用 Claude CLI，进行了更深入的探索。这让我们看到技能如何打包固化的工作流，将确定性执行与 AI 生成输出相结合，并在脚本失败时仍允许回退行为。最后，我们通过将技能与 MCP 和子智能体对比，将其置于更广泛的智能体领域中，阐明了每个基元在上下文架构、执行流和控制方面的运作方式。
我们不仅掌握了使用技能的能力，还建立了清晰的内部运作心智模型，明确了在设计更强大、更上下文高效的智能体系统时何时应用它们。
在下一章中，我们将学习如何在桌面应用程序中使用 Claude Code。
获取本书的 PDF 副本、代码包等
扫描二维码（或访问 packtpub.com/unlock）。按名称搜索本书，确认版本，然后按照页面上的步骤操作。
# 10 使用 Claude Code 桌面版注意： 请准备好发票。直接从 Packt 网站购买不需要发票。
在本章中，您将学习如何在 Claude 桌面应用程序中使用 Claude Code，在本地模式和云模式之间切换，并使用 Git Worktrees 并行运行多个编码智能体。您将了解如何协调独立的功能分支、管理后台智能体，并将独立开发的变更合并到单一代码库中。
本章的目标是展示如何使用 Claude Code 在本地和云环境中编排并行开发。
这很重要，因为它将开发从顺序的单线程工作转变为协调的多智能体工作流，使您能够扩展生产力，更快、更高效地构建功能。
在本章中，我们将涵盖以下主题：
-
介绍 Claude Code 桌面集成与后台智能体
-
运行模式：本地与云端
-
编排并行的本地和云智能体
-
理解 Claude Code 中的 Git Worktrees
-
合并并行功能分支
-
通过移动端在云端运行 Claude Code
10 介绍 Claude Code 桌面集成与后台智能体
在本节中，我们将探讨 Claude Code 桌面集成。Anthropic 已将 Claude Code 直接集成到 Claude 桌面应用程序和移动应用程序中，使开发任务和日常对话推理能在同一环境中进行。这减少了上下文切换的摩擦，实现了更流畅的工作流。除此之外，该集成还提供了开箱即用的基于云的后台智能体，直接在 Claude 中运行。
图 10.1 – Claude 桌面仓库选择界面
后台代理与并行开发
后台代理使得多个功能能够并发开发，而非顺序开发。在准备本演示时，这种工作流转变的影响立即变得清晰。无缝桌面集成与后台代理的结合，创造了一种与以往设置截然不同的开发体验。
此处演示的工作流涉及多个同时进行的操作，逐步跟进并不现实。取而代之的是，目标是专注于概念，并观察集成在实践中如何运作。重点在于理解这些能力如何结合以提升生产力，并重塑我们构建功能的方式。
Claude Code 安装与运行模式：本地与云端
Claude Desktop 应用包含一个 Code 标签页，可通过图形界面运行 Claude Code。它们共享相同的底层引擎和配置（CLAUDE.md、MCP 服务器、钩子等）。
以下屏幕截图显示了带有 Code 标签页的 Claude Desktop 界面。
图 10.2 – Claude Desktop Code 标签页界面
打开 Code 标签页后，Claude Code 工作区随即出现，允许你选择项目文件夹并开始与代码库交互。
图 10.3 – Claude Desktop 中的 Claude Code 工作区
选择工作区文件夹（本地工作树模式）
在开始任何工作前，请先选择一个文件夹。该文件夹将成为 Claude Code 操作的工作区。在大多数情况下，此文件夹包含一个代码仓库，最好是 GitHub 仓库。
此处的重要细节是我们选择的是一个文件夹。
当工作方式设置为 Local worktree（本地工作树） 时，Claude Code 会在本地机器上启动 Git 工作树（稍后讨论）。所有操作均在本地进行。此模式下无任何内容在云端运行。
由于工作在本地机器上进行，Claude Code 需要一个目录来创建和管理这些工作树。这就是我们提供文件夹位置的原因，它将在此处执行工作。
我们打开工作方式选择器，并确认 Local worktree 已被标记。
图 10.4 – 在本地工作树模式下选择工作区文件夹
选定后，我们打开 Agentic‑Coding‑with‑Claude‑Code 目录。该目录现在是所有操作将运行的工作区。此时，Claude Code 正使用 Git 工作树在本地运行。
切换至 Claude Code Web（云端模式）
现在将工作方式切换至默认选项，即标有云图标的选项。当我们切换到此模式时，Claude Code 将作为 Anthropic 基础设施上的托管实例运行。这被称为 Claude Code web / remote workers / background agents（Claude Code 网页版 / 远程工作器 / 后台代理）。
在此模型中，Anthropic 在其环境中运行容器化的 Claude Code 实例。这些实例需要访问我们的代码。我们通过授予 Claude Code web 访问我们 GitHub 仓库的权限来提供该访问权。
图 10.5 – 在 Claude Code Web（云端模式）中选择仓库
授权访问后，提示时工作流按顺序进行：
-
Anthropic 将启动一个
Claude Code实例。 -
该实例克隆仓库。
-
它直接在代码上工作。
-
它可以提交更改。
-
它可以创建拉取请求。
由于实例拥有仓库访问权，其运作方式如同项目中的任何其他开发者。此模型提供了规模优势。你可以并行运行多个 Claude 实例，每个实例同时处理不同的任务。并发实例的数量取决于你所配置和付费的额度。我们稍后将在本节中看到这种并行能力的实际演示。
Git 工作树如何实现并行开发
在 Local worktree（本地工作树） 模式下，Claude Code 依赖 Git Worktrees（Git 工作树）。Git 工作树允许我们将同一仓库的多个分支同时检出到不同的目录中，而无需多次克隆仓库。
图 10.6 – Git 工作树在本地模式下支持并行开发
当多个编码代理同时工作时，这变得尤为有用。
每个代理可在其自己的工作树中操作自己的分支。我们无需频繁暂存更改或在分支间切换。隔离通过文件系统中的独立目录来处理。
我们无需深入了解 Git 工作树即可进行此工作流。只需知道它们允许多个分支同时保持活动状态，且 Claude Code 利用此机制支持并行开发即可。
工作区选定且工作模式选定后，我们即可继续进行。
编排并行本地与云端代理
为建立上下文，Claude Code 的工作目录指向 Agentic‑Coding‑with‑Claude‑Code 仓库。
图 10.7 – 为编排本地与云端代理配置工作目录
此阶段的所有操作均在本地机器上运行。该仓库当前已检出至现有实现中使用的 hookhub 分支。
在本地运行 Next.js 应用
我们首先提示 Claude Code 在本地运行 Next.js 应用。
由于工作目录已配置，无需克隆任何内容。Claude Code 检查目录结构，检测到 hookhub 目录，进入该目录并列出文件。package.json 文件的存在表明这是一个 Next.js 项目。
图 10.8 – 使用 Claude Code 在本地运行 Next.js 应用
随后，它确定正确的执行顺序：
-
安装依赖：
npm install -
启动开发服务器：
npm run dev
开发服务器在后台运行。部分输出未显示，但进程成功完成。执行期间，Claude Code 检查 npm 版本。片刻后，Next.js 应用在端口 3001 启动，因端口 3000 已被占用而自动选择该端口。
图 10.9 – Next.js 开发服务器通过 Claude Code 在本地运行
协调并行本地与云端工作
在此阶段，我们扩展实现以演示如何跨本地与云端环境并行开发功能。
从 Claude Code 标签页切换至 Claude 应用，将其作为一个独立的研究环境，独立于你的本地 Claude Code 会话。通过打开新聊天并指示其搜索实现 Claude Code 钩子的在线仓库（重点关注 GitHub 星标数高的仓库），为其分配一个仓库发现任务。
图 10.10 – 在 Claude Code 中分配仓库发现任务
意图很明确：一旦确定仓库，结果将被传回 Claude Code 并集成到 HookHub 数据库中。
执行并发功能开发
当研究任务在云端运行时，我们返回当前在本地运行的 Claude Code 会话并请求一个新功能：
Add animations to the application
使用 Claude Code 进行并行开发：本地与云端工作流
本会话完全在您的本地机器上运行。您创建一个新实例，选择 Agentic‑Coding‑with‑Claude‑Code 仓库，并直接针对本地代码库实现功能。
接下来，在其运行时，我们创建另一个 Claude Code 实例，这次保持默认的云端选项。这将激活在 Anthropic 云端运行的后台代理。输入以下提示词：
Add to the project/hookhub branch a much cooler hero, make it anthropic style
这可以在以下截图中看到。
图 10.11 – 提示 Claude Code 在并行开发期间实现新功能
在提示词中，我们明确指示它执行以下操作：
-
在
project/hookhub分支上工作 -
添加一个显著改进的 Hero 区域
-
以 Anthropic 风格对其进行设计
图 10.12 – Claude Code 执行并发功能实现任务
在此阶段，所有三个任务都在本地和云端环境中并发执行：
-
一个云端研究进程，用于识别高星标的 Claude Code Hook 仓库
-
一个本地 Claude Code 会话，为 UI 添加动画（
vigilant fiestal） -
一个远程后台代理，在特定分支上重新设计 Hero 区域（
claude/anthropic‑hero‑design‑01Fo8dkJxcBUqWHyjhPfTHQS）
其中两个在本地执行，一个在 Anthropic 云端执行。
本地 Claude Code 实例完成动画功能并提出变更供审批。代理提出的变更需要批准。允许这些变更以便实施得以继续。
图 10.13 – 审查并批准 Claude Code 生成的本地代码变更
这完成了本地的动画任务，更新后的 UI 反映了新的动画效果。
观察远程分支创建
接下来，切换到云端运行的远程后台代理。代理在 Anthropic 云端环境中创建一个新分支。最初，它从 main 分支检出，而不是 project/hookhub。
这一点很重要，因为该功能旨在 project/hookhub 上实现。如果从 main 继续开发，可能会导致稍后合并时出现不一致。
不久之后，代理通过执行以下命令修正了分支上下文：
git checkout origin/project/hookhub
以下截图显示代理执行此命令以切换到正确的分支：
图 10.14 – 云端代理切换到正确的功能分支
这确保它现在正在针对正确的分支工作。它获取相关代码并再次列出项目文件，在继续进行 Hero 区域重新设计之前恢复完整上下文。
处理研究结果
与此同时，Claude Desktop 研究任务完成并返回高星标的 Claude Code Hook 仓库列表。输出包含多个 GitHub 仓库链接。
图 10.15 – Claude Code 显示精选的 Hook 仓库结果
复制完整的 URL 集合并将仓库信息粘贴到新的本地 Worktree 会话中，然后指示代理将这些链接添加到 HookHub 列表中。
图 10.16 – 将发现的仓库添加到 HookHub 配置
由于使用了 Git Worktree，此修改发生在与其特定分支关联的独立工作目录中。代理映射这些仓库并使用新条目更新 hooks.json 文件。
图 10.17 – 使用发现的仓库更新 hooks.json 配置
生成变更后，审查并接受它们。
图 10.18 – 审查并批准 hooks.json 配置的更新
此时，请注意以下几点：
-
动画功能已在本地完成并在 UI 中可见
-
数据库更新任务已使用新的仓库链接修改了
hooks.json -
远程云端代理在正确切换到
project/hookhub后正在处理 Hero 区域
以下截图显示了更新后的仓库链接并确认变更已应用。
图 10.19 – 确认更新后的 HookHub 仓库链接
理解 Git Worktree 布局
由于使用了 Git Worktree，单独的目录代表不同的活动分支。
主仓库目录保持完整。在此旁边，还有一个额外的 Worktree 目录：例如 zealous‑jemison（由 Claude Code 自动生成）对应另一个分支。每个并行任务都在自己的 Worktree 上下文中运行，这防止了功能实现之间的干扰。
在本例中，三个独立功能同时开发：应用程序的 UI 动画、Hook 仓库数据库的更新以及 Hero 区域的重新设计。每个功能都在单独的分支中实现，稍后再合并到单个分支中。
准备合并工件
剩下的挑战是整合所有工件。您有三个分支需要汇总：一个由云端代理更新的远程分支，以及两个包含动画变更和数据库更新的本地 Worktree 分支。
这些变更必须合并到一个单一、连贯的代码库中。因为一个分支存在于远程，而其他分支通过 Git Worktree 存在于本地，因此合并需要显式协调。
下一步是指示 Claude Code 合并这些分支，以便包括动画、更新的 Hook 仓库和重新设计的 Hero 区域在内的所有工件都合并到单个统一分支中，如以下提示词所示。
Merge all the commits here to branch project/hookub
从并行执行到受控集成的这一转变，完成了本地和基于云端的开发工作流的编排。
理解 Claude Code 中的 Git Worktree
在继续合并之前，我们需要了解 Git Worktree 的底层原理以及这种设置下版本控制的行为。目标是对 Claude Code 创建隔离工作副本时发生的情况建立正确的直觉。
当 Claude Code 创建 Worktree 时，它会创建一个与仓库关联但检出到不同分支的独立工作目录。
图 10.20 – Claude Code 用于并行开发的 Git Worktree 架构
Claude Code 如何使用 Worktree
当我们逐步查看时，流程更容易理解。以下是 Claude Code 创建并开始在 Worktree 内工作时发生的确切操作序列：
-
Claude Code 创建一个带有新分支的 Worktree。例如，我们可以将 Worktree 命名为
vigilant feistel（由 Claude Code 自动生成）。 -
所有代码和所有变更都发生在 Worktree 目录内。
-
当我们提交代码时，提交存在于
vigilant feistel分支中。 -
原始分支
project/hookhub保持完全未被触动。
5. 合并或放弃 Worktree 更改
-
如果我们对 Claude Code 的构建成果满意，则进行合并。
-
如果不满意，则删除 Worktree 和分支，不留任何烂摊子。
并行使用多个 Worktree
在图 10.20中，有两个 Worktree——vigilant feistel 和 zealous jemison：
-
我们打开编辑器，看到常规的
hookhub目录结构。 -
我们还看到两个额外的目录，其中每个目录都包含原始分支代码库的完全副本。
-
尽管目录结构匹配，但 Git 分支是分离的；
vigilant feistel和zealous jemison是独立的 GitHub 分支，不同于project/hookhub。 -
这允许执行多个并行任务，每个 Claude 实例在完全不同的分支中工作，并使用原始代码的全新副本。
使用多个代理进行工作需要编排，这意味着开发者必须协调多个工作上下文、分支和任务。Git Worktree 为管理这种协调提供了便捷的机制。
合并并行功能分支
本地 Claude Code 实例在 vigilant feistel 目录中实现了动画。该目录是一个链接到主仓库但检出到不同分支的 Git Worktree。
即使目标分支是 project/hookhub，所有实际工作都发生在 vigilant feistel 目录中。这正是 Git Worktree 的运作方式。它们允许在隔离的目录中进行开发，同时仍指向同一个仓库。
现在我们想要获取那里生成的代码并提交它。指示 Claude 创建一个提交，并在提交信息中明确说明更改是通过 Claude Code Desktop 生成的。
图 10.21 – 查看在 vigilant_fiestal worktree 中生成的动画功能更改
当该进程（vigilant fiestal）运行时，另一个本地 Claude 实例正在一个名为 zealous jemison 的独立 Worktree 中，使用 JSON 文件更新 GitHub URL。两个实例独立运行。Claude 准备暂存命令。
下面的屏幕截图显示 Claude Code 正在准备提交并提交审批。
图 10.22 – Claude Code 正在为动画功能更改准备提交
批准它。提交信息清楚地表明更改是使用 Claude Desktop 生成的。批准后，一个重要细节变得可见。活动分支不是 project/hookhub。而是 vigilant‑fiestel。
图 10.23 – 提交已应用到 vigilant-fiestel Git worktree 分支
这证实了 Worktree 的行为方式。当在 Worktree 内部创建提交时，它会应用到该 Worktree 的分支——而不是原始分支。提交成功添加到了 vigilant‑fiestel。
推送 Worktree 分支
现在我们推送更改。切换到 zealous jemison Worktree。该分支已经包含其提交。将其也推送上去。
Claude 将请求推送权限。下面的屏幕截图显示了 zealous‑jemison 的情况，它实现了数据库更新，将新的 Claude Code 仓库条目添加到 hooks.json 中。
图 10.24 – 将 zealous-jemison worktree 分支推送到远程仓库
vigilant‑fiestel 的情况如下：实现了着陆页 hero 区域的 UI 动画功能。
图 10.25 – 将 vigilant-fiestel worktree 分支推送到远程仓库
两个都批准。project/hookhub 分支仍然不显示新提交。这是预期的。每个 Worktree 维护自己的分支。
还有一个由远程 Claude Code 实例创建的第三个分支，称为 claude/anthropic‑hero‑design/<id>。
图 10.26 – 远程 Claude Code 代理完成 hero 区域重新设计
该分支中的所有更改已经提交并远程推送。
刷新仓库确认有三个新分支：
-
vigilant fiestel -
zealous jemison -
Anthropic Hero Design
下面的屏幕截图显示了仓库视图，其中可见这些新创建的分支。
图 10.27 – 显示新创建功能分支的 GitHub 仓库视图
每个分支代表一个独立开发的功能。
将所有内容合并到 project/hookhub
现在我们想将所有这些实现汇总到 project/hookhub 中。
我们不手动检出并合并每个分支，而是将任务委托给 Claude Code。
我们提供分支名称，并指示 Claude 将所有提交合并到 project/hookhub。
图 10.28 – 提示 Claude Code 将所有功能分支合并到 project/hookhub
Claude 开始在本地工作并创建另一个名为 suspicious‑bassi 的 Worktree。
它没有直接合并到 project/hookhub，而是创建了一个临时集成分支 project/hookhub‑merge。
图 10.29 – 创建临时 project/hookhub-merge 集成分支
这允许在接触主开发分支之前进行整合。
执行合并
Claude Code 开始合并过程。操作期间出现合并冲突。
图 10.30 – 分支整合期间检测到合并冲突
Claude 准备了一个解决方案：
-
解决来自
anthropic‑hero‑design的冲突。 -
合并
vigilant‑fiestel。 -
合并
zealous‑jemison。 -
将所有内容推送到
project/hookhub。 -
冲突涉及全局 CSS 文件。
-
Claude 提出编辑建议。我们批准它们。
-
创建合并提交。
-
Claude 继续：
git merge vigilant-fiestel -
然后运行以下命令：
git merge zealous-jemison
下面的屏幕截图显示 Claude Code 正在执行合并并提交合并提交以供审批。
图 10.31 – Claude Code 提交最终合并提交以供审批
此时，所有功能分支已整合到 project/hookhub‑merge 中。
推送到 project/hookhub 前进行测试
Claude 请求权限将合并结果推送到 project/hookhub。
暂时不要批准。推送前，先在本地测试。
图 10.32 – 推送到主分支前在本地测试合并后的项目
指示 Claude 启动开发服务器：
npm run dev
可能会出现错误：
npm is not found
Claude 通过 source .zshrc 配置文件来加载环境并再次尝试。
然后它确定缺少依赖并运行以下命令：
npm install
现在有两个进程正在运行：
-
npm install -
npm run dev
依赖安装完成后，开发服务器成功在端口 3002 上启动。合并后的实现现在正在本地运行。
验证集成结果
打开运行在端口 3002 上的应用程序，并将其与原始实现进行比较。
图 10.33 – 对比原始与增强后的 HookHub Hero 部分
差异立竿见影。新的 Hero 部分现在包含以下内容：
-
网格背景
-
横幅元素
-
曲折线条
-
仓库统计数据
-
动画效果
仓库列表包含的条目比以前更多。这些是由 Claude Code 调研并添加的。动画遍布整个网站，而不仅仅局限于孤立的组件。与原始的静态版本相比，体验感觉更具动态感。
所有三个独立开发的功能都能正确共存。
完成合并
验证完成后，我们批准推送。Claude 将 project/hookhub‑merge 合并到 project/hookhub 中。
图 10.34 – 将所有功能分支合并到 project/hookhub 后的最终提交历史
刷新仓库确认结果。该分支现在包含三次提交。每次提交合并一个不同的分支，这些分支源自由 Claude Code 创建的独立 Worktree。每个分支代表一个独立实现的功能。
这种设置凸显了开发扩展方式的一个重要转变。三个独立的功能由不同的 Claude Code 实例并行开发，同时运行。除了两个本地实例外，另一个 Claude Code 实例在远程运行。
看到这三条独立的开发线汇聚到一个分支中，其意义显而易见。我们通过委托并行功能实现，实际上实现了作为开发者的自我扩展。
同样值得注意的是，此过程中涉及的前端经验有限。为这些实现提供支持的 Claude Code 模型处理了前端工作，并证明了其能够生成所需代码。
通过移动端在云端运行 Claude Code
Claude Code 现已集成到移动应用程序中。桌面端使用的相同工作流可直接从手机发起。在此例中，从移动界面选择 claude‑code‑crash‑course 仓库，会话由此开始。
由于移动环境不在本地执行代码，所有操作均在 Anthropic 云端运行。不依赖本地机器。仓库在远程克隆，分支在远程检出，更改在远程提交。
我们首先指示 Claude 切换到 project/hookhub 分支并实现一个 Anthropic 风格的页脚。
图 10.35 – 从移动应用程序界面运行 Claude Code
工作流与桌面体验一致：Claude 克隆仓库，检出目标分支，检查项目结构，实现功能，提交更改，并准备拉取请求。
过程逐步展开。仓库被获取。分支被切换。文件被检查。系统指令确认分支已切换至 project/hookhub。
图 10.36 – 从移动会话中 Claude Code 分析仓库
理解项目上下文后，Claude 识别出该仓库是一个具有 Anthropic 风格品牌的 Next.js 应用程序，并据此进行操作。
值得注意的是，默认云配置不包含 MCP、自定义钩子或输出样式。环境使用默认设置运行。自定义配置可单独添加，但此会话在无此类配置下运行。
实现页脚组件
Claude 在 components 目录下生成一个新的 footer.tsx 文件。
图 10.37 – 从移动端 Claude Code 会话创建并集成页脚组件
页脚组件体现了 Anthropic 视觉风格。创建组件后，Claude 通过导入并将其渲染在主页面中，将其集成到 page.tsx 中。
版本控制操作随之自动进行。更改被暂存并提交。由于请求指定将更改推送到 project/hookhub，且 Claude Code 内部使用 Git worktree，因此会在后台发生额外的 Git 操作，以将 worktree 提交合并到正确的分支。
Git 日志确认了早期工作的先前合并和提交。新的页脚组件和页面修改现已成为分支历史的一部分。
审查拉取请求
在 GitHub 上打开仓库可看到新创建的拉取请求。最初，拉取请求针对 main 分支，这并非预期的基础分支。基础分支被更正为 project/hookhub。
调整分支后，拉取请求反映了两个修改过的文件：
-
page.tsx -
footer.tsx
差异显示了符合预期的页脚组件集成。
在此阶段，Claude 也可直接在 GitHub 上被 @ 提及以审查拉取请求。由于该分支未配置 GitHub 工作流，自动检查不会触发。
图 10.38 – 在 GitHub 上审查由 Claude Code 创建的拉取请求
审查仍为手动进行。
本地验证更改
为验证集成，请运行以下命令：
git fetch
git pull
npm run dev
启动开发服务器后，应用程序加载并在页面上渲染新的页脚。品牌标语 Built with love for Claude Code powered by Anthropic 出现在底部。
布局需要微调，可委托给 Claude Code 进一步优化。重要的是，整个工作流——从克隆到创建拉取请求——均从移动设备发起，并在云端完全执行。
工程模型保持一致：指定意图，允许 Claude 推理仓库，审查输出，并迭代。界面变了，但底层开发流程未变。
并行 Agent 适得其反的情况
并行编码 Agent 很有用，但并非总是正确的选择。以下是并行运行 Agent 往往事与愿违的情况。
-
紧密耦合的功能：当任务修改相同文件或相互依赖彼此输出时，并行 Agent 会产生合并冲突或无声地覆盖彼此的工作。如果功能 B 需要功能 A 的接口先存在，请按顺序运行它们。
-
共享状态和排序约束：数据库迁移、配置文件更改和共享类型定义会产生隐式依赖。两个 Agent 向同一配置、模式或路由文件添加条目会发生冲突。解决这些冲突的成本往往超过并行运行节省的时间。
-
微小任务：每个 Agent 会话都带来开销：启动上下文、阅读代码库和规划工作。对于顺序执行只需两分钟的任务，将其拆分到多个 Agent 然后审查和合并结果反而可能耗时更长。如果任务舒适地适合单个会话，请保持原样。
-
高昂的协调成本：如果你发现自己编写详细、明确的规范只是为了防止 Agent 互相干扰，这是一个信号。你花在定义边界上的时间越多，从并行性中获得的收益就越少。
-
探索性或不确定性工作：当你尚未知道正确的方法时，例如调试棘手的问题或为不明确的设计制作原型，并行代理只会增加不确定性。一次专注的迭代会话比多个代理同时探索死胡同更有效。
专业提示：
心智模型：当任务独立、定义明确且涉及代码库的不同部分时，并行代理效果最佳。拿不准时，先按顺序执行，确认任务间无交互后再并行化。
并行开发检查清单：
-
确保每个任务操作独立的文件/组件
-
验证每个代理提示词中的起始分支是否正确
-
推送到目标分支前测试合并结果
-
合并后清理工作树目录
总结
在本章中，你学习了如何在桌面应用程序中使用 Claude Code，在 Local worktree 和云模式之间切换，并行运行多个编码代理。你了解了 Git 工作树如何隔离功能开发，后台代理如何在云端运行，以及如何将独立开发的分支合并、测试并整合到单一的工作代码库中。你还探索了相同的工作流如何延伸到移动端，在那里所有执行都发生在云端。
这些信息很有用，因为它演示了如何从顺序开发转向编排的、多代理工作流。通过理解如何管理并行分支、协调本地和远程代理以及安全地合并它们的输出，你可以在保持对代码库控制的同时，显著提高开发吞吐量。
在下一章中，我们将探讨深度代理及其在长时程任务执行中的作用。我们将定义深度代理的特征并分析 LangChain 深度代理框架，包括其架构和执行模型。
获取本书的 PDF 副本、代码包等
扫描二维码（或访问 packtpub.com/unlock）。按名称搜索本书，确认版本，然后按照页面上的步骤操作。
注意：请准备好发票。直接从 Packt 网站购买的不需要发票。
# 11 理解深度代理在本章中，我们将深入探讨深度代理。深度代理是具有能力、实用性，并被设计用于执行各种任务的代理，特指那些需要跨多个步骤进行持续推理和行动的长时程任务。像 Claude Code、Cursor CLI 和 LangChain Deep Agents 这样的编码代理就属于这一类。这些系统不局限于单步工具使用；它们在扩展的工作流中运行，做出决策、调整计划，并迭代行动，直到达成更广泛的目标。
我们首先对深度代理进行分类，确定什么样的代理符合“深度”资格，并识别出将它们与简单代理模式区分开来的决定性特征。由此，我们在高层定义什么使代理成为深度代理，并考察那些支持长时程执行的属性。
这为像 Claude Code 这样的最先进编码代理是如何实现的提供了一个实用的视角，将我们的理解建立在真实工程基础之上。
本章将涵盖以下主题：
-
生产系统中的代理分类
-
什么使代理成为深度代理
11 生产系统中的代理分类
在讨论深度代理之前，我们首先需要建立一个分类体系，并阐明目前整个行业在生产环境中使用哪些类型的代理。我将对此进行简化，并描述我对这一格局的看法。
图 11.1 – 显示深度代理中编码代理的代理分类图
在最广泛的层面上，我们有代理领域。该领域包括当前真实系统中部署的所有类型代理。这些可以是完全自主代理或代理式应用。一个常见的例子是混合 RAG 架构，其中 LLM 决定下一步执行哪个步骤。
图 11.2 – 由 LLM 编排的混合 RAG 工作流
模型可能决定是否执行搜索、是否在检索前重述查询，或是否执行其他操作。LLM 实际上是在预定义工作流中编排下一个动作。
图 11.3 – 将 LLM 与外部工具连接的 ReAct 循环
在此范畴下，我们找到了 ReAct（推理与行动）代理。在 ReAct 代理中，LLM 决定是否使用工具。如果选择了工具，系统执行它并将结果作为观察返回。然后 LLM 决定是否有足够的信息返回最终响应。如果没有，它将继续循环：选择另一个工具，接收另一个观察，并迭代直到得出答案。
这个 ReAct 循环开启了更广泛的代理范式。大多数现代代理架构都可以追溯到这种算法结构。该方法在论文“ReAct: Synergizing Reasoning and Acting in Language Models”中被提出。
浅层代理及其局限性
在本分类中，我将 ReAct 代理归类为浅层代理。原因不是它缺乏实用性，而是它缺乏深入的能力。考虑一项需要彻底和扩展研究的任务。即使代理拥有搜索工具、维基工具或 Tavily 工具，它也不太可能执行足够深入的研究。这种局限性既源于架构设计，也源于现代 LLM 的现实。
该代理依赖函数调用。在每个决策点，LLM 进行函数调用以选择要执行的工具。函数调用本身没有错，尽管它有权衡。然而，核心局限在于上下文窗口。
此循环的每次迭代都会向上下文添加更多信息。LLM 决定，执行工具，结果被注入回提示词，循环重复。一两次迭代还能控制。随着迭代次数增加，上下文变得越来越大。
这种增长导致上下文腐烂。我们开始看到上下文混淆、上下文矛盾和上下文污染。随着时间的推移，性能下降，代理可能跑偏。
图 11.4 – 迭代工具调用工作流中的上下文累积
当处理复杂、长时间运行的任务时，这种局限性变得至关重要，例如实现一个功能、对一个主题进行深度研究，或执行一个需要持续推理和信息收集的多阶段工作流。这些从根本上不同于简单的请求，如预订航班。
除了质量下降，成本也会增加。每次 LLM 调用变得更重，因为它包含更多 Token。更多 Token 增加了延迟和费用。虽然 ReAct 架构是基础且强大的，但它不太适合复杂的长时程任务。
也就是说，浅层代理对于仅需几次迭代的任务非常有效。许多生产系统成功使用此架构。在许多现实用例中，此模式已足够，不需要额外的复杂性。
深度代理
回到分类体系，我们现在从浅层代理转向深度代理。
深度代理
深度代理旨在执行长周期任务。这些任务复杂，需要多次迭代，并涉及大量推理和处理。深度代理是长期运行的系统。它们可能运行数分钟、数小时，甚至数天。它们可以暂停执行、请求用户输入，并在收到输入后恢复。
深度研究代理
深度研究代理是常见的例子。像 Perplexity 这样的系统暴露了触发深度代理运行的深度研究功能。许多供应商现在提供类似的研究能力。Claude Code 包含研究选项。ChatGPT 包含研究选项。这些中的每一个都会触发深度代理实现，尽管内部设计因供应商而异。
也有开源的深度研究代理。GPT Researcher (github.com/assafelovic/gpt-researcher) 是该类别中最受欢迎的开源项目之一。我为它创建了一门课程。您可以在此找到：www.udemy.com/course/langchain/?srsltid=AfmBOopb6uyyf5oNvX1gvDus-Nqdln5B-bwZtJAW1NLsv7z7ggPJLX9A。
编码代理作为深度代理
深度代理的另一个主要子集是编码代理。例子包括 Claude Code、Devin、Cursor 和 Gemini CLI。编码代理是深度代理如何在行业中有效且被广泛采用的最有力演示之一。数百万开发者在使用它们。
正如您所见，对于本书，我主要关注 Claude Code，在撰写本书时，它是最流行的编码代理之一。Claude Code 能力极强，可以处理各种需要深度和规模的长期运行任务。
我们可以要求此类代理实现一个应用程序或功能。它不仅仅生成代码。它可以运行测试、执行应用程序、打开浏览器、截屏，并执行软件工程师手动执行的许多相同步骤。
因此，编码代理是深度代理的一个专业化子集，专门针对软件开发工作流进行定制。
应用层的创新
深度代理目前推动了该领域的大部分创新。LLM 仍在改进，但这些改进是渐进的。推理质量提高。能力扩展。然而，进步是增量式的，而非指数级的。
与此同时，建立在 LLM 之上的应用层正在快速推进。通过在代理之上分层抽象并在系统内组合代理，我们可以构建高度强大的机器，以自动化复杂的人类推理任务。这个应用层通常被称为代理工具箱。
代理工具箱是一个用于构建 AI 代理的即用型环境。它位于运行代理的工具和系统之上，并预配置了您所需的一切：默认提示词、工具处理、规划、文件访问等。框架为您提供原始构建块。运行时管理执行。工具箱完成繁重的工作，以便您无需从头设置一切即可开始构建。
五年前，AI 系统能够在没有人工干预的情况下从头创建一个功能完善且视觉精美的应用程序这一想法似乎不切实际。如今，这种能力已成为现实。
关键驱动力不仅是基础模型的改进，还在于我们作为开发者如何驾驭它们（工具箱工程）。创新正发生在应用层，在于我们如何实现和编排深度代理。
是什么让代理变得“深度”？
深度代理没有严格的正式定义。在实践中，我认为如果代理能够以质量和可靠性执行复杂的长期运行任务，则它是深度的。
要实现这一点，深度代理需要解决上下文膨胀和累积问题的能力。核心挑战变成了上下文工程和智能上下文管理。没有它，长周期执行就会崩溃。
大多数深度代理实现了几个常见的想法：
-
规划工具：代理在执行步骤前规划它将要做什么。
-
子代理能力：系统生成在隔离上下文中运行的专业工作者。这允许并发执行，而不会使单个共享上下文膨胀。
-
用于中间状态的文件系统：中间结果和共享状态被写入磁盘，而不是完全保留在 LLM 上下文中。这防止了不受控制的上下文增长。
-
大型系统提示词：深度代理通常依赖于一个综合性的系统提示词，该提示词编码了指令、约束和操作指导。
如果我们检查现代深度代理实现，通常会以某种形式看到这四个想法。在下一节中，我们将深入探讨这些组件中的每一个并检查具体实现。
图 11.5 – 深度代理架构的核心组件。改编自：LangChain 博客，深度代理，https://blog.langchain.com/deep-agents/
深度代理中的规划工具
虽然“深度代理”是一个通用术语，但 LangChain 团队在分析多个深度代理实现后对其进行了清晰的阐述。每个深度代理都包含一个规划工具。
当我们运行该工具时，我们会看到一个任务列表：一些已经完成，一个可能正在进行中，其他的排队等待执行。我们观察到的不是通过模型内部的思维链推理进行的隐式规划。相反，深度代理依赖显式规划工具。
这种规划机制通常以 Markdown 格式的待办事项列表形式实现。在执行步骤之间，代理主动审查并更新此计划。该计划是动态的。任务被标记为待处理、进行中或已完成。如果任务失败，代理不会像原始 ReAct 代理循环那样盲目重试。相反，规划工具以更受控的方式帮助引导执行。
该计划持续更新，用户可以影响任务列表。在 Claude Code 中，规划工具本身是内部的，其实现无法直接访问。在实践中，会调用 TodoWrite 和 TodoRead 动作。TodoWrite 工具创建和更新待办事项列表，接受 {todos: Todo[]} 参数。TodoRead 工具读取当前列表。此调用更新待办事项列表，反映执行计划的变化。即使内部推理不直接可见，TodoWrite 和 TodoRead 等动作也能让我们洞察代理在处理任务时如何动态调整其计划。
深度代理持续更新此待办事项列表，这提高了可靠性并增加了成功完成复杂任务的可能性。从概念上讲，这是直观的。在处理复杂工作时，我们将其分解为较小的任务并随时间跟踪进度。规划工具将这一相同模式形式化到了代理架构内部。
子代理和分层委托
我们讨论了规划工具，或待办事项列表工具。深度代理的另一个决定性特征是子代理能力。
深度代理利用子代理实现分层委托。主代理可以生成其自身的新实例，但这些实例是针对专注任务进行专业化的。每个子代理都有自己的系统提示词、自己的描述和自己的工具集，如下图所示：
图 11.6 – 使用子代理进行分层委托
这种设计反映了现实生活中委派的工作方式
在委派任务时，仅仅分配工作是不够的。受委派方必须具备正确的技能和正确的工具。清晰地沟通需要做什么也是必要的。
考虑一个实际例子
假设有一项任务需要特定的工艺技能，例如修复房屋的结构问题。如果缺乏所需的专业知识，该任务必须委派给拥有适当技能和工具的人。此人自带设备，独立执行工作，并交付最终结果。中间步骤的细节对于原始请求者来说保持隔离。重要的是最终结果。
这是子代理的一个有用类比
主代理通过提供清晰的描述来委派任务。子代理使用自己的工具和内部指令运行，独立执行工作，并返回结果。在执行过程中，子代理在隔离环境中工作。主代理看不到每一个中间推理步骤。它只接收最终输出。
从系统视角来看
这意味着子代理在它们自己的上下文窗口中运行。它们不会污染主代理的上下文。每个子代理可以拥有不同的系统提示词和一组针对其专业化定制的不同工具。这通过将聚焦的职责分配给专业化代理，实现了扩展并提高了质量。
内部机制
子代理执行它们自己的工具调用循环，包括它们自己的 ReAct 风格循环。完成后，它们仅返回最终响应，而不是完整的中间观察链。这种委派模式实现了上下文隔离，防止专业化工作膨胀主代理的上下文，并允许任务并行执行。因此，效率和深度都得到了提升。
实践中
我们可以在 Claude Code 等系统中观察到这种模式。请看以下示例：
图 11.7 – Claude Code 生成子代理以探索认证模式
在此示例中，Claude Code 生成一个探索代理来搜索认证模式。该探索代理并发运行，执行自己的搜索，并在主代理继续执行的同时独立运行。这展示了对子代理和层级委派的内置支持。
到目前为止，讨论侧重于概念和架构推理，而非实现细节。此处的目标是使概念结构清晰，并将这些能力与日常工作流中使用的工具联系起来。
这直接建立在 第 7 章 讨论的基础上，在该章中，我们探讨了子代理如何防止上下文膨胀、强制上下文隔离，并最终带来更好的结果。
Deep Agents 中的文件系统访问
Deep Agents 的另一个关键特征是对文件系统的访问。Deep Agents 配备了搜索文件、读取文件、更新文件、删除文件的工具，并总体上保持对文件系统的完全控制。这种能力在管理长时程任务的上下文中起着核心作用。
在 Claude Code 中
这通过一组文件操作工具体现出来。
图 11.8 – 可供代理使用的 Claude Code 文件操作工具
正如你所见，有一个用于读取文件内容的 Read 工具，一个用于创建或覆盖文件的 Write 工具，以及一个用于执行精确字符串替换的 Edit 工具。此外，Claude Code 还提供 Glob 和 Grep 工具来搜索文件和在文件内搜索。
如果我们查阅 LangChain 的 Deep Agents 文档，会看到一个类似的文件系统接口：ls、read_file、write_file、edit_file、glob 和 grep。Deep Agents 暴露的是一个接口而非特定实现。这意味着底层存储可以各不相同。例如，文件系统可以由 Google Cloud 上的 Firestore 或 AWS 上的 DynamoDB 提供支持。接口保持不变，而实现是灵活的。
为什么文件系统对长时程任务很重要
正如之前讨论的，随着对话的增长，上下文窗口也随之增长。这会导致一系列问题，最终导致上下文腐烂。上下文腐烂会产生来自 LLM 的降级响应。这种降级可能源于上下文矛盾、上下文混淆或提示词中的过度噪音。
在 LangChain 的一篇博客文章中，有一个说明捕捉了代理上下文工程的核心挑战。此处所示的图表受该解释启发。
图 11.9 – 可用上下文 vs. 选定上下文 vs. 所需信息。来源：LangChain Blog，代理如何利用文件系统进行上下文工程，https://blog.langchain.com/how-agents-can-use-filesystems-for-context-engineering/
想象一个巨大的蓝色矩形（框 1），代表所有可用上下文：代码库、文档、网络搜索结果、文件和数据库。这个空间可能很大且混乱。
在此范围内，框 2 代表代理为给定步骤选择并拉入上下文窗口的信息子集。这是代理选择阅读或搜索的内容。最后，框 3 代表代理完成任务实际需要的信息。
每当红圈不能与绿圈正确对齐时，会出现几种失效模式：
-
检索不足：代理仅检索了框 2 的一部分，遗漏了必要信息。
-
过度检索：
框 2变得太大，引入了过多噪音并稀释了信号。 -
检索错位：代理在错误的地方搜索，
框 1与框 2完全没有重叠。 -
上下文窗口限制：紫色框是有限的。它无法容纳所有内容，如果变得太大，性能会下降。
上下文工程的目标是使红圈尽可能小，同时完全覆盖绿圈。这种选择过程几乎可以在代理的每次迭代中发生。每一步都需要优化在上下文窗口中包含什么内容。
因此，信息如何被结构化、检索和优先排序，往往比提示词本身更重要。代理的质量取决于正确的信息是否存在于上下文窗口中。即使拥有强大的推理模型，不正确或不完整的上下文也可能导致错误结果或无法完成任务。
文件系统作为上下文引擎
这就是深度代理的文件系统变得至关重要的地方。文件系统充当引擎，使代理能够触达正确的上下文。概念上，整个文件系统对应于可用信息的蓝色矩形：
-
首先，文件系统允许代理将上下文写入持久化存储。临时结果、中间输出或检索到的信息可以写入文件。这些工件被存储在外部，而不是膨胀上下文窗口。
-
其次，文件系统提供了选择相关上下文的机制。诸如
glob之类的工具允许代理按模式查找文件，grep允许其使用正则表达式搜索文件内容。这些工具使代理能够精确检索下一步所需的内容。
通过这种方式，文件系统实现了语境工程的两大核心原则（第 1 章）：将语境写入持久化存储，以及选择性地检索相关语境。它是实现这两大功能的机制，也是 Deep Agent 能够管理长时任务且不会遭受语境膨胀之苦的基础。
系统提示词
在 AI 工程领域，“系统提示词很重要”这一说法已略显陈词滥调。然而，观察行业领军者的实际做法会发现，这一组件究竟有多关键。我们看到的系统提示词动辄数百行，并大量注入了庞大的工具描述。
公司投入巨大的工程资源，随着 LLM 的演进，迭代地策划、优化和更新这些提示词。对于 Deep Agent 而言，系统提示词是其推理、身份与边界的基础架构。
一份高效的系统提示词利用了最先进 LLM 天生擅长的能力：模式识别，以及将通用规则应用于特定新情境。一份精心设计的系统提示词能够实现以下目标：
-
确立清晰的身份与范围：通过明确定义 Agent 是什么（例如“处理基础订单的客服”）和不是什么（例如“非销售或市场职能”），提示词能立即确立运作边界。
-
赋能而非约束：优秀的提示词不会在何时使用何种工具上做死板规定，而是确立最终目标（例如“高效解决问题”），并授权 Agent 自主选择合适的工具。
-
提供推理框架，而非流程图：提示词不提供僵化的“如果/那么”分支逻辑，而是给出可复用的框架（例如：1. 识别核心问题，2. 收集语境，3. 提供解决方案，4. 确认满意度）。这教会模型如何应对问题，使其即便面对全新情境也能成功。
-
利用启发式边界：它依赖压缩后的原则而非详尽的清单。例如，指示模型“始终选择最简单的解决方案”充当贪心算法启发式，在不浪费 Token 空间的前提下，指导模型跨越数千个潜在边缘场景。
-
保持语言效率：优秀的提示词不浪费词汇。它避免重复和指令重叠，以免混淆 LLM 或导致行为矛盾。
以下是 LangChain Deep Agents 内置的系统提示词。该提示词可在官方仓库（github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/base_prompt.md）中找到，遵循 MIT 许可证。
You are a Deep Agent, an AI assistant that helps users accomplish tasks using tools. You respond with text and tool calls. The user can see your responses and tool outputs in real time.
## Core Behavior
- Be concise and direct. Don't over-explain unless asked.
- NEVER add unnecessary preamble ("Sure!", "Great question!", "I'll now...").
- Don't say "I'll now do X" — just do it.
- If the request is ambiguous, ask questions before acting.
- If asked how to approach something, explain first, then act.
## Professional Objectivity
- Prioritize accuracy over validating the user's beliefs
- Disagree respectfully when the user is incorrect
- Avoid unnecessary superlatives, praise, or emotional validation
## Following Conventions
- Read files before editing — understand existing content before making changes
- Mimic existing style, naming conventions, and patterns
## Doing Tasks
When the user asks you to do something:
1. **Understand first** — read relevant files, check existing patterns. Quick but thorough — gather enough evidence to start, then iterate.
2. **Act** — implement the solution. Work quickly but accurately.
3. **Verify** — check your work against what was asked, not against your own output. Your first attempt is rarely correct — iterate.
Keep working until the task is fully complete. Don't stop partway and explain what you would do — just do it. Only yield back to the user when the task is done or you're genuinely blocked.
**When things go wrong:**
- If something fails repeatedly, stop and analyze *why* — don't keep retrying the same approach.
- If you're blocked, tell the user what's wrong and ask for guidance.
## Tool Usage
- Use specialized tools over shell equivalents when available (e.g., `read_file` over `cat`, `edit_file` over `sed`)
- When performing multiple independent operations, make all tool calls in a single response — don't make sequential calls when parallel is possible.
## File Reading Best Practices
When reading multiple files or exploring large files, use pagination to prevent context overflow.
- Start with `read_file(path, limit=100)` to scan structure
- Read targeted sections with offset/limit
- Only read full files when necessary for editing
## Progress Updates
For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next.
由此可见，系统提示词是认知基线。过度依赖具体的硬编码会破坏模型的推理能力，而依赖模糊的指令则会导致混乱的不一致性。
总结
在本章中，我们建立了生产环境中 Agent 的实用分类法，识别了浅层 Agent 面对语境膨胀和长周期工作流时的局限性，并定义了什么是“深度” Agent。随后，我们分析了支撑深度执行的核心构建模块：通过动态待办列表进行显式规划、通过在隔离语境中运行的专用子 Agent 进行层级委派，以及将文件系统访问作为持久化状态和精准语境选择的机制。通过将这些组件与 Claude Code 和 LangChain DeepAgents 等真实系统相关联，我们将讨论落实到了具体实现上。
获取本书的 PDF 副本、代码包及更多内容
扫描二维码（或访问 packtpub.com/unlock）。按名称搜索本书，确认版本，然后按照页面上的步骤操作。
# 12 解锁您的专属权益注意：请准备好发票。直接从 Packt 网站购买的书籍无需发票。
您的这本书包含以下专属权益：
请按照下方指南解锁。该过程仅需几分钟，且仅需完成一次。
3 步轻松解锁本书的免费权益
步骤 1
准备好购买发票以供步骤 3使用。如果您有实体书，请用手机扫描并保存为 PDF、JPG 或 PNG 格式。
关于查找发票的更多帮助，请访问 www.packtpub.com/en-us/unlock?step=1。
注意：如果您直接从 Packt 购买本书，则无需发票。完成步骤 2后，即可立即访问专属内容。
步骤 2
扫描二维码或访问 packtpub.com/unlock。
在打开的页面（桌面端类似于图 12.1）中，按名称搜索本书并选择正确的版本。
Figure 12.1: Packt unlock landing page on desktop
步骤 3
选择书籍后，登录您的 Packt 账号或免费创建一个。然后上传发票（PDF、PNG 或 JPG，最大 10 MB）。按照屏幕上的说明完成流程。
需要帮助
如果您遇到困难并需要帮助，请访问 www.packtpub.com/unlock-benefits/help 查看详细的常见问题解答，了解如何查找您的发票等更多信息。此二维码将带您前往帮助页面。
如果您仍然面临问题，请联系 customercare@packt.com。
PacktLogo
订阅我们的在线数字图书馆，即可完全访问超过 7,000 本书籍和视频，以及帮助您规划个人发展和提升职业生涯的行业领先工具。欲了解更多信息，请访问我们的网站。
为什么要订阅？
-
通过来自 4,000 多位行业专业人士的实用电子书和视频，减少学习时间，将更多时间用于编码
-
通过专为您打造的技能计划改善学习效果
-
每月免费获赠一本电子书或视频
-
全文可搜索，轻松获取关键信息
-
复制粘贴、打印和书签内容
在 www.packtpub.com，您还可以阅读免费技术文章合集，注册各类免费通讯，并获取 Packt 图书和电子书的独家折扣和优惠。
您可能喜欢的其他书籍
如果您喜欢这本书，可能也会对 Packt 的以下书籍感兴趣：
https://www.packtpub.com/en-us/product/learn-model-context-protocol-with-typescript-9781806661398
使用 TypeScript 学习模型上下文协议
Christoffer Noring
ISBN：9781806661398
-
理解 MCP 协议及其核心组件
-
构建向多种客户端暴露工具和资源的 MCP 服务器
-
使用交互式检查器工具测试和调试服务器
-
使用 Claude for desktop 和 Visual Studio Code 代理使用服务器
-
保护 MCP 应用，以及管理和缓解常见威胁
-
使用基于云的策略构建和部署 MCP 应用
https://www.packtpub.com/en-nz/product/learn-model-context-protocol-with-python-9781806103232
使用 Python 学习模型上下文协议
Christoffer Noring
ISBN：9781806103232
-
理解 MCP 协议及其核心组件
-
构建向多种客户端暴露工具和资源的 MCP 服务器
-
使用交互式检查器工具测试和调试服务器
-
使用 Claude Desktop 和 Visual Studio Code Agents 使用服务器
-
保护 MCP 应用，以及管理和缓解常见威胁
-
使用基于云的策略构建和部署 MCP 应用
Packt 正在寻找像您这样的作者
如果您有兴趣成为 Packt 的作者，请访问 authors.packtpub.com 并立即申请。我们已与数千名像您一样的开发人员和技术专业人士合作，帮助他们与全球技术社区分享见解。您可以提交一般申请，申请我们正在招募作者的特定热门主题，或提交您自己的想法。
分享您的想法
现在您已读完 Agentic Coding with Claude Code，我们非常乐意听取您的想法！扫描下方二维码，直接前往该书的亚马逊评论页面分享您的反馈，或在您购买该书的网站上留下评论。
您的评论对我们和技术社区都很重要，将帮助我们确保交付优质内容。
## 索引A
AI 编码，未来代理式编码 247 – 249 命名和基于角色的上下文 249 专业代理团队 247
AI 实现，使用 SPEC37, 38 运行 38 – 40
代理框架321
Anthropic API 密钥 注意事项 46, 47 使用 45
高级项目级输出样式
创建 228 自定义 HTML 输出样式 228, 229 文件生成，自动化 231, 232 HTML 输出样式，使用 230, 231 多种输出样式 232 专业输出样式工作流 235
高级状态栏
最后用户提示词检索，实现 244 – 246 最后用户提示词，显示 241, 242 状态栏需求 242, 243 会话记录路径，访问 243
代理技能
自定义技能，使用 264 探索 259 安装，在 Claude Code 中 257 概览 254 项目级自定义技能，创建 263, 264 运行，在隔离的子代理上下文中 272 脚本，审查 262, 263 样式设置，使用技能 256 样式设置，启用技能后 258 样式设置，不使用技能 255 对比 MCP 服务器 272, 273 对比子代理 273
代理分类，生产系统 317 – 319
深度代理 320 浅层代理 319, 320
自动生成的提交信息
使用内容工程改进 76
辅助脚本 263
B
后台代理278
C
CLAUDE.md 变更，检查 151 提交 150 审查 150
Claude Code7 上下文工程策略 7
Claude Code GitHub 集成 140
Claude GitHub 应用 安装 142 GitHub 工作流 安装 142 先决条件安装 141 拉取请求，创建 143 – 146
Claude Code 连接，到 MCP 服务器 96
Claude Code，重启 99
Context7，通过 CLI 添加 97 范围和配置 98
Claude Code 桌面云模式 280, 281 Git Worktrees 支持 281, 282 安装 278, 279 集成 277 本地工作树模式 279 操作模式 278, 279
Claude Code 云端使用，通过移动端 变更，本地验证 314 页脚组件，实现 311, 312 拉取请求，审查 312, 313 运行 308, 311
Claude Code 子代理 168 功能 168, 172 文件结构 172, 173 参考链接 168 关系，对 React 代理 173, 174
Claude Haiku49
Claude Opus49
Claude Skills 市场 探索 260, 261 固定工作流 261, 262
Claude Sonnet49
Claude 订阅48 模型 49 计划和定价 49
CodeMode121, 122 沙箱中执行 125 集成 123, 124 关键观察 122, 123 MCP 到 TypeScript 转换 124 调用 MCP123 MCP 的作用 123
浙公网安备 33010602011771号