2075 lines
56 KiB
Markdown
2075 lines
56 KiB
Markdown
# 微信 AI 助手 API 接口设计
|
||
|
||
> 依据当前 `src/` 页面字段、数据结构和交互设计。本文定义目标契约，不表示这些接口已经实现。
|
||
>
|
||
> 适用范围：单机 Windows、单个本地操作者、Tauri 桌面端、本机 SQLite 业务状态、本机 sidecar。默认不引入账号、租户、Workspace 或远程同步。
|
||
|
||
## 1. 设计结论
|
||
|
||
### 1.1 协议选择
|
||
|
||
| 场景 | 协议 | 原因 |
|
||
|---|---|---|
|
||
| 列表、详情、筛选、创建、更新、启停、删除、配置保存 | HTTP JSON | 一次请求对应一个确定结果，便于重试、校验、审计和错误处理 |
|
||
| 文件上传 | HTTP `multipart/form-data`；大文件使用分片 HTTP | WebSocket 不适合传二进制大文件；HTTP 更容易限制大小、校验哈希和断点续传 |
|
||
| 智能体测试流式回复 | WebSocket | 同一会话需要发送消息、接收 token 增量、完成或失败事件 |
|
||
| 蒸馏任务进度 | WebSocket | 后台任务跨页面持续运行，需要实时阶段和进度事件 |
|
||
| 引擎状态、启动检查、结构化日志 | WebSocket | 状态和日志持续产生，轮询会增加延迟和重复流量 |
|
||
| 知识文件解析状态 | WebSocket | PDF、DOCX、PPT/PPTX 的文本提取可能耗时；图片和视频只做上传、校验及预览，不做自动识别 |
|
||
| 标注截图、窗口选择、区域保存、桌面窗口控制 | Tauri IPC | 全程由本地 React/Tauri/Rust 处理，不进入 HTTP、WebSocket 或 Go 后端服务 |
|
||
| 主题、当前 Tab、临时弹窗状态 | 前端本地状态 | 纯 UI 状态，不进入业务 API |
|
||
|
||
### 1.2 服务地址
|
||
|
||
- HTTP：`http://127.0.0.1:8766/api/v1`
|
||
- WebSocket：`ws://127.0.0.1:8766/api/v1/ws?ticket={singleUseTicket}`
|
||
- 现有视觉预览服务使用 `127.0.0.1:8765`，业务 API 使用 `8766`，避免端口冲突。
|
||
- 服务必须只监听 loopback，不监听局域网地址。
|
||
|
||
### 1.3 安全边界
|
||
|
||
1. Tauri 启动 sidecar 时生成随机 `sessionToken`，HTTP 使用 `Authorization: Bearer {sessionToken}`。
|
||
2. WebSocket 不在 URL 中携带长期 token。前端先申请 30 秒有效、单次使用的 `ticket`。
|
||
3. 模型 API Key 进入系统密钥库；任何 GET 响应只返回 `keyConfigured`，不得返回明文或掩码后的原始值。
|
||
4. 日志禁止记录 API Key、完整系统提示词、无关聊天原文、剪贴板内容和本机绝对文件路径。
|
||
5. 所有资源更新使用 `revision` 做乐观并发控制；版本不匹配返回 `409 REVISION_CONFLICT`。
|
||
6. 删除知识库、智能体、员工等不可逆操作必须由前端二次确认，并在请求中传 `confirmation`。
|
||
|
||
---
|
||
|
||
## 2. 通用规范
|
||
|
||
### 2.1 数据格式
|
||
|
||
- JSON 字段统一使用 `camelCase`，与 React/Tauri 当前数据结构一致。
|
||
- 时间统一为 UTC RFC 3339，例如 `2026-07-21T08:30:15.238Z`。
|
||
- 文件大小统一为整数 `sizeBytes`，`KB/MB` 仅由前端格式化。
|
||
- 比率统一为 `0~1` 小数，例如 `successRate: 0.984`；分数使用 `0~100`。
|
||
- ID 不使用名称，建议前缀：`kb_`、`kv_`、`file_`、`agent_`、`employee_`、`distill_`、`test_`、`log_`。
|
||
- 列表使用 cursor 分页；页面当前数据量虽小，接口仍保持可扩展。
|
||
|
||
### 2.2 成功响应
|
||
|
||
```json
|
||
{
|
||
"data": {},
|
||
"meta": {
|
||
"requestId": "req_01J3...",
|
||
"nextCursor": null,
|
||
"total": 6
|
||
}
|
||
}
|
||
```
|
||
|
||
- 单资源接口可省略 `nextCursor` 和 `total`。
|
||
- `204 No Content` 用于成功删除且无响应体的场景。
|
||
|
||
### 2.3 错误响应
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "VALIDATION_ERROR",
|
||
"message": "请求字段校验失败",
|
||
"retryable": false,
|
||
"fieldErrors": {
|
||
"title": "知识标题不能为空"
|
||
},
|
||
"details": null
|
||
},
|
||
"requestId": "req_01J3..."
|
||
}
|
||
```
|
||
|
||
常用状态码和错误码：
|
||
|
||
| HTTP | code | 含义 |
|
||
|---:|---|---|
|
||
| 400 | `VALIDATION_ERROR` | 字段格式、枚举或业务前置条件错误 |
|
||
| 401 | `UNAUTHORIZED` | 本机 session token 无效或过期 |
|
||
| 404 | `NOT_FOUND` | 资源不存在或已删除 |
|
||
| 409 | `REVISION_CONFLICT` | 乐观锁版本冲突 |
|
||
| 409 | `STATE_CONFLICT` | 当前状态不允许该操作 |
|
||
| 413 | `FILE_TOO_LARGE` | 文件超过用途限制 |
|
||
| 415 | `UNSUPPORTED_FILE_TYPE` | 文件扩展名、MIME 或内容签名不受支持 |
|
||
| 422 | `FILE_PARSE_FAILED` | 文件上传成功但无法解析 |
|
||
| 429 | `RATE_LIMITED` | 模型或任务并发达到限制 |
|
||
| 500 | `INTERNAL_ERROR` | 未分类内部错误 |
|
||
| 502 | `MODEL_UPSTREAM_ERROR` | 模型供应商错误 |
|
||
| 504 | `MODEL_TIMEOUT` | 模型调用超时 |
|
||
|
||
### 2.4 列表参数
|
||
|
||
```text
|
||
?query=退款&status=enabled&type=file&limit=20&cursor=eyJpZCI6...
|
||
```
|
||
|
||
| 参数 | 类型 | 默认 | 说明 |
|
||
|---|---|---:|---|
|
||
| `query` | string | `""` | 名称、标签或正文关键字，最大 100 字 |
|
||
| `status` | string | `all` | 各资源定义的状态枚举 |
|
||
| `limit` | integer | 20 | `1~100` |
|
||
| `cursor` | string | 无 | 服务端返回的游标，不允许客户端解析 |
|
||
| `sort` | string | `updatedAt:desc` | 白名单排序字段与方向 |
|
||
|
||
### 2.5 幂等性
|
||
|
||
以下 POST 请求必须携带 `Idempotency-Key`：
|
||
|
||
- 创建知识库草稿、发布知识版本；
|
||
- 创建智能体、发送测试消息；
|
||
- 创建蒸馏任务、发布员工；
|
||
- 启动或停止引擎。
|
||
|
||
服务端在 24 小时内对相同 key 和相同请求体返回首次结果；同 key 不同请求体返回 `409 IDEMPOTENCY_CONFLICT`。
|
||
|
||
---
|
||
|
||
## 3. 核心数据对象
|
||
|
||
### 3.1 FileAsset
|
||
|
||
```json
|
||
{
|
||
"id": "file_01J3...",
|
||
"purpose": "knowledge_source",
|
||
"fileName": "refund-policy.pdf",
|
||
"contentType": "application/pdf",
|
||
"extension": "pdf",
|
||
"sizeBytes": 2516582,
|
||
"sha256": "6fe1...",
|
||
"kind": "text",
|
||
"status": "ready",
|
||
"parseStatus": "completed",
|
||
"extractedTextLength": 12680,
|
||
"convertedTextFileId": "filetxt_01J3...",
|
||
"warnings": [
|
||
{ "code": "EMBEDDED_IMAGES_SKIPPED", "message": "文档中的 3 张图片已省略" }
|
||
],
|
||
"error": null,
|
||
"previewStatus": "ready",
|
||
"description": null,
|
||
"descriptionSource": null,
|
||
"createdAt": "2026-07-21T08:30:15.238Z"
|
||
}
|
||
```
|
||
|
||
枚举：
|
||
|
||
- `purpose`: `knowledge_source | agent_test_attachment | distill_source | report_export`
|
||
- `kind`: `text | image | video | binary`
|
||
- `status`: `uploading | uploaded | processing | ready | failed | deleted`
|
||
- `parseStatus`: `not_required | queued | processing | completed | failed`
|
||
- `previewStatus`: `none | processing | ready | failed`
|
||
- `descriptionSource`: 当前只允许 `manual | null`，禁止返回 `ai | ocr | vision`
|
||
|
||
图片或视频知识文件示例：
|
||
|
||
```json
|
||
{
|
||
"id": "file_01J4...",
|
||
"purpose": "knowledge_source",
|
||
"fileName": "refund-process.png",
|
||
"contentType": "image/png",
|
||
"extension": "png",
|
||
"sizeBytes": 356240,
|
||
"sha256": "7a2d...",
|
||
"kind": "image",
|
||
"status": "ready",
|
||
"parseStatus": "not_required",
|
||
"extractedTextLength": 0,
|
||
"convertedTextFileId": null,
|
||
"warnings": [],
|
||
"error": null,
|
||
"previewStatus": "ready",
|
||
"description": "退款申请、审核和到账三个步骤的流程图。",
|
||
"descriptionSource": "manual",
|
||
"createdAt": "2026-07-21T08:31:15.238Z"
|
||
}
|
||
```
|
||
|
||
### 3.2 KnowledgeSummary
|
||
|
||
```json
|
||
{
|
||
"id": "kb_refund",
|
||
"title": "售后常见问题与退款边界",
|
||
"type": "file",
|
||
"tags": ["售后", "退款"],
|
||
"status": "enabled",
|
||
"currentVersion": "v1.7",
|
||
"referenceCount": 82,
|
||
"fileCount": 4,
|
||
"updatedAt": "2026-06-05T01:42:00Z",
|
||
"revision": 7
|
||
}
|
||
```
|
||
|
||
- `type`: `file | image | video | mixed`
|
||
- `status`: `draft | processing | enabled | disabled | failed`
|
||
|
||
### 3.3 AgentSummary
|
||
|
||
```json
|
||
{
|
||
"id": "agent_intent",
|
||
"name": "客户意图识别",
|
||
"type": "builtin",
|
||
"enabled": true,
|
||
"version": "v2.1",
|
||
"tags": ["线索分级", "异议判断", "下一步建议"],
|
||
"knowledgeCount": 3,
|
||
"recentCallCount": 16,
|
||
"lastTestStatus": "passed",
|
||
"updatedAt": "2026-06-16T10:20:00Z",
|
||
"revision": 4
|
||
}
|
||
```
|
||
|
||
- `type`: `builtin | custom`
|
||
- `lastTestStatus`: `not_run | running | passed | failed`
|
||
|
||
### 3.4 DistillJobSummary
|
||
|
||
```json
|
||
{
|
||
"id": "distill_01J3...",
|
||
"name": "销售冠军 Aileen 话术蒸馏",
|
||
"state": "extracting",
|
||
"stage": "strategy_extraction",
|
||
"progress": 0.72,
|
||
"estimatedRemainingSeconds": 180,
|
||
"sourceCount": 1,
|
||
"successCount": 248,
|
||
"failedCount": 7,
|
||
"createdAt": "2026-07-21T08:30:15.238Z",
|
||
"updatedAt": "2026-07-21T08:34:10.000Z",
|
||
"revision": 9
|
||
}
|
||
```
|
||
|
||
- `state`: `draft | queued | extracting | evaluating | ready_to_publish | completed | cancelled | failed`
|
||
- `stage`: `source_validation | data_cleaning | scene_clustering | strategy_extraction | boundary_induction | counterexample_generation | evaluation | completed`
|
||
|
||
### 3.5 EmployeeSummary
|
||
|
||
```json
|
||
{
|
||
"id": "employee_1",
|
||
"name": "销售冠军 Aileen",
|
||
"version": "v3.2",
|
||
"enabled": true,
|
||
"traits": ["高意向逼单", "异议拆解", "温和推进"],
|
||
"domain": "private_sales",
|
||
"score": 96,
|
||
"weeklyCallCount": 28,
|
||
"updatedAt": "2026-06-18T09:00:00Z",
|
||
"revision": 3
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 应用初始化与实时连接
|
||
|
||
### 4.1 获取启动数据
|
||
|
||
`GET /bootstrap`
|
||
|
||
请求：无 body。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"apiVersion": "1.0",
|
||
"serverVersion": "0.1.0",
|
||
"platform": "windows",
|
||
"capabilities": {
|
||
"knowledge": true,
|
||
"agents": true,
|
||
"distillation": true,
|
||
"engine": true,
|
||
"nativeAnnotation": true
|
||
},
|
||
"engineState": {
|
||
"lifecycle": "idle",
|
||
"autoSendPaused": false,
|
||
"annotationComplete": true,
|
||
"updatedAt": "2026-07-21T08:30:15.238Z"
|
||
},
|
||
"badges": {
|
||
"clone": 3,
|
||
"knowledge": 0,
|
||
"agents": 1,
|
||
"distill": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
用途：主窗口一次请求获得能力开关、引擎初始状态和底部 Tab badge。主题仍存本地，不进入接口。
|
||
|
||
### 4.2 申请 WebSocket ticket
|
||
|
||
`POST /realtime-tickets`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"clientId": "desktop-main-7cb8",
|
||
"lastEventId": "evt_01J3...",
|
||
"subscriptions": ["engine", "logs", "distill:distill_01J3", "files:file_01J3"]
|
||
}
|
||
```
|
||
|
||
字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---:|---|
|
||
| `clientId` | string | 是 | 每个窗口唯一，最大 64 字 |
|
||
| `lastEventId` | string/null | 否 | 断线续传起点 |
|
||
| `subscriptions` | string[] | 否 | 初始订阅频道，最多 50 个 |
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"ticket": "wst_01J3...",
|
||
"webSocketUrl": "ws://127.0.0.1:8766/api/v1/ws?ticket=wst_01J3...",
|
||
"expiresAt": "2026-07-21T08:30:45.238Z",
|
||
"heartbeatSeconds": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 微信分身、引擎与日志
|
||
|
||
### 5.1 引擎状态
|
||
|
||
`GET /engine/state`
|
||
|
||
响应 `EngineState`：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"lifecycle": "running",
|
||
"agent": "running",
|
||
"visionStream": "running",
|
||
"wechatWindow": "connected",
|
||
"annotationComplete": true,
|
||
"autoSendPaused": false,
|
||
"activeConversationId": null,
|
||
"consecutiveErrors": 0,
|
||
"lastError": null,
|
||
"startedAt": "2026-07-21T08:30:15.238Z",
|
||
"updatedAt": "2026-07-21T08:30:18.000Z",
|
||
"revision": 12
|
||
}
|
||
}
|
||
```
|
||
|
||
枚举：
|
||
|
||
- `lifecycle`: `idle | checking | starting | running | stopping | error`
|
||
- `agent` / `visionStream`: `stopped | starting | running | error`
|
||
- `wechatWindow`: `unknown | connected | missing | changed`
|
||
|
||
### 5.2 执行启动检查
|
||
|
||
`POST /engine/startup-checks`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{ "forceRefresh": true }
|
||
```
|
||
|
||
响应 `202 Accepted`：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"runId": "check_01J3...",
|
||
"state": "running",
|
||
"checks": [
|
||
{ "id": "config", "label": "基础配置", "status": "waiting", "passed": null, "detail": null },
|
||
{ "id": "annotation", "label": "界面标注", "status": "waiting", "passed": null, "detail": null },
|
||
{ "id": "window", "label": "微信窗口连接情况", "status": "waiting", "passed": null, "detail": null }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
后续通过 `engine.startup_check.updated` WS 事件返回逐项状态；最终结果也可通过 `GET /engine/startup-checks/{runId}` 查询。
|
||
|
||
### 5.3 启动引擎
|
||
|
||
`POST /engine/start`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"startupCheckRunId": "check_01J3...",
|
||
"expectedRevision": 12
|
||
}
|
||
```
|
||
|
||
响应 `202 Accepted`：返回最新 `EngineState`。若检查未通过，返回 `409 STARTUP_CHECK_FAILED`，`details.failedCheckIds` 指明失败项。
|
||
|
||
### 5.4 停止引擎
|
||
|
||
`POST /engine/stop`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{ "expectedRevision": 13, "reason": "operator_request" }
|
||
```
|
||
|
||
响应 `202 Accepted`：返回 `lifecycle: "stopping"` 的 `EngineState`，最终状态通过 WS 推送。
|
||
|
||
### 5.5 暂停或恢复自动发送
|
||
|
||
`PATCH /engine/auto-send`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{ "paused": true, "expectedRevision": 14 }
|
||
```
|
||
|
||
响应：返回最新 `EngineState`。当前界面的“暂停自动发送/恢复自动发送”直接绑定此接口。
|
||
|
||
### 5.6 日志列表
|
||
|
||
`GET /logs?level=warning&module=model&query=req_91fa&limit=100&cursor=...`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": "log_01J3...",
|
||
"time": "2026-07-21T08:30:15.238Z",
|
||
"level": "warning",
|
||
"module": "model",
|
||
"message": "model gateway latency is higher than expected",
|
||
"requestId": "req_91fa",
|
||
"context": {
|
||
"fromSnapshotId": "snapshot_9821",
|
||
"toSnapshotId": "snapshot_9822"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"meta": { "requestId": "req_...", "nextCursor": null, "total": 1 }
|
||
}
|
||
```
|
||
|
||
- `level`: `info | warning | error`
|
||
- `module`: `agent | vision | capture | retriever | model | policy | sender`
|
||
|
||
暂停接收仅停止当前窗口的 WS 消费，不调用后端、不暂停引擎。清空视图只清前端缓存，不删除审计日志。
|
||
|
||
### 5.7 导出日志
|
||
|
||
`POST /logs/exports`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"filter": { "level": "all", "module": "all", "query": "" },
|
||
"format": "jsonl",
|
||
"from": "2026-07-20T00:00:00Z",
|
||
"to": "2026-07-21T23:59:59Z"
|
||
}
|
||
```
|
||
|
||
响应 `202 Accepted`：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"exportId": "export_01J3...",
|
||
"status": "processing",
|
||
"fileId": null
|
||
}
|
||
}
|
||
```
|
||
|
||
完成后发送 `export.completed`，payload 中提供 `fileId`；前端调用 `GET /files/{fileId}/content` 下载。
|
||
|
||
---
|
||
|
||
## 6. 文件上传、解析与预览
|
||
|
||
### 6.1 用途限制
|
||
|
||
| purpose | 支持格式 | 单文件限制 | 数量限制 |
|
||
|---|---|---:|---:|
|
||
| `agent_test_attachment` | PDF、DOCX、PPT、PPTX、TXT、MD、CSV、JSON | 20 MB | 每条消息最多 5 个 |
|
||
| `knowledge_source` | TXT、PDF、DOCX、PPT、PPTX、PNG、JPG/JPEG、GIF、WEBP、MP4、WEBM、MOV | 文档/图片 100 MB；视频 2 GB | 每个草稿最多 100 个 |
|
||
| `distill_source` | TXT、MD、CSV、JSON、PDF、DOCX、PPT、PPTX | 500 MB | 每个任务最多 50 个 |
|
||
|
||
服务端必须同时校验扩展名、MIME 和文件头；不能只信任浏览器提交的 `contentType`。
|
||
|
||
知识文件首期处理边界：
|
||
|
||
1. TXT 按 UTF-8 规范化保存；PDF 只提取已有文本层；DOCX 提取段落和表格文字；PPT/PPTX 提取文本框、表格和备注文字。
|
||
2. 文档中的嵌入图片直接省略，不调用 OCR、视觉模型或图片理解。
|
||
3. 图片和视频可以作为独立知识来源上传、保存和预览，但不执行 OCR、图片理解、视频理解、ASR、关键帧提取或自动摘要。
|
||
4. 图片和视频的 `description` 只能由操作者人工填写，`descriptionSource` 固定为 `manual`；后端不得自动生成或补全描述。
|
||
5. 媒体文件有人工描述时，知识检索只索引标题、标签和人工描述；没有描述时只索引标题和标签，原始媒体内容不进入文本检索。
|
||
6. 扫描版 PDF 或只有图片、没有可提取文字的 Office 文档返回 `422 NO_EXTRACTABLE_TEXT`，不能标记为文档转换成功。
|
||
7. 文档转换结果生成独立 UTF-8 `.txt` 文件，并通过 `convertedTextFileId` 关联原文件；知识版本正文由转换后的 TXT 和媒体人工描述组成。
|
||
|
||
### 6.2 小文件直接上传
|
||
|
||
`POST /files`
|
||
|
||
Content-Type：`multipart/form-data`
|
||
|
||
表单字段：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---:|---|
|
||
| `file` | binary | 是 | 文件内容 |
|
||
| `purpose` | enum | 是 | 上述用途 |
|
||
| `clientFileId` | string | 是 | 前端本次选择生成的 UUID，用于去重 |
|
||
| `sha256` | string | 否 | 客户端可计算时传入 |
|
||
|
||
响应 `201 Created`：返回 `FileAsset`。文本类文件通常返回 `parseStatus: "queued"`，不能把上传成功展示成解析成功。
|
||
|
||
### 6.3 大文件分片初始化
|
||
|
||
`POST /file-uploads`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"purpose": "knowledge_source",
|
||
"fileName": "product-training.mp4",
|
||
"contentType": "video/mp4",
|
||
"sizeBytes": 734003200,
|
||
"sha256": "可选整体哈希",
|
||
"clientFileId": "8fb2a9e5-..."
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"uploadId": "upload_01J3...",
|
||
"chunkSizeBytes": 8388608,
|
||
"uploadedParts": [],
|
||
"expiresAt": "2026-07-22T08:30:15.238Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.4 上传分片
|
||
|
||
`PUT /file-uploads/{uploadId}/parts/{partNumber}`
|
||
|
||
Headers：
|
||
|
||
```text
|
||
Content-Type: application/octet-stream
|
||
Content-Length: 8388608
|
||
Content-Range: bytes 0-8388607/734003200
|
||
X-Chunk-SHA256: 1c9e...
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"partNumber": 1,
|
||
"sizeBytes": 8388608,
|
||
"sha256": "1c9e...",
|
||
"accepted": true
|
||
}
|
||
}
|
||
```
|
||
|
||
重复上传同一分片且哈希相同必须幂等；哈希不同返回 `409 CHUNK_CONFLICT`。
|
||
|
||
### 6.5 完成分片上传
|
||
|
||
`POST /file-uploads/{uploadId}/complete`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"parts": [
|
||
{ "partNumber": 1, "sha256": "1c9e..." },
|
||
{ "partNumber": 2, "sha256": "41af..." }
|
||
]
|
||
}
|
||
```
|
||
|
||
响应 `201 Created`：返回 `FileAsset`。
|
||
|
||
### 6.6 查询和取消上传
|
||
|
||
- `GET /file-uploads/{uploadId}`：返回已上传分片，用于断点续传。
|
||
- `DELETE /file-uploads/{uploadId}`：删除临时分片，返回 `204`。
|
||
|
||
### 6.7 查询文件
|
||
|
||
`GET /files/{fileId}`：返回 `FileAsset`。
|
||
|
||
文件解析过程通过 WS 推送 `file.processing.updated`：
|
||
|
||
```json
|
||
{
|
||
"fileId": "file_01J3...",
|
||
"status": "processing",
|
||
"parseStatus": "processing",
|
||
"progress": 0.64,
|
||
"stage": "extracting_text",
|
||
"extractedTextLength": 0,
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
### 6.8 文档转换与媒体预览
|
||
|
||
- `GET /files/{fileId}/text?offset=0&limit=20000`：分页预览文档转换后的纯文本。
|
||
- `GET /files/{fileId}/text-file`：下载 UTF-8 `.txt` 转换结果，响应为 `text/plain; charset=utf-8`。
|
||
- `GET /files/{fileId}/content`：下载原文件或预览图片、视频；支持 `Range`。
|
||
- `PATCH /files/{fileId}`：只用于操作者保存图片或视频的人工描述。
|
||
|
||
文档转换规则：
|
||
|
||
- PDF 只读取文本层，不对页面截图或扫描内容执行 OCR。
|
||
- DOCX 中的段落、表格文本按文档顺序输出；图片、形状内不可直接读取的图像文字省略。
|
||
- PPT/PPTX 中的文本框、表格和备注按页输出；每页使用稳定页码分隔，图片内容省略。
|
||
- 成功提取到正文但省略了图片时，`parseStatus` 为 `completed`，同时返回 `EMBEDDED_IMAGES_SKIPPED` warning。
|
||
- 没有任何可提取正文时，`parseStatus` 为 `failed`，`error.code` 为 `NO_EXTRACTABLE_TEXT`。
|
||
|
||
媒体处理规则：
|
||
|
||
- 图片、视频上传完成并通过文件安全校验后，`parseStatus` 固定为 `not_required`。
|
||
- 服务端只生成安全预览能力，不识别画面、不抽取文字、不识别语音、不生成描述。
|
||
- `description` 完全来自人工输入，服务端原样保存；空描述允许保存，但媒体内容本身不会进入 FTS5 正文索引。
|
||
|
||
`PATCH /files/{fileId}` 请求：
|
||
|
||
```json
|
||
{
|
||
"description": "退款申请、审核和到账三个步骤的流程图。",
|
||
"descriptionSource": "manual",
|
||
"expectedRevision": 1
|
||
}
|
||
```
|
||
|
||
服务端必须拒绝 `descriptionSource` 不是 `manual` 的请求；响应返回最新 `FileAsset`。
|
||
|
||
文本响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"fileId": "file_01J3...",
|
||
"text": "第一章 退款申请范围……",
|
||
"offset": 0,
|
||
"returnedLength": 12680,
|
||
"totalLength": 12680,
|
||
"truncated": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.9 删除文件
|
||
|
||
`DELETE /files/{fileId}?expectedRevision=1`
|
||
|
||
- 未绑定草稿或消息时返回 `204`。
|
||
- 已被已发布版本引用时返回 `409 FILE_IN_USE`，不能物理删除。
|
||
|
||
---
|
||
|
||
## 7. 知识库接口
|
||
|
||
### 7.1 知识库列表与全文搜索
|
||
|
||
`GET /knowledge-bases?query=退款&status=all&limit=20&cursor=...`
|
||
|
||
响应：`data.items: KnowledgeSummary[]`。
|
||
|
||
搜索范围由设置中的 `knowledgeSearchFields` 决定；页面输入“标题、标签或完整正文”时，服务端返回匹配后的知识库摘要，不把完整正文放进列表响应。
|
||
|
||
### 7.2 创建草稿
|
||
|
||
`POST /knowledge-drafts`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"mode": "create",
|
||
"knowledgeId": null,
|
||
"baseVersion": null,
|
||
"title": "售后退款政策",
|
||
"description": "用于回答售后退款范围、异常订单与客户安抚相关问题。",
|
||
"tags": ["私域成交", "售后"]
|
||
}
|
||
```
|
||
|
||
更新知识库时：
|
||
|
||
```json
|
||
{
|
||
"mode": "update",
|
||
"knowledgeId": "kb_refund",
|
||
"baseVersion": "v1.7"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "kbdraft_01J3...",
|
||
"mode": "create",
|
||
"knowledgeId": null,
|
||
"baseVersion": null,
|
||
"title": "售后退款政策",
|
||
"description": "用于回答……",
|
||
"tags": ["私域成交", "售后"],
|
||
"fileIds": [],
|
||
"state": "draft",
|
||
"revision": 1,
|
||
"updatedAt": "2026-07-21T08:30:15.238Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.3 保存草稿基本信息
|
||
|
||
`PATCH /knowledge-drafts/{draftId}`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"title": "售后退款政策",
|
||
"description": "用于回答售后问题。",
|
||
"tags": ["私域成交", "售后"],
|
||
"expectedRevision": 1
|
||
}
|
||
```
|
||
|
||
校验：`title` 1~100 字；`description` 最大 2000 字；标签最多 20 个，每个 1~30 字，去重后保存。
|
||
|
||
响应：返回完整草稿和递增后的 `revision`。
|
||
|
||
### 7.4 绑定或移除来源文件
|
||
|
||
`POST /knowledge-drafts/{draftId}/files`
|
||
|
||
```json
|
||
{
|
||
"fileIds": ["file_01J3...", "file_01J4..."],
|
||
"expectedRevision": 2
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"draftId": "kbdraft_01J3...",
|
||
"files": [{ "id": "file_01J3...", "fileName": "refund-policy.pdf", "sizeBytes": 2516582, "kind": "text", "status": "ready", "parseStatus": "completed" }],
|
||
"readyCount": 1,
|
||
"processingCount": 1,
|
||
"failedCount": 0,
|
||
"revision": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
`DELETE /knowledge-drafts/{draftId}/files/{fileId}?expectedRevision=3`：从草稿移除，返回更新后的文件汇总。
|
||
|
||
### 7.5 草稿预览汇总
|
||
|
||
`GET /knowledge-drafts/{draftId}/preview`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"draftId": "kbdraft_01J3...",
|
||
"sourceCount": 3,
|
||
"ready": true,
|
||
"files": [{ "id": "file_01J3...", "fileName": "refund-policy.pdf", "sizeBytes": 2516582, "kind": "text", "status": "ready", "parseStatus": "completed" }],
|
||
"totalTextLength": 26000,
|
||
"blockingErrors": []
|
||
}
|
||
}
|
||
```
|
||
|
||
`ready` 只有在至少一个来源且所有必需解析完成时为 `true`。
|
||
|
||
### 7.6 发布知识库或保存新版本
|
||
|
||
`POST /knowledge-drafts/{draftId}/publish`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"versionNote": "补充异常订单处理边界",
|
||
"enableAfterPublish": true,
|
||
"expectedRevision": 4
|
||
}
|
||
```
|
||
|
||
响应 `201 Created`：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"knowledge": { "id": "kb_refund", "title": "售后常见问题与退款边界", "type": "file", "tags": ["售后", "退款"], "status": "enabled", "currentVersion": "v1.8", "referenceCount": 0, "fileCount": 1, "updatedAt": "2026-07-21T08:40:00Z", "revision": 1 },
|
||
"version": {
|
||
"id": "kv_01J3...",
|
||
"knowledgeId": "kb_refund",
|
||
"version": "v1.8",
|
||
"versionNote": "补充异常订单处理边界",
|
||
"fileIds": ["file_01J3..."],
|
||
"textLength": 26000,
|
||
"contentHash": "5c82...",
|
||
"createdAt": "2026-07-21T08:40:00Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
版本号由服务端生成，客户端不得自行加一。若 `baseVersion` 已落后，返回 `409 REVISION_CONFLICT`。
|
||
|
||
### 7.7 知识库详情
|
||
|
||
`GET /knowledge-bases/{knowledgeId}`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "kb_refund",
|
||
"title": "售后常见问题与退款边界",
|
||
"description": "涵盖退款期限、数字商品限制、异常订单处理和安抚话术边界。",
|
||
"tags": ["售后", "退款"],
|
||
"type": "file",
|
||
"status": "enabled",
|
||
"currentVersion": "v1.7",
|
||
"creator": { "id": "local_operator", "displayName": "本机管理员" },
|
||
"effectiveAt": "2026-06-05T01:42:00Z",
|
||
"lastRetrievedAt": "2026-07-21T08:18:00Z",
|
||
"metrics": {
|
||
"weeklyHitCount": 32,
|
||
"agentReferenceCount": 3,
|
||
"employeeBindingCount": 2,
|
||
"textLength": 26000
|
||
},
|
||
"revision": 7,
|
||
"updatedAt": "2026-06-05T01:42:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.8 详情子资源
|
||
|
||
- `GET /knowledge-bases/{id}/files`：当前版本的 `FileAsset[]`。
|
||
- `GET /knowledge-bases/{id}/references?type=all`：引用关系。
|
||
- `GET /knowledge-bases/{id}/versions?limit=20&cursor=...`：版本历史。
|
||
|
||
引用关系项：
|
||
|
||
```json
|
||
{
|
||
"resourceType": "agent",
|
||
"resourceId": "agent_quote",
|
||
"name": "报价策略生成",
|
||
"enabled": true,
|
||
"boundVersion": "v1.7"
|
||
}
|
||
```
|
||
|
||
版本项：
|
||
|
||
```json
|
||
{
|
||
"id": "kv_01J3...",
|
||
"version": "v1.7",
|
||
"versionNote": "修正数字商品退款边界",
|
||
"isCurrent": true,
|
||
"createdAt": "2026-06-05T01:42:00Z"
|
||
}
|
||
```
|
||
|
||
### 7.9 启停和删除
|
||
|
||
`PATCH /knowledge-bases/{id}/status`
|
||
|
||
```json
|
||
{ "enabled": false, "expectedRevision": 7 }
|
||
```
|
||
|
||
响应：返回最新 `KnowledgeSummary`。停用后已绑定关系保留，但检索时不能命中。
|
||
|
||
`DELETE /knowledge-bases/{id}`
|
||
|
||
```json
|
||
{
|
||
"confirmation": "售后常见问题与退款边界",
|
||
"expectedRevision": 8
|
||
}
|
||
```
|
||
|
||
有引用关系时默认返回 `409 RESOURCE_IN_USE` 和引用摘要；不提供静默级联删除。
|
||
|
||
---
|
||
|
||
## 8. 智能体接口
|
||
|
||
### 8.1 列表
|
||
|
||
`GET /agents?query=报价&type=all&enabled=all&limit=20&cursor=...`
|
||
|
||
响应：`data.items: AgentSummary[]`。
|
||
|
||
筛选枚举：`type=all|builtin|custom`，`enabled=all|true|false`。
|
||
|
||
### 8.2 创建智能体草稿
|
||
|
||
`POST /agent-drafts`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"mode": "create",
|
||
"agentId": null,
|
||
"name": "报价策略生成",
|
||
"description": "根据客户意向、商品成本和优惠边界生成报价建议。",
|
||
"tags": ["利润保护", "阶梯报价", "优惠边界"]
|
||
}
|
||
```
|
||
|
||
更新模式传 `mode: "update"` 和 `agentId`。响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "agentdraft_01J3...",
|
||
"mode": "create",
|
||
"agentId": null,
|
||
"name": "报价策略生成",
|
||
"description": "根据客户意向……",
|
||
"tags": ["利润保护", "阶梯报价", "优惠边界"],
|
||
"systemPrompt": "",
|
||
"knowledgeIds": [],
|
||
"lastTestSessionId": null,
|
||
"lastTestStatus": "not_run",
|
||
"revision": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.3 保存基本信息、提示词和授权
|
||
|
||
`PATCH /agent-drafts/{draftId}`
|
||
|
||
请求可部分更新：
|
||
|
||
```json
|
||
{
|
||
"name": "报价策略生成",
|
||
"description": "根据客户意向、商品成本和优惠边界生成报价建议。",
|
||
"tags": ["利润保护", "阶梯报价", "优惠边界"],
|
||
"systemPrompt": "你是报价策略助手……",
|
||
"knowledgeIds": ["kb_price", "kb_discount"],
|
||
"expectedRevision": 1
|
||
}
|
||
```
|
||
|
||
校验：名称 1~80 字；描述最大 2000 字；标签最多 20 个；系统提示词最大 20000 字；只能授权已生效知识库。
|
||
|
||
响应：返回完整草稿和新 `revision`。
|
||
|
||
### 8.4 发布或更新智能体
|
||
|
||
`POST /agent-drafts/{draftId}/publish`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"releaseNote": "首次发布报价策略生成智能体。",
|
||
"enableAfterPublish": true,
|
||
"expectedRevision": 3
|
||
}
|
||
```
|
||
|
||
前置条件：`lastTestStatus` 必须为 `passed`，且测试使用的 `draftRevision` 必须等于当前草稿 revision；提示词或授权变更后旧测试失效。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"agent": { "id": "agent_quote", "name": "报价策略生成", "type": "custom", "enabled": true, "version": "v1.0", "tags": ["利润保护", "阶梯报价", "优惠边界"], "knowledgeCount": 2, "recentCallCount": 0, "lastTestStatus": "passed", "updatedAt": "2026-07-21T08:50:00Z", "revision": 1 },
|
||
"release": {
|
||
"version": "v1.0",
|
||
"releaseNote": "首次发布报价策略生成智能体。",
|
||
"createdAt": "2026-07-21T08:50:00Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.5 详情
|
||
|
||
`GET /agents/{agentId}`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "agent_intent",
|
||
"name": "客户意图识别",
|
||
"type": "builtin",
|
||
"enabled": true,
|
||
"version": "v2.1",
|
||
"description": "识别客户所处阶段、购买意向、核心异议，并输出下一步跟进建议。",
|
||
"tags": ["线索分级", "异议判断", "下一步建议"],
|
||
"systemPrompt": "你是报价策略助手……",
|
||
"permissions": [
|
||
{ "code": "knowledge.query", "label": "查询知识库", "granted": true },
|
||
{ "code": "conversation.read_current", "label": "读取当前会话", "granted": true },
|
||
{ "code": "message.send", "label": "直接发送消息", "granted": false }
|
||
],
|
||
"knowledge": [
|
||
{ "id": "kb_refund", "title": "售后退款政策", "version": "v1.7", "enabled": true }
|
||
],
|
||
"metrics": {
|
||
"recentCallCount": 16,
|
||
"successRate": 0.984,
|
||
"averageLatencyMs": 1200,
|
||
"knowledgeCount": 3
|
||
},
|
||
"updatedAt": "2026-06-16T10:20:00Z",
|
||
"revision": 4
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.6 权限和测试记录
|
||
|
||
- `GET /agents/{id}/permissions`：返回上述 `permissions` 和 `knowledge`。
|
||
- `GET /agents/{id}/test-records?limit=20&cursor=...`。
|
||
|
||
测试记录项：
|
||
|
||
```json
|
||
{
|
||
"id": "test_01J3...",
|
||
"scenario": "高意向询价",
|
||
"status": "passed",
|
||
"latencyMs": 1200,
|
||
"draftRevision": 3,
|
||
"createdAt": "2026-06-18T09:30:00Z",
|
||
"error": null
|
||
}
|
||
```
|
||
|
||
### 8.7 启停和删除
|
||
|
||
`PATCH /agents/{id}/status`
|
||
|
||
```json
|
||
{ "enabled": false, "expectedRevision": 4 }
|
||
```
|
||
|
||
`DELETE /agents/{id}`
|
||
|
||
```json
|
||
{
|
||
"confirmation": "客户意图识别",
|
||
"expectedRevision": 5
|
||
}
|
||
```
|
||
|
||
内置智能体可按产品规则返回 `403 BUILTIN_AGENT_READ_ONLY`；若允许删除，必须明确为隐藏/禁用而非物理删除。
|
||
|
||
---
|
||
|
||
## 9. 智能体测试会话与 WebSocket 流式回复
|
||
|
||
### 9.1 创建测试会话
|
||
|
||
`POST /agent-test-sessions`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"agentId": "agent_intent",
|
||
"draftId": null,
|
||
"draftRevision": null,
|
||
"mode": "published"
|
||
}
|
||
```
|
||
|
||
编辑器沙箱传：
|
||
|
||
```json
|
||
{
|
||
"agentId": null,
|
||
"draftId": "agentdraft_01J3...",
|
||
"draftRevision": 3,
|
||
"mode": "draft"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"sessionId": "testsession_01J3...",
|
||
"state": "ready",
|
||
"channel": "agent-test:testsession_01J3...",
|
||
"maxFilesPerMessage": 5,
|
||
"maxFileSizeBytes": 20971520,
|
||
"acceptedExtensions": ["pdf", "docx", "ppt", "pptx", "txt", "md", "csv", "json"],
|
||
"expiresAt": "2026-07-21T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9.2 发送测试消息
|
||
|
||
使用 WebSocket command，不把文件二进制放进 WS。附件必须先通过 `POST /files` 上传。
|
||
|
||
```json
|
||
{
|
||
"type": "agent.test.message.send",
|
||
"requestId": "client_req_8",
|
||
"payload": {
|
||
"sessionId": "testsession_01J3...",
|
||
"clientMessageId": "bce8e547-...",
|
||
"content": "客户预算为 10000 元，可以如何报价？",
|
||
"fileIds": ["file_01J3..."]
|
||
}
|
||
}
|
||
```
|
||
|
||
校验：`content` 与 `fileIds` 至少一个非空；内容最大 20000 字；附件最多 5 个；附件 purpose 必须为 `agent_test_attachment` 且解析完成。
|
||
|
||
服务端事件顺序：
|
||
|
||
1. `agent.test.message.accepted`
|
||
2. 零到多个 `agent.test.message.delta`
|
||
3. `agent.test.message.completed` 或 `agent.test.message.failed`
|
||
|
||
accepted：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "testsession_01J3...",
|
||
"messageId": "msg_01J3...",
|
||
"clientMessageId": "bce8e547-...",
|
||
"assistantMessageId": "msg_01J4...",
|
||
"acceptedAt": "2026-07-21T08:55:00Z"
|
||
}
|
||
```
|
||
|
||
delta：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "testsession_01J3...",
|
||
"assistantMessageId": "msg_01J4...",
|
||
"sequence": 7,
|
||
"delta": "建议先核对",
|
||
"accumulatedLength": 28
|
||
}
|
||
```
|
||
|
||
completed：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "testsession_01J3...",
|
||
"assistantMessageId": "msg_01J4...",
|
||
"content": "建议先核对客户需求……",
|
||
"finishReason": "stop",
|
||
"usage": { "inputTokens": 412, "outputTokens": 96 },
|
||
"latencyMs": 1320,
|
||
"testResult": {
|
||
"status": "passed",
|
||
"draftRevision": 3,
|
||
"warnings": []
|
||
},
|
||
"completedAt": "2026-07-21T08:55:01.320Z"
|
||
}
|
||
```
|
||
|
||
failed：
|
||
|
||
```json
|
||
{
|
||
"sessionId": "testsession_01J3...",
|
||
"assistantMessageId": "msg_01J4...",
|
||
"code": "MODEL_TIMEOUT",
|
||
"message": "模型在 8000ms 内未返回",
|
||
"retryable": true
|
||
}
|
||
```
|
||
|
||
### 9.3 历史与取消
|
||
|
||
- `GET /agent-test-sessions/{sessionId}/messages?limit=100&cursor=...`：恢复弹窗后的对话。
|
||
- WS command `agent.test.generation.cancel`：`{ sessionId, assistantMessageId }`。
|
||
- `DELETE /agent-test-sessions/{sessionId}`：结束会话并清理未引用测试附件。
|
||
|
||
消息对象：
|
||
|
||
```json
|
||
{
|
||
"id": "msg_01J3...",
|
||
"role": "user",
|
||
"content": "客户预算为 10000 元",
|
||
"files": [
|
||
{ "id": "file_01J3...", "fileName": "budget.txt", "sizeBytes": 126 }
|
||
],
|
||
"state": "completed",
|
||
"createdAt": "2026-07-21T08:55:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 蒸馏任务接口
|
||
|
||
### 10.1 当前任务和员工列表
|
||
|
||
- `GET /distill-jobs?state=active&limit=10`：返回 `DistillJobSummary[]`，用于“当前任务”。
|
||
- `GET /employees?query=Aileen&enabled=all&limit=20&cursor=...`：返回 `EmployeeSummary[]`。
|
||
|
||
### 10.2 创建蒸馏草稿
|
||
|
||
`POST /distill-drafts`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"name": "销售冠军 Aileen 话术蒸馏",
|
||
"minimumValidConversations": 50
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "distilldraft_01J3...",
|
||
"name": "销售冠军 Aileen 话术蒸馏",
|
||
"fileIds": [],
|
||
"minimumValidConversations": 50,
|
||
"state": "draft",
|
||
"revision": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10.3 绑定上传文件
|
||
|
||
`POST /distill-drafts/{draftId}/files`
|
||
|
||
```json
|
||
{
|
||
"fileIds": ["file_01J3..."],
|
||
"expectedRevision": 1
|
||
}
|
||
```
|
||
|
||
响应：返回草稿、文件列表和有效内容统计：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"draftId": "distilldraft_01J3...",
|
||
"files": [{ "id": "file_01J3...", "fileName": "champion-scripts.docx", "sizeBytes": 245760, "kind": "text", "status": "ready", "parseStatus": "completed" }],
|
||
"statistics": {
|
||
"validConversationCount": 1286,
|
||
"scriptCount": 38,
|
||
"invalidRecordCount": 7
|
||
},
|
||
"revision": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
当前来源页只保留文件上传；不设计导入微信聊天、选择已有案例或日期范围字段。
|
||
|
||
### 10.4 保存草稿
|
||
|
||
`PATCH /distill-drafts/{draftId}`
|
||
|
||
```json
|
||
{
|
||
"name": "销售冠军 Aileen 话术蒸馏",
|
||
"minimumValidConversations": 50,
|
||
"expectedRevision": 2
|
||
}
|
||
```
|
||
|
||
响应：返回完整草稿。
|
||
|
||
### 10.5 开始能力提取
|
||
|
||
`POST /distill-drafts/{draftId}/start`
|
||
|
||
```json
|
||
{ "expectedRevision": 3 }
|
||
```
|
||
|
||
响应 `202 Accepted`：返回 `DistillJobSummary`。文件未解析完成、有效记录不足或草稿为空时返回 `400 VALIDATION_ERROR`。
|
||
|
||
任务进度通过 `distill.progress.updated` 推送：
|
||
|
||
```json
|
||
{
|
||
"jobId": "distill_01J3...",
|
||
"state": "extracting",
|
||
"stage": "strategy_extraction",
|
||
"stageLabel": "策略提取",
|
||
"progress": 0.72,
|
||
"processedCount": 1286,
|
||
"totalCount": 1286,
|
||
"stageCurrent": 13,
|
||
"stageTotal": 18,
|
||
"estimatedRemainingSeconds": 180,
|
||
"recognizedCapabilities": ["高意向识别", "异议拆解", "温和推进", "优惠边界", "长期跟进"],
|
||
"updatedAt": "2026-07-21T09:05:00Z",
|
||
"revision": 9
|
||
}
|
||
```
|
||
|
||
### 10.6 查询任务详情
|
||
|
||
`GET /distill-jobs/{jobId}`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"summary": { "id": "distill_01J3...", "name": "销售冠军 Aileen 话术蒸馏", "state": "extracting", "stage": "strategy_extraction", "progress": 0.72, "estimatedRemainingSeconds": 180, "sourceCount": 1, "successCount": 248, "failedCount": 7, "createdAt": "2026-07-21T08:30:15.238Z", "updatedAt": "2026-07-21T08:34:10Z", "revision": 9 },
|
||
"stages": [
|
||
{ "code": "data_cleaning", "label": "数据清洗", "state": "completed", "current": 1286, "total": 1286 },
|
||
{ "code": "scene_clustering", "label": "场景聚类", "state": "completed", "current": 18, "total": 18 },
|
||
{ "code": "strategy_extraction", "label": "策略提取", "state": "running", "current": 13, "total": 18 },
|
||
{ "code": "boundary_induction", "label": "边界归纳", "state": "waiting", "current": 0, "total": null },
|
||
{ "code": "counterexample_generation", "label": "反例生成", "state": "waiting", "current": 0, "total": null }
|
||
],
|
||
"recognizedCapabilities": ["高意向识别", "异议拆解", "温和推进", "优惠边界", "长期跟进"],
|
||
"error": null
|
||
}
|
||
}
|
||
```
|
||
|
||
页面已移除失败样本入口，因此不提供面向 UI 的失败样本明细接口；`failedCount` 只作为任务健康摘要和日志字段。
|
||
|
||
### 10.7 效果评估
|
||
|
||
`GET /distill-jobs/{jobId}/evaluation`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"jobId": "distill_01J3...",
|
||
"state": "completed",
|
||
"overallScore": 92,
|
||
"publishThreshold": 85,
|
||
"publishable": true,
|
||
"metrics": {
|
||
"sceneHitRate": 0.94,
|
||
"refusalAccuracy": 0.91,
|
||
"overreachRate": 0.003,
|
||
"consistency": 0.89
|
||
},
|
||
"cases": [
|
||
{ "id": "case_1", "name": "高意向询价", "result": "建议合理", "passed": true },
|
||
{ "id": "case_2", "name": "超边界优惠", "result": "已拒绝越权", "passed": true },
|
||
{ "id": "case_3", "name": "售后退款混合场景", "result": "回答包含不确定信息", "passed": false }
|
||
],
|
||
"completedAt": "2026-07-21T09:10:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
`POST /distill-jobs/{jobId}/evaluation-runs`：重新评估，响应 `202`，进度通过 WS 推送。
|
||
|
||
`POST /distill-jobs/{jobId}/evaluation-exports`：生成报告，响应结构同日志导出。
|
||
|
||
### 10.8 发布员工
|
||
|
||
`POST /distill-jobs/{jobId}/publish`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"name": "销售冠军 Aileen",
|
||
"domain": "private_sales",
|
||
"agentIds": ["agent_intent", "agent_quote"],
|
||
"knowledgeIds": ["kb_price", "kb_discount", "kb_refund"],
|
||
"enableAfterPublish": true,
|
||
"expectedRevision": 11
|
||
}
|
||
```
|
||
|
||
- `domain`: `private_sales | b2b_consulting | after_sales`
|
||
- 至少一个授权能力；知识授权可为空；只允许授权已启用资源。
|
||
|
||
响应 `201 Created`：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"employee": { "id": "employee_1", "name": "销售冠军 Aileen", "version": "v1.0", "enabled": true, "traits": ["高意向识别", "异议拆解"], "domain": "private_sales", "score": 92, "weeklyCallCount": 0, "updatedAt": "2026-07-21T09:15:00Z", "revision": 1 },
|
||
"sourceJobId": "distill_01J3...",
|
||
"publishedAt": "2026-07-21T09:15:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10.9 取消任务
|
||
|
||
`POST /distill-jobs/{jobId}/cancel`
|
||
|
||
```json
|
||
{ "expectedRevision": 9, "reason": "operator_request" }
|
||
```
|
||
|
||
仅 `queued | extracting | evaluating` 可取消。响应返回 `state: "cancelled"` 的任务摘要。
|
||
|
||
---
|
||
|
||
## 11. 员工详情接口
|
||
|
||
### 11.1 详情
|
||
|
||
`GET /employees/{employeeId}`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "employee_1",
|
||
"name": "销售冠军 Aileen",
|
||
"version": "v3.2",
|
||
"enabled": true,
|
||
"domain": "private_sales",
|
||
"traits": ["高意向逼单", "异议拆解", "温和推进"],
|
||
"profile": {
|
||
"applicableScenario": "已有明确需求、处于报价或决策阶段的私域客户",
|
||
"prohibitedBehavior": "承诺未授权折扣、绕过人工确认直接发送敏感信息"
|
||
},
|
||
"metrics": {
|
||
"overallScore": 96,
|
||
"weeklyCallCount": 28,
|
||
"adoptionRate": 0.82,
|
||
"exceptionCount": 1
|
||
},
|
||
"agentBindings": [
|
||
{ "id": "agent_intent", "name": "客户意图识别", "granted": true }
|
||
],
|
||
"knowledgeBindings": [
|
||
{ "id": "kb_price", "title": "产品价格表", "bound": true }
|
||
],
|
||
"updatedAt": "2026-06-18T09:00:00Z",
|
||
"revision": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11.2 启停、画像和授权
|
||
|
||
`PATCH /employees/{id}/status`
|
||
|
||
```json
|
||
{ "enabled": false, "expectedRevision": 3 }
|
||
```
|
||
|
||
`PATCH /employees/{id}/profile`
|
||
|
||
```json
|
||
{
|
||
"name": "销售冠军 Aileen",
|
||
"domain": "private_sales",
|
||
"traits": ["高意向逼单", "异议拆解", "温和推进"],
|
||
"applicableScenario": "已有明确需求、处于报价或决策阶段的私域客户",
|
||
"prohibitedBehavior": "承诺未授权折扣",
|
||
"expectedRevision": 4
|
||
}
|
||
```
|
||
|
||
`PUT /employees/{id}/bindings`
|
||
|
||
```json
|
||
{
|
||
"agentIds": ["agent_intent", "agent_quote"],
|
||
"knowledgeIds": ["kb_price", "kb_discount", "kb_sales_champion"],
|
||
"expectedRevision": 5
|
||
}
|
||
```
|
||
|
||
均返回最新员工详情。
|
||
|
||
### 11.3 详情页各 Tab
|
||
|
||
- `GET /employees/{id}/evaluation`：结构同蒸馏评估摘要。
|
||
- `GET /employees/{id}/versions?limit=20&cursor=...`。
|
||
- `GET /employees/{id}/calls?limit=50&cursor=...`。
|
||
|
||
调用记录项：
|
||
|
||
```json
|
||
{
|
||
"id": "call_01J3...",
|
||
"time": "2026-07-21T04:26:00Z",
|
||
"scenario": "高意向询价",
|
||
"result": "suggestion_adopted",
|
||
"resultLabel": "建议已采纳",
|
||
"requestId": "req_01J3..."
|
||
}
|
||
```
|
||
|
||
### 11.4 重新蒸馏和复制
|
||
|
||
`POST /employees/{id}/redistill`
|
||
|
||
```json
|
||
{ "baseVersion": "v3.2" }
|
||
```
|
||
|
||
响应 `201`：返回预填的 `distillDraftId`。
|
||
|
||
`POST /employees/{id}/clone`
|
||
|
||
```json
|
||
{ "name": "销售冠军 Aileen 副本", "copyBindings": true }
|
||
```
|
||
|
||
响应 `201`：返回新员工详情，默认 `enabled: false`。
|
||
|
||
---
|
||
|
||
## 12. 设置接口
|
||
|
||
### 12.1 获取全部配置
|
||
|
||
`GET /settings`
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"revision": 12,
|
||
"model": {
|
||
"provider": "volcengine",
|
||
"endpoint": "https://ark.cn-beijing.volces.com/api/v3",
|
||
"modelName": "doubao-pro-32k",
|
||
"requestTimeoutMs": 8000,
|
||
"keyConfigured": true,
|
||
"keyUpdatedAt": "2026-07-20T09:00:00Z"
|
||
},
|
||
"prompt": {
|
||
"fixedPrompt": "你是本地微信分身助手，需要遵守托管策略、回复边界与用户授权。",
|
||
"customPrompt": "保持友好、简洁、可信赖。优先调用知识库和已授权员工能力。",
|
||
"customPromptMaxLength": 4000
|
||
},
|
||
"replyRules": {
|
||
"quietHoursEnabled": false,
|
||
"quietHours": { "start": "22:00", "end": "08:00", "timezone": "Asia/Shanghai" },
|
||
"autoAddFriend": false,
|
||
"proactiveContact": false,
|
||
"distillationEnabled": true
|
||
},
|
||
"featureGates": {
|
||
"agentsEnabled": true,
|
||
"employeesEnabled": true,
|
||
"knowledgeEnabled": true
|
||
},
|
||
"knowledgeSearch": {
|
||
"algorithm": "sqlite_fts5_bm25",
|
||
"maxResults": 5,
|
||
"fields": ["title", "tags", "fullText"],
|
||
"activeKnowledgeIds": ["kb_sales_champion", "kb_refund"]
|
||
},
|
||
"hosting": {
|
||
"enabled": false,
|
||
"localMessageServiceEnabled": true,
|
||
"confirmBeforeSend": true,
|
||
"abnormalPauseEnabled": true,
|
||
"consecutiveErrorLimit": 3,
|
||
"messageWaitSeconds": 30
|
||
},
|
||
"updatedAt": "2026-07-21T08:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 12.2 保存配置
|
||
|
||
`PUT /settings`
|
||
|
||
请求传完整可编辑配置，但不传 `fixedPrompt`、`keyConfigured`、`keyUpdatedAt`：
|
||
|
||
```json
|
||
{
|
||
"expectedRevision": 12,
|
||
"model": {
|
||
"provider": "volcengine",
|
||
"endpoint": "https://ark.cn-beijing.volces.com/api/v3",
|
||
"modelName": "doubao-pro-32k",
|
||
"requestTimeoutMs": 8000
|
||
},
|
||
"prompt": {
|
||
"customPrompt": "保持友好、简洁、可信赖。"
|
||
},
|
||
"replyRules": {
|
||
"quietHoursEnabled": false,
|
||
"quietHours": { "start": "22:00", "end": "08:00", "timezone": "Asia/Shanghai" },
|
||
"autoAddFriend": false,
|
||
"proactiveContact": false,
|
||
"distillationEnabled": true
|
||
},
|
||
"featureGates": {
|
||
"agentsEnabled": true,
|
||
"employeesEnabled": true,
|
||
"knowledgeEnabled": true
|
||
},
|
||
"knowledgeSearch": {
|
||
"maxResults": 5,
|
||
"fields": ["title", "tags", "fullText"],
|
||
"activeKnowledgeIds": ["kb_sales_champion", "kb_refund"]
|
||
},
|
||
"hosting": {
|
||
"enabled": false,
|
||
"localMessageServiceEnabled": true,
|
||
"confirmBeforeSend": true,
|
||
"abnormalPauseEnabled": true,
|
||
"consecutiveErrorLimit": 3,
|
||
"messageWaitSeconds": 30
|
||
}
|
||
}
|
||
```
|
||
|
||
响应：完整最新配置。前端“恢复”必须恢复最近一次 GET/PUT 成功的数据，不能只清除 dirty 状态。
|
||
|
||
### 12.3 API Key
|
||
|
||
`PUT /settings/model-api-key`
|
||
|
||
```json
|
||
{ "apiKey": "真实密钥" }
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keyConfigured": true,
|
||
"keyUpdatedAt": "2026-07-21T09:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
`DELETE /settings/model-api-key`：返回 `204`。密钥只在此 PUT 请求中出现一次。
|
||
|
||
### 12.4 测试模型连接
|
||
|
||
`POST /settings/model-connection-tests`
|
||
|
||
使用当前未保存表单值：
|
||
|
||
```json
|
||
{
|
||
"provider": "volcengine",
|
||
"endpoint": "https://ark.cn-beijing.volces.com/api/v3",
|
||
"modelName": "doubao-pro-32k",
|
||
"requestTimeoutMs": 8000,
|
||
"useStoredApiKey": true
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"success": true,
|
||
"latencyMs": 324,
|
||
"provider": "volcengine",
|
||
"modelName": "doubao-pro-32k",
|
||
"checkedAt": "2026-07-21T09:31:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
失败时仍返回对应 HTTP 错误和明确 code：`MODEL_AUTH_FAILED | MODEL_NOT_FOUND | MODEL_TIMEOUT | MODEL_NETWORK_UNREACHABLE`。
|
||
|
||
### 12.5 组合提示词预览
|
||
|
||
`POST /settings/prompt-previews`
|
||
|
||
```json
|
||
{ "customPrompt": "保持友好、简洁、可信赖。" }
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"fixedPrompt": "你是本地微信分身助手……",
|
||
"customPrompt": "保持友好、简洁、可信赖。",
|
||
"combinedPrompt": "你是本地微信分身助手……\n\n保持友好、简洁、可信赖。",
|
||
"characterCount": 52
|
||
}
|
||
}
|
||
```
|
||
|
||
### 12.6 黑白名单
|
||
|
||
`GET /contact-lists?type=allow|block&query=张三`
|
||
|
||
响应项：
|
||
|
||
```json
|
||
{
|
||
"id": "contact_rule_01J3...",
|
||
"type": "allow",
|
||
"displayName": "张三",
|
||
"headerFingerprint": "sha256:...",
|
||
"source": "manual",
|
||
"createdAt": "2026-07-21T09:32:00Z"
|
||
}
|
||
```
|
||
|
||
`POST /contact-lists`
|
||
|
||
```json
|
||
{
|
||
"type": "allow",
|
||
"displayName": "张三",
|
||
"headerFingerprint": "sha256:...",
|
||
"source": "manual"
|
||
}
|
||
```
|
||
|
||
`DELETE /contact-lists/{ruleId}`：返回 `204`。
|
||
|
||
仅名称不足以稳定识别微信会话；生产数据必须包含当前会话头生成的 `headerFingerprint`。
|
||
|
||
### 12.7 管理页逐项开关
|
||
|
||
以下接口复用资源状态，不额外创建第二套启停数据：
|
||
|
||
- 智能体：`PATCH /agents/{id}/status`
|
||
- 员工：`PATCH /employees/{id}/status`
|
||
- 知识库：`PATCH /knowledge-bases/{id}/status`
|
||
- 三个总开关：`PUT /settings` 中的 `featureGates`
|
||
|
||
---
|
||
|
||
## 13. WebSocket 通用协议
|
||
|
||
### 13.1 连接和订阅
|
||
|
||
连接成功事件：
|
||
|
||
```json
|
||
{
|
||
"eventId": "evt_01J3...",
|
||
"type": "connection.ready",
|
||
"occurredAt": "2026-07-21T09:35:00Z",
|
||
"payload": {
|
||
"clientId": "desktop-main-7cb8",
|
||
"heartbeatSeconds": 20,
|
||
"resumeAccepted": true
|
||
}
|
||
}
|
||
```
|
||
|
||
客户端订阅：
|
||
|
||
```json
|
||
{
|
||
"type": "subscribe",
|
||
"requestId": "client_req_1",
|
||
"payload": {
|
||
"channels": ["engine", "logs", "distill:distill_01J3", "files:file_01J3"]
|
||
}
|
||
}
|
||
```
|
||
|
||
服务端确认：
|
||
|
||
```json
|
||
{
|
||
"eventId": "evt_01J4...",
|
||
"type": "ack",
|
||
"occurredAt": "2026-07-21T09:35:00.010Z",
|
||
"requestId": "client_req_1",
|
||
"payload": { "acceptedChannels": ["engine", "logs", "distill:distill_01J3", "files:file_01J3"] }
|
||
}
|
||
```
|
||
|
||
### 13.2 服务端事件包络
|
||
|
||
```json
|
||
{
|
||
"eventId": "evt_01J5...",
|
||
"type": "engine.state.changed",
|
||
"occurredAt": "2026-07-21T09:35:01Z",
|
||
"requestId": "req_01J3...",
|
||
"resource": { "type": "engine", "id": "local" },
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
### 13.3 事件清单
|
||
|
||
| type | channel | payload |
|
||
|---|---|---|
|
||
| `engine.state.changed` | `engine` | 完整 `EngineState`，不是局部 patch |
|
||
| `engine.startup_check.updated` | `engine` | `runId`、`state`、完整 `checks[]` |
|
||
| `engine.annotation.changed` | `engine` | `annotationComplete`、`revision`、`updatedAt` |
|
||
| `log.appended` | `logs` | 单条完整 `LogEvent` |
|
||
| `file.processing.updated` | `files:{fileId}` | 文件处理进度对象 |
|
||
| `knowledge.changed` | `knowledge:{id}` | `KnowledgeSummary` |
|
||
| `agent.changed` | `agent:{id}` | `AgentSummary` |
|
||
| `agent.test.message.accepted` | `agent-test:{sessionId}` | 消息受理对象 |
|
||
| `agent.test.message.delta` | `agent-test:{sessionId}` | token 增量对象 |
|
||
| `agent.test.message.completed` | `agent-test:{sessionId}` | 完成对象 |
|
||
| `agent.test.message.failed` | `agent-test:{sessionId}` | 错误对象 |
|
||
| `distill.progress.updated` | `distill:{jobId}` | 完整进度对象 |
|
||
| `distill.evaluation.updated` | `distill:{jobId}` | 评估状态和结果摘要 |
|
||
| `employee.changed` | `employee:{id}` | `EmployeeSummary` |
|
||
| `settings.changed` | `settings` | `revision`、`changedSections[]`；前端收到后重新 GET |
|
||
| `export.completed` | `exports:{exportId}` | `exportId`、`status`、`fileId`、`error` |
|
||
|
||
### 13.4 心跳、重连和顺序
|
||
|
||
- 服务端每 20 秒发送 `ping`，客户端 10 秒内返回 `pong`。
|
||
- 事件在单连接内按 `eventId` 顺序发送；业务顺序以资源 `revision` 为准。
|
||
- 前端忽略 `revision` 小于当前状态的迟到事件。
|
||
- 断线后指数退避：1s、2s、4s、8s，最大 15s。
|
||
- 重连时用最后一个已处理 `eventId` 申请新 ticket；事件缓存建议保留 10 分钟。
|
||
- 无法续传时 `connection.ready.payload.resumeAccepted=false`，前端必须重新 GET 当前页面资源。
|
||
- WS 只负责通知和流式增量；创建、更新、删除仍由 HTTP 完成。
|
||
|
||
---
|
||
|
||
## 14. Tauri 原生 IPC：不得改成 HTTP/WS 的能力
|
||
|
||
这些接口仍是 API 契约，但调用形式只允许 `invoke(command, payload)`。标注调试全程在本机 React/Tauri/Rust 内完成，直接操作本机窗口、截图和应用生命周期。
|
||
|
||
本地边界：
|
||
|
||
1. `src/pages/AnnotationPage.jsx` 和 `src/overlay.js` 不调用业务 HTTP 或 WebSocket。
|
||
2. 截图字节、截图路径、窗口句柄、窗口元数据、标注区域和未保存会话状态不得发送给 Go 后端服务。
|
||
3. Go 后端不提供标注调试接口，也不读取标注调试状态；保存和加载只通过 Tauri/Rust 本地存储。
|
||
4. Tauri event 只在本机 WebView 窗口之间传递，不桥接到业务 WebSocket。
|
||
|
||
### 14.1 标注区域对象
|
||
|
||
```json
|
||
{
|
||
"id": "region_01J3...",
|
||
"name": "聊天内容",
|
||
"type": "chat_content",
|
||
"description": "微信当前会话消息区",
|
||
"bbox_image": [120, 180, 860, 1240],
|
||
"bbox_source": [80, 120, 573.333, 826.667],
|
||
"bbox_screen": [420, 280, 1160, 1340],
|
||
"scaleFactor": 1.5
|
||
}
|
||
```
|
||
|
||
坐标统一为 XYXY：`[x1, y1, x2, y2]`。生产必需类型：
|
||
|
||
- `conversation_header`
|
||
- `chat_content`
|
||
- `input_box`
|
||
- `send_button`
|
||
|
||
`custom` 只能附加，不能代替必需类型。
|
||
|
||
### 14.2 IPC 命令
|
||
|
||
| command | 请求 | 返回 |
|
||
|---|---|---|
|
||
| `enter_window_select_mode` | `{}` | `{ mode: "window_select" }` |
|
||
| `capture_screen` | `{}` | `CaptureResult` |
|
||
| `read_screenshot_bytes` | `{ path }` | `number[]` 或二进制 buffer |
|
||
| `load_regions` | `{}` | `AnnotationConfig | null` |
|
||
| `save_regions` | `{ annotation: AnnotationConfig }` | `{ path, revision, updatedAt }` |
|
||
| `start_vision_stream` | `{}` | `{ state: "running" }` |
|
||
| `stop_vision_stream` | `{}` | `{ state: "stopped" }` |
|
||
| `start_agent` | `{}` | `{ state: "running" }` |
|
||
| `stop_agent` | `{}` | `{ state: "stopped" }` |
|
||
| `open_popup_window` | `{ route }` | `{ label }` |
|
||
| `close_current_window` | `{}` | `null` |
|
||
| `exit_application` | `{}` | `null` |
|
||
|
||
`CaptureResult`：
|
||
|
||
```json
|
||
{
|
||
"screenshotPath": "受限应用数据目录中的路径",
|
||
"screenshotWidth": 1440,
|
||
"screenshotHeight": 900,
|
||
"scaleFactor": 1.5,
|
||
"source": {
|
||
"id": "win-window:12345",
|
||
"kind": "window",
|
||
"label": "WeChat",
|
||
"appName": "WeChat.exe",
|
||
"title": "微信",
|
||
"pid": 4312,
|
||
"x": 200,
|
||
"y": 100,
|
||
"width": 960,
|
||
"height": 600,
|
||
"scaleFactor": 1.5
|
||
},
|
||
"screenListMs": 12,
|
||
"captureMs": 40,
|
||
"saveMs": 8,
|
||
"totalMs": 60
|
||
}
|
||
```
|
||
|
||
`AnnotationConfig`：
|
||
|
||
```json
|
||
{
|
||
"app": "wechat",
|
||
"screenshotPath": "受限应用数据目录中的路径",
|
||
"screenshotWidth": 1440,
|
||
"screenshotHeight": 900,
|
||
"scaleFactor": 1.5,
|
||
"source": {},
|
||
"regions": [],
|
||
"createdAt": "2026-07-21T09:40:00Z",
|
||
"updatedAt": "2026-07-21T09:42:00Z",
|
||
"revision": 3
|
||
}
|
||
```
|
||
|
||
原生保存成功后由 Tauri event 发送：
|
||
|
||
```json
|
||
{
|
||
"event": "annotation-completion-changed",
|
||
"payload": true
|
||
}
|
||
```
|
||
|
||
引擎状态变化沿用：
|
||
|
||
```json
|
||
{
|
||
"event": "engine-state-changed",
|
||
"payload": { "enabled": true }
|
||
}
|
||
```
|
||
|
||
标注调试状态只允许 Tauri/Rust 本地模块读取。HTTP 业务服务和 Go 后端不得读取、同步或转发截图、窗口信息及标注区域。
|
||
|
||
---
|
||
|
||
## 15. 页面到接口映射
|
||
|
||
| 页面/窗口 | 源文件 | 初始加载 | 用户操作 | 实时事件 |
|
||
|---|---|---|---|---|
|
||
| 微信分身 | `src/pages/ClonePage.jsx` | `/bootstrap`、`/engine/state` | 启动检查、启动/停止引擎、暂停自动发送；标注走 Tauri IPC | `engine.*`、`log.appended` |
|
||
| 运行日志 | `src/windows/EngineLogsWindow.jsx` | `GET /logs` | 导出日志；清空/暂停是前端视图操作 | `log.appended`、`export.completed` |
|
||
| 知识库列表 | `src/pages/KnowledgePage.jsx` | `GET /knowledge-bases` | 搜索、打开详情 | `knowledge.changed` 可选 |
|
||
| 新增/更新知识库 | `src/windows/KnowledgeWindows.jsx` | 创建/读取 knowledge draft | 上传文档、图片或视频；预览转换后的 TXT；人工填写媒体描述；移除、发布 | `file.processing.updated`、`knowledge.changed` |
|
||
| 知识库详情、预览、引用、版本 | `src/windows/KnowledgeWindows.jsx` | knowledge detail/files/references/versions | 预览、下载、启停、更新、删除 | `knowledge.changed`、文件处理事件 |
|
||
| 智能体市场 | `src/pages/SkillsPage.jsx` | `GET /agents` | 搜索、筛选、启停、打开详情 | `agent.changed` 可选 |
|
||
| 新增/更新智能体 | `src/windows/SkillWindow.jsx` | 创建/读取 agent draft | 基本信息、提示词、知识授权、测试、发布 | 测试会话事件 |
|
||
| 智能体详情 | `src/windows/SkillWindow.jsx` | `GET /agents/{id}` | 更新、测试、启停、删除 | `agent.changed` |
|
||
| 测试智能体 | `src/components/AgentChatPanel.jsx` | 创建 test session、加载 messages | 上传附件、发送、取消生成 | `agent.test.*` |
|
||
| 员工蒸馏主页 | `src/pages/DistillPage.jsx` | active jobs、employees | 搜索、取消任务、打开详情 | `distill.progress.updated` |
|
||
| 开始蒸馏 | `src/windows/DistillWindows.jsx` | 创建/读取 distill draft | 上传文件、开始提取、重新评估、导出、发布 | `file.processing.updated`、`distill.*` |
|
||
| 员工详情 | `src/windows/DistillWindows.jsx` | `GET /employees/{id}` | 启停、编辑画像、管理授权、重新蒸馏、复制 | `employee.changed` |
|
||
| 设置 | `src/windows/SettingsContent.jsx` | `GET /settings` | 保存/恢复、Key 更换/删除、连接测试、名单 CRUD | `settings.changed` |
|
||
| 标注调试页 | `src/pages/AnnotationPage.jsx` | Tauri `capture_screen/load_regions` | 画框、编辑、删除、保存 | Tauri annotation event |
|
||
| 原生透明标注层 | `src/overlay.js` | Tauri overlay state | 选窗、画框、编辑、删除、保存或取消 | Tauri annotation event |
|
||
|
||
---
|
||
|
||
## 16. 前端交互约束
|
||
|
||
1. 所有页面首次打开必须显示 loading，失败显示真实错误和重试入口；不得用 mock 数据补成功状态。
|
||
2. 按钮发起 mutation 后立即禁用，直到响应完成；重复点击依赖 `Idempotency-Key` 兜底。
|
||
3. 搜索输入建议 250ms debounce；新的请求发出时取消旧请求，避免旧结果覆盖新结果。
|
||
4. 详情窗口更新后关闭原窗口没有问题，但重新打开详情必须 GET 最新资源，不能依赖 `localStorage` 或 `BroadcastChannel` 作为业务事实源。
|
||
5. WS 事件只更新同 revision 或更新 revision；发生缺号或冲突时重新 GET。
|
||
6. 文件选择后先展示本地文件名和上传进度；只有 `FileAsset.status=ready` 才显示“格式有效/可预览”。
|
||
7. 智能体测试期间禁用下一步、附件移除和重复发送；`completed` 后才标记测试通过。
|
||
8. 蒸馏后台运行时关闭窗口不取消任务；再次打开按 jobId 查询并续订频道。
|
||
9. 删除响应成功后从列表移除；`409 RESOURCE_IN_USE` 必须显示引用资源，不得假装删除成功。
|
||
10. 配置保存以服务端返回的完整对象替换本地表单基线；连接测试不自动保存配置。
|
||
|
||
---
|
||
|
||
## 17. 实施顺序
|
||
|
||
1. **基础层**：HTTP client、错误模型、session token、SQLite repository、revision、WebSocket ticket/重连。
|
||
2. **设置与知识库**：消除 API Key、本地配置、知识列表和创建流程中的 mock/localStorage。
|
||
3. **文件中心**：上传、解析、预览、清理和处理进度事件。
|
||
4. **智能体**：草稿、授权、测试 WS 流式输出、发布和详情。
|
||
5. **蒸馏与员工**：后台任务、进度、评估、发布和详情子资源。
|
||
6. **引擎与日志**：将现有 Tauri/sidecar 状态映射成结构化 HTTP/WS 契约，同时保留标注为 Tauri IPC。
|
||
|
||
完成判定：页面展示字段均来自上述响应；所有可操作按钮有真实 mutation；长任务和流式生成有可恢复事件；上传、解析失败、并发冲突和断线重连都有明确结果。
|