快速链接

• 简介
• 演示
• 功能
• 快速入门
• 配置
• 示例图库
• 贡献指南

[!重要提示] 请查阅官方文档，以获取完整的功能列表、自定义选项和示例。

简介

ReadmeAI 是一款开发者工具，它利用强大的仓库处理引擎和先进的语言模型，自动生成功能完善的 README 文件。你只需提供代码库的 URL 或路径，即可生成结构清晰、内容详尽的 README 文档。

为什么使用 ReadmeAI？

本项目旨在简化所有技术领域和不同经验水平下的文档编写与维护流程。其核心原则包括：

• 🔵 自动化： 通过一条命令即可生成详细且结构化的 README 文件。
• ⚫️ 可定制： 提供多种模板、样式、徽章等选项供选择。
• 🟣 灵活： 随时可在 OpenAI、Ollama、Anthropic 和 Gemini 之间切换。
• 🟠 语言无关： 兼容多种编程语言和框架。
• 🟡 最佳实践： 确保所有项目的文档整洁一致。
• 🟢 智能过滤： 基于可自定义的 .readmeaiignore 规则进行智能文件分析。
• ⛔️ 离线模式： 即使不使用 LLM API 服务，也能离线创建 README 文件。

演示

在终端中运行：

readmeai-cli-demo

功能

自定义你的 README

让我们从探索 ReadmeAI 支持的各种自定义选项和样式开始：

生成的章节与内容

꩜ 展开以查看更多！

项目简介 本节捕捉了您项目的精髓和价值主张。 用于生成此部分的提示模板可在此处查看prompts.toml。

功能表 详细的功能分解和技术能力。 用于生成此部分的提示模板可在此处查看prompts.toml。

项目结构 您项目的目录结构的可视化表示。 该树状图使用纯Python生成，并嵌入代码块中。
项目索引 总结了项目的关键模块，这些模块也被用作下游prompts.toml的上下文。

入门指南 依赖项和系统要求在预处理过程中从代码库中提取出来。 解析器在这里承担了大部分繁重的工作。
安装、使用与测试 根据从代码库中提取的数据，自动生成设置说明和使用指南。

社区与支持 开发路线图、贡献指南、许可证信息以及社区资源。 还包含一个返回按钮,方便导航。
贡献指南 关于如何为项目做出贡献的说明，包括资源链接和基本的贡献指南。 对于开源项目，还包含了贡献者图。

开始使用

先决条件

ReadmeAI 需要 Python 3.9 或更高版本，以及以下任一种安装方法：

要求	详情
• Python ≥3.9	核心运行时
安装方法（选择其一）
• pip	默认的 Python 包管理工具
• pipx	隔离环境安装工具
• uv	高性能包管理工具
• docker	容器化环境

支持的仓库平台

要生成 README 文件，请提供源仓库。ReadmeAI 支持以下平台：

平台	详情
文件系统	本地仓库访问
GitHub	行业标准托管平台
GitLab	全面 DevOps 集成
Bitbucket	Atlassian 生态系统

支持的 LLM API 服务

ReadmeAI 不依赖于特定模型，支持以下 LLM API 服务：

提供商	最适合场景	详情
OpenAI	通用用途	行业领先的语言模型
Anthropic	高级任务	Claude 系列语言模型
Google Gemini	多模态 AI	Google 最新技术
Ollama	开源	无需 API 密钥
离线模式	本地运行	无需互联网连接

---

安装

ReadmeAI 已在 PyPI 上发布，名称为 readmeai，可通过以下方式安装：

 Pip

推荐大多数用户使用 pip 进行安装：

❯ pip install -U readmeai

 Pipx

使用 pipx，readmeai 将被安装在一个隔离的环境中：

❯ pipx install readmeai

 Uv

使用 uv 是安装 readmeai 的最快方式：

❯ uv tool install readmeai

 Docker

要在容器化环境中运行 readmeai，请从 [Docker Hub][dockerhub-link] 拉取最新镜像：

❯ docker pull zeroxeli/readme-ai:latest

 从源码构建

点击以从源码构建 readmeai

1. 克隆仓库：

   ❯ git clone https://github.com/eli64s/readme-ai
   

2. 进入项目目录：

   ❯ cd readme-ai
   

3. 安装依赖：

   ❯ pip install -r setup/requirements.txt
   

或者，使用 [设置脚本][setup-script] 来安装依赖：

 Bash

1. 运行设置脚本：

   ❯ bash setup/setup.sh
   

或者，使用 poetry 来构建并安装项目依赖：

 Poetry

1. 使用 poetry 安装依赖：

   ❯ poetry install
   

其他可选依赖项

[!重要] 要使用 Anthropic 和 Google Gemini 客户端，需要额外的依赖项。请通过以下 extras 安装包：

• Anthropic：

  ❯ pip install "readmeai[anthropic]"
  

• Google Gemini：

  ❯ pip install "readmeai[google-generativeai]"
  

• 安装多个客户端：

  ❯ pip install "readmeai[anthropic,google-generativeai]"
  

使用方法

