# AI Agent 系统

一个围绕“真实开发工作流”构建的智能编程助手。系统基于兼容 OpenAI API 的大模型（DeepSeek、Qwen、Kimi 等），提供 CLI 与 Web 双入口，支持文件/终端/网络等多种工具调用，并可持续追踪上下文、终端快照和对话历史。

> ⚠️ **项目定位**：学习与实验用的个人项目，代码大量由 AI 协助完成，尚未达到生产级稳定性。欢迎重构、提 Bug、补文档。

---

## 功能亮点

1. **多模态阅读工具**  
   `read_file` 支持 `type=read/search/extract` 三种模式：可按行阅读片段、在文件内搜索关键词并返回上下文窗口、或一次抽取多段内容。所有模式都具备 UTF-8 校验与 `max_chars` 截断；Web 前端会直接显示“正在搜索/提取”等状态。

2. **模块化配置**  
   新的 `config/` 目录按主题拆分（`api.py`、`limits.py`、`paths.py`、`terminal.py` 等），既方便独立维护，又保持 `from config import ...` 的兼容导出。

3. **多终端 & 实时可视化**  
   支持最多 3 个持久化 Shell 会话 (`terminal_session`)，可在 Web 端查看每个终端的实时输出、切换会话、执行命令。CLI/Web 均可在“快速/思考模式”间切换。

4. **可控写入 & 文件安全**  
   `append_to_file` 采用双阶段协议（写入窗口 + 标记校验），`modify_file` 提供块级替换，`file_manager` 严格校验路径防止越界，聚焦文件机制保证关键信息始终在上下文中。

5. **对话持久化与回放**  
   所有对话、工具调用、token 统计都会写入 `data/conversations/`；Web 端提供会话搜索、加载、删除。`utils/context_manager` 可对长对话进行压缩并保留写入结果。

---

## 目录结构（节选）

```
.
├── main.py                  # CLI 入口，负责模式选择与终端初始化
├── web_server.py            # Flask + Socket.IO Web 服务
├── config/                  # 模块化配置目录
│   ├── __init__.py          # 聚合导出，兼容 from config import ...
│   ├── api.py               # 模型/API/Tavily 配置
│   ├── limits.py            # 上下文与工具阈值（read/run/terminal 等）
│   ├── terminal.py          # 多终端并发、缓冲、超时配置
│   ├── conversation.py      # 对话存储目录、索引、备份策略
│   ├── paths.py             # 项目/数据/日志路径
│   ├── security.py          # 禁止命令、路径、需要确认的工具
│   ├── ui.py                # 输出格式、日志等级、版本号
│   ├── memory.py            # 记忆文件路径
│   ├── todo.py              # 待办工具限制
│   └── auth.py              # 管理员账号配置
├── core/
│   ├── main_terminal.py     # CLI 主循环，解析命令并调度工具
│   ├── web_terminal.py      # Web 适配层：广播工具状态、维护 Web 会话
│   └── tool_config.py       # 工具分组与启用状态管理
├── modules/
│   ├── file_manager.py      # 路径校验、读写、搜索、抽取
│   ├── terminal_manager.py  # 多终端会话池
│   ├── terminal_ops.py      # run_command / run_python 实现
│   ├── memory_manager.py    # 长/短期记忆文件操作
│   ├── search_engine.py     # Tavily 搜索封装
│   ├── todo_manager.py      # 待办工具后端
│   ├── webpage_extractor.py # 网页提取与保存
│   └── persistent_terminal.py 等辅助模块
├── utils/
│   ├── api_client.py        # 调用模型 API（流式输出、工具触发）
│   ├── context_manager.py   # 对话上下文、聚焦文件、压缩逻辑
│   ├── conversation_manager.py # 对话索引、加载、保存
│   ├── logger.py            # 日志初始化
│   └── terminal_factory.py  # 终端实例工厂
├── static/
│   ├── index.html           # Web 主界面（对话/工具流）
│   ├── terminal.html        # 终端独立面板
│   ├── login.html / register.html  # 简易登录/注册页
│   ├── claude-colors-simple.html   # 主题示例
│   ├── app.js / style.css   # 前端逻辑与主样式
│   ├── vendor/              # 第三方库（CodeMirror / Socket.IO 客户端等）
│   ├── file_manager/        # 文件预览/编辑辅助资源
│   ├── debug.html           # 调试工具页
│   └── backup_*/            # 历史版本前端备份
├── prompts/                 # 系统提示词、工具提示模板
├── data/
│   ├── conversations/       # 默认对话存档
│   ├── memory.md / task_memory.md
│   └── conversation_history.json
├── users/                   # 多用户独立工作区（会话、项目、上传文件）
├── test/                    # 集成测试与脚本（如 api_interceptor_server）
├── logs/                    # 运行日志、debug_stream.log
├── project/                 # 默认项目目录（可在启动时指定）
└── README.md / AGENTS.md / requirements.txt 等文档
```

---

## 配置指南

1. **安装依赖**
   ```bash
   git clone <repo>
   cd <repo>
   pip install -r requirements.txt
   ```

