图示体系规划

本文件用于规划《Anthropic Engineering 学习指南》的 Mermaid / draw.io 图示体系。目标是让整本书形成统一视觉语言，而不是每章零散画图。

一、图示原则

1. 每章至少一张核心图：解释本章最重要的工程结构或流程。
2. 每部分至少一张总览图：帮助读者建立阶段性认知。
3. 优先 Mermaid：便于版本管理和 Markdown 阅读。
4. 复杂总架构可后续转 draw.io：企业平台总图、Runtime 总图可以后续绘制 draw.io。
5. 图必须服务文字：不要为画图而画图，每张图都要在正文中解释。
6. 统一命名：chapter-XX-topic.mmd。

二、全书核心图清单

0. 前言 / 全书结构图

文件：

diagrams/chapter-00-book-structure.mmd

内容：

Book Goal → Six Parts → CI Failure Analysis Agent → Java / Spring Boot Mapping

用途：前言、全书结构说明。

优先级：高。

0. 全书总览图

文件：

diagrams/book-overview.mmd

内容：

Prompt → Workflow → Agent → Context → Tool → Skill → Harness → Memory → MCP → Multi-Agent → Runtime → Enterprise Platform

用途：README、前言、课程导读。

优先级：高。

第一部分：AI Agent 工程基础

第一部分总览图

文件：

diagrams/part-01-agent-engineering-overview.mmd

内容：

Why Agent → Workflow vs Agent → Agentic Coding → CI Failure Analysis Agent

优先级：高。

第 1 章：为什么需要 Agent

文件：

diagrams/chapter-01-agent-basic-loop.mmd

图示：Agent 基本循环。

User Task → Plan → Tool Call → Observation → Reflect → Continue / Done

优先级：高。

第 2 章：Workflow 与 Agent 的边界

文件：

diagrams/chapter-02-workflow-vs-agent.mmd

图示：Prompt / Workflow / Agent 判断树。

一次调用能否完成？
流程是否固定？
是否需要动态决策？

优先级：高。

第 3 章：Claude Code 的工程思想

文件：

diagrams/chapter-03-agentic-coding-loop.mmd

图示：Explore → Plan → Code → Test → Fix → Summary。

优先级：高。

第二部分：Context Engineering

第二部分总览图

文件：

diagrams/part-02-context-engineering-overview.mmd

内容：

Context Collection → Selection → Compression → Isolation → Injection

优先级：高。

第 4 章：从 Prompt Engineering 到 Context Engineering

文件：

diagrams/chapter-04-context-layer.mmd

图示：Context Layer 基本架构。

优先级：高。

第 5 章：Context 的组成

文件：

diagrams/chapter-05-context-components.mmd

图示：System Prompt、Task、Conversation、Tool Results、Memory、Code、Git、Policy 等组成。

优先级：高。

第 6 章：Context Selection

文件：

diagrams/chapter-06-context-selection-pipeline.mmd

图示：Candidate Recall → Permission Filter → Scoring → Dedup → Budget Packing → Render。

优先级：高。

第 7 章：Context Compression

文件：

diagrams/chapter-07-context-compression.mmd

图示：Raw Context → Type-specific Compressor → Compressed Context → References。

优先级：中高。

第 8 章：Context Isolation

文件：

diagrams/chapter-08-context-isolation.mmd

图示：Shared Workspace + Private Scratchpads。

优先级：高。

第三部分：Tool 与 Skill Engineering

第三部分总览图

文件：

diagrams/part-03-tool-skill-overview.mmd

内容：

Tool = action
Skill = procedure
Project Knowledge = project-specific instruction

优先级：中高。

第 9 章：Tool Engineering

文件：

diagrams/chapter-09-tool-registry.mmd

图示：Agent → ToolRegistry → Permission Check → ToolExecutor → External System → ToolResult。

优先级：高。

第 10 章：Tool Orchestration

文件：

diagrams/chapter-10-tool-orchestration.mmd

图示：ToolPlanner → Sequential / Parallel / Batch Executor → Aggregator → Context Compressor。

优先级：高。

第 11 章：Agent Skills

文件：

diagrams/chapter-11-skill-progressive-disclosure.mmd

图示：Skill Metadata → SKILL.md → Resources / Examples / Scripts。

优先级：高。

第 12 章：Project Knowledge

文件：

diagrams/chapter-12-project-knowledge-loader.mmd

图示：README / AGENTS.md / Build files / docs → RepositoryProfile → Context。

优先级：中高。

第四部分：Harness 与 Memory Engineering

第四部分总览图

文件：

diagrams/part-04-harness-memory-overview.mmd

内容：

Harness controls loop
Memory stores long-term context outside window

优先级：中高。

第 13 章：Harness Engineering

文件：

diagrams/chapter-13-harness-loop.mmd

图示：Initialize → Plan → Act → Observe → Verify → Recover / Checkpoint。

优先级：高。

第 14 章：Long-running Agent

文件：

diagrams/chapter-14-long-running-state-machine.mmd

图示：Created → Initializing → Planning → Executing → Verifying → Checkpointing → Completed / Paused / Failed。

优先级：高。

第 15 章：Memory Engineering

文件：

diagrams/chapter-15-memory-lifecycle.mmd

图示：Agent Event → Worth Remembering → Memory Store → Retrieval → Context。

优先级：高。

第 16 章：Memory Retrieval 与 Governance

文件：

