用 Tunc Art 分享和打开文件
每个文件都有一个短的私密链接,例如 tuncart.com/Q7m4Kp。链接是一个地址,不是钥匙。
想要能直接用的搭法?示例里有可以贴给智能体的提示词。
打开文件
- 用你的 Tunc 账号登录。你可以打开自己的文件,以及通过工作区分享给你的文件。
- 图片、视频、音频、PDF 和网页(在沙箱里打开,脚本不会运行)直接显示在页面里;Markdown 按排版后的文档显示,代码和 JSON 文件带语法高亮(art.tunchub.com 上也是如此),其他文本和 CSV 按纯文本显示。Word、Excel、PowerPoint、压缩包和其他文件显示名称、类型和大小,并带一个下载按钮。 网页在沙箱里打开,访问不到你的账号;PDF 使用浏览器自带的阅读器。
- 下载 始终返回原始字节。
密码分享
所有者可以在文件页面上打开分享密码,并另外把密码发给对方。拿到链接和密码的人每次可以打开文件 30 分钟。关闭分享会立刻结束所有已解锁的会话。密码最长有效 7 天,或者到文件过期为止;重新设置可以延长。只有所有者能打开分享:助手无法打开分享。密码分享不会改变所有者智能体能做的事。
智能体与 Art API
智能体可以从 claude.ai、ChatGPT 和其他 MCP 客户端用 Tunc 登录,没有浏览器时用一个代码连接,或者使用 API 密钥。在 Tunc Hub 里,Art 是内置的;看看它是怎么工作的。
用 Tunc 账号登录
支持登录的 MCP 客户端用你的 Tunc 账号连接 https://mcp.tuncart.com/mcp:不需要复制任何密钥。 另一个产品的地址是 https://mcp.tuncorb.com/mcp。 你的客户端会打开 Tunc;你登录,或者用组织与条款创建一个免费账号,然后授权一次并选择它可以使用什么。
| 客户端 | 步骤 |
|---|---|
| claude.ai, Claude Desktop and Claude mobile | Customize → Connectors → Add custom connector → 名称填 Tunc Art,URL 填 https://mcp.tuncart.com/mcp → Add → Connect。免费版只允许一个自定义连接器;Team 和 Enterprise 由 Owner 在 Organization settings → Connectors 里添加。这个链接会打开对话框,名称和 URL 已经填好: |
| Claude Code | 先添加服务器,然后运行 /mcp,选择 tunc-art,再 Authenticate。 |
| ChatGPT | Settings → Apps & Connectors → Advanced → 打开 Developer mode → Create → 名称填 Tunc Art,URL 填 https://mcp.tuncart.com/mcp,Authentication 选 OAuth → Create → Connect。 |
| Cursor | 加到 ~/.cursor/mcp.json,然后 Settings → MCP:会显示“Needs login” → Login。 |
| VS Code (Copilot) | 命令面板 → MCP: Add Server → HTTP → https://mcp.tuncart.com/mcp → 名称 tunc-art → 允许登录提示。 |
| Gemini CLI | 加到 settings.json,然后运行 /mcp auth tunc-art。 |
| Copilot Studio | Tools → Add a tool → New tool → Model Context Protocol → URL 填 https://mcp.tuncart.com/mcp → Authentication 选 OAuth 2.0,Dynamic discovery。 |
只接受请求头的客户端改用 API 密钥。
没有浏览器的智能体
运行在服务器或终端里的智能体会给你一个代码和一个链接,例如 https://tuncart.com/connect?code=BCDF-GHJK。打开它,登录,确认代码一致后授权。任何支持设备授权(RFC 8628)的 OAuth 库都可以做:
# 每个智能体只需注册一次(不需要重定向地址)
curl -s https://core.tunc.ai/oauth/register -H 'content-type: application/json' \
-d '{"client_name":"report-writer","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"]}'
# → {"client_id":"dcr_…",…}
# 申请一个代码,把 verification_uri_complete 给对方看
curl -s https://core.tunc.ai/oauth/device_authorization -d client_id=dcr_… -d scope="orb.read art.read art.write" -d resource=https://mcp.tuncart.com/mcp
# → {"device_code":"…","user_code":"BCDF-GHJK",
# "verification_uri_complete":"https://tuncart.com/connect?code=BCDF-GHJK","interval":5,"expires_in":600}
# 每隔 interval 秒轮询一次,直到对方允许
curl -s https://core.tunc.ai/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d device_code=… -d client_id=dcr_…
# → 在此之前是 {"error":"authorization_pending"};允许之后:
# → {"access_token":"…","expires_in":900,"refresh_token":"…","scope":"…"}
# 在 access token 过期之前,用 refresh token 换一组新的
curl -s https://core.tunc.ai/oauth/token -d grant_type=refresh_token -d refresh_token=… -d client_id=dcr_…把 access token 作为 Authorization: Bearer 发送到 https://mcp.tuncart.com/mcp。每次刷新都会返回新的 refresh token:只保留最新的那个,重复使用旧的会把智能体断开。
A2A
支持 A2A 1.0 的智能体可以在 https://tuncart.com/.well-known/agent-card.json 找到 Tunc Art,并调用 https://a2a.tuncart.com。每条消息带一个数据部分,里面有 skill(一个 MCP 工具名,例如 art_read)和它的 arguments;返回值就是那个工具的结果。使用 API 密钥,或者用资源 https://a2a.tuncart.com 登录。
curl -s https://a2a.tuncart.com -H "Authorization: Bearer $TUNC_API_KEY" -H 'A2A-Version: 1.0' \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{
"messageId":"m-1","role":"ROLE_USER",
"parts":[{"data":{"skill":"art_read","arguments":{"operation":"list"}},"mediaType":"application/json"}]}}}'
# → {"jsonrpc":"2.0","id":1,"result":{"message":{"role":"ROLE_AGENT",
# "parts":[{"data":{…工具返回的结果…},"mediaType":"application/json"}],…}}}改名、更改权限或断开
每个智能体和密钥都列在 tunchub.com → 智能体与密钥,连同它的连接方式和它能做什么。可以改名,用“更改权限”收回权限(之后再需要时会重新询问你),或者断开:它会在一分钟内停止工作。 你的所有智能体共用你的 Personal 书架。
这些工具做什么
- art_write:保存任意类型的文件,最大 250 MiB。小文件直接内联(
text或content_base64,最大 8 MiB);更大的文件先用mode: "begin"拿到上传地址,PUT 字节,然后用mode: "complete"。返回值带着文件的artifact_id和它的私密链接。文件永远不会被覆盖:新版本就是一个新文件。 - art_read:
list查找文件,最新的在前,可以带title、mime_prefix、kind(image、pdf、workbook、presentation、document 等)、created_after、created_before和sort(newest、oldest、name、largest)。带get加include_content会返回里面的内容:文本按文本;PNG、JPEG、GIF 或 WebP 按图片;PDF 按每页的图片,一次四页(用pages选哪几页);Word、PowerPoint、OpenDocument、iWork 和邮件文件按文本;表格按sheet和range取文本;压缩包按成员列表,用part逐个读取;大照片按缩小后的图片。其他内容只要不超过 8 MiB,都以content_base64返回,offset和length可以读取任意大小文件的一部分。 - art_delete:删除你上传的文件。它的链接立刻失效,分享密码被关闭,而且无法撤销。
使用 API 密钥
创建 API 密钥,用你的 Tunc 账号在 tunchub.com 上创建。选择它可以做什么:读取 Tunc Orb(每个密钥都可以)、在 Tunc Orb 中保存与删除,以及打开、上传和删除 Tunc Art 文件。密钥只显示一次;放在系统的密钥管理里,永远不要写进提示词。随时可以在智能体与密钥里断开,它会在一分钟内停止工作。
一个密钥同时适用于两个 API:Tunc Orb 用 https://api.tuncorb.com,Tunc Art 用 https://api.tuncart.com。以 Authorization: Bearer <key> 的形式发送。
连接 MCP 客户端
Tunc Orb 的工具在 https://mcp.tuncorb.com/mcp,Tunc Art 的在 https://mcp.tuncart.com/mcp。把需要的那个加进去,密钥放在 Authorization 头里(替换 $TUNC_API_KEY):
Claude Code
claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp --header "Authorization: Bearer $TUNC_API_KEY"Cursor (mcp.json)
{
"mcpServers": {
"tunc-art": {
"url": "https://mcp.tuncart.com/mcp",
"headers": {
"Authorization": "Bearer $TUNC_API_KEY"
}
}
}
}VS Code (mcp.json)
{
"servers": {
"tunc-art": {
"type": "http",
"url": "https://mcp.tuncart.com/mcp",
"headers": {
"Authorization": "Bearer $TUNC_API_KEY"
}
}
}
}Gemini CLI (settings.json)
{
"mcpServers": {
"tunc-art": {
"httpUrl": "https://mcp.tuncart.com/mcp",
"headers": {
"Authorization": "Bearer $TUNC_API_KEY"
}
}
}
}OpenAI Responses API (tools)
{
"type": "mcp",
"server_label": "tunc-art",
"server_url": "https://mcp.tuncart.com/mcp",
"authorization": "$TUNC_API_KEY"
}权限不足的密钥调用工具时,工具错误会在 missing_scope 里指出缺哪一项;已断开的密钥返回 401。
直接调用 API
# Files you can open (paged)
curl -s "https://api.tuncart.com/v1/files?limit=20" -H "Authorization: Bearer $TUNC_API_KEY"
# Upload: start, send the bytes to upload.url, then complete
curl -s https://api.tuncart.com/v1/files \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name":"q4-report.pdf","mime_type":"application/pdf","byte_count":482113}'
# → {"artifact":{"id":"…",…},"upload":{"method":"PUT","url":"…","headers":{…},…}}
curl -s https://api.tuncart.com/v1/files/<id>/complete \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" -d '{"byte_count":482113}'
# Download, and delete a file your key uploaded
curl -s https://api.tuncart.com/v1/files/<id>/content -H "Authorization: Bearer $TUNC_API_KEY" -o q4-report.pdf
curl -s -X DELETE https://api.tuncart.com/v1/files/<id> -H "Authorization: Bearer $TUNC_API_KEY"curl -s https://api.tuncorb.com/v1/write \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"create","name":"hello","about":"first record",
"text":"Hello from my agent","mutation_id":"mut_'"$(openssl rand -hex 13)"'"}'
curl -s https://api.tuncorb.com/v1/read \
-H "Authorization: Bearer $TUNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"get","name":"hello"}'import os
import secrets
import requests
headers = {"Authorization": f"Bearer {os.environ['TUNC_API_KEY']}"}
# Tunc Orb:保存一条记录(每次变更一个 mutation_id,重试时复用同一个)
saved = requests.post("https://api.tuncorb.com/v1/write", headers=headers, json={
"operation": "create", "name": "hello", "about": "第一条记录",
"text": "来自我的智能体", "mutation_id": "mut_" + secrets.token_hex(13),
})
print(saved.json())
# Tunc Art:列出你的文件
print(requests.get("https://api.tuncart.com/v1/files", headers=headers).json())限制
- 合理使用:免费版每天 50,000 次 Tunc Orb 操作,付费存储为 500,000 次。读取、搜索和保存计入;删除和状态查询不计入。每天 UTC 零点重新计数。
- 每个智能体每秒:50 次读取、20 次保存、5 次搜索和 20 次其他调用。短时间突发没问题。
- Tunc Art:每个人每分钟 60 次上传,文件最大 250 MiB。
- 存储与 Tunc Hub、Tunc Orb、Tunc Art 共用;账号页会显示每个产品用了多少。
错误
| 代码 | 含义 | 存储相关字段 |
|---|---|---|
507 storage_limit | Tunc Orb:你的 Tunc 存储已满,所以保存被拒绝——在此之前,如果有 Tunc Art 文件,会先删掉最旧的来腾空间。读取和删除仍然可用。 | error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url |
409 storage_quota_exceeded | Tunc Art:即使删掉最旧的文件腾出空间,这次上传也放不下。 | quota_bytes, active_bytes, requested_bytes, 以及 storage,字段同上 |
429 rate_limited | 调用太多。等 details.retry_after_secs(Orb)或 Retry-After 头(两者)指定的时间。在 Orb 上,details.limit 会说明是哪一种限制:daily、某一类(read、write、search 或 control),或者同时登录的密钥太多时的 key_sign_in。 | — |
401 auth_required, not_connected | auth_required:缺少密钥或密钥无效。not_connected:密钥已断开或已过期,新建一个。对不接受的密钥,Tunc Art 返回 unauthenticated。 | — |
403 forbidden | 密钥没有这项权限。missing_scope 会指出是哪一个,例如 orb.write(Orb:error.details.missing_scope)。用该权限新建一个密钥。 | — |
Tunc Orb 的错误长这样:{"ok":false,"error":{"code":…,"message":…,"next_step":…,"details":{…}}};next_step 会说明接下来该做什么。存储满了靠重试永远解决不了:删掉不再需要的内容,或者在账号里增加存储。
用已登录的智能体调用 Tunc Core 的文件 API
已经登录过的智能体,或者你在 账号的连接页面用一个代码授权过的智能体,把它的 access token 发给 Tunc Core 的文件 API:
# Start an upload
curl -s https://core.tunc.ai/api/v1/art/files \
-H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{"display_name":"q4-report.pdf","mime_type":"application/pdf","byte_count":482113}'
# → {"artifact":{…},"upload":{"method":"PUT","url":"…","headers":{…},"expires_in_seconds":…}}
# Send the bytes to upload.url with upload.method and upload.headers, then:
curl -s https://core.tunc.ai/api/v1/art/files/<id>/complete \
-H "authorization: Bearer $TUNC_ACCESS_TOKEN" \
-H 'content-type: application/json' -d '{"byte_count":482113}'# Files you can access (paged; filters: title, mime_prefix, kind, created_after, created_before, sort, cursor, limit)
curl -s "https://core.tunc.ai/api/v1/art/files?limit=20" \
-H "authorization: Bearer $TUNC_ACCESS_TOKEN"
# One file's metadata, then its bytes (Range supported)
curl -s https://core.tunc.ai/api/v1/art/files/<id> -H "authorization: Bearer $TUNC_ACCESS_TOKEN"
curl -s https://core.tunc.ai/api/v1/art/files/<id>/content -H "authorization: Bearer $TUNC_ACCESS_TOKEN" -o q4-report.pdf存储
Tunc Art 和 Tunc Orb 共用一个账号的存储额度。账号的存储页会显示总量和每个产品的份额。每个文件最大 250 MiB;智能体通过 MCP 内联发送最多 8 MiB,更大的文件用预签名上传。给每个文件真实的媒体类型,它才能预览。
智能体保存的文件在免费版保留 30 天,付费存储保留 365 天,每个文件都会显示到期日。存储满时先删除最旧的文件,账号页会列出删掉了什么。
