用 AI 自动生成项目 README——分析代码结构，输出专业文档

每个开源项目都需要 README，但写文档是程序员最不爱做的事。这个工具扫描项目代码，调用 AI 生成一份结构化的 README。

核心代码

#!/usr/bin/env python3# readmeai.pyimportos,subprocessfrompathlibimportPathfromcollectionsimportCounterfromopenaiimportOpenAIfromdotenvimportload_dotenv load_dotenv()client=OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"),base_url="https://api.deepseek.com/v1")defscan_project(root="."):"""扫描项目结构，提取关键信息。"""info={"name":Path(root).resolve().name,"files":[],"langs":Counter(),"deps":[],"tests":False,"docker":False,"ci":False}# 跳过无关目录skip={".git","__pycache__","node_modules",".venv","venv",".idea"}forfinPath(root).rglob("*"):ifany(pinskipforpinf.parts):continueiff.is_file():info["files"].append(str(f.relative_to(root)))suffix=f.suffix.lower()ifsuffixin{".py",".js",".ts",".go",".rs",".java"}:info["langs"][suffix]+=1iff.namein{"requirements.txt","pyproject.toml","package.json"}:info["deps"].append(str(f.relative_to(root)))if"test"instr(f).lower():info["tests"]=Trueif"docker"instr(f).lower()orf.name=="Dockerfile":info["docker"]=Trueif".github/workflows"instr(f)or".gitlab-ci.yml"instr(f):info["ci"]=True# 获取 Git 信息try:info["git_url"]=subprocess.run(["git","remote","get-url","origin"],capture_output=True,text=True,cwd=root).stdout.strip()info["description"]=subprocess.run(["git","log","--oneline","-1","--format=%s"],capture_output=True,text=True,cwd=root).stdout.strip()except:info["git_url"]=""info["description"]=""returninfodefgenerate_readme(info):"""AI 生成 README。"""langs=", ".join(f"{v}{k}"fork,vininfo["langs"].most_common(3))deps_text="\n".join(f"-{d}"fordininfo["deps"][:8])ifinfo["deps"]else"无"files_sample="\n".join(f"-{f}"forfininfo["files"][:30])prompt=f"""你是一个技术文档专家。根据以下项目信息生成一份完整的 README.md。 ## 项目信息 - 名称：{info['name']}- 描述：{info['description']}- 语言：{langs}- 测试：{"有"ifinfo['tests']else'无'}- Docker：{"有"ifinfo['docker']else'无'}- CI/CD：{"有"ifinfo['ci']else'无'}## 依赖文件{deps_text}## 项目结构（部分）{files_sample}请生成 README.md，包含：标题、简介、特性、快速开始、项目结构、依赖安装、使用说明。用 Markdown 格式。"""resp=client.chat.completions.create(model="deepseek-chat",messages=[{"role":"user","content":prompt}],temperature=0.3,max_tokens=2000,)returnresp.choices[0].message.contentif__name__=="__main__":importsys root=sys.argv[1]iflen(sys.argv)>1else"."info=scan_project(root)readme=generate_readme(info)output=Path(root)/"README.md"output.write_text(readme,encoding="utf-8")print(f"✅ README.md 已生成 ({len(readme)}字符)")

使用方式

python readmeai.py /path/to/your/project# ✅ README.md 已生成 (1847 字符)

效果

生成的 README 包含：

• 📛 项目名称和简介
• ✨ 功能特性
• 🚀 快速开始（安装、运行）
• 📁 项目结构
• 📦 依赖安装
• 📖 使用说明

总结

AI 写 README 的优势不是"写得更好"，而是"不用写"。把省下的时间花在写代码上。