CLI-Anything 之 Tigris 对象存储 Harness：让 AI Agent 通过一个入口驱动快照、IAM 与临时凭证

CLI-Anything 之 Tigris 对象存储 Harness：让 AI Agent 通过一个入口驱动快照、IAM 与临时凭证

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

本篇技术指南围绕 CLI-Anything 仓库中 tigris 子模块的 Agent Harness 展开，讲解如何把 Tigris（全球分布式、S3 兼容、免出口流量费的对象存储服务）的官方 CLI 包装成一个对 AI Agent 友好的统一命令行入口cli-anything-tigris。读完本文，你将掌握该 Harness 的安装与认证流程、七大命令组（auth / bucket / object / presign / snapshot / access-key / iam）的完整用法、--json机器可读输出的契约，以及面向编码 Agent 的隔离、备份与销毁安全最佳实践，并了解其底层"壳调用官方 CLI"的实现原理。

背景：为什么需要一个 Tigris CLI Harness

Tigris 是一个全球分布式、S3 兼容的对象存储服务，核心卖点包括数据就近放置读取、无出口流量费（no egress fees）、以及快照（snapshots）和范围受限访问密钥（scoped access keys）等专有原语。对于编码 Agent（如 Claude Code、Codex）而言，直接面对原始 CLI 存在输出不可解析、命令繁多、权限管理繁琐等问题。

cli-anything-tigris的思路与 CLI-Anything 项目一致：包装官方tigrisCLI 而非重新实现 S3 协议，从而：

• 让 Agent 触及 Tigris 的全部原语（快照、IAM、范围化凭证、OAuth），而不仅是通用 S3 操作；
• 随着上游 CLI 发布新命令，Harness 自动继承新能力；
• 通过"处处--json"的单一入口统一输出契约。

需要特别强调的是，这是Tigris CLI 专属工具，不是通用的 S3/MinIO/R2/AWS 端点管理器，这一点在 README 与 TIGRIS.md 中均有明确声明。

安装与认证

安装分三步，缺一不可：

# 1. 安装底层 Tigris CLI npm install -g @tigrisdata/cli # 或：brew install tigrisdata/tap/tigris # 2. 认证（浏览器 OAuth） tigris login # 3. 安装本 Harness pip install cli-anything-tigris

前提条件（来自 SKILL.md）：

• Python 3.10+（依赖 PEP 604 联合类型与 PEP 585 泛型；macOS 系统自带 Python 为 3.9，需用 pyenv、uv 或brew install python@3.12）；
• tigrisCLI 在 PATH 上（其二进制别名是t3）。

认证默认走tigris login的浏览器 OAuth 流程，凭据由官方 CLI 自身解析。对于依赖环境变量认证的场景，Harness 还支持通过--access-key/--secret-key显式传入凭据——底层实现会把它们导出为子进程的TIGRIS_STORAGE_ACCESS_KEY_ID、AWS_ACCESS_KEY_ID、TIGRIS_STORAGE_SECRET_ACCESS_KEY、AWS_SECRET_ACCESS_KEY环境变量（见 tigris_backend.py）。

setup.py（setup.py）显示运行时依赖仅两个：click>=8.0.0与prompt-toolkit>=3.0.0，刻意不引入 boto3，因为 S3 协议由官方 CLI 负责。安装后提供cli-anything-tigris控制台脚本。

快速上手

# 交互式 REPL cli-anything-tigris # 或直接驱动 cli-anything-tigris --json auth whoami cli-anything-tigris --json bucket list cli-anything-tigris --json object cp ./local.bin t3://my-bucket/remote.bin cli-anything-tigris --json snapshot take my-bucket --name baseline-v1 cli-anything-tigris --json access-key create agent-run-42 cli-anything-tigris --json access-key rotate tid_AaBb --yes cli-anything-tigris --json presign get --bucket my-bucket --key hello.txt

