README 工程与技术文档指南 是做什么的？
这是一套严格的框架，用于创建世界级、人性化的 GitHub 仓库 README，尊重读者时间，清晰传达技术价值，并消除通用的营销废话。
1. 核心理念：30 秒规则
开发者和用户不会从头到尾“阅读”文档——他们会高速扫描。想象一下，你是一个疲惫的开发者在凌晨 2 点偶然发现你的仓库。
你的 README 必须在 30 秒内回答三个问题：
- 这是什么？（一个清晰、单句的定义，零营销水分）。
- 我为什么要关心？（它解决的现实世界问题，以及它取代的令人沮丧的变通方法）。
- 我现在如何运行？（一个 3 步、可复制粘贴的快速入门，附带经过测试的命令）。
2. 清晰、基于实际的写作指南
文档经常会变成臃肿的企业公关用语。高质量的开源项目完全避免这种语气。
2.1 禁用词与陈词滥调字典
| ❌ 被禁的陈词滥调/行话 | ✔️ 清晰、实际的替代方案 |
|---|---|
| "在当今快节奏的数字环境中..." | （完全删除。直接切入问题）。 |
| "轻松传输 / 无缝集成..." | "从浏览器拖放文件，它们就会出现在你的手机上。" |
| "一个革命性的、尖端的平台..." | "一个轻量级的、自托管的个人中继。" |
| "将你的生产力提升到新的高度..." | "省去你给自己发邮件链接的麻烦。" |
| "现代开发的见证..." | （删除。像工程师一样说话，而不是公关公司）。 |
| "完全消除了巨大的英雄横幅..." | （永远不要吹嘘内部重构。说明 UI 现在提供了什么）。 |
| "防御性 Web 登录架构..." | "使用 HttpOnly SameSite Cookie 和 CSRF 令牌进行安全登录。" |
| "零骨架 SWR 缓存..." | "即时加载：打开收件箱时没有空白白屏。" |
2.2 真实写作的规则
- "周二咖啡"测试： 大声朗读你的草稿。听起来像一个深思熟虑的软件工程师在喝咖啡时向同事解释他们最喜欢的工具吗？如果听起来像企业营销手册，就重写。
- 徽章纪律： 将徽章限制在 3-6 个有意义的指标（版本、构建/CI 状态、许可证、核心技术栈）。不要堆叠 15 个装饰性徽章，这会分散项目本身的注意力。
- 无神秘先决条件： 在未列出先决条件和环境凭据来源的情况下，永远不要只写
docker compose up或npm start。
3. 双受众结构
出色的文档能够在不损害清晰度的前提下，连接两个不同的受众：
flowchart TD
Audience["仓库访客"]
Audience --> HomeUser["1. 普通人/日常用户<br>(想知道这个能否解决他们的痛点)"]
Audience --> Sysadmin["2. 工程师/系统管理员/开发者<br>(想了解架构、安全性和技术栈)"]
HomeUser --> PlainSection["'为什么存在？' 部分<br>- 现实世界场景（不再有推送机器人的短信或邮件附件）<br>- 3 步概念工作流<br>- 隐私与自托管优势"]
Sysadmin --> TechSection["'工作原理' 部分<br>- 架构图 (Mermaid)<br>- 组件职责<br>- 安全与令牌模型<br>- 存储与数据库机制"]
3.1 面向日常用户的通俗语言
从相关的现实摩擦点开始：
"你有没有发现自己给自己发送邮件链接，在 Telegram 或 WhatsApp 上给机器人发消息只是为了把文本复制到你的手机上，或者等待云盘同步只是为了移动一个 PDF？Vault 用你自己的私人存储箱取代了这些变通方法。"
3.2 面向开发者的深度技术细节
随后提供精确的架构和实现细节：
- API 引擎： ASP.NET Core 10 Minimal APIs，将文件直接流式传输到磁盘，最大 100 MB，并实时进行 SHA-256 验证（零内存膨胀）。
- Web SPA： React 19 + TypeScript，使用 SameSite HttpOnly Cookie、CSRF 令牌和键盘快捷键（
/搜索）。 - 移动客户端： 原生 Kotlin Jetpack Compose，带有 WorkManager 离线发件箱队列和 Android
FileProvider集成。 - 数据库： PostgreSQL 18，存储元数据和 14 天的滑动会话令牌。
4. 视觉展示与 UI 布局
如果你的应用程序有可视化界面（Web、移动或 CLI 输出），在介绍性推介之后立即展示它。
4.1 响应式展示表格模式
<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 移动收件箱</th>
<th width="33%" align="center">⚙️ 设备中心</th>
<th width="34%" align="center">🔐 无缝配对</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="移动收件箱" width="260px" />
<br/>
<sub><i>即时本地缓存、实时搜索和一键操作。</i></sub>
</td>
<!-- 剩余列 -->
</tr>
</table>
4.2 截图规则：
- 信息性标题： 使用标题描述用户可以在视图中 做什么，而不是串联行话。
- 真实截图： 始终使用实际产品 UI 的清晰截取，而不是带假笔记本框架的通用模拟模板。
5. 防弹的快速入门设计
快速入门必须是可复现的，无需故障排除。
标准的 3 步设置：
### 1. 生成本地证书与凭据
```bash
./scripts/setup-local.sh # 或 ./scripts/setup-local.ps1
作用：在 .local/tls/ 目录下生成受信任的本地主机 TLS 证书，并将随机引导密码写入 .env 文件。
2. 启动堆栈
docker compose up -d
3. 打开你的工作空间
在浏览器中导航至 **https://localhost:8080**：
- 用户名：
[email protected](或owner) - 密码： 你
.env文件中的引导密码
---
## 6. 标准 README 结构检查清单
在构建任何技术仓库的 README 时，使用此检查清单：
- [ ] **1. 标题与头部：** 图标/Logo、标题和一个句子的功能性标语。
- [ ] **2. 聚焦的徽章：** 发布版本、构建状态、核心平台、许可证。
- [ ] **3. 为什么存在：** 日常问题、解决方案和用通俗语言描述的 3 步工作流。
- [ ] **4. 视觉导览：** 带有实用标题的 Web、移动或 CLI 界面的截图。
- [ ] **5. 核心能力：** 按实际任务组织的以用户为中心的功能列表。
- [ ] **6. 工作原理（技术层面）：** Mermaid 架构图 + 简洁的组件分解（API、客户端、DB、认证/安全）。
- [ ] **7. 快速入门（Docker / 本地）：** 先决条件、逐步命令和凭据位置。
- [ ] **8. 移动/客户端设置（如适用）：** 直接下载链接、配对说明和局域网测试指南。
- [ ] **9. 自动化测试与验证：** 在本地运行后端和前端测试套件的命令。
- [ ] **10. 仓库地图与贡献指南：** 清晰的 ASCII 目录树、指南链接和 MIT/Apache 许可证。
---
## 7. 参考开源仓库
检查这些广受赞誉的开源 README 以获取结构和视觉灵感：
- **`matiassingers/awesome-readme`**：精选的 GitHub 上最佳 README 目录。
- **`othneildrew/Best-README-Template`**：模块化、高影响力仓库模板的行业黄金标准。
- **`charmbracelet/bubbletea` 和 `charmbracelet/gum`**：卓越的终端展示、GIF 使用和可扫描的代码块。
- **`supabase/supabase`**：出色的双受众平衡，配有清晰的系统架构图和快速上手体验。
- **`fastapi/fastapi`**：无摩擦快速入门、真实代码示例和清晰价值主张的大师课。