企业官网建设流程全解析

C4 Context 层架构文档化实战：用 c4-context Agent 绘制系统全景视图

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

导读

本文围绕 agents24 仓库中 c4-architecture 插件 的 c4-context Agent 展开，讲解如何在 C4 模型的自底向上文档化工作流中，完成最高层级的System Context（系统上下文）建模：识别角色与外部系统、绘制用户旅程、产出非技术利益相关者也能读懂的 Mermaid 系统上下文图，并完整落地为一份c4-context.md文档。读完本文，你将掌握该 Agent 的角色定位、六大能力维度、11 步响应流程、标准文档模板与 MermaidC4Context图画法，并能在真实代码库中调用它生成一份可复用的高层架构文档。

C4 模型与 Context 层：整个系统的一张"大图"

在 C4 模型（Context → Container → Component → Code 四个层级）中，System Context 是最顶层。按 c4-context Agent 的核心哲学描述，上下文图将"系统画成中央的一个方框"，四周环绕着它的用户，以及与之交互的其他软件系统——关注点是人（参与者、角色、用户画像）和软件系统，而不是技术、协议等低层细节。

这带来三个关键定位：

1. 系统边界：明确什么在系统内部、什么在系统外部；
2. 业务价值：说明系统解决什么业务问题、提供什么高层能力；
3. 受众：这份文档需要能被非技术人员（业务/管理利益相关者）理解，因为它提供的是整个系统的"全景视图"（big picture view）。

这也意味着，最详尽的架构细节（每个目录、类、函数怎么组织的）在 Code 层；Context 层恰恰相反——信息越抽象、越面向决策者越有价值。

认识 c4-context Agent：插件内的"最后一位玩家"

在仓库中，c4-architecture 插件把四个专业 Agent 与一个协调命令打包在一起：

从 c4-context.md 的 frontmatter 可以确认它的身份信息：name: c4-context、model: sonnet，description字段则充当激活条件——当用户要求"创建最高层级的 C4 系统上下文文档"时，调度器才会唤起它。这与仓库文档 agent-skills.md 描述的"YAML frontmatter 承载名称与激活条件"机制一致。

值得注意的模型分配：c4-code 使用haiku（量大但任务机械），而合成类的 c4-component、c4-container 与 c4-context 均使用sonnet（需要更强的分析综合能力），从侧面印证 Context 层合成工作的难度系数。

工作流定位：自底向上的最后一环

c4-context 在整条生成链路中处于最终步骤。整个工作流由 c4-architecture 命令 采用**自底向上（bottom-up）**的方式编排：

1. Phase 1（Code 层）：发现仓库全部子目录，按深度"最深优先"排序，过滤node_modules、.git、build、dist等非代码目录，为每个目录生成c4-code-<name>.md（含完整函数签名、依赖清单）；
2. Phase 2（Component 层）：把 code 文档按领域/技术/组织边界合成逻辑组件，产出c4-component-<name>.md与主索引c4-component.md；
3. Phase 3（Container 层）：结合 Dockerfile、K8s manifests、Terraform 等部署定义，把组件映射为可部署容器，并为每个容器接口生成 OpenAPI 3.1+ 规范，产出c4-container.md；
4. Phase 4（Context 层）：交给 c4-context，合成容器文档、组件文档、README、需求文档与测试文件，产出最终的系统上下文文档。

c4-context 的输入与输出

按 c4-context.md 的 Workflow Position，其衔接关系是：

• 前置依赖（After）：c4-Container 与 c4-Component Agent（它负责合成二者的产出）；
• 输入（Input）：容器文档、组件文档、系统文档（README、架构说明、需求/设计文档）、测试文件；
• 输出（Output）：c4-context.md——一份包含系统全景、角色、功能、用户旅程、外部依赖与上下文图的完整系统上下文文档。

一个容易忽略但很有价值的输入来源是测试文件：测试断言了什么行为，往往能反推系统"对外承诺了哪些能力"，这对识别高层特性、验证用户旅程的真实性很有帮助。在 c4-architecture 命令的配置项 中对应参数是include_tests（是否分析测试文件，默认true）。

