← 返回学习路线

SYSTEM

桌面智能创作助手(码字工具)|接口文档

QuillAgent文档
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 接口安全约束清单(必须遵守)

  1. ❌禁止将用户 apiKey 放入 HTTP 请求头;✅全部放在 POST 请求体 modelConfig。
  2. ❌禁止任何接口日志打印 modelConfig.apiKey;全局过滤器脱敏;所有日志打印点代码评审。
  3. ❌异常堆栈、返回报文禁止回显原始 apiKey。
  4. ✅SSE 事件严格白名单(token / error / complete);禁止透传原始模型输出直接作为指令执行。
  5. ✅素材 / 提示词等用户文本入库前校验长度与格式,content 不解析为指令(防 prompt 注入)。
  6. ✅Electron 主进程与渲染进程禁止 console.log 打印任何 apiKey;代码评审所有 console 语句。
  7. ✅所有接口(健康探测与 GET /api/system/info 除外)强制校验请求头 X-Local-Token;token 由后端启动生成写入本地文件、经 Electron 主进程读取注入,不通过 HTTP 下发、不入日志、不入库;校验失败返回 401 ERR-AUTH-001。
  8. ✅校验 Host 头仅允许 localhost / 127.0.0.1,拒绝其他 Host(防 DNS rebinding)。
  9. ✅CORS 禁用 *,仅精确匹配生产 file://(Origin: null)与开发 http://localhost:5173。

说明:以上为 v1.0 纵深防御手段;威胁模型仅覆盖”浏览器网页发起的跨页攻击”,不防御本机已存在的恶意程序。

6 常见调用流程示例

流程 A:写作 + AI 续写(本地 Ollama 模式)

  1. 设置页 GET /api/status/local-model → statusEnum=READY,本地模式可选。
  2. 打开文档,编辑正文;前端防抖写入 writingCache 防丢稿。(其余接口请求头统一携带 X-Local-Token)
  3. 光标处点击【续写】→ POST /api/ai/continue,body 携带 context + modelConfig(LOCAL)。
  4. 后端调用 Ollama,SSE 流式返回 token;前端在光标处插入,用户可撤销。
  5. 用户点【保存】→ PUT /api/documents/{id} 保存正文;可 POST .../versions 存版。

流程 B:选中文字快捷处理(自有 API 模式)

  1. 设置页选 USER_PROVIDED_API 并填入密钥,存 localStorage。
  2. 框选正文 → 点击【扩写】→ POST /api/ai/quick,body 携带 selectedText + operation=expand + modelConfig(USER_PROVIDED_API)。
  3. 后端代理第三方 OpenAI 兼容接口,SSE 流式返回;前端原地替换选中段,可撤销。

流程 C:全文自检

  1. 点击【全文自检】→ POST /api/ai/check,携带 genre + content + modelConfig。
  2. 后端规则引擎 + 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 协议。