readme

自述文件

自述文件用于说明一款工具。它会说明工具的功能，展示工具运行情况，并介绍如何安装、使用和移除工具。它不会劝说读者。如果事实充分，它们就能支撑自述文件；如果需要修饰一番，这反映的是工具本身的问题，而非写作问题。

规则

1. 第一行说明这是什么。 用简单的陈述句，例如：“使用 cron 定时备份 sqlite 数据库。”不要采用问题／解决方案的叙述方式，不要讲述痛点，也不要问“厌倦了 X 吗？”。读者应该能在五秒内知道自己正在看什么。
2. 尽早展示实际调用。 命令及其实际输出胜过任何描述。复制真实会话的内容，不要使用理想化示例。
3. 陈述事实，不用形容词。 删除“强大”“简单”“优雅”“快如闪电”“无缝”等词。说明具体机制：不要写“闪电般快速的搜索”，而应写“使用 ripgrep 在约 50 毫秒内搜索 10 万个文件”。
4. 说明工具会影响什么。 凡是会运行代码、注册钩子、写入文件或发起网络请求的内容，都要在安装命令旁说明，并告知如何禁用或卸载。这是对工具行为的说明，不是建立信任的手段。
5. 每项事实只提一次。 如果已在“安装”一节说明安装方法，就不要在其他地方重复。重复会让人觉得是在推销。
6. 用 <details> 收纳细节，不要删掉。 架构说明、设计原理和参考表格应放在包含 Markdown 内容的 <details> 区块中（<summary> 后空一行，</details> 前空一行）。
7. 不要采用叙事口吻。 不要写“我开发这个工具是因为……”“我的收获”“起源故事”，也不要在开头写理念。如果设计原理很重要，就在折叠区块中简短说明。
8. 按使用顺序组织内容。 工具是什么 → 安装 → 用法／示例 → 工作原理 → 参考资料／常见问题 → 许可证。想尝试工具的读者不应该为了找到命令而先翻过理论内容。

工作流程

1. 默默收集上下文

提问前先阅读现有内容：README.md、清单文件（package.json、pyproject.toml、go.mod、Cargo.toml）、LICENSE、顶层源代码目录。推断名称、语言、安装命令和许可证。

2. 只询问无法推断的信息

把剩余问题合并为一轮，最多询问：

• 用一句话说明工具的功能（如果代码中看不出来）
• 一条展示工具运行情况的实际命令及其输出（或者提出运行工具并截取输出）
• 工具是否会运行 shell 命令／钩子、在项目目录之外写入文件，或发起网络请求

仓库中已有答案的问题无需再问。

3. 编写

按照上述规则编写 README。结构应服务于内容，而不是套用固定模板——小型 CLI 所需的内容远少于框架。除非现有内容中已有表情符号，否则不要使用。仅当仓库中已有徽章或用户提出要求时才添加徽章。

改写时：保留准确内容，修正下列违规之处，并保留当前 README 已经做得好的部分。

4. 完成前自查

违规情况	修正方法
以问题、痛点或“厌倦了 X 吗？”开篇	改为直接陈述工具是什么
采用问题／解决方案的推销式结构	说明工具的功能；跳过推销
使用没有数据支撑的形容词（“快速”“简单”“强大”）	改为说明具体机制或测量数据，或者删除
在多个章节重复同一价值点	保留首次事实性说明，删除其余内容
未说明工具影响的内容／钩子／网络行为	在安装说明旁写明，包括卸载方法
同一命令出现在 3 个以上位置	只保留一个用法章节
在示例前介绍起源故事或理念	移到折叠区块中，或删除
使用理想化的示例输出	改为使用实际截取的输出

报告发现并修正了哪些违规之处，以便用户否决有意为之的选择。