拉链
Go CLI和MCP服务器，将zip文件作为虚拟文件系统公开，以实现无缝的AI代理集成。
问题陈述
当AI编码代理（Claude Code等）需要操作zip存档中的文件（例如zip中的Excel文件）时，它们会浪费大量令牌编写即席提取/重新打包脚本。这创建了一个“令牌黑洞”，其中代理重复实现相同的zip提取逻辑。
zipfs通过在zip存档上提供透明的文件系统层来解决这个问题。代理可以像处理普通目录一样处理zip内容，而zipfs会自动处理所有提取和重新打包。
特性
- 将zip文件作为工作区目录打开
- 会话管理（多个拉链同时打开）
- Tree/ls/grep覆盖zip内容
- 读取/写入单个文件
- 自动将更改同步回zip
.bak.zip备份 - 用于AI代理集成的MCP服务器模式
- 用于人工/脚本使用的CLI模式
- 符合XDG基本目录(
~/.local/share/zipfs/) - 通过以下方式与xlq集成（超越mcp）
--basepath
快速开始
CLI示例
# Open a zip file
zipfs open /tmp/report.zip --name report
# Browse contents
zipfs tree report
zipfs ls report/data/
# Get workspace path (for tool integration)
zipfs path report
# Output: ~/.local/share/zipfs/workspaces/report/contents
# Use with xlq for Excel files inside the zip
xlq --basepath $(zipfs path report) head --file financials.xlsx
# Sync changes back to the zip
zipfs sync report
# Clean up
zipfs close report
zipfs prune # remove all workspaces状态和会话管理
# List all open sessions
zipfs sessions
# Check status of a specific session
zipfs status report
# Read a file from the zip
zipfs read report:data/config.json
# Write/update a file in the zip
echo "new content" | zipfs write report:data/notes.txt
# Search within zip contents
zipfs grep "pattern" reportMCP集成
zipfs可以作为MCP服务器运行，将zip文件系统操作作为AI代理可以调用的工具公开。
配置
添加到您的 claude_desktop_config.json 或 .claude/settings.json:
{
"mcpServers": {
"zipfs": {
"command": "zipfs",
"args": ["mcp"]
}
}
}可用的MCP工具
zipfs_open-将zip文件作为工作区会话打开zipfs_close-关闭工作区会话zipfs_ls-列出zip中的目录内容zipfs_tree-显示zip内容的树视图zipfs_read-从zip读取文件内容zipfs_write-在zip工作区中写入/更新文件zipfs_delete-删除工作区中的文件或目录zipfs_grep-在zip内容中搜索模式zipfs_path-获取工具集成的工作空间路径zipfs_sync-将工作区更改同步回zipzipfs_sessions-列出所有打开的会话zipfs_prune-删除过时的或所有工作区会话zipfs_status-显示提取后修改/添加/删除的文件
MCP工作流示例
1. zipfs_open(path="/data/reports.zip", name="reports")
-> { session_id, workspace_path, file_count }
2. zipfs_ls(session="reports")
-> { entries: ["Q4-Report.xlsx", "summary.docx", ...] }
3. zipfs_path(session="reports")
-> { path: "/home/user/.local/share/zipfs/workspaces/reports/contents" }
4. xlq_head(basepath="...", file="Q4-Report.xlsx", sheet="Revenue")
-> { rows: [...] }
5. zipfs_sync(session="reports")
-> { synced: true, backup: "/data/reports.bak.zip" }安装
go install github.com/Fuabioo/zipfs@latest工作区结构
zipfs使用XDG基本目录规范进行工作区管理：
~/.local/share/zipfs/
├── workspaces/
│ └── /
│ │ ├── contents/ # Extracted zip contents (the "mounted" filesystem)
│ │ ├── original.zip # Copy of the original zip at open time
│ │ └── metadata.json # Session metadata
│ └── ...
└── config.json # Global configuration (optional)同步时，原始zip将备份为 .bak.zip 在被覆盖之前。
用例
Zips中的Excel操作
zipfs open archive.zip --name data
xlq --basepath $(zipfs path data) head --file report.xlsx --sheet Summary
xlq --basepath $(zipfs path data) write-cell --file report.xlsx --sheet Summary --cell B5 --value 42
zipfs sync data管道友好型工作流
zipfs open /tmp/archive.zip --name work
cat newfile.txt | zipfs write work:data/newfile.txt
zipfs read work:data/config.json | jq '.version = "2.0"' | zipfs write work:data/config.json
zipfs sync work
zipfs close work --no-sync批处理文件更新
for zip in *.zip; do
name=$(basename "$zip" .zip)
zipfs open "$zip" --name "$name"
zipfs write "$name:config.json" --content '{"updated": true}'
zipfs sync "$name"
zipfs close "$name" --no-sync
done文档
看 docs/ADR/ 架构决策记录包括：
- 项目范围和目标
- 工作空间布局和XDG合规性
- 会话管理生命周期
- 同步和备份策略
- MCP协议设计
- CLI界面设计
- xlq集成模式
- 安全模型
- Go项目结构
许可证
麻省理工学院