本项目是一个基于 ReAct（Reasoning + Acting） 架构的智能 Agent 系统。Agent 通过大语言模型（LLM）进行推理（Thought），调用工具执行操作（Action），并根据工具返回结果（Observation）持续迭代，直到得出最终答案（Final Answer）。
- 基于 ReAct 范式，实现"思考 → 行动 → 观察"的循环推理
- 支持文件读写和终端命令执行
- 使用 XML 标签结构化输出（
<thought>/<action>/<observation>/<final_answer>） - 交互式 CLI，支持对危险命令进行人工确认
- 自动解析模型输出的函数调用参数（含多行字符串、转义字符处理）
Agent-main/
├── README.md # 项目文档
└── mini_code/
├── agent.py # Agent 核心逻辑与工具函数
├── prompt_template.py # ReAct 系统提示词模板
└── __pycache__/ # Python 字节码缓存
| 组件 | 技术 |
|---|---|
| 编程语言 | Python 3 |
| LLM 接口 | OpenAI SDK（兼容 SiliconFlow API） |
| 默认模型 | Qwen/Qwen3-8B |
| CLI 框架 | Click |
| 环境变量管理 | python-dotenv |
RacAgent 是系统的核心类，位于 agent.py。
| 参数 | 类型 | 说明 |
|---|---|---|
tools |
List[Callable] |
可用工具函数列表 |
model |
str |
使用的 LLM 模型名称 |
project_directory |
str |
项目工作目录路径 |
| 方法 | 说明 |
|---|---|
run(user_input) |
主运行循环：接收用户输入，执行 ReAct 循环直到产出最终答案 |
render_system_prompt(template) |
渲染系统提示词，注入工具列表、操作系统信息和文件列表 |
call_model(messages) |
调用 LLM 并追加助手消息到对话历史 |
parse_action(code_str) |
解析模型输出的 <action> 内容，提取函数名和参数 |
get_tool_list() |
自动生成工具描述列表（函数签名 + 文档字符串） |
get_operating_system_name() |
检测当前操作系统名称 |
用户输入 (Question)
│
▼
┌─────────────────┐
│ LLM 推理 │◄──────────────────────┐
│ 输出 Thought │ │
│ + Action/Final │ │
└────────┬────────┘ │
│ │
┌────┴────┐ │
│ │ │
<action> <final_answer> │
│ │ │
▼ ▼ │
执行工具 返回结果 │
│ │
▼ │
Observation ─────────────────────────────┘
- Agent 将用户问题和系统提示词发送给 LLM
- LLM 输出
<thought>（思考过程）和<action>（工具调用） - Agent 解析并执行工具，获取
<observation>（观察结果） - 将观察结果追加到对话历史，再次调用 LLM
- 循环直到 LLM 输出
<final_answer>
定义在 prompt_template.py 中，使用 Python string.Template 进行变量替换，注入以下动态信息：
${tool_list}— 可用工具的名称、签名和描述${operating_system}— 当前操作系统（macOS / Windows / Linux）${file_list}— 项目目录下的文件绝对路径列表
提示词要求模型严格使用 XML 标签格式输出，并通过 Few-shot 示例演示正确的交互模式。
系统提供三个内置工具函数：
读取指定文件的全部内容。
| 参数 | 类型 | 说明 |
|---|---|---|
file_path |
str |
文件的绝对路径 |
返回：文件的完整文本内容。
将内容写入指定文件（覆盖写入）。
| 参数 | 类型 | 说明 |
|---|---|---|
file_path |
str |
文件的绝对路径 |
content |
str |
要写入的内容（自动将 \\n 转换为换行符） |
返回："写入成功"。
在 Shell 中执行终端命令。
| 参数 | 类型 | 说明 |
|---|---|---|
command |
str |
要执行的 Shell 命令 |
返回：命令成功时返回 "执行成功"，失败时返回 stderr 错误信息。
安全机制：执行终端命令前会提示用户确认（CLI 交互），用户可选择取消操作。
parse_action 方法实现了自定义的函数调用参数解析器，能够处理：
- 普通参数：数字、布尔值等（通过
ast.literal_eval解析） - 字符串参数：单引号/双引号包裹的字符串字面量
- 多行字符串：模型输出中使用
\n表示换行的字符串 - 嵌套括号：正确处理参数中包含括号的情况
- 转义字符：支持
\"、\'、\n、\t、\r、\\等转义序列
# 安装依赖
pip install openai python-dotenv click
# （可选）配置 API Key — 通过 .env 文件
# OPENROUTER_API_KEY=your_api_keycd mini_code
python agent.py <项目目录路径>启动后，终端会提示输入任务描述，Agent 将自动执行 ReAct 循环完成任务。
$ python agent.py /path/to/your/project
请输入任务：读取 main.py 的内容并在末尾添加一行注释
💭 Thought: 我需要先读取 main.py 的内容...
🔧 Action: read_file(/path/to/your/project/main.py)
🔍 Observation：<文件内容>
💭 Thought: 已获取文件内容，现在在末尾添加注释...
🔧 Action: write_to_file(/path/to/your/project/main.py, "# 新增注释\n")
🔍 Observation：写入成功
✅ Final Answer：已成功在 main.py 末尾添加注释。当前默认使用 SiliconFlow 作为 LLM API 提供商：
- Base URL：
https://api.siliconflow.cn/v1 - 默认模型：
Qwen/Qwen3-8B
可在 RacAgent.__init__ 中修改 base_url、api_key 和 model 参数以切换到其他兼容 OpenAI 接口的服务。
要添加自定义工具，只需定义一个普通 Python 函数并提供文档字符串，然后传入 tools 列表即可：
def my_custom_tool(param1: str, param2: int) -> str:
"""工具描述，会出现在系统提示词中供 LLM 参考。"""
# 实现逻辑
return "结果"
# 在 main 中注册
tools = [read_file, write_to_file, run_terminal_command, my_custom_tool]Agent 会自动通过 inspect 模块提取函数签名和文档字符串，生成工具描述并注入系统提示词。