SYSTEM
桌面智能创作助手(码字工具)|接口文档
src/content/notes/projects/02-接口文档.md 桌面智能创作助手(码字工具)|接口文档
文档版本:v2.0(重定位·激进瘦身)
包含:REST 接口、SSE 流式接口、SSE 事件定义、请求/响应样例、全局错误码、安全约束。 🔵v2.0 变更:产品重定位为码字工具 + AI 赋能;移除 FSM 对话主接口
/api/chat、写文件审批/api/chat/approval、文件片段预览/api/file/preview、会话管理/api/sessions/*、调试快照接口;新增文档管理、文档版本、AI 续写、AI 灵感、素材、导出等接口。 🔵SSE 事件白名单收敛为 3 种:token / error / complete(不再有 session / citation / agent_status / approval)。 重要安全约定:用户 API‑Key 全部放在 POST 请求体,不放在 HTTP Header;后端绝不持久化密钥;密钥只在单次请求内存;禁止写入日志。 本机接口鉴权:所有业务接口须携带X-Local-Token请求头(由后端启动写入本地文件、经 Electron 主进程注入渲染进程,永不经过 HTTP 传输);缺失或错误返回401 ERR-AUTH-001。 SSE 前端:不使用 EventSource,全部使用 fetch + ReadableStream。
1 全局约定
1.1 基础地址
开发环境与生产单机部署:http://localhost:8080(后端仅绑定 127.0.0.1)。
请求头鉴权(v2.0 新增):除健康探测与 GET /api/system/info 外,所有接口必须携带请求头 X-Local-Token: <token>。该 token 由后端启动时生成并写入应用数据目录下的本地文件,Electron 主进程读取后经 preload 注入渲染进程;后端不通过任何 HTTP 接口下发 token,token 也绝不放入请求体或日志。缺失或不匹配返回 401 ERR-AUTH-001。
Host 校验:后端仅接受 Host 为 localhost 或 127.0.0.1 的请求,其余一律拒绝(防 DNS rebinding)。
CORS:禁用 *;仅精确匹配 Electron 渲染进程来源——生产 file://(Origin: null)与开发 http://localhost:5173。
1.2 Content‑Type
- REST 普通接口:
application/json - SSE 流式接口:
text/event‑stream;返回 SSE 标准流data: {...}\n\n;data 内部为 JSON 字符串。
1.3 通用模型配置 modelConfig
所有需要调用大模型的接口请求体均携带
modelConfig:
{
"mode": "LOCAL | USER_PROVIDED_API",
"provider": "openai | deepseek | qwen",
"apiKey": "sk-xxxx",
"baseUrl": "https://api.example.com/v1",
"modelName": "gpt-4o",
"temperature": 0.7,
"maxTokens": 2048,
"useOnlineSearch": false
}
mode=LOCAL:provider/apiKey/baseUrl/modelName全部忽略;后端调用配置项ollama.base-url指定的 Ollama(宿主机127.0.0.1:11434/ 容器http://ollama:11434)。mode=USER_PROVIDED_API:必须提供apiKey、baseUrl、modelName;provider用于内置模板回填。temperature(可选):创意程度 0‑1;未传用默认值(0.7)。maxTokens(可选):单次生成最大 token;【单次生成字数】由前端换算后经提示词约束 + maxTokens 双重控制。useOnlineSearch(可选,默认 false):联网素材开关;开启后 AI 续写 / 快捷处理先调第三方搜索 API 补充素材,搜索未配置或失败返回ERR-SEARCH-001。
安全:
modelConfig.apiKey只存在单次请求内存;绝不落库、绝不写日志。
1.4 全局错误码
| 错误码 | 说明 | HTTP |
|---|---|---|
| 0 | 成功 | 200 |
| ERR-PARAM-001 | 请求参数非法 / 缺少必填字段 | 400 |
| ERR-AUTH-001 | 缺少或错误的本机令牌(X-Local-Token 校验失败) |
401 |
| ERR-MODEL-001 | Ollama 服务不可达;本地模式不可用 | 400 |
| ERR-MODEL-002 | 用户自有 API 配置缺失(需前往设置页填写密钥) | 400 |
| ERR-MODEL-003 | 调用第三方模型 API 失败(密钥错误 / 配额耗尽) | 400 |
| ERR-SEARCH-001 | 联网素材开关开启但搜索服务未配置 / key 失效 / 调用失败 | 400 |
| ERR-DOC-001 | 文档不存在 | 404 |
| ERR-VERSION-001 | 文档版本不存在 | 404 |
| ERR-CONFIG-001 | 配置文件解析失败;已回滚旧配置 | 400 |
| ERR-INTERNAL-001 | 服务内部异常(日志脱敏,返回友好提示,不返回堆栈) | 500 |
业务错误统一返回:
{ "code": "ERR-MODEL-002", "message": "请在设置页填入您自己的 API 密钥后重试。", "requestId": "uuid-xxx" }
1.5 SSE 事件总览(白名单 3 种)
| type | 说明 | 数据内容 |
|---|---|---|
| token | 模型输出文本增量 | {"type":"token","payload":"文本片段"} |
| error | SSE 通道内业务异常 | {"type":"error","payload":{"code":"ERR-MODEL-001","message":"友好提示"}} |
| complete | 本次流正常结束,SSE 流关闭 | {"type":"complete","payload":{}} |
流结束条件:
type=complete或type=error。
2 REST 接口
2.1 本地 Ollama 健康状态
GET /api/status/local-model
设置页健康检测:Ollama 服务连通性、对话模型存在状态。探测收敛为 3 状态(仅 HTTP 探测无法可靠区分”未安装 / 未启动”,两者合并)。
响应 200:
{
"statusEnum": "UNAVAILABLE | MODEL_MISSING | READY",
"ollamaReachable": true,
"targetModel": "qwen2.5:3b",
"modelExists": true,
"machineRamGB": 16,
"suggestModelList": [
{"model":"qwen2.5:1.5b","ramMin":4,"desc":"低配笔记本 CPU 运行"},
{"model":"qwen2.5:3b","ramMin":8,"desc":"推荐平衡,8G 内存以上"},
{"model":"qwen2.5:7b","ramMin":16,"desc":"16G+ 内存,独立显卡"}
],
"pullCommand": "ollama pull qwen2.5:3b",
"troubleshootHint": "如无法连接,请确认 Ollama 服务已启动(托盘骆驼图标)或安装。"
}
UNAVAILABLE:无法连接 Ollama 服务(未安装或未启动统一归此状态)。MODEL_MISSING:服务已连通,但对话模型未下载。READY:就绪,本地模式可用。- 拓扑说明:容器模式无法探测宿主机安装状态,
UNAVAILABLE引导文案隐藏”未安装”字样,只提示”无法连接”。 - 安全:健康探测接口不要求
X-Local-Token(供启动遮罩轮询使用)。
2.2 文档管理
GET /api/documents?genre=&keyword= # 文档列表(可按文体/关键词过滤)
POST /api/documents # 新建文档 {"title":"…","genre":"NOVEL|MEDIA|OFFICIAL|CUSTOM","content":"…"}
GET /api/documents/{id} # 文档详情(含正文)
PUT /api/documents/{id} # 保存正文/标题 {"title":"…","content":"…"}
DELETE /api/documents/{id} # 删除文档(级联删除版本)
内容格式约定:
content为 TipTap 富文本 HTML(前端editor.getHTML());AI 入参、字数统计、全文自检使用由content投影的纯文本(editor.getText());material.content仍为纯文本。
响应样例(列表):
{
"code": "0",
"data": [
{"id":1,"title":"第一章 初入异世","genre":"NOVEL","charCount":2840,"updatedAt":"2026-10-04T10:00:00Z"}
]
}
错误:ERR-DOC-001(文档不存在)、ERR-PARAM-001。
2.3 文档历史版本
GET /api/documents/{id}/versions # 版本列表
GET /api/documents/{id}/versions/compare?v1={vid}&v2={vid} # 双版本行级 diff
POST /api/documents/{id}/versions # 手动存版 {"content":"当前正文快照"}
POST /api/documents/{id}/versions/rollback # 回滚 {"versionId":123},回滚作为新版本追加
响应样例(列表):
{
"code": "0",
"data": {
"versions": [
{"id":3,"contentHash":"sha256-xxx","charCount":2840,"isCurrent":true,"createdAt":"2026-10-04T12:00:00Z"},
{"id":2,"contentHash":"sha256-yyy","charCount":2510,"isCurrent":false,"createdAt":"2026-10-04T11:30:00Z"}
]
}
}
doc_version按content_hash去重(内容未变不落新版本);回滚保留历史不可覆写;自动存版由前端在文档切离 / 退出时调用一次(防高频)。 错误:ERR-DOC-001、ERR-VERSION-001、ERR-PARAM-001。
2.4 文档导出
GET /api/documents/{id}/export?format=md|txt|word
Content-Disposition指定文件名;默认格式按文体:网文.txt/ 自媒体.md/ 公文.docx,前端可覆盖。word 由 Apache POI(XWPF)生成,仅做结构化基础排版(标题层级 + 段落),不承诺复杂样式 / 图文混排(v1.0 降级项);POI 生成失败返回 ERR-INTERNAL-001,用户可回退 txt/md。导出内容本地流转,不上传第三方。 错误:ERR-DOC-001、ERR-INTERNAL-001。
2.5 文体模板 / 提示词模板
GET /api/prompt-templates?genre=NOVEL # 模板列表(按文体过滤,可选)
POST /api/prompt-templates # 新建/更新 {"id":"可选","name":"写邮件","prompt":"…","genre":"NOVEL|MEDIA|OFFICIAL|CUSTOM","category":"WRITE|SUMMARY|MAIL|OTHER"}
DELETE /api/prompt-templates/{id} # 删除模板
内置网文 / 自媒体 / 公文三套文体模板为系统资源(
isSystem=true,只读);用户在其下新增自定义子模板;prompt不含密钥;入库前校验长度与格式。
响应样例(GET):
{
"code": "0",
"data": [
{"id":1,"name":"写邮件","prompt":"请根据以下要点撰写一封正式邮件:","genre":"OFFICIAL","category":"MAIL","isSystem":false,"createdAt":"…"}
]
}
2.6 素材收藏管理
GET /api/materials?genre=NOVEL # 素材列表(按文体过滤,可选)
POST /api/materials # 新建 {"genre":"NOVEL","kind":"QUOTE|CASE|PHRASE","content":"素材文本","source":"来源/备忘,可选"}
PUT /api/materials/{id} # 修改素材
DELETE /api/materials/{id} # 删除素材
素材按 genre 分栏归档;
kind区分金句 / 案例 / 专业表述;插入正文由前端实现(原样粘贴 content);content 为纯文本,不解析为指令。
响应样例(GET):
{
"code": "0",
"data": [
{"id":1,"genre":"OFFICIAL","kind":"PHRASE","content":"坚持问题导向、目标导向…","source":"写作规范","createdAt":"…"}
]
}
2.7 全文自检
POST /api/ai/check
规则引擎 + LLM 混合检查;普通 JSON 接口(非 SSE)。词级问题(重复用词 / 敏感词 / 口语化 / 格式)由后端规则引擎按 genre 检规判定;语义级问题(语句平淡 / 开头无吸引力 / 逻辑断层)由 ModelRouter 单轮判定。
请求体:
{
"genre": "NOVEL | MEDIA | OFFICIAL",
"content": "待检查全文",
"modelConfig": { "mode": "LOCAL" }
}
响应 200:
{
"code": "0",
"data": {
"issues": [
{"type":"REPEAT_WORD","severity":"MINOR","offsetStart":12,"offsetEnd":16,"original":"仿佛","suggestion":"可用 好像/宛如 替换","replacement":"宛如"},
{"type":"SENSITIVE","severity":"MAJOR","offsetStart":40,"offsetEnd":46,"original":"…","suggestion":"平台敏感词,建议替换","replacement":null},
{"type":"FLAT_BEGIN","severity":"MAJOR","offsetStart":0,"offsetEnd":30,"sentenceIndex":0,"suggestion":"开头缺乏吸引力,建议用悬念/冲突/反常识开场","replacement":null},
{"type":"LOGIC_GAP","severity":"MEDIUM","offsetStart":300,"offsetEnd":340,"sentenceIndex":8,"suggestion":"此处论证出现断层,缺少衔接","replacement":null}
],
"summary": "共发现 4 个问题,其中 1 个敏感词。"
}
}
offset为纯文本投影上的字符偏移(UTF‑16 code unit,即editor.getText()的偏移,非 HTML 偏移);前端负责”纯文本 offset ↔ TipTap/ProseMirror position”映射,替换后重取文本重建映射。语义级问题可返回sentenceIndex便于整句定位。
体裁检规对照:
| genre | 规则引擎(词级) | LLM(语义级) |
|---|---|---|
| NOVEL 网文 | REPEAT_WORD 重复用词、SENSITIVE 平台敏感词 | — |
| MEDIA 自媒体 | FLAT_WORD 平淡词标记 | FLAT_BEGIN 语句平淡 / 开头无吸引力 |
| OFFICIAL 公文 | INFORMAL 口语化词汇、FORMAT 格式不规范 | LOGIC_GAP 逻辑断层 |
2.8 系统基础信息
GET /api/system/info
返回版本、Spring Boot / Spring AI 版本等基础信息;不返回任何密钥、敏感配置。
3 SSE 流式接口
三个 AI 生成类接口均为 SSE,事件仅
token / error / complete;请求体除各自参数字段外统一携带modelConfig。
3.1 AI 续写
POST /api/ai/continue
依据光标上文语境续写正文;前端在光标处流式插入,可接受 / 撤销 / 重新生成。
请求体:
{
"genre": "NOVEL | MEDIA | OFFICIAL",
"context": "光标之前的正文(前端可截取合理长度)",
"targetWords": 300,
"modelConfig": { "mode": "LOCAL" }
}
返回(SSE):
data: {"type":"token","payload":"夜色如墨,他缓缓"}
data: {"type":"token","payload":"抬起头来……"}
data: {"type":"complete","payload":{}}
错误:ERR-MODEL-001/002/003、ERR-SEARCH-001(联网开关开启但搜索失败)、ERR-PARAM-001。
3.2 选中文字快捷处理
POST /api/ai/quick
对选中文本做单向处理,单轮调用;SSE 流式返回,前端默认原地替换选中段,可撤销。
请求体:
{
"operation": "expand | condense | restyle | wordcount",
"genre": "NOVEL | MEDIA | OFFICIAL",
"selectedText": "框选的段落文字",
"targetWords": 300,
"restyleTarget": "NOVEL_SLANG | MEDIA_HOOK | OFFICIAL_FORMAL",
"modelConfig": { "mode": "LOCAL" }
}
operation:expand扩写 /condense精简 /restyle换风格 /wordcount调篇幅。targetWords:wordcount目标字数(可选);restyleTarget:restyle目标风格(可选)。
返回(SSE):
data: {"type":"token","payload":"扩写后的文本..."}
data: {"type":"complete","payload":{}}
3.3 大纲生成
POST /api/ai/outline
按文体将零散关键点组织为 Markdown 层级大纲(
#/##/###),前端解析为可点击跳转的列表。
请求体:
{
"genre": "NOVEL",
"keyPoints": ["穿越到修仙大陆", "主角身份是废材", "金手指:识宝能力"],
"modelConfig": { "mode": "LOCAL" }
}
返回(SSE):
data: {"type":"token","payload":"## 第一章 初入异世\n"}
data: {"type":"token","payload":"### 1.1 身份揭露\n"}
data: {"type":"complete","payload":{}}
3.4 灵感建议
POST /api/ai/inspire
按主题 / 文体给出开头、标题、情节或论点建议,供用户挑选后插入正文。
请求体:
{
"genre": "MEDIA",
"topic": "职场新人如何高效汇报",
"aspect": "TITLE | OPENING | OUTLINE_IDEA",
"modelConfig": { "mode": "LOCAL" }
}
返回(SSE):同 token / complete 结构,逐条流式返回建议文本。
4 前端本地存储约定(Electron localStorage)
后端完全不感知、不读取这部分应用本地存储。
{
"backendBaseUrl": "http://localhost:8080",
"modelMode": "LOCAL | USER_PROVIDED_API",
"apiConfig": { "provider": "qwen", "apiKey": "sk-xxxx", "baseUrl": "xxx", "modelName": "qwen-max" },
"searchConfig": { "provider": "tavily", "apiKey": "tvly-xxx" },
"writingParams": { "temperature": 0.7, "maxTokens": 2048, "useOnlineSearch": false },
"modelPresets": { "NOVEL": {"...": "..."}, "OFFICIAL": {"...": "..."} },
"currentGenre": "NOVEL",
"writingCache": { "draft:{documentId}": {"content": "...", "updatedAt": "..."} },
"dayWordCount": "{yyyy-MM-dd}:12345",
"editorPrefs": { "theme": "dark|light|auto", "typewriter": false, "wordCountFloating": true },
"exportedAt": "2026-xx-xxTxx:xx:xxZ"
}
安全:apiKey 保存在应用本地 localStorage;导出 JSON 会包含密钥,提示用户妥善保管。写作参数 / 预设 / 缓存均仅存本机,不上传后端。
5 接口安全约束清单(必须遵守)
- ❌禁止将用户 apiKey 放入 HTTP 请求头;✅全部放在 POST 请求体
modelConfig。 - ❌禁止任何接口日志打印
modelConfig.apiKey;全局过滤器脱敏;所有日志打印点代码评审。 - ❌异常堆栈、返回报文禁止回显原始 apiKey。
- ✅SSE 事件严格白名单(token / error / complete);禁止透传原始模型输出直接作为指令执行。
- ✅素材 / 提示词等用户文本入库前校验长度与格式,content 不解析为指令(防 prompt 注入)。
- ✅Electron 主进程与渲染进程禁止
console.log打印任何 apiKey;代码评审所有 console 语句。 - ✅所有接口(健康探测与
GET /api/system/info除外)强制校验请求头X-Local-Token;token 由后端启动生成写入本地文件、经 Electron 主进程读取注入,不通过 HTTP 下发、不入日志、不入库;校验失败返回401 ERR-AUTH-001。 - ✅校验
Host头仅允许localhost / 127.0.0.1,拒绝其他 Host(防 DNS rebinding)。 - ✅CORS 禁用
*,仅精确匹配生产file://(Origin: null)与开发http://localhost:5173。
说明:以上为 v1.0 纵深防御手段;威胁模型仅覆盖”浏览器网页发起的跨页攻击”,不防御本机已存在的恶意程序。
6 常见调用流程示例
流程 A:写作 + AI 续写(本地 Ollama 模式)
- 设置页 GET
/api/status/local-model→statusEnum=READY,本地模式可选。 - 打开文档,编辑正文;前端防抖写入
writingCache防丢稿。(其余接口请求头统一携带X-Local-Token) - 光标处点击【续写】→ POST
/api/ai/continue,body 携带context+modelConfig(LOCAL)。 - 后端调用 Ollama,SSE 流式返回 token;前端在光标处插入,用户可撤销。
- 用户点【保存】→ PUT
/api/documents/{id}保存正文;可 POST.../versions存版。
流程 B:选中文字快捷处理(自有 API 模式)
- 设置页选 USER_PROVIDED_API 并填入密钥,存 localStorage。
- 框选正文 → 点击【扩写】→ POST
/api/ai/quick,body 携带selectedText+operation=expand+modelConfig(USER_PROVIDED_API)。 - 后端代理第三方 OpenAI 兼容接口,SSE 流式返回;前端原地替换选中段,可撤销。
流程 C:全文自检
- 点击【全文自检】→ POST
/api/ai/check,携带genre+content+modelConfig。 - 后端规则引擎 + LLM 返回问题列表;前端标红、悬浮替换词、一键替换。
7 附录:依赖与版本
- Spring Boot 3.5.x;Spring AI 1.x GA;JDK21。
- 版本说明:Spring AI 2.0 GA 基于 Spring Boot 4 基线(与 Boot 3 不兼容),本项目锁定 1.x GA。
- 数据层:SQLite(
org.xerial:sqlite-jdbc,MyBatis‑Plus 指定DbType.SQLITE)。v2.0 不再使用 Redis。 - 前端:Electron ≥28(Vue3 + Element Plus + TipTap/ProseMirror 编辑器内核)。
- Ollama API:原生 Ollama HTTP 接口;第三方模型:OpenAI 兼容 REST 协议。