指南文档规范

面向 guide 目录的统一写作、改写、校验规范。目标不是“把文档写长”，而是让整站文档在结构、措辞、示例、视觉层次和可信度上保持一致。

这份规范同时面向人工作者和后续批量改文档的 agent。

因此这里写的是可直接执行的统一规则，不是讨论稿。

目标

这份规范只解决四件事：

1. 统一整站文档的结构、文风和标题口径。
2. 让每篇文档都能先带读者跑通，再帮助读者理解，再帮助读者扩展。
3. 让所有结论和示例都基于源码、配置或可编译示例，而不是猜测。
4. 让 .vitepress 已有能力真正参与表达，而不是退化成普通 Markdown 长文。

判断标准只有两条：

• 读者能否快速找到主线。
• 读者能否相信文档里的结论和示例。

Agent 执行口径

如果由 agent 按本规范改写文档，统一按下面的顺序执行：

1. 先判定页面类型，再决定结构，不先下笔改文。
2. 必须先阅读文档对应的源码，才有资质修改文档。涉及框架行为、注册入口、中间件、模块接入方式时，先核对 E:\gitcode\spire；涉及 SqlSharp / 数据访问时，先核对 E:\gitcode\sqlsharp。未读源码之前，不得动笔改文，更不得凭空编造 API 名称（如 addSqlSharp()）。
3. 先找依据，再写结论；找不到依据时，宁可删掉旧结论，也不要补猜测。
4. 涉及仓颉语言、Option、match、if let、?.、??、安全转换 as 等语法和标准库行为时，优先核对 E:\gitcode\cangjie_runtime。
5. 涉及扩展库 API、扩展库推荐写法、扩展库常见模式时，优先核对 E:\gitcode\cangjie_stdx。
6. 涉及页面中的仓颉示例是否真的能通过时，优先在 E:\gitcode\demo 做编译验证。
7. E:\gitcode\spire-doc\模式匹配.md 这类专项写法文档可以作为表达风格参考，但不能覆盖源码、编译结果和运行库真实实现。
8. 改文档时，不只记录"当前项目已经怎么用"，还要主动挖掘源码已经暴露给开发者的能力和扩展点。

冲突处理规则只有一条：

• 旧文档、局部经验、习惯写法与源码冲突时，一律以源码和编译结果为准。

适用范围

本规范适用于 guide 下所有内容，尤其包括：

• guide/infrastructure
• guide/hosting
• guide/web
• guide/security
• guide/sqlsharp
• guide/scheduler
• projects

当前整站内容可以统一归为四类：

