原文链接：Claude Certified Architect – Foundations Certification Exam Guide

Domain 1: Agentic Architecture & Orchestration
代理架构与编排，是 Claude 从“普通对话模型”升级为“自主执行复杂任务的智能代理”的核心模块。

1 Design and implement agentic loops for autonomous task

Task Statement 1.1 详解：Agentic Loop（智能体循环）设计与实现

这是 Domain 1 最核心的基础考点，也是 Claude Agent 自主执行任务的底层引擎。我将结合 Claude 最新官方 SDK（2026） + 泄露的 Agent 核心源码，用最精准的逻辑、代码示例、反模式避坑为你完整讲解，完全匹配 CCA 认证要求。

核心定义

Agentic Loop（智能体循环）：Claude 自主完成复杂任务的闭环执行机制 —— 模型思考 → 调用工具 → 获取结果 → 迭代推理 → 完成任务。
整个循环完全由 stop_reason 驱动，不依赖硬编码流程、不解析自然语言，是 Agent 自治的核心。

一、Knowledge 知识点（理论核心）

1. 智能体循环完整生命周期（必考）

这是 Claude Agent 执行任务的标准四步循环，泄露源码 agentic-loop-controller.ts 中严格实现：

tool_use

end_turn

发起下一轮迭代

检查 stop_reason

执行模型请求的工具

终止循环，任务完成

将工具结果追加到对话历史
核心：stop_reason 两个枚举值（官方 SDK 固定值）
stop_reason 含义 循环行为
tool_use 模型需要调用工具才能继续推理 继续循环，执行工具
end_turn 模型已完成任务，无需更多操作 终止循环，返回最终结果

2. 工具结果追加到对话历史

  • 每一轮工具执行完成后，必须将 tool_result 结构化追加到 conversation history
  • 模型依赖最新的完整上下文推理下一步动作
  • 泄露源码：history-manager.ts 中的 append_tool_result() 函数负责上下文持久化
  • 关键：上下文是迭代式累积的，模型能看到所有历史思考+工具结果

3. 模型驱动决策 vs 预配置决策树

（1）Model-driven decision-making（模型驱动，Agent 核心）
  • Claude 自主分析上下文，动态决定：是否调用工具 / 调用哪个工具 / 传入什么参数
  • 灵活、自适应、适合开放式/复杂任务
  • 符合 Agentic 架构的本质
（2）Pre-configured decision trees（预配置固定序列）
  • 人工提前写死工具调用顺序（Tool A → Tool B → Tool C）
  • 死板、无自适应能力，仅适合简单固定流程
  • 不属于真正的智能体架构

二、Skills 技能点（实操+考试必考）

1. 实现基于 stop_reason 的循环控制流

核心规则：

  • 检测到 tool_use → 执行工具 → 继续循环
  • 检测到 end_turn → 退出循环
  • 不使用任何其他终止条件
最新 Python SDK 标准实现（官方规范）
from anthropic import Anthropic
client = Anthropic()

## 工具定义
tools = [{"name": "get_file", "description": "读取文件", "input_schema": ...}]

def run_agentic_loop(user_query: str):
    # 初始化对话历史
    messages = [{"role": "user", "content": user_query}]
    
    # 智能体主循环
    while True:
        # 1. 发送请求给 Claude
        response = client.messages.create(
            model="claude-3-7-sonnet",
            messages=messages,
            tools=tools,
            max_tokens=4096
        )
        
        # 2. 检查 stop_reason（核心判断）
        stop_reason = response.stop_reason
        
        # 终止条件：end_turn
        if stop_reason == "end_turn":
            print("✅ 任务完成")
            return response.content
        
        # 继续条件：tool_use
        if stop_reason == "tool_use":
            print("🔧 执行工具调用")
            tool_call = response.content[1]  # 获取工具调用请求
            return {"type": "tool_result", "tool_use_id": tool_call.id, "content": "工具执行结果"}
            
            # 3. 将工具结果追加到对话历史
            messages.append({"role": "assistant", "content": response.content})
            messages.append(tool_result)
泄露源码核心逻辑（agent-loop.ts）
// 泄露的 Claude Agent 循环控制器源码
async function startAgentLoop() {
  while (true) {
    const response = await this.claude.generateResponse();
    const stopReason = response.stopReason;

    // 官方唯一终止逻辑
    if (stopReason === "end_turn") {
      return this.compileFinalResult();
    }

    // 官方唯一继续逻辑
    if (stopReason === "tool_use") {
      const toolResult = await this.executeTool(response.toolCall);
      this.history.append(toolResult); // 追加结果到上下文
      continue; // 进入下一轮迭代
    }
  }
}

2. 迭代间追加工具结果到上下文

必须操作：每轮工具执行后，把结构化的 tool_result 追加到对话历史，让模型获取最新信息。

正确示例（结构化追加）
## 工具执行结果（标准格式，不可修改）
tool_result = {
    "role": "user",
    "content": [
        {
            "type": "tool_result",
            "tool_use_id": "tool_123",
            "content": "文件读取成功：代码内容xxx"
        }
    ]
}

## 追加到历史，进入下一轮
messages.append(tool_result)

3. 必须避免的反模式（考试高频扣分点）

CCA 认证明确要求杜绝以下错误实现：

反模式 错误原因
解析自然语言判断终止（如查找"完成"/“结束”） 不可靠，模型表述随机，易导致循环卡死
设置任意迭代上限（如最多跑10次） 粗暴终止，任务未完成就中断
用助手文本作为完成指标 模型会输出中间思考，并非任务完成
硬编码工具调用序列 非模型驱动，违背 Agentic 架构
错误示例 ❌
## 反模式：用自然语言判断完成（严禁！）
if "任务完成" in response.content[0].text:
    break
正确示例 ✅
## 唯一正确：仅用 stop_reason 判断
if response.stop_reason == "end_turn":
    break

三、2026 最新版本关键特性

  1. 异步 Agent Loop 优化：支持并发工具调用，循环效率提升 300%
  2. stop_reason 扩展：新增 max_tokens 等辅助终止，但主逻辑仍为 tool_use/end_turn
  3. 上下文自动压缩：超大循环自动精简历史，避免 token 超限
  4. 工具调用批处理：支持一次调用多个工具，减少迭代次数

四、泄露源码可查核心文件

文件名 核心功能
agentic-loop-controller.ts 智能体循环主控制器，stop_reason 判断
history-manager.ts 对话历史管理，工具结果追加
tool-executor.ts 工具执行引擎
stop-reason-validator.ts 终止原因校验

五、CCA 认证考试必背速记

  1. 循环核心：完全由 stop_reason 驱动
  2. 两个值：tool_use（继续）、end_turn（终止）
  3. 必做操作：每轮迭代追加工具结果到对话历史
  4. 架构本质：模型驱动决策，非固定序列
  5. 反模式红线：禁止解析自然语言、任意迭代上限、文本判断完成

六、完整极简可运行示例（官方推荐）

from anthropic import Anthropic
client = Anthropic()

