blackbird/docs/aibox_file_network_cli_refactor.md

aibox 文件操作与网络操作命令行化 开发计划

目标

将 aibox 中所有 Python 原生实现的文件操作和网络操作改为通过系统命令行工具实现，统一工具执行模式，减少 Python 依赖。

涉及模块

现有类	作用	替换方案
FileToolBase	文件工具基类	简化为命令行工具基类
ReadFileTool	读文件	cat / head / tail / wc
WriteFileTool	写文件	mkdir -p + shell 重定向
ListFilesTool	列目录	ls / find / du
SimpleWebClient	HTTP 客户端	curl
WebPage	网页解析对象	移除，curl + grep/sed 替代
SimpleWebCrawlerTool	网页爬虫工具	curl + 文本处理管道

阶段一：文件操作命令行化

实现说明（已落地）：阶段一采用「工具返回 markdown 提示词」的方式而非工具内部调子进程。read_file / write_file / list_files 三个工具的 execute() 不再执行 Python 文件 I/O，而是返回一段 markdown 提示词，指导智能体改用 run_command 工具执行对应的命令行命令（head/tail/sed/wc/file/cut/cat/ls/du/find）。工具接口（名称与参数）保持不变，安全限制（500 行、10KB/行、10MB 文件、路径 shlex.quote 转义）在提示词中注明。

1.1 ReadFileTool 重构

用以下命令行工具替代 Python 文件 I/O：

原功能	命令行实现
head=True 读取开头 N 行	head -n N
tail=True 读取末尾 N 行	tail -n N
指定行范围 start_line ~ end_line	sed -n 'start,endp'
统计行数 _count_lines	wc -l
文件编码检测	file -b --mime-encoding
单行超长截断	cut -c 1-10000

保留的安全限制：

• 文件大小限制 MAX_FILE_SIZE：通过 wc -c 或 stat -f%z 检查
• 行数上限 500 行：head -n 500 作为最后一道防线
• 单行 10KB 限制：cut -c 1-10000

1.2 WriteFileTool 重构

原功能	命令行实现
创建目录	mkdir -p
覆盖写入 mode=w	content > filepath
追加写入 mode=a	content >> filepath
检查文件大小	wc -c 或 stat -f%z
路径安全检查	realpath / test -f

1.3 ListFilesTool 重构

原功能	命令行实现
列出目录内容	ls -la 或 find . -maxdepth 1
隐藏文件过滤	ls -la 默认不显示 . 开头的隐藏文件（或 find 排除）
文件大小统计	du -sh * 或 ls -lh
目录/文件区分	ls -F 或 find -type f/d

1.4 FileToolBase 简化

移除 normalize_path()、check_path_safety() 中 Python os 模块调用，改为：

• 路径规范化：realpath
• 文件存在性检查：test -f / test -d
• 文件大小检查：wc -c 或 stat

1.5 安全边界保留

• MAX_FILE_SIZE（默认 10MB）：通过命令检查
• 行数上限 500 行：head -n 500 兜底
• 单行长度上限 10KB：cut -c 1-10000 兜底
• 所有路径参数 shlex.quote() 转义

阶段二：网络操作命令行化

实现说明（已落地）：阶段二沿用阶段一的方式，web 工具（SimpleWebCrawlerTool）的 execute() 不再使用 requests/BeautifulSoup，而是返回 markdown 提示词，指导智能体改用 run_command 执行 curl 命令完成各 action（get/text/title/links/search）。WebPage、SimpleWebClient 类已删除；urljoin/urlparse/BeautifulSoup 导入已清理。代理通过 get_proxy() 读取配置并拼出 --socks5 参数。注意 requests 仍在 aibox.py 其他位置（API 调用、DeepSeek 请求）使用，故保留其依赖。

2.1 SimpleWebClient → curl

原功能	命令行实现
HTTP GET 请求	curl -sL --max-time N
自定义 User-Agent	curl -A "..."
SOCKS5 代理	curl --socks5 host:port 或环境变量 ALL_PROXY
请求间隔控制	SubprocessCommandExecutor 层面控制
响应状态码	curl -sL -o /dev/null -w '%{http_code}'
下载大小限制	curl --max-filesize N 或管道 head -c N

