blackbird/docs/reports/aibox_refactor_progress_20260814.md

aibox 模块化重构进度报告

状态：A/B 批工具 + Wave 1 子系统已抽离 · 日期：2026-08-14 · 基线：aibox v3.0 测试：171 项全过（10.79s） 关联文档：

• aibox_orchestrator_worker_plan.md（v2.9 编排者-执行者分层方案）
• aibox_open_dev_plan.md（开放版安全裁剪方案）
• 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 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 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
• tests/test_prompt_manager.py
• tests/test_db.py
• tests/test_skill_manager.py

共 70 项全过。

2.4 工具系统基础设施

• tools/base.py（115 行）：Tool 抽象基类，定义 get_name / get_description / get_parameters / execute / execute_streaming / validate_params / format_result 接口
• tools/registry.py（135 行）：ToolRegistry 注册器，支持热重载与流式输出分发
• tools/__init__.py / 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    —     技能管理器

运行命令：

# 从仓库根目录
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	✅ 已同步 v3.0	行数、目录结构、开发指南、v3.0 更新日志已更新
本报告	✅ 新建	归档已完成工作与剩余规划
aibox_orchestrator_worker_plan.md	历史	v2.9 分层方案（已实施）
aibox_open_dev_plan.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）