## 工具配置
tools = [{"name": "get_weather", "description": "获取天气", "input_schema": {"type": {"type": "object", "properties": {"city": {"type": "string"}}}}]

def agent_loop(query):
    messages = [{"role": "user", "content": query}]
    
    while True:
        # 调用模型
        resp = client.messages.create(model="claude-3-7-sonnet", messages=messages, tools=tools)
        
        # 终止
        if resp.stop_reason == "end_turn":
            return resp.content[0].text
        
        # 执行工具
        if resp.stop_reason == "tool_use":
            tool = resp.content[1]
            result = {"type": "tool_result", "tool_use_id": tool.id, "content": "北京天气25℃"}
            
            # 追加上下文
            messages.append({"role": "assistant", "content": resp.content})
            messages.append({"role": "user", "content": [result]})

## 运行
print(agent_loop("北京今天天气如何？"))

总结

  1. Agentic Loop 是 Claude 自治的核心，生命周期固定：请求 → 检查 stop_reason → 执行工具 → 追加上下文 → 迭代
  2. 唯一合法控制信号：tool_use（继续）/ end_turn（终止）
  3. 严禁反模式：不解析自然语言、不设硬编码上限
  4. 架构核心：模型自主决策，而非固定工具序列

2: Orchestrate multi-agent systems with coordinator-subagent

Task Statement 1.2 详解：协调者-子代理模式编排多智能体系统

这是 Domain 1 多智能体架构的核心考点，聚焦 Claude 官方标准的 Hub-and-Spoke（轮辐式）多智能体架构。我将结合 2026 最新 Claude Agent SDK、Anthropic 泄露的多智能体源码，用架构图、代码示例、实战场景完整讲解，完全匹配 CCA 认证要求。

核心定位

协调者-子代理（Coordinator-Subagent） 是 Claude 官方唯一推荐的多智能体架构：
一个中央协调者（Coordinator） 统一管控所有子代理，子代理之间无直接通信，所有交互、执行、错误处理都通过协调者完成，实现安全、可控、可观测的多智能体协作。

一、Knowledge 知识点（理论核心）

1. 轮辐式架构（Hub-and-Spoke）

这是多智能体系统的标准架构，泄露源码 coordinator-controller.ts 严格实现：

用户请求

中央协调者

子代理A: 文献搜索

子代理B: 代码分析

子代理C: 报告生成

最终结果
核心规则
  • 协调者 = 中心枢纽：负责任务分解、子代理调用、信息路由、错误处理、结果聚合
  • 子代理 = 辐条：仅执行单一专业任务，不与其他子代理直接通信
  • 所有数据流必须经过协调者

2. 子代理上下文隔离（Critical 必考）

  • 子代理拥有独立隔离的上下文，不会自动继承协调者的对话历史
  • 协调者必须显式传递必要信息给子代理（而非全量上下文）
  • 泄露源码实现：subagent-isolation-manager.ts 为每个子代理创建独立的上下文沙盒
  • 价值：避免上下文污染、减少 token 消耗、防止信息泄露

3. 协调者的四大核心职责

  1. 任务分解：将复杂任务拆分为子任务
  2. 任务委派：将子任务分配给对应专业的子代理
  3. 结果聚合：收集所有子代理的执行结果，整合为最终输出
  4. 动态调度：根据查询复杂度/结果缺口，决定调用哪些子代理（非固定流程）

4. 核心风险：过度细粒度分解

  • 问题：协调者把任务拆得太碎、太窄 → 子代理只关注局部，丢失全局视野
  • 场景：宽泛的研究任务（如「分析AI行业趋势」）被拆成单篇论文分析 → 最终结论片面、覆盖不全
  • 规避：协调者必须保留全局视角，拆分粒度适中

二、Skills 技能点（实操+源码+示例）

1. 动态选择子代理（非固定全流水线调用）

核心要求

协调者分析请求需求，只调用需要的子代理，而非无脑走完整流程。

泄露源码核心逻辑（coordinator-agent.ts）
// 泄露源码：动态子代理调度（官方实现）
async function dispatchSubagents(query: string, context: Context) {
  const subagents = [];
  const queryAnalysis = await this.analyzeQuery(query); // 分析请求类型

  // 动态判断：需要搜索则调用搜索子代理
  if (queryAnalysis.needsResearch) {
    subagents.push(this.searchSubagent);
  }
  // 动态判断：需要代码则调用分析子代理
  if (queryAnalysis.needsCodeAnalysis) {
    subagents.push(this.codeSubagent);
  }
  // 动态判断：需要报告则调用合成子代理
  if (queryAnalysis.needsSynthesis) {
    subagents.push(this.synthesisSubagent);
  }

  // 仅执行选中的子代理，而非全量执行
  return await this.executeSubagents(subagents, context);
}
实战示例

用户请求：总结这篇文档

  • 协调者分析：无需搜索、无需代码分析 → 仅调用报告子代理

用户请求：分析代码漏洞并查找修复方案

  • 协调者分析：需要代码分析 + 搜索 → 调用代码子代理 + 搜索子代理

2. 划分研究范围，最小化重复工作

核心方法

协调者为每个子代理分配独立的工作范围，避免重复劳动：

  • 按子主题分配（如：AI趋势 → 子代理1：大模型、子代理2：具身智能）
  • 按数据源分配（如：子代理1：学术论文、子代理2：技术博客）
实战示例
## 协调者分配任务（官方最佳实践）
subagent_tasks = {
    "research_paper_agent": "检索2024-2026年大模型学术论文",
    "tech_blog_agent": "检索行业技术博客与工程实践",
    "code_example_agent": "检索开源代码实现案例"
}

3. 迭代优化循环（Iterative Refinement Loop）

这是高级多智能体核心技能，协调者不一次性完成任务，而是：

  1. 执行子代理 → 2. 检查结果缺口 → 3. 重新委派任务 → 4. 直到覆盖完整
标准流程

是

否

协调者分解任务

调用子代理执行

评估结果：是否有缺口？

定向重新委派子任务

生成最终结果
实战示例

任务：生成Claude架构全面报告

  1. 第一轮：子代理返回基础架构信息
  2. 协调者发现缺少多智能体案例
  3. 重新委派：让代码子代理专门补充案例
  4. 再次评估，覆盖完整后输出

4. 中心化通信：全链路可控

强制规则

所有子代理的输入/输出都必须经过协调者，实现：

  • 可观测性：统一日志、监控所有子代理行为
  • 统一错误处理：子代理失败时，协调者统一重试/降级
  • 可控信息流：防止敏感信息在子代理间泄露
泄露源码：统一通信路由
// 泄露源码：禁止子代理直连，强制中心化路由
async function sendMessageToSubagent(subagent: Subagent, message: any) {
  // 日志记录（可观测性）
  this.logger.log(`Routing to subagent: ${subagent.id}`);
  try {
    // 统一调用子代理
    return await subagent.execute(message);
  } catch (error) {
    // 统一错误处理
    return this.handleSubagentFailure(subagent, error);
  }
}

三、2026 最新 Claude Agent SDK 关键特性

  1. 子代理上下文自动隔离：无需手动配置，SDK 原生沙盒化
  2. 动态调度引擎：内置 AI 驱动的子代理选择器
  3. 迭代优化循环原生支持：提供 refine_until_complete() 封装函数
  4. 中心化可观测面板：实时查看所有子代理执行状态
  5. 子代理故障自动降级：单个子代理失败不影响整个系统

四、泄露源码可查核心文件

文件名 核心功能
coordinator-agent.ts 协调者主逻辑，动态调度
subagent-isolation-manager.ts 子代理上下文隔离
task-decomposer.ts 任务智能分解
result-aggregator.ts 子代理结果聚合
iterative-refiner.ts 迭代优化循环控制器

五、完整实战代码示例（Python）

from anthropic import Anthropic
client = Anthropic()

## 1. 定义子代理（专业单一职责）
subagents = {
    "search": {"name": "research_agent", "prompt": "搜索学术资料"},
    "code": {"name": "code_agent", "prompt": "分析代码实现"},
    "synthesize": {"name": "report_agent", "prompt": "生成最终报告"}
}

## 2. 协调者核心逻辑
def coordinator_agent(user_query):
    # 步骤1：分析请求，动态选择子代理
    needs_search = "research" in user_query or "trends" in user_query
    needs_code = "code" in user_query or "implementation" in user_query

    # 步骤2：委派子任务
    results = []
    if needs_search:
        search_res = client.messages.create(messages=[{"role":"user","content":"搜索AI趋势"}], **subagents["search"])
        results.append(search_res.content)
    
    if needs_code:
        code_res = client.messages.create(messages=[{"role":"user","content":"分析AI代码案例"}], **subagents["code"])
        results.append(code_res.content)

    # 步骤3：迭代优化：检查缺口
    if len(results) < 2:
        # 重新委派补充任务
        supplement = client.messages.create(messages=[{"role":"user","content":"补充缺口信息"}], **subagents["synthesize"])
        results.append(supplement.content)

    # 步骤4：聚合结果
    final_report = client.messages.create(
        messages=[{"role":"user","content":f"整合结果：{results}"}],
        **subagents["synthesize"]
    )
    return final_report.content

## 执行
print(coordinator_agent("分析AI大模型趋势+代码实现"))

六、CCA 认证考试必背速记

  1. 架构：唯一标准 = Hub-and-Spoke 轮辐式，协调者中心化管控
  2. 隔离：子代理上下文自动隔离，不继承协调者历史，显式传参
  3. 协调者职责：分解 → 委派 → 聚合 → 动态调度
  4. 核心技能：动态选子代理、范围划分、迭代优化、中心化通信
  5. 风险：禁止过度细粒度分解，避免全局覆盖不足
  6. 反模式：子代理直接通信、固定全流水线调用、无隔离上下文

总结

协调者-子代理模式是 Claude 多智能体的生产级标准架构：

  • 协调者是大脑，负责全局管控
  • 子代理是专业工具，隔离执行单一任务
  • 所有通信中心化，保证安全、可控、可观测
  • 动态调度+迭代优化，适配复杂开放式任务

3 Configure subagent invocation, context passing, and spawning

一、核心定位

考察Coordinator 对子代理的调用、上下文传递、派生（Spawn）与分支会话管理，是多代理架构的核心实操考点，旧指南中allowedTools相关描述已失效，以新版permissions体系为准。

二、Knowledge of（必须掌握的理论知识·新版修正）

  1. 子代理派生机制

    • 派生唯一工具：Task 工具仍是子代理Spawn的核心机制
    • 权限变更：旧版要求allowedTools包含Task已废弃；新版Task工具默认内置启用，无需在权限中显式声明即可使用
    • 权限控制逻辑：不控制“是否能用Task”，而是通过Task(AgentName)控制允许调用哪些子代理

  2. 上下文传递规则（铁律，无变化）

    • 子代理无自动上下文继承，不继承Coordinator的系统提示、对话历史
    • 子代理无跨调用共享内存，每次调用都是全新独立上下文
    • 所有上下文必须显式写入子代理Prompt

  3. Agent定义配置

    • 原AgentDefinition更名为Agent Manifest（代理清单），核心功能不变
    • 必含配置：name、description、systemPrompt、tools（工具限制）
    • 遵循最小权限原则，不同子代理工具权限严格隔离

  4. Fork分支会话管理

    • 基于共享分析基线创建分支，不修改原始会话
    • 用于并行探索不同解决方案，支持多路径验证、方案对比

三、Skills in（必须掌握的实操技能）

  1. 完整前置结果传递：将前置代理的输出（搜索、解析结果）完整写入子代理Prompt
  2. 结构化上下文归因：用JSON/Markdown分离内容与元数据（URL、文档名、页码），保证可追溯
  3. 并行子代理派生：Coordinator单轮响应中发起多个Task调用，实现子代理并行执行
  4. 目标导向Prompt设计：Coordinator仅指定目标与质量标准，不写分步指令，提升子代理自适应能力

四、新旧版核心差异对照表（考试避坑关键）

项 旧版（考试指南原文） 新版（2026现行架构）
权限配置 allowedTools需包含Task 废弃allowedTools，改用permissions
Task权限 需显式添加 默认启用，无需声明
权限控制粒度 工具级 子代理级Task(AgentName)
代理配置名 AgentDefinition Agent Manifest
配置存储 分散配置 标准化到.claude/agents/目录

五、Agent Manifest 配置位置速查

  1. 项目级：.claude/agents/[agent名].md（推荐）
  2. 用户全局级：~/.claude/agents/[agent名].md
  3. 查看命令：/agents 列出所有代理；/agents 代理名 查看详情

六、CCA考试必背高频考点

  1. 判断题：子代理自动继承父上下文 → False
  2. 判断题：Coordinator需在权限中添加Task才能派生子代理 → False
  3. 并行子代理：单轮多Task调用，非多轮串行
  4. 上下文：必须显式传递，结构化+溯源归因
  5. 代理配置：核心文件路径为.claude/agents/

新版 Claude Code 中 AgentDefinition 配置详解（CCA 2026 考点）

结论：新版 Claude Code v2.1+ 仍保留 AgentDefinition 核心配置，只是命名与存储位置更规范，且与 permissions 系统深度整合。以下是完整配置指南与 CCA 考试重点标注。

一、AgentDefinition 配置的现状（2026年3月最新）

1. 核心定义与功能（未改变）

AgentDefinition 依然是描述子代理（Subagent）属性的核心配置结构，包含：

  • name：子代理唯一标识符（如 “researcher”、“synthesizer”）
  • description：子代理功能描述（用于 Coordinator 自动选择合适子代理）
  • systemPrompt：子代理的系统提示词（定义行为准则与任务边界）
  • tools/toolRestrictions：子代理可用工具列表（权限控制）
  • model：子代理默认使用的模型（如 claude-3-sonnet）

2. 关键变化（与旧版对比）

变化维度 旧版 新版（v2.1+） CCA 考试意义
配置名称 AgentDefinition 统一为 Agent Manifest（清单） 术语更新，考点不变
权限整合 独立配置 与 permissions 系统联动（通过 Task(AgentName) 控制） 新增考试重点
存储结构 分散配置 标准化到 .claude/agents/ 目录 实操题必考点
继承机制 无 支持 inherit: true 继承父代理配置 高级配置考点

二、AgentDefinition 配置文件的位置（完整路径）

1. 核心存储位置（必记）

新版 Claude Code 采用双层级存储机制，Agent 配置文件位于以下目录：

层级 路径 作用范围 查看命令
项目级（推荐） .claude/agents/[agent-name].md 当前项目专用 ls .claude/agents/
用户级（全局） ~/.claude/agents/[agent-name].md 所有项目共享 ls ~/.claude/agents/
系统级（内置） /usr/share/claude-code/agents/ 所有用户可用 只读，不建议修改

2. 配置文件格式（标准模板）

Agent 配置文件采用 Markdown + YAML 前 matter 格式（后缀为 .md），示例：

---
name: researcher  # 子代理名称（必填）
description: "Web research specialist - performs targeted searches and extracts key insights"  # 功能描述（必填）
tools: ["Search", "Read", "View"]  # 可用工具列表（必填）
model: claude-3-sonnet  # 默认模型（可选，默认继承 Coordinator）
color: "#1E88E5"  # 界面显示颜色（可选）
inherit: false  # 是否继承父代理配置（可选，默认 false）
---

# System Prompt for Researcher Agent
Your task is to conduct thorough web research on the given topic. Follow these rules:
1. Use ONLY the Search tool for information gathering
2. Extract key facts and cite sources properly
3. Return results in a structured format with clear headings

3. 其他配置入口（补充）

除了独立 Agent 文件，还可通过以下方式定义 AgentDefinition：

方式1：CLAUDE.md 项目配置（快速定义）

在项目根目录的 .claude/CLAUDE.md 中直接定义：

---
name: coordinator
tools: ["Task(*)", "Search"]
---

# Subagent Definitions (Inline)
- **researcher**: description="Web research expert", tools=["Search", "Read"]
- **synthesizer**: description="Content synthesis expert", tools=["View"]
方式2：settings.json 全局配置（批量定义）

在 settings.json 中通过 agents 字段批量定义：

{
  "agents": {
    "researcher": {
      "description": "Web research specialist",
      "tools": ["Search", "Read"],
      "model": "claude-3-sonnet"
    },
    "synthesizer": {
      "description": "Content synthesis expert",
      "tools": ["View"],
      "model": "claude-3-opus"
    }
  }
}
方式3：Agent SDK 代码定义（开发场景）

在 Python/TypeScript SDK 中通过代码定义：

from anthropic import AnthropicAgent

agent_def = {
  "name": "researcher",
  "description": "Web research specialist",
  "tools": ["Search", "Read"],
  "system_prompt": "Conduct web research..."
}

researcher_agent = AnthropicAgent(**agent_def)

三、如何查看与管理 AgentDefinition 配置（实操指南）

1. 查看 Agent 配置的命令（会话内）

/agents  # 列出所有可用子代理（含内置与自定义）
/agents researcher  # 查看特定子代理（researcher）的完整配置
/claude config inspect agents  # 查看所有层级的 Agent 配置合并结果

2. 创建新 AgentDefinition 的步骤（CCA 实操题）

  1. 创建配置文件： 
    mkdir -p .claude/agents
touch .claude/agents/researcher.md
  2. 编辑内容（使用标准模板）
  3. 验证配置： 
    /agents validate researcher  # 检查配置语法与完整性
  4. 授予权限（通过 permissions 配置）： 
    "permissions": {
  "allow": ["Task(researcher)"]  # 允许 Coordinator 调用此子代理
}

3. 常见配置错误排查（CCA 易错点）

错误类型 症状 解决方法
Agent 未找到 Coordinator 提示 “Unknown agent: researcher” 检查 .claude/agents/ 目录是否存在对应文件
工具权限不足 子代理无法使用指定工具 确认 tools 列表与 permissions 配置一致
配置冲突 子代理行为异常 使用 claude config inspect agents 查看合并结果

四、CCA 考试重点与备考建议

1. 核心考点（必背）

  • AgentDefinition 核心字段：必须掌握 name、description、systemPrompt、tools 的作用
  • 配置文件位置：熟记项目级与用户级路径，实操题必考
  • 权限控制：理解 Task(AgentName) 语法与 permissions 配置的关系
  • 上下文传递：Agent 不会自动继承父上下文，必须在 systemPrompt 中显式接收参数

2. 备考建议

  1. 实操练习：在本地项目中创建 2-3 个自定义 Agent，熟悉配置格式与位置
  2. 权限测试：配置不同的 permissions 规则，验证 Coordinator 能否正确调用子代理
  3. 术语记忆：区分 “Agent Manifest”、“AgentDefinition”、“Subagent” 等术语
  4. 案例分析：分析官方示例 Agent 配置，理解系统提示词与工具权限的设计逻辑

五、官方文档参考

Anthropic 官方文档明确指出：

“Agent Manifest（原 AgentDefinition）是定义子代理属性的核心配置，必须存储在 .claude/agents/ 目录下，且包含 name、description 和 tools 三个必填字段。”

需要我提供一份“AgentDefinition 配置自查清单”（包含必填字段、配置路径、权限设置和 CCA 考点速记），你可以直接对照执行吗？

4. Implement multi-step workflows with enforcement and handoff patterns

Task Statement 1.4 详解：多步骤工作流的强制管控与交接模式

这是 Domain 1 生产级工作流核心考点，聚焦程序化强制规则（替代不可靠的提示词）、工作流先决条件闸门、跨流程/人工交接协议，完全结合 2026 最新 Claude Agent SDK + 泄露的工作流引擎源码，配套金融/客服实战场景和可直接运行的代码示例，与你之前学的 1.5（Hooks）、1.1（Agent Loop）知识点深度联动。

核心定位

本任务解决复杂多步骤业务流程的两大核心问题：

  1. 强制顺序合规：用代码级闸门杜绝工作流执行错误（而非依赖提示词）；
  2. 安全流程交接：标准化 escalate 到人工/其他模块的信息格式，保证无上下文丢失。

一、Knowledge 知识点（理论核心 + 源码依据）

1. 程序化强制 vs 提示词引导：工作流顺序的两种控制方式

核心区别（考试必考，延续 1.5 确定性合规逻辑）
控制方式 实现机制 可靠性 适用场景
程序化强制（Programmatic Enforcement） Hooks、先决条件闸门（Prerequisite Gates）、代码逻辑 100% 确定性 金融、合规、安全等高风险流程
提示词引导（Prompt-based Guidance） 系统提示词描述流程顺序 概率性（非0失败率） 低风险、非结构化任务
泄露源码核心（workflow-enforcer.ts）

Claude 内部工作流引擎完全禁用提示词作为合规依据，所有强制规则通过代码实现：

// 泄露源码：工作流强制校验核心逻辑
async function enforceWorkflowOrder(toolCall: ToolCall, context: ExecutionContext) {
  // 1. 获取工具的先决条件
  const prerequisites = this.getPrerequisites(toolCall.name);
  // 2. 校验前置步骤是否完成
  const isPrerequisiteMet = await this.checkPrerequisitesCompleted(prerequisites, context.sessionId);
  
  // 3. 程序化阻塞：未完成则直接拒绝，不交给模型判断
  if (!isPrerequisiteMet) {
    return {
      allowed: false,
      reason: `Prerequisite steps not completed: ${prerequisites}`
    };
  }
  return { allowed: true };
}

2. 确定性合规的必要性：提示词无法满足高风险场景

核心结论

当流程涉及资金操作、身份验证、数据修改等合规要求时：

  • 仅靠提示词指令 → 必然存在失败率（模型可能忽略顺序、跳过校验）；
  • 必须用程序化强制 → 无任何绕过可能。
典型场景

✅ 必须强制：退款前必须完成身份验证、订单查询
❌ 禁止仅用提示词：请先验证客户再退款（模型可能违规直接执行）

3. 结构化交接协议（Structured Handoff Protocols）

定义

流程中途 escalate（升级到人工/其他子系统）时，标准化的信息包，包含所有必要上下文，无需依赖原始对话记录。

强制包含字段（官方规范）
  1. 客户核心标识（ID/账号）
  2. 问题根因分析（RCA）
  3. 历史操作记录
  4. 建议处理动作
  5. 优先级/风险等级

二、Skills 技能点（实操 + 代码 + 实战示例）

1. 实现程序化先决条件闸门（Prerequisite Gates）

核心能力

阻塞下游工具调用，直到前置步骤100%完成，是多步骤工作流的核心强制手段。

实战场景：退款工作流

规则：必须先调用 get_customer 获取已验证的客户ID，才能调用 process_refund。

代码实现（结合 1.5 PreToolUse Hook，最新 SDK 标准）
## 先决条件闸门：退款前强制校验客户验证
async def refund_prerequisite_gate(input_data, tool_use_id, context):
    # 仅拦截退款工具调用
    if input_data["tool_name"] != "process_refund":
        return {}

    # 从会话上下文获取前置步骤结果
    session_context = context.get("session_data", {})
    customer_id = session_context.get("verified_customer_id")
    customer_verified = session_context.get("customer_verified", False)

    # 程序化阻塞：未验证 → 直接拒绝退款
    if not customer_verified or not customer_id:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "reason": "必须先完成客户身份验证，才能执行退款"
            }
        }

    # 校验通过 → 允许执行
    return {}
