Rhost 文档规范

description: 约定 docs/ 四类文档分类、目录结构、命名、写作格式、模板与代码同步维护要求
created: 2026-10-06 22:05:00
updated: 2026-10-06 23:34:18

1. 目的

文档与代码同属交付物。本规范解决三个问题：

放哪里——任何一个文档主题都有唯一、可预期的归属目录；
怎么写——统一头部元信息、结构与 Markdown 风格，读者不需要重新适应每篇文档；
怎么保鲜——约定更新时间维护与代码同步义务，杜绝"文档比代码旧两个版本"。

本规范基于 Diátaxis 文档体系，按 Rhost（Tauri 2 + Rust + Vue 3，中小型项目）的实际情况裁剪，不追求大而全。

2. 文档体系：四类文档

类别	目录	回答的问题	典型读者	写作姿态
教程 Tutorial	`getting-started/`	"我怎么从零跑通？"	新来的开发者	线性步骤，每步有验证点，保护学习者不被分支问题打断
操作指南 How-to	`guides/`	"我怎么完成 X 任务 / 解决 X 报错？"	已有基础的开发者	任务导向，直奔步骤与命令，不解释背景
技术参考 Reference	`reference/`	"这个命令/帧/字段的精确定义是什么？"	正在写代码的人	客观、完备、无教程化，只写含义、类型、默认值
深度解释 Explanation	`explanation/`	"为什么是这样设计的？"	贡献者、维护者	讲背景、取舍、约束与后果，可以讨论与论证

判别的快捷方式：学一遍 → tutorial；做一件事 → guide；查一个定义 → reference；理解为什么 → explanation。

一篇文档允许以某一类为主、在结尾用"另见"链接指向其他类文档，但不要把四种写法混在同一篇正文里（典型反例：在 IPC 参考里大段教环境搭建）。

3. 目标目录结构

docs/
├── index.md                    # VitePress 站点首页（home 布局，文档总入口）
├── .vitepress/                 # VitePress 配置（config.mts；dist/cache/.temp 不入库）
├── getting-started/            # 教程：环境准备、首次启动、第一个连接
├── guides/                     # 操作指南：构建、开发、排障、升级
│   └── troubleshooting/        # 具体报错/异常现象的排查手册
├── reference/                  # 技术参考：IPC 命令、二进制帧、配置 schema、设置项
├── explanation/
│   ├── architecture.md         # 整体架构与通信协议（为什么这样分层）
│   └── design/
│       ├── docs-spec.md        # 本规范
│       ├── applog-design.md    # 各特性设计方案（feature-design.md）
│       └── decisions/          # ADR 架构决策记录（ADR-NNN-kebab-title.md）
└── assets/                     # 图片资源统一存放，禁止散落在 md 同级
    ├── screenshots/
    └── diagrams/

约定：

中小型项目不预建 faq/、api/、translations/、examples/ 等目录；FAQ 并入 guides/troubleshooting/，IPC/帧参考放 reference/，确有需要再拆；
文档站点使用 VitePress，内容根目录即 docs/：配置放 docs/.vitepress/config.mts，首页为 docs/index.md（路由 /）；站点依赖与 docs:dev / docs:build 脚本在仓库根 package.json；docs/.vitepress/ 的 dist、cache、.temp 已加入 .gitignore；
新增文档后必须在 config.mts 的 nav/sidebar 同步登记，link 不带 .md 扩展名；除站点首页与配置外，普通文档仍保持纯 Markdown 可直接阅读，不使用其他站点专属语法；
站点经 GitHub Actions（.github/workflows/docs.yml）推送到 main 自动部署到 GitHub Pages：仓库 Settings → Pages → Source 选 GitHub Actions；base 不写死，由 CI 用 configure-pages 的 base_path 经 DOCS_BASE 环境变量注入（项目页 /<repo>/、用户主页 / 自动适配），本地 dev/build 默认根路径，禁止在 nav/sidebar 手写仓库名前缀；
根目录只保留 README.md（简介 + 极简上手 + 跳转 docs/）、LICENSE；长篇内容一律进 docs/，不把万字文档塞进根 README。

4. 文件命名

