Canvas 是做什麼的？
canvas.n3wth.com 是一個互動式 Markdown 編輯器，附帶渲染後的預覽功能，並以公開 slug 作為索引。當來源更新時，已開啟的分享頁面會自動重新渲染。
此技能透過已認證的 HTTP 代理 API 運作，無需瀏覽器。本檔案不包含機密資訊——呼叫端需從其自身環境提供 CANVAS_AGENT_TOKEN 和 Convex 站台基底 URL。
使用時機
- 建立一個可供其他人或代理開啟的共同工作介面
- 推送 Markdown 內容並回傳一個穩定的連結
- 原地更新現有畫布，讓已開啟的分頁自動重新渲染
- 編輯前讀取目前的來源內容
呼叫端必須具備的環境變數
| 變數 | 說明 |
|---|---|
CANVAS_SITE_URL | Convex HTTP 基底 URL，例如 https://.convex.site（結尾不要加斜線） |
CANVAS_AGENT_TOKEN | 共享的 bearer token，當部署環境有設定時使用 |
公開分享連結一律使用 https://canvas.n3wth.com/c/{slug}（而非 Convex 站台主機）。
認證： 如果在 Convex 部署上設定了 CANVAS_AGENT_TOKEN，則每個代理路由都需要 Authorization: Bearer $CANVAS_AGENT_TOKEN。如果 token 未設定（例如本機/開發環境），則相同的路由不需要此標頭——請在正式環境中設定 token。
API
每個可變動/讀取的代理路由都需要認證：
Authorization: Bearer $CANVAS_AGENT_TOKEN
Content-Type: application/json
探索性路由（無需認證）：
curl -sS "$CANVAS_SITE_URL/agent/v1"
1. 建立
curl -sS -X POST "$CANVAS_SITE_URL/agent/v1/canvases" \
-H "Authorization: Bearer $CANVAS_AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "我的畫布",
"source": "# 你好\n\n這是 **Markdown**。"
}'
回應包含 slug、url、version。請將 url 回傳給使用者——這是可以在 https://canvas.n3wth.com/c/{slug} 開啟的畫布。
2. 寫入來源
curl -sS -X PUT "$CANVAS_SITE_URL/agent/v1/canvases/$SLUG/source" \
-H "Authorization: Bearer $CANVAS_AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"source":"# 已更新\n\n這裡是新的內容。"}'
已經在 https://canvas.n3wth.com/c/$SLUG 開啟的分頁會自動重新渲染，無需重新整理。
3. 讀取目前來源
curl -sS "$CANVAS_SITE_URL/agent/v1/canvases/$SLUG" \
-H "Authorization: Bearer $CANVAS_AGENT_TOKEN"
4. 列表
curl -sS "$CANVAS_SITE_URL/agent/v1/canvases" \
-H "Authorization: Bearer $CANVAS_AGENT_TOKEN"
只回傳元資料（不包含來源主體）。
代理工作流程
- 確認您的環境中已設定
CANVAS_SITE_URL和CANVAS_AGENT_TOKEN（切勿將其提交到版本控制）。 - 使用可選的
title/source呼叫POST /agent/v1/canvases。 - 將回應中的
url（https://canvas.n3wth.com/c/{slug}）告知人類或其他代理。 - 在反覆修改的過程中，使用
PUT .../source進行更新。 - 若編輯前需要目前來源，可使用
GET .../canvases/{slug}。
錯誤
| 狀態碼 | 說明 |
|---|---|
| 401 | 缺少或錯誤的 bearer token（僅在部署環境有設定 CANVAS_AGENT_TOKEN 時發生） |
| 404 | 未知的 slug |
| 400 | 驗證失敗（來源大小、JSON 格式） |
來源大小限制：512 KiB 字元。
不包含的功能
無繪圖白板，也無第三方畫布產品。此 API 僅提供建立、寫入來源、讀取和列表功能。
可攜式安裝
將此資料夾複製到 skills.n3wth.com 或任何您的主機代理技能根目錄中，命名為 canvas/SKILL.md。透過 AGENTS.md 將代理指向該檔案。聯絡方式：[email protected]。GitHub：https://github.com/n3wth。