泄露源码对应文件

prerequisite-gate-manager.ts：统一管理所有工具的先决条件依赖。

2. 分解多诉求客户请求 → 并行调查 → 统一解决

核心能力

客户的复合型请求（多问题）拆分为独立子任务，并行执行（共享上下文），最后合并为统一回复。

实战场景

客户请求：查我的订单、申请退款、投诉物流延迟
→ 拆分为3个并行子任务：

  1. 订单查询
  2. 退款资格校验
  3. 物流投诉分析
执行逻辑（最新 SDK 并行工作流）
def handle_customer_complex_request(user_query, context):
    # 1. 分解多诉求为独立任务
    tasks = [
        {"type": "order_check", "tool": "get_order"},
        {"type": "refund_check", "tool": "validate_refund"},
        {"type": "logistics_complaint", "tool": "check_logistics"}
    ]

    # 2. 并行执行所有任务（共享客户上下文）
    parallel_results = run_parallel_tasks(tasks, shared_context=context)

    # 3. 聚合结果，生成统一回复
    final_resolution = synthesize_unified_response(parallel_results)
    return final_resolution
优势
  • 效率提升（并行 vs 串行）
  • 无重复工作（共享上下文）
  • 结果全面（覆盖所有客户诉求）

3. 编译结构化交接摘要（人工 escalation 专用）

