322 lines
12 KiB
Markdown
322 lines
12 KiB
Markdown
# LLM 代码生成工具
|
||
|
||
本项目是一个基于大语言模型的智能代码生成与维护工具。它不仅能够根据项目 `README.md` 描述**自动生成完整的 Python 包代码**，还支持**在现有项目上增量添加功能**和**自动修复 Bug**。工具采用 `uv` 管理依赖，包含单元测试、并行检查、断点续写等特性，并通过一个**面向 LLM 的中间设计层**来提升生成质量和可维护性。
|
||
|
||
|
||
## ✨ 核心特性
|
||
|
||
- 📦 **自动生成**：解析 `README.md`，分析需要生成的文件列表及依赖关系，按顺序生成每个文件的代码。
|
||
- 📋 **中间设计层**：生成一个 `design.json` 文件，包含项目结构、文件关联、功能摘要等信息。后续所有代码生成均以该 JSON + README 作为上下文，确保 LLM 始终理解全局设计。
|
||
- 🧩 **增量功能开发**：通过编写**需求工单**（如 `feature.issue`），描述新增功能，工具自动分析现有代码并生成新增或修改的文件。
|
||
- 🐞 **自动 Bug 修复**：通过编写**Bug 工单**（如 `bug.issue`），描述问题现象，工具结合代码和错误信息生成修复补丁。
|
||
- 🔧 **命令执行**：生成文件后可自动执行建议命令（如安装依赖、运行构建），内置危险命令拦截（执行命令失败不会终止任务，仅记录错误）。
|
||
- ✅ **单元测试**：使用 `pytest` 编写测试用例，支持测试覆盖率统计。
|
||
- ⏯️ **断点续写**：生成过程中断后可自动从上次中断处继续，状态保存在 `.llm_generator_state.json`。
|
||
- 🖥️ **命令行工具**：提供 `llm-codegen` 命令，支持多种操作模式。
|
||
- 📝 **详细日志**：所有操作、LLM 响应、错误均通过 `loguru` 记录到文件。
|
||
- 🎨 **美观输出**：使用 `rich` 显示进度条和彩色状态。
|
||
- 📊 **Diff 输出格式支持**：在生成代码变更时提供标准 unified diff 格式输出，便于代码审查和版本控制集成。
|
||
|
||
## 🚀 安装
|
||
|
||
### 依赖
|
||
- Python 3.9+
|
||
- 使用 `uv` 管理包
|
||
|
||
```bash
|
||
# 安装依赖
|
||
uv add [dev]
|
||
```
|
||
|
||
### 配置 API 密钥
|
||
设置环境变量（推荐）：
|
||
```bash
|
||
export DEEPSEEK_APIKEY="your-api-key"
|
||
```
|
||
或在命令行中通过 `--api-key` 传入。
|
||
|
||
## 📖 使用方法
|
||
|
||
工具支持四种操作模式，通过子命令区分：
|
||
|
||
```bash
|
||
llm-codegen init README.md # 从零初始化项目
|
||
llm-codegen enhance feature.issue # 根据需求工单增强项目
|
||
llm-codegen fix bug.issue # 根据Bug工单修复项目
|
||
llm-codegen design README.md # 生成设计文件 design.json
|
||
```
|
||
|
||
### 1. 初始化项目 (`init`)
|
||
|
||
根据 `README.md` 生成完整的项目骨架和代码。
|
||
|
||
```bash
|
||
llm-codegen init path/to/README.md -o ./generated
|
||
```
|
||
|
||
**流程**：
|
||
- 读取 `README.md`，调用 LLM 生成**中间设计文件** `design.json`（位于输出目录）。
|
||
- 基于 `design.json` 和 `README.md` 按顺序生成每个文件。
|
||
- 生成完成后执行可选命令、检查和自动修复。
|
||
|
||
### 2. 增强项目 (`enhance`)
|
||
|
||
当已有项目需要添加新功能时，编写一个**需求工单**（如 `add-logging.issue`），然后运行：
|
||
|
||
```bash
|
||
llm-codegen enhance add-logging.issue -o ./project
|
||
```
|
||
|
||
**需求工单模板**（`feature.issue`）：
|
||
```yaml
|
||
# 需求工单示例
|
||
name: 添加日志记录功能
|
||
description: 为所有核心函数增加日志输出，记录调用参数和执行时间。
|
||
affected_files:
|
||
- src/llm_codegen/core.py
|
||
- src/llm_codegen/utils.py
|
||
acceptance_criteria:
|
||
- 每个公共函数应记录开始和结束日志
|
||
- 日志级别为 INFO，包含函数名和参数
|
||
- 使用 loguru 记录
|
||
```
|
||
|
||
工具会自动：
|
||
- 读取现有项目的 `design.json` 和代码。
|
||
- 分析需求，确定需要修改的文件。
|
||
- 生成代码变更（新增或修改文件）。
|
||
- 执行检查和修复。
|
||
|
||
### 3. 修复 Bug (`fix`)
|
||
|
||
发现 Bug 时，编写一个**Bug 工单**（如 `crash-on-empty.issue`），然后运行：
|
||
|
||
```bash
|
||
llm-codegen fix crash-on-empty.issue -o ./project
|
||
```
|
||
|
||
**Bug 工单模板**（`bug.issue`）：
|
||
```yaml
|
||
# Bug 工单示例
|
||
name: 当输入为空时程序崩溃
|
||
description: 调用 parse_readme 时若 README 为空文件，抛出未处理的 IndexError。
|
||
steps_to_reproduce:
|
||
- 创建空文件 empty.md
|
||
- 运行 llm-codegen init empty.md
|
||
expected_behavior: 应给出友好提示并退出。
|
||
actual_behavior: 抛出 IndexError 并打印堆栈。
|
||
affected_files:
|
||
- src/llm_codegen/core.py
|
||
```
|
||
|
||
工具会自动：
|
||
- 定位相关代码。
|
||
- 结合错误信息生成修复方案。
|
||
- 应用补丁，并重新运行测试验证。
|
||
|
||
### 4. 生成设计文件 (`design`)
|
||
|
||
根据 `README.md` 生成中间设计文件 `design.json`，而不生成代码文件，文件内容会被提交给 LLM 以确保设计质量。
|
||
|
||
```bash
|
||
llm-codegen design path/to/README.md -o ./output
|
||
```
|
||
|
||
**流程**：
|
||
- 读取 `README.md`，调用 LLM 生成**中间设计文件** `design.json`（位于输出目录）。
|
||
- 文件内容会被提交给 LLM，基于 README 描述生成设计蓝图。
|
||
- 生成完成后，可手动检查或直接用于后续操作。
|
||
|
||
**示例**：
|
||
假设有一个项目描述文件 `project_readme.md`，运行：
|
||
```bash
|
||
llm-codegen design project_readme.md -o ./my_design
|
||
```
|
||
这将生成 `./my_design/design.json`，其中包含项目结构、文件关联等信息。
|
||
|
||
**注意事项**：
|
||
- 此命令专门用于生成 `design.json`，不涉及代码生成，适用于需要先设计后开发的场景。
|
||
- 生成的 `design.json` 是工具与 LLM 交互的核心，请确保其准确性，因为它会被提交给 LLM 用于后续生成。
|
||
- 如果已有 `design.json`，此命令会覆盖它，建议备份原有文件。
|
||
|
||
## 🧠 中间设计层 (`design.json`)
|
||
|
||
`design.json` 是工具与 LLM 之间的“通用语言”，它记录了项目的完整设计蓝图，结构如下：
|
||
|
||
```json
|
||
{
|
||
"project_name": "MyProject",
|
||
"version": "X.X.X",
|
||
"description": "项目简短描述",
|
||
"files": [
|
||
{
|
||
"path": "src/llm_codegen/core.py",
|
||
"summary": "核心生成逻辑，包含 CodeGenerator 类",
|
||
"dependencies": ["src/llm_codegen/utils.py"],
|
||
"functions": [
|
||
{
|
||
"name": "generate_file",
|
||
"summary": "生成单个文件，返回代码和命令",
|
||
"inputs": ["file_path", "prompt", "deps"],
|
||
"outputs": ["code", "commands"]
|
||
}
|
||
],
|
||
"classes": [...]
|
||
}
|
||
],
|
||
"commands": [
|
||
"pip install -e .",
|
||
"pytest tests/"
|
||
],
|
||
"check_tools": ["pytest", "pylint", "mypy"]
|
||
}
|
||
```
|
||
|
||
该文件由 LLM 在 `init` 阶段生成，并在后续所有操作中作为上下文提供给 LLM，确保每次生成都符合整体设计。
|
||
|
||
## 📄 README 作为设计资产
|
||
|
||
README.md 不仅是项目文档，更是工具的关键设计资产。它作为项目的起点，用于生成中间设计文件 `design.json`，并在此后的所有操作中提供上下文。
|
||
|
||
### 重要性
|
||
|
||
- **设计输入**: README.md 描述了项目的整体目标和功能，是 LLM 生成代码和设计的基础。它确保了生成的代码与项目意图保持一致。
|
||
- **一致性保障**: 通过保持 README.md 和 `design.json` 同步，工具可以基于准确的设计信息进行操作，避免生成偏差，提升维护效率。
|
||
|
||
### 同步机制
|
||
|
||
工具提供了自动同步机制来维护 README.md 和 `design.json` 的一致性：
|
||
|
||
- **`sync_readme` 方法**: 在 `CodeGenerator` 类中（位于 `src/llm_codegen/core.py`），`sync_readme` 方法可以比较 README.md 的内容和 `design.json` 中的描述，自动更新 `design.json` 以反映 README.md 的变更，或报告差异以供审查。
|
||
- **集成到工作流**: 同步机制可以集成到 `enhance` 或 `fix` 操作中，在生成代码前后自动运行，确保设计信息始终最新。
|
||
|
||
### 如何保持与 design.json 一致
|
||
|
||
为了确保 README.md 和 `design.json` 保持同步，建议：
|
||
|
||
1. **定期同步**: 在修改 README.md 后，运行 `llm-codegen` 工具的相关命令（如 `enhance` 或通过自定义脚本调用 `sync_readme`）来更新 `design.json`。
|
||
2. **避免手动修改**: 尽量不要手动编辑 `design.json`，除非完全理解设计意图。工具生成的 `design.json` 应作为权威来源，手动修改可能导致后续操作错误。
|
||
3. **检查不一致**: 工具在运行 `enhance` 或 `fix` 时，可以自动检查 README.md 和 `design.json` 之间的不一致，并提示用户进行同步，防止设计漂移。
|
||
|
||
通过维护这种同步，项目可以持续演进，而设计资产始终保持最新和准确，确保 LLM 生成的代码始终符合项目设计。
|
||
|
||
## 🔄 核心工作流
|
||
|
||
### 初始化流程
|
||
1. 读取 `README.md`，调用 LLM 生成 `design.json`。
|
||
2. 解析 `design.json`，获得文件列表和依赖关系。
|
||
3. 按顺序生成每个文件，生成时上下文包括：
|
||
- `README.md`
|
||
- `design.json`
|
||
- 已生成的依赖文件内容
|
||
4. 执行文件关联的命令（如安装依赖）。
|
||
5. （可选）运行检查工具，若有错误则触发自修复。
|
||
|
||
### 增强/修复流程
|
||
1. 读取项目根目录下的 `design.json` 和现有代码。
|
||
2. 解析需求/缺陷工单，识别受影响文件。
|
||
3. 调用 LLM 生成代码变更（可新增文件或修改现有文件），上下文包括：
|
||
- `README.md`
|
||
- `design.json`
|
||
- 所有受影响文件的当前内容
|
||
- 工单内容
|
||
4. 应用变更，更新 `design.json` 中的摘要（如果新增了函数/类）。
|
||
5. 执行检查与修复。
|
||
|
||
|
||
|
||
## 📝 工单模板
|
||
|
||
### 需求工单 (`feature.issue`)
|
||
```yaml
|
||
name: <功能名称>
|
||
description: <详细描述>
|
||
affected_files: # 可能影响到的文件（可选，留空则让 LLM 自动分析）
|
||
- path/to/file1.py
|
||
- path/to/file2.py
|
||
acceptance_criteria: # 验收条件（列表）
|
||
- 条件1
|
||
- 条件2
|
||
```
|
||
|
||
### Bug 工单 (`bug.issue`)
|
||
```yaml
|
||
name: <Bug 标题>
|
||
description: <详细描述>
|
||
steps_to_reproduce: # 复现步骤
|
||
- 步骤1
|
||
- 步骤2
|
||
expected_behavior: <期望行为>
|
||
actual_behavior: <实际行为>
|
||
affected_files: # 可能相关的文件（可选）
|
||
- path/to/file.py
|
||
```
|
||
|
||
## ⚙️ 配置
|
||
|
||
通过 `pyproject.toml` 的 `[tool.llm-codegen]` 部分自定义行为：
|
||
|
||
```toml
|
||
[tool.llm-codegen]
|
||
check_tools = ["pytest", "pylint", "mypy", "black"]
|
||
max_retries = 3
|
||
dangerous_commands = ["rm", "sudo", "chmod", "dd"]
|
||
```
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 环境设置
|
||
```bash
|
||
# 安装 uv
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
|
||
# 创建虚拟环境并激活
|
||
uv venv
|
||
source .venv/bin/activate
|
||
|
||
# 安装项目（可编辑模式）和开发依赖
|
||
uv pip install -e ".[dev]"
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
生成的项目将包含以下文件和目录：
|
||
```txt
|
||
.
|
||
├── README.md # 项目说明（原始输入）
|
||
├── pyproject.toml # 项目元数据、依赖、脚本入口
|
||
├── src/
|
||
│ └── llm_codegen/ # 主代码包
|
||
│ ├── __init__.py
|
||
│ ├── cli.py # 命令行入口（typer）
|
||
│ ├── core.py # 核心生成逻辑（BaseGenerator 类）
|
||
│ ├── enhance_generator.py
|
||
│ ├── fix_generator.py
|
||
│ ├── init_generator.py
|
||
│ ├── utils.py # 工具函数（危险命令判断、文件操作）
|
||
│ └── models.py # 数据模型（Pydantic）
|
||
├── tests/ # 单元测试
|
||
│ ├── __init__.py
|
||
│ ├── test_cli.py
|
||
│ ├── test_core.py
|
||
│ └── test_checker.py
|
||
└── logs/ # 运行日志（自动创建）
|
||
```
|
||
|
||
### 运行测试
|
||
```bash
|
||
pytest tests/
|
||
```
|
||
|
||
### 编写工单示例
|
||
项目生成后，`issues/` 目录下会包含示例工单文件，可参考编写。
|
||
|
||
## 📌 注意事项
|
||
|
||
- 中间设计文件 `design.json` 是核心资产，请勿手动修改（除非你完全理解设计意图），否则可能导致后续生成偏差。
|
||
- 断点续写状态文件 `.llm_generator_state.json` 自动管理，无需手动干预。
|
||
- 若 `README.md` 或 `design.json` 发生重大变更导致结构不一致，工具会提示并建议重新初始化。
|
||
|
||
---
|
||
|
||
通过引入中间设计层和工单驱动机制，本工具不仅实现了从零生成，更成为项目的“AI 协作者”，能够持续参与功能迭代与缺陷修复，大幅提升开发效率。 |