llmcodegen/README.md

# LLM 代码生成工具（自举版 · 增强版）

本项目是一个基于大语言模型的智能代码生成与维护工具。它不仅能够根据项目 `README.md` 描述**自动生成完整的 Python 包代码**，还支持**在现有项目上增量添加功能**和**自动修复 Bug**。工具采用 `uv` 管理依赖，包含单元测试、并行检查、断点续写等特性，并通过一个**面向 LLM 的中间设计层**来提升生成质量和可维护性。


## ✨ 核心特性

- 📦 **自动生成**：解析 `README.md`，分析需要生成的文件列表及依赖关系，按顺序生成每个文件的代码。
- 📋 **中间设计层**：生成一个 `design.json` 文件，包含项目结构、文件关联、功能摘要等信息。后续所有代码生成均以该 JSON + README 作为上下文，确保 LLM 始终理解全局设计。
- 🧩 **增量功能开发**：通过编写**需求工单**（如 `feature.issue`），描述新增功能，工具自动分析现有代码并生成新增或修改的文件。
- 🐞 **自动 Bug 修复**：通过编写**Bug 工单**（如 `bug.issue`），描述问题现象，工具结合代码和错误信息生成修复补丁。
- 🔧 **命令执行**：生成文件后可自动执行建议命令（如安装依赖、运行构建），内置危险命令拦截（执行命令失败不会终止任务，仅记录错误）。
- ✅ **单元测试**：使用 `pytest` 编写测试用例，支持测试覆盖率统计。
- 🔍 **并行检查**：生成代码后并行运行多个检查工具（`pylint`、`mypy`、`black` 等），收集错误信息。
- 🔄 **自修复**：将检查错误、README、design.json 和相关代码提交给 LLM，自动生成修复补丁并应用。
- ⏯️ **断点续写**：生成过程中断后可自动从上次中断处继续，状态保存在 `.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工单修复项目
```

### 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
```

工具会自动：
- 定位相关代码。
- 结合错误信息生成修复方案。
- 应用补丁，并重新运行测试验证。

## 🧠 中间设计层 (`design.json`)

`design.json` 是工具与 LLM 之间的“通用语言”，它记录了项目的完整设计蓝图，结构如下：

```json
{
  "project_name": "MyProject",
  "version": "1.0.0",
  "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，确保每次生成都符合整体设计。


## 🔄 核心工作流

### 初始化流程
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. 执行检查与修复。

## 📊 Diff 输出格式支持

工具支持在生成代码变更时输出 diff 格式，便于代码审查和集成到版本控制系统。diff 输出以标准 unified diff 格式呈现，适用于 `enhance` 和 `fix` 操作。

### 字段描述

diff 输出包含以下关键字段：

- **文件名**：变更的文件路径，如 `src/llm_codegen/core.py`。
- **行号**：变更发生的行号范围，使用 `@@` 标记表示。
- **旧代码**：被修改或删除的代码行，以 `-` 开头。
- **新代码**：新增或修改后的代码行，以 `+` 开头。
- **变更类型**：隐含在 diff 中，如添加（只有 `+` 行）、删除（只有 `-` 行）、修改（同时有 `-` 和 `+` 行）。

### 使用示例

运行 `llm-codegen enhance` 或 `llm-codegen fix` 时，通过 `--diff` 选项启用 diff 输出。例如：

```bash
llm-codegen enhance feature.issue -o ./project --diff
```

输出示例：

```diff
--- a/src/llm_codegen/core.py
+++ b/src/llm_codegen/core.py
@@ -10,7 +10,7 @@
    def generate_file(self, file_path, prompt_instruction, dependency_files):
        # 生成代码逻辑
        code = self._call_llm(...)
-        commands = []
+        commands = ["安装依赖"]
        return code, commands
```

### 注意事项

- diff 输出功能仅适用于增强（`enhance`）和修复（`fix`）操作，初始化（`init`）操作不产生 diff，因为它是从头生成。
- 确保使用支持 diff 格式的工具（如 `git diff`、`diff` 命令）查看和应用变更。
- 如果不需要 diff 输出，可以省略 `--diff` 选项，工具将直接应用变更到文件。
- diff 输出不影响工具的核心功能，仅为可选辅助特性。

### 内部实现

工具在生成 diff 输出后，内部使用 `src/llm_codegen/diff_applier.py` 模块来解析和应用 diff 到代码文件。该模块负责读取 diff 格式，验证变更，并安全地更新文件。开发者可以查看此模块的代码以了解更多细节，例如如何与 LLM 响应集成和确保变更的正确性。

## 📝 工单模板

### 需求工单 (`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           # 核心生成逻辑（CodeGenerator 类）
│       ├── checker.py        # 并行检查与修复模块
│       ├── utils.py          # 工具函数（危险命令判断、文件操作）
│       └── models.py         # 数据模型（Pydantic）
│       └── diff_applier.py   # 应用llm返回的diff
├── 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 协作者”，能够持续参与功能迭代与缺陷修复，大幅提升开发效率。