一律小写英文 + kebab-case：config-import-export.md；禁止空格、驼峰、中文文件名；
特性设计文档统一 -design 后缀：<feature>-design.md（如 applog-design.md）；
排障文档以"现象/对象"命名，让读者从文件名就能判断是否与自己的问题相关：vim-utf8-locale.md；
ADR 文件名固定 ADR-NNN-<kebab-title>.md，三位序号、序号只增不回收；
单文件正文建议不超过 400 行；超出时优先按主题拆分；确实不宜拆分的长文，在头部块后给出章节目录（TOC）。

5. 文档头元信息

每个文档一级标题之后、正文之前，用 > 引用块给出元信息，只保留以下四个字段，顺序固定为：摘要 → 创建时间 → 更新时间 → 作者。先一句话概括文档是什么，再看时间信息，最后看作者，阅读逻辑最顺。

字段	必需性	写法
`description`（摘要）	必填	一句话概括文档核心内容，80 字以内；只写"是什么"，不写背景铺垫与口号
`创建时间`	必填	文档初次编写时间 `YYYY-MM-DD HH:mm:ss`（24 小时制、本地时间），填写后永不修改
`更新时间`	必填	最近一次实质性内容修订时间 `YYYY-MM-DD HH:mm:ss`，有实质改动才更新；仅订正错别字等不动正文语义的修改可不更新
`作者`	可省略	撰写人或团队；多人用逗号分隔

示例：

markdown

# 应用日志（App Log）设计方案与规范

> description: 应用日志的采集、缓冲、面板输出、持久化与轮转设计
>
> created: 2026-10-05 14:30:00
>
> updated: 2026-10-05 14:30:00
>
> author:

补充约定：

除上述四个字段外，头部不再放其他字段；文档的覆盖范围、边界、关联代码、前置条件等信息一律在正文中交代（设计文档的放置位置见 §7）；
头部不承担状态管理：不写"草稿 / 已落地 / 已废弃"等状态词；文档是否与当前实现一致、是否已废弃，由正文内容与 git 历史体现；
例外一：§8 ADR 模板中的"状态"是决策生命周期状态（提议 / 已采纳 / 已替代），属于决策记录的正文属性，不是文档头元信息，照常保留；
例外二：docs/index.md 是 VitePress home 布局的站点入口，使用其 layout: home frontmatter（hero/features），不套用四字段头部；其余所有文档必须套用。

6. Markdown 写作规范

每篇文档恰好一个一级标题（与文件名表意一致）；正文从 ## 开始逐级递进，不跳级；
内部链接一律相对路径：同目录 [x](./x.md)、跨目录按实际层级回退；迁移文件时必须修正链接；
代码块必须标注语言（rust/ts/vue/bash/json/text）；所有命令与配置保证可直接复制运行，给完整示例而非片段，除非片段本身就是讨论对象；
禁止模糊表述。不写"简单配置一下即可"，要写出具体字段、取值与默认值；
对照、清单、字段定义优先用表格；步骤用有序列表；并列要点用无序列表；
正文以中文为主；命令、标识符、协议字段、报错原文等保留英文原文，不做翻译（如 spawn_blocking、KEY_ENCRYPTED:）；
引用源码位置写从仓库根开始的路径，如 src-tauri/src/ssh/frame.rs，让读者能直接定位；
图片统一放 docs/assets/ 对应子目录并集中引用，禁止图片散落在 md 同级目录；截图必须来自当前版本，过时截图随功能改动更新或删除；
强调"必须/禁止"的约束用加粗，约束条目优先用列表逐条陈述，不埋在长段落里。

7. 设计文档（`*-design.md`）的结构要求

设计文档回答"为什么这样做 + 做成什么样"。除 §5 的头部外，正文按下列骨架组织（按特性大小裁剪，但 1、2、3、9 项不得省略）。原头部承载的"范围 / 边界 / 关联代码"信息改在第 1 节开头用一小段交代（覆盖什么、不覆盖什么、涉及哪些源码路径）。