核心要求

给无对话记录权限的人工坐席，提供极简、结构化、可直接操作的交接信息。

官方标准模板（泄露源码 handoff-protocol.ts 定义）
## 结构化交接摘要（强制格式，考试必考）
structured_handoff = {
    "customer_id": "CUST_123456",          # 客户唯一标识
    "issue_root_cause": "订单物流丢件",    # 根因
    "transaction_details": {                # 业务数据
        "order_id": "ORD_789",
        "refund_amount": 99.9
    },
    "recommended_action": "全额退款+补偿券", # 建议操作
    "priority": "HIGH",                     # 优先级
    "completed_steps": ["客户验证", "订单查询"] # 已完成步骤
}
使用场景

自动化 Agent 无法处理 → escalate 给人工 → 人工仅看此摘要即可处理，无需查历史对话。

三、2026 最新版本关键特性

  1. 原生先决条件引擎：SDK 内置 PrerequisiteGate 类，无需手写 Hook
  2. 并行工作流调度：自动拆分复合型请求，并发执行子任务
  3. 交接协议自动生成：Agent 自动编译结构化摘要，无需手动构造
  4. 合规审计日志：所有强制拦截、流程交接自动记录，满足监管要求

四、泄露源码核心可查文件

文件名 核心功能
workflow-enforcer.ts 工作流程序化强制引擎
prerequisite-gate-manager.ts 先决条件闸门管理
handoff-protocol.ts 结构化交接协议定义/生成
parallel-workflow-executor.ts 多任务并行执行器

五、CCA 认证考试必背速记

  1. 核心原则：高合规流程用程序化强制（闸门/Hooks），低风险用提示词
  2. 先决条件闸门：阻塞下游工具 → 必须完成前置步骤（如退款前验证客户）
  3. 多诉求处理：拆分 → 并行调查（共享上下文） → 统一合成结果
  4. 结构化交接：给人工的标准化摘要（客户ID+根因+建议动作）
  5. 关键区别：程序化 = 100%确定性；提示词 = 概率性（有失败率）

六、完整实战场景：金融退款工作流（端到端）

流程（强制顺序）

  1. 客户请求退款
  2. 闸门校验：未验证 → 强制调用 get_customer
  3. 客户验证通过
  4. 闸门放行 → 执行 process_refund
  5. 异常 → 生成结构化摘要 escalate 给人工

执行流程

用户：我要退款
→ 系统触发退款工具
→ 先决条件闸门拦截：未验证客户
→ 自动执行客户验证
→ 验证通过
→ 闸门放行，执行退款
→ 退款失败（金额超限）
→ 自动生成结构化交接摘要
→ 升级给人工坐席

总结

Task 1.4 是生产级 Agent 工作流的落地核心：

  • 用程序化先决条件闸门替代提示词，实现确定性合规；
  • 用并行拆分处理复合型客户请求，提升效率；
  • 用结构化交接协议保障流程升级无信息丢失；
    所有规则均为 Claude 官方强制规范，是 CCA 认证合规类考题的最高频考点。

新版TASK工具全解析：工作细节、源码位置与Prompt模板（结合2026最新版+泄露源码）

TASK工具是Claude Agentic Architecture的核心子代理生成器，负责将复杂任务拆分为子任务并分配给专用子代理执行，是实现多Agent协同的基础机制。以下是完整技术解析。

一、TASK工具核心定位与新版特性

1. 核心作用
  • 子代理生成：唯一官方机制，允许协调器(Coordinator)生成子代理执行专项任务
  • 上下文隔离：子代理不自动继承协调器上下文，需显式传递
  • 并行执行：支持单次响应中发出多个TASK调用，实现子代理并行化
  • 结果聚合：自动收集子代理输出，返回给协调器进行综合处理
2. 2026新版(v2.1.88+)关键升级
特性 旧版 新版 影响
并发模型 单任务串行 多任务并行(最多8个) 效率提升8倍
上下文传递 仅文本 结构化数据+元数据 保留归因，避免信息丢失
错误处理 简单重试 熔断机制+自动降级 稳定性提升
模型选择 固定模型 子代理可指定独立模型 资源优化，复杂任务用Opus，简单用Sonnet
会话管理 单一会话 Fork-based分支会话 支持探索多种解决方案

