章节模板与语言风格规范

本规范用于统一《Anthropic Engineering 学习指南》的章节结构、语气和工程表达。

1. 章节结构

每章推荐采用以下结构：

# 第 X 章：章节标题

本章导读
章节元信息

1. 本章要解决什么问题
2. 对应 Anthropic 文章 / 工程来源
3. 核心观点
4. 工程视角重新解释
5. 架构图 / 流程图
6. Java / Spring Boot 落地方案
7. 企业案例 / 贯穿案例
8. 与其他框架对比 / 常见误区
9. 本章小结
10. 实践任务

不是所有章节都必须机械使用完全相同标题，但必须覆盖以下要素：

• 问题定义；
• 来源或参考文章；
• 工程解释；
• 图示；
• Java / Spring Boot 映射；
• 贯穿案例；
• 误区；
• 小结；
• 实践任务。

2. 本章导读格式

第 1～23 章统一添加：

> **本章导读**  
> - 核心问题：...  
> - 关键词：...  
> - 学习产出：...

写法要求：

• 核心问题只写一个主问题；
• 关键词使用术语表推荐写法；
• 学习产出写成读者能获得的工程能力，而不是“了解某概念”。

3. 元信息格式

导读后使用独立的章节元信息块，避免它与 Markdown 导读引用块合并：

<aside class="chapter-meta" aria-label="章节信息">
  <span><strong>所属部分</strong>：第二部分：Context Engineering</span>
  <span><strong>对应文章</strong>：Anthropic Engineering — <em>Effective Context Engineering for AI Agents</em></span>
  <span><strong>官方链接</strong>：...</span>
  <span><strong>本章状态</strong>：精修稿</span>
</aside>

如果章节是综合工程章节，可将“对应文章”写为“综合工程章节”，并增加“参考来源”。新增章节后可运行 npm run book:format 统一元信息结构。

4. 图示引用格式

所有 Mermaid 图必须同时保留 .mmd 源文件和预渲染的 .svg，正文统一使用 <figure>，不再保留内联 Mermaid 代码块。推荐格式：

<figure class="book-figure book-figure--primary">
  <a class="book-figure__link" href="../diagrams/chapter-XX-topic.svg" target="_blank" rel="noopener">
    <img src="../diagrams/chapter-XX-topic.svg" alt="图名" loading="lazy" decoding="async">
  </a>
  <figcaption>
    <strong>图 X-1 图名</strong>
    <span class="book-figure__note">阅读提示。</span>
    <a class="book-figure__source" href="../diagrams/chapter-XX-topic.mmd">Mermaid 源文件</a>
  </figcaption>
</figure>

要求：

• 每章主图编号为“图 X-1”，其余图按出现顺序连续编号；
• 图片必须提供表达图意的中文 alt，不得使用文件名代替；
• .mmd 与 .svg 文件统一保存在 diagrams/；
• 点击图片可以打开原始 SVG，便于放大查看；
• 新增普通 Markdown 图片后，运行 npm run book:format 统一为 <figure>；
• 运行 npm run diagrams:render 只渲染新增或变更过的 Mermaid 图。

5. 贯穿案例写法

统一案例：

CI 失败分析 Agent
项目：order-service
Build：#4312
PR：#882

写作原则：

• 每章只解释本章概念如何作用于案例；
• 不在每章重复完整背景；
• 事实口径以 references/case-study-ci-failure-agent.md 为准；
• 输出应强调 evidence-backed report，而不是“模型猜测”。

6. 语言风格

推荐表达：

Agent 是由 Context、Tool、Skill、Memory、Harness 和 Runtime 共同构成的工程系统。

避免表达：

Agent 可以自动理解一切并自主完成任务。

推荐表达：

Memory 是上下文窗口之外的长期上下文资产，只有被检索并注入后才成为当前 Context。

避免表达：

Memory 就是聊天历史。

推荐表达：

Tool 提供动作能力，Skill 提供完成一类任务的方法。

避免表达：

Skill 就是工具集合。

7. 术语规则

以 references/glossary.md 为准。

重点统一：

8. Java / Spring Boot 写法

Java 落地部分应尽量使用接口优先表达：

public interface ContextProvider {
    List<ContextChunk> provide(ContextRequest request);
}

避免一开始写完整工程实现。

推荐关注：

• 模块边界；
• 接口职责；
• 数据结构；
• 执行流程；
• 权限与治理；
• 可观测性。

9. 小结写法

小结建议 3～5 条，不写泛泛总结。

推荐格式：

本章可以总结为：

1. X 解决的是 ...；
2. X 在 Runtime 中承担 ...；
3. 企业落地时要注意 ...；
4. 在 CI 失败分析案例中，X 体现为 ...。

10. 实践任务写法

实践任务应满足：

• 可独立完成；
• 不依赖完整 Java 示例工程；
• 可成为后续示例工程的输入；
• 尽量围绕 CI 失败分析 Agent 展开。