# 写作规范（STYLE.md） 本规范约束《Loop Workflow 企业应用指南》全书所有 Markdown 正文、模板与案例的写法。所有作者（人与 Agent）在提交正文前必须使本文件通过 `make check`。 ## 0. 优先级与边界 - 术语一致性优先级：**TERMINOLOGY.md > STYLE.md > 单章约定**。任何冲突以 TERMINOLOGY.md 为准。 - 本文件只规定“怎么写”，不规定工程构建。构建、目录骨架、`SUMMARY.md`、`book.yaml`、字体与主题由工程批次（`Makefile / book.yaml / SUMMARY.md / scripts/** / theme/**`）维护，本文件不覆盖这些路径。 - 凡是“规则”都写成可被脚本判定真伪的断言（见 §15）。不可机器判定的偏好不计入“规则”，只作为建议。 ## 1. 语言与排版 - 正文语言为**简体中文**；代码、命令、配置、标识符保留英文原文。 - 中英文混排：中文与英文 / 数字之间各加一个半角空格（`使用 Workflow 运行 3 次`）。中文标点紧贴中文，英文标点紧贴英文。 - 标点：中文句子用中文全角标点（，。：；？！）；代码与命令内部一律半角。 - 引号：中文用“ ”与‘ ’；不使用直引号 `"` 作引号。 - 数字：度量、次数、版本用阿拉伯数字；一句之首不用阿拉伯数字起头。 - 日期与时间：日期用 ISO `2026-08-13`；时间带时区 `18:00+08:00`；相对时间写绝对值，不写“昨天”。 - 单位：与代码 / UI 一致（如时长 `30s`、`5m`、`1h`；容量 `MiB`/`GiB`）。 - 每行一句（soft wrap）。句号收尾后换行，便于 diff 与审阅。不在句中强制断行。 ## 2. 语气与人称 - 默认对读者称呼“你”，使用主动语态与现在时。例如写“你提交后 Run 进入 `running`”，不写“被提交后将会进入”。 - 简洁优先：一句表达一个动作。删除无信息的客套（“众所周知”“显而易见”）。 - 指令用祈使句（“在 `triggers` 下添加一项”）；结论用陈述句。 - 避免绝对化承诺（“永远”“绝不”“100% 安全”），改用可验证的限定（“默认超时 30s 内”）。 ## 3. 术语 - 一切核心名词的中文写法、英文写法与**禁用变体**以 `TERMINOLOGY.md` 为唯一来源。 - 正文首次出现核心术语时写“中文（English）”，此后全书统一用其规范写法之一。 - 不自造中文译名。若 `TERMINOLOGY.md` 未覆盖，先在该文件补条目并交 Review，再用于正文。 - 代码标识符（结构体、字段、枚举值、API 路径）保持与源码完全一致的英文大小写，不翻译、不重排。 ## 4. 标题层级 - 一篇（Part）用 `#`（H1），一章用 `##`（H1 由 `SUMMARY.md` 装配时产生，正文章首用 `##`），节用 `###`，子节用 `####`，最多到 `####`。 - 标题不跳级：H2 下不能直接出现 H4。 - 标题末尾不加标点。标题不使用纯 Emoji。 - 同一章内标题唯一，不重复。 ## 5. 段落、强调与行内代码 - 段落之间空一行。不在段落内插入空行。 - 强调用 `**粗体**` 表示关键概念首次定义；用 `*斜体*` 仅用于书名、新词引入。 - 标识符、文件名、字段名、短命令、状态值、HTTP 方法一律用行内代码 `` ` `` 包裹（如 `Workflow` 结构体、`status` 字段、`POST /api/workflows`）。 - 不要用行内代码做整句强调。 ## 6. 代码块 - 所有围栏代码块**必须标注语言**（```yaml、```bash、```go、```text 等）。无语言的纯缩进块禁止。 - 代码块要可独立理解：必要上下文用注释给出，不依赖正文外的隐含状态。 - 命令示例必须可复制即跑；需要替换的值用 `<占位符>` 形式（如 ``），并在块前一行说明。 - 输出用 ```text，命令用 ```bash，配置用 ```yaml，Go 用 ```go。不要把命令与输出混在同一个 ```bash 块里，输出单独用 ```text。 - 不要在代码块里放行号，除非整章在讲解行号。 - 代码块不写 `\`\`\`语言` 之外的前缀（不写 `bash ~$`），提示符写在内容里。 ## 7. 命令与输出 - 每条命令以 `$ ` 起头（行首 `$ `），输出紧随其后不加前缀。 - 命令注释用 `#` 并写在命令上方或行尾。 - 关键预期输出必须给出，并用注释标出“你应看到……”的判断点。 - 命令默认可幂等或可清理；破坏性命令（`delete`、`--force`、`drop`）必须在该命令上方用 `> **⚠️ 注意：**` 提示后果。 ## 8. 配置示例（YAML / Schema） - 所有 YAML 示例的字段名、取值、枚举必须与当前代码中的真实 schema 一致；不确定时引用源码位置而不杜撰字段。 - 一个示例只演示一个关注点。需要多字段时，用注释标出哪些是必需、哪些可选。 - 必填字段缺省时用 `<必填>` 占位，不得留空假装合法。 - 示例里的 `id`、`token`、密钥一律用占位符，不出现任何真实凭据。 ## 9. 提示框（Callout） 统一使用引用块 + 标签前缀，全书一致的五种： ```text > **💡 提示：** 非必须但有帮助的信息。 > **⚠️ 注意：** 可能导致错误结果或数据变化的操作。 > **❌ 反例：** 常见错误写法及其后果。 > **✅ 正例：** 与反例对照的正确写法。 > **🔧 进阶：** 可选的更优做法，初学者可跳过。 ``` - 一行一种标签；多段内容延续引用块。 - 全书只用以上五种标签，不新造。 ## 10. 链接、图片与媒体槽位 - 站内链接用相对路径；外部链接写完整 URL。 - 所有图片放 `media/`，命名 `fig-<章号>-<序号>-.png`（如 `fig-03-02-run-graph.png`）。 - 图片必须有 alt 文本；正文中用“如上图 3-2 所示”引用，图题写在图下方居中：`图 3-2 Run graph 的节点与边`。 - 表格不另存图片；复杂流程图用图片并在 `media/` 保留可编辑源文件（同名的 `.drawio`/`.svg`）。 - 媒体槽位（media slot）：每章 / 案例模板中预留图位用占位段落 `` 标注，正文成稿后替换。 ## 11. 文件命名约定 - 章节文件：`<两位章号>-.md`，章号对应 `SUMMARY.md` 顺序，`slug` 用小写英文与连字符（如 `04-create-from-prompt.md`）。 - 案例文件：`case-<三位序号>-.md`，序号即案例编号，全书 `case-001`–`case-080`（如 `case-001-bug-triage.md`）。 - 媒体文件：见 §10。 - 文件名只用小写字母、数字、连字符；不含空格、中文、下划线（除模板文件 `chapter.md` / `case.md` 本身）。 - 目录结构以 `book.yaml` / `SUMMARY.md`（工程批次）为准，本规范只约束文件名。 ## 12. 可执行性与可复现性 - 所有命令与配置默认可在干净环境复现。涉及版本依赖时写明版本（如 `typst 0.13`、`pandoc 3.x`）。 - 任何“点击 UI”步骤都要给出等价的 API / CLI 路径或明确说明“仅 UI 路径”。 - 示例数据用最小可运行集合；不依赖外部未提供的私有数据。 - 截图须与当前 UI 版本一致；UI 变更后同步更新对应截图。 ## 13. 字数与节奏 - 每章正文 1500–3500 字（中文），案例 600–1200 字。超出时分节或拆章。 - 首段用 2–4 句给出“本章你将学会什么”。 - 每章末尾用“小结 + 下章预告”收尾，小结为可勾选要点列表。 ## 14. 引用源码与外部资料 - 引用代码位置写成可点击的相对路径与符号（如 `internal/workflow/run.go:Run.Execute`）。改用仓库内统一引用格式，不写绝对本机路径。 - 引用外部文档给出链接与访问日期。 ## 15. 可检查规则（machine-checkable） 以下规则是**断言**，由工程批次的 `make check`（`scripts/**`）实现校验，违反即 fail。本节是检查器的契约，修改前需与工程批次对齐。 **扫描范围**：正文/结构规则（1–8、10）只在 `manuscript/**/*.md`（作者生成的章节与案例，正文根以工程批次 `SUMMARY.md` 为准）上判定；**排除** `STYLE.md`、`TERMINOLOGY.md`、`templates/**`、`media/**`、`dist/`、`build/`。规则 9（Plan 校验）额外扫描 `templates/**/*.md` 里的 `loop.plan/v1` 块，防止模板自身回归。**案例 glob**：`manuscript/part-05-enterprise-cases/**/case-*.md`；**章节 glob**：`manuscript/part-<篇号>-/*.md`。 **AST 排除区**（下列规则只在 Markdown 正文文本节点上判定，**忽略**围栏代码块内容、行内代码 `code`、HTML 注释 ``）：规则 1（禁字面量 / 占位）、规则 5（中英文空格）、规则 11（禁用术语变体）。这样元文件里“定义规则本身”的字面量、YAML 中合法的 `{{ }}` Plan 插值、`` / `` 标记不会被误判。 **canonical 槽位**：10 个槽位标记（HTML 注释，名称定义于 `templates/chapter.md` 与 `templates/case.md`）须在 `manuscript/**/*.md` 每个章节/案例文件中各出现一次（Pandoc AST 与 raw 文本计数均应为 10）；缺失即 fail。媒体登记注释不计入槽位覆盖。 1. 不允许出现字面量 `TBD`、`TODO`、`FIXME`、`XXX`、`待补充`、`待填`（含中英文与全角）；正文文本节点中残留的 `{{…}}` 模板占位等同未填，禁止（YAML 代码块内的 `{{ }}` 是合法 Plan 插值，不计）。 2. 每个围栏代码块都必须带语言标注。 3. 标题层级不跳级（H1→H2→H3→H4，逐级；不出现 H2 直接接 H4）。 4. 同一文件内标题文本不重复。 5. 中英文混排处，中文与英文/数字之间有且仅有一个半角空格（CJK 与 ASCII 边界）。 6. 行尾不得有多余空格；文件以单个换行结尾。 7. 所有图片引用的 `media/` 路径真实存在；占位 `` 以外不得引用缺失文件。 8. 代码块语言仅限白名单：`yaml`、`bash`、`text`、`go`、`json`、`typescript`、`tsx`、`sql`、`mermaid`。 9. `yaml` 代码块中的 `loop.plan/v1` 示例须通过 `workflow plan validate`（`diagnostics=[]`），不只是 YAML 语法可解析（这会捕获非法运算符 `or`、未声明引用 `input.x` 等）。 10. Callout 仅使用 §9 定义的五种标签前缀。 11. 自动禁用只读 `TERMINOLOGY.md` 中的 `` HTML 注释（每行一条；仅在正文 Markdown AST 文本节点做精确字符串匹配，排除围栏代码、行内 code、HTML 注释；不拆表格单元格、不分词、不正则、不上下文推断）。`TERMINOLOGY.md` 各表“禁用 / 旧称变体”列中需要上下文判断的条目（如“步骤 / Step 作节点类型名”）属人工 Review，不进入自动禁用；`channel` 是合法旧类型、非禁用，只是新书优先 `scope`。 ## 16. 禁止项汇总 - 禁止 `TBD/TODO/FIXME/待补充` 等占位进入提交。 - 禁止虚构术语、字段、枚举值、API、文件路径。 - 禁止未标注语言的代码块、跳级标题、重复标题。 - 禁止在示例中出现真实凭据或私有数据。 - 禁止用截图替代本可用文字 / 代码表达的内容。 - 禁止中英文标点混用、全半角混用造成的歧义。 - 禁止两位案例编号（用 `case-001`–`case-080`）与 `专家` 等非规难度词（难度取 `入门` / `进阶` / `复杂`）。 - 禁止在表达式中用 `or` / `and` / `not` 单词运算符（用 `||` / `&&` / `!`）。 --- 变更本规范时，请在同一提交的 commit message 中说明“新增 / 收紧 / 放宽”了哪条可检查规则，以便工程批次同步检查器。