docs(aibox): 同步v3.0模块化文档，修复测试路径漂移

- README.md: 更新行数(8450->3706)、重写目录结构(含tools/subsystems/tests包)、补充包依赖方向与测试运行说明、新增v3.0更新日志 - test_basic_tools.py: 4个ReadFileTool测试改用tmp_path fixture，消除cwd依赖 - 新增 docs/reports/aibox_refactor_progress_20260814.md: 重构进度报告
2026-08-13 16:26:41 +08:00
1 parent 791fac0efd
commit d47ef6efb4
@@ -55,21 +55,47 @@ python aibox.py

 启动后，WebSocket 服务器将运行在 `ws://localhost:8765`（地址与端口可在 `config.json` 的 `system.websocket_host` / `system.websocket_port` 中修改）。

-> 注意：本模块入口文件为 `aibox.py`（单文件约 8450 行，集成 WebSocket 服务器、AI 引擎、工具/技能系统、任务调度器于一体）。`client.py` 为示例 WebSocket 客户端，`voice_client.py` 为语音客户端，`_run.sh` 为被 `core` 拉起的启动脚本。
+> 注意：本模块入口文件为 `aibox.py`（当前约 3706 行，集成 WebSocket 服务器、AI 引擎、工具/技能系统、任务调度器于一体；自 v3.0 起工具类与子系统已抽离至 `tools/`、`subsystems/`、`common/`、`tests/` 包，aibox.py 仅保留核心类与编排逻辑）。`client.py` 为示例 WebSocket 客户端，`voice_client.py` 为语音客户端，`llm_client.py` 为多厂商大模型客户端抽象层，`_run.sh` 为被 `core` 拉起的启动脚本。

 ## 📁 目录结构

 ```
 aibox/
-├── aibox.py           # 服务主程序（WebSocket 服务器 + AI 引擎 + 工具/技能系统 + 任务调度器）
+├── aibox.py           # 服务主程序（WebSocket 服务器 + AI 引擎 + 任务调度器 + 核心类 DeepSeekChat/WebSocketHandler/EnhancedAIManager）
 ├── client.py          # 示例 WebSocket 客户端
 ├── voice_client.py    # 语音客户端
+├── llm_client.py      # 大模型客户端抽象层（多厂商切换，DeepSeekClient 兼容 OpenAI 协议）
 ├── entry.html         # 前端入口页
 ├── entry1.html        # 前端入口页（变体）
 ├── frontend.html      # 前端主页面
-├── llm_client.py      # 大模型客户端抽象层（多厂商切换）
 ├── common/            # 基础设施包（i18n / 配置 / 常量 / 日志）
-├── tools/             # 工具系统基础包（Tool 基类 + ToolRegistry 注册器）
+│   ├── config.py      # ConfigManager 配置管理
+│   ├── constants.py   # 常量定义
+│   ├── i18n.py       # 多语言
+│   └── logger.py     # 日志器
+├── subsystems/        # 子系统包（Wave 1：从 aibox.py 抽离的基础设施）
+│   ├── executors.py        # CommandExecutor + SubprocessCommandExecutor
+│   ├── prompt_manager.py   # PromptManager（单例，提示词按数字前缀排序加载）
+│   ├── db.py               # MemoryDatabase + MemoDatabase（SQLite）
+│   └── skill_manager.py    # SkillManager（技能发现/加载/热重载）
+├── tools/             # 工具系统包（A 批 + B 批共 17 个工具类）
+│   ├── base.py             # Tool 抽象基类
+│   ├── registry.py         # ToolRegistry 工具注册器
+│   ├── basic_tools.py      # A 批：ReadFile/WriteFile/ListFiles/SimpleWebCrawler/GetCurrentTime/Calculator
+│   ├── command_tool.py     # B 批：CommandLineTool（run_command）
+│   ├── skill_tools.py      # B 批：SearchSkills/ReloadSkills/InstallSkill/CreateSkill
+│   ├── db_tools.py         # B 批：MemoryTool/MemoTool
+│   ├── prompt_tools.py     # B 批：UpdateIdentity/UpdateSoul/SaveMemoryAndEndConversation
+│   ├── proxy_tools.py      # B 批：SetProxy/GetProxy
+│   └── misc_tools.py       # B 批：AskUserTool
+├── tests/             # 单元测试套件（171 项全过）
+│   ├── conftest.py              # sys.path 配置 + websockets 桩
+│   ├── test_basic_tools.py      # A 批工具 43 项
+│   ├── test_b_tools.py          # B 批工具 58 项
+│   ├── test_executors.py        # 命令执行器
+│   ├── test_prompt_manager.py   # 提示词管理器
+│   ├── test_db.py               # 记忆/备忘录数据库
+│   └── test_skill_manager.py    # 技能管理器
 ├── skills/            # 内置扩展技能（*.py 可执行脚本 / *.md Markdown 技能）
 │   ├── hello-world.py
 │   ├── aes-crypto.py
@@ -79,6 +105,7 @@ aibox/
 │   ├── ssh-exec.py
 │   ├── sftp-transfer.py
 │   └── ...
+├── prompts/           # 系统提示词源文件（运行期复制到 ~/.aibox/prompts/）
 ├── SKILLS_FORMAT.md   # 技能文件格式说明
 ├── _run.sh            # 启动脚本（被 core 守护时调用）
 ├── _runcli.sh         # 命令行启动脚本
@@ -87,6 +114,25 @@ aibox/
 └── README.md
 ```

