Proof - 協調型マークダウンエディタ

Proof はヒューマンとエージェント向けの協調型ドキュメントエディタです。2 つのモードをサポートしています:

1. Web API - HTTP 経由で共有ドキュメントを作成・編集 (インストール不要)
2. ローカルブリッジ - macOS Proof アプリを localhost:9847 経由で操作

ID と属性

Proof ドキュメントへのすべての書き込みには属性が必要です。エージェントの ID は次の 2 つのフィールドで表現されます:

• マシンID (by は全ての操作に、X-Agent-Id ヘッダ): ai:compound-engineering — 安定した小文字ハイフン区切り、機械可読形式。マーク、イベント、API レスポンスに表示されます。
• 表示名 (name は POST /presence に): Compound Engineering — ユーザーが読める形式。Proof のプレゼンスチップやコメント作成者バッジに表示されます。

ドキュメントセッションごとに X-Agent-Id ヘッダを含めてプレゼンスに投稿し、表示名を 1 回設定します。Proof はそのセッション中、名前をエージェント ID にバインドします。これらの値はこのスキルの呼び出し元のデフォルトです。HITL レビュー (references/hitl-review.md) を実行する呼び出し元は、異なるサブエージェントがドキュメントを所有する場合、別の identity ペアを渡すことができます。ai:compound や他のアドホックなバリエーションは使用しないでください — 呼び出し元が明示的にオーバーライドしない限り、ID は一貫性を保ちます。

Human-in-the-Loop レビューモード

既存のローカルマークダウンファイルに対する human-in-the-loop イテレーション: Proof にアップロード、ユーザーが Proof の web UI で注釈を付ける、フィードバックをスレッド内返信と追跡された編集として取り込む、最終ドキュメントをディスクに同期します。2 つのエントリーポイント、同じメカニズム — 両方の場合について references/hitl-review.md で完全なループ仕様をロード (呼び出しコントラクト、マーク分類、べき等な取り込みパス、例外ベースの終端レポート、終端同期アトミック書き込み):

• ユーザーの直接リクエスト — ローカルマークダウンファイルに名前をつけ、Proof での協調イテレーションを求めるユーザーの単純なフレーズ: 「この部分を Proof に共有してイテレーションできるようにしてほしい」「このドキュメントを Proof でイテレーションしてほしい」「このファイルを Proof で HITL したい」「Proof でこのレビューをもらいたい」「このファイルを Proof エディタで開いてレビューさせてほしい」。ファイルはユーザーが最近作成、編集、または参照したマークダウンです。曖昧な場合は、どのファイルかを質問します。これはファーストクラスのエントリーポイント — アップストリーム呼び出し元を必要としません。
• アップストリームスキルハンドオフ — ce-brainstorm、ce-ideate、または ce-plan がドラフトを完成させ、次のフェーズの前に人間によるレビューのためにハンドオフします。ファイルパスとタイトルを明示的に渡します。

Web API (共有のプライマリ手段)

共有ドキュメントの作成

認証不要。アクセストークン付きの共有可能な URL を返します。

curl -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",
  "_links": {
    "state": "https://www.proofeditor.ai/api/agent/abc123/state",
    "ops": "https://www.proofeditor.ai/api/agent/abc123/ops"
  }
}

tokenUrl を共有リンクとして使用します。_links は正確な API パスを提供します。

共有ドキュメントの読み込み

curl -s "https://www.proofeditor.ai/api/agent/{slug}/state" \
  -H "x-share-token: <token>"

共有ドキュメントの編集

すべての操作は POST https://www.proofeditor.ai/api/agent/{slug}/ops に送信されます

注記: /api/agent/{slug}/ops パス (作成レスポンスの _links から) を使用してください。/api/documents/{slug}/ops ではありません。

保護されたドキュメントの認証:

• ヘッダ: x-share-token: <token> または Authorization: Bearer <token>
• トークンは URL パラメータから来ます: ?token=xxx または作成レスポンスの accessToken
• ヘッダ: X-Agent-Id: ai:compound-engineering (プレゼンスに必要; 一貫した属性化のため ops にも含める)

ワイヤー形式の注意。 /api/agent/{slug}/ops はトップレベルの type フィールドを使用します。/api/agent/{slug}/edit/v2 は operations 配列を使用し、各エントリは op を持ちます。混在させないでください — /ops に op を送信すると 422 が返されます。

すべての変更には baseToken が必要です。 最新の /state または /snapshot 読み取りから mutationBase.token を再利用します — トークンは秒単位で古くなることはなく、STALE_BASE は回復可能なエラーです。BASE_TOKEN_REQUIRED または STALE_BASE で、再読み込みして 1 回再試行してください。このセッションで以前の読み取りが行われていない場合のみ、変更前の読み取りを実行してください。references/hitl-review.md の baseToken レシピを参照してください。