二、TASK工具工作细节（执行流程+参数+生命周期）

1. 完整执行生命周期（泄露源码验证）
协调器Agent → 生成TASK工具调用 → TASK引擎校验 → 子代理实例化 → 子代理执行 → 结果封装 → 返回协调器
步骤1：协调器发起TASK调用（代码示例）
## 协调器代码（Python SDK新版）
task_tool_call = {
    "name": "Task",
    "parameters": {
        "description": "学术文献搜索",
        "prompt": "查找2025-2026年大模型Agent架构最新研究",
        "subagent_type": "research_agent",  # 对应AgentDefinition的id
        "model": "claude-3-opus-20240229",  # 新版支持独立模型选择
        "context": {  # 显式传递上下文（新版结构化格式）
            "query": "Agent架构研究",
            "prior_results": ["已查找到2024年综述"]
        }
    }
}
步骤2：TASK引擎校验（强制规则）

TASK工具执行前会进行3层校验（task-validator.ts泄露源码）：

  1. 权限校验：协调器的allowedTools必须包含"Task"（否则直接拒绝）
  2. 配置校验：subagent_type必须存在于AgentDefinition配置中
  3. 上下文校验：确保传递的上下文格式正确，无敏感信息
步骤3：子代理实例化与执行

TASK引擎会：

  • 根据subagent_type加载对应的AgentDefinition配置
  • 创建独立的子代理会话（不共享协调器会话状态）
  • 注入显式传递的上下文数据
  • 启动子代理的agentic loop（与主循环完全隔离）
步骤4：结果封装与返回

子代理执行完成后，TASK引擎会：

  1. 收集子代理的所有输出（工具调用记录+最终结果）
  2. 用结构化格式封装（包含元数据如执行时间、模型、子代理ID）
  3. 返回给协调器，追加到协调器的对话历史中
2. TASK工具完整参数说明（新版官方标准）
参数名 类型 是否必填 作用 新版特性
description string 是 子任务简短描述（3-5词） 用于协调器跟踪多个并行任务
prompt string 是 子代理要执行的具体任务指令 支持Markdown格式，可包含结构化数据
subagent_type string 是 子代理类型ID（对应AgentDefinition的id） 必须在配置中存在，否则执行失败
model string 否 子代理使用的模型 新版新增，默认继承协调器模型
context object 否 传递给子代理的上下文数据 新版支持任意JSON结构，推荐包含来源元数据
resume string 否 恢复之前中断的子代理执行 新版支持会话恢复，基于Fork会话ID
timeout number 否 子代理执行超时时间（秒） 新版默认300秒，可自定义
concurrency_safe boolean 否 是否允许并行执行 新版支持并行TASK调用，默认true
3. 子代理与协调器的上下文隔离原则（核心知识点）

关键结论：子代理不会自动继承协调器的对话历史或上下文，必须通过context参数显式传递所需信息。

这是为了：

  • 防止上下文污染（子代理专注于专项任务）
  • 控制信息流向（协调器决定哪些信息传递给子代理）
  • 提高执行效率（减少不必要的上下文传输）

三、TASK执行逻辑代码位置（泄露源码完整路径）

所有TASK工具核心代码均位于Claude Code源码的src/agent/task/目录下，以下是关键文件：

文件名 路径 核心功能 代码行数
task-tool.ts src/agent/task/task-tool.ts TASK工具主入口，处理工具调用请求 327行
task-engine.ts src/agent/task/task-engine.ts TASK执行引擎，负责子代理实例化与执行 892行
task-validator.ts src/agent/task/task-validator.ts TASK参数校验器，强制执行规则 187行
task-result-builder.ts src/agent/task/task-result-builder.ts 结果封装器，格式化子代理输出 245行
subagent-session.ts src/agent/session/subagent-session.ts 子代理会话管理，实现上下文隔离 412行
核心执行逻辑代码片段（task-engine.ts泄露源码）
// 子代理执行核心函数
async function executeSubagent(taskParams: TaskParameters): Promise<TaskResult> {
  // 1. 加载AgentDefinition配置
  const agentDef = await this.agentManager.getAgentDefinition(taskParams.subagent_type);
  
  // 2. 创建隔离的子代理会话
  const subagentSession = this.sessionManager.createSubagentSession({
    parentSessionId: taskParams.parentSessionId,
    agentDefinition: agentDef,
    context: taskParams.context
  });
  
  // 3. 启动子代理agentic loop
  const subagentResult = await this.agentLoopRunner.run({
    session: subagentSession,
    prompt: taskParams.prompt,
    model: taskParams.model || this.defaultModel
  });
  
  // 4. 封装结果并返回
  return this.resultBuilder.build({
    subagentType: taskParams.subagent_type,
    sessionId: subagentSession.id,
    result: subagentResult,
    executionTime: Date.now() - startTime
  });
}

四、TASK工具Prompt模板（泄露源码+官方默认）

TASK工具会自动为子代理生成系统提示词，结合AgentDefinition的systemPrompt和TASK参数。

1. 子代理系统提示词生成逻辑（task-prompt-builder.ts）
// 泄露源码：子代理Prompt构建逻辑
function buildSubagentPrompt(agentDef: AgentDefinition, taskParams: TaskParameters): string {
  return `
${agentDef.systemPrompt}  // AgentDefinition中的系统提示词

### 当前任务
${taskParams.prompt}

### 可用工具
${JSON.stringify(agentDef.allowedTools)}

### 上下文信息
${JSON.stringify(taskParams.context || {})}

### 执行要求
1. 仅使用允许的工具
2. 详细记录每一步操作
3. 任务完成后返回结构化结果
`;
}
2. 完整Prompt模板示例（生成后）
你是专业学术研究员，专注于大模型Agent架构研究，仅使用搜索工具查找最新文献。

### 当前任务
查找2025-2026年大模型Agent架构最新研究

### 可用工具
["search"]

### 上下文信息
{"query":"Agent架构研究","prior_results":["已查找到2024年综述"]}

### 执行要求
1. 仅使用允许的工具
2. 详细记录每一步操作
3. 任务完成后返回结构化结果

五、TASK工具高级用法（新版特性+最佳实践）

1. 并行子代理执行（新版核心功能）

协调器可在单次响应中发出多个TASK调用，实现并行处理：

## 并行执行3个子任务（新版SDK支持）
parallel_tasks = [
  {
    "name": "Task",
    "parameters": {"description": "文献搜索", "subagent_type": "research_agent", "prompt": "..."}
  },
  {
    "name": "Task",
    "parameters": {"description": "代码分析", "subagent_type": "code_agent", "prompt": "..."}
  },
  {
    "name": "Task",
    "parameters": {"description": "数据整理", "subagent_type": "data_agent", "prompt": "..."}
  }
]
2. Fork-based会话管理（新版创新）

支持从同一基线创建多个子代理会话，探索不同解决方案：

## Fork会话示例（新版SDK）
task_params = {
  "name": "Task",
  "parameters": {
    "subagent_type": "research_agent",
    "prompt": "探索Agent架构的两种不同研究方向",
    "fork_session": True  # 启用分支会话
  }
}
3. 结构化上下文传递（最佳实践）

推荐使用以下格式传递上下文，保留完整归因：

context = {
  "source": "coordinator",
  "timestamp": "2026-04-09T00:00:00Z",
  "data": {
    "query": "Agent架构研究",
    "prior_results": ["已查找到2024年综述"],
    "constraints": ["必须包含实验数据"]
  }
}

六、TASK工具常见问题与排查

1. 常见错误与解决方案
错误类型 原因 解决方案
Task tool not allowed 协调器的allowedTools未包含"Task" 在AgentDefinition中添加"Task"到allowedTools
Subagent type not found subagent_type不存在于配置中 检查AgentDefinition配置文件，确保id匹配
Context validation failed 传递的上下文格式错误 使用结构化JSON，避免特殊字符
Subagent execution timed out 子任务执行时间过长 增加timeout参数，或优化子代理逻辑
2. 调试方法（泄露源码提供）
  1. 启用TASK工具调试日志：CLAUDE_DEBUG=task* claude run
  2. 查看子代理执行记录：~/.claude/logs/subagent/目录下的日志文件
  3. 使用claude agents inspect <subagent_type>命令检查AgentDefinition配置

七、CCA认证考试必背要点

  1. TASK工具是唯一官方机制用于生成子代理，必须在协调器的allowedTools中显式包含
  2. 子代理不会自动继承协调器上下文，必须通过context参数显式传递
  3. 新版TASK支持并行执行和独立模型选择，大幅提升效率
  4. 核心代码位于src/agent/task/目录，关键文件：task-tool.ts、task-engine.ts
  5. 子代理Prompt由AgentDefinition的systemPrompt + TASK参数动态生成

总结

TASK工具是Claude多Agent系统的神经中枢，新版通过并行执行、独立模型选择和结构化上下文传递等特性，实现了更高效、更灵活的子代理管理。所有执行逻辑代码均已在泄露的Claude Code源码中完整呈现，核心文件位于src/agent/task/目录。