设置您的 API 密钥

在使用第三方服务运行 readmeai 时，您必须提供有效的 API 密钥。例如，OpenAI 客户端的设置如下：

❯ export OPENAI_API_KEY=<your_api_key>

# 对于 Windows 用户：
❯ set OPENAI_API_KEY=<your_api_key>

点击查看用于 Ollama、Anthropic、Google Gemini 的环境变量

Ollama

有关 Ollama 服务器设置的更多信息，请参阅 Ollama 文档。

开始之前，请按照以下步骤操作：

1. 从 Ollama 仓库拉取您选择的模型：

   ❯ ollama pull llama3.2:latest
   

2. 启动 Ollama 服务器并设置 OLLAMA_HOST 环境变量：

   ❯ export OLLAMA_HOST=127.0.0.1 && ollama serve
   

Anthropic

1. 导出您的 Anthropic API 密钥：

   ❯ export ANTHROPIC_API_KEY=<your_api_key>
   

Google Gemini

1. 导出您的 Google Gemini API 密钥：

   ❯ export GOOGLE_API_KEY=<your_api_key
   

使用 CLI

使用 LLM API 服务运行

以下是使用 OpenAI 客户端运行 readmeai 所需的最小命令：

❯ readmeai --api openai -o readmeai-openai.md -r https://github.com/eli64s/readme-ai

[!重要] 默认模型设置为 gpt-3.5-turbo，在成本和性能之间提供了最佳平衡。当使用 gpt-4 系列及更高版本的模型时，请注意监控您的费用和使用情况，以避免产生意外费用。

ReadmeAI 可以轻松切换 API 提供商和模型。我们可以使用与上述相同的命令，但采用 Anthropic 客户端：

❯ readmeai --api anthropic -m claude-3-5-sonnet-20240620 -o readmeai-anthropic.md -r https://github.com/eli64s/readme-ai

最后，使用 Google Gemini 客户端：

❯ readmeai --api gemini -m gemini-1.5-flash -o readmeai-gemini.md -r https://github.com/eli64s/readme-ai

使用本地模型运行

我们还可以使用 Ollama 中免费且开源的本地托管模型来运行 readmeai：

❯ readmeai --api ollama --model llama3.2 -r https://github.com/eli64s/readme-ai

在本地代码库上运行

要从本地代码库生成 README 文件，只需提供项目的完整路径：

❯ readmeai --repository /users/username/projects/myproject --api openai

添加更多自定义选项：

❯ readmeai --repository https://github.com/eli64s/readme-ai \
           --output readmeai.md \
           --api openai \
           --model gpt-4 \
           --badge-color A931EC \
           --badge-style flat-square \
           --header-style compact \
           --navigation-style fold \
           --temperature 0.9 \
           --tree-depth 2
           --logo LLM \
           --emojis solar

在离线模式下运行

ReadmeAI 支持“离线模式”，允许您在不使用 LLM API 服务的情况下生成 README 文件。

❯ readmeai --api offline -o readmeai-offline.md -r https://github.com/eli64s/readme-ai

 Docker

在 Docker 容器中运行 readmeai CLI：

❯ docker run -it --rm \
    -e OPENAI_API_KEY=$OPENAI_API_KEY \
    -v "$(pwd)":/app zeroxeli/readme-ai:latest \
    --repository https://github.com/eli64s/readme-ai \
    --api openai

 Streamlit

无需安装，即可在 Streamlit Cloud 上直接在浏览器中试用 readme-ai。

有关该应用程序的更多详细信息，请参阅 GitHub 上的 readme-ai-streamlit 仓库。

[!警告] readme-ai Streamlit Web 应用程序可能并不总是与最新功能保持同步。请使用命令行界面 (CLI) 以获得最新的功能。

 从源码构建

点击以从源码运行 readmeai

 Bash

如果您使用 bash 脚本从源码安装了该项目，请运行以下命令：

1. 激活虚拟环境：

   ❯ conda activate readmeai
   

2. 运行 CLI：

   ❯ python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
   

 Poetry

1. 激活虚拟环境：

   ❯ poetry shell
   

2. 运行 CLI：

   ❯ poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
   

测试

开发和测试过程中使用了 pytest 和 nox 框架。

使用 uv 安装依赖项：

❯ uv pip install --dev --group test --all-extras

使用 Pytest 运行单元测试套件：

❯ make test

使用 nox，在 Python 版本 3.9、3.10、3.11 和 3.12 上测试应用程序：

❯ make test-nox

[!提示] _{Nox 是一种用于在多个环境中测试应用程序的自动化工具。这有助于确保您的项目在不同 Python 版本和环境中都具有兼容性。}

配置

通过多种选项和样式设置来自定义您的 README 生成，例如：

