tapcanvas-api

TapCanvas API

这是 TapCanvas 项目对外 API 的唯一 skill。

目标：

• 为 TapCanvas 项目的公共接口提供唯一调用入口。
• 用一个统一配置文件管理 apiBaseUrl 和 apiKey。
• 明确失败，不做静默降级、不猜测默认接口、不切换到旧 skill。

唯一路径

涉及以下任一场景时，只能使用本 skill：

• 调用 /public/agents/chat
• 调用 /public/agents/tools/execute 读取或执行当前 Agents 工具面
• 调用 /public/draw
• 调用 /public/vision
• 调用 /public/video
• 调用 /public/tasks/result
• 调用 /public/flows 相关接口

禁止：

• 再使用分散的 TapCanvas API skill
• 在不同 skill 里各自维护一套 apiKey / apiBaseUrl
• 未经确认地改用其他 endpoint 或本地伪造结果

配置

必须读取同目录下的 config.json：

{
  "apiBaseUrl": "http://localhost:8788",
  "apiKey": "tc_sk_xxx"
}

字段说明：

• apiBaseUrl: TapCanvas API 域名或本地开发地址，不带尾部斜杠更清晰
• apiKey: 当前用户生成的 API Key

本地开发实例若已由 Hono 显式启用 TAPCANVAS_DEV_PUBLIC_BYPASS，诊断时可以额外传 --devBypassToken <token>。调用器只在该参数明确出现时发送 x-tap-dev-bypass，并且不会 同时发送 Bearer，以复现浏览器 HttpOnly 会话委托链；生产调用、普通 API Key 调用和 config.json 不会自动启用或保存 bypass。本地 Hono 未显式启用该 token 时请求会原地失败。

诊断已登录浏览器会话时，可以显式传 --sessionCookie <cookie>，或仅在当前进程设置 TAPCANVAS_SESSION_COOKIE；同时必须显式传 --origin <origin> 或设置 TAPCANVAS_SESSION_ORIGIN，以满足浏览器会话的 CSRF 来源校验。调用器只把这些值用于 本次请求，既不写入 config.json，也不与 Bearer 或 dev bypass 同时发送。会话或来源 无效时必须原样返回 401/403。

优先级：

1. 脚本参数显式传入
2. config.json
3. 环境变量 TAPCANVAS_API_BASE_URL / TAPCANVAS_API_KEY

鉴权方式互斥优先级：显式 dev bypass > 显式会话 Cookie > API Key。

如果最终缺少 apiBaseUrl 或 apiKey，必须直接失败。

执行方式

统一使用脚本：

node apps/agents-cli/skills/tapcanvas-api/scripts/call.mjs \
  --endpoint chat \
  --payload '{"vendor":"auto","prompt":"你好"}'

也支持 payload 文件：

node apps/agents-cli/skills/tapcanvas-api/scripts/call.mjs \
  --endpoint draw \
  --payloadFile /abs/path/request.json

本地开发诊断示例：

node apps/agents-cli/skills/tapcanvas-api/scripts/call.mjs \
  --endpoint chat \
  --apiBaseUrl http://127.0.0.1:8788 \
  --devBypassToken '<explicit-local-secret>' \
  --payload '{"prompt":"你好","stream":true}'

Endpoint 规则

可用 endpoint：

• chat -> POST /public/agents/chat
• agentTool -> POST /public/agents/tools/execute
• draw -> POST /public/draw
• vision -> POST /public/vision
• video -> POST /public/video
• taskResult -> POST /public/tasks/result
• flows -> GET /public/projects/:projectId/flows
• flowGet -> GET /public/flows/:id
• flowPatch -> POST /public/flows/:id/patch