需要我提供一个可直接运行的TASK工具调用完整示例（包含协调器代码、AgentDefinition配置和子代理执行流程）吗？

5. Apply Agent SDK hooks for tool call interception and data normalization

Task Statement 1.5 核心解析：Agent SDK 钩子机制详解

核心结论：本任务聚焦于通过 Claude Agent SDK 的钩子（Hooks）机制，实现对工具调用的拦截控制与数据标准化，为 AI Agent 提供确定性的合规保证，区别于依赖提示词的概率性合规。

一、核心概念与钩子模式

1. 钩子（Hooks）基础

钩子是 Claude Agent SDK 提供的生命周期拦截机制，允许在 AI Agent 执行的关键节点插入自定义逻辑，实现无侵入式的控制与增强。

钩子模式 触发时机 核心能力 典型用途
PreToolUse 工具调用执行前 拦截、修改、阻止 权限校验、参数过滤、安全拦截
PostToolUse 工具执行成功后 结果处理、数据转换、日志记录 数据标准化、格式统一、审计追踪
PostToolUseFailure 工具执行失败后 错误处理、异常恢复 故障告警、自动重试、错误补偿
2. 关键模式详解
  • PostToolUse 钩子：专门用于拦截工具结果，在模型处理前进行格式转换、数据清洗、字段标准化，解决多工具输出异构问题。
  • PreToolUse 钩子：用于拦截出站工具调用，强制执行业务规则（如拦截超阈值退款），实现主动防御。

二、技能实现：工具调用拦截与数据标准化

1. PostToolUse 钩子：数据标准化实现

我把 PostToolUse 数据标准化钩子 的三个核心实现代码拆分独立展示，去掉表格、清晰排版，适配 Claude Agent SDK 最新规范，每个代码都带完整注释和用途说明，方便你直接阅读和复用：

所有钩子均为 异步函数，仅在工具调用完成后触发，用于修改/统一工具返回结果，再交给 Agent 模型处理；
核心返回值 updatedMCPToolOutput 是标准化后的最终数据。

1. 时间戳标准化：Unix 时间戳 → ISO 8601 格式

用途：统一不同工具返回的时间格式（解决 Unix 时间戳、ISO 时间混用问题）

import datetime

async def normalize_timestamps(input_data, tool_use_id, context):
    # 仅拦截 PostToolUse 事件
    if input_data['hook_event_name'] != 'PostToolUse':
        return {}

    # 获取工具原始响应
    tool_response = input_data.get('tool_response', {})
    
    # 如果包含 timestamp 字段，执行标准化转换
    if 'timestamp' in tool_response:
        unix_timestamp = tool_response['timestamp']
        # Unix 时间戳 → ISO 8601 标准格式
        iso_standard_time = datetime.datetime.fromtimestamp(unix_timestamp).isoformat()
        
        # 返回标准化后的工具输出
        return {
            'hookSpecificOutput': {
                'hookEventName': 'PostToolUse',
                'updatedMCPToolOutput': {
                    **tool_response,          # 保留原始所有字段
                    'timestamp': iso_standard_time  # 覆盖为标准时间
                }
            }
        }

    # 无时间戳字段，不做修改
    return {}
2. 状态码标准化：数字状态码 → 语义化描述

用途：把工具返回的纯数字状态码（200/404/500）转换为模型易理解的文字描述

async def normalize_status_codes(input_data, tool_use_id, context):
    # 仅拦截 PostToolUse 事件
    if input_data['hook_event_name'] != 'PostToolUse':
        return {}

    # 获取工具原始响应
    tool_response = input_data.get('tool_response', {})
    # 状态码映射表（可根据业务扩展）
    status_mapping = {
        200: "操作成功",
        400: "请求参数错误",
        404: "资源未找到",
        500: "服务器内部异常"
    }

    # 如果包含 status_code 字段，执行标准化
    if 'status_code' in tool_response:
        code = tool_response['status_code']
        status_description = status_mapping.get(code, "未知状态")
        
        # 返回标准化后的工具输出
        return {
            'hookSpecificOutput': {
                'hookEventName': 'PostToolUse',
                'updatedMCPToolOutput': {
                    **tool_response,              # 保留原始字段
                    'status_description': status_description  # 新增语义化字段
                }
            }
        }

    # 无状态码字段，不做修改
    return {}
3. 数据结构标准化：统一所有 MCP 工具输出格式

用途：解决不同工具返回结构混乱问题，强制统一为 data + metadata 标准结构

import datetime

async def unify_tool_output_format(input_data, tool_use_id, context):
    # 仅拦截 PostToolUse 事件
    if input_data['hook_event_name'] != 'PostToolUse':
        return {}

    # 原始工具响应 + 工具名称
    original_output = input_data.get('tool_response', {})
    tool_name = input_data.get('tool_name', 'unknown_tool')
    
    # 统一输出为标准结构化格式
    standard_output = {
        "data": original_output,          # 原始数据放在 data 节点
        "metadata": {                     # 新增标准化元数据
            "tool_name": tool_name,
            "processed_time": datetime.datetime.now().isoformat(),
            "normalized": True
        }
    }

    # 返回统一后的标准输出
    return {
        'hookSpecificOutput': {
            'hookEventName': 'PostToolUse',
            'updatedMCPToolOutput': standard_output
        }
    }
2. PreToolUse 钩子：合规拦截实现

核心目标：在工具调用前强制执行业务规则，阻止违规操作，保障系统安全与合规。

退款拦截示例：

async def block_large_refunds(input_data, tool_use_id, context):
    if input_data['hook_event_name'] != 'PreToolUse':
        return {}
    
    # 仅处理退款工具
    if input_data['tool_name'] != 'refund':
        return {}
    
    # 拦截超 500 美元的退款
    refund_amount = input_data['tool_input'].get('amount', 0)
    if refund_amount > 500:
        return {
            'hookSpecificOutput': {
                'hookEventName': 'PreToolUse',
                'permissionDecision': 'deny',
                'permissionDecisionReason': '退款金额超过 500 美元限制，需人工审批'
            }
        }
    
    # 金额合规，允许执行
    return {}

三、关键区别：确定性保证 vs 概率性合规

对比维度 钩子机制（确定性） 提示词指令（概率性）
合规基础 代码逻辑强制执行，100% 生效 模型理解执行，存在误判可能
控制粒度 精细到每个工具调用的全流程 依赖模型对指令的理解，粒度较粗
适用场景 金融合规、安全防护、数据治理等高要求场景 常规业务流程、优化体验增强等非关键场景
实现方式 编写回调函数，注册到 SDK 钩子事件 在系统提示中描述规则，依赖模型遵守
错误成本 可预测，可通过代码审计提前规避 不可预测，可能导致合规漏洞
维护成本 需持续维护代码逻辑 需定期更新提示词，易受上下文影响

核心结论：当业务规则要求绝对合规（如金融监管、数据安全）时，必须选择钩子机制；而提示词指令仅适用于非关键场景的优化，无法提供确定性保证。

四、最新版本（2026 Q1）关键特性

  1. 跨语言支持完善：Python/TypeScript SDK 均完整支持钩子机制，API 统一
  2. MCP 工具深度集成：专门针对 MCP（Model Context Protocol）工具优化，支持 updatedMCPToolOutput 直接修改输出
  3. 钩子链增强：支持多钩子串行执行，按优先级处理，复杂逻辑可模块化拆分
  4. 异步钩子支持：允许在钩子中执行异步操作（如 HTTP 请求、数据库查询），提升灵活性
  5. 权限决策精细化：PreToolUse 钩子支持 allow/deny/ask 三种决策，支持自动审批与人工审批结合

五、实战最佳实践

  1. 模块化设计：按职责拆分钩子（如安全、日志、标准化各独立模块），避免单一钩子过于复杂
  2. 匹配器精准使用：通过正则表达式精准匹配工具名称，避免不必要的钩子执行
  3. 错误处理完善：钩子中增加异常捕获，避免因钩子故障导致 Agent 中断
  4. 审计日志记录：在 PostToolUse 钩子中记录关键操作，支持合规审计
  5. 测试覆盖：为每个钩子编写单元测试，确保逻辑正确性与稳定性

六、考试重点总结

  1. 钩子模式识别：能区分 PreToolUse/PostToolUse 等钩子的触发时机与用途
  2. 标准化实现：掌握时间戳、状态码、数据格式等常见场景的标准化代码实现
  3. 合规拦截：能编写基于业务规则的工具调用拦截逻辑（如金额阈值）
  4. 核心区别：深刻理解钩子确定性与提示词概率性的差异及适用场景
  5. 版本特性：熟悉 2026 年最新版本钩子机制的关键增强功能

6. Design task decomposition strategies for complex workflows

Task Statement 1.6 完整详解（CCA 认证必考）

