From caaee38967bffbee5ef2da6025558052f79dc768 Mon Sep 17 00:00:00 2001 From: JOJO <1498581755@qq.com> Date: Fri, 14 Nov 2025 18:53:04 +0800 Subject: [PATCH] docs: refresh README --- README.md | 392 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 203 insertions(+), 189 deletions(-) diff --git a/README.md b/README.md index 5eb007a..dd1489e 100644 --- a/README.md +++ b/README.md @@ -1,195 +1,209 @@ # AI Agent 系统 -一个以“自主演练”为核心目标的智能编程助手。系统基于兼容 OpenAI API 的大语言模型（DeepSeek、Qwen、Kimi 等），围绕“真实开发工作流”构建：它能够持久化管理多个终端、操作文件、调用网络工具，并通过 Web 与 CLI 双入口提供可视化的实时反馈。 +一个围绕“真实开发工作流”构建的智能编程助手。系统基于兼容 OpenAI API 的大模型（DeepSeek、Qwen、Kimi 等），提供 CLI 与 Web 双入口，支持文件/终端/网络等多种工具调用，并可持续追踪上下文、终端快照和对话历史。 -> ⚠️ **项目状态**：这是一个个人学习项目，代码主要由 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` 工具采用“二段式”协议：先向模型发放写入窗口，再监听其流式输出，自动验证 `<<>>` / `<<>>` 标记，缺失时会在第二次工具返回中提示补救，保证文件写入可靠且可追溯。 - -- **双模式推理** - 在 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 协助完成，尚未达到生产级稳定性。欢迎重构、提 Bug、补文档。 --- -如在使用中遇到问题，欢迎反馈；如果你也在探索 AI 驱动的自主开发流程，期待你的实践经验。*** +## 功能亮点 + +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 + cd + 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//`；请避免将真实密钥提交到仓库，必要时扩展 `.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 或提交改进建议 🙌