2.2 WebPage 移除

WebPage 类不再需要，其功能由命令行管道实现：

原属性/方法	命令行实现
title	`curl -sL
text	`curl -sL
links	`curl -sL
status_code	curl -sL -o /dev/null -w '%{http_code}'
headers	curl -sL -I

2.3 SimpleWebCrawlerTool 重构

action	命令行实现
get	curl -sL 获取完整页面信息
text	`curl -sL
title	`curl -sL
links	`curl -sL
search	`curl -sL

2.4 下载大小限制

• 响应体：curl --max-filesize 或 curl | head -c 100M 管道限制
• 配置项 web.max_download_size（默认 100MB）

阶段三：清理与收尾

实现说明（已落地）：

• 3.1 requirements.txt 已移除 beautifulsoup4；requests 保留（仍在 aibox.py 的 DeepSeek API 调用 ConversationCompressor 与 DeepSeekChat 中使用，属核心功能，无法移除）。
• 3.2 已统一：文件/网页工具改为返回 markdown 提示词，实际 I/O 全部委托给 run_command（SubprocessCommandExecutor），天然复用其 1MB 输出上限、超时与中断取消。
• 3.3 中断支持已随 SubprocessCommandExecutor.cancel() 覆盖。
• 3.4 默认提示词 3_file_operations.md、4_web_access.md 已更新为命令行走指导（head/sed/cat/ls/curl 等）。
• 3.5 README.md 工具表与安全说明已更新。

3.1 移除 Python 依赖

从 requirements.txt 删除：

- requests
- beautifulsoup4

3.2 统一使用 SubprocessCommandExecutor

所有新工具统一通过 SubprocessCommandExecutor 执行命令，与 CommandLineTool 保持一致：

• 输出上限 1MB（超出自动终止进程并截断）
• 超时控制
• 中断取消（cancel() → process.kill()）

3.3 中断支持

• 利用已有的 SubprocessCommandExecutor.cancel() 机制
• 确保 Ctrl+C 可终止长时间运行的 curl 下载或文件操作

3.4 更新提示词

~/.aibox/prompts/ 中相关文件更新：

文件	更新内容
3_file_operations.md	文件操作描述改为命令行方式
4_web_access.md	网络访问描述改为 curl 方式

3.5 更新文档

• SKILLS_FORMAT.md：技能开发示例中文件/网络操作更新
• README.md：更新依赖说明和架构图

不做的事

• 不改变工具接口：read_file、write_file、list_files、web 四个工具名称和参数签名保持不变
• 不改变 CommandLineTool（run_command）：已有的命令执行工具不动
• 不改变 SubprocessCommandExecutor：已有安全限制（1MB 输出）保持不变
• 不改变记忆/备忘录数据库：MemoryDatabase、MemoDatabase 的 SQLite 操作保留

收益

• 减少依赖：移除 requests、beautifulsoup4 两个 Python 库，降低供应链风险
• 统一执行模式：所有外部操作（文件、网络、命令）全部走 SubprocessCommandExecutor，统一超时控制、输出限制、中断取消
• 更强的可审计性：AI 操作日志中能看到完整的 curl / cat / ls 命令，更透明
• 复用已有基础设施：CommandLineTool 已有的安全防护直接复用

风险与注意事项

风险	缓解措施
curl 不存在	启动时检测 curl 可用性，缺失时尝试 wget 降级或报错
跨平台 sed/grep 差异	macOS (BSD) 和 Linux (GNU) 行为差异；使用 POSIX 兼容写法，必要时运行时检测
网页解析精度下降	grep 正则提取 HTML 不可靠；优先用 lynx -dump 或 html2text 替代 BeautifulSoup 解析
命令注入风险	所有用户输入参数必须经过 shlex.quote() 转义
Proxy 配置	curl 通过 --socks5 或 ALL_PROXY 环境变量传递，与现有 set_proxy 工具集成
性能影响	文件操作每步 fork 新进程，但 aibox 不是高吞吐服务，IO 瓶颈远大于进程开销