AI Coding Agent
底层实现原理

基于 Amazon Q Developer CLI/Kiro-CLI (Rust) 与 Claude Code (TypeScript/Python)
两大开源项目的源码级深度分析

按 ← → 键或点击箭头翻页 · 点击 ▼ 展开详情

OVERVIEW

议程概览

从源码视角解构 AI Coding Agent 的核心设计

1

架构对比
Rust vs TypeScript 两种范式

2

Agent Loop
核心循环 · 状态机 · 流式解析

3

工具系统
Tool Use 的完整执行管道

4

Prompt 工程
分层 Prompt · 上下文管理

5

MCP 协议
工具扩展的事实标准

6

安全模型
四层防御 · Hook 规则引擎

7

插件体系
五维扩展 · Hook 生命周期

8

终端渲染
用户体验 · 输出风格

9

设计原则
七大共性原则总结

10

为何能高质量开发
架构保障质量的底层逻辑

ARCHITECTURE

架构对比分析

两种技术路线，殊途同归的核心范式

🦀

Amazon Q Developer CLI
RustTokio AsyncActor Model

🤖 Agent Loop 状态机 · 6 种显式状态转换
🔧 10+ 内置工具 (fs_read/write, bash, grep, glob…)
🔐 三级权限模型 (Allow / Ask / Deny)
🔌 MCP 集成 + Hook 脚本扩展

🟦

Claude Code
TypeScriptPython 插件Markdown 配置

🤖 Agent Loop 事件驱动 · 多 Agent 并行协作
🔧 内置工具 + 插件可声明自定义工具
🔐 Hook 声明式安全策略 · 9 种事件拦截
🧩 5 种扩展点 (Command / Agent / Skill / Hook / MCP)

维度	Amazon Q CLI	Claude Code
实现语言	Rust（编译时安全、零成本抽象）	TypeScript 核心 + Python 插件
架构模式	单体 Agent + Actor 消息传递💡 这里的 Actor 就是把 Agent 内部的功能模块当作独立的"小演员"，它们各自干各自的活，需要协作时就互相发消息，而不是直接调用对方的方法或共享数据。	核心引擎 + 插件生态
LLM 通信	AWS SDK Streaming (CodeWhisperer API)	Anthropic API (SSE)
工具执行	内置 Rust 原生 + MCP 工具	内置 + MCP 工具
并发模型	Tokio async + FuturesUnordered💡 类比 JS：FuturesUnordered ≈ Promise.all() 但流式逐个返回结果，且 Rust 编译器在编译期就杜绝了并行任务间的数据竞争。	Node.js 事件循环 + 子进程
状态管理	SQLite + 内存状态机 (6 种状态)	文件系统 + 会话状态

CORE MECHANISM

Agent Loop — 核心执行循环

AI Coding 最核心的设计模式：LLM 与工具的交互闭环

🔄 循环控制模型对比 — 状态机 vs 事件驱动 ▼

🦀 Q Developer — 显式有限状态机

6 种状态 + 编译时穷举检查，状态转换由 match 驱动

🟦 Claude Code — 事件驱动 + 多 Agent

9 种 Hook 事件，插件可注入任意生命周期节点

核心差异：Q Developer 用编译时类型安全的状态机，所有转换路径在代码中穷举；Claude Code 用事件驱动模型，插件通过声明式 JSON 注册 Hook，可在不修改核心代码的情况下扩展循环行为。两者都支持 Pre/Post Hook 拦截工具执行。

📡 流式解析与 LLM 通信对比 ▼

🦀 Q Developer — AWS SDK Streaming

LLM 流式输出

→

累积文本块

→

实时渲染到终端

检测 tool_use

→

增量 JSON 解析

→

提取工具名+参数

→

触发工具执行

Model trait 返回 Stream（非 Future）→ 逐 chunk 流式处理；内置 CancellationToken 支持用户随时 Ctrl+C 中断

🟦 Claude Code — Anthropic API (SSE)

Anthropic SSE

→

事件流解析

→

渲染 / Tool Use 分流

→

Hook 链 → 执行

共同点：都采用流式处理（非等待完整响应），都支持中途取消。
差异：Q Developer 用 AWS SDK 私有协议 + Rust async Stream；Claude Code 用标准 SSE (Server-Sent Events) + Node.js 事件循环。Claude Code 的 Hook 链在工具执行前后可被插件拦截和修改。

