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. 安装依赖

   git clone <repo>
   cd <repo>
   pip install -r requirements.txt
   

2. 配置环境变量（敏感信息）

   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. 运行方式

   # CLI（推荐快速试验）
   python main.py
   
   # Web（推荐，可视化终端/工具流）
   python web_server.py
   # 访问 http://localhost:8091
   

   启动时可选择“快速模式”或“思考模式”，并指定项目路径（默认为 ./project）。

5. 子智能体测试服务（可选）

   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 或提交改进建议 🙌