一次调用的完整路径

在支持该插件的 IDE / 命令行 harness 中，用户只需要（详见 usage.md）：

# 斜杠命令形式 /c4-architecture:c4-architecture # 自然语言形式 "Create C4 architecture documentation for this codebase"

命令内部的编排顺序固定为c4-code → c4-component → c4-container → c4-context，最终全部文档写入仓库根目录新建的C4-Documentation/目录，结构如下（来自命令文档）：

C4-Documentation/ ├── c4-code-*.md # Code 级文档（每个目录一份） ├── c4-component-*.md # Component 级文档（每个组件一份） ├── c4-component.md # Master 组件索引 ├── c4-container.md # Container 级文档 ├── c4-context.md # Context 级文档 └── apis/ # API 规范 ├── [container]-api.yaml # 每个容器的 OpenAPI 规范 └── ...

值得说明：C4 官方观点是大多数团队只需要 Context 与 Container 两级图就够了。本工作流为了文档完备性四个层级全量生成，但具体团队可只选用其中需要的层级——这也是命令文档中明确声明的设计取舍。

六大能力维度：Context 层文档工程师的核心技能

c4-context Agent 的 Capabilities 章节将其能力组织为六个维度，覆盖了从"看懂系统"到"讲清给外人听"的完整链条：

1. 系统上下文分析（System Context Analysis）

• 系统识别：界定系统边界，说明系统做什么；
• 系统描述：编写系统目的与能力的短/长描述；
• 系统范围：分辨边界内外的内容；
• 业务上下文：理解系统解决的业务问题；
• 系统能力：记录系统提供的高层特性与能力。

2. 角色与用户识别（Persona and User Identification）

• 用户画像识别：找出所有与之交互的用户画像；
• 角色定义：界定用户角色及其职责；
• 参与者识别：同时识别人类用户与程序化"用户"（外部系统、API、服务——它们虽不是人，却是系统的真实使用者，是 Context 层最容易遗漏的部分）；
• 用户特征：记录用户需求、目标与交互模式；
• 用户旅程映射：为每个关键特性与角色绘制用户旅程。

3. 特性文档化（Feature Documentation）

• 识别系统提供的全部高层特性；记录每个特性做什么、谁在用；
• 理解特性优先级与特性间关系；
• 把特性映射到角色与用户旅程。

4. 用户旅程映射（User Journey Mapping）

• 为每个特性识别关键旅程；以步骤化方式记录用户旅程；
• 创建旅程可视化（映射图、流程图）；
• 记录程序化旅程（外部系统与 API 的调用旅程）——注意它和"人"的旅程分开对待；
• 把旅程映射到角色，并记录旅程中的所有系统触点（touchpoints）。

5. 外部系统文档化（External System Documentation）

• 识别全部外部系统、服务与依赖；
• 明确集成类型（API、事件、文件传输等）；
• 做依赖分析，理解关键依赖与集成模式；
• 记录与第三方服务、数据库、消息队列等的关系；
• 理清与外部系统间的数据流方向。

6. 上下文图与文档产出（Context Diagrams & Context Documentation）

• 用 Mermaid 生成 C4 规范的上下文图，展示系统、用户与外部系统及相互关系；
• 仅在确实相关时才标注技术（默认不放技术细节）；
• 产出对非技术利益相关者友好、格式一致的整套文档（系统总览、角色、特性、旅程、外部依赖、系统边界）。

行为特征：怎么"像一个优秀的架构写作者"那样工作

c4-context.md 用 Behavior Traits 定义了该 Agent 的工作风格，核心可概括为七条行为准则：

• 系统性：有条理地分析容器、组件与系统文档，先穷尽证据再下结论；
• 分层心智：始终聚焦高层系统理解，不沉溺于实现细节（那是 Code 层的活）；
• 双受众导向：产出对技术与非技术读者都友好的文档；
• 不遗漏程序化用户：主动识别所有"非人类参与者"；
• 旅程全覆盖：为所有关键特性写完整用户旅程；
• 依赖穷举：识别所有外部系统与依赖，不漏任何一个第三方服务；
• 图与文档双产出：画清晰、利益相关者友好的图，同时维持格式一致性。