注意：bucket 删除、access-key 删除、access-key 轮换均需显式--yes，否则 Harness 拒绝调用后端。

全局选项

这些选项定义在 tigris_cli.py。入口函数还通过TIGRIS_CLI前缀支持环境变量（auto_envvar_prefix="TIGRIS_CLI"）。

REPL 模式

不带子命令直接运行cli-anything-tigris即进入交互式 REPL，支持 tab 补全与历史记录（基于 prompt-toolkit）。REPL 内置help显示命令速查、quit/exit/q退出，并把每行输入经shlex.split后交给 Click CLI 解析（tigris_cli.py）。

七大命令组全参考

auth —— 认证

包装tigris login/logout/whoami：

实现位于 core/auth.py，其中login/logout因不支持 JSON 格式化而以capture=False方式直接流式输出。

bucket —— Bucket CRUD

底层映射见 core/bucket.py：delete命令在未带--yes时会直接输出错误并退出码 1，从源头拦截危险操作。

object —— 对象操作

包装tigris ls/cp/rm/stat：

两点实现细节值得注意：

1. URI 规范化：后端_path_to_t3会把tigris://bucket/key、bucket/key甚至/bucket/key统一规范化为t3://bucket/key（tigris_backend.py），单测 test_core.py 覆盖了各种非法输入（如s3://b/k、tigris://nokey）的拒绝逻辑。
2. 上传/下载复用cp：put --file走tigris cp <file> t3://bucket/key，put --text会把文本暂存到临时文件再 cp 并在结束时清理；get则反向下载。这解释了为什么 SKILL.md 中object组的说明是"wrapstigris ls/cp/rm/stat"。

cp命令要求 src 与 dst 至少一方是远程 URI，否则报错退出（core/object.py）。当两端都是 t3 时执行服务端复制（server-side copy），数据完全不经 Agent 中转，也不会产生出口流量费——这是成本与安全上的关键特性。

presign —— 限时 URL

默认有效期 3600 秒；还支持--access-key指定签名所用密钥。实现见 core/presign.py，底层调用tigris presign <path> --method get|put --expires-in <sec>。后端会同时兼容上游 CLI 的两种返回形态：JSON 模式下解析{"url": "..."}字段，否则回退为裸 URL 字符串。

snapshot —— 时间点快照（Tigris 专属原语）

快照是 bucket 某一时间点的只读副本，是通用 S3 兼容提供商不具备的能力，也是每个 Agent 隔离与回滚方案的基石。实现见 core/snapshot.py。

access-key —— 范围化编程凭证

assign与snapshot组合使用即可实现"按 Agent 隔离"：为单次 Agent 运行铸造一个仅限单一 bucket 的最小权限密钥，运行结束即删除。delete与rotate的--yes校验在 core/access_key.py 中由命令层强制，未携带--yes直接拒绝。

iam —— 策略与组织用户

实现见 core/iam.py。与access-key assign配合，IAM 策略让组织可以向编程客户端授予狭窄、可审计的权限。

双输出模式与 Agent 调用契约

所有命令支持两种输出：

• 人类可读（默认）：表格、颜色、格式化文本，经统一的 REPL skin 渲染；
• 机器可读（--json）：输出 JSON 信封；对于上游 CLI 原生支持--format json的命令（如buckets list、snapshots list、whoami），则原样透传其 JSON 输出；对不支持 JSON 的命令（如cp），由 Harness 包一层薄信封。

后端_run的核心逻辑是：拼装tigris <args> --format json命令（--format json追加在末尾避免与子命令解析冲突），用subprocess.run执行并解析 JSON；解析失败则回退为原始文本（tigris_backend.py）。非零退出码会抛出TigrisCliError并附带 stderr 信息。

Agent 程序化调用时遵循以下契约（来自 SKILL.md 与 TIGRIS.md）：