+**包依赖方向**（单向，禁止反向引用）：
+
+```
+common  ←  subsystems  ←  tools  ←  aibox.py
+```
+
+- `common`：仅依赖标准库，不引用任何其他包
+- `subsystems`：依赖 `common`，不引用 `tools` 或 `aibox`
+- `tools`：依赖 `common` + `subsystems`，不引用 `aibox`
+- `aibox.py`：聚合层，导入上述三个包
+
+**运行测试**：
+
+```bash
+# 从仓库根目录运行
+py -m pytest aibox/tests -q
+# 当前：171 项全过，约 11s
+```
+
 运行期数据存放于 `~/.aibox/`：

 ```
@@ -632,10 +678,19 @@ Server -> Client: {type: "dialogue_reset", content: "✅ 对话状态已完全

 ### 添加新工具

-1. 继承 `Tool` 基类（位于 `tools/base.py`）
+1. 继承 `Tool` 基类（位于 [tools/base.py](tools/base.py)）
 2. 实现 `get_name()`、`get_description()`、`get_parameters()`、`execute()`
 3. 可选实现 `execute_streaming()` 支持流式输出（通过 `output_queue` 发送 `("line", content)` 和 `("complete", final_result)`）
-4. 在 `DeepSeekChat._register_tools()` 中注册
+4. 按工具类别放入对应文件：
+   - 基础工具（文件/网页/计算/时间）→ `tools/basic_tools.py`
+   - 命令执行 → `tools/command_tool.py`
+   - 技能管理 → `tools/skill_tools.py`
+   - 数据库工具 → `tools/db_tools.py`
+   - 提示词/身份更新 → `tools/prompt_tools.py`
+   - 代理配置 → `tools/proxy_tools.py`
+   - 其他 → `tools/misc_tools.py`
+5. 在 [tools/__init__.py](tools/__init__.py) 的 `__all__` 中导出新类
+6. 在 `DeepSeekChat._register_tools()` 中按 `tool_profile`（orchestrator/worker）注册

 ```python
 class MyTool(Tool):
