# demo_devtools_project

**Repository Path**: ailark/demo_devtools_project

## Basic Information

- **Project Name**: demo_devtools_project
- **Description**: 创建一个编程AI Agent的Demo程序，用于理解AI编程的底层原理。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-19
- **Last Updated**: 2025-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI ReAct Agent 演示项目（CLI）

一个基于 ReAct 推理格式的命令行 AI Agent 演示。它通过 DeepSeek 模型（`deepseek-chat`）与本地工具协作（读文件、写文件、执行终端命令），逐步思考与行动，直到生成最终答案。

**核心特点**
- 使用 ReAct 模式：严格输出 `<thought>`、`<action>`、`<observation>`、`<final_answer>` 标签。
- 可调用本地工具：`read_file`、`write_to_file`、`run_terminal_command`。
- CLI 交互：实时打印 Agent 的思考与动作，并在执行终端命令前征求确认。
- 可配置系统提示：通过 `prompt_template.py` 控制约束与环境信息注入。

---

**目录结构**
- `agent.py`：主入口与核心逻辑，定义 `ReActAgent` 类、工具注册与命令行交互。
- `prompt_template.py`：系统提示模板（中文），包含 ReAct 示例与约束。
- `manual.md`：操作规范示例（Step1/Step2），与模板内容一致，便于理解输出格式。
- `baidu_map.py`：占位文件（当前为空）。
- `snake/pos_homepage.html`：静态 POS 售卖点系统页面示例（本项目未与 Python 代码联动）。

---

**运行环境**
- Python `3.9+`（推荐 `3.10+`）。
- 依赖：`openai`、`click`。

安装依赖：
```
pip install openai click
```

---

**密钥与配置**
- 本项目通过 `OpenAI` 客户端以 `base_url=https://api.deepseek.com` 调用 DeepSeek 模型。
- 将 DeepSeek 的 API Key 写入环境变量，优先 `DEEPSEEK_API_KEY`；兼容 `OPENAI_KEY` 与 `OPENAI_API_KEY`。不再读取 `.env` 文件。
- 可选：设置 `OPENAI_BASE_URL` 或 `OPENAI_API_BASE`（默认 `https://api.deepseek.com`）。

示例设置：
- macOS/Linux：
```
export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# 兼容：export OPENAI_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# 可选：export OPENAI_BASE_URL=https://api.deepseek.com
```
- Windows PowerShell：
```
$env:DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
# 兼容：$env:OPENAI_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
# 可选：$env:OPENAI_BASE_URL="https://api.deepseek.com"
```

> 说明：当设置 `DEEPSEEK_API_KEY` 时，内部将使用 DeepSeek 服务；如使用 `OPENAI_KEY/OPENAI_API_KEY` 也可兼容。请确保 Key 有效且具备调用 `deepseek-chat` 或 `deepseek-reasoner` 的权限与额度。

---

**快速开始**
1) 在终端设置环境变量 `OPENAI_KEY`（见上）。
2) 在命令行运行：
```
python agent.py .
```
3) 根据提示输入任务（例如）：
```
在当前目录下生成一个 README.md，概述项目目标、结构、安装、使用方法与示例。
```
4) 观察输出：
- 控制台会逐步打印 `Thought`、`Action`、`Observation`；
- 当模型选择 `run_terminal_command(...)` 时会提示是否继续（输入 `y` 继续）；
- 当得到 `<final_answer>` 时流程结束，并打印最终答案。

---

**核心模块说明**
- `ReActAgent`（位于 `agent.py`）：
  - `__init__`：注册工具、设置模型名、项目目录、DeepSeek 客户端。
  - `run(user_input)`：循环调用模型；解析并执行 `<action>` 中的工具；将 `<observation>` 反馈给模型；直到出现 `<final_answer>`。
  - `render_system_prompt(...)`：渲染 `prompt_template.py`，注入操作系统、项目目录、文件列表、工具签名。
  - `get_api_key()`：仅从环境变量加载 `OPENAI_KEY`；未配置会提示并退出。
  - `parse_action(...)`：解析形如 `func(arg1, arg2, ...)` 的工具调用文本，支持多行字符串与转义。
- 工具函数：
  - `read_file(file_path)`：读取指定文件内容（UTF-8）。
  - `write_to_file(file_path, content)`：写入文件；将 `\\n` 转换为换行；返回“写入成功”。
  - `run_terminal_command(command)`：执行 Shell 命令；成功返回“执行成功”，失败返回 `stderr`。

---

**使用示例（建议）**
- 生成报告文件：
  - 输入任务：在当前目录生成 `report.md`，内容为“项目简介、文件说明、后续计划”。
  - Agent 可能选择：`write_to_file("/绝对路径/report.md", "...内容...")`。
- 检查文件内容：
  - 输入任务：读取 `manual.md` 的前 200 行并概括要点。
  - Agent 可能选择：`read_file("/绝对路径/manual.md")`，并在后续思考中总结。
- 执行构建命令：
  - 输入任务：在当前目录执行 `ls -la` 或 `pytest -q`。
  - Agent 选择 `run_terminal_command("...")` 时会询问是否继续。

---

**扩展与定制**
- 增加工具：在 `agent.py` 中实现新函数，并加入 `tools = [...]` 列表。注意为函数编写简要 `docstring`，便于模板中展示。
- 修改提示模板：根据业务场景编辑 `prompt_template.py`（如增加示例、限制、环境信息）。
- 模型与地址：如需切换模型名或 API Base，修改 `ReActAgent.__init__` 中的 `model` 与 `base_url`。

---

**注意事项**
- 终端命令执行具有潜在风险，请谨慎授权并审阅命令内容。
- 写文件时路径须为绝对路径（模板已强调），避免产生不可预期的写入位置。
- `baidu_map.py` 当前为空文件；`snake/pos_homepage.html` 为独立的静态页面示例，可通过本地 HTTP 服务查看：
```
cd snake
python -m http.server 8000
# 浏览器访问 http://localhost:8000/pos_homepage.html
```

---

**许可与版权**
- 本项目目录未包含许可证文件；如需开源或分发，请补充相应 LICENSE 并标注第三方依赖条款。