# 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 | grep -oP '<title>\K[^<]+'` |
| `text` | `curl -sL | lynx -dump -stdin` 或 `html2text` |
| `links` | `curl -sL | grep -oP 'href="[^"]*"'` |
| `status_code` | `curl -sL -o /dev/null -w '%{http_code}'` |
| `headers` | `curl -sL -I` |

### 2.3 SimpleWebCrawlerTool 重构

| action | 命令行实现 |
|--------|-----------|
| `get` | `curl -sL` 获取完整页面信息 |
| `text` | `curl -sL | lynx -dump -stdin` 或 `html2text` |
| `title` | `curl -sL | grep -oP '<title>\K[^<]+'` |
| `links` | `curl -sL | grep -oP 'href="[^"]*"'` |
| `search` | `curl -sL | grep -c 'keyword'` 或 `grep -q` |

### 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` 删除：

```diff
- 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 瓶颈远大于进程开销 |