@@ -656,6 +711,8 @@ class MyTool(Tool):
        return f"执行结果: {param}"
 ```

+> **依赖约束**：`tools/` 包只能依赖 `common` + `subsystems` + 标准库，不得反向引用 `aibox.py` 任何符号；如需访问 aibox 内部状态，应通过构造函数注入（参考 `MemoryTool(memory_db=...)` 模式）。
+
 > **注意**：`execute()` 必须返回字符串。工具结果会经过多层安全防护：
 > 1. **工具层源头限制**：文件/网页工具返回 markdown 指引，实际 I/O 由 `run_command` 完成（`run_command` 输出≤1MB，超出立即终止进程；`read_file` 指引命令限制 500 行、单行≤10KB）
 > 2. **`_sanitize_tool_result()`**：None/非字符串转为安全字符串，过滤控制字符
@@ -734,6 +791,16 @@ elif command == "/mycommand":

 ## 📄 更新日志

+### v3.0
+- ✅ **模块化重构（aibox.py 8450 行 → 3706 行，缩减 56%）**：
+  - **A 批基础工具抽离**（[tools/basic_tools.py](tools/basic_tools.py)）：`FileToolBase` / `ReadFileTool` / `WriteFileTool` / `ListFilesTool` / `SimpleWebCrawlerTool` / `GetCurrentTimeTool` / `CalculatorTool` 共 7 类，无外部子系统依赖；配套 43 项单元测试
+  - **B 批管理面工具抽离**（[tools/](tools/) 目录）：`CommandLineTool` / `SearchSkillsTool` / `ReloadSkillsTool` / `InstallSkillTool` / `CreateSkillTool` / `MemoryTool` / `MemoTool` / `UpdateIdentityTool` / `UpdateSoulTool` / `SaveMemoryAndEndConversationTool` / `SetProxyTool` / `GetProxyTool` / `AskUserTool` 共 13 类，按职责分 7 个文件；配套 58 项单元测试
+  - **Wave 1 子系统抽离**（[subsystems/](subsystems/) 目录）：`CommandExecutor` + `SubprocessCommandExecutor`（executors.py）、`PromptManager`（prompt_manager.py）、`MemoryDatabase` + `MemoDatabase`（db.py）、`SkillManager`（skill_manager.py）共 4 子系统；配套 70 项单元测试
+  - **测试套件**：[tests/](tests/) 目录 171 项全过，覆盖 A/B 批工具与 Wave 1 子系统
+  - **修复**：`subsystems/db.py` 的 `get_recent_memories(limit=None)` SQL datatype mismatch bug（`LIMIT ?` 传 None 时移除 LIMIT 子句）
+  - **架构约束**：建立 `common ← subsystems ← tools ← aibox` 单向依赖，禁止反向引用；`tools/__init__.py` 与 `subsystems/__init__.py` 采用"重导出"策略，调用点无需关心子模块位置
+  - **未抽离**：Wave 2（`TaskScheduler` / `ConversationHistory`）、Wave 3（`ConversationCompressor`）、C 批工具（`ExpressEmotionTool` / `SubAgentTool`）、核心类（`DeepSeekChat` / `WebSocketHandler` / `EnhancedAIManager`）仍保留在 `aibox.py` 内
+
 ### v2.9
 - ✅ **编排者-执行者工具分层（工具集 profile）**：
  - `DeepSeekChat` 新增 `tool_profile` 参数（`orchestrator` / `worker`），`_register_tools()` 按 profile 分组装配工具集
@@ -138,29 +138,41 @@ def test_calculator_unknown_operation():


 # ==================== ReadFileTool ====================
+#
+# 说明：使用 pytest 的 tmp_path fixture 创建临时文件作为 read_file 入参，
+# 不依赖任何相对路径或 cwd——早期版本用 filepath="aibox.py" 假设从
+# aibox/ 目录运行 pytest，从仓库根运行会因路径漂移失败（2026-08-14 修复）。

-def test_read_file_head_returns_command_prompt():
+def test_read_file_head_returns_command_prompt(tmp_path):
    """head 模式应返回含 head 命令 + run_command 指引的 markdown。"""
-    r = ReadFileTool().execute(filepath="aibox.py", head=True, max_lines=10)
+    f = tmp_path / "sample.txt"
+    f.write_text("line1\nline2\n")
+    r = ReadFileTool().execute(filepath=str(f), head=True, max_lines=10)
    assert "head -n 10" in r
    assert "run_command" in r


-def test_read_file_tail_returns_command_prompt():
-    r = ReadFileTool().execute(filepath="aibox.py", tail=True, max_lines=20)
+def test_read_file_tail_returns_command_prompt(tmp_path):
+    f = tmp_path / "sample.txt"
+    f.write_text("line1\nline2\n")
+    r = ReadFileTool().execute(filepath=str(f), tail=True, max_lines=20)
    assert "tail -n 20" in r
    assert "run_command" in r


-def test_read_file_range_returns_sed_command():
-    r = ReadFileTool().execute(filepath="aibox.py", start_line=5, end_line=15)
+def test_read_file_range_returns_sed_command(tmp_path):
+    f = tmp_path / "sample.txt"
+    f.write_text("line1\nline2\n")
+    r = ReadFileTool().execute(filepath=str(f), start_line=5, end_line=15)
    assert "sed -n '5,15p'" in r
    assert "run_command" in r


-def test_read_file_max_lines_cap_at_500():
+def test_read_file_max_lines_cap_at_500(tmp_path):
    """max_lines 应被钳制到 500 防止超大范围。"""
-    r = ReadFileTool().execute(filepath="aibox.py", max_lines=99999)
+    f = tmp_path / "sample.txt"
+    f.write_text("line1\n")
+    r = ReadFileTool().execute(filepath=str(f), max_lines=99999)
    assert "sed -n '1,500p'" in r


@@ -0,0 +1,167 @@
+# aibox 模块化重构进度报告
+
+> 状态：A/B 批工具 + Wave 1 子系统已抽离 · 日期：2026-08-14 · 基线：aibox v3.0
+> 测试：171 项全过（10.79s）
+> 关联文档：
+> - [aibox_orchestrator_worker_plan.md](aibox_orchestrator_worker_plan.md)（v2.9 编排者-执行者分层方案）
+> - [aibox_open_dev_plan.md](aibox_open_dev_plan.md)（开放版安全裁剪方案）
+> - [aibox_SECURITY_AUDIT_20260801.md](../security/aibox_SECURITY_AUDIT_20260801.md)（安全审计基线）
+
+## 1. 重构目标
+
+将单文件 8450 行的 `aibox.py` 按职责拆分为多个内聚包，建立清晰的依赖方向与测试基线，降低维护成本、为后续工具/子系统扩展提供稳定骨架。
+
+**目标架构**（单向依赖，禁止反向引用）：
+
+```
+common  ←  subsystems  ←  tools  ←  aibox.py
+```
+
+| 层 | 职责 | 依赖 |
+|---|---|---|
+| `common/` | 配置、常量、i18n、日志 | 标准库 |
+| `subsystems/` | 命令执行器、提示词、数据库、技能管理 | `common` |
+| `tools/` | Tool 基类 + 17 个工具类 | `common` + `subsystems` |
+| `aibox.py` | 核心类聚合（DeepSeekChat/WebSocketHandler/EnhancedAIManager + 调度/压缩/历史） | 上述三包 |
+
+## 2. 已完成工作
+
+### 2.1 A 批基础工具抽离（`tools/basic_tools.py`，342 行）
+
+7 个无外部子系统依赖的工具类：
+
+| 类 | 工具名 | 说明 |
+|---|---|---|
+| `FileToolBase` | — | 文件操作基类（normalize_path / check_path_safety） |
+| `ReadFileTool` | `read_file` | 读文件指引（head/tail/sed） |
+| `WriteFileTool` | `write_file` | 写文件指引（heredoc） |
+| `ListFilesTool` | `list_files` | 列目录指引（ls） |
+| `SimpleWebCrawlerTool` | `web` | 网页访问指引（curl + 代理） |
+| `GetCurrentTimeTool` | `get_current_time` | 时间获取 |
+| `CalculatorTool` | `calculator` | 四则运算 |
+
+**测试**：[tests/test_basic_tools.py](../../aibox/tests/test_basic_tools.py) 43 项全过
+
+### 2.2 B 批管理面工具抽离（`tools/` 目录，共 13 类）
+
+| 文件 | 类 | 工具名 |
+|---|---|---|
+| `command_tool.py` | `CommandLineTool` | `run_command` |
+| `skill_tools.py` | `SearchSkillsTool` / `ReloadSkillsTool` / `InstallSkillTool` / `CreateSkillTool` | `search_skills` / `reload_skills` / `install_skill` / `create_skill` |
+| `db_tools.py` | `MemoryTool` / `MemoTool` | `memory` / `memo` |
+| `prompt_tools.py` | `UpdateIdentityTool` / `UpdateSoulTool` / `SaveMemoryAndEndConversationTool` | `update_identity` / `update_soul` / `save_memory_and_end_conversation` |
+| `proxy_tools.py` | `SetProxyTool` / `GetProxyTool` | `set_proxy` / `get_proxy` |
+| `misc_tools.py` | `AskUserTool` | `ask_user` |
+
+**测试**：[tests/test_b_tools.py](../../aibox/tests/test_b_tools.py) 58 项全过
+
+### 2.3 Wave 1 子系统抽离（`subsystems/` 目录）
+
+| 文件 | 类 | 行数 |
+|---|---|---|
+| `executors.py` | `CommandExecutor` + `SubprocessCommandExecutor` | 279 |
+| `prompt_manager.py` | `PromptManager`（单例，数字前缀排序加载） | 241 |
+| `db.py` | `MemoryDatabase` + `MemoDatabase`（SQLite） | 530 |
+| `skill_manager.py` | `SkillManager` | 186 |
+
+**测试**：
+- [tests/test_executors.py](../../aibox/tests/test_executors.py)
+- [tests/test_prompt_manager.py](../../aibox/tests/test_prompt_manager.py)
+- [tests/test_db.py](../../aibox/tests/test_db.py)
+- [tests/test_skill_manager.py](../../aibox/tests/test_skill_manager.py)
+
+共 70 项全过。
+
+### 2.4 工具系统基础设施
+
+- [tools/base.py](../../aibox/tools/base.py)（115 行）：`Tool` 抽象基类，定义 `get_name` / `get_description` / `get_parameters` / `execute` / `execute_streaming` / `validate_params` / `format_result` 接口
+- [tools/registry.py](../../aibox/tools/registry.py)（135 行）：`ToolRegistry` 注册器，支持热重载与流式输出分发
+- [tools/__init__.py](../../aibox/tools/__init__.py) / [subsystems/__init__.py](../../aibox/subsystems/__init__.py)：采用"重导出"策略，外部统一用 `from tools import Tool, ReadFileTool`，调用点无需关心子模块位置
+
+### 2.5 关键 Bug 修复
+
+- **`subsystems/db.py` 的 `get_recent_memories(limit=None)` SQL datatype mismatch**：`LIMIT ?` 传 `None` 时 SQLite 报错；修复为 `limit` 为 `None` 时移除 `LIMIT` 子句
+- **`test_basic_tools.py` 路径漂移**（2026-08-14 修复）：4 个测试用 `filepath="aibox.py"` 假设 pytest 从 `aibox/` 目录运行；改用 pytest `tmp_path` fixture 创建临时文件，测试不再依赖 cwd
+
+## 3. 量化指标
+
+| 指标 | 起点（v2.8） | 当前（v3.0） | 变化 |
+|---|---|---|---|
+| `aibox.py` 行数 | 8450 | 3706 | -56% |
+| 抽离工具类数 | 0 | 17 | +17 |
+| 抽离子系统数 | 0 | 4 | +4 |
+| 测试用例数 | 0 | 171 | +171 |
+| 测试运行时长 | — | 10.79s | — |
+
+## 4. 测试套件现状
+
+```
+aibox/tests/ (171 项，10.79s)
+├── test_basic_tools.py      43 项  A 批工具（文件/网页/时间/计算器）
+├── test_b_tools.py          58 项  B 批工具（13 个管理面工具）
+├── test_executors.py        —     命令执行器
+├── test_prompt_manager.py   —     提示词管理器
+├── test_db.py               —     记忆/备忘录数据库
+└── test_skill_manager.py    —     技能管理器
+```
+
+运行命令：
+
+```bash
+# 从仓库根目录
+py -m pytest aibox/tests -q
+```
+
+## 5. 剩余工作（未抽离）
+
+### 5.1 aibox.py 剩余类清单（3706 行）
+
+| 类 | 起始行 | 批次 | 说明 |
+|---|---|---|---|
+| `ConversationCompressor` | L70 | Wave 3 | 对话压缩器，依赖 `llm_client` |
+| `TaskScheduler` | L570 | Wave 2 | 任务调度器，依赖 `MemoDatabase` |
+| `ConversationHistory` | L986 | Wave 2 | 对话历史管理 |
+| `ExpressEmotionTool` | L1309 | C 批 | 情绪表达工具，依赖 `run_light_subagent` |
+| `SubAgentTool` | L1574 | C 批 | 子代理派生工具，依赖 `run_full_subagent` |
+| `DeepSeekChat` | L1700 | 核心类 | 保留入口（编排逻辑） |
+| `WebSocketHandler` | L2715 | 核心类 | 保留入口 |
+| `EnhancedAIManager` | L3377 | 核心类 | 保留入口 |
+
+### 5.2 建议优先级
+
+| 优先级 | 批次 | 内容 | 风险 |
+|---|---|---|---|
+| 高 | Wave 2 | `TaskScheduler` + `ConversationHistory` 抽离至 `subsystems/` | 低（依赖已抽离的 `MemoDatabase`） |
+| 中 | Wave 3 | `ConversationCompressor` 抽离至 `subsystems/` | 中（需评估与 `DeepSeekChat` 的循环依赖，参考 lessons learned） |
+| 中 | C 批 | `ExpressEmotionTool` + `SubAgentTool` 抽离至 `tools/` | 中（依赖 `DeepSeekChat` 的 `run_light_subagent` / `run_full_subagent`，需通过依赖注入或协议接口打破循环） |
+| 低 | 核心类 | `DeepSeekChat` / `WebSocketHandler` / `EnhancedAIManager` | 保留在 `aibox.py`，作为聚合入口 |
+
+### 5.3 风险点
+
+1. **`ConversationCompressor` 与 `DeepSeekChat` 的循环依赖**：压缩器需调用 LLM，而 `DeepSeekChat` 持有压缩器；需通过依赖注入或协议接口打破（参考 project_memory 中 lessons learned）
+2. **C 批工具依赖 `DeepSeekChat` 内部方法**：`run_light_subagent` / `run_full_subagent` 是 `DeepSeekChat` 的方法，抽离工具时需先抽离这些方法或改为函数式调用
+3. **测试覆盖盲区**：C 批工具（`ExpressEmotionTool` / `SubAgentTool`）和 Wave 2/3 子系统尚无单元测试，抽离时应同步补测
+
+## 6. 文档同步状态
+
+| 文档 | 状态 | 备注 |
+|---|---|---|
+| [aibox/README.md](../../aibox/README.md) | ✅ 已同步 v3.0 | 行数、目录结构、开发指南、v3.0 更新日志已更新 |
+| 本报告 | ✅ 新建 | 归档已完成工作与剩余规划 |
+| [aibox_orchestrator_worker_plan.md](aibox_orchestrator_worker_plan.md) | 历史 | v2.9 分层方案（已实施） |
+| [aibox_open_dev_plan.md](aibox_open_dev_plan.md) | 待评估 | 开放版裁剪方案，与本次模块化正交 |
+| [aibox_file_network_cli_refactor.md](aibox_file_network_cli_refactor.md) | 待评估 | 文件/网络/CLI 重构计划 |
+
+## 7. 验证记录
+
+```
+$ py -m pytest aibox/tests -q
+........................................................................ [ 42%]
+........................................................................ [ 84%]
+...........................                                              [100%]
+171 passed in 10.79s
+```
+
+- 测试基线：2026-08-14
+- 运行环境：Windows + PowerShell 5
+- Python：通过 `py` 启动器调用（`python` 不在 PATH）