196 lines
8.9 KiB
Markdown
196 lines
8.9 KiB
Markdown
# AI Agent 系统
|
||
|
||
一个以“自主演练”为核心目标的智能编程助手。系统基于兼容 OpenAI API 的大语言模型（DeepSeek、Qwen、Kimi 等），围绕“真实开发工作流”构建：它能够持久化管理多个终端、操作文件、调用网络工具，并通过 Web 与 CLI 双入口提供可视化的实时反馈。
|
||
|
||
> ⚠️ **项目状态**：这是一个个人学习项目，代码主要由 AI 辅助编写。目前功能基本可用，但代码结构有待优化（存在一定的 "屎山代码" 趋势）。欢迎贡献和建议！
|
||
|
||
## 1. 项目亮点
|
||
|
||
- **工具链覆盖面广**
|
||
通过 Function Calling 暴露 `create_file`、`append_to_file`、`modify_file`、`run_command`、`terminal_session`、`web_search` 等多种能力，模型可以自主“选工具—执行—读取反馈”，形成可复现的自动化流程。
|
||
|
||
- **实时终端能力**
|
||
`modules/terminal_manager.py` 和 `modules/persistent_terminal.py` 维护最多 3 个长期存在的 Shell 会话。无论是后台启动开发服务器还是开启 Python REPL，都可以在 Web 端实时查看输出、切换会话、发送指令。
|
||
|
||
- **可控的文件写入流程**
|
||
`append_to_file` 工具采用“二段式”协议：先向模型发放写入窗口，再监听其流式输出，自动验证 `<<<APPEND ... >>>` / `<<<END_APPEND>>>` 标记，缺失时会在第二次工具返回中提示补救，保证文件写入可靠且可追溯。
|
||
|
||
- **双模式推理**
|
||
在 CLI/Web 启动流程中可选择“快速模式”或“思考模式”。思考模式下，系统只在每个任务的第一轮调用开启 `reasoning`，后续复用已有思路，平衡速度与稳健性。
|
||
|
||
- **对话持久化与重放**
|
||
`utils/conversation_manager.py` 将完整对话（含工具调用记录、token 统计）保存于 `data/conversations/`。Web 端提供列表、搜索、加载、删除能力，方便复现任务与排查问题。
|
||
|
||
- **细粒度上下文管理**
|
||
`utils/context_manager.py` 维护临时聚焦文件、文件备注、token 统计和 conversation history，避免模型反复读取同一文件并保障上下文稳定。
|
||
|
||
## 2. 系统架构一览
|
||
|
||
```
|
||
.
|
||
├── main.py # CLI 启动入口，负责模式选择和终端初始化
|
||
├── web_server.py # Flask + Socket.IO Web 服务，处理流式推理与前端通信
|
||
├── core/
|
||
│ ├── main_terminal.py # CLI 终端主循环，负责工具分发与对话管理
|
||
│ └── web_terminal.py # 面向 Web 的终端适配层，追加消息广播与状态同步
|
||
├── modules/
|
||
│ ├── file_manager.py # 路径校验、文件增删改、聚焦文件刷新
|
||
│ ├── terminal_manager.py # 多会话终端池与持久化管理
|
||
│ ├── terminal_ops.py # run_command / run_python 等终端工具实现
|
||
│ ├── memory_manager.py # 轻量记忆存储
|
||
│ ├── search_engine.py # 封装 Tavily 搜索
|
||
│ └── webpage_extractor.py # 网页正文提取
|
||
├── utils/
|
||
│ ├── api_client.py # HTTPX 异步客户端，支持流式/思考模式
|
||
│ ├── context_manager.py # 对话上下文与 token 统计
|
||
│ ├── conversation_manager.py# 持久化存储 + 索引管理
|
||
│ └── logger.py # 日志统一配置
|
||
├── static/
|
||
│ ├── index.html / app.js / style.css # Web 前端
|
||
│ └── terminal.html # 终端监控页
|
||
├── prompts/ # 系统提示词与模板
|
||
└── data/ # 对话、副本、记忆等持久化 artefacts
|
||
```
|
||
|
||
整体流程：
|
||
|
||
1. 用户通过 CLI 或 Web 端发起请求。
|
||
2. `context_manager` 整理上下文、聚焦文件、终端快照，组装成模型消息。
|
||
3. `utils/api_client.py` 以流式模式请求模型，并根据 `tool_calls` 调度 `modules/` 中的具体实现。
|
||
4. 工具执行结果写入对话记录，Web 前端实时收到 Socket.IO 推送。
|
||
5. 当写入类工具（如 `append_to_file`）执行完毕，系统会自动触发下一轮模型调用，让模型在新的上下文中继续工作或总结。
|
||
|
||
## 3. 主要功能解读
|
||
|
||
### 3.1 Web 前端体验
|
||
|
||
- 悬浮侧边栏列出历史对话，可搜索与加载；
|
||
- 消息区分思考流 (`thinking`)、正文流 (`text`)、工具状态；
|
||
- 右下角滚动锁定按钮可在“追踪最新输出”与“自由浏览历史”之间快速切换；
|
||
- 右侧面板展示聚焦文件内容，随写入工具执行自动刷新；
|
||
- 单独的 Token 面板实时展示累计消耗。
|
||
|
||
### 3.2 终端管理
|
||
|
||
- 终端会话由 `modules/terminal_manager.py` 维护，支持命名、切换、销毁；
|
||
- `terminal_session` 工具负责初始化或连接现有会话，`terminal_input` / `run_command` / `run_python` 等工具负责写入指令；
|
||
- Web 端可查看所有终端输出的实时流，并通过广播事件及时同步状态。
|
||
|
||
### 3.3 文件操作
|
||
|
||
- `file_manager._validate_path` 对路径做严格校验，禁止跨项目访问；
|
||
- `append_to_file` 通过 `finalize_pending_append` 实现流式写入和标记校验，缺少尾标时会提示再次调用；
|
||
- `modify_file` 提供块式补丁替换，`append_to_file` 负责大段写入；
|
||
- 聚焦文件机制（至多 3 个）保证重要文件内容保持在上下文中，便于模型对齐状态。
|
||
|
||
### 3.4 对话与记忆
|
||
|
||
- 所有对话写入 `data/conversations/conv_*.json`，附带 token 统计、工具记录；
|
||
- `memory_manager` 支持简单的长期记忆读写，可根据业务需求扩展；
|
||
- Web 端的 conversation API（查看、搜索、删除）直接调用 `web_terminal` 暴露的接口。
|
||
|
||
## 4. 快速上手
|
||
|
||
### 4.1 环境准备
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/你的用户名/你的仓库名.git
|
||
cd 你的仓库名
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 4.2 配置模型与可选工具
|
||
|
||
编辑 `config.py`：
|
||
|
||
```python
|
||
# API配置（选择兼容 OpenAI 的服务端）
|
||
API_BASE_URL = "https://api.deepseek.com"
|
||
API_KEY = "your-api-key"
|
||
MODEL_ID = "deepseek-chat"
|
||
|
||
# Tavily 搜索（可选）
|
||
TAVILY_API_KEY = "your-tavily-api-key"
|
||
```
|
||
|
||
其他常见配置例如：
|
||
|
||
- `DEFAULT_RESPONSE_MAX_TOKENS`：每次调用的最大输出 token；
|
||
- `MAX_TERMINALS`、`TERMINAL_BUFFER_SIZE`：终端并发与缓存；
|
||
- `FORBIDDEN_PATHS`、`FORBIDDEN_ROOT_PATHS`：安全白名单。
|
||
|
||
### 4.3 运行方式
|
||
|
||
```bash
|
||
# CLI 模式
|
||
python main.py
|
||
|
||
# Web 模式（推荐，可实时观察工具执行）
|
||
python web_server.py
|
||
# 默认地址: http://localhost:8091
|
||
```
|
||
|
||
CLI/Web 启动时都会提示选择“快速模式 / 思考模式”以及项目路径。
|
||
|
||
## 5. 常见工作流示例
|
||
|
||
### 5.1 构建简单的 Flask 服务
|
||
|
||
1. 模型先 `create_folder` / `create_file` 建立骨架；
|
||
2. 通过 `append_to_file` 编写 `app.py` / 模板文件；
|
||
3. 调用 `terminal_session` 启动开发服务器；
|
||
4. 使用第二个终端验证接口，最终总结执行结果。
|
||
|
||
### 5.2 数据处理脚本
|
||
|
||
1. 通过 `read_file` / `focus_file` 审阅现有数据；
|
||
2. `append_to_file` 写入新的分析脚本；
|
||
3. 使用 `run_python` 或持久化的 Python REPL 调试；
|
||
4. 将运行日志、聚焦文件内容写入总结，留存于对话记录中。
|
||
|
||
## 6. 已知问题与改进方向
|
||
|
||
- [ ] 代码结构待重构，部分模块耦合较高；
|
||
- [ ] 异常与超时处理不够细致；
|
||
- [ ] `append_to_file` 针对极大文件内容仍需更多优化；
|
||
- [ ] Windows 文件路径存在偶发兼容性问题；
|
||
- [ ] 缺乏系统级集成测试，主要依赖人工回放。
|
||
|
||
## 7. 项目定位
|
||
|
||
这是一个**学习和实验性质**的项目，主要目标是：
|
||
|
||
- 探索 AI Agent 与工具链协同的实现方式；
|
||
- 练习持久化终端管理、流式推理和对话重放；
|
||
- 搭建完整的 Web/CLI 交互闭环。
|
||
|
||
**不是**生产级别的工具（请勿在重要项目中直接使用）。
|
||
|
||
## 8. 贡献指南
|
||
|
||
- 🐛 **Bug 报告**：在 Issues 中提供复现步骤与日志；
|
||
- 💡 **功能建议**：描述场景、期望行为；
|
||
- 🔧 **代码贡献**：欢迎重构和重写模块，但请遵循现有目录结构；
|
||
- 📝 **文档改进**：补充使用手册、最佳实践或 FAQ。
|
||
|
||
> 代码大量由 AI 协助生成，可能存在冗余、命名不一致等问题，欢迎提交重构 PR。提交前请确保基本功能和工具调用流程保持可用。
|
||
|
||
## 9. 参考与致谢
|
||
|
||
- [Claude](https://claude.ai)：对话模式、思考显示、聚焦文件的灵感来源；
|
||
- [ChatGPT](https://chat.openai.com)：交互体验、工具调用设计；
|
||
- 感谢 DeepSeek、Qwen、Kimi 等开放模型服务，以及 Tavily 搜索 API 提供的数据能力支持。
|
||
|
||
## 10. 开源协议与联系方式
|
||
|
||
- 本项目采用 [MIT License](LICENSE)。
|
||
- Issues / Discussions：请前往仓库对应页面提交。
|
||
- 如果这个项目对你有帮助，欢迎点个 ⭐ Star！
|
||
|
||
---
|
||
|
||
如在使用中遇到问题，欢迎反馈；如果你也在探索 AI 驱动的自主开发流程，期待你的实践经验。***
|