218 lines
12 KiB
Markdown
218 lines
12 KiB
Markdown
# 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. **配置环境变量（敏感信息）**
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env，填写 API Key / 管理员哈希 / 终端沙箱配置
|
||
```
|
||
关键项说明：
|
||
- `AGENT_API_BASE_URL` / `AGENT_API_KEY` / `AGENT_MODEL_ID`：模型服务入口（必要）。
|
||
- `AGENT_THINKING_*`：可选的“思考模式”专用模型，不填则回退到基础模型。
|
||
- `AGENT_ADMIN_USERNAME` / `AGENT_ADMIN_PASSWORD_HASH`：管理员账号（使用 `generate_password_hash` 生成 PBKDF2 哈希）。
|
||
- `WEB_SECRET_KEY`：Flask Session 密钥，建议使用 `secrets.token_hex(32)`。
|
||
- `TERMINAL_SANDBOX_*`：终端容器镜像、挂载路径、资源额度（默认 0.5 核心 + 1GB 内存），若本地无 Docker，可将 `TERMINAL_SANDBOX_REQUIRE` 置为 `0`，系统会自动退回宿主机终端。
|
||
- `PROJECT_MAX_STORAGE_MB`：单个项目允许的最大磁盘占用（默认 2GB，超限写入会被拒绝）。
|
||
- `MAX_ACTIVE_USER_CONTAINERS`：并发允许的用户容器数量，超过后会提示“资源繁忙”。
|
||
|
||
3. **（可选）调整 Python 配置**
|
||
- `config/limits.py`：读写/搜索等工具上限。
|
||
- `config/paths.py`：项目、日志、数据目录。
|
||
- `config/terminal.py`：终端并发数、缓冲大小（环境变量会覆盖默认值）。
|
||
- `config/security.py`：命令/路径黑名单及需要二次确认的工具。
|
||
|
||
4. **运行方式**
|
||
```bash
|
||
# CLI（推荐快速试验）
|
||
python main.py
|
||
|
||
# Web（推荐，可视化终端/工具流）
|
||
python web_server.py
|
||
# 访问 http://localhost:8091
|
||
```
|
||
启动时可选择“快速模式”或“思考模式”，并指定项目路径（默认为 `./project`）。
|
||
|
||
5. **子智能体测试服务（可选）**
|
||
```bash
|
||
python sub_agent/server.py
|
||
# 默认监听 8092 端口，供 create_sub_agent/wait_sub_agent 工具调用
|
||
```
|
||
当前实现为占位服务，会在 `sub_agent/tasks/` 下生成交付文件，并立即返回测试结果，便于主智能体打通基础流程。
|
||
|
||
---
|
||
|
||
## 主要工具与能力
|
||
|
||
| 工具 | 说明 |
|
||
| --- | --- |
|
||
| `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 日志。
|
||
- **终端隔离**：默认通过 `TERMINAL_SANDBOX_*` 配置启动 Docker 容器执行命令，每个终端挂载独立工作区；若本地无容器运行时，可暂时将 `TERMINAL_SANDBOX_REQUIRE=0` 退回宿主机模式。
|
||
- **快捷命令环境**：`run_command` / `run_python` 会在专用的“工具容器”中执行，复用同一虚拟环境与依赖，减少对宿主机的影响；空闲超过 `TOOLBOX_TERMINAL_IDLE_SECONDS` 会自动释放。
|
||
- **资源保护**：容器默认限制为 0.5 vCPU / 1GB 内存，项目磁盘超过 2GB 会拒绝写入；当活跃用户容器达到 `MAX_ACTIVE_USER_CONTAINERS` 时系统会返回“资源繁忙”提示，避免服务器过载。
|
||
- **日志**：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 或提交改进建议 🙌
|