如何快速上手readmex:从安装到生成第一份专业README的3分钟完整教程
如何快速上手readmex:从安装到生成第一份专业README的3分钟完整教程
readmex 是一款 AI 驱动的 README 与交互式 Wiki 生成工具:只需指定项目路径,它会自动分析代码结构、技术栈和依赖,几分钟内为你的仓库生成带徽章、Logo 和完整使用说明的专业 README,还可一键生成 MkDocs 交互式网站文档,是面向中文生态的开源 DeepWiki 方案。本文带你从安装、配置到出结果,3 分钟完成全部流程。
1分钟认识 readmex:AI 驱动的 README 自动生成器
readmex 把"写 README"这件繁琐的活交给了 AI,核心能力包括:
- 🤖 AI 生成结构化 README:项目简介、技术栈、安装与使用示例一应俱全
- 🖼️ 智能 Logo 设计:调用文生图模型(如 DALL·E 3)自动绘制项目 Logo
- 🏷️ 自动徽章:贡献者、分支、星标等状态徽章自动嵌入
- 🧠 技术栈识别:自动检测项目使用的编程语言与框架
- 🌐 交互式 Wiki:可选生成 MkDocs 网站并本地预览或部署
它支持 Python、JavaScript、Go、Rust、C++ 等数十种语言与构建文件,完整映射关系见 language_mapping.json,更多功能介绍可参考中文文档 README_CN.md。
一键安装 readmex:pip 安装只需一行命令
前置要求:Python 3.8 及以上(依赖声明见 pyproject.toml)。
pip install readmex
安装完成后,命令行中会注册 readmex 命令,直接可用。如果你更想从源码运行、顺便阅读实现,也可以克隆仓库:
git clone https://gitcode.com/gh_mirrors/rea/readmeX
cd readmeX
python -m readmex
💡 提示:也可以运行
python -m readmex.utils.cli以完整模块路径启动,效果相同。
配置 API 密钥:环境变量与全局配置两种方式
readmex 需要两类模型 API 密钥:LLM(生成文本内容)和 T2I(生成 Logo)。两种方式任选其一,环境变量优先级更高,CI/CD 场景推荐用环境变量,本地开发推荐全局配置文件。
方式一:设置环境变量(推荐 CI/CD)
export LLM_API_KEY="your_llm_api_key" # 必填
export T2I_API_KEY="your_t2i_api_key" # 必填
# 可选:自定义端点与模型名称
export LLM_BASE_URL="https://api.example.com/v1"
export T2I_BASE_URL="https://api.example.com/v1"
export LLM_MODEL_NAME="your-llm-model"
export T2I_MODEL_NAME="your-t2i-model"
方式二:全局配置文件(推荐本地)
创建 ~/.readmex/config.json,工具会自动查找,字段模板可参考 config_template.json:
{
"LLM_API_KEY": "你的LLM密钥",
"T2I_API_KEY": "你的T2I密钥",
"LLM_MODEL_NAME": "gpt-3.5-turbo",
"T2I_MODEL_NAME": "dall-e-3"
}
常用配置变量一览:
| 变量 | 是否必填 | 说明 |
|---|---|---|
LLM_API_KEY |
✅ 必填 | 语言模型 API 密钥 |
T2I_API_KEY |
✅ 必填 | 文生图模型 API 密钥 |
LLM_BASE_URL / T2I_BASE_URL |
可选 | 自定义 API 端点(可指向本地模型) |
LLM_MODEL_NAME / T2I_MODEL_NAME |
可选 | 指定使用的模型 |
EMBEDDING_* / LOCAL_EMBEDDING |
可选 | RAG 嵌入模型配置 |
MAX_WORKERS |
可选 | 并发线程数,默认 10 |
完整的环境变量示例可参考仓库内的 source.env。
3分钟生成第一份专业 README:命令行快速上手
配置完成后,在项目目录下执行:
readmex # 交互模式,按提示输入项目路径
readmex . # 为当前目录生成
readmex ./my-project # 为指定目录生成
等待几分钟后,readmex 会在项目中生成:
project_structure.txt—— 项目结构树script_description.json—— 各脚本的 AI 描述requirements.txt—— 依赖清单logo.png—— AI 绘制的项目 LogoREADME.md—— 最终的专业 README 文档 🎉
如果你想更进一步,生成可交互的 Wiki 网站:
readmex --website --serve # 生成 MkDocs 网站并启动本地服务器
命令行入口实现在 cli.py,README 生成的核心逻辑在 core.py,想深入了解源码的同学可以从这两个文件读起。
readmex 工作原理:一张流程图看懂生成过程
整个流程可以概括为四步:
- 文件过滤:筛选出项目中有效的代码文件
- 并行分析:一方面解析 import 语句识别技术栈,另一方面让 AI 为每个文件生成描述
- 素材汇聚:将结构化的仓库信息与 Logo(文生图模型生成)合并进 README 模板的 Prompt
- 输出成品:生成包含标题、简介、徽章等完整结构的专业 README
常见问题 FAQ
- 必须配置 API 密钥吗? 必须,至少需要 LLM 和 T2I 两个密钥;未配置时启动会提示配置缺失,可运行
readmex --help查看帮助。 - 能完全本地运行吗? 可以。通过
LLM_BASE_URL等变量指向自己的本地模型服务即可,无需依赖云端。 - 中途想取消怎么办? 直接按
Ctrl+C,会提示Operation cancelled。 - 生成结果不满意? 全局配置文件中可填写
github_username、email等个人信息字段,让生成的 README 更贴合项目背景。
🚀 到这里,readmex 入门流程就走完了:pip install readmex → 配置两个密钥 → 执行 readmex .,你的项目就能拥有一份媲美大厂的 README。

