aispace

aispace

为 AI Agent 和人类安全地临时分享文件。
可编写脚本的 CLI，支持链接过期、格式可预测的 JSON，以及可选的本地 age 加密。

网站 · 文档

aispace.sh 是一个对机器人友好的文件投递服务，适用于过大、结构复杂或临时性的聊天文件。这个开源客户端专为自动化而设计：单个二进制文件、稳定的退出码、流式上传，以及在可预测的最后一行打印分享 URL。

• 专为 Agent 打造： 支持的命令提供稳定的 JSON、完善的错误文档、标准输入支持，以及用于自动化的明确非交互标志。包含机密信息的交接命令仍需交互操作。
• 短期有效，设计如此： 文件过期、链接单独设置过期时间、撤销链接，以及可选的每条链接下载次数限制。
• 按需保护隐私： 密封式异步传输会在本地加密文件名、文件元数据和内容；主密钥永远不会发送给 aispace。现有的 age X25519 流程仍可用于收件人密钥工作流。

密封式传输、Agent 身份、设备配对和自适应持久化优先意图仍属实验功能。普通上传和持久化 R2 存储仍可照常使用。

托管服务由独立团队运营。本仓库包含客户端、Agent 技能和集成示例，不包含服务端、计费系统、部署配置或客户数据。

60 秒快速上手

安装最新版本：

curl -fsSL https://aispace.sh/install.sh | sh

使用在 aispace 控制面板中创建的密钥进行身份验证，然后存储文件：

aispace login --key ask_...
aispace upload report.pdf --json

如果使用 Pro 账户，可添加一个单独设置过期时间的公开交接链接：

aispace upload report.pdf --link --link-expires 1h --max-downloads 1

URL 会单独打印在最后一行，方便 Agent 或 shell 脚本捕获。添加 --json 可获取格式稳定、便于机器读取的响应。精简后的响应如下：

{"file":{"id":"...","name":"report.pdf"},"link":{"url":"https://aispace.sh/d/...","expires_at":1757003600}}

其他安装方式：

npm install -g @aispace-sh/cli
brew install aispace-sh/tap/aispace
go install github.com/aispace-sh/aispace-client@latest

使用 AISPACE_VERSION=v1.2.3 固定 shell 安装程序的版本。发布的二进制文件支持 amd64 和 arm64 架构的 macOS、Linux 和 Windows。shell 安装程序支持 macOS 和 Linux；Windows 用户请使用 npm。

---

为 Agent 配备 aispace

仓库中包含一个可复用且兼容 Codex 的技能。克隆仓库，并将该技能链接到你的个人 Codex 技能目录：

git clone https://github.com/aispace-sh/aispace-client.git
mkdir -p ~/.codex/skills
ln -s "$PWD/aispace-client/skills/aispace" ~/.codex/skills/aispace

重启 Codex，然后让它在需要向你提供报告、压缩包、图片或其他生成的内容时使用 aispace。该技能默认使用仅限账户访问的存储，除非你请求公开链接；优先采用较短的过期时间，并将加密身份视为凭据。

模型上下文协议（MCP）

原生 CLI 还通过本地 stdio 暴露十个类型化 MCP 工具。在控制面板中创建一个单独配置范围的机器人密钥，在启动 Codex 的环境中导出该密钥，然后添加：

