qing
254fbf4628
README.md 修复： - 新增 ask_user 工具到工具列表 - 补充配置表中缺失的 17 个字段（system/scheduler/api/context/memo/files/commands/web/memory/conversation/tools/compressor/proxy） - 补充对话压缩完整配置项 README.robot.md 新增： - 17 章节完整技术手册（~500 行） - 架构图、数据流、协议详情 - 19 个工具的完整实现信息 - 配置参考（含所有字段说明） - 已知限制与安全建议 - 部署与故障排查指南
824 lines
28 KiB
Markdown
824 lines
28 KiB
Markdown
# AIBOX 模块技术手册
|
||
|
||
> 文档版本：2026-07-30
|
||
> 代码版本：v2.0
|
||
> 语言：Python 3.8+
|
||
> 定位：单 AI 智能体系统（独立于微服务体系）
|
||
|
||
---
|
||
|
||
## 一、模块概述
|
||
|
||
### 1.1 定位
|
||
|
||
**AIBOX** 是一个基于 DeepSeek API 的单 AI 智能体系统，通过 WebSocket 与客户端双向通信。所有任务（文件操作、网页访问、记忆管理、任务调度等）都由 AI 对话驱动执行。
|
||
|
||
### 1.2 与微服务体系的关系
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| 启动方式 | `core`(PMC) 通过 `init.txt` 拉起 |
|
||
| 监听端口 | 8765（WebSocket） |
|
||
| 与主干关系 | **完全独立**，不调用 waf/gateway/dnfs 等服务 |
|
||
| 数据存储 | 本地 `~/.aibox/`（不使用 db:8005） |
|
||
| 前端 | 独立 HTML 页面 |
|
||
|
||
### 1.3 核心特性
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| AI 对话 | DeepSeek API + 思考模式（reasoning 流式输出） |
|
||
| 实时通信 | WebSocket 双向通信 + 流式输出 |
|
||
| 工具系统 | 19 个内置工具（文件/网页/记忆/任务/命令等） |
|
||
| 技能扩展 | 热重载 `.py` 脚本和 `.md` 技能 |
|
||
| 记忆管理 | 自动保存/检索对话记忆 |
|
||
| 任务调度 | 一次性/重复/即时任务 |
|
||
| 自我进化 | AI 动态更新角色与用户画像 |
|
||
| 对话压缩 | 自动压缩长对话历史 |
|
||
| 多语言 | 中英自动检测 |
|
||
|
||
---
|
||
|
||
## 二、技术架构
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 层 | 技术 | 用途 |
|
||
|----|------|------|
|
||
| 语言 | Python 3.8+ | 主程序 |
|
||
| 通信 | websockets | WebSocket 服务器 |
|
||
| AI | DeepSeek API | 智能对话、工具调用、流式输出 |
|
||
| 存储 | SQLite | 记忆数据库、备忘录任务 |
|
||
| HTTP | requests | 网页访问、API 调用 |
|
||
| HTML 解析 | beautifulsoup4 | 网页内容提取 |
|
||
| SSH | paramiko | SSH 远程执行（技能） |
|
||
| 加密 | cryptography | AES 加密（技能） |
|
||
|
||
### 2.2 架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ WebSocket 客户端 │
|
||
│ (entry.html / frontend.html / client.py / voice_client.py) │
|
||
└────────────────────────┬────────────────────────────────────┘
|
||
│ ws://localhost:8765
|
||
┌────────────────────────▼────────────────────────────────────┐
|
||
│ WebSocket 服务器 (main.py) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ 消息处理器 │ │ 命令处理器 │ │ 任务调度器 │ │
|
||
│ │ (handle_msg) │ │ (handle_cmd) │ │ (MemoScheduler) │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
|
||
└─────────┼─────────────────┼───────────────────┼─────────────┘
|
||
│ │ │
|
||
┌─────────▼─────────────────▼───────────────────▼─────────────┐
|
||
│ AI 对话引擎 (DeepSeekChat) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ 提示词管理器 │ │ 工具注册器 │ │ 对话压缩器 │ │
|
||
│ │ (PromptMgr) │ │ (ToolRegistry)│ │ (ConversationComp)│ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
|
||
└─────────┼─────────────────┼───────────────────┼─────────────┘
|
||
│ │ │
|
||
┌─────────▼─────────────────▼───────────────────▼─────────────┐
|
||
│ 数据持久层 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ 记忆数据库 │ │ 备忘录 DB │ │ 对话历史管理器 │ │
|
||
│ │ (memories.db) │ │ (memos.db) │ │ (JSON files) │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.3 核心数据流
|
||
|
||
```
|
||
客户端请求 → WebSocketHandler.handle_message()
|
||
↓
|
||
┌─── 消息类型判断 ───┬─── 命令类型判断 ───┬─── 任务操作判断 ───┐
|
||
│ type="message" │ type="command" │ type="task" │
|
||
└─────────┬─────────┴─────────┬─────────┴─────────┬─────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
AI 对话引擎 命令处理器 任务管理器
|
||
(DeepSeekChat) (handle_command) (handle_task)
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
工具调用循环 系统命令执行 任务 CRUD 操作
|
||
(ToolRegistry) (/new, /list...) (add, complete...)
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
流式响应生成 命令结果返回 任务状态广播
|
||
(chunk → complete) (command_result) (task_status)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、代码结构
|
||
|
||
### 3.1 文件结构
|
||
|
||
```
|
||
aibox/
|
||
├── main.py # 核心（~8000 行）
|
||
│ ├── WebSocketHandler # WebSocket 消息处理
|
||
│ ├── DeepSeekChat # AI 对话引擎
|
||
│ ├── PromptManager # 提示词管理
|
||
│ ├── Tool + 19 个工具类 # 工具系统
|
||
│ ├── MemoScheduler # 任务调度器
|
||
│ ├── MemoryManager # 记忆管理
|
||
│ └── ConfigManager # 配置管理
|
||
├── client.py # CLI WebSocket 客户端
|
||
├── voice_client.py # 语音客户端（语音输入/输出）
|
||
├── entry.html # Web 前端入口
|
||
├── frontend.html # Web 主页面
|
||
├── skills/ # 内置扩展技能
|
||
│ ├── hello-world.py # 示例技能
|
||
│ ├── bing_search.py # 必应搜索
|
||
│ ├── ssh-exec.py # SSH 远程执行
|
||
│ ├── sftp-transfer.py # SFTP 传输
|
||
│ ├── facerec.py # 人脸识别
|
||
│ ├── aes-crypto.py # AES 加密
|
||
│ ├── gitclient.py # Git 操作
|
||
│ └── *.md # Markdown 技能（prompt）
|
||
├── tasks/ITIL.md # ITIL 任务模板
|
||
├── SKILLS_FORMAT.md # 技能格式规范
|
||
├── requirements.txt
|
||
├── _run.sh # core 拉起的启动脚本
|
||
├── _runcli.sh # CLI 启动
|
||
├── _set.sh # 依赖安装
|
||
├── _setenv.sh # 环境变量设置
|
||
└── README.md # 用户文档
|
||
```
|
||
|
||
### 3.2 main.py 核心类
|
||
|
||
| 类名 | 行号 | 功能 |
|
||
|------|------|------|
|
||
| `Tool` | L3642 | 工具基类（抽象方法：get_name/execute） |
|
||
| `WebSocketHandler` | ~L1900 | WebSocket 消息处理 |
|
||
| `DeepSeekChat` | ~L2400 | AI 对话引擎 |
|
||
| `PromptManager` | ~L1050 | 提示词文件管理 |
|
||
| `ConfigManager` | ~L1080 | 配置加载/合并 |
|
||
| `MemoryManager` | ~L5200 | 记忆 CRUD |
|
||
| `MemoScheduler` | ~L4700 | 任务调度器 |
|
||
| `ConversationCompressor` | ~L6480 | 对话压缩 |
|
||
|
||
### 3.3 运行期数据
|
||
|
||
```
|
||
~/.aibox/
|
||
├── config.json # 配置（自动生成默认值）
|
||
├── prompts/
|
||
│ ├── 00_IDENTITY.md # 用户身份（AI 可更新）
|
||
│ ├── 1_*.md # 基础技能提示词
|
||
│ ├── 99_SOUL.md # AI 灵魂定义（AI 可更新）
|
||
│ └── 100_STATUS.md # AI 状态记录
|
||
├── skills/ # 用户扩展技能
|
||
├── memories.db # 记忆库（SQLite）
|
||
├── memos.db # 备忘录任务（SQLite）
|
||
├── current_conversation.json # 当前对话上下文
|
||
├── conversation_history.json # 对话索引
|
||
├── archive/ # 历史对话归档
|
||
├── tool_results/ # 工具执行结果缓存
|
||
└── ai.log # 日志（自动轮转）
|
||
```
|
||
|
||
---
|
||
|
||
## 四、工具系统
|
||
|
||
### 4.1 工具基类
|
||
|
||
```python
|
||
class Tool:
|
||
"""工具基类，所有工具必须继承此类"""
|
||
|
||
def get_name(self) -> str:
|
||
"""返回工具名称（抽象方法，必须实现）"""
|
||
pass
|
||
|
||
def get_description(self) -> str:
|
||
"""返回工具描述"""
|
||
return ""
|
||
|
||
def get_parameters(self) -> Dict:
|
||
"""返回工具参数（JSON Schema 格式）"""
|
||
return {"type": "object", "properties": {}}
|
||
|
||
def execute(self, **kwargs) -> str:
|
||
"""执行工具（抽象方法，必须实现）"""
|
||
pass
|
||
|
||
def execute_streaming(self, **kwargs):
|
||
"""流式执行（可选实现）"""
|
||
return None
|
||
```
|
||
|
||
### 4.2 内置工具一览
|
||
|
||
| 工具名 | 类名 | 行号 | 功能 |
|
||
|--------|------|------|------|
|
||
| `read_file` | `ReadFileTool` | L5762 | 读取文件（支持 head/tail/paging） |
|
||
| `write_file` | `WriteFileTool` | L5884 | 写入/追加文件 |
|
||
| `list_files` | `ListFilesTool` | L5961 | 目录列表 |
|
||
| `web` | `SimpleWebCrawlerTool` | L5637 | 网页抓取（标题/正文/链接） |
|
||
| `memory` | `MemoryTool` | L5280 | 记忆 CRUD（search/save/delete） |
|
||
| `memo` | `MemoTool` | L4753 | 任务 CRUD（add/complete/list/search） |
|
||
| `run_command` | `CommandLineTool` | L6150 | 系统命令执行（支持超时） |
|
||
| `search_skills` | `SearchSkillsTool` | L4076 | 搜索扩展技能 |
|
||
| `reload_skills` | `ReloadSkillsTool` | L4199 | 热重载技能 |
|
||
| `create_skill` | `CreateSkillTool` | L4409 | AI 自主创建技能 |
|
||
| `install_skill` | `InstallSkillTool` | L4306 | 技能安装指引 |
|
||
| `ask_user` | `AskUserTool` | L4275 | 向用户提问 |
|
||
| `update_identity` | `UpdateIdentityTool` | L4518 | 更新用户身份 |
|
||
| `update_soul` | `UpdateSoulTool` | L4582 | 更新 AI 灵魂 |
|
||
| `save_memory_and_end_conversation` | `SaveMemoryAndEndConversationTool` | L4646 | 保存记忆并结束对话 |
|
||
| `get_current_time` | `GetCurrentTimeTool` | L6055 | 获取当前时间 |
|
||
| `calculator` | `CalculatorTool` | L6095 | 数学计算 |
|
||
| `set_proxy` | `SetProxyTool` | L6415 | 设置 SOCKS5 代理 |
|
||
| `get_proxy` | `GetProxyTool` | L6453 | 查看代理配置 |
|
||
|
||
### 4.3 工具执行流程
|
||
|
||
```
|
||
AI 决定调用工具 → 生成 JSON 格式工具调用
|
||
↓
|
||
DeepSeekChat.process_tool_calls()
|
||
↓
|
||
┌─── 解析工具名 ───┬─── 解析参数 ───┬─── 注册工具 ───┐
|
||
└─────────────────┴───────────────┴─────────────────┘
|
||
↓
|
||
ToolRegistry.get_tool(name)
|
||
↓
|
||
tool.execute(**params)
|
||
↓
|
||
┌─── 结果处理 ───┬─── 错误处理 ───┬─── 长结果截断 ───┐
|
||
└─────────────────┴───────────────┴─────────────────┘
|
||
↓
|
||
返回结果给 AI → AI 继续生成响应
|
||
```
|
||
|
||
---
|
||
|
||
## 五、WebSocket 协议
|
||
|
||
### 5.1 客户端 → 服务器
|
||
|
||
| 类型 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| `message` | `content` | 普通对话文本 |
|
||
| `command` | `command` | 斜杠命令（如 `/new`, `/help`） |
|
||
| `task` | `action`, `title`, ... | 任务操作（add/complete/list） |
|
||
| `ping` | — | 心跳检测 |
|
||
|
||
### 5.2 服务器 → 客户端
|
||
|
||
| 类型 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| `chunk` | `content` | AI 响应片段（流式） |
|
||
| `complete` | `content` | AI 响应完成 |
|
||
| `reasoning` | `content` | AI 思考过程 |
|
||
| `error` | `content` | 错误信息 |
|
||
| `command_result` | `content` | 命令执行结果 |
|
||
| `task_status` | `task_id`, `status` | 任务状态更新 |
|
||
| `task_process` | `task_id`, `content` | 任务执行过程 |
|
||
| `dialogue_ended` | — | 对话结束 |
|
||
| `dialogue_reset` | — | 对话重置完成 |
|
||
| `info` | `content` | 系统信息 |
|
||
| `pong` | — | Ping 响应 |
|
||
|
||
### 5.3 消息流示例
|
||
|
||
```
|
||
// 普通对话
|
||
Client: {type: "message", content: "你好"}
|
||
Server: {type: "chunk", content: "你好！"}
|
||
Server: {type: "complete", content: "你好！有什么可以帮你的吗？"}
|
||
|
||
// 工具调用
|
||
Server: {type: "tool_call", tool: "web", args: {url: "..."}}
|
||
Server: {type: "chunk", content: "网页内容：..."}
|
||
Server: {type: "complete", content: "网页已获取"}
|
||
|
||
// 任务执行
|
||
Client: {type: "task", action: "add", title: "提醒", delay: 60}
|
||
Server: {type: "command_result", content: "任务已添加"}
|
||
// 60 秒后
|
||
Server: {type: "task_status", task_id: 1, status: "executing"}
|
||
Server: {type: "task_process", task_id: "1", content: "处理中..."}
|
||
Server: {type: "task_status", task_id: 1, status: "complete"}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、任务系统
|
||
|
||
### 6.1 任务类型
|
||
|
||
| 类型 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| 一次性 | `reminder_time` | 指定执行时间 |
|
||
| 重复（daily） | `repeat_type: "daily"` | 每天执行 |
|
||
| 重复（weekly） | `repeat_type: "weekly"`, `weekday` | 每周指定日 |
|
||
| 重复（monthly） | `repeat_type: "monthly"`, `day` | 每月指定日 |
|
||
| 重复（custom） | `repeat_type: "custom"`, `interval`, `unit` | 自定义间隔 |
|
||
| 即时 | `is_immediate: true` | 立即执行 |
|
||
|
||
### 6.2 任务调度流程
|
||
|
||
```
|
||
MemoScheduler._run() # 后台线程
|
||
↓
|
||
检查所有未完成任务
|
||
↓
|
||
┌─── 到达时间？ ───┬─── 未完成？ ───┬─── 允许用户任务？ ───┐
|
||
└─────────────────┴───────────────┴─────────────────┘
|
||
↓
|
||
创建新的 AI 对话（将任务内容作为用户输入）
|
||
↓
|
||
AI 处理任务（可能调用多个工具）
|
||
↓
|
||
标记任务已触发
|
||
↓
|
||
广播结果到所有客户端
|
||
↓
|
||
计算下一次执行时间（重复任务）
|
||
```
|
||
|
||
### 6.3 数据库表结构
|
||
|
||
```sql
|
||
-- memories.db
|
||
CREATE TABLE memories (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
user_id TEXT,
|
||
content TEXT,
|
||
importance INTEGER DEFAULT 2,
|
||
created_at TEXT,
|
||
updated_at TEXT,
|
||
embedding BLOB -- 预留向量嵌入
|
||
);
|
||
|
||
-- memos.db
|
||
CREATE TABLE memos (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
title TEXT,
|
||
content TEXT,
|
||
reminder_time TEXT,
|
||
repeat_type TEXT,
|
||
repeat_interval INTEGER,
|
||
repeat_interval_unit TEXT,
|
||
is_immediate INTEGER DEFAULT 0,
|
||
status TEXT DEFAULT 'pending',
|
||
is_triggered INTEGER DEFAULT 0,
|
||
created_at TEXT,
|
||
user_id TEXT
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 七、记忆系统
|
||
|
||
### 7.1 记忆操作
|
||
|
||
| 操作 | AI 调用 | 说明 |
|
||
|------|---------|------|
|
||
| 保存 | `memory(action="save", content=...)` | AI 主动保存重要信息 |
|
||
| 搜索 | `memory(action="search", query=...)` | 按关键词搜索记忆 |
|
||
| 列表 | `memory(action="list", page=...)` | 分页浏览所有记忆 |
|
||
| 删除 | `memory(action="delete", id=...)` | 删除指定记忆 |
|
||
|
||
### 7.2 自动记忆
|
||
|
||
- AI 在对话结束时（`/exit`）自动保存关键信息
|
||
- 可配置 `system.auto_save_memory` 开关
|
||
- 重要度（importance）1-5 级
|
||
|
||
---
|
||
|
||
## 八、对话压缩
|
||
|
||
### 8.1 压缩触发条件
|
||
|
||
| 条件 | 阈值（默认） | 配置项 |
|
||
|------|-------------|--------|
|
||
| 消息数超过 | 200 条 | `compress_message_threshold` |
|
||
| Token 数超过 | 120000 | `compress_token_threshold` |
|
||
|
||
### 8.2 压缩流程
|
||
|
||
```
|
||
检测到阈值触发
|
||
↓
|
||
保留最近 8 条消息（compress_keep_recent）
|
||
↓
|
||
对早期消息按时间衰减加权（weight_decay_factor=0.01）
|
||
↓
|
||
调用 AI 生成摘要（max_input_chars=6000）
|
||
↓
|
||
将摘要作为系统消息插入
|
||
↓
|
||
压缩后继续对话
|
||
```
|
||
|
||
### 8.3 压缩配置
|
||
|
||
```json
|
||
{
|
||
"compressor": {
|
||
"min_messages_to_compress": 5,
|
||
"weight_decay_factor": 0.01,
|
||
"max_input_chars": 6000,
|
||
"llm_max_tokens": 800
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 九、扩展技能系统
|
||
|
||
### 9.1 技能类型
|
||
|
||
| 类型 | 格式 | 存储位置 |
|
||
|------|------|---------|
|
||
| 可执行脚本 | Python/Shell，支持 `--help` | `~/.aibox/skills/` |
|
||
| Markdown 技能 | `.md` 文件，首行为简介 | `~/.aibox/skills/` |
|
||
|
||
### 9.2 内置技能
|
||
|
||
| 技能名 | 文件 | 功能 |
|
||
|--------|------|------|
|
||
| hello-world | `skills/hello-world.py` | 示例技能 |
|
||
| bing_search | `skills/bing_search.py` | 必应搜索 |
|
||
| ssh-exec | `skills/ssh-exec.py` | SSH 远程执行 |
|
||
| sftp-transfer | `skills/sftp-transfer.py` | SFTP 文件传输 |
|
||
| facerec | `skills/facerec.py` | 人脸识别 |
|
||
| aes-crypto | `skills/aes-crypto.py` | AES 加密/解密 |
|
||
| gitclient | `skills/gitclient.py` | Git 操作封装 |
|
||
|
||
### 9.3 技能热重载
|
||
|
||
```python
|
||
# 新技能放置到 ~/.aibox/skills/
|
||
# 调用 reload_skills 工具
|
||
# AI 下次对话时即可使用
|
||
```
|
||
|
||
### 9.4 技能格式规范
|
||
|
||
详见 [SKILLS_FORMAT.md](file:///Users/qingsong/micro_servers/aibox/SKILLS_FORMAT.md)
|
||
|
||
---
|
||
|
||
## 十、配置参考
|
||
|
||
### 10.1 完整配置项
|
||
|
||
#### system 段
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `save_dir` | str | `~/.aibox` | 数据存储目录 |
|
||
| `datetime_format` | str | `%Y-%m-%d %H:%M:%S` | 日期时间格式 |
|
||
| `date_format` | str | `%Y%m%d_%H%M%S` | 文件名日期格式 |
|
||
| `debug_level` | int | `1` | 调试级别 0-3 |
|
||
| `load_history_by_default` | bool | `true` | 启动时加载历史对话 |
|
||
| `log_file` | str | `~/.aibox/ai.log` | 日志文件路径 |
|
||
| `log_max_size` | int | `10485760` | 日志最大字节数（10MB） |
|
||
| `log_backup_count` | int | `5` | 日志备份数量 |
|
||
| `websocket_host` | str | `localhost` | WebSocket 监听地址 |
|
||
| `websocket_port` | int | `8765` | WebSocket 监听端口 |
|
||
| `skills_dir` | str | `~/.aibox/skills` | 技能目录 |
|
||
| `prompts_dir` | str | `~/.aibox/prompts` | 提示词目录 |
|
||
|
||
#### scheduler 段
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `enabled` | bool | `true` | 启用任务调度器 |
|
||
| `check_interval` | float | `1.0` | 检查间隔（秒） |
|
||
| `max_tasks_per_run` | int | `10` | 单次最大触发任务数 |
|
||
| `broadcast_enabled` | bool | `true` | 广播任务执行结果 |
|
||
|
||
#### api 段
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `deepseek_api_url` | str | `https://api.deepseek.com/chat/completions` | API URL |
|
||
| `deepseek_model` | str | `deepseek-v4-flash` | 模型名 |
|
||
| `api_key_env` | str | `DEEPSEEK_API_KEY` | API Key 环境变量名 |
|
||
| `timeout` | int | `30` | 请求超时（秒） |
|
||
| `temperature` | float | `0.7` | 生成温度 0-1 |
|
||
|
||
#### context 段
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `max_history_messages` | int | `500` | 历史消息上限 |
|
||
| `max_context_messages` | int | `120` | 上下文窗口 |
|
||
| `max_tokens` | int | `8192` | 最大生成 Token |
|
||
| `max_history_conversations` | int | `5` | 保留历史对话数 |
|
||
| `preserve_system_prompts` | bool | `true` | 保留系统提示词 |
|
||
| `compress_enabled` | bool | `true` | 启用对话压缩 |
|
||
| `compress_message_threshold` | int | `200` | 压缩消息阈值 |
|
||
| `compress_token_threshold` | int | `120000` | 压缩 Token 阈值 |
|
||
| `compress_ratio` | float | `0.2` | 压缩保留比例 |
|
||
| `compress_keep_recent` | int | `8` | 保留最近消息数 |
|
||
|
||
#### memo 段
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `default_reminder_minutes` | int | `60` | 默认提醒分钟数 |
|
||
| `max_memos_per_check` | int | `10` | 单次最大触发任务数 |
|
||
| `allow_user_tasks` | bool | `true` | 允许用户创建任务 |
|
||
|
||
#### proxy 段
|
||
|
||
| 字段 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `type` | str | `""` | 代理类型（socks5/http） |
|
||
| `host` | str | `""` | 代理主机 |
|
||
| `port` | int | `0` | 代理端口 |
|
||
| `username` | str | `""` | 代理用户名 |
|
||
| `password` | str | `""` | 代理密码 |
|
||
|
||
### 10.2 环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `DEEPSEEK_API_KEY` | DeepSeek API Key（必填） |
|
||
| `AI_CONFIG_PATH` | 自定义配置文件路径 |
|
||
|
||
---
|
||
|
||
## 十一、命令行参数
|
||
|
||
```bash
|
||
python main.py [选项]
|
||
```
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `--verbose`, `-v` | flag | `false` | 显示详细日志 |
|
||
| `--debug` | int | `None` | 调试级别 0-3 |
|
||
| `--lang` | str | `None` | 强制语言 zh/en |
|
||
| `--host` | str | `None` | 覆盖 WebSocket 主机 |
|
||
| `--port` | int | `None` | 覆盖 WebSocket 端口 |
|
||
| `--no-scheduler` | flag | `false` | 禁用任务调度器 |
|
||
| `--scheduler-interval` | float | `1.0` | 调度器检查间隔 |
|
||
| `--config`, `-c` | str | `None` | 指定配置文件 |
|
||
| `--check-memo` | flag | `false` | 检查到期任务并退出 |
|
||
| `--memo-add` | str | `None` | 添加任务（CLI） |
|
||
| `--memo-list` | flag | `false` | 列出任务 |
|
||
| `--memo-complete` | int | `None` | 完成指定任务 |
|
||
|
||
### 使用示例
|
||
|
||
```bash
|
||
# 启动服务器
|
||
python main.py
|
||
|
||
# 详细日志 + 指定端口
|
||
python main.py --verbose --port 9000
|
||
|
||
# 检查并执行到期任务（cron 场景）
|
||
python main.py --check-memo
|
||
|
||
# 添加任务
|
||
python main.py --memo-add "每日备份|执行数据库备份|+1h"
|
||
|
||
# 列出所有任务
|
||
python main.py --memo-list
|
||
```
|
||
|
||
---
|
||
|
||
## 十二、前端集成
|
||
|
||
### 12.1 前端文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `entry.html` | 简单入口页（重定向到 frontend.html） |
|
||
| `frontend.html` | 完整前端界面（对话/任务/设置） |
|
||
|
||
### 12.2 WebSocket 连接
|
||
|
||
```javascript
|
||
const ws = new WebSocket('ws://localhost:8765');
|
||
|
||
// 发送消息
|
||
ws.send(JSON.stringify({
|
||
type: 'message',
|
||
content: '你好'
|
||
}));
|
||
|
||
// 接收消息
|
||
ws.onmessage = (event) => {
|
||
const data = JSON.parse(event.data);
|
||
switch (data.type) {
|
||
case 'chunk':
|
||
appendToChat(data.content);
|
||
break;
|
||
case 'complete':
|
||
finishResponse();
|
||
break;
|
||
case 'error':
|
||
showError(data.content);
|
||
break;
|
||
}
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 十三、部署
|
||
|
||
### 13.1 目录结构
|
||
|
||
```
|
||
/opt/micro_servers/aibox/
|
||
├── main.py
|
||
├── client.py
|
||
├── skills/
|
||
├── _run.sh # core 拉起入口
|
||
├── _set.sh # 首次安装
|
||
└── requirements.txt
|
||
```
|
||
|
||
### 13.2 core init.txt 配置
|
||
|
||
```bash
|
||
# aibox 由 core 拉起
|
||
bash /opt/micro_servers/aibox/_run.sh
|
||
```
|
||
|
||
### 13.3 systemd 单元（可选）
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=AIBOX AI Agent
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=deploy
|
||
WorkingDirectory=/opt/micro_servers/aibox
|
||
ExecStart=/usr/bin/python3 main.py
|
||
Restart=always
|
||
RestartSec=5
|
||
Environment=DEEPSEEK_API_KEY=xxx
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
---
|
||
|
||
## 十四、已知限制
|
||
|
||
| ID | 描述 | 严重等级 |
|
||
|----|------|---------|
|
||
| L1 | 单实例运行，不支持多进程 | 🟡 Medium |
|
||
| L2 | 记忆库无向量搜索，仅关键词匹配 | 🟡 Medium |
|
||
| L3 | 对话压缩可能丢失早期重要信息 | 🟢 Low |
|
||
| L4 | 工具执行无超时控制（部分工具） | 🟡 Medium |
|
||
| L5 | 日志无远程推送，仅本地文件 | 🟢 Low |
|
||
| L6 | 无用户认证，WebSocket 连接可被滥用 | 🔴 High |
|
||
| L7 | API Key 以明文存储在环境变量或文件中 | 🟡 Medium |
|
||
|
||
### L6 详细说明
|
||
|
||
WebSocket 服务器**无任何认证**，任何能连接到 `ws://localhost:8765` 的客户端都可以：
|
||
- 与 AI 对话（消耗 API 额度）
|
||
- 执行系统命令（`run_command`）
|
||
- 操作文件系统（`read_file`/`write_file`）
|
||
- 创建/删除任务
|
||
|
||
**建议**：
|
||
1. 仅绑定 `localhost`（默认配置已这样做）
|
||
2. 添加 API Token 认证
|
||
3. 限制 `run_command` 可执行的命令范围
|
||
|
||
---
|
||
|
||
## 十五、开发指南
|
||
|
||
### 15.1 添加新工具
|
||
|
||
1. 继承 `Tool` 基类
|
||
2. 实现 `get_name()`、`get_description()`、`get_parameters()`、`execute()`
|
||
3. 在 `DeepSeekChat._register_tools()` 中注册
|
||
4. 更新 README 文档
|
||
|
||
```python
|
||
class MyTool(Tool):
|
||
def get_name(self) -> str:
|
||
return "my_tool"
|
||
|
||
def get_description(self) -> str:
|
||
return "我的自定义工具"
|
||
|
||
def get_parameters(self) -> Dict:
|
||
return {
|
||
"type": "object",
|
||
"properties": {
|
||
"param": {"type": "string", "description": "参数说明"}
|
||
},
|
||
"required": ["param"]
|
||
}
|
||
|
||
def execute(self, param: str, **kwargs) -> str:
|
||
return f"执行结果: {param}"
|
||
```
|
||
|
||
### 15.2 添加新命令
|
||
|
||
在 `WebSocketHandler.handle_command()` 中添加：
|
||
|
||
```python
|
||
elif command == "/mycommand":
|
||
result = "命令执行结果"
|
||
await self.send_message(websocket, {
|
||
"type": "command_result",
|
||
"content": result
|
||
})
|
||
```
|
||
|
||
### 15.3 添加配置项
|
||
|
||
1. 在 `ConfigManager._get_default_config()` 中添加默认值
|
||
2. 在 README 文档中添加说明
|
||
3. 确保 `_merge_configs()` 能正确处理新增字段
|
||
|
||
---
|
||
|
||
## 十六、故障排查
|
||
|
||
### 16.1 常见问题
|
||
|
||
| 问题 | 排查步骤 |
|
||
|------|---------|
|
||
| API Key 无效 | 检查 `echo $DEEPSEEK_API_KEY` 或 `~/.cert/deepseek.key` |
|
||
| 技能不生效 | 确认技能文件在 `~/.aibox/skills/` 且有执行权限 |
|
||
| 任务不执行 | 检查调度器状态：`/tasks`；检查时间设置 |
|
||
| 对话压缩丢失信息 | 调整 `compress_message_threshold` 和 `compress_keep_recent` |
|
||
| WebSocket 断开 | 检查服务器进程：`ps aux | grep main.py`；查看日志 |
|
||
|
||
### 16.2 日志位置
|
||
|
||
```bash
|
||
# 查看实时日志
|
||
tail -f ~/.aibox/ai.log
|
||
|
||
# 查看最近错误
|
||
grep "ERROR" ~/.aibox/ai.log | tail -20
|
||
```
|
||
|
||
### 16.3 数据库检查
|
||
|
||
```bash
|
||
# 检查记忆库
|
||
sqlite3 ~/.aibox/memories.db "SELECT * FROM memories LIMIT 10;"
|
||
|
||
# 检查任务库
|
||
sqlite3 ~/.aibox/memos.db "SELECT * FROM memos WHERE status='pending';"
|
||
```
|
||
|
||
---
|
||
|
||
## 十七、版本历史
|
||
|
||
| 版本 | 日期 | 主要变更 |
|
||
|------|------|---------|
|
||
| v2.0 | 当前 | 新增 `ask_user`、`update_soul`、`create_skill`、`install_skill`、`set_proxy`/`get_proxy` 等工具；支持 Markdown 技能；对话压缩支持 Token 阈值 |
|
||
| v1.0 | — | 初始版本：WebSocket 服务器、文件/网页/记忆操作、任务调度、扩展技能、多语言 |
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 配置文件示例
|
||
|
||
完整默认配置见 [main.py:1100-1180](file:///Users/qingsong/micro_servers/aibox/main.py#L1100-L1180)
|
||
|
||
### B. 数据库 Schema
|
||
|
||
完整建表语句见：
|
||
- 记忆库：[main.py](file:///Users/qingsong/micro_servers/aibox/main.py) 中 `MemoryManager._init_db()`
|
||
- 任务库：[main.py](file:///Users/qingsong/micro_servers/aibox/main.py) 中 `MemoScheduler._init_db()`
|
||
|
||
### C. 参考文档
|
||
|
||
- [DeepSeek API 文档](https://platform.deepseek.com/docs)
|
||
- [websockets 库文档](https://websockets.readthedocs.io/)
|
||
- [SKILLS_FORMAT.md](file:///Users/qingsong/micro_servers/aibox/SKILLS_FORMAT.md)
|
||
|
||
---
|
||
|
||
*本文档由代码审查工具生成，供开发团队参考。*
|