codeagent

用一句话描述需求，由 LangGraph 驱动的代码 agent 自动完成分析、拆解与实现，并在 workspaces/ 下交付可运行的项目文件（如单页 HTML）。

底层模型为 DeepSeek OpenAI 兼容 API；依赖管理使用 uv。

---

这是什么

codeagent 是一个「主 agent + 工作流图」的自动化开发编排器：

1. 主 agent（create_agent）接收你的一句话项目描述，调用 start_project 工具启动完整流程。
2. 工作流（LangGraph）按固定节点推进：
   • 决定项目文件夹名并创建 workspaces/<项目名>/
   • 分析任务，提取结构化字段（背景、目标、拆解决策等）
   • 判断任务是否需要拆分为小组；简单任务直接执行，复杂任务拆组并递归处理子组（深度由 MAX_SUBTASK_DEPTH 控制）
   • 执行阶段通过文件工具读写代码，生成 index.html 等交付物
3. 计费汇总：每次 LLM 调用自动累计 token，执行结束后输出 cache 命中输入、未命中输入、输出的用量与费用（Decimal 精确计费）。

适合快速验证「描述 → 单文件 Web 小工具 / 原型页面」类需求，例如键盘测试页、坏点检测页、小游戏等。

项目结构

codeagent/
├── agent.py          # 兼容入口
├── main_agent.py     # 主 agent 与 start_project 工具
├── workflow.py       # 主工作流图
├── unit_workflow.py  # 可递归嵌套的任务单元子图
├── workflow_shared.py
├── file_tools.py     # 项目目录内读写文件
├── billing.py        # Token 统计与费用（Decimal）
├── config.py         # 环境变量与 DeepSeek 客户端
└── visualize.py      # 工作流 Mermaid / PNG 导出
main.py               # CLI 入口
workspaces/           # 生成的项目输出目录
test-deepseek.py      # 单独测试 API 与计费

---

如何配置

1. 安装依赖

uv sync

可选：若需本地 Graphviz 渲染 PNG，可安装 graphviz；未安装时仍会通过 Mermaid API 生成流程图。

2. 环境变量

复制 .env.example 为 .env 并填写：

DEEPSEEK_API_KEY=your-api-key-here
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-v4-flash
# 子工作组最大嵌套深度（根级拆分组为深度 1）
MAX_SUBTASK_DEPTH=3

变量	说明
DEEPSEEK_API_KEY	DeepSeek API 密钥（必填）
DEEPSEEK_BASE_URL	API 地址，默认 https://api.deepseek.com
DEEPSEEK_MODEL	模型名，默认 deepseek-v4-flash
MAX_SUBTASK_DEPTH	子任务组最大递归深度，默认 3

3. 计费单价（内置）

执行结束后按 DeepSeek 定价自动汇总（codeagent/billing.py，全程 Decimal）：

类型	百万 tokens 价格
输入（缓存命中）	0.02 元
输入（缓存未命中）	1 元
输出	2 元

---

使用

查看工作流架构（不调用 LLM）

uv run main.py

会在项目根目录生成 langgraph_workflow.png / .mmd 与 langgraph_workflow_main.png / .mmd，并打印可用命令说明。

新建项目（完整 agent 流程）

uv run main.py --new "你的项目一句话描述"

单独测试 DeepSeek API

uv run test-deepseek.py

---

使用展示

以下是一次真实运行的命令与终端输出节选。

命令：

uv run main.py --new "我要一个屏幕坏点测试页，双击进入或退出全屏，有几个纯色背景，有几个栅格背景，有控制鼠标指针涂满整个屏幕的界面。最后页面中间提示测试已完成，你可以点击这里退出全屏"

流程图生成：

✅ 完整工作流 PNG：...\langgraph_workflow.png
✅ 完整工作流 Mermaid：...\langgraph_workflow.mmd
✅ 主 agent 入口 PNG：...\langgraph_workflow_main.png
✅ 主 agent 入口 Mermaid：...\langgraph_workflow_main.mmd

执行结果（摘要）：

agent 在 workspaces/screen-dead-pixel-tester/ 下生成 index.html，并实现：

功能	说明
纯色背景（5 种）	红、绿、蓝、白、黑
栅格背景（2 种）	网格、点阵
双击全屏	双击进入/退出全屏
鼠标涂屏	拖动画笔涂满屏幕，可调大小与擦除
完成提示	全屏中央显示「测试已完成，点击退出全屏」

交付位置：

workspaces/screen-dead-pixel-tester/index.html

用浏览器直接打开即可使用。

Token 用量与费用（本次运行）：

--- Token 用量与费用 ---

LLM 调用次数: 15

用量 (tokens):
  input (cache hit):  29824
  input (cache miss): 12396
  output:             11476

费用 (元):
  input (cache hit):  0.00059648
  input (cache miss): 0.012396
  output:             0.022952
  total:              0.03594448

本次 15 次 LLM 调用，总费用约 0.036 元。

---

输出目录说明

每次 --new 会在 workspaces/<项目文件夹名>/ 下产生：

• index.html（或其它 agent 写入的文件）
• 1任务分析.json — 结构化任务分析
• 2子任务组.json — 若发生拆分
• logs/ — 各节点的 LLM 输入/输出日志，便于排查

---

注意

• API 密钥请勿提交到版本库，仅放在本地 .env。
• 生成代码为 agent 自动产出，上线前请自行审查安全性与兼容性。