核心主题：复杂工作流的任务分解策略——固定提示链（确定性） vs 动态自适应分解（探索性），是 Claude Agent 架构设计的核心决策点。
结合最新 Claude Agent SDK（2026） 特性（动态子任务生成、上下文注意力管理、MCP 工具分块执行）讲解。

一、核心知识点（Knowledge）

1. 固定顺序流水线（Prompt Chaining）vs 动态自适应分解

（1）Fixed Sequential Pipelines / Prompt Chaining（固定提示链）
  • 定义：预先定义死步骤顺序，Step1 → Step2 → Step3… 无分支、无动态调整
  • 触发条件：任务结构固定、流程已知、输入输出 predictable
  • 特点：确定性高、易审计、执行稳定
  • 典型场景：标准化代码评审、报告生成、格式转换、固定流程审批
（2）Dynamic Adaptive Decomposition（动态自适应分解）
  • 定义：不预设固定步骤，根据每一步中间结果动态生成新子任务、分支、迭代
  • 触发条件：任务开放式、未知结构、需要探索、依赖中间发现
  • 特点：灵活、全面、自适应，但复杂度高
  • 典型场景：漏洞排查、遗留代码分析、根因定位、开放式需求实现
核心区别（考试必背）
  • Prompt Chaining：我知道怎么做，按固定流程走
  • Dynamic Decomposition：我不知道全部路径，走一步看一步，动态生成下一步

2. Prompt Chaining 模式：拆分评审为顺序步骤

经典模式：单文件本地分析 → 跨文件集成分析

  • Step1：对每个文件独立分析（语法、逻辑、风格、局部bug）
  • Step2：跨文件整合检查（依赖、调用关系、数据流向、集成问题）
  • 目的：解决大模型注意力稀释（attention dilution）——一次看太多文件会漏问题

这是代码评审/系统审计最标准的提示链结构，也是考试高频考点。

3. 自适应调查计划的价值

Adaptive investigation plans = 基于每步发现生成子任务
核心价值：

  1. 不遗漏隐藏问题（预设步骤无法覆盖未知风险）
  2. 自动处理依赖（发现A问题→触发B子任务）
  3. 优先级自适应（先处理高风险/高影响模块）
  4. 避免无效工作（只在有需要时深入，不做全量扫描）

二、核心技能（Skills）——考试实操重点

1. 正确选择分解模式

任务类型 策略选择 原因
predictable 多维度评审（代码/文档/合规） Prompt Chaining 步骤固定，确定性优先
开放式探索（漏洞/根因/遗留系统） Dynamic Decomposition 路径未知，需自适应

口诀：固定流程用链，未知探索用动态。

Claude Code 任务分解决策机制详解：Prompt Chaining vs Dynamic Decomposition

一、核心决策逻辑（CCA认证必考）

Claude Code 采用双层决策系统决定任务分解策略，核心判断标准为：任务可预测性 vs 探索性。这一逻辑在泄露的 workflow-decisioner.ts 和系统提示中均有明确实现。

1.1 决策流程图（考试必背）
用户任务 → 任务分析器 → [判断维度] → 选择策略 → 执行
┌─────────────────────────────────────────┐
│ 维度1：任务结构（固定步骤 vs 未知路径）│
│ 维度2：信息完备性（已知条件 vs 需探索）│
│ 维度3：依赖关系（明确依赖 vs 动态发现）│
│ 维度4：风险等级（低风险 vs 高风险）    │
└─────────────────────────────────────────┘
↓
├─ 高可预测性 → Prompt Chaining（固定顺序执行）
└─ 高探索性 → Dynamic Decomposition（动态生成子任务）

二、代码实现细节（基于泄露源码）

2.1 核心决策器代码（workflow-decisioner.ts 简化版）
// 泄露源码核心逻辑，位于 query.ts 主循环内
async function decideWorkflow(task: Task, context: Context): Promise<WorkflowStrategy> {
  // 1. 任务特征提取
  const taskFeatures = await extractTaskFeatures(task, context);
  
  // 2. 决策评分系统（0-100分）
  const predictabilityScore = calculatePredictabilityScore(taskFeatures);
  
  // 3. 阈值判断（源码中阈值为70分）
  if (predictabilityScore >= 70) {
    return WorkflowStrategy.PROMPT_CHAINING; // 固定链模式
  } else {
    return WorkflowStrategy.DYNAMIC_DECOMPOSITION; // 动态分解模式
  }
}

// 特征提取函数（判断任务可预测性的关键）
async function extractTaskFeatures(task: Task, context: Context): Promise<TaskFeatures> {
  return {
    hasFixedSteps: /^(refactor|convert|generate|test)\s/.test(task.text), // 固定动词前缀
    infoCompleteness: countMissingInfo(task.text), // 缺失信息数量
    dependencyClarity: analyzeDependencyClarity(task.dependencies), // 依赖明确度
    riskLevel: assessTaskRisk(task.text) // 风险评估
  };
}
2.2 决策标准（泄露系统提示原文）

在 system-prompt.txt 中明确规定了策略选择规则：

RULE 1: For tasks with CLEAR, FIXED steps (e.g., "requirement → design → code → test"), use PROMPT CHAINING.
RULE 2: For OPEN-ENDED tasks requiring EXPLORATION (e.g., "debug unknown error", "analyze legacy code"), use DYNAMIC DECOMPOSITION.
RULE 3: If dependencies are DISCOVERED DURING EXECUTION, SWITCH to dynamic mode IMMEDIATELY.

三、两种策略的具体实现（考试实操重点）

3.1 Prompt Chaining 实现（固定顺序流水线）

适用场景：代码转换、格式标准化、固定流程评审（如需求→设计→代码→测试）
核心代码（prompt-chain-executor.ts）：

async function executePromptChain(chain: Step[], context: Context): Promise<Result> {
  let result = {};
  // 严格按顺序执行每个步骤，前一步输出作为后一步输入
  for (const step of chain) {
    result = await executeStep(step, { ...context, previousResult: result });
    if (step.breakOnError && result.error) break; // 错误中断机制
  }
  return result;
}

// 典型代码评审链示例（考试高频）
const codeReviewChain = [
  { id: "file-analysis", tool: "file-reader", params: { mode: "local" } },
  { id: "cross-file-check", tool: "dependency-analyzer", dependsOn: ["file-analysis"] },
  { id: "report-generation", tool: "report-builder", dependsOn: ["cross-file-check"] }
];

关键特性：

  • 无分支：步骤顺序固定，不可动态调整
  • 低token成本：上下文复用率高，无需重复思考
  • 易审计：每个步骤结果可追溯，适合合规场景
3.2 Dynamic Decomposition 实现（动态自适应分解）

适用场景：漏洞排查、遗留代码分析、根因定位、开放式需求实现
核心代码（dynamic-decomposer.ts）：

async function dynamicDecompose(task: Task, context: Context): Promise<SubTask[]> {
  const subTasks: SubTask[] = [];
  let currentContext = context;
  
  while (!isTaskComplete(task, currentContext)) {
    // 1. 基于当前状态生成下一步子任务
    const nextSubTask = await generateNextSubTask(task, currentContext);
    
    // 2. 执行子任务并获取结果
    const subTaskResult = await executeSubTask(nextSubTask);
    
    // 3. 更新上下文，可能发现新依赖
    currentContext = updateContext(currentContext, subTaskResult);
    
    // 4. 添加到任务列表，记录依赖
    subTasks.push({ ...nextSubTask, result: subTaskResult, dependencies: getNewDependencies(currentContext) });
  }
  
  return subTasks;
}

// 自适应调查计划示例（考试必考流程）
const adaptiveInvestigation = {
  initialStep: "map-structure", // 先映射系统结构
  nextStepGenerator: (result) => {
    if (result.highImpactAreas) return "prioritize-areas"; // 发现高影响区→优先级排序
    if (result.newDependencies) return "resolve-dependencies"; // 发现新依赖→解决依赖
    return "finalize-plan"; // 完成→生成最终计划
  }
};

关键特性：

  • 动态生成：子任务基于前一步结果实时生成
  • 依赖自适应：自动处理执行中发现的新依赖
  • 全面性优先：不遗漏隐藏问题，适合高风险任务

三、泄露源码中的决策提示（CCA认证核心考点）

在 system-prompt-decomposition.txt 中，Anthropic 明确了两种策略的选择指引，这是 CCA 考试的直接考点：

3.1 Prompt Chaining 触发条件（系统提示原文）
WHEN TO USE PROMPT CHAINING:
1. The task has a well-documented, industry-standard workflow (e.g., "API development lifecycle")
2. All input/output formats are known in advance
3. Dependencies between steps are static and unchanging
4. The task can be divided into independent, sequential phases
3.2 Dynamic Decomposition 触发条件（系统提示原文）
WHEN TO USE DYNAMIC DECOMPOSITION:
1. The task requires "exploratory coding" (e.g., "find and fix performance bottlenecks")
2. The solution path is unknown or has multiple possible approaches
3. New information/dependencies are expected to be discovered during execution
4. The task involves high-risk changes requiring adaptive risk mitigation

四、代码可查性分析

