# 写作规范（STYLE.md）

本规范约束《用 AgentTeam Agent 建立团队协作》全书所有 Markdown 正文、模板与附录的写法。
所有作者（人与 Agent）在提交正文前都必须使本文件通过 `make check`。

## 0. 优先级与边界

- 术语一致性优先级：**TERMINOLOGY.md > STYLE.md > 单章约定**。
- 本文件只规定“怎么写”，不规定工程构建。
- 规则尽量写成可被脚本判定真伪的断言。

## 1. 语言与排版

- 正文语言为简体中文；代码、命令、配置、标识符保留英文原文。
- 中文与英文 / 数字之间各加一个半角空格。
- 中文句子使用中文全角标点；代码与命令内部使用半角标点。
- 日期写绝对值，如 `2026-08-16`；不写“昨天”“本周三”这类相对时间。
- 每行一句（soft wrap）。

## 2. 语气与人称

- 默认对读者称呼“你”，使用主动语态。
- 先给推荐做法，再给原因和例外。
- 避免空泛形容词，尽量写成可执行动作。

## 3. 术语

- Agent、Role、Skill、Runtime、Task、Thread、Memory 等核心名词，以 `TERMINOLOGY.md` 为唯一来源。
- 首次出现时可写“中文（English）”，之后保持全书一致。
- 不自造平行译名。

## 4. 标题层级

- 篇使用 `#`。
- 章使用 `##`。
- 节使用 `###`。
- 最多到 `####`。
- 标题不跳级，不重复。

## 5. 行内代码与代码块

- 标识符、文件名、字段名、命令、状态值和模型名用行内代码包裹。
- 所有围栏代码块必须标注语言。
- 命令示例使用 `bash`，输出使用 `text`。
- 除非是合法的 Workflow Plan，不要在正文里放 `yaml` 代码块。

## 6. 提示框

全书统一使用以下 5 种提示框：

> **💡 提示：** 非必须但有帮助的信息。
> **⚠️ 注意：** 可能导致错误结果或返工的操作。
> **❌ 反例：** 常见错误写法及其后果。
> **✅ 正例：** 与反例对应的更好做法。
> **🔧 进阶：** 面向已经跑通默认路径的团队。

## 7. 媒体与模板

- 所有图片放在 `media/`。
- 章节暂时没有实际图片时，在“媒体槽位”写明“本章不新增媒体”。
- 所有教学章节都保留 10 个 canonical 槽位，并且各出现一次。

## 8. 文风要求

- 面向通用开发团队，而不是只面向某一个客户项目。
- 重点解释默认阵型、上下文治理、技能组合与团队资产沉淀。
- 读者读完后，应该能把章节内容直接抄进自己的 Agent 配置或协作消息里。