docs: refresh README
This commit is contained in:
parent
dacc68f46a
commit
caaee38967
392
README.md
392
README.md
@ -1,195 +1,209 @@
|
|||||||
# AI Agent 系统
|
# AI Agent 系统
|
||||||
|
|
||||||
一个以“自主演练”为核心目标的智能编程助手。系统基于兼容 OpenAI API 的大语言模型（DeepSeek、Qwen、Kimi 等），围绕“真实开发工作流”构建：它能够持久化管理多个终端、操作文件、调用网络工具，并通过 Web 与 CLI 双入口提供可视化的实时反馈。
|
一个围绕“真实开发工作流”构建的智能编程助手。系统基于兼容 OpenAI API 的大模型（DeepSeek、Qwen、Kimi 等），提供 CLI 与 Web 双入口，支持文件/终端/网络等多种工具调用，并可持续追踪上下文、终端快照和对话历史。
|
||||||
|
|
||||||
> ⚠️ **项目状态**：这是一个个人学习项目，代码主要由 AI 辅助编写。目前功能基本可用，但代码结构有待优化（存在一定的 "屎山代码" 趋势）。欢迎贡献和建议！
|
> ⚠️ **项目定位**：学习与实验用的个人项目，代码大量由 AI 协助完成，尚未达到生产级稳定性。欢迎重构、提 Bug、补文档。
|
||||||
|
|
||||||
## 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 环境准备
|
|
||||||
|
|
||||||
```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 驱动的自主开发流程，期待你的实践经验。***
|
## 功能亮点
|
||||||
|
|
||||||
|
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 或提交改进建议 🙌
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user