后端接口对接清单

这是根据当前 App 前端代码整理出来的后端接口清单。你可以先把这些接口挂到自己的服务器上，后面再逐步补充业务逻辑。

本地默认端口：3030 前端会自动回退到线上地址支持普通 JSON + SSE 流式响应

DeepSeek 对话框测试

在这里直接问问题，页面会调用你服务器上的 /api/llm/chat。

对话测试窗口

输入问题，检查服务器环境变量里的 key 是否可用。

LLM Chat

接口地址

系统提示词

问题

等待输入问题。

模型回答

优先级建议

如果你想先把主链路跑通，建议先实现下面 5 个接口。

1. 健康检查

GET /health

2. 预设人物

GET /api/presets

3. profile 详情

GET /api/profiles/{profileId}

4. arena 运行

POST /api/arena/run

5. arena 流式

POST /api/arena/stream

接口列表

下面是当前前端实际调用到的全部接口。你可以按这个清单逐个实现。

GET

健康检查

/health

用途

前端启动时探活
判断后端是否可用

返回建议

{
  "ok": true,
  "error": null,
  "runtime": {
    "mode": "local"
  },
  "import": {
    "running": false,
    "lastImportedProfileIds": []
  },
  "timestamp": "2026-05-09T00:00:00Z"
}

GET

导入状态

/api/admin/import-status

用途

查看默认资料导入是否完成

返回结构

state
overview

POST

导入默认 profiles

/api/admin/import-defaults

用途

初始化默认人物库

通常返回 ImportStatusResponse

GET

获取预设人物列表

/api/presets

用途

首页、角色选择页展示预设人物

返回结构

presets: PresetProfile[]

GET

获取某个 profile 的完整包

/api/profiles/{profileId}

用途

拉取某个 profile 的详细资料、节点、agents

返回结构

profile
nodes
agents
sourceDocument?

POST

解析人物时间线

/api/timeline/parse

请求体

{
  "displayName": "李雷",
  "biography": "......",
  "profileId": "optional"
}

返回结构

{
  "personId": "p001",
  "displayName": "李雷",
  "nodes": []
}

POST

构建 agents

/api/agents/build

请求体

{
  "personId": "p001",
  "displayName": "李雷",
  "biography": "......",
  "nodes": []
}

返回结构

{
  "agents": []
}

POST

合并 agents

/api/agents/merge

请求体

{
  "primary": {},
  "secondary": {},
  "displayName": "合并后名字",
  "mergePrompt": "optional"
}

返回结构

{
  "agent": {},
  "execution": {
    "requestedModel": "xxx",
    "requestedEffort": "medium",
    "effectiveModel": "xxx",
    "effectiveEffort": "high",
    "fallbackUsed": false,
    "sessionId": "optional",
    "durationMs": 1234
  }
}

POST

发起 arena 对话

/api/arena/run

请求体

{
  "topic": "要讨论的问题",
  "mode": "chat",
  "selectedAgentIds": ["a1", "a2"],
  "agents": [],
  "roundCount": 3,
  "maxMessageChars": 180,
  "guidance": "optional",
  "continueFromRunId": "optional",
  "sessionId": "optional"
}

返回结构

{
  "result": {
    "runId": "r001",
    "mode": "chat",
    "topic": "......",
    "participants": [],
    "messages": [],
    "summary": {}
  },
  "links": {
    "runId": "r001"
  }
}

POST

流式 arena 对话

/api/arena/stream

说明

请求体和 /api/arena/run 一致
返回 text/event-stream
适合前端实时刷新

支持事件

run_started
phase_started
speaker_started
speaker_delta
speaker_completed
message
phase_completed
summary_started
summary_delta
summary
done
error

GET

查询 arena 历史

/api/arena/history?limit=20

返回结构

{
  "runs": []
}

GET

查询某次 run 详情

/api/arena/runs/{runId}

返回结构

{
  "result": {},
  "links": {}
}

POST

中断 session

/api/arena/sessions/{sessionId}/interrupt

返回结构

{
  "ok": true,
  "sessionId": "s001"
}

POST

生成海报

/api/arena/poster

请求体

{
  "runId": "r001",
  "stylePreset": "poster",
  "aspectRatio": "3:4",
  "language": "zh"
}

返回结构

{
  "runId": "r001",
  "links": {},
  "poster": {}
}

POST

上传导入 profile

/api/profile-imports

请求类型

multipart/form-data
importType 必填
file 必填
displayNameHint / title / profileId 可选

返回结构

{
  "bundle": {},
  "import": {}
}

本地端口说明

默认本地地址

http://127.0.0.1:3030
http://localhost:3030
http://10.0.2.2:3030
http://192.168.0.145:3030

结论

你本地后端建议先起在 3030 端口。前端会自动尝试这些地址，连不上再回退到线上服务。