🤖 多 Agent 协作模型对比 ▼

🦀 Q Developer — 单 Agent + Subagent 委派

✅ 主 Agent 通过 delegate 工具委派子任务
✅ 每个 Agent 同时只能执行一个任务
✅ 每个 Subagent 有独立上下文，避免主对话膨胀
✅ Agent 配置文件定义不同角色（.amazonq/cli-agents/）

🟦 Claude Code — 插件定义专业 Agent

✅ 插件通过 agents/ 目录声明专业 Agent
✅ 多 Agent 并行协作（如 code-review 4 路并行审查）
✅ Agent 间通过文件系统 + worktree 隔离协调
✅ SubagentStop Hook 确保子任务完成质量

共同点：都支持主 Agent 委派子任务并行执行，子 Agent 有独立上下文。
差异：Q Developer 的 Subagent 是内置机制；Claude Code 的 Agent 通过插件声明式定义，可携带专属工具、Prompt 和 Hook，扩展性更强。

📜 对话历史管理 — Q Developer 5 大不变量 ▼

✅ 不变量 1: 历史必须以 user 消息开头（不能以 tool_result 开头）
✅ 不变量 2: user / assistant 消息严格交替
✅ 不变量 3: 每个 tool_use 必须有对应的 tool_result
✅ 不变量 4: 缺失的 tool_result 自动补 "cancelled" 占位符
✅ 不变量 5: 无效 tool name 替换为 dummy tool spec

Q Developer 最大历史: MAX_CONVERSATION_STATE_HISTORY_LEN = 500 条消息

Claude Code 通过 PreCompact Hook 可自定义压缩策略（详见 Slide 6）

↕ 滚动查看更多

TOOL SYSTEM

工具系统架构

让 LLM 从"只能说话"变成"能做事"的关键

🦀 Q Developer — 内置工具集（Rust 原生实现）

🟦 Claude Code — 内置 + 插件可扩展工具

📖

FsRead
行范围 · 编码检测

✏️

FsWrite
create / strReplace

⚡

ExecuteCmd
Bash · "最后手段"

🔍

Grep / Ls
搜索 · 目录列表

🔧 内置工具：Read, Edit, Write, Bash, Glob 等
🧩 插件通过 skills/ 注入专业能力（如前端设计、代码审查）
🔌 MCP Server 提供外部工具（与 Q Developer 相同协议）
🪝 PreToolUse Hook 可拦截/修改任意工具调用

差异：Q Developer 工具集固定在编译时；Claude Code 工具可通过插件动态扩展

🔧 工具执行管道对比 — 从调用到结果 ▼

🦀 Q Developer — 8 步管道

① 名称解析

→

② Schema 验证

→

③ 语义验证

→

④ 权限评估

⑤ Pre-Hook

→

⑥ 执行工具

→

⑦ Post-Hook

→

⑧ 格式化结果

名称解析: CanonicalToolName 映射 (如 "file_read" → "FsRead")
语义验证: canonicalize_path_sys() 防止路径遍历攻击
权限评估: Allow / Ask / Deny 三级模型

🟦 Claude Code — Hook 驱动管道

① 工具匹配

→

② PreToolUse Hook

→

③ 权限判定

④ 执行工具

→

⑤ PostToolUse Hook

→

⑥ 注入结果

工具匹配: 内置工具 + 插件注册 + MCP Server 工具
Hook 拦截: PreToolUse 可用 prompt 或 command 两种方式验证
权限判定: Hook exit code 控制（0=允许, 2=阻止并告知 LLM）

🎯 工具行为引导对比 — 让 LLM "三思而后行" ▼

🦀 Q Developer: __tool_use_purpose

const TOOL_USE_PURPOSE_FIELD_NAME: &str = "__tool_use_purpose"; // 每次工具调用必须附带意图说明 // → 可解释性 + 行为约束 + 审计追踪

🟦 Claude Code: Skill 注入专业 Prompt

# skills/code-review/SKILL.md # 通过 YAML frontmatter 声明触发条件 # 匹配时自动注入专业指导到 Prompt # → 引导 LLM 按特定流程使用工具