类型	当前目录示例	用途
总览页	spire/overview.md、web/overview.md、sqlsharp/overview.md	建立地图、说明边界、给出阅读顺序
学习页	infrastructure/configuration.md、security/authentication-jwt-bearer.md	带读者从不会到会
专题页	sqlsharp/queryable.md、scheduler/cron.md	集中讲一个子能力或一组规则
案例页	projects/blog/*.md	展示能力如何在真实项目中组合

硬性规则

以下规则是强约束，不是建议。

1. 结论必须有依据

涉及以下内容时，必须先核对源码、配置、README 或可运行示例：

• 默认值
• 生命周期
• 中间件顺序
• 参数绑定规则
• 认证授权行为
• SQL 生成行为
• 支持与不支持的能力边界
• 具体 API 名称、方法名、注解名、配置项名称

不允许用“应该是”“大概”“通常会”替代核实。

允许写“通常”的前提只有一个：该行为确实受条件影响，并且条件已经写明。

依据来源优先级

不同类型结论，统一按下面优先级取证：

结论类型	首选依据
框架行为、注册入口、中间件、模块接入方式	E:\gitcode\spire（源码、配置、README）
SqlSharp / 数据访问 / ORM 行为	E:\gitcode\sqlsharp（源码、配置、README）
仓颉语法、Option 行为、模式匹配写法	E:\gitcode\cangjie_runtime
扩展库 API、扩展库常见写法	E:\gitcode\cangjie_stdx
示例是否语法正确、是否能通过编译	E:\gitcode\demo
站内专项写法建议	E:\gitcode\spire-doc\模式匹配.md 等本地规范文档

补充规则：

• 本地规范文档只能总结和约束写法，不能反向定义语言能力。
• 如果 cangjie_runtime、cangjie_stdx 与旧文档表述不一致，以源码为准。
• 如果源码能证明 API 存在，但示例无法在 demo 编译通过，不能写成“已验证示例”。

2. 示例必须可验证

所有新写或改写的仓颉示例，提交前必须在 E:\gitcode\demo 中做语法或编译验证。

以这条为准：

Set-Location E:\gitcode\demo
cjpm build

补充规则：

• 如果示例依赖新包，先同步修改 E:\gitcode\demo\cjpm.toml 再验证。
• 如果示例来自现有项目源码，也必须整理成可以在 demo 中验证的形式后，才能作为“已验证示例”写入文档。
• 不能验证的示例，不得写成“推荐写法”或“最小示例”。
• 如果第一次构建失败，先区分是语法问题、依赖问题还是沙箱/环境问题；只有成功构建后，才可标记为“已验证”。

3. 不写手工“下一步”

站点已经有上一页/下一页导航。

因此：

• 不再使用 ## 下一步 作为固定章节。
• 需要补充跳转时，统一使用 ## 相关专题、## 延伸阅读 或正文内自然链接。

4. 保留标准技术术语

以下术语属于稳定技术词，不要为了“口语化”强行翻译掉：

• Web
• MVC
• JWT
• Bearer
• OpenAPI
• Cron
• SQL
• DbContext
• Queryable
• Identity Server
• HttpClient

需要弱化的是产品名、品牌名和内部实现名，不是标准技术名词。

5. 措辞必须明确

禁止这类模棱两可的表述：

• “这个一般也可以这样用”
• “大概就是”
• “你可以理解成差不多”
• “某种程度上”
• “通常来说它会自动处理”

必须改成可判断的句子，例如：

• “当参数未标注来源时，基本类型不会自动从查询字符串绑定。”
• “当前项目在 main.cj 中先注册路由，再注册认证与授权中间件。”
• “该页示例已在 E:\gitcode\demo 中通过 cjpm build 验证。”

6. 下规则时要交代原因

文档不只要告诉读者“应该怎么做”，还要尽量告诉读者“为什么要这么做”。

尤其是下面这几类内容，不能只给结论，不解释原因：

• 生命周期约束
• 注册顺序约束
• 中间件顺序约束
• 推荐模式或最佳实践
• 限制与边界

推荐写法：

• 先写规则本身
• 再写这条规则在防什么问题
• 最后再给一个最小示例或反例

例如，不要只写：

• “Singleton 不能依赖 Scoped。”

更好的写法是：

• “Singleton 不能依赖 Scoped。因为 Singleton 会被整个应用长期持有，而 Scoped 应该跟随请求或作用域结束而释放；一旦前者持有后者，就会把短生命周期对象错误地拉长，造成资源释放时机错乱或隐藏状态污染。”

7. 不要冗余

文档要完整，但不要重复。

统一要求：

• 同一个结论在相邻段落里不要换句话重复说两到三遍。
• 已经在表格里说清的内容，正文只补“怎么看”和“为什么”，不要整段重写表格。
• 已经在代码注释里点明的行为，代码后总结不要再逐行复述。
• 适用场景、核心问题、生产建议、常见问题 各自承担不同职责，不要把同一条结论在多个章节机械搬运。
• 能用一句话说清时，不要扩成一段口号式解释。

判断标准：

• 删掉这一句后，读者是否损失新信息。
• 如果没有损失，这一句大概率就是冗余。

统一页面类型与模板

1. 总览页模板

总览页负责导航，不负责展开全部细节。

推荐结构：

1. # 标题
2. 一句话摘要
3. ## 适用场景
4. ## 核心问题
5. ## 模块地图
6. ## 推荐阅读顺序
7. ## 当前边界
8. ## 相关专题

要求：

• 必须说明“这组内容解决什么问题”。
• 必须给出阅读顺序。
• 必须写清当前文档覆盖范围和未覆盖范围。
• 不能把总览页写成超长教程。

2. 学习页模板

学习页是最常见的页面类型。

推荐结构：

1. # 标题
2. 一句话摘要
3. ## 适用场景
4. ## 核心问题
5. ## 快速开始
6. ## 核心概念
7. ## 常见用法
8. ## 相关专题

可选章节：

• ## 前置条件
• ## 相关依赖
• ## 不适用场景
• ## 最佳实践
• ## 与其他模块组合
• ## 生产建议
• ## 常见问题
• ## 延伸阅读

3. 专题页模板

专题页用于承载规则密度更高的内容，例如：

• Cron 语法
• Queryable 查询规则
• 原生 SQL 规则
• 授权策略对比

推荐结构：

1. # 标题
2. 一句话摘要
3. ## 适用场景
4. ## 核心规则
5. ## 常见写法
6. ## 限制与边界
7. ## 常见问题
8. ## 相关专题

要求：

• 表格优先于大段罗列。
• 规则必须可验证。
• 高级原理优先放进折叠块。

4. 案例页模板

案例页不是 API 手册，而是“能力组合示范”。

推荐结构：

1. # 标题
2. 一句话摘要
3. ## 适用场景
4. ## 核心问题
5. ## 项目结构 或 ## 模块结构
6. ## 关键实现
7. ## 运行方式
8. ## 当前边界
9. ## 相关专题

要求：

• 必须明确“哪些能力已经落地，哪些只是扩展建议”。
• 不能把未接入能力写成现状。
• 关键结论必须回到实际仓库源码。

页面大纲规范

仅有页面类型还不够。

后续统一改文档时，每一篇都应先确定大纲，再进入正文改写。

1. 先出大纲，再写正文

统一顺序如下：

1. 先判定页面类型。
2. 先列出本页 H2 大纲。
3. 检查大纲是否只服务一个主问题。
4. 大纲通过后，再补正文、示例、提示块和交叉链接。

禁止直接一边写正文一边临时长出章节。

2. 大纲是强约束，不是参考目录

大纲的作用是固定页面主线，避免同类页面写成不同结构。

因此：

• 同类型页面优先保持同一批 H2 名称。
• 不要同一层混用“使用方式 / 怎么使用 / 接入方法 / 快速上手”这类重复含义标题。
• 没有必要的章节不要补。
• 缺少关键章节也不能省。

3. 每页 H2 数量控制

统一控制如下：

• 总览页：6 到 8 个 H2。
• 学习页：7 到 10 个 H2。
• 专题页：5 到 8 个 H2。
• 案例页：6 到 9 个 H2。

处理规则：

• 少于下限时，通常说明信息骨架不完整。
• 超过上限时，优先拆页，不继续堆章节。
• 如果某页必须超过上限，说明它很可能被判错了页面类型。

4. 各页面类型的标准大纲

下面的大纲不是“可参考”，而是默认标准骨架。

总览页标准大纲

默认使用：

1. ## 适用场景
2. ## 核心问题
3. ## 模块地图
4. ## 推荐阅读顺序
5. ## 当前边界
6. ## 相关专题

可选补充：

• ## 核心概念
• ## 延伸阅读

限制：

• 总览页通常不写 ## 快速开始。
• 总览页不展开长代码示例。
• 总览页不承载大段规则表。

学习页标准大纲

默认使用：

1. ## 适用场景
2. ## 核心问题
3. ## 快速开始
4. ## 核心概念
5. ## 常见用法
6. ## 相关专题

可选补充：

• ## 前置条件
• ## 相关依赖
• ## 不适用场景
• ## 最佳实践
• ## 可扩展能力
• ## 与其他模块组合
• ## 生产建议
• ## 常见问题
• ## 延伸阅读

限制：

• 没有最小示例时，不应进入 ## 核心概念。
• ## 生产建议 不得提前到 ## 快速开始 之前。
• ## 常见问题 只收真实疑问，不要重复正文结论。
• ## 最佳实践 不是口号区，必须给出“什么情况下用、推荐结构是什么、为什么这样组织”。
• ## 与其他模块组合、## 生产建议、## 常见问题 都不是默认必备章节；没有新增信息时直接省略。

专题页标准大纲

默认使用：

1. ## 适用场景
2. ## 核心规则
3. ## 常见写法
4. ## 限制与边界
5. ## 常见问题
6. ## 相关专题

可选补充：

• ## 规则对比
• ## 执行流程
• ## 扩展点
• ## 延伸阅读

限制：

• 专题页优先讲规则，不先讲历史背景。
• 同页内不要同时展开多个互不依赖的子专题。
• 规则很多时，优先拆成多个专题页，而不是一个大全页。

案例页标准大纲

默认使用：

1. ## 适用场景
2. ## 核心问题
3. ## 项目结构 或 ## 模块结构
4. ## 关键实现
5. ## 运行方式
6. ## 当前边界
7. ## 相关专题

可选补充：

• ## 请求流程
• ## 数据流
• ## 可扩展能力
• ## 排错入口
• ## 延伸阅读

限制：

• 案例页不能写成组件 API 列表。
• 案例页的 ## 关键实现 必须回到真实仓库代码。
• 案例页中的扩展建议必须明确标注为“可扩展方向”而不是现状。

5. 标题命名白名单

为减少同义标题漂移，H2 优先从下面这组标准标题中选：

• 适用场景
• 核心问题
• 运行模型
• 前置条件
• 相关依赖
• 快速开始
• 最佳实践
• 核心概念
• 核心规则
• 常见用法
• 常见写法
• 模块地图
• 项目结构
• 模块结构
• 关键实现
• 执行流程
• 请求流程
• 数据流
• 可扩展能力
• 扩展点
• 与其他模块组合
• 生产建议
• 限制与边界
• 当前边界
• 常见问题
• 排错入口
• 推荐阅读顺序
• 相关专题
• 延伸阅读

如果必须新增标题，要求如下：

• 必须比现有标题更准确，而不是换个说法。
• 必须能长期复用，不是只适合当前一篇。
• 不要引入宣传性或口语化标题。

6. 大纲审核问题

每篇文档在开始正文前，至少先回答这 7 个问题：

1. 这页属于哪一种页面类型？
2. 这页只解决哪一个主问题？
3. 为什么这些 H2 的顺序最合适？
4. 读者会先看到最小路径，还是先被背景说明拖住？
5. 哪些章节必须保留，哪些章节其实应该拆出去？
6. 文末是放 相关专题，还是放 延伸阅读？
7. 这页有没有把源码已经给出的能力和扩展点挖出来，并且和“当前已用能力”区分开？

7. 改写保全规则

改写旧文档时，不能只追求结构更整齐，还必须保证知识点不丢。

统一要求：

• 先列出旧文档已有的核心概念、规则、边界和示例主题。
• 再决定这些内容是保留、合并、上移、下移，还是拆到其他页面。
• 只允许“重组”，不允许无依据地删掉核心知识点。
• 如果某个知识点不再放在当前页，必须有明确去向，通常通过 相关专题 或新页面承接。

重点检查：

• 核心概念是否还在
• 关键行为规则是否还在
• 生命周期、作用域、校验、默认行为这类高频知识点是否还在
• 原文里有价值的“最佳实践 / 推荐模式 / 模块封装方式”是否仍被保留
• 原来有示例支撑的知识点，改写后是否仍有示例支撑

内容组织原则

1. 一页只解决一个主问题

每一页都必须能回答一句话：

• “读完这页，读者到底掌握了什么？”

如果一个页面同时想讲：

• 是什么
• 怎么用
• 为什么这样设计
• 如何在真实项目落地
• 所有高级扩展

通常说明页面过载了，需要拆分。

2. 固定采用“三段式学习顺序”

每篇学习页默认遵循：

1. 先跑通
2. 再理解
3. 再扩展

对应到写作上：

• 先给可运行最小示例
• 再解释核心概念和心智模型
• 最后补生产建议、组合方式和边界

3. 章节过渡必须自然

章节名可以统一，但不能写得像硬切目录。

规则如下：

• 所有页面统一使用 核心问题 回答"它解决什么问题"，不再使用 这是什么。
• 核心问题、运行模型 这类章节的首句，必须直接回答标题，不要先铺垫空话。
• 适用场景 结束后，下一节要能自然承接，不能让读者感觉突然换题。

4. 先常见路径，后高级路径

必须优先讲：

• 默认写法
• 最常见接入方式
• 大多数读者的第一条路径

高级路径只在以下情况展开：

• 和默认路径行为明显不同
• 生产环境必须知道
• 当前页主题本来就是高级专题

4.2 学习页尾部章节收敛规则

## 与其他模块组合、## 生产建议、## 常见问题 很容易写成重复区，后续统一按“能省则省、能短不长”处理。

统一规则：

• 这三个章节默认都是可选项，不再为了凑模板强行补齐。
• 如果内容只是重复正文结论、换个说法再讲一遍，直接删除。
• 如果某条信息已经有明确承接页，优先放到 ## 相关专题，不要在当前页重讲。
• 这三个章节总和通常控制在 15 到 30 行内；超过后优先合并、删减或拆页。

## 与其他模块组合 统一写法：

• 只保留“组合后行为会变化”或“读者不容易自己推出来”的集成点。
• 优先写成 2 到 4 条短列表，每条一句到两句。
• 能直接链接到对应专题页时，不在当前页展开代码大段。
• 只是“这个模块也能一起用”时，不单开本节。

## 生产建议 统一写法：

• 只收敛会影响稳定性、排错成本、安全性或部署结果的规则。
• 优先写成 3 到 5 条短列表，每条先给规则，再补一句原因。
• 已在 最佳实践、核心规则 或正文中讲透的内容，不再重复进本节。
• 口号式表述一律删除，例如“建议合理设计”“注意模块化”。

## 常见问题 统一写法：

• 只保留真实高频疑问或容易误判的行为边界。
• 优先控制在 2 到 4 个问题，每个问题回答 2 到 4 行。
• 如果问题答案只是正文原句复读，删除该问题。
• 如果某类问题已经有独立 FAQ 页，当前页只保留入口链接，不再复制答案。

4.3 最佳实践 章节写法

当页面包含 ## 最佳实践 时，统一按下面的要求写：

• 必须基于当前源码里已经存在的组织方式、扩展入口或推荐接入模式。
• 必须回答三个问题：为什么这样组织、调用方应该怎么落地、这样做给调用方留下了什么替换空间。
• 不能只写“推荐使用 addXxx()”“建议模块化”这类没有展开的提醒。
• 如果主题涉及注册、模块装配、Builder、配置回调或多实现扩展，最佳实践 至少要给一个可复用代码示例。
• 如果旧文档里已有高价值的最佳实践，改写时应优先保留并重组，而不是删除后换成抽象总结。

5. 主动挖掘能力与扩展点

文档不能只停留在“项目里现在这样写”。

如果源码已经给开发者留下能力入口、可替换点或扩展面，文档应尽量识别并表达出来。

优先检查这些位置：

• interface
• abstract class
• 可继承实现或可替换实现
• Builder、注册器、模块装配入口
• 扩展函数、工厂函数、策略接口
• 配置对象、选项对象、回调参数
• 中间件管线、过滤器、行为链
• 泛型约束、类型参数、可替换依赖

统一写法要求：

• 先写“当前项目已落地的能力”。
• 再写“源码已支持但当前页示例未展开的能力”。
• 最后才写“可扩展方向”。

这三类内容不能混写。

必须明确区分：

• 已落地能力：当前项目或当前示例已经使用。
• 已支持能力：源码能证明存在，但当前项目不一定已使用。
• 可扩展方向：基于现有扩展点可以继续实现，但当前仓库未提供现成落地代码。

如果只是“理论上可以”，但找不到源码入口，不要写成扩展点。

文风规范

应该这样写

• 先结论，后解释
• 先行为，后原理
• 一段只讲一个重点
• 多用短句
• 多用主动句
• 多用确定句

推荐句式：

• “这个能力解决的是……”
• “默认行为是……”
• “只有在……时，才需要……”
• “当前项目中，这个结论对应……”

不应该这样写

• 修辞堆砌
• 口号式表达
• 连续反问
• 一段里塞多个结论
• 还没给代码就先讲很长抽象理论

明确性规则

以下词要尽量少用，除非后面立刻给条件：

• 一般
• 通常
• 大概
• 基本上
• 某种程度
• 相对来说

如果必须使用，下一句必须补全条件。

标题与菜单命名规则

页面标题

• 一级标题：页面主题
• 二级标题：任务导向，例如“快速开始”“核心概念”“常见用法”
• 三级标题：具体能力点，例如“参数绑定”“路由约束”“查询扩展”

禁止：

• 一级标题写成宣传语
• 二级标题写成修辞句
• 三级标题写成难以扫描的长句

菜单命名

菜单优先使用：

• 领域词
• 能力词
• 标准技术名词

避免直接使用：

• 品牌名
• 仓库名
• 纯内部类名

当前菜单命名口径以现有侧栏为准：

• 开始
• 框架指南
• 专题指南
• 实战案例
• 基础设施
• 宿主
• Web
• 安全
• 性能
• 数据访问
• 任务调度

总览命名

在一个分组内部，首篇入口统一叫 总览。

只有当子分组本身也需要独立地图时，才使用：

• 认证总览
• 授权总览

术语规则

同一目录内，同一概念只保留一个主称呼。

例如：

• 统一用“配置管理”，不要同层混用“配置系统 / 配置中心 / 配置模块”
• 统一用“日志记录”，不要同层混用“日志系统 / 日志框架 / 日志能力”

如确有别名：

• 第一次出现时说明一次
• 之后只保留一个主称呼

示例规范

示例主题

同一组学习页的示例要围绕同一个业务主线展开，避免一页一个业务名导致读者反复切换上下文。

guide/infrastructure 目录默认围绕 Chat 应用组织示例，优先使用这些稳定角色：

• ChatOptions：模型、密钥、超时、基础地址等配置。
• ChatClient：对外暴露的主服务。
• IChatTransport：可替换的模型提供方或传输层。
• ChatSession：请求级、会话级或流式调用状态。
• ChatPromptBuilder：轻量、可重复创建的辅助服务。

处理规则：

• 配置、选项、DI、日志、HTTP、缓存等基础设施页，优先复用同一批 Chat 类型。
• 如果当前能力天然需要别的领域对象，必须说明为什么换主题；不要只为了“更像业务”临时改成订单、用户、商品。
• 示例里的分类名、配置键、服务名也要跟随主题，例如 chat:model、chat.transport、chat.prompt。
• 旧文档改写时，优先把有价值的示例迁移到 Chat 主线，而不是直接删除知识点。

示例分层

每篇学习页至少应具备以下三层之一，复杂页面最好三层都有：

1. 最小示例
2. 推荐写法
3. 生产写法

区别如下：

层级	目的	特征
最小示例	先跑通	最短路径，依赖最少
推荐写法	日常项目可直接用	结构清晰，符合站内推荐模式
生产写法	展示完整接入	会引入配置、DI、日志、事务、权限等

关键知识点必须有示例

以下内容如果在页面中展开说明，原则上都要配示例：

• 生命周期
• 作用域
• 校验开关
• 默认解析行为
• 注册顺序影响
• 扩展点或替换点

不能只给表格或结论，不给代码支撑。

如果某个知识点不适合放完整示例，至少要给最小片段，并明确提示读者重点看哪一行。

示例来源规则

示例来源分两类：

类型	规则
从源码摘录	必须确认和当前源码一致
为文档新写	必须在 E:\gitcode\demo 中验证

推荐做法：

• 先从真实源码提取
• 再整理成最小可解释版本
• 最后放到 demo 做语法或编译验证

示例前置说明

长代码块前，必须加一句引导，告诉读者先看哪里。

推荐写法：

• “先看这三行：……”
• “这里只需要先理解注册入口。”
• “这段代码重点看参数绑定和返回值。”

示例后置说明

代码块结束后，必须补一小段总结：

• 这段代码解决了什么问题
• 当前应该记住什么
• 和上一段相比新增了什么

代码块规则

• 仓颉代码统一使用 cangjie
• 前端代码按实际语言使用 ts、tsx、css
• 配置使用 json、toml、yaml
• 命令行使用 bash 或 powershell
• Mermaid 图统一使用 mermaid

不要省略 info string。

补充要求：

• 示例中的关键行尽量加短注释，告诉读者这一行为什么重要。
• 注释优先解释“行为”和“边界”，不要解释显而易见的语法。
• 用于证明规则的示例，注释里要点明“这一行验证了什么”。
• 最佳实践 里的示例优先写成“读者可以直接照着组织项目”的完整片段，而不是只截几行结论。
• 多行回调、配置委托、工厂委托统一写成 { options =>、{ options, sp => 这类形式，把参数箭头放在左花括号同一行，不要拆成单独一行的 options =>。

示例校验流程

每次新增或改写示例，按以下顺序执行：

1. 确认该示例要证明什么结论
2. 回到源码、配置或项目仓库核对结论
3. 将示例整理到 E:\gitcode\demo
4. 根据需要补充 demo/cjpm.toml 依赖
5. 运行 cjpm build
6. 通过后再写入文档

最低要求：

• 文档里的仓颉示例必须是“验证过的示例”
• 不能先写文档，再假设代码能编译

基于源码写结论的规则

以下内容必须以具体文件为依据：

• 默认认证方案
• 中间件调用顺序
• 默认连接方式
• 容器注册方式
• 参数绑定规则
• 事务边界
• 查询规则
• 视图或实体的字段行为

源码仓库对应关系：

文档涉及的领域	对应源码仓库
框架行为、注册入口、中间件、模块接入	E:\gitcode\spire
SqlSharp / 数据访问 / ORM	E:\gitcode\sqlsharp
仓颉语法、标准库行为	E:\gitcode\cangjie_runtime
扩展库 API	E:\gitcode\cangjie_stdx
示例编译验证	E:\gitcode\demo

建议作者在改文时先记下依据来源，例如：

• E:\gitcode\spire\soulsoft_web_authorization\src\AuthorizationServiceCollectionExtensions.cj
• E:\gitcode\spire\soulsoft_extensions_http\src\HttpClientFactoryServiceCollectionExtensions.cj
• E:\gitcode\sqlsharp\soulsoft_extensions_sqlsharp\src\ISqlsharpServiceExtension.cj
• E:\gitcode\spire\soulsoft_web_mvc\src\MvcServiceCollectionExtensions.cj
• cangjie_runtime/stdlib/libs/std/core/option.cj
• cangjie_stdx/src/stdx/serialization/serialization/serializable.cj

源码路径是作者核验用的，禁止出现在最终文档正文中。 文档面向的是读者，不是代码审查者。源码路径、文件名、行号等信息只保留在作者的查证记录里，不得写入 ## 章节正文、代码注释、提示块或任何读者可见的位置。

识别扩展点时，额外优先检查：

• Builder 或模块注册入口
• 配置结构与默认值
• 抽象接口及其实现
• 回调签名与扩展函数
• 泛型参数和类型约束
• README 中声明但正文未展开的能力

如果找不到依据，先不要写结论。

VitePress 能力使用规范

当前站点已明确可用的能力包括：

• tip / warning / info / details
• code-group
• mermaid
• 自定义组件 DocTip
• 页面导航与本地搜索

这些能力必须按用途使用，不能想到什么就加什么。

1. tip

用途：

• 一句话记忆点
• 默认推荐路径
• 低风险提醒

适合：

• “第一次接入时，先用默认配置”
• “这三个参数最重要”

不适合：

• 装正文
• 写长解释

2. warning

用途：

• 常见误用
• 容易踩坑的行为
• 与直觉不一致的默认规则

适合：

• 参数不标注来源会绑定失败
• 某行为只在生产环境生效
• 并发选项可能导致线程堆积

3. info

用途：

• 中性补充信息
• 版本、前提、上下游说明
• “这不是错误，但要知道”

适合：

• 该能力依赖某个包
• 该行为只在某目录结构下成立

4. details

用途：

• 高级原理
• 可选扩展
• 不影响首次阅读的深入说明

必须使用 details 的场景：

• 原理解释超过 10 行
• 同页需要保留进阶内容，但不想打断主线
• 收录排障、限制、兼容性细节

5. code-group

用途：

• 同一目标的多种写法对照
• 开发环境 / 生产环境
• 直接使用 / DI 集成
• 最小示例 / 推荐写法

只有满足“目标相同、写法不同”时才使用 code-group。

不要拿 code-group 装不相关代码。

优先使用 code-group 的典型场景：

• 类型映射 / 实例注册 / 工厂注册
• Singleton / Scoped / Transient
• 直接使用 / Builder 接入 / 模块入口接入
• 显式 key / 继承 key / 注入当前 key

6. mermaid

用途：

• 模块关系图
• 生命周期图
• 调用链图
• 请求流图
• 数据流图

适合放在：

• 总览页
• 中间件顺序页
• 容器和模块关系页
• 事务、变更跟踪、任务触发等机制页

不适合：

• 为了“看起来高级”硬画图
• 一个表格就能说清的关系

补充要求：

• 当页面出现复杂依赖关系、调用链、模块装配关系、生命周期流转或架构分层时，优先考虑使用“文字 + 箭头”的图来表达。
• 图里的节点名称优先使用业务词、模块词、接口词，不要堆内部实现细节。
• 图的目标是先让读者看懂“谁依赖谁、谁调用谁、谁流向谁”，不是展示所有实现类。

推荐形式：

也就是说，复杂关系优先画成“文字节点 + 箭头方向”的结构图，再由正文补充规则和边界。

7. DocTip

当前自定义组件来源：

• .vitepress/theme/index.ts
• .vitepress/theme/components/DocTip.vue

当前支持的类型只有：

• primary
• warning
• danger

统一用途如下：

类型	用途
primary	本页唯一必须记住的一句话
warning	高风险误用提醒
danger	会导致明显错误或错误结论的场景

使用规则：

• 每页最多使用一次 DocTip
• 只放一句核心结论
• 不装长段解释
• 不要写成口号、步骤口令或空泛提醒
• 如果摘要已经能清楚表达主结论，可以不放 DocTip

示例：

<DocTip type="primary">
`getOrThrow<T>()` 适合必需依赖，缺失注册会立即抛异常。
</DocTip>

8. 表格

优先用表格表达：

• 对比
• 规则范围
• 参数说明
• 能力边界
• 选型差异

不要把长段叙述硬塞进表格。

9. 图片与截图

优先级：

1. 代码
2. 表格
3. Mermaid
4. 截图

截图只适合：

• UI 页面
• Swagger / OpenAPI 页面
• 需要展示结果外观的场景

不适合用截图代替代码和配置。

视觉与排版细则

这一节不是“审美建议”，而是站内统一排版规则。

目标只有一个：让不同作者写出来的页面，在扫描节奏、重点呈现和视觉层次上保持一致。

1. 首屏结构

所有页面默认按这个顺序组织首屏：

1. # 标题
2. 一句话摘要
3. 可选的强调块：DocTip 或 tip / info
4. ## 适用场景

约束如下：

• 标题下不要直接堆长段背景说明。
• 首屏只允许出现一个强调块。
• 首屏优先解决“这页讲什么、适合谁、先看什么”。
• 总览页的图示或 Mermaid，不要放在摘要前面。

2. 摘要格式

摘要统一使用引用块：

> 这一页说明什么、适用于什么场景、读完后能得到什么。

摘要规则：

• 只写一句话。
• 优先控制在 30 个中文字符到 50 个中文字符内，最多不超过 2 行。
• 只写结果和边界，不写背景铺垫。
• 不在摘要里放列表、链接、长代码或多个并列结论。

3. 段落长度

正文段落按下面规则控制：

• 一段只讲一个结论。
• 单段优先控制在 2 到 5 行。
• 超过 6 行时，优先拆段，不要继续累加从句。
• 连续 3 段以上纯说明文字后，优先补一个表格、示例、提示块或小结。

4. 列表规则

列表只用于真正的并列信息：

• 条件
• 步骤
• 对比项
• 检查项

约束如下：

• 同一层列表优先控制在 3 到 7 项。
• 超过 7 项时，先分组，再列出。
• 列表项尽量保持同一语法结构。
• 不要连续出现多层嵌套列表；需要再分层时，优先改成二级标题或表格。

5. 表格规则

表格只用于比正文更清楚的场景：

• 参数说明
• 能力对比
• 规则范围
• 适用与不适用边界

约束如下：

• 单表优先不超过 6 列。
• 单元格内优先不超过 2 句短句。
• 代码、长解释、排障步骤不要塞进表格。
• 表格后最好补一句总结，说明读者应该看哪一列、记住什么差异。

6. 代码块规则

代码块统一遵循以下规则：

• 必须带 info string。
• 长代码块前必须先写一句“先看哪里”。
• 代码块后必须补一句“这段代码解决了什么”。
• 连续 3 个代码块之间不能没有解释文字。

长度控制：

• 20 行以内：可以直接展示。
• 21 到 30 行：建议加行内说明或拆成两个片段。
• 31 到 50 行：必须先给阅读提示，并优先拆成“注册入口 / 核心逻辑 / 返回结果”之类的片段。
• 超过 50 行：除源码导读页外，一律拆分，不直接整段贴出。

code-group 使用规则：

• 只用于“同一目标，不同写法”的对照。
• 同组优先不超过 3 个标签页。
• 不要把互不相关的代码放进同一个 code-group。

7. 提示块与强调组件

当前站点可用强调能力包括：

• tip
• warning
• info
• details
• DocTip

统一数量控制：

• DocTip：每页最多 1 个。
• warning：每页优先不超过 2 个。
• tip + info + warning + DocTip 合计优先不超过 3 个。
• details 不计入上面的数量，但必须确实承担折叠作用。

使用规则：

• DocTip 用于本页唯一必须记住的一句话。
• DocTip 由于当前组件是大字号、居中布局，只适合一句短句，不适合列表和长解释。
• tip 只写推荐路径和低风险提醒。
• warning 只写真实踩坑点、错误配置或错误认知。
• info 只写中性前提、依赖条件、版本差异。
• details 只收纳不影响首次阅读主线的内容。

必须改用 details 的场景：

• 原理说明超过 10 行。
• 排障说明会打断主线。
• 兼容性、限制、扩展写法只对部分读者有用。

8. Mermaid 使用规则

Mermaid 只在这几类页面中优先使用：

• 模块关系
• 请求链路
• 生命周期
• 任务触发流程
• 数据流或事务流

约束如下：

• 每张图只表达一个主关系。
• 单页优先不超过 2 张 Mermaid 图。
• 能用表格直接说清的内容，不画图。
• 图后必须补一句“这张图应该怎么看”。
• 图前后要回到正文结论，不要让 Mermaid 变成孤立插图。

9. 截图规则

截图只用于这些场景：

• 页面外观
• Swagger / OpenAPI 展示结果
• 控制台输出结果
• 配置完成后的可视化效果

统一约束：

• 不允许用截图代替代码、配置和命令。
• 截图必须服务于“展示结果”，不是“承载信息主体”。
• 截图下方最好补一句说明，告诉读者应该看哪里。
• 如果截图里包含关键配置，同页必须同时给出文本版配置或代码片段。

10. 标题密度

标题层级按下面规则控制：

• 一级标题只保留 1 个。
• 二级标题优先控制在 5 到 8 个。
• 单个二级标题下的三级标题优先不超过 4 个。
• 整页三级标题明显过多时，优先拆页，不继续下钻四级标题。

经验规则：

• 如果一页已经出现大量 H3，并且开始依赖 H4 才能组织内容，通常说明这一页应该拆成专题页。

11. 链接与收尾区域

链接分两类处理：

• 正文内链接：用于当前主线确实依赖的内容。
• 文末链接：统一放进 ## 相关专题 或 ## 延伸阅读。

约束如下：

• 正文同一段里优先只放 1 个链接。
• ## 相关专题 优先放 2 到 4 个链接。
• ## 延伸阅读 只补充真正有扩展价值的内容，不做目录镜像。
• 不要在文末堆 6 个以上离散链接。

12. 分隔线规则

统一要求：

• 不要在每个章节之间机械插入 ---。
• 只有在“正文结束，下面进入附录、排障、补充材料”时，才考虑使用分隔线。
• 如果不用分隔线也能靠标题自然分段，就不要额外加视觉分隔。

交叉链接规则

什么时候必须加交叉链接：

• 当前页依赖另一个基础能力
• 当前页是某专题的实现页
• 当前页和案例页之间有明显对应关系

统一放置位置：

• 总览页使用 ## 相关专题
• 学习页或专题页使用 ## 相关专题 或 ## 延伸阅读

不要再使用 ## 下一步。

每篇文档的改写流程

改写任意一篇文档时，按下面流程执行：

1. 先判定页面类型：总览页、学习页、专题页、案例页
2. 先阅读文档对应的源码仓库：框架行为核对 E:\gitcode\spire，SqlSharp / 数据访问核对 E:\gitcode\sqlsharp，确认结论依据。未读源码之前，不得动笔改文。
3. 如果页面涉及仓颉语言语法或标准库行为，补查 E:\gitcode\cangjie_runtime；如果涉及扩展库行为，补查 E:\gitcode\cangjie_stdx
4. 如需判断写法取舍，可参考 E:\gitcode\spire-doc\模式匹配.md，但最终仍以源码和编译结果为准
5. 同时检查当前源码是否暴露了值得说明的能力入口、替换点、扩展点，并区分"已落地""已支持""可扩展方向"
6. 确认本页只解决一个主问题
7. 先写最小示例，再补核心概念
8. 把示例放进 E:\gitcode\demo 验证
9. 再决定是否加入 tip / warning / details / code-group / mermaid / DocTip
10. 最后统一术语、标题和链接

审核清单

每篇文档提交前至少检查以下问题：

结构

• 是否符合对应页面类型模板
• 是否先跑通，再解释，再扩展
• 是否存在不必要的第三层、第四层标题堆叠
• 改写旧文档时，原有核心概念和关键知识点是否仍被保留或明确迁移

正确性

• 所有结论是否有源码或配置依据
• 所有仓颉示例是否在 E:\gitcode\demo 验证过
• 所有 API 名称、注解名、配置项名称是否和源码一致

文风

• 是否存在模棱两可的句子
• 是否存在修辞化、宣传化表达
• 是否每段只讲一个重点
• 关键规则、限制和最佳实践是否解释了“为什么”，而不是只下结论
• 是否存在相邻段落、表格与正文、代码注释与代码后总结之间的重复表达

体验

• 是否给出了最小示例
• 关键知识点是否配了示例，而不是只给结论
• 如果存在 最佳实践，它是否给出了可复用结构，而不是空泛建议
• 遇到复杂关系、依赖或架构时，是否优先使用了“文字 + 箭头”的图来降低理解成本
• 长代码块前是否告诉读者先看哪里
• 示例关键行是否加了必要的短注释
• 是否合理使用了至少一种 VitePress 能力改善阅读层次
• 是否补充了必要的交叉链接

命名

• 菜单文案是否使用统一口径
• 页面标题是否清晰、可扫描
• 术语是否在同层目录内保持一致

最终原则

整站文档统一遵循以下原则：

• 先证据，后结论
• 先最小路径，后完整能力
• 先常见场景，后高级场景
• 先帮助读者完成任务，再解释设计原理
• 先统一结构和措辞，再追求页面效果

如果某篇文档在“结构、可信度、明确性、可验证性”这四项里有任意一项不达标，就不算完成。