写作规范 · 视觉元素
Note
本文档规定 SoulMem 文档（mdbook）中视觉元素的使用方式，是写作规范的第一部分。后续将补充术语、语体与工具链规范。
规范的目的不是限制创作，而是让“内容角色“与“视觉呈现“一一对应：同一个视觉元素永远表达同一种语义，读者不用猜、作者不用解释。
1. 两条总原则
- 语义优先：写作时先回答“这段内容是什么角色？“——注释？记忆示例？核心设计？技术陈述？——再选择对应的元素。禁止先写样式、再决定含义。
- 一物一用：同一个 markdown 元素不承担两个语义角色。CSS 只是把语义角色画出来，不是内容的来源。
推论：禁止“随手加样式“。任何视觉差异都必须对应一个语义角色，并登记在本规范中；新增视觉元素 = 新增语义角色，需要先在此定义、再投入使用。
2. 语体档位与视觉切换
SoulMem 文档存在两档语体，它们的切换必须有明确的视觉符号：
| 档位 | 内容 | 语气 | 视觉容器 |
|---|---|---|---|
| 叙事档 | 示例、场景、对话、开场故事 | 轻松，允许玩梗（小红/小白、早八） | 叙事容器（未加标签的块引用，独特背景，见 4.2 节） |
| 定义档 | 机制解释、术语定义、算法、字段说明 | 陈述性、严谨，不用梗 | 普通段落与代码 |
为什么需要视觉切换：两档语体都可能连续占据大段篇幅。没有视觉区分，读者无法判断当前在读的是“角色记忆的内容“还是“系统的机制说明“——而这两类内容的可信度完全不同：记忆示例是角色认定的事实，不是系统事实。
- 规则 2.1：叙事档内容必须放进叙事容器（见 4.2）。裸的叙事段落视为违规。
- 规则 2.2：定义档禁止玩梗、禁止网络用语、禁止打破第四面墙。需要轻松语气的内容一律归入叙事档。
- 规则 2.3：打破第四面墙的句子（如“文档作者没有打错字“）只允许出现在
[!note]澄清误会时，不得打断定义档的论证流。
3. 视觉元素总表
| 元素 | 语义角色 | 语法 | 何时使用 | 禁止 |
|---|---|---|---|---|
# H1 | 页面标题 | # 标题 | 每文件一个，与 SUMMARY 章节名一致 | 每文件多于一个 |
## ~ #### | 分节标题 | ##/###/#### | 按层级分节 | 跳级（如 ## 直接到 ####） |
| 普通段落 | 定义档正文 | 空行分隔 | 机制、解释、论证 | 叙事内容（须入容器） |
| 加粗 | 概念强调 | **词** | 关键词、术语首次强调 | 标识符（用反引号） |
| 斜体 | 次要语气 | *词* | 定义档避免；叙事容器内角色台词可用 | 定义档正文用斜体强调 |
反引号 | 标识符/字段/命令 | `name` | 代码符号、字段名、命令 | 概念词（用加粗） |
| 列表 | 枚举/步骤 | - | 并列项、流程步骤 | 单个条目也强行成列表 |
| 链接 | 交叉引用 | [文字](相对路径) | 见第 5 节 | 死链、指向不存在的章节 |
--- | 分节分隔线 | --- | 章内大分节（如三类记忆之间） | 装饰性使用 |
| 代码块 | 代码/配置 | ``` | 代码、数据结构、配置 | 伪代码用 mermaid |
| 表格 | 结构化对照 | 表格语法 | 字段对照、规则表 | 叙事内容 |
| mermaid | 图 | ```mermaid | 流程、结构、时序 | 简单列表能说清的 |
<br> | 段落内硬换行 | <br> | 对话行换行 | 作为间距（间距由 CSS 统一负责） |
| 块引用 | 说明类注释（标签卡片）或叙事容器（裸 >） | > 系列 | 说明类用标签；叙事内容用裸块引用 | 说明类内容裸 >；叙事内容加标签 |
4. 块引用与叙事容器
块引用（>）是本书使用最频繁、也最需要规范的组件。当前它同时承担“注释、记忆示例、设计强调“三个角色且视觉相同——必须拆分。
4.1 内置标签（mdbook 原生支持，已验证）
mdbook 0.5.4 支持 GitHub 风格的块引用标签，渲染为带图标和标题的卡片。已核对源码：仅以下五种（大小写不敏感），标签必须独占首行，后续行写内容：
> [!note]
> 给读者的补充说明、实现细节的旁注。
> [!important]
> 设计观点与原则的强调（如"一切特征和事件都属于记忆"）。
> [!warning]
> 有争议的机制、已知取舍（如遗忘机制的争议）。
> [!tip]
> 使用建议、写作建议。
> [!caution]
> 容易踩坑之处。
| 标签 | 语义角色 | 示例场景 |
|---|---|---|
[!note] | 注释 | 给读者的补充说明、实现细节旁注 |
[!important] | 核心设计 | 设计原则与观点强调 |
[!warning] | 争议/警告 | 有争议的机制、已知取舍 |
[!tip] | 建议 | 使用建议、写作建议 |
[!caution] | 注意/陷阱 | 容易踩坑之处 |
规则 4.1：所有“给读者的说明“类内容（注释、核心设计、争议、建议、注意）必须使用上述标签之一。未加标签的块引用一律视为叙事容器（见 4.2），只允许承载叙事档内容。
标题本地化（CSS）：内置标签的标题固定渲染为英文（Note/Tip/…），且不支持 > [!note] 自定义标题 这种同行标题（会被当作字面文本）。中文化通过 CSS 实现，在 soulmem-theme.css 中加入：
/* 内置标签标题中文化（隐藏英文原文，用伪元素替换） */
.blockquote-tag-title {
font-size: 0;
}
.blockquote-tag-title::after {
font-size: 1rem;
font-weight: 600;
}
.blockquote-tag-note .blockquote-tag-title::after { content: "注释"; }
.blockquote-tag-tip .blockquote-tag-title::after { content: "建议"; }
.blockquote-tag-important .blockquote-tag-title::after { content: "核心设计"; }
.blockquote-tag-warning .blockquote-tag-title::after { content: "争议"; }
.blockquote-tag-caution .blockquote-tag-title::after { content: "注意"; }
规则 4.2：已知五种标签之外的标签（如 > [!example]）在 mdbook 0.5.4 中会原样显示为文本（已核对 pulldown-cmark 0.13.4 源码与官方测试），禁止使用。需要新组件时，先在本规范登记、再引入 preprocessor 等机制。
4.2 叙事容器（无需标签词）
叙事档内容的视觉切换符号 = 叙事容器：拥有独特背景、未加标签的块引用，与注释（靛蓝系）一眼可辨（暖色系）。
叙事容器不需要任何标签词。叙事内容本身就带有轻松的语气和例子说明的功能，强制要求固定的“示例/场景/对话“标签反而显得机械，还给读者造成冗余信息。作者按叙事自然书写即可；需要时可以用加粗短语（如 > **小白的麻辣烫**）当小标题，但那只是内容的一部分，不是规范要求。
规则 4.3：叙事档内容必须写在未加标签的块引用（叙事容器）中，叙事内容不得加内置标签。反过来说，未加标签的块引用一律按叙事容器渲染。
> 2026-07-12 中午，和用户在街角那家麻辣烫店，被辣到了。
> 三个月前，小白第一次去吃麻辣烫，被辣得一直喝水。
> **小红**：你看这个小白就是逊啦，才这么点就被辣到了。
> **小白**：辣？赛博生命的事，怎么能说辣呢？
规则 4.4：除叙事容器外，禁止其他用途的裸块引用（如引文）；确有必要时先在本规范登记新组件，再投入使用。
视觉规格（明暗双适配，供 CSS 实现）：
:root {
--sm-example-bg: #fdf6ec; /* 叙事容器底：暖色（琥珀 50） */
--sm-example-border: #d97706; /* 左边条：琥珀 600 */
}
.navy, .coal, .ayu, .rust {
--sm-example-bg: #221c14; /* 深色主题：暖黑 */
--sm-example-border: #f59e0b; /* 左边条：琥珀 500 */
}
/* 叙事容器 = 未加标签的块引用；带标签的是注释卡片 */
.content blockquote:not(.blockquote-tag) {
background: var(--sm-example-bg);
border-left-color: var(--sm-example-border);
}
边距、圆角与注释一致（1.5em、8px），仅底色与左边条不同。对话行内的加粗人名（**小红**）是内容，不是标签，不受本规则约束。
4.3 记忆示例的写法
记忆示例是叙事容器最常出现的形式（情境/语义/程序性记忆的实例）。约定：
- 用角色视角直接呈现记忆内容，形如一条真实的记忆记录；
- 示例前在定义档说明“这是什么记忆“；容器内不再解释，保持纯净；
- 记忆内容中的时间、地点用具体值（如
2026-07-12），不用“某年某月“占位——除非故事本身在强调模糊（如遗忘后的记忆）。
5. 章节引用规则（当前阶段）
背景：本书后续部分尚未定稿，且作者计划进行一次内容重组。因此现阶段：
规则 5.1：允许前向引用（“后续章节”），但必须使用统一句式，禁止自创说法。
| 场景 | 规范句式 |
|---|---|
| 指向后续未定稿内容 | 具体机制将在后续章节阐述。（可加主题词：“具体机制（如遮罩实现）将在后续章节阐述。”） |
| 指向主题而非具体章节 | 详见 [遗忘算法](../algorithm/forget.md) 相关章节。 |
| 指向已存在且稳定的章节 | 相对链接：详见 [检索算法](../algorithm/retrieve.md)。 |
规则 5.2：禁止在正文写死具体章节标题或文件名作为“未来承诺“（如“将在《XX》章详述“）——重组会破坏这类引用。指向未来内容时用主题词，不用章节名。
规则 5.3：重组完成后，把前向引用逐步替换为相对链接，并启用 mdbook-linkcheck 校验所有链接（见第 7 节）。
6. 术语与专名（待补充）
- 专名大小写固定：
SoulMem、LLM、PPR、SurrealDB（统一写法待确认后定稿）； - 一物一名：同一概念全文统一叫法（如“角色 / 数字角色 / 赛博生命“择一为主），别名登记进术语表；
- 首次出现给出中英对照，如
情境记忆（Situation / Episodic）。
（术语表将在规范第二部分建立。）
7. 机械化检查（规划）
规范定稿后引入工具，把规则变成可自动检查的约束：
- pangu：中英文之间自动加空格；
- markdownlint-cli2：标题层级、空行、列表一致性；
- mdbook-linkcheck：链接与锚点有效性（重组完成后启用）；
- CI 检查：专名大小写白名单、禁止
<br>作间距（裸块引用是否违规依赖 review，暂不自动化）。
8. 生效范围与迁移
- 新内容：自本规范生效起，按本规范写作。
- 存量内容：分批迁移，优先级：
- 块引用分类（注释 → 标签卡片；记忆示例、对话 → 未加标签的叙事容器）——对阅读影响最大；
- 裸
>清理； - 专名与术语统一；
- 前向引用句式统一。
- 本规范随写作迭代更新；新增任何视觉元素前，先在此登记。