共同思路：都通过 Prompt 层面引导 LLM 的工具使用行为，而非仅靠硬编码限制。Q Developer 在每次调用时强制声明意图；Claude Code 通过 Skill 在上下文中注入领域知识。

⚡ 并行工具执行对比 ▼

🦀 Q Developer: TaskExecutor + FuturesUnordered

Rust async 并行，编译时保证线程安全

🟦 Claude Code: 子进程 + 多 Agent 并行

Node.js 子进程并行，Agent 间 worktree 隔离

💡 关键洞察：工具描述就是 Prompt — 两者都通过自然语言描述引导 LLM 的工具选择行为（如 ExecuteCmd 写着 "Use only as a last-resort"）

↕ 滚动查看更多

PROMPT ENGINEERING

分层 Prompt 与上下文管理

Context Window 是 AI Coding 最核心的稀缺资源

🦀 Q Developer — 五层 Prompt 架构

Layer 5: 当前用户消息 + 附加上下文（文件/图片）

Layer 4: 对话历史 (user/assistant 严格交替)

Layer 3: 工具规格 (name + description + JSON Schema)

Layer 2: Context Entries (MCP / Hook / 资源文件)

Layer 1: Base System Prompt (角色 / 能力 / 风格)

Context Entry 格式：以 --- CONTEXT ENTRY BEGIN/END --- 包裹，注入时间、OS、CWD 等环境信息

🟦 Claude Code — 插件注入式 Prompt

System Prompt + CLAUDE.md 项目规则

SessionStart Hook 注入初始上下文

Skills 按需自动加载领域知识

Agent 定义专属 System Prompt

对话历史 + 工具规格 + MCP 资源

核心差异：Q Developer 的 Prompt 层次在代码中硬编码；Claude Code 的每一层都可被插件动态注入和修改（SessionStart Hook、Skills、Agent 定义）

🧠 Context Window 管理策略对比

🦀 Q Developer

📦 自动压缩 (Compact) ▼

上下文溢出时，调用 LLM 对历史对话生成摘要：
100 条消息 (200K tokens) → 摘要 (~2K) + 最近 20 条 ≈ 30K tokens

✂️ 消息截断 + 历史裁剪 ▼

超大工具输出截断：[前 10000 字符]...truncated
保留最近消息，维护 tool_use/tool_result 配对完整性
MAX_RESOURCE_FILE_LENGTH = 10KB

🟦 Claude Code

📦 PreCompact Hook 可定制压缩 ▼

压缩前触发 PreCompact Hook，插件可自定义哪些信息必须保留
例如：保留关键架构决策、保留未完成的 TODO 列表

🧩 Skills 按需加载 ▼

Skill 只在任务上下文匹配 description 时才加载，避免无关知识占用窗口
例如：只有涉及前端时才加载 frontend-design Skill

终端 Prompt 使用率提示 (Q Developer): [default] 42% > _ ← Context Window 使用率 · [default] 85% !> _ ← ⚠️ 考虑 /clear 或 /compact

EXTENSIBILITY

MCP — 工具扩展的事实标准

Model Context Protocol: 两个项目共同采用的工具互操作协议

🏷️ 配置与命名空间对比 ▼

🦀 Q Developer:

命名空间：@builtin/ · @github-tools/
优先级：Agent Config > Workspace > Global
配置：.amazonq/mcp.json

🟦 Claude Code:

插件声明：.claude-plugin/plugin.json
支持 mcpServers 字段声明 Server
配置：JSON 声明式，插件自动注册

共同点：都支持 stdio 和 HTTP 两种传输方式，都支持 tools/list_changed 动态刷新。
差异：Q Developer 用 Actor 模型管理每个 MCP Server 的生命周期和并发；Claude Code 通过插件 JSON 声明式配置，更简洁但灵活性依赖插件体系。

SECURITY

安全与权限模型

安全是架构级关注点，不是事后补丁 — 多层纵深防御

🛡️ Amazon Q CLI 四层防御

Layer 4: Hook Validation
PreToolUse Hook 脚本可阻止任何工具执行

Layer 3: User Approval
敏感操作需要用户交互确认

Layer 2: Path Permissions
Allow/Deny glob 模式 · Deny 始终优先

