API 概览
Lyncore 提供一套 REST + SSE API，可在外部程序或脚本中驱动对话、Agent、知识库、记忆、工作流等能力。
版本说明：Lyncore 分两个编译产物——个人版（Lite） 与 企业版（Enterprise），通过 Go build tag
lite区分。两者路由表不同，企业版独有与个人版独有的端点在下文中以标注区分（[企业]/[个人]）。未标注的端点两者都提供。
基础信息
| 项目 | 个人版（Lite） | 企业版（Enterprise） |
|---|---|---|
| 默认监听地址 | http://127.0.0.1:19824 | http://0.0.0.0:8080 |
| 主 API 前缀 | /api/v1 | /api/v1 |
| V4 子系统前缀 | /api/v4 | /api/v4（另注册别名 /api/v1/v4） |
| 协议 | HTTP + SSE（流式） | HTTP + SSE |
| 认证 | Authorization: Bearer <token> | Authorization: Bearer <token> |
| 内容类型 | application/json | application/json |
端口可通过 CLI flag --port（个人版）或配置项 server.port（企业版，默认 8080）覆盖。
认证
API 使用 JWT Bearer 认证。先调用登录接口换取令牌：
POST /api/v1/auth/login
Content-Type: application/json
{"username": "admin", "password": "your-password"}返回 access_token / refresh_token，之后所有请求在请求头携带：
Authorization: Bearer <access_token>- 个人版：
/api/v1/auth/login为桩实现，接受任意用户名/密码，签发lite-admin管理员令牌，不校验密码；本地单用户，租户固定为default。 - 企业版：校验凭据，支持多租户、RBAC、OIDC SSO（
/api/v1/auth/oidc/login）。管理员可在/api/v1/admin/users/:id/api-keys为用户签发 API Key，Key 同样可作为 Bearer 令牌使用。 - 缺失或非法
Authorization头返回40100。
个人版下
/api/v1/skills/*、/api/v1/knowledge/*、/api/v4/tools/execute、/api/v1/usage/stats、/api/v1/briefing、/api/v1/mcp等部分端点未挂载鉴权中间件，仅做租户兜底或完全公开，请勿在不可信网络暴露。
核心端点速览
| 分类 | 方法 | 路径 | 版本 | 说明 |
|---|---|---|---|---|
| 对话 | POST | /api/v1/chat | 两者 | 发送消息（SSE 流式） |
| 对话 | POST | /api/v1/chat/approval | 个人 | 人工审批回填 |
| 对话 | POST | /api/v1/chat/clarification | 个人 | 澄清回填 |
| 会话 | GET/POST | /api/v1/chat/conversations | 两者 | 会话列表 / 创建 |
| 会话 | GET/PATCH/DELETE | /api/v1/chat/conversations/:id | 两者 | 会话详情 / 更新 / 删除 |
| 会话 | GET | /api/v1/chat/conversations/search | 两者 | 搜索会话 |
| Agent | GET/POST | /api/v1/agents | 两者 | 列出 / 创建 Agent |
| Agent | PUT/DELETE | /api/v1/agents/:id | 两者 | 更新 / 删除 Agent |
| Agent | POST | /api/v1/agents/:id/run | 企业 | 运行 Agent（异步） |
| 知识库 | GET/POST | /api/v1/knowledge/documents | 两者 | 文档列表 / 上传 |
| 知识库 | DELETE | /api/v1/knowledge/documents/:id | 两者 | 删除文档 |
| 知识库 | POST | /api/v1/knowledge/search | 两者 | 语义检索 |
| 知识库 | GET/POST | /api/v1/knowledge/mining | 两者 | 对话挖掘列表 / 触发 |
| 知识库 | POST | /api/v1/knowledge/create | 个人 | 建知识库 |
| 知识库 | POST | /api/v1/knowledge/:kb_id/upload | 个人 | 上传入库 |
| 记忆 | GET/POST | /api/v1/memory | 两者 | 记忆列表 / 创建 |
| 记忆 | PUT/DELETE | /api/v1/memory/:id | 两者 | 更新 / 删除记忆 |
| 记忆 | POST | /api/v1/memory/search | 两者 | 语义检索记忆 |
| 模型 | GET/POST | /api/v4/llm/models | 两者 | 模型列表 / 新增 |
| 模型 | PUT/DELETE | /api/v4/llm/models/:name | 两者 | 更新 / 删除模型 |
| 模型 | POST | /api/v4/llm/chat | 两者 | 直连 LLM 补全 |
| 模型 | PUT | /api/v4/llm/models/:name/default | 个人 | 设默认模型 |
| 技能 | GET/POST | /api/v1/skills | 两者 | 技能列表 / 创建 |
| 技能 | GET/POST | /api/v1/skills/marketplace/search、/install | 两者 | 市场搜索 / 一键安装 |
| 工作流 | POST/GET | /api/v1/dag ⚠️ | 个人 | 已退役（410 Gone）；DAG 仅作对话式任务分解内部执行体，不暴露独立接口 |
| 工作流 | POST | /api/v1/dag/stream ⚠️ | 个人 | 已退役（410 Gone） |
| 工作流 | POST/GET | /api/v1/longtask | 两者 | 长任务创建 / 列表 |
| 工作流 | GET/POST | /api/v1/evolution/workflows/* | 个人 | 自进化工作流蓝绿/看门狗 |
| 调度 | POST/GET | /api/v4/scheduler/* | 两者 | 定时任务 |
| 浏览器 | POST | /api/v4/browser/{screenshot,read,act,snapshot} | 两者 | 浏览器操作 |
| 桌面 | POST | /api/v4/desktop/* | 个人 | 桌面控制（需 cua-driver） |
| 媒体 | POST | /api/v4/media/tts、/asr、/image-gen | 个人 | TTS / 语音识别 / 文生图 |
| 文件 | POST/GET | /api/v1/files、/api/v1/sandbox/* | 两者 | 文件与沙箱 |
| 计费 | GET | /api/v1/billing/summary | 两者 | 用量与账单 |
| 激活 | POST/GET | /api/v1/activation/* ⚠️ | 两者 | 已移除（激活改为内置流程，无独立 HTTP 端点） |
| 租户 | GET/POST | /api/v1/tenants | 企业 | 租户管理 |
| 用户 | GET/POST | /api/v1/admin/users | 企业 | 用户管理 |
| 审计 | GET | /api/v1/admin/audit/* | 企业 | 审计与合规 |
| 指标 | GET | /metrics | 企业 | Prometheus 指标 |
| 指标 | GET | /api/v1/usage/stats、/api/v1/briefing | 个人 | 用量统计 / 简报（无鉴权） |
| A2A | GET | /.well-known/agent.json | 两者 | AgentCard |
| A2A | POST | /a2a/tasks/send、/sendSubscribe | 两者 | 提交 Agent 任务 |
| MCP | POST | /api/v1/mcp | 两者 | MCP JSON-RPC 入口 |
| 通道 | POST | /api/v1/webhook/{feishu,dingtalk,wecom} | 企业 | 消息通道回调 |
注意：代码层面不存在
/api/v1/sessions、/api/v1/users/me、/api/v1/models、/api/v1/tools/call、/api/v1/reminders、/api/v1/todos、/api/workflows/*这类路由。会话能力走/api/v1/chat/conversations；用户/租户管理走企业版/api/v1/admin/*与/api/v1/tenants/*；提醒与待办仅作为对话内的 MCP 工具存在，没有独立 HTTP 接口。
流式响应（SSE）
对话（POST /api/v1/chat）与部分工作流端点使用 Server-Sent Events 推送。判定流式方式：请求头 Accept: text/event-stream，或 JSON 体传 "stream": true；否则企业版降级为 202 Accepted 并返回 workflow_id 供轮询。
每一帧为 data: {json}\n\n 形式，JSON 内带 type 字段区分事件类型；首帧为心跳，终止帧为 data: [DONE]\n\n。
POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer <access_token>
{"message": "今天的天气怎么样？", "session_id": "conv_xxx"}响应流（节选）：
data: {"type":"heartbeat"}
data: {"type":"message","delta":"今天"}
data: {"type":"message","delta":"上海"}
data: {"type":"tool_call","name":"web_search","args":{"query":"上海天气"},"id":"call_xxx"}
data: {"type":"tool_result","id":"call_xxx","result":"上海 25-32°C，多云"}
data: {"type":"message","delta":"根据查询结果，今天上海多云，气温 25 到 32 度。"}
data: {"type":"done","usage":{"prompt_tokens":120,"completion_tokens":45}}
data: [DONE]常见 type：heartbeat（心跳）、message（文本增量，含 delta）、tool_call（工具调用）、tool_result（工具结果）、done（完成，含 usage）、error（错误）。企业版心跳以 SSE 注释 : heartbeat 形式发送。
响应与错误格式
所有非流式响应包裹在统一结构体中：
{
"code": 0,
"data": { },
"message": "ok",
"request_id": "req_abc123"
}错误响应（code 非零，data 通常省略）：
{
"code": 40100,
"message": "missing or invalid Authorization header",
"request_id": "req_abc123"
}错误码：
| code | 含义 |
|---|---|
0 | 成功 |
40001 | 参数错误 |
40100 | 未认证（缺失/非法令牌） |
40101 | refresh token 已泄露/失效 |
40200 | 需要付费 / 许可证未激活 |
40300 | 无权限 |
40400 | 资源不存在 |
40900 | 资源冲突 |
42200 | 语义错误（业务校验未通过） |
42900 | 请求过于频繁（限流） |
50000 | 未知错误 |
50001 | 内部错误 |
50300 | 服务不可用 |
50400 | 超时 |
分页数据 data 形态为 { "items": [...], "total": N, "page": 1, "page_size": 20, "total_pages": M }。