本文档为 Zeka Stack 文档站点提供写作规范和结构建议，确保文档质量一致、对人类和 AI 都友好。
每个 .md 文件有且仅有一个一级标题 # 标题，它同时也是菜单项的显示文本。
- 保持简短，不超过 10 个字
- 用名词或名词短语，不用句子
- 好：
# 日志系统# 统一异常处理 - 差：
# 如何使用日志系统来记录应用运行时的日志
文档的骨架由二级标题 ## 构成，推荐顺序：
- 简介 / 作用
- 设计理念 / 为什么这么设计
- 使用方法
- 配置说明
- 最佳实践
- 相关链接
不是每个文档都需要全部章节，但顺序应该从"是什么"到"怎么用"再到"怎么用好"。
- 三级标题
###：某个章节下的子主题 - 四级标题
####：极少使用，只有复杂配置或边界情况才需要
模块主文档是读者进入某个模块后看到的第一份内容，应该在 200 行以内讲清楚三件事：
- 这个模块是做什么的 — 一段话说清定位
- 怎么用 — 最小可运行示例（代码块）
- 去哪里看更多 — 链接到补充文档
# 模块名称
## 📖 简介
一段话说明定位和核心能力。
## 🚀 快速使用
最小 Maven 依赖 + 最小代码示例。
## 📦 配置属性
表格列出常用配置项。
## 🔗 相关链接
- [[其他模块/index|其他模块]]
补充文档聚焦于单一主题，每个文件只讲一件事：
detail-unified-exception-handler.md— 只讲统一异常处理detail-parameter-validation.md— 只讲参数校验detail-design.md— 只讲内部设计
不要把多个不相关主题塞进同一个文件。
文件名应直接反映内容：
- 好：
detail-xss-protection.md、detail-sensitive-field-encryption.md - 差：
detail-advanced-topics.md、detail-notes.md
不需要开头寒暄、不需要铺垫背景、不需要解释为什么写这篇文档。直接进入主题。
- 好：
cubo-logsystem-spring-boot 提供了结构化日志和动态日志级别调整能力。 - 差：
在现代微服务架构中，日志是非常重要的一环。本文将详细介绍如何使用日志系统。
能用代码块说明的，就不要用纯文字描述。
对于 Maven 依赖、配置文件、Java 代码，始终提供可直接复制的代码块，并标注语言类型：
```xml
<dependency>
<groupId>dev.dong4j</groupId>
<artifactId>cubo-logsystem-spring-boot-starter</artifactId>
</dependency>
```
```yaml
log:
level: INFO
```配置属性文档统一使用表格：
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
log.level |
String | INFO |
日志级别 |
不要用列表、代码块或纯文本来罗列配置项。
当对比关系超过 3 项时，用表格。当列举配置项、属性、类型时，用表格。
- 3 个以下的简单列举可以用列表
- 3 个以上的结构化数据用表格
[[目标文件路径|显示文本]]链接路径必须对应站点同步后的真实文件位置，而不是源码仓库的相对路径。
| 场景 | 正确写法 | 错误写法 |
|---|---|---|
| 模块主页 | [[arco-meta/arco-builder/index|构建框架总览]] |
[[arco-builder/index|构建框架总览]] |
| 子模块主页 | [[cubo-starter/cubo-logsystem-spring-boot/index|日志系统]] |
[[cubo-starter/cubo-logsystem-spring-boot|日志系统]] |
| 补充文档 | [[cubo-starter/cubo-rest-spring-boot/detail-xss-protection|XSS 防护]] |
[[detail-xss-protection|XSS 防护]] |
每个文档末尾用二级标题 ## 🔗 相关链接 收尾，保持风格一致：
## 🔗 相关链接
- [[arco-meta/arco-builder/index|构建框架总览]]
- [[arco-meta/arco-builder/arco-project-builder|构建逻辑抽象层]]当前开发不仅涉及团队协作，还涉及 AI Agent 协作。AI 友好意味着：
- 结构清晰，标题层级准确
- 有明确的代码示例和配置说明
- 有完整的错误码、状态码说明
- 有输入输出示例，而不仅仅是类型定义
不要只写"注入依赖即可"，而是给出完整的 Maven 坐标 + Java 代码 + 配置文件。
如果某个配置项有取值范围、互斥条件或依赖关系，明确写出来。
> [!注意]
> `log.async.enabled` 为 `true` 时，`log.async.ring-buffer-size` 才生效。接口文档不只是字段列表，还应该说明：
- 成功时返回什么
- 失败时返回什么错误码
- 各错误码对应的含义和建议处理方式
不只是单个接口，还要说明接口之间的调用关系和业务流程。比如：
## 创建订单流程
1. 调用 `POST /orders` 创建订单
2. 调用 `POST /payments` 发起支付
3. 支付成功后订单状态自动流转为 `PAID`新增或修改文档后，对照以下清单检查：
- 一级标题是否简洁且唯一
- 是否有可运行的代码示例
- 配置项是否使用表格
- 双向链接路径是否正确（尤其是
/index） - 相关链接是否放在文末
## 🔗 相关链接下 - 是否运行了
pnpm run dev验证链接无警告 - 文档文件是否已纳入 Git 管理（避免“更新于”显示异常，如
1970.01.01）
在源码模块下创建文件，运行 npm run sync，再运行 pnpm run dev 验证。
如果修改的是源码模块文档，在源码仓库中修改，然后重新同步。
在源码仓库中删除文件，运行 npm run sync，同步脚本会自动清理站点中的孤立文件。不要直接在站点仓库中手动删除同步产物。