/edit/v2 ブロック refs は別の問題です: リビジョン全体にわたってドリフトする可能性があるため、最後のスナップショット後に書き込みが行われた場合、ブロック編集前に新鮮な refs のため /snapshot を再フェッチしてください。

変更エラー後の再試行規律 — 再試行前に検証してください。 エラーレスポンスは何も書き込まれなかったことの証拠ではありません。

• STALE_BASE、BASE_TOKEN_REQUIRED、MISSING_BASE、INVALID_BASE_TOKEN — コミット前、トークン関連。/state を再読み込みして、同じペイロードと新鮮な baseToken で 1 回再試行します。汎用の mutate ヘルパーはこれらを自動再試行できます。
• ANCHOR_NOT_FOUND、ANCHOR_AMBIGUOUS — コミット前だが、quote がコンテンツとユニークに一致しなくなっています。再読み込みだけでは役に立ちません。呼び出し元は再試行前にアンカーを厳しくするか再生成する必要があります。むやみに自動再試行しないでください。
• INVALID_OPERATIONS、INVALID_REQUEST、INVALID_REF、INVALID_BLOCK_MARKDOWN、INVALID_RANGE、INVALID_MARKDOWN、422 — コミット前だが、ペイロードが間違っています。むやみに再試行しないでください。最初にペイロードを修正してください。
• COLLAB_SYNC_FAILED、REWRITE_BARRIER_FAILED、PROJECTION_STALE、INTERNAL_ERROR、5xx、ネットワークタイムアウト、および任意の collab.status: "pending" を持つ 202 — 呼び出しが失敗のように見えても、正規のドキュメントが書き込まれた可能性があります。再試行前に /state を再読み込みして、意図されたマーク/編集が既に存在するかチェックしてください。存在しない場合のみ再試行します。
• Idempotency-Key (以下を参照) は同じリクエストでの二重適用から保護します (例えば、TCP レベルの再試行)。新しいリクエストボディを構築して 2 番目の呼び出しを送信した場合は役に立ちません — それは新しい論理書き込みで新しいキーです。

重複マーク インシデントは通常、タイムアウト後に検証せずに comment.add または suggestion.add を再試行した場合に発生します。疑わしい場合: 再読み込み、差分、その後判断します。

Idempotency-Key ヘッダ は安全なオートメーション再試行のためすべての変更で推奨されます。/state.contract.idempotencyRequired が true の場合は必須です。同じ論理書き込み (同じペイロード) を再試行するときは同じキーを使用し、サーバーが再試行を組み合わせることができるようにします。新しいキーは新しい書き込みを意味します — ペイロードが同じであってもです。

テキストにコメント:

{"type": "comment.add", "quote": "text to comment on", "by": "ai:compound-engineering", "text": "Your comment here", "baseToken": "<token>"}

コメントへの返信:

{"type": "comment.reply", "markId": "<id>", "by": "ai:compound-engineering", "text": "Reply text", "baseToken": "<token>"}

コメントを解決/未解決:

{"type": "comment.resolve", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}
{"type": "comment.unresolve", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}

置換を提案 (保留中 — ユーザーが受け入れ/拒否する必要):

