智能代码调试助手，自动分析错误并修复代码
CodeHealer 是一个基于大语言模型（LLM）的智能代码调试助手，旨在自动化 Bug 修复流程。它能够：
- 自动分析错误：解析错误堆栈，识别错误类型和根因
- 智能代码修复：定位问题代码，生成修复方案
- 反馈闭环验证：自动运行测试验证修复效果，失败时自动重试
- 安全护栏：危险操作拦截与人工审批机制
- 调试记忆：记录历史调试信息，避免重复解决相同问题
| 特性 | 说明 |
|---|---|
| 反馈闭环 | 测试 + Lint + 类型检查，驱动 Agent 自我修正 |
| 治理护栏 | 拦截危险命令，保护项目安全 |
| 多轮修复 | 测试失败时自动重试（最多 3 次） |
| 凭据安全 | 使用系统钥匙串存储 API Key |
- 软件开发者（个人开发者、小团队）
- 需要快速定位和修复 Bug 的工程师
- 希望自动化调试流程的技术团队
- Python >= 3.9
- 操作系统：Windows 10/11、macOS 12+、Linux (Ubuntu 20.04+)
- 网络连接（用于调用 DeepSeek API）
pip install codehealer# 克隆仓库
git clone https://github.com/unblieving/codehealer.git
cd codehealer
# 安装项目（开发模式）
pip install -e .
# 安装开发依赖（可选）
pip install -e ".[dev]"安装完成后，运行初始化命令配置 API Key：
codehealer setup系统将引导您输入 DeepSeek API Key，密钥将安全存储到系统钥匙串中。
# 分析并修复错误
codehealer fix "错误信息或问题描述"
# 对指定文件进行调试
codehealer fix --file path/to/file.py "问题描述"
# 运行测试并自动修复失败用例
codehealer test-and-fix# 显示详细输出
codehealer fix --verbose "问题描述"
# 指定最大重试次数
codehealer fix --max-retries 5 "问题描述"
# 仅分析错误，不自动修复
codehealer analyze "错误信息"# 查看 API Key 状态
codehealer key status
# 更新 API Key
codehealer key update
# 清除 API Key
codehealer key clearcodehealer --help
codehealer fix --help# 安装构建工具
pip install build
# 构建 sdist 和 wheel
python -m build构建产物将输出到 dist/ 目录：
dist/codehealer-{version}.tar.gz- 源码包dist/codehealer-{version}-py3-none-any.whl- 轮子包
# 安装 twine
pip install twine
# 上传到 PyPI
twine upload dist/*
# 或上传到测试 PyPI
twine upload --repository testpypi dist/*# 从本地 wheel 安装
pip install dist/codehealer-1.0.0-py3-none-any.whl
# 或从源码包安装
pip install dist/codehealer-1.0.0.tar.gzCodeHealer/
├── pyproject.toml # 项目配置与依赖定义
├── README.md # 项目文档
├── SPEC.md # 设计规约
├── PLAN.md # 开发计划
├── AGENT_LOG.md # Agent 运行日志
├── SPEC_PROCESS.md # 规约处理文档
│
├── src/ # 源代码目录
│ └── codehealer/
│ ├── __init__.py
│ │
│ ├── agent/ # Agent 主循环
│ │ ├── __init__.py
│ │ └── loop.py # 循环控制与调度
│ │
│ ├── llm/ # LLM 抽象层
│ │ ├── __init__.py
│ │ ├── base.py # LLM 接口定义
│ │ ├── deepseek.py # DeepSeek API 实现
│ │ └── mock.py # Mock LLM（测试用）
│ │
│ ├── tools/ # 工具实现
│ │ ├── __init__.py
│ │ ├── base.py # 工具基类
│ │ ├── file_ops.py # 文件操作工具
│ │ ├── shell_ops.py# Shell 命令工具
│ │ └── test_ops.py # 测试运行工具
│ │
│ ├── guardrails/ # 治理护栏
│ │ ├── __init__.py
│ │ └── safety.py # 安全检查与拦截
│ │
│ ├── feedback/ # 反馈闭环
│ │ ├── __init__.py
│ │ ├── aggregator.py # 反馈聚合
│ │ ├── lint_checker.py # Lint 检查
│ │ └── test_runner.py # 测试运行器
│ │
│ └── models/ # 数据模型
│ ├── __init__.py
│ ├── action.py # 动作模型
│ ├── feedback.py # 反馈信号模型
│ ├── message.py # 消息模型
│ └── session.py # 调试会话模型
│
└── tests/ # 测试目录
├── __init__.py
├── test_agent_loop.py # Agent 循环测试
├── test_guardrails.py # 护栏测试
└── test_mock_llm.py # Mock LLM 测试
| 模块 | 职责 |
|---|---|
agent/ |
Agent 主循环，协调 LLM 决策与工具执行 |
llm/ |
LLM 抽象层，支持多模型切换 |
tools/ |
工具集，提供文件、Shell、测试等操作 |
guardrails/ |
安全护栏，拦截危险操作 |
feedback/ |
反馈闭环，收集测试/Lint 结果驱动自我修正 |
models/ |
数据模型定义 |
CodeHealer 采用多层凭据保护机制：
| 威胁 | 风险等级 | 对策 |
|---|---|---|
| API Key 硬编码 | 高 | 使用 keyring 存储到系统钥匙串 |
| .env 文件泄露 | 中 | .gitignore 排除 + 文档说明 |
| 日志泄露 | 中 | 日志自动脱敏处理 |
| 进程环境可见 | 低 | 文档说明风险 |
凭据管理流程：
- 首次运行：引导用户输入 API Key（隐藏输入）
- 存储：使用
keyring库存储到系统钥匙串 - 查看：仅显示 Key 是否存在，不回显明文
- 更新：提供
codehealer key update命令 - 清除：提供
codehealer key clear命令
CodeHealer 内置危险命令检测，自动拦截以下类型的操作：
DANGEROUS_PATTERNS = {
"file_delete": [r"rm\s+", r"del\s+", r"unlink"],
"database": [r"DROP\s+", r"DELETE\s+FROM", r"TRUNCATE"],
"system": [r"format\s+", r"mkfs", r"dd\s+if="],
"network": [r"curl.*POST", r"wget.*\|.*sh"],
}当检测到危险操作时：
- 暂停执行：阻止操作立即执行
- 显示详情：展示操作内容和潜在影响
- 请求确认：等待用户明确确认
- 记录日志：记录所有危险操作及处理结果
⚠️ 检测到危险操作: rm -rf /tmp/cache
影响范围: 删除 /tmp/cache 目录及其所有内容
是否继续？(y/N):
- 读取文件：允许，无需确认
- 写入文件：需要显示变更内容
- 删除文件：需要用户确认
- 修改系统配置：需要用户确认
| 边界项 | 限制值 |
|---|---|
| 最大迭代次数 | 10 次 |
| 单次 LLM 调用超时 | 30 秒 |
| 工具执行超时 | 60 秒 |
| 自动修复重试次数 | 3 次 |
- 需要网络连接调用 DeepSeek API
- 不支持离线运行
- LLM 输出可能存在不稳定性，依赖反馈闭环保证质量
- 复杂 Bug 可能需要人工介入
# 运行所有测试
pytest
# 运行测试并显示覆盖率
pytest --cov=src/codehealer
# 运行特定测试文件
pytest tests/test_guardrails.py# 格式化代码
black src/ tests/
# 排序导入
isort src/ tests/
# 类型检查
mypy src/
# Lint 检查
flake8 src/ tests/MIT License