[mcp_servers.aispace]
command = "aispace"
args = ["mcp", "serve"]
env_vars = ["AISPACE_KEY", "AISPACE_URL", "AISPACE_ALLOWED_ROOTS"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

[mcp_servers.aispace.tools.aispace_create_link]
approval_mode = "prompt"

[mcp_servers.aispace.tools.aispace_revoke_link]
approval_mode = "prompt"

[mcp_servers.aispace.tools.aispace_delete_file]
approval_mode = "prompt"

运行 codex mcp list 验证连接。同一主机上的 ChatGPT 桌面应用、Codex CLI 和 Codex IDE 扩展会共享此配置。请将密钥保存在密钥存储中，或通过注入的环境提供；切勿将其展开后的值放入已提交的项目文件或命令参数中。Claude Code 和通用主机示例请参阅 docs/CLI.md。

对于自定义 Agent 运行时，docs/LLM_USAGE.md 包含系统提示词片段、兼容 OpenAI/Anthropic 的工具架构，以及 Python 处理程序参考。可运行的 shell、CI 和加密交接方案请参阅 examples。

常见工作流

# Upload text from stdin and return an expiring public link (Pro).
echo "hello" | aispace upload - --name note.txt --link --link-expires 1h

# Keep a file available only to this key.
aispace upload secret.txt --private

# Share ciphertext; keep the generated age identity locally.
aispace upload secret.pdf --encrypt --identity-out secret.agekey --link

# Authenticated handoff to another key on the same account—no public URL.
aispace upload notes.md --shared --json

# Sealed multi-file handoff. The URL fragment holds the local decryption secret.
aispace transfer create report.pdf charts.png --sealed --link --expires 1d --max-downloads 1

# Move that sealed transfer to a nearby browser/device with an expiring code.
aispace handoff offer "$TRANSFER_ID"
# On the receiving CLI: aispace handoff receive J7KM-PQRT

# Pin an agent and deliver without exposing a bearer decryption link.
aispace recipient add "$RECIPIENT_INVITATION"
aispace recipient verify research-agent --fingerprint "$RECIPIENT_FINGERPRINT"
aispace transfer create report.pdf --sealed --to research-agent --from my-agent --expires 7d
aispace inbox receive "$DELIVERY_ID" --yes

# Paste the link interactively, inspect its private manifest, then decrypt and verify.
aispace transfer receive

# Receive, manage, and revoke.
aispace ls --json
aispace download <file_id> --output ./file
aispace download <file_id> --output ./file --verify   # check the recorded SHA-256
aispace link <file_id> --expires 30m --max-downloads 1
aispace revoke <link_id>
aispace rm <file_id>

关于密封数据包、可信 Agent 收件箱、设备配对、自适应 R2 回退和恢复，请遵循 docs/SECURE_HANDOFFS.md。完整的命令参考见 docs/CLI.md；HTTP 契约见 docs/API.md。

upload 接受 --name、--expires、--content-type、--sha256、--link、--link-expires、--max-downloads、--private、--shared、--encrypt、--recipient 和 --identity-out。上传时会从磁盘流式读取。加密上传会在本地使用 age X25519，并将密文存储为 <name>.age；密钥身份绝不会发送到 API。

transfer create 使用 aispace-sealed-v1：AES-256-GCM 认证分块和加密清单支持多个文件、分段重试以及经验证的回执。transfer receive 接受通过提示词、--token-file 或 AISPACE_TRANSFER_TOKEN 提供的密钥；在共享系统上，应避免将完整片段链接或密钥放入进程参数中。

除非显式指定 --include-secret，否则 transfer create --json 不会包含持有者链接和密钥；包含密钥的 JSON 必须重定向输出，不得写入终端。handoff encode 同样接受通过受保护的提示词、--token-file 或 AISPACE_TRANSFER_TOKEN 提供的密钥。

使用 --json 时，错误也会保持结构化格式并写入 stderr。upload --link --json 返回 {"file": File, "link": ShareLink}；加密上传还会添加一个 "encryption" 对象。

配置

优先级：标志 > 环境变量 > 配置文件 > 默认值。

设置	标志	环境变量	文件键	默认值
API 密钥	--key	AISPACE_KEY	key	—
服务	--url	AISPACE_URL	url	https://aispace.sh

省略 decrypt --identity-file 时，AISPACE_AGE_IDENTITY 会提供解密身份。出于特意的安全设计，它不能作为命令行值使用。

配置文件：$XDG_CONFIG_HOME/aispace/config.json（默认路径为 ~/.config/aispace/config.json），写入权限为 0600。如果其他用户可读取该文件，程序会打印警告。AISPACE_CONFIG 可覆盖该路径。

时长（--expires、--link-expires）接受 Go 语法以及 d 后缀：30m、24h、7d、1d12h，或不带单位的秒数。省略这些参数时，将使用服务默认值（文件为 7 天，Pro 公开链接为 1 小时）。

文件权限和链接

文件可见性控制经过身份验证的密钥访问权限。公开链接是一种独立的访问能力：创建公开链接需要 Pro 账户，创建后，任何持有该 URL 的人都可以访问对应文件。

文件模式	谁可以访问？	文件有效期	公开链接有效期	下载上限	访问权限泄露时的暴露范围
private	仅上传密钥	默认 7 天；Free 最长 7 天，Pro 最长 30 天	无	账户每月限额	属于该密钥的私有文件，直到删除或过期
account	账户上的所有有效密钥	默认 7 天；Free 最长 7 天，Pro 最长 30 天	无	账户每月限额	账户共享的文件，直到删除或过期
private + 公开链接	上传密钥和任何持有 URL 的人	最长 30 天，因为创建链接需要 Pro	默认 1 小时；最长 30 天，且不会超过文件有效期	可选的单链接上限	仅限链接指向的文件，直到链接过期、被撤销、达到下载上限、文件被删除或过期
account + 公开链接	账户密钥和任何持有 URL 的人	最长 30 天，因为创建链接需要 Pro	默认 1 小时；最长 30 天，且不会超过文件有效期	可选的单链接上限	URL 访问权限会在链接失效时结束；账户密钥仍可访问文件，直到文件被删除或过期
客户端加密文件	可见性设置控制密文访问权限；只有持有 age 身份的人才能解密	与所选文件模式的限制相同	创建链接时适用相同的仅限 Pro 限制	可选的单链接上限	需要同时获取密文和 age 身份才能接触明文

可用的时长格式包括 30s、15m、1h、36h 和 7d。

文件有效期结束后，文件将无法访问。链接可能会更早失效，例如链接过期、被撤销或达到下载上限。删除文件会立即终止经过身份验证的密钥访问权限，并使所有关联的公开链接失效。

退出代码

代码	含义
0	成功
1	通用错误（网络错误、下方未列出的 4xx/5xx）
2	用法错误
3	身份验证错误（401，或未配置密钥）
4	配额／大小错误（402、413）
5	请求频率受限（429）——幂等 GET 请求会等待 Retry-After（最长 30 秒）并重试一次

错误会以 error: <message> (<code>) 的形式输出到 stderr；使用 --json 时，则会将 JSON 对象 {"error":{"code","message","status","details","exit_code"}} 输出到 stderr。

开发

go test -race ./... && go vet ./... && test -z "$(gofmt -l .)"
go build -ldflags "-X main.version=0.0.0-dev" -o aispace .
(cd npm && npm test && npm pack --dry-run)

测试套件使用本地 HTTP 测试夹具，无需 aispace 密钥。欢迎贡献——请从 CONTRIBUTING.md 开始，查看 ROADMAP.md，并阅读 CHANGELOG.md。针对具体问题的 Bug 报告和功能提案可使用仓库提供的结构化问题表单。

版本发布通过手动触发的 GitHub Actions 工作流完成。GoReleaser 会构建带校验和的 macOS、Linux 和 Windows 二进制文件，更新 Homebrew tap，将 @aispace-sh/cli 发布到 npm，在这三个平台上验证已安装的 MCP 服务，最后将 sh.aispace/mcp 发布到官方 Registry。有关发布者配置、可恢复的仅 MCP 发布流程和发布检查清单，请参阅 RELEASE.md。

安全

请通过 GitHub Security Advisories 私下报告漏洞。请勿在公开问题中包含凭据、私有链接或客户数据。请参阅 docs/SECURITY.md。