OpenBox for AI Agent — pip install samai-openbox

安装

一行 pip 命令。支持 Python 3.8+。包内附带静态 OpenBox 二进制，无任何系统依赖。

# 标准安装
pip install samai-openbox

# 或用 pipx（推荐的 CLI 工具隔离安装方式）
pipx install samai-openbox

# 验证
samai-openbox --version
samai-openbox --help

该包为 Windows、macOS、Linux 各平台附带静态链接的 OpenBox 二进制。无需 Go 工具链，无需 Fyne，无 GUI 依赖——只有 CLI 引擎。

为什么 AI 智能体需要 Python 封装？

LLM 智能体很擅长写 shell 命令，但经常会搞错归档工具的语法。一条稳定的 CLI 就能解决这个问题。

🧠

一个动词，一套语法

所有归档操作都是 samai-openbox <动词> <文件...>。智能体不必记住 7z 用 a 还是 c、tar 要 -z 还是 -j、甚至 rar 是否已安装。

📦

自包含二进制

pip wheel 内嵌当前平台的静态 OpenBox 二进制。无需系统 zip/tar/7z——在最小化的 Docker 镜像和 CI runner 中尤其有用。

🔒

路径穿越防护

与 GUI 应用相同的引擎层防护：解压时拦截 ../../etc/passwd 类型的恶意条目。可以安全地用于解压不可信来源的压缩包。

⚡

零启动开销

静态 Go 二进制，热路径中无 Python 运行时。samai-openbox --version 约 10ms 完成。大型归档按底层 Go 归档库的速度处理。

🧩

JSON 输出模式

加 --json 后每条命令在 stdout 输出机器可解析的 JSON。完美适配智能体推理循环：列出归档内容、决定提取哪些、验证结果。

🎯

稳定且有文档的 CLI

动词和标志使用 semver 版本管理。我们不会在小版本里把 compress 改名为 pack。智能体可以依赖这个技能规范数年。

60 秒上手 CLI

五个动词覆盖智能体需要的全部归档操作。

压缩文件

# 把文件 / 文件夹压缩成新归档
# 输出格式由扩展名自动识别：.zip .tar .tar.gz .7z
samai-openbox compress report.pdf photos/ -o backup.zip

# 指定格式与压缩级别（0-9）
samai-openbox compress src/ -o release.tar.gz --level 9

# 7z 压缩（PATH 中需要 7-Zip CLI）
samai-openbox compress bigfile.bin -o archive.7z

解压归档

# 解压到目录（不存在时自动创建）
samai-openbox extract backup.zip -d ./restored

# 支持所有格式：zip, tar, tar.gz, 7z, rar, iso
samai-openbox extract legacy.rar -d ./legacy
samai-openbox extract cd-image.iso -d ./cd-contents

列出归档内容（JSON）

# 人类可读的列表
samai-openbox list backup.zip

# 机器可读的 JSON — 适合智能体推理
samai-openbox list backup.zip --json

# JSON 输出示例：
{
  "archive": "backup.zip",
  "format": "zip",
  "entries": [
    {"name": "report.pdf",  "size": 2516582, "modified": "2024-08-15T10:23:00Z"},
    {"name": "photos/",     "size": 0,       "modified": "2024-08-15T10:24:00Z", "is_dir": true},
    {"name": "photos/01.jpg", "size": 4409111, "modified": "2024-08-14T18:11:00Z"}
  ]
}

测试归档完整性

# 仅校验 CRC，不实际解压——损坏时退出码非零
samai-openbox test backup.zip

# CI 场景：检查目录下每个归档
for f in *.zip *.tar.gz *.7z; do
  samai-openbox test "$f" || echo "CORRUPT: $f"
done

查看版本与支持格式

samai-openbox --version
# openbox 0.4.4 (samai-openbox wrapper 0.1.0)
# platform: linux/amd64 · go1.23.4

samai-openbox formats
# FORMAT   COMPRESS  EXTRACT  NOTES
# zip      yes       yes      deflate or store
# tar      yes       yes      stdlib
# tar.gz   yes       yes      5 levels
# 7z       yes*      yes      *write needs 7z CLI
# rar      no        yes      read-only
# iso      no        yes      read-only

ClawHub 技能规范

把以下内容放进智能体的技能目录，让它知道何时、如何调用 OpenBox。

# skill.yaml — 把 samai-openbox 注册为智能体技能
name: openbox-archive
version: 0.1.0
description: 压缩与解压归档（zip, tar, tar.gz, 7z, rar, iso）
command: samai-openbox
install: pip install samai-openbox
verbs:
  - name: compress
    usage: samai-openbox compress <files...> -o <archive> [--level 0-9]
    formats_out: [zip, tar, tar.gz, 7z]
  - name: extract
    usage: samai-openbox extract <archive> -d <dir>
    formats_in: [zip, tar, tar.gz, 7z, rar, iso]
  - name: list
    usage: samai-openbox list <archive> [--json]
  - name: test
    usage: samai-openbox test <archive>
safety:
  - 解压时拦截路径穿越条目（../../etc/passwd）
  - 无网络调用 · 无遥测 · 无自动更新
  - 任何错误都返回非零退出码 — 可用 && 安全串联

智能体对话示例

LLM 智能体用 OpenBox 打包项目交付物的实际对话。

👤 用户

把 reports/ 文件夹打包成 .zip 准备发邮件，但跳过任何大于 10 MB 的文件。然后列一下压缩包内容让我确认一下。

🤖 智能体（使用 samai-openbox）

# 1. 在 reports/ 中查找小于 10 MB 的文件
find reports/ -type f -size -10M -print0 | \
  xargs -0 samai-openbox compress -o reports-email.zip

# 2. 以 JSON 列出结果以供验证
samai-openbox list reports-email.zip --json

完成。reports-email.zip 含 23 个文件，压缩后 47.2 MB（原始 89.4 MB）。三个超过 10 MB 的文件被排除：reports/q3-raw-data.csv、reports/audit-full.pdf、reports/appendix-exhibits.pptx。要我把这三个单独打成 .tar.gz 发送吗？

让你的智能体拥有归档技能

安装