2. **配置模型与限额**  
   在 `config/api.py` 设置大模型 API 信息，在 `config/limits.py` 调整工具阈值；常用示例：
   ```python
   # config/api.py
   API_BASE_URL = "https://api.deepseek.com"
   API_KEY = "sk-..."
   MODEL_ID = "deepseek-chat"
   TAVILY_API_KEY = "tvly-..."  # 可选

   # config/limits.py
   READ_TOOL_DEFAULT_MAX_CHARS = 30000
   READ_TOOL_DEFAULT_CONTEXT_BEFORE = 1
   READ_TOOL_DEFAULT_CONTEXT_AFTER = 1
   READ_TOOL_MAX_MATCHES = 50
   ```
   其他常用配置：
   - `config/paths.py`：项目根目录、数据/日志路径
   - `config/terminal.py`：多终端缓冲与超时
   - `config/security.py`：敏感命令、路径黑名单、需要确认的操作
   - `config/conversation.py`：对话存储、索引与备份
   - `config/ui.py`：日志格式与版本号

3. **运行方式**
   ```bash
   # CLI（推荐快速试验）
   python main.py

   # Web（推荐，可视化终端/工具流）
   python web_server.py
   # 访问 http://localhost:8091
   ```
   启动时可选择“快速模式”或“思考模式”，并指定项目路径（默认为 `./project`）。

---

## 主要工具与能力

| 工具 | 说明 |
| --- | --- |
| `read_file` | `type=read/search/extract`，支持行区间阅读、文件内关键词搜索（带上下文窗口和命中去重）、多段抽取；可设置 `max_chars` 控制返回体量。 |
| `focus_file` / `unfocus_file` | 将 UTF-8 文本持续注入上下文（最多 3 个），适合频繁查看/修改的文件。 |
| `append_to_file` / `modify_file` | 双阶段写入、大块内容追加、结构化补丁替换。 |
| `terminal_session` / `terminal_input` / `run_command` / `run_python` | 管理多终端会话、发送命令或一次性脚本；Web 端可实时查看输出。 |
| `web_search` / `extract_webpage` / `save_webpage` | 外部信息检索与网页内容提取/落盘。 |
| `todo_*` / `update_memory` | 记录待办事项、更新全局/任务记忆；适合长任务拆解与结果总结。 |

---

## Web 前端体验

- 左侧：对话列表，可搜索/加载历史记录。
- 中间：分层展示思考 (`thinking`)、助手回复、工具执行流；`read_file` 的三种模式会在工具卡片上直接标注“读取/搜索/提取”及执行结果。
- 右侧：聚焦文件即时预览，终端面板实时刷新，Token 统计显示本轮消耗。
- 底部：提供停止/清空/下载日志等快速操作。

> 当前版本尚未内置“文件管理器”式的可视化浏览器；若需查看文件树，可在终端使用 `ls` 或配合聚焦机制。

---

## 常见工作流

### 1. 阅读 + 修改核心代码
1. `read_file type=search` 定位关键函数。
2. `read_file type=extract` 抽取需要改动的多段内容。
3. `focus_file` 保持核心文件常驻上下文，配合 `modify_file` 输出补丁。

### 2. 构建脚手架并验证
1. `create_folder` / `create_file` / `append_to_file` 生成工程骨架。
2. `terminal_session` 启动开发服务器；`terminal_input` 查看日志。
3. `todo_*` 记录剩余任务，`update_memory` 写入结论。

### 3. 信息搜集与整理
1. `web_search` 获取外部资料。
2. `extract_webpage` 抽取正文，或 `save_webpage` 落盘。
3. `read_file type=search/extract` 在本地笔记中快速定位与摘录。

---

## 开发与测试建议

- **本地运行**：`python main.py` / `python web_server.py`；调试 Web 端建议同时开启浏览器控制台观察 WebSocket 日志。
- **日志**：CLI 模式下输出使用 `OUTPUT_FORMATS` 定义的 Emoji；Web 模式所有工具事件都会写入 `logs/debug_stream.log`。
- **数据隔离**：多用户目录位于 `users/<username>/`；请避免将真实密钥提交到仓库，必要时扩展 `.gitignore`。
- **测试**：暂未配置自动化测试，可参考 `test/` 目录（如 `api_interceptor_server.py`）编写自定义脚本。

---

## 已知限制

- 缺乏文件管理器式的可视化浏览；需依赖终端与聚焦机制。
- 主要依赖手动测试，尚无完备的自动化/集成测试。
- Windows 路径偶有兼容性问题，建议在类 Unix 环境下运行。
- 仍有部分旧代码需重构（异步策略、异常处理、配置热更新等）。

---

## 贡献方式

- 提 Bug：附复现场景与日志，方便排查。
- 提需求：描述使用场景、期望行为与约束。
- 代码贡献：请遵循现有目录结构与模块职责，提交 PR 前确保基础功能可用。
- 文档贡献：欢迎补充 FAQ、最佳实践或脚本案例。

> Commit 建议使用 Conventional Commits；首次克隆请运行 `pip install -r requirements.txt` 并根据需要调整 `config/` 下的参数。

---

## 许可与致谢

- 协议：MIT。
- 致谢：感谢 DeepSeek、Qwen、Kimi 等兼容 OpenAI 的 API，及 Tavily 搜索服务提供的数据能力；同时参考了 Claude/ChatGPT 的交互体验设计。
- 若本项目对你有帮助，欢迎 Star 或提交改进建议 🙌