项目 README
README 既不是参数手册也不是广告。它是帮助新读者信任项目并获取首个结果的最短路径。
不要为了存在而填充章节。读者应能回答三个问题：这是什么？它适合我吗？我能获得首个结果并理解风险边界吗？
核心原则
- 每个声明都需要证据。省略无法在仓库中验证或无法由用户确认的声明；不要将猜测软化成模糊的散文。
- 快速入门是必须的：提供从安装到获得有用结果的最短真实路径。如果命令无法验证，请询问，而不是留空或自行编造。
- 当 README 已经存在时，询问是否替换、保留选定材料或在原地扩展。不要猜测或覆盖用户编写的内容。
- 在首屏确立身份和入口点。对于公开项目，使用项目名称/徽标、一行描述、真实徽章和导航，然后立即放置快速入门。仅在截图/GIF 比文字传达更多信息时才使用。
- 展示而非断言：终端输出、截图、代码和经过验证的数字比形容词更有力。
- 按任务而不是按参数组织。解释“我想做什么 → 哪个命令能做到”；将完整的选项列表留给
--help。 - 删除任何不能帮助读者决定、信任或采取行动的句子。
- 如果项目涉及本地文件、数据库、凭证、网络或模型调用，请解释它读取、写入和离开设备的内容，以及其默认的只读/确认/备份/fail-closed 姿态。没有代码证据就不要做出安全承诺。
- 将 README 保持为前门；将深层细节链接到
docs/或CONTRIBUTING.md，而不是将 README 变成手册。 - 匹配项目；不要强制一个模板适用于 CLI、MCP、库、应用和研究仓库。
- 避免未经验证的自夸，例如“行业领先”、“生产就绪”或“极致性能”。请参阅
content-writing中的护栏。
选择读者
对 README 的读者进行分类以设置详细程度：
- 个人（个人项目、内部工具或个人脚本）：读者主要是你，包括未来的你。必需：一行描述、快速入门和已知限制。徽章、贡献指南、社区频道、星标历史和路线图是可选的。基线是三个月后你仍然能运行它。
- 公开（开源、分布式软件或团队共享）：读者是陌生人。包括描述、价值、快速入门、用法、配置、文档索引、贡献和许可证。仅在真正存在时添加徽章和社区信息。
如果仓库是公开的、已发布到包管理器或有外部用户，则默认视为公开；对于私有个人项目和一次性工作，默认视为个人。对于混合情况，使用公开的详细程度。
选择模式
| 模式 | 何时使用 | 第一步 |
|---|---|---|
| 创建 | 没有 README 存在，或用户明确要求重写 | 检查仓库并收集事实。 |
| 改进 | README 存在且需要改进 | 阅读它，询问如何处理现有内容，然后进行。 |
| 审核 | 用户仅要求诊断 | 验证 README 中的每个声明与仓库的匹配情况，并报告发现。 |
关卡： 如果 README 存在，暂停等待用户选择：(1) 完全替换，(2) 重写同时保留指定材料，或 (3) 在原地扩展。“帮我写 README” 并不暗示选项 1。
首屏内容与开发者工具样式（公开项目）
读者在一屏后决定是否继续。第一屏应展示项目能做什么。
对于 CLI、MCP 和本地开发者工具，优先采用克制、可验证的开发者文档：
<div align="center">
可选徽标
# 项目名称
**一行描述**
仅真实徽章
语言切换器（仅当另一语言 README 存在时）
锚点导航（当文档超过 100 行时）
</div>
---
能力概述：实际命令/工具、输入、输出和默认安全姿态
三条规则：
- 一行描述： 保持易记且大约一行：它是什么，为谁准备，及其最重要的事实性区别。将原则和背景留到后面。
- 能力概述： 列出实际命令/工具、输入、输出、读/写对象和默认安全姿态。避免诸如“快速、安全、智能”之类的泛泛声明。
- 接下来是快速入门： 优选 1–3 个最短步骤。最后一步必须验证安装或服务发现。将复杂配置放在后面。
视觉材料是可选的。仅在它们能增加信息时才选择 GIF/asciinema、截图和真实终端输出。如果没有演示素材，不要发明一个；改用真实命令、预期输出和验证步骤。
个人项目可以省略徽标、徽章和导航，但一行描述和可见输出仍然有用。
证据阶梯
在编写每个声明前，对其证据进行分类：
| 级别 | 来源 | 使用方式 |
|---|---|---|
| 1 | 在仓库中： 源码、测试、示例、配置、CI、标签、截图 | 直接编写。 |
| 2 | 用户确认： 定位、差异化、指标、截图、案例 | 直接编写。 |
| 3 | 外部可验证： 包页面、发布、公开基准 | 带链接编写。 |
| 4 | 没有来源 | 省略。如果重要则询问；否则删除。 |
切勿发明安装命令、CLI 参数、API 签名、配置键、环境变量、路径、性能数字、兼容性声明、许可证条款或社区链接。
请参阅 references/evidence.md 了解仓库扫描和证据规则。
工作流
- 分类读者和模式： 个人/公开 和 创建/改进/审核。如果 README 存在，在修改前先询问如何处理。
- 收集仓库证据： 检查包元数据、入口点、结构、配置、文档、Git/CI、资产、读/写路径、凭证、网络、模型调用和错误码。此阶段收集事实而非结论；请参阅
references/evidence.md。 - 分类项目和读者： CLI、MCP、库、应用、研究项目、Agent Skill 或 monorepo。据此选择章节；请参阅
references/structure.md。 - 验证快速入门： 查找并验证安装后能产生有用结果的第一条命令。如果无法验证，请询问，不要通过此关卡。
- 规划章节： 为项目类型选择章节并为每个章节确定证据。省略不受支持的章节。同时决定首屏布局、快速入门验证，以及是否需要安全/数据流、错误码或故障排查。
- 起草： 身份和能力 → 快速入门 → 特性 → 安装/配置 → 基于任务的使用 → 原理/背景 → 安全/隐私边界 → 错误/故障排查 → 已知限制 → 开发/深度文档。在读者获得可行路径之后再解释原理，而不是在此之前。
- 运行质量关卡： 检查
references/checklist.md中的每一项，特别是事实准确性和可执行步骤。 - 交付： 默认在对话中提供草稿；仅在明确要求时才写入磁盘。在写入前重新运行检查清单。
输出
简明扼要地陈述：(1) 读者和模式；(2) 项目类型和目标读者；(3) 章节计划及每个章节的证据来源；(4) README 草稿；(5) 因证据缺失而需要用户确认的声明；(6) 已知的遗漏。切勿将猜测标记为已验证。明确列出不受支持的声明，而不是用模糊的语言掩饰它们。
红旗
- 缺少或空白的快速入门，或编造的命令且仓库中没有入口点。
- 未询问如何处理就覆盖现有 README。
- 未经确认的性能、兼容性、用户数或星标数声明。
- 指向不存在的 CI、包或许可证的徽章。
- 用空标题或“待办/即将推出”填充模板章节。
- 嵌入完整的 API 手册而不是链接到它。
- 复制长篇的
--help表格而不是展示基于任务的命令。 - 首屏只有口号或原理，没有真正的入口点或可验证的结果。
- 对于触及本地数据、凭证、网络或模型调用的工具，缺少安全/数据流信息。
- 在无代码/测试证据的情况下承诺只读操作、无数据泄漏、fail-closed 行为或零配置。
- 故障排查仅说“重启”而没有症状、错误码、原因和解决方法。
- 一行描述占了一段，或者原理出现在第一个可运行路径之前。
- 用形容词如“强大”、“优雅”、“极致”或“开箱即用”替代证据。
- 将贡献指南、行为准则或社区链接强行加在不存在的个人项目上。
- 架构图包含不存在的组件或调用关系。
- 未经用户授权就写入文件。
参考文献
仅按需阅读：
references/structure.md：阅读流程、按项目类型选择章节以及章节编写指导。references/evidence.md：仓库扫描、证据级别以及绝不能编造的声明。references/checklist.md：编写前的质量关卡，针对事实、可用性、呈现和语言。