proof

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Proof - Collaborative Markdown Editor

Proof - 协作式Markdown编辑器

Proof is a collaborative document editor for humans and agents. It supports two modes:

Web API - Create and edit shared documents via HTTP (no install needed)
Local Bridge - Drive the macOS Proof app via localhost:9847

Proof是一款面向人类和智能代理（Agent）的协作式文档编辑器。它支持两种模式：

Web API - 通过HTTP协议创建和编辑共享文档（无需安装）
本地桥接工具 - 通过localhost:9847驱动macOS版Proof应用

Web API (Primary for Sharing)

Web API（主要用于分享）

Create a Shared Document

创建共享文档

No authentication required. Returns a shareable URL with access token.

bash

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

Response format:

json

{
  "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"
  }
}

Use the

tokenUrl

as the shareable link. The

_links

give you the exact API paths.

无需身份验证。返回包含访问令牌的可分享URL。

bash

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

响应格式：

json

{
  "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路径。

Read a Shared Document

读取共享文档

bash

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

bash

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

Edit a Shared Document

编辑共享文档

All operations go to

POST https://www.proofeditor.ai/api/agent/{slug}/ops

Note: Use the

/api/agent/{slug}/ops

path (from

_links

in create response), NOT

/api/documents/{slug}/ops

Authentication for protected docs:

Header:

x-share-token: <token>

Authorization: Bearer <token>

Token comes from the URL parameter:
```
?token=xxx
```
or the
```
accessToken
```
from create response

Comment on text:

json

{"op": "comment.add", "quote": "text to comment on", "by": "ai:<agent-name>", "text": "Your comment here"}

Reply to a comment:

json

{"op": "comment.reply", "markId": "<id>", "by": "ai:<agent-name>", "text": "Reply text"}

Resolve a comment:

json

{"op": "comment.resolve", "markId": "<id>", "by": "ai:<agent-name>"}

Suggest a replacement:

json

{"op": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:<agent-name>", "content": "replacement text"}

Suggest a deletion:

json

{"op": "suggestion.add", "kind": "delete", "quote": "text to delete", "by": "ai:<agent-name>"}

Bulk rewrite:

json

{"op": "rewrite.apply", "content": "full new markdown", "by": "ai:<agent-name>"}

所有操作都需发送至

POST https://www.proofeditor.ai/api/agent/{slug}/ops

注意： 使用创建响应中

_links

字段提供的

/api/agent/{slug}/ops

路径，而非

/api/documents/{slug}/ops

。

受保护文档的身份验证：

请求头：

x-share-token: <token>

或

Authorization: Bearer <token>

令牌来自URL参数：
```
?token=xxx
```
或创建响应中的
```
accessToken
```
字段

添加文本评论：

json

{"op": "comment.add", "quote": "text to comment on", "by": "ai:<agent-name>", "text": "Your comment here"}

回复评论：

json

{"op": "comment.reply", "markId": "<id>", "by": "ai:<agent-name>", "text": "Reply text"}

标记评论为已解决：

json

{"op": "comment.resolve", "markId": "<id>", "by": "ai:<agent-name>"}

建议替换文本：

json

{"op": "suggestion.add", "kind": "replace", "quote": "original text", "by": "ai:<agent-name>", "content": "replacement text"}

建议删除文本：

json

{"op": "suggestion.add", "kind": "delete", "quote": "text to delete", "by": "ai:<agent-name>"}

批量重写：

json

{"op": "rewrite.apply", "content": "full new markdown", "by": "ai:<agent-name>"}

Known Limitations (Web API)

已知限制（Web API）

```
suggestion.add
```
with
```
kind: "insert"
```
returns Bad Request on the web ops endpoint. Use
```
kind: "replace"
```
with a broader quote instead, or use
```
rewrite.apply
```
for insertions.
Bridge-style endpoints (
```
/d/{slug}/bridge/*
```
) require client version headers (
```
x-proof-client-version
```
,
```
x-proof-client-build
```
,
```
x-proof-client-protocol
```
) and return 426 CLIENT_UPGRADE_REQUIRED without them. Use the
```
/api/agent/{slug}/ops
```
endpoint instead.

在Web操作端点使用
```
suggestion.add
```
且
```
kind: "insert"
```
会返回错误请求（Bad Request）。可改用
```
kind: "replace"
```
并扩大引用范围，或使用
```
rewrite.apply
```
来实现插入操作。
桥接风格的端点（
```
/d/{slug}/bridge/*
```
）需要客户端版本请求头（
```
x-proof-client-version
```
,
```
x-proof-client-build
```
,
```
x-proof-client-protocol
```
），若缺少这些头会返回426 CLIENT_UPGRADE_REQUIRED。请改用
```
/api/agent/{slug}/ops
```
端点。

Local Bridge (macOS App)

本地桥接工具（macOS应用）

Requires Proof.app running. Bridge at

http://localhost:9847

Required headers:

```
X-Agent-Id: claude
```
(identity for presence)
```
Content-Type: application/json
```
```
X-Window-Id: <uuid>
```
(when multiple docs open)

需要运行Proof.app。桥接地址为

http://localhost:9847

。

必填请求头：

```
X-Agent-Id: claude
```
（用于身份标识）
```
Content-Type: application/json
```
```
X-Window-Id: <uuid>
```
（当打开多个文档时需要）

Key Endpoints

核心端点

Method	Endpoint	Purpose
GET	`/windows`	List open documents
GET	`/state`	Read markdown, cursor, word count
GET	`/marks`	List all suggestions and comments
POST	`/marks/suggest-replace`	`{"quote":"old","by":"ai:<agent-name>","content":"new"}`
POST	`/marks/suggest-insert`	`{"quote":"after this","by":"ai:<agent-name>","content":"insert"}`
POST	`/marks/suggest-delete`	`{"quote":"delete this","by":"ai:<agent-name>"}`
POST	`/marks/comment`	`{"quote":"text","by":"ai:<agent-name>","text":"comment"}`
POST	`/marks/reply`	`{"markId":"<id>","by":"ai:<agent-name>","text":"reply"}`
POST	`/marks/resolve`	`{"markId":"<id>","by":"ai:<agent-name>"}`
POST	`/marks/accept`	`{"markId":"<id>"}`
POST	`/marks/reject`	`{"markId":"<id>"}`
POST	`/rewrite`	`{"content":"full markdown","by":"ai:<agent-name>"}`
POST	`/presence`	`{"status":"reading","summary":"..."}`
GET	`/events/pending`	Poll for user actions

请求方法	端点	用途
GET	`/windows`	列出已打开的文档
GET	`/state`	读取Markdown内容、光标位置、字数统计
GET	`/marks`	列出所有建议和评论
POST	`/marks/suggest-replace`	`{"quote":"old","by":"ai:<agent-name>","content":"new"}`
POST	`/marks/suggest-insert`	`{"quote":"after this","by":"ai:<agent-name>","content":"insert"}`
POST	`/marks/suggest-delete`	`{"quote":"delete this","by":"ai:<agent-name>"}`
POST	`/marks/comment`	`{"quote":"text","by":"ai:<agent-name>","text":"comment"}`
POST	`/marks/reply`	`{"markId":"<id>","by":"ai:<agent-name>","text":"reply"}`
POST	`/marks/resolve`	`{"markId":"<id>","by":"ai:<agent-name>"}`
POST	`/marks/accept`	`{"markId":"<id>"}`
POST	`/marks/reject`	`{"markId":"<id>"}`
POST	`/rewrite`	`{"content":"full markdown","by":"ai:<agent-name>"}`
POST	`/presence`	`{"status":"reading","summary":"..."}`
GET	`/events/pending`	轮询用户操作

Presence Statuses

在线状态

thinking

reading

idle

acting

waiting

completed

thinking

reading

idle

acting

waiting

completed

Workflow: Review a Shared Document

工作流：审阅共享文档

When given a Proof URL like

https://www.proofeditor.ai/d/abc123?token=xxx

Extract the slug (
```
abc123
```
) and token from the URL
Read the document state via the API
Add comments or suggest edits using the ops endpoint
The author sees changes in real-time

bash

undefined

当收到类似

https://www.proofeditor.ai/d/abc123?token=xxx

的Proof链接时：

从URL中提取slug（
```
abc123
```
）和令牌
通过API读取文档状态
使用操作端点添加评论或建议编辑
作者会实时看到更改

bash

undefined

Read

读取文档

curl -s "https://www.proofeditor.ai/api/agent/abc123/state"
-H "x-share-token: xxx"

Comment

添加评论

curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops"
-H "Content-Type: application/json"
-H "x-share-token: xxx"
-d '{"op":"comment.add","quote":"text","by":"ai:compound","text":"comment"}'

Suggest edit

建议编辑

curl -X POST "https://www.proofeditor.ai/api/agent/abc123/ops"
-H "Content-Type: application/json"
-H "x-share-token: xxx"
-d '{"op":"suggestion.add","kind":"replace","quote":"old","by":"ai:compound","content":"new"}'

undefined

undefined

Workflow: Create and Share a New Document

工作流：创建并分享新文档

bash

undefined

bash

undefined

1. Create

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. Extract URL and token

2. 提取URL和令牌

URL=$(echo "$RESPONSE" | jq -r '.tokenUrl') SLUG=$(echo "$RESPONSE" | jq -r '.slug') TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken')

3. Share the URL

3. 分享URL

echo "$URL"

4. Make edits using the ops endpoint

4. 使用操作端点进行编辑

curl -X POST "https://www.proofeditor.ai/api/agent/$SLUG/ops"
-H "Content-Type: application/json"
-H "x-share-token: $TOKEN"
-d '{"op":"comment.add","quote":"Content here","by":"ai:compound","text":"Added a note"}'

undefined

undefined

Safety

安全注意事项

Use
```
/state
```
content as source of truth before editing
Prefer suggest-replace over full rewrite for small changes
Don't span table cells in a single replace
Always include
```
by
```
field for attribution tracking

编辑前请以
```
/state
```
返回的内容作为可信来源
对于小范围更改，优先使用建议替换（suggest-replace）而非批量重写
替换操作不要跨表格单元格
始终包含
```
by
```
字段以跟踪操作归属