CLAP Web 接口

所有模型调用都经由服务商层，端点是 OpenAI 兼容的 HTTP API。 凭证只从环境变量（*_API_KEY / *_TOKEN / *_KEY）、 ~/.config/opencode/opencode.json、~/.pi/agent/auth.json 读入内存， 接口只返回掩码。

对话与模型

方法	路径	说明
GET	/api/models	按服务商分组的模型清单；含环境变量装配结果（env_assembly）、掩码凭证、可用性与默认选择。
POST	/api/chat	流式对话（SSE）。请求体 {"message","provider","model","branch","lane","grounded","zims","top_k","renew_summary","mode","message_id","lang"}； mode：send（新提问）、regenerate（对 message_id 重新回答，旧答案被替换）、 edit（用 message 改写该提问并重答）。 事件依次为 start →（有依据模式）sources → 若干 delta → done （含延迟、token 用量、来源清单、逐句核对结果 audit、错误）。 有依据模式下先检索 ZIM，检索不到材料时直接回答「来源未提及」，不调用模型。 界面支持中英日法俄德西葡意韩十种语言与浅色/深色/跟随系统三种主题。
POST	/api/chat/stop	暂停生成。请求体 {"stream_id"}；留空则暂停当前全部在跑的流。 已生成的文字会保留，会话中记为 error:"cancelled"。

会话

方法	路径	说明
GET	/api/session/get?branch=	当前会话：指定分支的消息（含共同主线）、分支、标注、续期记录。
POST	/api/session/new	新建空会话。
POST	/api/session/clear	一键清空当前对话（新建空会话并覆盖自动保存）。
POST	/api/session/delete_message	删除消息：{"id","cascade"}。cascade=false 只删这一条并把子消息接回上一级； true 删除这一条及之后。被其他分支共享的消息会拒绝删除。
POST	/api/session/save	保存为 v2 .clap。请求体 {"path"}。
POST	/api/session/load	加载 .clap（v1 自动无损迁移）。请求体 {"path"}。
GET	/api/session/export/download?format=&branch=	直接下载当前分支的导出文件（浏览器弹出保存位置）：md / html / json。
GET	/api/session/download	直接下载当前会话为 .clap 文件。
POST	/api/session/upload	从本机选择 .clap 文件加载会话（multipart file）。
GET	/api/session/share/download	直接下载 .clapshare 分享包。
GET	/api/annotate/download?format=csv|json	直接下载标注表。
POST	/api/session/fork	在某条消息处分叉。请求体 {"at","name","model","note"}。
POST	/api/session/export	导出当前分支。请求体 {"format":"md|html|json","branch","path"}； 返回 content 和写入的 path。HTML 是单文件，不引用任何外部资源。
POST	/api/session/share	打包成 .clapshare（不含密钥与本机路径）。
POST	/api/session/adopt	导入分享包。请求体 {"package","policy":"rename|overwrite|fork"}。
POST	/api/session/renew	会话续期：不调用模型，直接生成摘要（轮次、内容要点、标注）。返回 summary， 下一条对话会把它作为系统消息带上去。

ZIM 外置知识库

方法	路径	说明
GET	/api/zim/list	列出 CLAP_ZIM_ROOTS（默认 ~/Documents/重点文献）下的 ZIM：条目数、体积、语言、能否读取。
POST	/api/zim/search	{"query","zims","top_k"} → 结果 [{zim,path,title,snippet,score}]。 长问句会自动去掉疑问词，再按关键词分别检索后合并。
GET	/api/zim/article?zim=&path=	读取原文（把 HTML 转成纯文本），用于引用面板和阅读器。
POST	/api/zim/suggest	标题补全。请求体 {"prefix","zim","limit"}。

模型设置

方法	路径	说明
GET	/api/settings	服务商配置与默认模型；密钥永远只返回掩码。
POST	/api/settings/provider	手动配置服务商：{"id","base","key","models"}。 key 留空表示不修改；models 可写逗号分隔的模型 ID（留空则从端点自动获取）。
DELETE	/api/settings/provider/{id}	删除该服务商的本地配置。
POST	/api/settings/default	设置默认模型：{"provider","model"}。
POST	/api/settings/import	导入 JSON 配置（opencode / pi / CLAP 风格）：{"json": "…"}。 导入后密钥只写入本机配置文件（权限 0600），响应与界面只显示掩码。
POST	/api/settings/test	测试连接：{"id"} → 是否可用 + 模型清单。

标注与本地知识库

方法	路径	说明
POST	/api/annotate	请求体 {"target","kind","tags","note","author"}； kind 取 keypoint / question / generated / reviewed / error_fix / knowledge_point。
POST	/api/annotate/export	导出 CSV/JSON。请求体 {"path","format"}。
POST	/api/kb/index	上传文件并入库（multipart）。
POST	/api/kb/search	{"query","k"} 检索本地知识库。
GET	/api/kb/stats	本地知识库状态（分块数、目录）。
POST	/api/kb/clear	清空本地知识库。

页面

方法	路径	说明
GET	/	对话页：有依据模式、分支、标注、导出、分享、续期。
GET	/kb	知识库页：ZIM 列表、检索、原文阅读、分享包导入。
GET	/timeline?file=…	时间轴视图，渲染指定的 .clap 会话。
GET	/api-docs	本页。