设计目标与硬约束——开头先简述范围、边界与关联代码；目标用表格给出可量化口径（延迟、大小、并发数等），不写"高性能"这类无法验收的话；
必须遵守的既有项目约束——列出本设计不能违反的上游决策（如"高频流走 Channel，禁止全局 Event"），新读者据此理解方案边界；
现状盘点与差距——用"位置 / 现状 / 差距"表格说明起点，结论一句话说清"本设计补齐哪几块"；
目标与非目标——非目标显式写出（如"不做真实进度条，不伪造进度"），划清不做的范围；
总体架构——组件划分、数据流、与既有模块的关系；
详细设计——协议、数据结构、时序、状态机、并发与存储策略；魔数要给取值与理由；
安全与降级——敏感数据处理（密码/私钥/PTY 字节流"永不入日志/文件"类声明）、失败时如何降级且不影响主流程；
测试与验证——单测、e2e、手工验证各自覆盖什么；
未决问题——没有则显式写"无"；遗留项不得静默。

可参考已落地的范例：applog-design.md、metrics-design.md、config-import-export-design.md。

8. ADR 架构决策记录

跨模块、长期有效或推翻了既往做法的决策，写 ADR 放 explanation/design/decisions/（如"为什么终端字节流走二进制帧而非 JSON"）。ADR 只记录当时的决策与理由，内容只追加不回改；决策变化时新建 ADR 并把旧文标记为"已被 ADR-NNN 替代"。

模板（新建文件复制使用）：

markdown

# ADR-NNN: 决策标题

> status: 提议 / 已采纳 / 已废弃 / 已被 ADR-NNN 替代
>
> created: YYYY-MM-DD HH:mm:ss
>
> author:

## 背景
要解决的问题、约束条件、触发原因。

## 考虑的方案
1. 方案 A：做法、优点、代价
2. 方案 B：做法、优点、代价

## 决策
最终选择了哪个方案，一句话结论。

## 影响
- 优点：
- 缺点 / 代价：
- 后果：对开发、测试、兼容性、升级的影响；相关文档与代码位置。

9. 图表与代码内呈现

当前所有文档在纯 Markdown 环境阅读，架构图/时序图/帧格式优先使用 text 代码块画 ASCII 图（与现有文档一致），保证不依赖任何渲染器即可读；
图中出现的模块名、帧名、字段名必须与代码一致，改名时同步改图；
未来引入文档站点后，新图可用 mermaid，但既有 ASCII 图无需为换格式而重画；
不在文档中大段粘贴源码；文档写"为什么 + 契约"，实现细节以代码为准，给出文件路径即可。

10. 维护与同步

文档随代码同仓库、同分支、同 PR 提交；评审代码时同步评审对应文档；
以下改动必须在同一 PR 更新对应文档：
- 二进制帧类型或 payload 变更（ssh/frame.rs ↔ stores/session.ts ↔ 架构文档）；
- invoke 命令的增删与入参/错误前缀变更（错误前缀即协议，如 KEY_ENCRYPTED:）；
- 配置文件 schema、设置项（stores/settings.ts）、导入导出格式变更；
- 模块分层与目录结构调整；
文档有实质性修订时同步更新头部的更新时间（创建时间永不改动）；实现与文档冲突时，先修代码或先修文档使其一致，不允许已知偏差留在 main；确实来不及的，在正文"已知偏差"小节列明；
废弃文档不删除，在正文开头注明已废弃并指向新文档，保留决策可追溯性；
提交文档前过一遍下方检查清单。

11. 提交前检查清单

[ ] 文件名符合 kebab-case 与后缀约定，放在正确的分类目录；
[ ] 头部四字段合规：摘要 ≤80 字、创建时间未被改动、更新时间为本次修订时间（YYYY-MM-DD HH:mm:ss）；
[ ] 全文仅一个一级标题，标题不跳级；
[ ] 相对链接、源码路径、代码块语言标注正确；
[ ] 命令与配置可复制、可验证，无"简单配置一下"式模糊表述；
[ ] 设计文档：目标可量化、非目标明确、安全与降级、未决问题已交代；
[ ] 本 PR 的代码改动涉及帧 / IPC / 配置 / 设置 / 分层时，相关文档已同步；
[ ] 图片在 docs/assets/ 下，无与 md 同级散落的图片。

Rhost 文档规范 ​

1. 目的 ​

2. 文档体系：四类文档 ​

3. 目标目录结构 ​

4. 文件命名 ​

5. 文档头元信息 ​

6. Markdown 写作规范 ​

7. 设计文档（*-design.md）的结构要求 ​

8. ADR 架构决策记录 ​

9. 图表与代码内呈现 ​

10. 维护与同步 ​

11. 提交前检查清单 ​