Response Approach：11 步响应流程

在收到请求后，该 Agent 遵循明确的执行序列（定义于 c4-context.md）：

1. 分析容器文档（c4-container 的产出），理解系统如何部署；
2. 分析组件文档（c4-component 的产出），理解系统逻辑构成；
3. 分析系统文档：README、架构文档、需求文档等；
4. 分析测试文件：借由测试理解系统行为与特性；
5. 确定系统目的：系统做什么、解决什么问题；
6. 识别角色：全部角色（人类与程序化）；
7. 识别特性：系统提供的全部高层特性；
8. 映射用户旅程：为每个关键特性创建旅程图；
9. 识别外部系统：全部外部系统与依赖；
10. 绘制上下文图：生成 Mermaid 上下文图；
11. 生成文档：输出完整的上下文文档。

这个流程暗示了它的读码习惯：它不是从源码本身开始（源码已由上游 Code/Component/Container 层消化），而是站在"已消化文档 + 系统级资料"的肩膀上做最终合成——这正是分层工作流的精髓。

文档模板：一份可直接套用的 c4-context.md 骨架

c4-context Agent 给出了标准文档模板，生成文档时应遵循如下结构（完整保留，可直接复制作为C4-Documentation/c4-context.md的起点）：

# C4 Context Level: System Context ## System Overview ### Short Description [One-sentence description of what the system does] ### Long Description [Detailed description of the system's purpose, capabilities, and the problems it solves] ## Personas ### [Persona Name] - **Type**: [Human User / Programmatic User / External System] - **Description**: [Who this persona is and what they need] - **Goals**: [What this persona wants to achieve] - **Key Features Used**: [List of features this persona uses] ## System Features ### [Feature Name] - **Description**: [What this feature does] - **Users**: [Which personas use this feature] - **User Journey**: [Link to user journey map] ## User Journeys ### [Feature Name] - [Persona Name] Journey 1. [Step 1]: [Description] 2. [Step 2]: [Description] 3. [Step 3]: [Description] ... ### [External System] Integration Journey 1. [Step 1]: [Description] 2. [Step 2]: [Description] ... ## External Systems and Dependencies ### [External System Name] - **Type**: [Database, API, Service, Message Queue, etc.] - **Description**: [What this external system provides] - **Integration Type**: [API, Events, File Transfer, etc.] - **Purpose**: [Why the system depends on this] ## System Context Diagram [Mermaid diagram showing system, users, and external systems] ## Related Documentation - [Container Documentation](https://link.gitcode.com/i/8b21b504c1cfc39460712288221f1c52) - [Component Documentation](https://link.gitcode.com/i/3c4e264b88da9eed2eccc87e14cbda17)

模板的语义分层很清晰：总览 → 角色 → 特性 → 旅程 → 外部系统 → 图 → 关联文档，恰好就是"系统是什么→谁用→用来干嘛→怎么用→靠什么外部支撑→全景图→去哪看细节"的叙事线。最后一步以链接收束到容器/组件文档，让读者从全景一层层"钻取"到细节，保持层级文档的链接一致性（这也是命令文档 Coordination Notes 强调的纪律）。

Context Diagram Template：用 Mermaid C4Context 画"居中盒子"图

文档化的收尾是生成上下文图。Agent 使用Mermaid 的 C4 专用语法C4Context，模板如下（来自 c4-context.md）：

对语法做个速览：Person声明人类参与者、System声明当前系统（图中的"中央盒子"）、System_Ext声明外部软件系统、SystemDb声明外部数据库，而Rel声明关系——每个Rel都可以携带技术标签（如"API"、"Sends events to"、"Reads from and writes to"），用于说明数据/调用流向。更丰富的边界声明（如System_Boundary）则会在 C4Container 层级（见 c4-container.md 的模板）中大量出现，那里每个部署单元被Container与ContainerDb包裹。

上下文图的关键原则