CLAP Web API

Every model call goes through the provider layer, which speaks the OpenAI-compatible HTTP API. Credentials are read into memory only from environment variables (*_API_KEY / *_TOKEN / *_KEY), ~/.config/opencode/opencode.json and ~/.pi/agent/auth.json; the API only ever returns masked values.

Chat and models

Method	Path	Description
GET	/api/models	Models grouped by provider, with the environment assembly result (env_assembly), masked credentials, availability and the default selection.
POST	/api/chat	Streaming chat (SSE). Body {"message","provider","model","branch","lane","grounded","zims","top_k","renew_summary","mode","message_id","lang"}. mode: send (new question), regenerate (answer the user message message_id again; the previous answer is replaced), edit (replace that question with message and answer again). Events: start → (grounded mode) sources → delta… → done (latency, tokens, sources, the per-sentence check audit, and any error). In grounded mode the ZIM libraries are searched first; if nothing is found the reply is “the material does not mention it” and no model call is made. The interface ships ten languages (Chinese, English, Japanese, French, Russian, German, Spanish, Portuguese, Italian, Korean) and three theme modes (light, dark, system).
POST	/api/chat/stop	Pause generation. Body {"stream_id"}; omit it to pause every running stream. Text already produced is kept and stored as error:"cancelled".

Sessions

Method	Path	Description
GET	/api/session/get?branch=	Current session: messages of the chosen branch (including the shared main line), branches, annotations and renewals.
POST	/api/session/new	Start an empty session.
POST	/api/session/clear	Clear the current conversation in one click (new empty session, autosave overwritten).
POST	/api/session/delete_message	Delete a message: {"id","cascade"}. cascade=false removes only that node and reattaches its children to the parent; true removes it and everything after. Messages shared with another branch are refused.
POST	/api/session/save	Save as a v2 .clap file. Body {"path"}.
POST	/api/session/load	Load a .clap file (v1 files are migrated losslessly). Body {"path"}.
GET	/api/session/export/download?format=&branch=	Download the current branch directly (the browser asks where to save): md / html / json.
GET	/api/session/download	Download the current session as a .clap file.
POST	/api/session/upload	Load a session from a local .clap file (multipart file).
GET	/api/session/share/download	Download a .clapshare package directly.
GET	/api/annotate/download?format=csv|json	Download the annotation table directly.
POST	/api/session/fork	Fork a branch at a message. Body {"at","name","model","note"}.
POST	/api/session/export	Export the current branch. Body {"format":"md|html|json","branch","path"}; returns content and the written path. The HTML export is a single file with no external resources.
POST	/api/session/share	Pack into a .clapshare file (no credentials, no local paths).
POST	/api/session/adopt	Import a share package. Body {"package","policy":"rename|overwrite|fork"}.
POST	/api/session/renew	Session renewal: builds a summary without calling a model (turns, key content, annotations). The returned summary is carried as a system message with the next question.

External ZIM library

Method	Path	Description
GET	/api/zim/list	Lists the ZIM files under CLAP_ZIM_ROOTS (default ~/Documents/重点文献): entries, size, language, readability.
POST	/api/zim/search	{"query","zims","top_k"} → [{zim,path,title,snippet,score}]. Long questions are stripped of question words and searched term by term, then merged.
GET	/api/zim/article?zim=&path=	Read the original article (HTML converted to plain text) for the citation panel and reader.
POST	/api/zim/suggest	Title suggestions. Body {"prefix","zim","limit"}.

Model settings

Method	Path	Description
GET	/api/settings	Provider configuration and the default model; keys are only ever returned masked.
POST	/api/settings/provider	Configure a provider manually: {"id","base","key","models"}. An empty key keeps the stored one; models accepts comma-separated IDs (empty = fetch from the endpoint).
DELETE	/api/settings/provider/{id}	Remove that provider's local configuration.
POST	/api/settings/default	Set the default model: {"provider","model"}.
POST	/api/settings/import	Import a JSON document (opencode / pi / CLAP style): {"json": "…"}. Keys are written only to the local settings file (mode 0600); responses and the UI show a mask.
POST	/api/settings/test	Test a provider: {"id"} → availability and model list.

Annotations and the local knowledge base

Method	Path	Description
POST	/api/annotate	Body {"target","kind","tags","note","author"}; kind is one of keypoint / question / generated / reviewed / error_fix / knowledge_point.
POST	/api/annotate/export	Export CSV/JSON. Body {"path","format"}.
POST	/api/kb/index	Upload and index a document (multipart).
POST	/api/kb/search	Search the local knowledge base. Body {"query","k"}.
GET	/api/kb/stats	Local knowledge base status (chunks, directory).
POST	/api/kb/clear	Clear the local knowledge base.

Pages

Method	Path	Description
GET	/	Chat workspace: grounded mode, branches, annotations, export, share, renew.
GET	/kb	Knowledge page: ZIM list, search, original reading, share package import.
GET	/timeline?file=…	Timeline view rendered for a .clap session.
GET	/api-docs	This page.