TUNC.AI / Tunc Art 文档

用 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 mobileCustomize → Connectors → Add custom connector → 名称填 Tunc Art,URL 填 https://mcp.tuncart.com/mcp → Add → Connect。免费版只允许一个自定义连接器;Team 和 Enterprise 由 Owner 在 Organization settings → Connectors 里添加。这个链接会打开对话框,名称和 URL 已经填好:
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Tunc%20Art&connectorUrl=https%3A%2F%2Fmcp.tuncart.com%2Fmcp
Claude Code先添加服务器,然后运行 /mcp,选择 tunc-art,再 Authenticate。
claude mcp add --transport http tunc-art https://mcp.tuncart.com/mcp
ChatGPTSettings → 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。
{
  "mcpServers": {
    "tunc-art": {
      "url": "https://mcp.tuncart.com/mcp"
    }
  }
}
VS Code (Copilot)命令面板 → MCP: Add Server → HTTP → https://mcp.tuncart.com/mcp → 名称 tunc-art → 允许登录提示。
Gemini CLI加到 settings.json,然后运行 /mcp auth tunc-art。
{
  "mcpServers": {
    "tunc-art": {
      "httpUrl": "https://mcp.tuncart.com/mcp"
    }
  }
}
Copilot StudioTools → 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_limitTunc Orb:你的 Tunc 存储已满,所以保存被拒绝——在此之前,如果有 Tunc Art 文件,会先删掉最旧的来腾空间。读取和删除仍然可用。error.details.storage: state, limit_bytes, used_bytes, orb_bytes, art_bytes, needed_bytes, manage_url
409 storage_quota_exceededTunc 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_connectedauth_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 天,每个文件都会显示到期日。存储满时先删除最旧的文件,账号页会列出删掉了什么。