Layer 1: Tool Allowlist
Agent 配置中的 allowed_tools 白名单

enum PermissionEvalResult { Allow, // 直接执行，无需确认 Ask, // 需要用户交互确认 Deny, // 拒绝 + 原因返回给 LLM }

🛤️ 路径安全 — canonicalize_path_sys ▼

/home/user/../etc/passwd → /etc/passwd → ❌ Deny
./src/../../secrets → /secrets → ❌ Deny
/home/user/project/src → ✅ Allow

🪝 Claude Code Hook 安全体系

🔒 security-guidance — 9 种安全模式检测 ▼

⚠️ XSS 跨站脚本 · ⚠️ eval() 动态执行 · ⚠️ dangerouslySetInnerHTML
⚠️ document.write · ⚠️ innerHTML 注入 · ⚠️ new Function() 注入
⚠️ pickle 反序列化 · ⚠️ os.system() · ⚠️ child_process 命令注入
仅拦截 Edit|Write|MultiEdit，不影响其他工具性能

⚙️ Hookify 规则引擎 — 用户可配置的安全策略 ▼

# .claude/hookify.block-rm.local.md --- name: block-dangerous-rm enabled: true event: bash action: block conditions: - field: command operator: regex_match pattern: rm\s+-rf\s+/ --- ⚠️ 检测到危险的 rm 命令，已阻止执行。

操作符: regex_match (LRU 缓存) · contains · not_contains · equals · starts_with · ends_with
字段: command · file_path · new_text · user_prompt · transcript

EXTENSIBILITY

插件与扩展体系

两种扩展哲学：Q Developer 配置驱动 vs Claude Code 插件生态

🦀 Q Developer — 三种扩展方式

🤖

Agent 配置 — JSON 定义角色
.amazonq/cli-agents/ · prompt · allowedTools · MCP

🪝

Hook 脚本 — Pre/Post 工具拦截
preToolUse · postToolUse · agentSpawn · exit code 控制

🔌

MCP Server — 外部工具服务
.amazonq/mcp.json · stdio/HTTP · Actor 模型管理

设计哲学：编译时确定核心能力，运行时通过配置文件和 MCP 扩展。扩展点少但每个都深度集成。

🟦 Claude Code — 五种扩展点

⌨️

Commands — 斜杠命令
/feature-dev · /code-review · /hookify

🤖

Agents — 专业化子 Agent
code-explorer · code-reviewer · code-architect

📚

Skills — 知识模块 (上下文自动加载)
frontend-design · writing-rules

🪝

Hooks — 9 种事件钩子
PreToolUse · PostToolUse · Stop · SessionStart...

🔌

MCP — 外部工具服务器
plugin.json 声明 · 自动启动

🦀 Q Developer Agent 配置示例 ▼

配置路径：.amazonq/cli-agents/reviewer.json
可定义：name · prompt · allowedTools 白名单 · hooks（preToolUse / postToolUse 拦截）

🟦 Claude Code 9 种 Hook 事件一览 ▼

工具生命周期：
🪝 PreToolUse — 工具执行前拦截/修改
🪝 PostToolUse — 工具执行后审计/补充
🛑 Stop — Agent 停止前触发
🛑 SubagentStop — 子 Agent 完成时触发

会话生命周期：
🟢 SessionStart — 注入初始上下文
🔴 SessionEnd — 清理/持久化
💬 UserPromptSubmit — 用户输入预处理
📦 PreCompact — 压缩前保留关键信息
📢 Notification — 自定义通知

完整事件流图详见 Slide 4「循环控制模型对比」

🟦 feature-dev 7 阶段工作流 — Claude Code 插件实战 ▼

① Discovery

→

② Explore

→

③ Clarify

→

④ Design

→

⑤ Implement

→

⑥ Review

→

⑦ Complete

Phase 2 并行启动 2-3 个 code-explorer Agent 探索代码库

STREAMING

终端渲染与用户体验

流式解析之后的最后一公里：如何让用户感受到"实时对话"

🦀 Q Developer — crossterm 终端控制 + Markdown 语法高亮 + Spinner 动画

🟦 Claude Code — Node.js 终端渲染 + 插件可自定义输出风格 (explanatory / learning)

💡 渲染层的差异化：Q Developer 用 crossterm💡 Rust 的终端控制库，直接操控光标位置、文字颜色、清屏刷新等，类似在终端里"画 UI"。精确控制终端光标和颜色；Claude Code 通过 SessionStart Hook💡 会话开始时触发的钩子，插件可在此注入内容到 system prompt，从而改变 AI 整个会话的输出风格。插件可改变输出风格（如 explanatory-output-style💡 让 AI 回复自动附带更详细的解释说明，适合需要理解"为什么"的场景。插件增加教学性解释，learning-output-style💡 让输出带有学习引导风格，比如"你可以试试…"这种语气，适合新手学习。插件增加学习引导）

SUMMARY

七大共性设计原则

两个项目从不同技术栈出发，殊途同归的核心范式

原则 1: LLM 作为决策中心，工具作为执行手臂
LLM 不直接操作系统，通过结构化 Tool Use 间接操作，所有操作可审计、可拦截、可回滚

原则 2: 流式处理优先
不等完整响应，增量解析 + 实时渲染，用户体验接近实时对话

原则 3: 安全是架构级关注点
从工具定义、路径验证、Hook 拦截到用户确认的完整链路，多层纵深防御

原则 4: Context Window 是稀缺资源
自动压缩、消息截断、历史裁剪——所有设计围绕"有限窗口内塞入最有价值的信息"

原则 5: 工具描述即 Prompt
工具 description 不是给人看的文档，而是给 LLM 看的行为指令，直接决定 Agent 表现

原则 6: 可扩展性通过 MCP 标准化
MCP 是 AI Coding 工具互操作的事实标准，解耦 Agent 核心与工具实现

原则 7: 结构化对话管理
不是简单的 request-response，而是通过状态机（Q Developer 6 种状态）或事件驱动模型（Claude Code 9 种 Hook）管理对话生命周期，处理取消、超时、权限请求、错误恢复等所有边界情况

WHY IT WORKS

为何这种设计能完成高质量代码开发？

从架构原理看 AI Coding Agent 的质量保障机制

🧠 为什么 LLM + Tool Use 比纯生成更可靠？ ▼

纯 LLM 生成的问题：凭"记忆"写代码，无法验证文件是否存在、API 是否正确、依赖是否匹配

Tool Use 模式的优势：
1️⃣ 先读后写 — LLM 先用 FsRead/Grep 读取现有代码，理解真实上下文后再修改，而非凭空生成
2️⃣ 即时验证 — 写完代码后可以用 ExecuteCmd 运行测试，发现错误立即修正
3️⃣ 增量修改 — strReplace 精确替换而非重写整个文件，保留原有代码结构
4️⃣ 上下文真实 — 通过工具获取的是文件系统的真实状态，不是 LLM 的"幻觉"

🔄 迭代循环如何保证最终质量？ ▼

关键：Agent Loop 不是一次性生成，而是多轮迭代

读取代码

→

分析理解

→

生成修改

→

写入文件

→

运行测试

→

发现错误

→

再次修正

每一轮工具执行的结果都会反馈给 LLM，LLM 根据真实的执行结果（而非猜测）决定下一步。
这种 "感知-决策-行动-反馈" 的闭环，本质上模拟了人类开发者的工作方式。

💡 核心结论：AI Coding Agent 的质量不来自"更聪明的模型"，而来自架构设计 — 通过 Tool Use 获取真实上下文、通过迭代循环自我修正、通过多层安全防止破坏性操作、通过 MCP 扩展专业能力。这套架构让 LLM 从"猜测式生成"进化为"验证式开发"。

↕ 滚动查看更多

THANK YOU

Thank You

AI Coding 的核心范式：
LLM Agent + Tool Use + Streaming + Safety Guardrails + MCP Extensibility

源码参考：
github.com/aws/amazon-q-developer-cli
github.com/anthropics/claude-code

AI Coding Agent底层实现原理

🦀 Q Developer — 五层 Prompt 架构

🟦 Claude Code — 插件注入式 Prompt

🧠 Context Window 管理策略对比

🛡️ Amazon Q CLI 四层防御

🪝 Claude Code Hook 安全体系

🦀 Q Developer — 三种扩展方式

🟦 Claude Code — 五种扩展点

Thank You

AI Coding Agent
底层实现原理