{"type": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:compound-engineering", "content": "replacement text", "baseToken": "<token>"}

提案して即座に適用 (追跡されるが確定済み — ユーザーは却下して元に戻せる):

{"type": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:compound-engineering", "content": "replacement text", "status": "accepted", "baseToken": "<token>"}

status: "accepted" は提案マークを作成して 1 回の呼び出しで変更を確定します。マークは編集ごとの属性と却下して元に戻す機能を持つ監査証跡として保持されます。kind: "insert" | "delete" | "replace" で動作します。

既存の提案を受け入れ/却下:

{"type": "suggestion.accept", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}
{"type": "suggestion.reject", "markId": "<id>", "by": "ai:compound-engineering", "baseToken": "<token>"}

suggestion.resolve はサポートされていません — 代わりに accept または reject を使用します。

一括書き換え (ドキュメント全体置換):

{"type": "rewrite.apply", "content": "full new markdown", "by": "ai:compound-engineering", "baseToken": "<token>"}

/edit/v2 経由のブロックレベル編集 (別のエンドポイント、別の形状):

curl -X POST "https://www.proofeditor.ai/api/agent/{slug}/edit/v2" \
  -H "Content-Type: application/json" \
  -H "x-share-token: <token>" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "by": "ai:compound-engineering",
    "baseToken": "mt1:<token>",
    "operations": [
      {"op": "replace_block", "ref": "b3", "block": {"markdown": "Updated paragraph."}},
      {"op": "insert_after", "ref": "b3", "blocks": [{"markdown": "## New section"}]}
    ]
  }'

操作ごとのボディ形状 (単数形 block vs 複数形 blocks は重要です — 間違った形式を送信すると 422 が返ります):

op	ボディフィールド
replace_block	ref, block: {markdown}
insert_after	ref, blocks: [{markdown}, ...]
insert_before	ref, blocks: [{markdown}, ...]
delete_block	ref
replace_range	fromRef, toRef, blocks: [{markdown}, ...]
find_replace_in_block	ref, find, replace, occurrence: "first" | "all"

/snapshot を読み込み、安定したブロック ref ID を取得します。operations はアトミックにコミットされます — すべての操作がランドするか、どの操作もランドしないか — したがって 1 つの /edit/v2 呼び出しは数十個のブロック編集を安全かつ効率的にバッチできます (references/hitl-review.md Phase 2.4 の一括スイープ ガイダンスを参照)。

クライアントが接続されている間の編集は問題ありません。 /edit/v2、suggestion.add (デフォルト status: "accepted" を含む)、およびすべてのコメント操作は能動的なコラボレーション中に機能します。rewrite.apply のみが LIVE_CLIENTS_PRESENT によってブロックされます — 飛行中の Yjs 編集を上書きします。

ループが壊れるとき。 変更が新鮮な読み込みと 1 回の再試行後も失敗し続けるか、読み込み間でステート が矛盾しているように見える場合、POST https://www.proofeditor.ai/api/bridge/report_bug に失敗したリクエスト ID、slug、生レスポンスを呼び出します。サーバーは充実させてイシューをファイルします。

既知の制限事項 (Web API)

• ブリッジスタイルのエンドポイント (/d/{slug}/bridge/*) はクライアントバージョンヘッダ (x-proof-client-version, x-proof-client-build, x-proof-client-protocol) を必要とし、それらなしで 426 CLIENT_UPGRADE_REQUIRED を返します。代わりに /api/agent/{slug}/ops を使用してください。

ローカルブリッジ (macOS アプリ)

Proof.app が実行されている必要があります。ブリッジは http://localhost:9847 です。

必須ヘッダ:

• X-Agent-Id: claude (プレゼンス用の ID)
• Content-Type: application/json
• X-Window-Id: <uuid> (複数のドキュメントが開いている場合)

キーエンドポイント

メソッド	エンドポイント	目的
GET	/windows	オープンドキュメントをリスト
GET	/state	マークダウン、カーソル、単語数を読み込む
GET	/marks	すべての提案とコメントをリスト
POST	/marks/suggest-replace	{"quote":"old","by":"ai:compound-engineering","content":"new"}
POST	/marks/suggest-insert	{"quote":"after this","by":"ai:compound-engineering","content":"insert"}
POST	/marks/suggest-delete	{"quote":"delete this","by":"ai:compound-engineering"}
POST	/marks/comment	{"quote":"text","by":"ai:compound-engineering","text":"comment"}
POST	/marks/reply	{"markId":"<id>","by":"ai:compound-engineering","text":"reply"}
POST	/marks/resolve	{"markId":"<id>","by":"ai:compound-engineering"}
POST	/marks/accept	{"markId":"<id>"}
POST	/marks/reject	{"markId":"<id>"}
POST	/rewrite	{"content":"full markdown","by":"ai:compound-engineering"}
POST	/presence	{"status":"reading","summary":"..."}
GET	/events/pending	ユーザーアクションをポール

プレゼンスステータス

thinking、reading、idle、acting、waiting、completed

ワークフロー: 共有ドキュメントをレビュー

https://www.proofeditor.ai/d/abc123?token=xxx のような Proof URL が与えられたとき:

1. URL から slug (abc123) とトークンを抽出
2. API 経由でドキュメントステートを読み込む
3. ops エンドポイントを使用してコメントを追加するか編集を提案
4. 作成者はリアルタイムで変更を見る

# 一度読み込み — 同じレスポンスは下記のすべての変更のドキュメントコンテンツと baseToken の両方をもたらします。
STATE=$(curl -s "https://www.proofeditor.ai/api/agent/abc123/state" \
  -H "x-share-token: xxx")
BASE=$(printf '%s' "$STATE" | jq -r '.mutationBase.token')
# 必要に応じてドキュメントフィールドを検査: printf '%s' "$STATE" | jq '.markdown, .revision'

# コメント
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \
  -H "Content-Type: application/json" \
  -H "x-share-token: xxx" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d "$(jq -n --arg base "$BASE" '{type:"comment.add",quote:"text",by:"ai:compound-engineering",text:"comment",baseToken:$base}')"

# 編集を提案 (追跡済み、保留中)
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \
  -H "Content-Type: application/json" \
  -H "x-share-token: xxx" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d "$(jq -n --arg base "$BASE" '{type:"suggestion.add",kind:"replace",quote:"old",by:"ai:compound-engineering",content:"new",baseToken:$base}')"

# 提案して即座に適用 (追跡済み、確定済み)
curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops" \
  -H "Content-Type: application/json" \
  -H "x-share-token: xxx" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d "$(jq -n --arg base "$BASE" '{type:"suggestion.add",kind:"replace",quote:"old",by:"ai:compound-engineering",content:"new",status:"accepted",baseToken:$base}')"

ワークフロー: 新しいドキュメントを作成して共有

# 1. 作成
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
  -H "Content-Type: application/json" \
  -d '{"title":"My Doc","markdown":"# Title\n\nContent here."}')

# 2. URL とトークンを抽出
URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
SLUG=$(echo "$RESPONSE" | jq -r '.slug')
TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')

# 3. プレゼンス経由で表示名をバインド
curl -s -X POST "https://www.proofeditor.ai/api/agent/$SLUG/presence" \
  -H "Content-Type: application/json" \
  -H "x-share-token: $TOKEN" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d '{"name":"Compound Engineering","status":"reading","summary":"Uploaded doc"}'

# 4. URL を共有
echo "$URL"

# 5. ops エンドポイントを使用して編集 (baseToken 必須)
BASE=$(curl -s "https://www.proofeditor.ai/api/agent/$SLUG/state" \
  -H "x-share-token: $TOKEN" | jq -r '.mutationBase.token')
curl -X POST "https://www.proofeditor.ai/api/agent/$SLUG/ops" \
  -H "Content-Type: application/json" \
  -H "x-share-token: $TOKEN" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d "$(jq -n --arg base "$BASE" '{type:"comment.add",quote:"Content here",by:"ai:compound-engineering",text:"Added a note",baseToken:$base}')"

ワークフロー: Proof Doc をローカルにプル

現在の Proof ドキュメントステートをローカルマークダウンファイルに同期します。以下によって使用されます:

• HITL レビューエンド同期 (references/hitl-review.md Phase 5) ドキュメントがローカルファイルから発生した場合
• Proof ドキュメントのアドホックスナップショットをディスクに (タブを閉じる前、アーカイブ、ハンドオフの前)
• ライブ Proof バージョンに対してローカルの作業コピーをリフレッシュ

SLUG=<slug>
TOKEN=<accessToken>
LOCAL=<absolute-path>

# 1 つの読み込みをテンプファイルへ — マークダウンを $(...) を通して渡すことを避け、末尾の改行を削除します。
STATE_TMP=$(mktemp)
curl -s "https://www.proofeditor.ai/api/agent/$SLUG/state" \
  -H "x-share-token: $TOKEN" > "$STATE_TMP"
REVISION=$(jq -r '.revision' "$STATE_TMP")

# アトミック書き込み: .markdown バイトをテンプシブリングに直接ストリーム、その後リネーム。
TMP="${LOCAL}.proof-sync.$$"
jq -jr '.markdown' "$STATE_TMP" > "$TMP" && mv "$TMP" "$LOCAL"
rm "$STATE_TMP"

jq -jr (-j 末尾改行なし、-r 生文字列) はマークダウンバイトをシェル変数を通さずに temp ファイルに直接ストリーミングするため、末尾の改行は無傷で保たれます。同じファイルシステム内の mv はアトミックです — クラッシュした書き込みは半分書き込まれたファイルではなく元の構造を残します。

pull が直接リクエストされていないときは書き込み前に確認します。 ワークフローが異なるアクション (例えば、HITL レビュー完了) の副作用として pull で終わる場合、「Sync reviewed doc to <localPath>?」のような短い確認で差し迫った書き込みを提示します。サイレント上書きは驚くべきことです — ユーザーはローカルファイルがセッションに存在することを忘れたか、Proof が明示的に pull を要求するまで正規版のままであると期待した可能性があります。

セーフティ

• 編集前にソース真実として /state コンテンツを使用
• アクティブなコラボレーション中は edit/v2 (直接ブロック変更) または suggestion.add (追跡される変更) を使用。誰かが接続しているときに LIVE_CLIENTS_PRESENT によってブロックされるため、rewrite.apply はクライアントなしのシナリオのために予約
• 単一の置換でテーブルセルにスパンしない
• すべての操作に by: "ai:compound-engineering" を、一貫した属性化のためヘッダに X-Agent-Id: ai:compound-engineering" を常に含める
• 最新の /state または /snapshot 読み込みから baseToken を再利用; STALE_BASE で再読み込みして 1 回再試行