• 聚焦"人与软件系统"，而非技术栈与协议；
• 系统边界清晰，一目了然哪些在边界内；
• 包含全部用户（人类与程序化）；
• 包含系统交互的全部外部系统；
• 保持利益相关者友好：非技术受众能读懂；
• 避免在图中展示技术、协议或低层细节。

把这条原则和 Container 层原则对比就格外清楚：Container 层恰恰要展示"Spring Boot + PostgreSQL"这类技术选型，而 Context 层刻意回避技术细节。两套文档面向完全不同的读者——这是四个 C4 Agent 之间最深刻的分工逻辑。

边界划分：与其余三个 C4 Agent 的区别

c4-context.md 用 "Key Distinctions" 明确划定了它与同插件兄弟 Agent 的职责边界：

• vs c4-Container Agent：Context 提供最高层的系统视图；Container 专注于部署架构与容器划分；
• vs c4-Component Agent：Context 聚焦系统整体语境；Component 聚焦单个容器内部的逻辑组件结构；
• vs c4-Code Agent：Context 提供利益相关者友好的概览；Code 提供最底层的代码要素细节（函数签名、行号位置、依赖）。

一句话总结四者关系：Code 层负责"把每一个函数讲清楚"，Component 层负责"把代码归堆成组件"，Container 层负责"把组件装进部署单元并给出 API"，Context 层负责"把这些全部翻译成一张人能看懂的全景图"。

典型使用方式与产出清单

在 c4-architecture 命令 的 Phase 4 编排下，该 Agent 收到的标准提示词会要求它基于容器文档、组件文档、系统文档与测试文件产出完整的 Context 级文档。你也可以在子任务调度中直接唤起它，例如：

• "Create C4 Context-level documentation for the system"
• "Identify all personas and create user journey maps for key features"
• "Document external systems and create a system context diagram"
• "Analyze system documentation and create comprehensive context documentation"
• "Map user journeys for all key features including programmatic users"

若想直接对既有代码库一次性生成完整 C4 文档，可按 usage.md 在命令中运行/c4-architecture:c4-architecture，并根据目标仓库情况调整命令文档中列出的配置项：

Context 层的成功标准

在命令文档的 "Success Criteria" 中，与 Context 层相关的验收点包括：系统上下文包含全部角色（人类 + 程序化）；所有关键特性都有用户旅程；全部外部系统与依赖被识别；上下文图展示系统、用户与外部系统；文档以C4-Documentation/目录组织。也就是说，这份文档"全不全"，最终要看：角色是否齐、旅程是否全、外部依赖是否穷尽、图是否正确。

最终产出清单（Output Examples）应包含：

• 清晰的系统描述（短描述 + 长描述）；
• 全面的角色文档（人类 + 程序化用户）；
• 完整特性列表及其描述；
• 所有关键特性的详细用户旅程图；
• 完整的外部系统与依赖文档；
• 展示系统、用户、外部系统的 Mermaid 上下文图；
• 指向容器与组件文档的链接；
• 非技术受众也能理解、且格式一致的文档。

在仓库中实际使用它

你可以在仓库文档与代码中找到这条工作流的完整证据链：

• Agent 定义本体：c4-context.md（模型sonnet，角色"系统上下文文档专家"）；
• 四层 Agent 的横向对比：c4-code、c4-component、c4-container；
• 编排工作流与配置项：c4-architecture.md（Phase 1～4、目录发现策略、成功标准、C4-Documentation/输出结构）；
• 插件在仓库中的注册位置：architecture.md 的目录树；
• 面向用户的调用示例与完整编排链（c4-code → c4-component → c4-container → c4-context）：usage.md。

实际落地建议：把一次/c4-architecture:c4-architecture的全量执行当成"首次成稿"，之后在每一次架构演进（新增外部集成、新增用户角色、特性变更）时单独唤起 c4-context 增量更新c4-context.md，保持这张"全景图"与代码现实同步。需要单独复查时，只需对 Agent 说"更新系统上下文文档并补全新角色的用户旅程"即可。

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents