Universal File Opener CLI

UFO CLI

为 AI Agent 接触的每个文件提供一个本地工具。 查找传入文件中隐藏或有风险的内容，包括用于指示 AI 的文本；读取文件，在不破坏文件的前提下进行更改，并交付干净的副本。一个适用于 Linux 的离线 CLI 和本地 MCP 服务，每个步骤都会生成一份 JSON 回执。

• 查找。 ufo inspect --deep 会报告支持格式中的注释、跟踪的更改、隐藏文本、隐藏工作表、行和幻灯片、演讲者备注、文档属性、宏和嵌入文件。文本扫描会标记看起来像是给 AI 助手下达指令的行、个人数据和凭据模式，以及形近的混合文字系统词语；还会指出以文档名义传播的程序。ufo inspect --human 会以易读的方式打印相同的发现。
• 读取。 ufo text 会提取内容并附带来源信息，--format structure 还会添加地址和哈希值。ufo capabilities --file 会告知 Agent 单个文件允许执行的操作：有界读取、候选编辑及其确切帮助信息，或者说明为何应停止。
• 更改。 对 Word、Excel、PowerPoint、PDF、JSON、CSV 和文本文件进行受保护的编辑时，会检查源文件哈希和预期内容、写入新副本，且绝不覆盖原文件。未改动的包部件和未指定的值会保留其精确字节；ufo text --format structure --targets 会为所选更改生成精确的保护模板。
• 交付。 ufo clean 会写入一份副本，移除检查发现的可移除隐藏内容；回执会列出已移除和未移除的内容。

检查报告会说明覆盖范围的缺口。对于未知文件，基本信息并不意味着 UFO 为其格式提供专用读取器、编辑器或安全检查器；检查结果仅供参考：UFO 不是杀毒软件，也不保证内容安全。文件和资源限制同样适用。

个人和小型团队可免费使用。 所有命令和支持的文件类型均包含在内，无需注册，也没有水印。人数少于 10 人且年收入（包括资助）低于 100 万美元的组织符合条件；任何组织都可以免费试用。请查看资格详情。

网站以及与其他 Agent 工具的比较：https://universalfileopener.com/cli/

安装

原生 Linux x86_64 安装需要 glibc 2.35 或更高版本（已在 Ubuntu 24.04 和 Debian 12 上测试）。不支持原生 Alpine/musl 安装。已随附 Java 运行时；下方的容器选项使用其自身的运行时。

curl -fsSL https://universalfileopener.com/install.sh | sh
ufo doctor
ufo skill install --agent claude-code --dir "$PWD"

install.sh 会从最新的 版本发布下载应用映像，根据该版本发布中的 SHA256SUMS 进行校验，并将其安装到 ~/.local 下，无需 sudo。同一版本发布还提供 Debian 软件包（sudo apt install ./universal-file-opener_1.10.2_amd64.deb）和 ufo-cli-1.10.2-docker.tar，这是可用于离线传输的容器映像归档。

容器

在包含 report.docx 的目录中，下载并运行公开映像：

docker run --rm --network none --read-only --cap-drop ALL \
  --user "$(id -u):$(id -g)" --security-opt no-new-privileges \
  --pids-limit 128 --cpus 2 --memory 1g \
  --tmpfs /tmp:rw,nosuid,nodev,size=256m \
  --mount type=bind,src="$PWD",dst=/input,readonly \
  ghcr.io/krauqllc/ufo-cli:1.10.2 text /input/report.docx

无需登录 GitHub。临时挂载为必需项。进行编辑时，请在 /output 挂载单独的可写输出文件夹，并在其中选择一个新文件。容器可以读取、编辑并识别文本；页面渲染和 Office 到 PDF 的转换需要应用程序包。若要部署并固定到不可变映像，请使用版本发布说明中的摘要。

连接 Agent

在项目文件夹中运行。对于 Cursor，使用 ufo skill install --agent cursor --dir "$PWD"。对于 Codex，使用 ufo skill install --agent codex --dir "$PWD" --replace；它只会添加或更新项目 AGENTS.md 中带标记的 UFO 部分，其余内容保持不变。安装指南后，请启动新会话。

如果使用 MCP 客户端而非技能，运行 ufo mcp print-config --client claude-code 即可打印模板。替换其中的可执行文件和文件夹占位符，然后将其合并到客户端配置中。 打印配置不会注册服务。请参阅完整设置说明。

获取首个实用结果

在此仓库的克隆副本中，确保已安装 Python 3.10+ 和 jsonschema：

python3 tools/cli/first_run_demo.py --ufo "$(command -v ufo)" \
  --expect-version 1.10.2 --output first-look --mcp

这个简短示例会生成两个虚构的输入文件。它会收集陌生文件的基本信息，查找受支持 DOCX 中的文档属性、审阅者评论和隐藏文本，并写入一份干净的副本。它会独立检查 保存后的 ZIP/XML 字节、原始哈希值、完整回执架构，以及拒绝覆盖现有输出的行为。 打开 first-look/START_HERE.txt 查看结果。

每个 notInspected 未检查项和跳过的清理类别都会保留在证据中。 可选的 MCP 检查会发现工具，并通过本地 stdio 调用检查； 但这不能证明已安装的助手成功连接。

查看完整的混合文件编辑工作流

观看 64 秒短片，然后 检查并重放该工作流。 一份虚构的变更简报会更新电子表格模型、一份带有原生修订记录的 Word 备忘录，以及 董事会演示文稿中的两张幻灯片。

短片使用可下载文件经 Microsoft Office 实际导出的内容。重放只需要 Python 3 和 UFO， 无需 Agent 或模型 API。它会检查重新计算后的全部 20 项保存结果、现有公式、 早期期间、原生 Word 修订记录、原始哈希值以及未改动的程序包部分。每项编辑都与 其试运行输出哈希值一致；若源哈希值过期，则会拒绝操作。这是经过剪辑的脚本演示， 不是 Agent 录制内容，也不是计时基准测试。

高效工作

阅读所需操作的帮助：ufo edit paragraphs --help。使用 ufo find --text 'budget' --compact report.docx 定位文本，然后通过 ufo text --format structure --compact 读取选定的段落、单元格或幻灯片。 将对同一文件的独立更改批量处理，并在下一次编辑时复用输出回执中的哈希值。 需要审计记录时，请保存完整回执。

--compact 适用于 text、find、inspect --deep 和 edit；intake、 convert 和 unpack 不接受此选项。对于 MCP，请阅读 tools/list 架构： find 接受一个文件，report 则需要输出路径。

每项编辑操作都接受 --expect-sha256（MCP 中为 options.expectedSha256），因此 如果源文件已过期，操作会拒绝执行，而不会进行编辑。请查看各操作的帮助，了解 该操作的其他标志，不要照搬其他操作的标志。对于陌生文件，请从 ufo capabilities --file FILE 开始。交接前，务必检查回执中跳过的内容，并检查输出。

此存储库包含什么

二进制文件位于 Releases 页面。此存储库包含检查这些文件所需的内容：

路径	内容
docs/cli/schemas/	CLI 写入的每份回执和报告对应的 JSON 架构
tools/cli/first_run_demo.py	展示如何检查陌生文件以及如何进行检查并生成干净副本的简短示例，包含独立检查
tools/cli/own_file_evaluation.py	使用你自己的文件运行 UFO：读取文件、进行可逆编辑，并独立检查每个输出
tools/cli/evaluate_sample.py	使用生成的示例文件进行端到端评估
tools/corpus/compare_agent_tools.py	在相同任务和检查条件下，与其他 Agent 文件工具进行比较
tools/corpus/realworld_corpus_manifest.tsv	该比较使用的公开文件及其来源和 SHA-256
tools/corpus/download_realworld_corpus.py	下载这些文件并逐个验证

tools/ 下的其他文件是上述脚本导入的辅助工具。它们需要 Python 3.10 或更高版本、用于回执验证的 jsonschema，以及已安装的 UFO 构建版本。

经过审查的发行版源文件也位于 packaging/npm/、 packaging/linux-cli/registry/ 和 packaging/homebrew/ 下。这些封装器和 描述文件面向同一 Linux x86_64 发行版。Homebrew tap 是公开的。Homebrew 7 只有在你信任其他 tap 后，才会从中加载 formula： brew trust --formula krauqllc/ufo/ufo，然后运行 brew install krauqllc/ufo/ufo。 此发行版还提供完整的本地 MCPB 捆绑包，适用于兼容的 Linux 客户端，已列入 官方 MCP Registry。 目录修订版本 1.10.2-1 提供匹配的 1.10.2 引擎和捆绑包。安装捆绑包时，只选择已存在的任务文件夹；默认情况下不会授予任何目录访问权限。npm 软件包 @krauq/ufo-cli 会安装相同的已验证运行时；发布者通过 2FA 批准后，版本 1.10.2 就会显示在该软件包页面上，可通过 npm view @krauq/ufo-cli versions 查看。在 npm 12 上，使用 npm install --global @krauq/[email protected] --allow-scripts=@krauq/ufo-cli； 在 npm 11 或更早版本上，省略 --allow-scripts 并保持安装脚本启用。 该封装器会验证并安装此精确的 Linux 运行时。Smithery 和 Glama 账号提交是另外两项待办步骤。

自行检查

UFO=$(command -v ufo)
python3 tools/cli/evaluate_sample.py --ufo "$UFO" --expect-version 1.10.2 --output sample-result
python3 tools/cli/own_file_evaluation.py --files ~/my-files --ufo "$UFO" --expect-version 1.10.2 --output my-files-report
python3 tools/corpus/download_realworld_corpus.py --download --output corpus
python3 tools/corpus/compare_agent_tools.py --download --corpus tools/corpus/realworld_corpus_manifest.tsv --corpus-root corpus --ufo "$UFO"

--download 会获取其他工具的固定版本发行版，而 --setup-libraries 会创建比较所用的 Python 库环境。两者都只需联网一次；实际运行时无需联网。

许可证

此处的文件采用 Apache 2.0 许可证（LICENSE、NOTICE）。二进制文件依据 ENGINE-LICENSE.txt 授权：个人、评估、教育、非商业用途，以及人数少于 10 人且年收入低于 100 万美元（包括资助）的组织均可免费使用。规模更大的组织需要获取许可证。

使用 ufo license install ./license.json 安装收到的文件，然后运行 ufo license status。每个付费周期都会收到一个新文件；使用 ufo license install ./license.json --replace 安装续期文件。检查过程无需联网。如需获取或恢复文件方面的帮助，请将订单号发送至 [email protected]。

安全

如要报告安全问题，请发送邮件至 [email protected]，并在主题中注明“Security”。