选项	描述	默认
--align	标题中的文本对齐方式	center
--api	LLM API 服务提供商	offline
--badge-color	徽章颜色名称或十六进制代码	0080ff
--badge-style	徽章图标样式类型	flat
--header-style	标题模板样式	classic
--navigation-style	目录样式	bullet
--emojis	在章节标题前添加的表情主题包	None
--logo	项目徽标图片	blue
--logo-size	徽标图片大小	30%
--model	要使用的特定 LLM 模型	gpt-3.5-turbo
--output	输出文件名	readme-ai.md
--repository	仓库 URL 或本地目录路径	None
--temperature	内容生成的创造力水平	0.1
--tree-max-depth	目录树结构的最大深度	2

运行以下命令以查看所有可用选项：

❯ readmeai --help

访问官方文档以获取关于配置和自定义 README 文件的完整指南。

示例图库

本图库展示了跨多种编程语言、框架和项目类型的多样化 README 示例。

技术	仓库	README	项目描述
Python	README-Python.md	readmeai	ReadmeAI 的核心项目
Apache Flink	README-Flink.md	pyflink-poc	PyFlink 概念验证
Streamlit	README-Streamlit.md	readmeai-streamlit	Web 应用程序界面
Vercel & NPM	README-Vercel.md	github-readme-quotes	部署展示
Go & Docker	README-DockerGo.md	docker-gs-ping	容器化 Golang 应用
FastAPI & Redis	README-FastAPI.md	async-ml-inference	机器学习推理服务
Java	README-Java.md	minimal-todo	极简待办事项应用
PostgreSQL & DuckDB	README-PostgreSQL.md	buenavista	数据库代理服务器
Kotlin	README-Kotlin.md	android-client	移动客户端应用程序
离线模式	README-Offline.md	litellm	离线功能演示

社区贡献

分享您的 README 文件

我们诚邀开发者在我们的Show & Tell讨论版块中分享他们生成的 README 文件。您的贡献有助于：

• 展示多样化的文档风格
• 提供真实世界的示例
• 帮助改进 ReadmeAI 工具

您还可以在 GitHub 上的示例目录中找到更多 README 示例。

路线图

• 发布 readmeai 1.0.0，具备强大的文档创建和维护能力。
• 扩展模板支持，覆盖更多 项目类型 和 编程语言。
• 开发 Vscode 扩展，以便直接在编辑器中生成 README 文件。
• 开发 GitHub Actions，实现文档更新的自动化。
• 添加 徽章包，提供更多徽章样式和选项。
  • 代码覆盖率、CI/CD 状态、项目版本等。

贡献

欢迎贡献！请阅读贡献指南开始您的旅程。

• 💡 贡献指南：了解我们的贡献流程和编码规范。
• 🐛 报告问题：发现错误？请告诉我们！
• 💬 发起讨论：有想法或建议吗？我们非常期待您的反馈。

致谢

特别感谢以下项目及其出色的开源贡献：

🎗 许可证

版权所有 © 2023-2025 readme-ai。
根据 MIT 许可证发布。

readme-ai 快速上手指南

readme-ai 是一款强大的开发者工具，能够利用大语言模型（LLM）自动分析代码仓库并生成结构清晰、内容详实的 README 文档。支持多种模型后端（OpenAI, Ollama, Anthropic, Gemini）及丰富的样式定制。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)。
• Python 版本：Python 3.9 或更高版本。
• 依赖项：
  • pip (Python 包管理工具)
  • Git (用于克隆仓库或处理本地路径)
  • LLM API Key (可选)：若使用云端模型需准备 OpenAI/Anthropic/Gemini 的 API Key；若使用本地模型需安装并运行 Ollama。

提示：国内用户若访问 PyPI 较慢，建议在安装命令中指定清华或阿里镜像源。

安装步骤

推荐使用 pip 进行安装。

1. 基础安装

pip install readmeai

2. 国内加速安装（推荐）

如果您在中国大陆，使用以下命令可显著提升下载速度：

pip install readmeai -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 验证安装

安装完成后，检查版本号以确认安装成功：

readmeai --version

基本使用

1. 配置 API Key (可选)

如果您计划使用云端大模型（如 GPT-4），请先导出 API Key。若使用本地 Ollama 或离线模式，可跳过此步。

export OPENAI_API_KEY="your-api-key-here"
# 或者针对其他模型
export ANTHROPIC_API_KEY="your-api-key-here"

2. 生成 README

只需一条命令即可为远程仓库或本地项目生成 README。

场景 A：分析远程 GitHub 仓库

readmeai --repository https://github.com/eli64s/readme-ai

场景 B：分析本地代码目录

readmeai --repository /path/to/your/local/project

场景 C：自定义样式与模型（进阶示例）

指定使用 compact 头部风格、彩色徽章以及特定的 Emoji 主题：

readmeai --repository https://github.com/eli64s/readme-ai \
  --header-style COMPACT \
  --badge-color FF4B4B \
  --badge-style flat-square \
  --emojis solar \
  --model openai

3. 查看结果

命令执行完毕后，工具会在当前目录下生成一个名为 README.md 的文件。您可以直接在 GitHub 上推送该文件，或使用 Markdown 编辑器预览。

注意：生成的文件默认包含智能过滤逻辑，会自动忽略 .git 目录及配置文件。如需自定义忽略规则，可在项目根目录创建 .readmeaiignore 文件。