Clip Pro

Clip 使用指南与 API

这里是 Clip 笔记与 Geometry 画板的使用指南。阅读说明后可直接打开 Clip 或 Geometry；自动化工具则应读取 OpenAPI 规范，以稳定地调用同一组接口。

打开 Clip 打开 Geometry 查看 OpenAPI JSON

面向人

写笔记、画图、整理推导

在 Clip 中写 Markdown、数学公式和 TikZ 图；在 Geometry 中编辑画板。想把画板放进笔记，先在 Geometry 点击“提交”，再使用其导出的完整 TikZ 代码块。

面向 AI / 程序

遵循规范直接调用

读取 /pro/openapi.json，发现笔记与画板 API。修改笔记必须先读取原文；Geometry 的 tikz 返回值必须逐字原样插入。

人工快速开始

1. 在 Clip 写作支持标题、列表、链接、表格、图片、公式与代码块。

2. 在 Geometry 绘图用控制点调整图形；完成后手动“提交”保存全部画板。

3. 合并到笔记复制或通过 API 取得画板完整 ```tikz 围栏，放进对应章节。

写作语法

数学

行内公式使用 $E=mc^2$ ；独立公式使用成对且独占行的 $$...$$。命令使用单个反斜杠，例如 \frac{a}{b}，不要将数学放进反引号。

TikZ 图

```tikz
\begin{tikzpicture}
  \draw (0,0) -- (2,1);
\end{tikzpicture}
```

围栏中只放完整的 tikzpicture，不要放 \documentclass、外部文件读写或 shell 命令。

Geometry 操作

画板支持 Shift 多选、移动、复制、左右/上下镜像、裁剪、延伸、分组和图层调整；颜色、线型和首尾箭头可批量设置。圆共用一个绘制入口，但生成两种元素：circle 只有边框，fill-circle 只有填充且没有边；椭圆、矩形、多边形及其他闭合 Path 使用通用填充模型。函数曲线以独立 function-curve 保存表达式、定义域和采样参数，往返时保持为 TikZ plot，不会烘焙为折线。

AI 修改画板时先读取能力接口和目标画板，再 PATCH 完整 workspace、最新 if_updated_at 及 export_tikz: true。服务端会生成并编译验证 TikZ，成功后在同一响应的 tikz 字段返回完整代码围栏。

TikZ 缓存

相同 TikZ 源码使用内容哈希复用已编译 SVG，缓存跨请求和服务重启保留；源码改变会自动生成新键。渲染响应提供 ETag、X-TikZ-Cache 和 X-TikZ-Cache-Key。需要重新校验同一源码时传 refresh: true，刷新失败不会破坏旧缓存。

只改一张插图时使用 PATCH /clip/api/notes/{id}/tikz/{index}；整篇强制重编译使用 POST /clip/api/notes/{id}/tikz/recompile，响应会返回采用新 SVG 的完整笔记 HTML。旧画板固定画布只在渲染时移除，不改写原始图源。

API 快速索引

GET /clip/api/notes/resolve?title=…按完整名称直接取得笔记 ID 与原始正文；重名时返回候选。

GET /clip/api/notes/search?q=…按名称片段轻量搜索，不渲染正文和 TikZ。

POST /clip/api/notes/merge/prepare按名称或 ID 批量取得原文及版本指纹。

POST /clip/api/notes/merge校验全部版本后写入整理结果；可显式清理来源。

PATCH /clip/api/notes/{id}提交完整 text；先读取并保留未修改内容。

GET /clip/api/geometry/capabilities读取全部基础图元、操作、显示字段和坐标引用规则。

GET/PATCH …/boards/{id}读取或回写完整结构化工作区；传 export_tikz: true 可直接获得新 TikZ。

GET …/boards/{id}/tikz取得完整、未改写的 TikZ Markdown 围栏。

给 AI 的必要约束

接口目前无鉴权。创建、修改和删除会直接影响 Clip 数据；删除不可恢复。AI 写入前应读取目标笔记、确认用户意图，并保留 title、note_type 及未要求修改的章节。导入 Geometry 时，禁止重新生成、格式化、拆分或删改 tikz 代码块中的图内信息。