ReadmeAI - AI 驱动的 README 生成器
通过 AI 自动生成结构化、可定制的 README 文件，支持多种 LLM 提供商和离线模式。
证据显示：CLI 需要用户提供 API 密钥，但未明确说明权限最小化；有离线模式，但未提及用户确认步骤；数据流透明度部分，README 说明了数据发送到 LLM API，但未详细说明；敏感数据处理方面，API 密钥通过环境变量传递，但未说明存储方式；依赖安全方面，依赖版本部分固定，但未提及安全审计；外部影响方面，生成 README 文件，但未说明对系统的影响；回滚方面，未提及；来源归属方面，有作者信息，但未验证。扣分原因：缺少用户确认、回滚机制，数据流和敏感数据处理说明不充分。
证据显示：README 和 pyproject.toml 中的描述一致，均为 README 生成器；依赖在 pyproject.toml 中列出，但未验证可用性；失败消息方面，测试覆盖了错误处理，但未提供用户友好的错误消息。扣分原因：依赖可用性未验证，失败消息未详细说明。
证据显示：README 提供了多种使用场景（本地、GitHub、GitLab、Bitbucket），支持多种 LLM 提供商和离线模式；能力边界通过 CLI 选项明确；触发精度通过 CLI 参数精确控制；环境适配支持 Python 3.9+，多种安装方式。扣分原因：未明确说明能力边界，但整体充分。
证据显示：信息架构清晰，有快速链接和目录；安装说明详细，包括 pip、pipx、uv、docker；命名稳定，CLI 命令一致；示例和 FAQ 丰富，但 FAQ 未单独列出；已知限制未明确；许可证为 MIT；版本和变更日志未提供；维护责任有作者信息。扣分原因：缺少已知限制、版本变更日志。
证据显示：输出为 README 文件，可直接使用；边际价值高，自动化生成文档；成本效益方面，有离线模式，但 API 使用可能产生费用。扣分原因：成本效益未详细说明，但整体合理。
证据显示：README 中的功能声明与代码和测试部分对应；跨来源验证有限，但测试和文档一致；事实与推断分离，README 区分了功能描述和示例。扣分原因：跨来源验证不足。
- API 密钥通过环境变量传递，但未说明存储和轮换机制，建议用户谨慎管理。
- 依赖版本部分固定，但未提及安全审计，建议用户定期检查依赖漏洞。
- 生成 README 时可能将代码内容发送到第三方 LLM API，用户应了解数据隐私风险。
这个 Agent 能做什么，适合哪些场景？
ReadmeAI 是一个命令行工具，利用先进的 LLM 自动生成 README 文件。它解析代码库，提取依赖、结构和技术栈，然后生成包含项目概述、功能表、目录树、入门指南等章节的完整文档。它支持多种头部和导航风格，可定制徽章颜色、样式和 Logo。提供多种 LLM 后端：OpenAI、Anthropic、Gemini、Ollama，以及无需 API 密钥的离线模式。该项目基于 Python 开发，以 PyPI 包形式发布，并可通过 Docker 容器运行。它旨在简化文档创建和维护，确保项目文档的一致性和可读性。
ReadmeAI 接受仓库 URL 或本地路径作为输入，通过文件系统或 Git 平台获取源码。内部使用预处理器解析代码，提取项目结构、依赖和关键模块（通过 readmeai.parsers 和 tree.py）。然后调用配置的 LLM API（如 OpenAI gpt-3.5-turbo）或使用离线模式，根据 prompts.toml 中的模板生成 README 内容。生成的文件包含项目介绍、功能表、目录结构、安装指南、使用说明和贡献指南等章节。CLI 提供了 --repository、--api、--model、--badge-style、--header-style 等选项，允许高度定制。输出的 MD 文件可通过 --output 指定文件名。此外，它还支持通过 .readmeaiignore 模式过滤文件。
- 开发者想要快速为 GitHub 仓库生成专业的 README，无需手动编写。
- 团队需要为多个项目维护一致的文档风格和结构。
- 技术写作者需要基于真实代码生成准确的文档，以节省时间。
- 项目维护者希望自动更新 README，以反映代码库的变化（通过未来 GitHub Action 集成）。
- 使用离线模式的用户可以在不连接外部 API 的情况下生成基本 README。
- 在不同任务间切换 LLM 提供商，选择 OpenAI、Anthropic 或本地 Ollama 模型。
这个 Agent 有哪些优点和局限？
- 支持多种 LLM 提供商（OpenAI, Anthropic, Gemini, Ollama），提供灵活性和模型选择自由。
- 高度可定制：多种头部样式（classic, modern, compact, banner, console），徽章颜色和样式，以及导航风格。
- 具有离线模式，无需 API 密钥即可生成 README，保护隐私和节省成本。
- 语言无关，支持多种编程语言和框架，通过解析器自动提取项目信息。
- 提供智能文件过滤（
.readmeaiignore），避免包含不必要的文件。 - 支持从源代码构建和 Docker 部署，适应不同的安装偏好。
- 使用第三方 LLM API 时可能产生费用，需要 API 密钥，并需监控使用量（默认模型 gpt-3.5-turbo 成本较低，但高级模型可能昂贵）。
- 生成的 README 质量依赖于 LLM 输出，可能并非总是准确，尤其对于非常复杂或特定领域的代码库。
- 需要 Python 3.9+ 环境，安装可能涉及额外依赖（如 anthropic 和 google-generativeai extras）。
- 离线模式的 README 可能不够详细或缺乏上下文，因为无 LLM 生成动态内容。
- 集成 GitLab 和 Bitbucket 的支持尚不明确，可能不如 GitHub 完善。
如何安装或部署这个 Agent？
首先，确保 Python 3.9 或更高版本。推荐使用 pip 安装：pip install -U readmeai。也支持 pipx（pipx install readmeai）、uv（uv tool install readmeai）和 Docker（docker pull zeroxeli/readme-ai:latest）。若需使用 Anthropic 或 Gemini 客户端，安装额外的依赖：pip install "readmeai[anthropic]" 或 pip install "readmeai[google-generativeai]"。
如何使用这个 Agent？
安装后，确保设置 API 密钥（如 export OPENAI_API_KEY=<your_key>）。运行以下命令生成 README：readmeai --api openai -o README.md -r https://github.com/eli64s/readme-ai。使用 Anthropic：readmeai --api anthropic -m claude-3-5-sonnet-20240620 -o README.md -r <repo>。使用 Gemini：readmeai --api gemini -m gemini-1.5-flash -o README.md -r <repo>。使用 Ollama：首先拉取模型（ollama pull llama3.2），然后运行 readmeai --api ollama --model llama3.2 -r <repo>。对于本地代码库，直接提供路径：readmeai --repository /path/to/project --api openai。离线模式：readmeai --api offline -o README.md -r <repo>。要查看所有选项，运行 readmeai --help。
常见问题
使用 ReadmeAI 需要付费吗？
我可以自定义生成的 README 吗？
ReadmeAI 能否用于私有仓库？
生成 README 时，如何避免包含敏感文件？
.readmeaiignore 文件来排除不需要的文件或目录。