diagrams/chapter-16-memory-governance.mmd

图示：Scope Filter → Permission Filter → Retrieval → Conflict Resolution → Audit。

优先级：中高。

第五部分：MCP 与 Multi-Agent

第五部分总览图

文件：

diagrams/part-05-mcp-multi-agent-overview.mmd

内容：

MCP connects external systems
Multi-Agent coordinates multiple context windows and roles

优先级：中高。

第 17 章：MCP

文件：

diagrams/chapter-17-mcp-context-provider.mmd

图示：Agent Runtime → MCP Client → MCP Servers → Enterprise Systems。

优先级：高。

第 18 章：Multi-Agent System

文件：

diagrams/chapter-18-multi-agent-research.mmd

图示：Coordinator → Planner → Subagents → Synthesizer → Reviewer。

优先级：高。

第 19 章：Multi-Agent Context Sharing

文件：

diagrams/chapter-19-multi-agent-context-sharing.mmd

图示：Global Context / Role Context / Private Context / Shared Workspace / Artifact Store。

优先级：高。

第六部分：企业级 Agent Runtime

第六部分总览图

文件：

diagrams/part-06-enterprise-runtime-overview.mmd

内容：

Runtime + Managed Agents + Enterprise Platform + Java Framework

优先级：高。

第 20 章：Agent Runtime

文件：

diagrams/chapter-20-agent-runtime.mmd

图示：API → Runtime Core → Context / Tool / Skill / Memory / Event / Security。

优先级：高。

第 21 章：Managed Agents

文件：

diagrams/chapter-21-managed-agents-brain-hands-session.mmd

图示：Brain ↔ Hands，Brain / Hands → Session Event Log。

优先级：高。

第 22 章：企业 Agent 平台架构

文件：

diagrams/chapter-22-enterprise-agent-platform.mmd

图示：User Interface → API Gateway → Agent Runtime → Context / Tool / Skill / Memory / MCP / Security / Observability。

优先级：高。

第 23 章：Java / Spring Boot Agent Framework

文件：

diagrams/chapter-23-java-agent-framework-modules.mmd

图示：agent-api、agent-core、agent-runtime、agent-context、agent-tool、agent-skill、agent-memory、agent-harness、agent-mcp。

优先级：高。

三、贯穿案例图

CI 失败分析 Agent 总图

文件：

diagrams/case-ci-failure-agent-overview.mmd

内容：

CI Failure Event → Agent Runtime → Context Manager → Tool Orchestrator → Harness → Report

优先级：高。

CI 失败分析工具编排图

文件：

diagrams/case-ci-failure-tool-plan.mmd

内容：

summarize_ci_failure + get_git_diff + get_project_instructions 并行
→ search_code
→ read_file_range
→ aggregate report

优先级：高。

CI 失败分析上下文图

文件：

diagrams/case-ci-failure-context.mmd

内容：

User Task + CI Summary + Git Diff + AGENTS.md + Memory + Code Snippets → Context Window

优先级：高。

四、建议优先绘制顺序

第一批必须完成（已完成）：

book-overview.mmd
chapter-02-workflow-vs-agent.mmd
chapter-04-context-layer.mmd
chapter-09-tool-registry.mmd
chapter-13-harness-loop.mmd
chapter-20-agent-runtime.mmd
chapter-22-enterprise-agent-platform.mmd
case-ci-failure-agent-overview.mmd

第二批（已完成）：

chapter-06-context-selection-pipeline.mmd
chapter-07-context-compression.mmd
chapter-11-skill-progressive-disclosure.mmd
chapter-15-memory-lifecycle.mmd
chapter-17-mcp-context-provider.mmd
chapter-18-multi-agent-research.mmd
chapter-21-managed-agents-brain-hands-session.mmd
chapter-23-java-agent-framework-modules.mmd

第三批（已完成）：补齐所有剩余章节图与各部分总览图。

chapter-00-book-structure.mmd
chapter-01-agent-basic-loop.mmd
chapter-03-agentic-coding-loop.mmd
chapter-05-context-components.mmd
chapter-08-context-isolation.mmd
chapter-10-tool-orchestration.mmd
chapter-12-project-knowledge-loader.mmd
chapter-14-long-running-state-machine.mmd
chapter-16-memory-governance.mmd
chapter-19-multi-agent-context-sharing.mmd
part-01-agent-engineering-overview.mmd
part-02-context-engineering-overview.mmd
part-03-tool-skill-overview.mmd
part-04-harness-memory-overview.mmd
part-05-mcp-multi-agent-overview.mmd
part-06-enterprise-runtime-overview.mmd

当前 Mermaid 图已经覆盖：前言、第 1～23 章、六个部分总览和贯穿案例。

五、Mermaid 风格约定

推荐：

源文件：diagram-style-example.mmd

约定：

• 流程图默认 flowchart TD；
• 对比关系可用 flowchart LR；
• 状态机用 stateDiagram-v2；
• 调用链用 sequenceDiagram；
• 节点文字尽量短；
• 不在图中放大段解释；
• 图后正文解释关键路径。

六、后续 draw.io 候选图

以下图后续适合转为 draw.io，用于正式发布或演示：

enterprise-agent-platform.drawio
agent-runtime-architecture.drawio
managed-agents-brain-hands-session.drawio
ci-failure-agent-case-study.drawio
java-agent-framework-modules.drawio

当前阶段先用 Mermaid。