1. 始终加--json以获得可解析输出；
2. 检查返回码——0 为成功，非 0 为错误；
3. 读取 stderr 获取错误信息；
4. object cp接受t3://bucket/key或tigris://bucket/keyURI；t3 → t3 的服务端复制完全跳过往返；
5. presign在人类模式下 URL 输出到 stdout；JSON 模式下位于url字段；
6. 销毁类操作：bucket 删除、access-key 删除与轮换必须显式--yes；建议先对目标 bucket 打快照，再执行操作，最后视情况保留或丢弃快照；
7. 按 Agent 隔离：access-key create+access-key assign --bucket B --role Editor铸造单 bucket 作用域密钥，Agent 运行结束用access-key delete吊销。

架构与源码导览

Harness 目录结构如下（详见 TIGRIS.md）：

tigris/agent-harness/ ├── setup.py # 依赖仅 click、prompt-toolkit；无 boto3 ├── TIGRIS.md # 架构与 SOP 文档 └── cli_anything/tigris/ ├── __main__.py # python -m 入口 ├── tigris_cli.py # Click CLI + REPL 调度器 ├── core/ │ ├── auth.py # login, logout, whoami │ ├── bucket.py # list, create, delete, info │ ├── object.py # list, put, get, delete, info, cp │ ├── presign.py # presign get/put │ ├── snapshot.py # list, take │ ├── access_key.py # list, create, get, delete, assign, rotate │ └── iam.py # policies + users ├── utils/ │ ├── tigris_backend.py # 围绕 `tigris` 的 subprocess 包装器 │ └── repl_skin.py # 统一 REPL 皮肤 ├── skills/SKILL.md # 完整命令参考与 Agent 使用指引 └── tests/ ├── test_core.py # subprocess.run 全 mock 的单测 └── test_full_e2e.py # 真实 CLI 的端到端测试（环境变量门控）

各命令组与上游 CLI 的映射关系：

测试策略：test_core.py在模块级 patch 了shutil.which，并把subprocess.run完全 mock 掉，因此无需安装tigrisCLI 也无网络即可运行，覆盖 URI 规范化、--yes强制校验、JSON 透传等行为；test_full_e2e.py面向真实 bucket，需设置环境变量CLI_ANYTHING_TIGRIS_RUN_E2E=1、tigris在 PATH 且已认证，运行说明见 tests/TEST.md。

Agent 实战模式

结合上述机制，可以沉淀出三类可直接复用的模式：

1. 备份优先的销毁流程——任何删除/轮换前先建恢复点：

cli-anything-tigris --json snapshot take my-bucket --name pre-cleanup cli-anything-tigris --json bucket delete --name old-bucket --yes # 如需回滚：snapshot list 找到快照后恢复

2. 单 Agent 单密钥的最小权限隔离：

cli-anything-tigris --json access-key create agent-run-42 cli-anything-tigris --json access-key assign tid_AaBb --bucket my-bucket --role Editor # ... Agent 在此密钥作用域内工作 ... cli-anything-tigris --json access-key delete tid_AaBb --yes # 运行结束吊销

3. 免共享凭证的工件交接——通过预签名 URL 把对象访问权移交给其他工具或下游 Agent，全程不泄露密钥：

cli-anything-tigris --json presign get --bucket my-bucket --key artifacts/model.pt --expires 3600

适用边界与注意事项

• 该 Harness 只面向官方 Tigris CLI，认证模型遵循其 OAuth 会话或环境变量凭据，不要将其用作通用 S3 端点工具；
• 破坏性命令的--yes由命令层强制校验（未携带即拒绝），但快照、IAM、密钥等操作仍会真实作用于云端资源，生产环境请先在小规模 bucket 上验证；
• Python 版本要求 3.10+，旧版 Python（尤其 macOS 系统 Python 3.9）需先升级解释器；
• 底层 CLI 若不在 PATH，Harness 启动时会报错并提示安装命令，但--help仍可用（后端初始化错误被延迟处理，见 tigris_cli.py）。

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything