AI Skills
ce-proof

ce-proof

熱門

在 Proof 中發布、閱讀、評論或編輯 Markdown。適用於產生 Proof 連結、分享規格書/計劃/草稿，或交接規劃工作流程的發布成果；請避免用於校對（proofread）、數學證明（math）、證據（evidence）或概念驗證（proof-of-concept）等語境。

2.4萬星標
1943分支
更新於 2026/8/3
獲取技能源代碼

相關技能

notion38萬network-config-validation24萬agent-security-manager7.2萬
SKILL.md
唯讀
名稱
ce-proof
描述

在 Proof 中發布、閱讀、評論或編輯 Markdown。適用於產生 Proof 連結、分享規格書/計劃/草稿，或交接規劃工作流程的發布成果；請避免用於校對（proofread）、數學證明（math）、證據（evidence）或概念驗證（proof-of-concept）等語境。

Proof - 協同 Markdown 編輯器

Proof 是一款供人類與 Agent 共同使用的協同文件編輯器。本 Skill 使用基於 https://www.proofeditor.ai 的託管式 Web API（HTTP/Bash）。若環境中已提供具備型別的 proof_* MCP 工具，請優先使用；否則請使用下方列出的 HTTP 操作說明。

身份識別與歸屬標記（Identity and Attribution）

對 Proof 文件進行的每一次寫入操作都必須標明歸屬。有兩個欄位用於攜帶 Agent 的身份資訊：

  • 機器 ID（每次操作中的 by 欄位與 X-Agent-Id 標頭）： ai:compound-engineering — 穩定、小寫且帶連字符、易於機器解析。會顯示於標記（marks）、事件（events）以及 API 的回應中。
  • 顯示名稱（POST /presence 請求中的 name 欄位）： Compound Engineering — 適合人類閱讀，會顯示於 Proof 的線上狀態標籤與評論作者徽章上。

每個文件工作階段（session）只需透過傳送 X-Agent-Id 標頭發布一次線上狀態即可設定顯示名稱；Proof 會在該工作階段中將顯示名稱與該 Agent ID 進行綁定。這些數值是呼叫本 Skill 時的預設值；若有獨立的子 Agent 需要擁有該文件，呼叫端亦可傳遞不同的 identity 配對。請勿使用 ai:compound 或其他隨意變體 — 除非呼叫端明確覆寫，否則身份應保持統一。

發布模式（Publish Mode）

最主要的用途是單向發布：取得現有的本機 Markdown 檔案（腦力激盪記錄、整合計劃、心得總結、草稿），讀取其完整內容並將其作為新文件的內文發布（請參閱「工作流程：建立並分享新文件」取得來源檔案的操作說明 — 切勿發布占位符內容），最後將可分享的 URL 提供給使用者。本機檔案仍為權威版本（canonical） — 發布操作不會將任何內容同步回磁碟。使用者可以開啟連結進行閱讀、評論並分享給他人；Agent 在取得該 URL 後，也能透過下方的編輯 API 參與協同作業。入口點有兩種，運作機制完全相同（請參閱「工作流程：建立並分享新文件」）：

  • 使用者直接要求 — 使用者直接以口頭語句指定本機 Markdown 檔案，並要求透過 Proof 分享：「把這個分享到 proof」、「發布這個到 proof」、「在 proof editor 中開啟這個讓我審閱」、「幫我拿這個文件的 proof 連結」。該檔案即為使用者剛建立、編輯或引用的 Markdown 檔案；若有歧義，請詢問使用者是指哪一個檔案。這是第一優先的入口點 — 不需要依賴上游呼叫端。
  • 上游 Skill 交接 — ce-brainstorm、ce-ideate 或 ce-plan 完成草稿後，明確傳遞檔案路徑與標題，交接給發布模式以供人工審閱。

僅限發布 Markdown 內容。若來源為 HTML 格式的整合計劃，請勿上傳至 Proof，而應改為傳回本機瀏覽器開啟的路徑。發布整合計劃時，若可確認準備狀態，請在標題加上標籤，例如：Plan: <title> (requirements-only) 或 Plan: <title> (implementation-ready)。

請勿在未告知的情況下默默用 Proof 連結替換受版本控制追蹤的專案文件。除非使用者明確同意，否則切勿將機密資訊、憑證、API 金鑰、私密 Token 或敏感個人資料上傳至 Proof。

憑證管理（Credentials）

建立文件時會傳回兩組權限不同的憑證：

  • accessToken — 日常使用的 Bearer 憑證，用於閱讀、編輯、線上狀態與事件。所有非所有者（non-owner）層級的 Agent API 呼叫皆使用此憑證。
  • ownerSecret — 僅限所有者權限使用（刪除及其他所有者層級的操作）。切勿將其作為日常 Bearer 憑證使用。

請在工作階段中分別儲存這兩組憑證（使用 shell 變數或等效的非專案記憶體）。切勿將 ownerSecret 或 accessToken 寫入受版本控制的檔案、提交紀錄（commits）或永久的專案日誌中。切勿在展示給使用者的 UI 文案中暴露 ownerSecret。

提供給人類時，請務必給予帶有 Token 的連結（tokenUrl），切勿單獨給予裸 URL /d/<slug> — 因為編輯器 Token 同時具備認領無所有者文件（ownerless docs）的能力。

在公開模式下建立的文件在尚未被已登入的 Every 使用者於瀏覽器中認領前均為無所有者狀態（帳號選單 → 認領所有權 Claim ownership）。一旦完成認領，ownerSecret 將永久撤銷；而 accessToken 則可繼續正常運作。認領完成後，刪除與其他所有者操作將歸屬於該 Every 帳號的所有者 — 請詢問所有者，或使用其 Every 所有者工作階段 Token。請勿使用已撤銷的 ownerSecret 重試刪除操作。

若收到 403 且 HTTP 回應包含 code: "DOCUMENT_DELETE_FORBIDDEN" 與 reason: "CREDENTIAL_NOT_OWNER"，或是帶入建立時的 ownerSecret 卻收到 401，即代表該 Secret 已被撤銷（通常是在認領之後）。請停止使用該 ownerSecret；並要求所有者進行刪除或提供 Every 所有者工作階段。

Web API

文件層面的身份驗證方式（優先順序如下）：

  • Authorization: Bearer <accessToken>
  • x-share-token: <accessToken>
  • 請求 URL 中的 ?token=<accessToken>

標準 Agent 讀寫介面（僅限 v3 — 請勿自行發明其他 Agent 修改路徑）：

  • 閱讀：GET /api/agent/<slug>/v3/document
  • 寫入：POST /api/agent/<slug>/v3/edit

建立分享文件

公開建立路由無需身份驗證。成功後會傳回帶有 Token 的可分享 URL。

curl -sS -X POST https://www.proofeditor.ai/share/markdown \
  -H "Content-Type: application/json" \
  -d '{"title":"My Doc","markdown":"# Hello\n\nContent here."}'

需要保留的回應欄位：

{
  "slug": "abc123",
  "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx",
  "accessToken": "xxx",
  "ownerSecret": "yyy",
  "shareUrl": "https://www.proofeditor.ai/d/abc123",
  "_links": {
    "read": "https://www.proofeditor.ai/api/agent/abc123/v3/document",
    "edit": { "method": "POST", "href": "/api/agent/abc123/v3/edit" },
    "delete": { "method": "DELETE", "href": "/api/documents/abc123" }
  }
}

請使用 tokenUrl 作為對外分享的連結。請立即擷取並儲存 slug、accessToken 與 ownerSecret — 當文件尚未被認領前，若需進行清理作業會需要使用 ownerSecret。

閱讀分享文件

若您已擁有 Proof 分享 URL，可透過內容交涉（content negotiation）或 v3 API 進行擷取：

curl -sS -H "Accept: application/json" "https://www.proofeditor.ai/d/{slug}?token=<token>"
curl -sS -H "Accept: text/markdown" "https://www.proofeditor.ai/d/{slug}?token=<token>"

curl -sS "https://www.proofeditor.ai/api/agent/{slug}/v3/document" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: ai:compound-engineering"
# -> { ok, revision, title, markdown, comments[], suggestions[], mutationReady? }

處於 ACTIVE 狀態的文件可無需 Token 直接透過 v3/document 進行閱讀。但修改、線上狀態與事件訂閱仍需帶有 Token 的憑證。無 Token 呼叫 GET /d/<slug> JSON 會回報 role: null 且不包含修改連結 — 這屬於真實的能力回報，並非瀏覽器鎖定。

v3 閱讀回應中的 comments[] 與 suggestions[] 是審閱狀態的來源。回覆、解決與取消解決時請使用評論的 id（reply / resolve / unresolve）。接受與拒絕時請使用修訂建議的 id（accept / reject）。v3 支援解決與取消解決評論；但不支援刪除評論。

當 mutationReady 為 false 時，revision 可能為 null — 此時請忽略 baseRevision 並於稍後重新閱讀。

編輯分享文件

傳送 { by, baseRevision?, operations: [...] } 至 POST /api/agent/{slug}/v3/edit。目標標的是 markdown 中的可見文字（並非原始 Markdown 語法，亦非區塊引用）。不需要基礎 Token。baseRevision（來自上次閱讀的整數）為選擇性的衝突防護 — 若省略則直接套用至最新版本（head）。Idempotency-Key 為選擇性標頭；重要寫入與重試時建議使用。

curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/v3/edit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "by":"ai:compound-engineering",
    "operations":[
      {"op":"replace","find":"old visible text","with":"new text"},
      {"op":"comment","on":"text to anchor on","body":"Is this still accurate?"}
    ]
  }'

內容操作（Content operations）：

op body
replace find, with（選擇性參數 occurrence / before / after）
insert after 或 before + markdown（錨點：引文、heading:Title、section:Title、"start" 或 "end"）
delete find
set_document markdown（以最小 diff 替換整份文件；對線上協作者十分安全）

審閱操作（Review operations）：

op body
comment on, body（選擇性參數 occurrence）
reply comment (id), body, 選擇性參數 resolve: true
resolve / unresolve comment (id)
suggest kind: "insert"|"delete"|"replace", find, with?（插入/替換時必需帶入 with）
accept / reject suggestion (id)

編輯策略

優先選擇影響範圍最小的操作：

  1. 逐字或特定範圍的內文修改 → replace / insert / delete
  2. 需要呈現可見的追蹤修訂 → suggest（隨後按需執行 accept/reject）
  3. 全文件替換 → 僅在使用者要求完整替換或變更無法以精確範圍表達時使用 set_document

若 find/錨點匹配到多個位置，伺服器將拒絕請求並傳回 TARGET_AMBIGUOUS 與 error.candidates — 此時不會變更任何內容。請使用 occurrence（"first"、"last" 或從 0 開始的索引）或 before/after 來消除歧義。切勿預設伺服器會靜默選擇第一個匹配項。

單一請求中的內容操作會以原子化（atomically）方式套用；審閱操作則會依序套用。若內容成功提交後審閱操作失敗，回應將會是 ok: false 並帶有 partial: true — 請重新閱讀並僅重試失敗的操作（使用相同的 Idempotency-Key 可安全地重複播放）。

錯誤回應格式為 { ok:false, error:{ code, message, retryable, opIndex?, target?, candidates?, current? } }。代碼包含：AUTH、NOT_FOUND、INVALID_REQUEST、TARGET_NOT_FOUND、TARGET_AMBIGUOUS、CONFLICT、TOO_LARGE、BUSY、PENDING、INTERNAL。

  • retryable: false — 請修正請求內容；切勿盲目重試
  • retryable: true 且帶有 error.current — 針對 current 重新定位目標並重試一次
  • TARGET_AMBIGUOUS — 依據 candidates 新增 occurrence / before / after
  • BUSY — 稍作退避延遲後重試
  • 確定的 200 且 ok:true — 檢查傳回的 revision / 文件內容；若內文完整即可直接進行鏈式操作，無需額外閱讀
  • 202 / PENDING — 寫入可能已提交；在連鎖執行下一操作或回報成功前，請先重新閱讀 v3/document

每次編輯成功後：請確認 ok:true，確認目標文字/評論/建議是否符合預期，隨後附上簡短摘要並提供 Proof 連結。

線上狀態（Presence）

curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/presence" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d '{"name":"Compound Engineering","status":"reading","summary":"Joining the doc"}'

常見狀態：reading、thinking、acting、waiting、completed、error。

文件標題

curl -sS -X PUT "https://www.proofeditor.ai/api/documents/{slug}/title" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"title":"Updated document title"}'

刪除文件

僅所有者憑證具備刪除權限：

curl -sS -X DELETE "https://www.proofeditor.ai/api/documents/{slug}" \
  -H "Authorization: Bearer <ownerSecret>"

檢視者、評論者與編輯者的 accessToken 無法執行刪除。成功時傳回 shareState: "DELETED"；後續閱讀將傳回文件已刪除的回應（許多路由會傳回 410）。

生命週期管理： 切勿在每次發布交接後自動刪除文件 — 供審閱的文件必須保留。請在工作階段中持久化保存 ownerSecret。僅在使用者要求移除/清理時，或是完成使用者明確指定為一次性的臨時草稿時才執行刪除。

標記與隱私（Marks and privacy）

清空 Markdown 內容（包括將 set_document 設定為空白/極簡內容）並不會清除評論標記。引文與評論欄位仍可透過 v3/document 被任何擁有分享憑證的人閱讀。在沒有所有者刪除權限的情況下，擦除內容並不算真正的隱私清理 — 請在文件尚未被認領前使用 ownerSecret 刪除文件，或在認領後請求所有者進行刪除。

<!-- truncated for translation batch; full body continues in source -->