# 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 驱动的自主开发流程，期待你的实践经验。***