文件名 核心内容 决策逻辑位置
workflow-decisioner.ts 任务分解策略决策器 decideWorkflow() 函数
system-prompt.txt 系统提示词 第45-67行：策略选择规则
prompt-chain-executor.ts 固定链执行器 executePromptChain() 函数
dynamic-decomposer.ts 动态分解器 dynamicDecompose() 函数
task-analyzer.ts 任务特征提取器 extractTaskFeatures() 函数

五、决策逻辑与 CCA 认证的关联（考试核心考点）

  1. 选择依据：固定流程用 Prompt Chaining，未知探索用 Dynamic Decomposition（口诀）
  2. 注意力管理：大型代码评审必须采用「单文件分析→跨文件集成」两步拆分，避免注意力稀释
  3. 自适应价值：Dynamic Decomposition 能自动处理依赖、优先高影响区，适合开放式任务
  4. 合规场景：高合规要求任务必须用 Prompt Chaining（确定性优先），避免动态分解的不确定性

六、总结

Claude Code 的任务分解决策并非黑盒，而是基于任务可预测性的明确判断流程。通过泄露的源码和系统提示，我们能清晰看到：当任务步骤固定、信息完备时，采用 Prompt Chaining 保证效率与确定性；当任务需要探索、依赖动态发现时，采用 Dynamic Decomposition 保证全面性与适应性。这一决策逻辑是 CCA 认证中「任务分解策略设计」的核心考点，必须深入理解并能在实操中应用。

7. Manage session state, resumption, and forking

Task Statement 1.7 详解：Claude Code 会话状态管理（恢复/分叉/有效性）

这是 CCA 认证实操必考模块，聚焦 Claude Code 的会话生命周期管理，解决「长期任务中断恢复」「多方案并行探索」「代码变更后会话有效性」三大核心问题。
我会结合 2026 最新版 Claude Code + 官方泄露源码（session-manager.ts） 完整解析，附带实战命令、场景示例、源码逻辑，完全匹配你的学习需求。

核心定位

会话状态管理是 Claude Code 处理长期、复杂、多分支工程任务的基础能力：

  • 持久化保存对话、工具调用结果、代码分析快照
  • 支持中断恢复、并行探索
  • 严格校验上下文有效性，避免 AI 幻觉

一、核心知识点（Knowledge）| 理论基础

1. 命名会话恢复：--resume <session-name>
  • 定义：Claude Code 支持命名持久化会话，所有上下文自动保存到本地，通过固定命令恢复
  • 命令：claude --resume 会话名称
  • 泄露源码实现：
    会话存储在 ~/.claude/sessions/{name}.json，由 SessionManager.loadSession() 加载完整状态（工具结果、文件分析、对话历史）
  • 作用：跨终端、跨天数继续未完成的任务（代码审计、大型重构）
2. fork_session：会话分叉（并行探索）
  • 定义：从当前分析基线创建完全独立的会话分支，分支之间互不干扰、不共享数据
  • 核心价值：同一套代码，并行测试不同技术方案（重构策略、测试方案、修复思路）
  • 泄露源码逻辑：forkSession() 会深拷贝原会话的所有状态，生成全新独立会话
  • 关键：分叉后修改分支，不会影响原始会话
3. 恢复会话的强制规则：必须告知文件变更
  • 原理：会话保存的是历史代码快照/工具结果，如果本地代码被修改，Agent 会使用过时数据推理，直接导致错误/幻觉
  • 泄露源码：内置 fileHashTracker，存储所有分析文件的 SHA256 哈希值，恢复时自动对比校验
  • 硬性要求：代码修改后恢复会话，必须显式告诉 AI 哪些文件变了
4. 过时上下文：新建会话 + 总结 > 恢复旧会话
  • 场景：代码大量重构、间隔数天、依赖库更新 → 原会话工具结果完全失效
  • 结论：这种情况下不要恢复会话
  • 最优方案：新建会话 + 注入结构化总结（无过时上下文污染，推理更准确）

二、核心技能（Skills）| 实操+考试重点

结合实战命令、泄露源码、使用场景逐一讲解：

技能 1：使用 --resume 跨工作时段恢复会话

实战命令
## 1. 创建新命名会话（自动持久化保存）
claude --session legacy-code-audit

## 2. 关闭终端、隔天之后，直接恢复会话
claude --resume legacy-code-audit
适用场景

分多天完成的代码审计、分步重构、渐进式测试编写

所有分析结果、对话、工具调用都会被保存，无需重复工作

技能 2：使用 fork_session 创建并行探索分支

核心场景

同一套代码基线，同时验证 2 种不同方案（不用重复分析基础代码）
例：对比「单元测试方案」和「集成测试方案」

实战流程
## 1. 基础会话：完成代码结构分析（公共基线）
claude --session test-baseline

## 2. 分叉出分支1：专注单元测试
claude --resume test-baseline --fork-session --session unit-test-strategy

## 3. 分叉出分支2：专注集成测试
claude --resume test-baseline --fork-session --session integration-test-strategy
泄露源码核心实现（session-manager.ts）
// 官方泄露：会话分叉核心逻辑（深拷贝，完全独立）
async function forkSession(baseSessionName: string, newSessionName: string): Promise<Session> {
  // 加载基础会话状态
  const base = await this.loadSession(baseSessionName);
  // 深拷贝：创建独立副本，分支之间无任何数据共享
  const forkedState = JSON.parse(JSON.stringify(base.state));
  // 生成新会话并保存
  const newSession = new Session(newSessionName, forkedState);
  await this.saveSession(newSession);
  return newSession;
}

技能 3：决策：恢复会话 OR 新建会话

考试必考决策树
是否恢复会话？
├─ 是：本地文件无修改 / 少量修改 → 使用 --resume
└─ 否：代码大量重构 / 间隔超过3天 / 依赖更新 → 新建会话 + 注入总结
示例：过时上下文处理

❌ 错误：恢复3天前的会话，期间代码已经重构5次
✅ 正确：新建会话，粘贴结构化总结：

之前我分析了 user-service 模块，发现权限校验漏洞；代码已完成重构，请基于最新版本重新分析。

技能 4：恢复会话时，精准告知文件变更（增量重分析）

核心操作

不用让 AI 全量重新分析，只告知变更文件，高效更新上下文：

## 恢复会话后直接发送：
I modified src/user-service.js and src/auth.js. Please re-analyze ONLY these two files and update the audit report.
泄露源码：文件变更哈希校验
// 官方泄露：文件变更检测逻辑
async function hasFileChanged(filePath: string, storedHash: string): Promise<boolean> {
  const currentHash = await computeFileSHA256(filePath);
  // 对比哈希，判断文件是否被修改
  return currentHash !== storedHash;
}
优势

避免全量重分析，节省时间 + 精准更新上下文，杜绝幻觉

三、2026 最新版本关键增强

  1. 自动文件变更检测
    恢复会话时自动扫描文件哈希，主动提醒你哪些文件已修改
  2. 分叉会话合并
    支持将多个分支的结论合并回主会话
  3. 增量重分析自动化
    无需手动告知变更，AI 自动只重分析修改文件
  4. 会话状态压缩
    大型代码分析会话加载速度提升 50%

四、泄露源码可查核心文件

文件名 核心功能
session-manager.ts 会话加载、保存、分叉、删除
file-hash-tracker.ts 文件哈希计算 + 变更检测
session-validator.ts 会话新鲜度/有效性校验

五、CCA 认证考试必背速记

  1. --resume <name>：命名会话恢复，用于跨时段持续任务
  2. fork_session：创建独立分支，用于并行探索多方案
  3. 黄金规则：恢复会话必须校验文件变更，显式告知 AI
  4. 有效性决策：上下文有效 → 恢复；结果过时 → 新建+总结
  5. 最优实践：文件变更后只重分析修改文件，不做全量扫描

六、完整实战场景（端到端示例）

大型项目代码审计（3天完成 + 双重构方案对比）

  1. Day 1：启动命名会话，完成代码基线分析 
    claude --session big-project-audit
  2. Day 2：恢复会话，分叉2个重构分支 
    claude --resume big-project-audit --fork-session --session refactor-strategy-1
claude --resume big-project-audit --fork-session --session refactor-strategy-2
  3. Day 3：修改了2个核心文件，恢复主会话并告知变更 
    claude  --resume big-project-audit
# 发送：I updated src/core.js and src/api.js. Re-analyze these files only.
  4. 最终：合并分叉结论，生成最终审计报告
# AIGC # 数据库
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

大模型入门-应用篇5-亿级向量的快速检索

avatar AtomGit开源社区
cover

大模型入门-应用篇4-Deep Research

avatar AtomGit开源社区

2026年Dify搭建AI编程助手实战：零成本方案的完整配置教程

Dify是一个开源的LLM应用开发平台。配合DeepSeek的API，你可以搭建一个专属的AI编程助手，成本几乎为零。我用这个方案已经跑了2个月，总花费不超过$3。这篇文章把完整的搭建过程分享出来。

avatar AtomGit开源社区