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 环境准备

# 克隆仓库
git clone https://github.com/你的用户名/你的仓库名.git
cd 你的仓库名

# 安装依赖
pip install -r requirements.txt

4.2 配置模型与可选工具

编辑 config.py：

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

# 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：对话模式、思考显示、聚焦文件的灵感来源；
• ChatGPT：交互体验、工具调用设计；
• 感谢 DeepSeek、Qwen、Kimi 等开放模型服务，以及 Tavily 搜索 API 提供的数据能力支持。

10. 开源协议与联系方式

• 本项目采用 MIT License。
• Issues / Discussions：请前往仓库对应页面提交。
• 如果这个项目对你有帮助，欢迎点个 ⭐ Star！

---

如在使用中遇到问题，欢迎反馈；如果你也在探索 AI 驱动的自主开发流程，期待你的实践经验。***