LyncoreLyncore
Lyncore

API 概览 ​

Lyncore 提供一套 REST + SSE API，可在外部程序或脚本中驱动对话、Agent、知识库、记忆、工作流等能力。

版本说明：Lyncore 分两个编译产物——个人版（Lite） 与 企业版（Enterprise），通过 Go build tag lite 区分。两者路由表不同，企业版独有与个人版独有的端点在下文中以标注区分（[企业] / [个人]）。未标注的端点两者都提供。

基础信息 ​

项目个人版（Lite）企业版（Enterprise）
默认监听地址http://127.0.0.1:19824http://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/jsonapplication/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。

鉴权说明（个人版）：GET /api/v1/skills（技能列表）与 /api/v1/knowledge/* 组未挂载鉴权中间件，仅做租户兜底 default，完全公开；其余核心端点（/api/v1/mcp、/api/v1/briefing、/api/v1/chat/approval、/api/v1/chat/clarification 等）均需 Bearer 令牌。注意：/api/v4/tools/execute 仅 dev 模式挂载（生产默认 404）且需鉴权；文档曾列出的 /api/v1/usage/stats 端点代码已不存在，勿调用。请勿在不可信网络暴露任何本地端点。

核心端点速览 ​

分类方法路径版本说明
对话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两者搜索会话
AgentGET/POST/api/v1/agents两者列出 / 创建 Agent
AgentPUT/DELETE/api/v1/agents/:id两者更新 / 删除 Agent
AgentPOST/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/*；个人 /api/v1/marketplace/*两者市场搜索 / 安装 / 连接器（两版路径不同，见 技能市场）
工作流POST/GET/api/v1/dag企业DAG 编排（Temporal 驱动，仅 create/list/get 3 条；dag/stream、dag/:dagID/resume 企业版未注册）；个人版保留 410 Gone 占位路由（含 stream/resume 子路由），DAG 仅作对话式任务分解内部执行体
任务中心GET/POST/api/v4/tasks、/api/v4/tasks/:taskId/{cancel,retry,instruct}两者任务列表 / 详情 / 指令下发与控制
自进化GET/POST/api/v1/evolution/{status,rules,heal,audit,insights,skills}两者技能沉淀 / 规则学习 / 自愈（扩展端点与 workflows 子组为个人版，见 自进化）
工作流GET/POST/api/v1/evolution/workflows/*个人自进化工作流蓝绿/看门狗
调度POST/GET/api/v4/scheduler/*两者定时任务（企业版走 Temporal，含 pause/resume/execute-now/执行历史）
浏览器POST/api/v4/browser/{screenshot,read,act,snapshot}两者浏览器操作（GET /browser/cast 投屏 WebSocket）
桌面POST/api/v4/desktop/*个人桌面控制（需 cua-driver）
目标GET/POST/PUT/api/v4/goal/{active,:id}两者目标管理（见 任务与目标）
通知GET/POST/DELETE/api/v4/notifications/*两者通知中心（见 任务与目标）
内容黄金位GET/POST/api/v4/content-cards/*两者内容卡片（见 任务与目标）
SATCOMPOST/GET/api/v1/satcom/*、/api/v1/inbound/events/:eventName两者卫星协议 / 入站事件（HMAC 验签，见 SATCOM）
媒体POST/api/v4/media/tts、/asr、/image-gen个人TTS / 语音识别 / 文生图
文件POST/GET/api/v1/files/{upload,:id}、/api/v1/sandbox/*两者文件与沙箱（企业版另有 7 端点沙箱管理，见 实例状态）
实例GET/PUT/api/v1/{health,instance,queue,config,diagnostics,telemetry}、/api/v4/profile/ai两者实例状态 / 配置 / 遥测（见 实例状态）
计费GET/api/v1/billing/*两者用量、账单、计费方案（企业版含 plans/overage，见 计费）
授权激活GET/api/v1/activation/status两者本地授权 / 企业授权状态查询；企业版另有 POST /activation/activate（公开）与 POST /activation/deactivate（需登录）；个人版的 /register、/transfer 已随 v2 历史授权码体系退役（恒定 404）
租户GET/POST/api/v1/tenants企业租户管理
用户GET/POST/api/v1/admin/users企业用户管理
审计GET/api/v1/admin/audit/*企业审计与合规
合规GET/POST/DELETE/api/v1/gdpr/*、/api/v1/offboarding/*企业GDPR 与员工离职（见 企业管理）
指标GET/metrics企业Prometheus 指标
指标GET/api/v1/briefing个人每日简报（需 Bearer 令牌）
A2AGET/.well-known/agent.json两者AgentCard（个人版为 lyncore-lite v2.0，开启 Streaming；该路径公开以便协议互发现）
A2APOST/GET/DELETE/a2a/tasks/send、/sendSubscribe、/a2a/tasks/:id/status、/a2a/tasks/:id两者提交 / 查询 / 取消 Agent 任务（该组需鉴权）
MCPPOST/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/v1/longtask、/api/workflows/* 这类路由。会话能力走 /api/v1/chat/conversations；用户/租户管理走企业版 /api/v1/admin/* 与 /api/v1/tenants/*；提醒与待办仅作为对话内的 MCP 工具存在，没有独立 HTTP 接口；长任务（LongTask）已随工作流重构移除，任务查询改走 /api/v4/tasks。

流式响应（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 形式发送。

响应与错误格式 ​

所有非流式响应包裹在统一结构体中：

json
{
  "code": 0,
  "data": { },
  "message": "ok",
  "request_id": "req_abc123"
}

错误响应（code 非零，data 通常省略）：

json
{
  "code": 40100,
  "message": "missing or invalid Authorization header",
  "request_id": "req_abc123"
}

错误码：

code含义
0成功
40001参数错误
40100未认证（缺失/非法令牌）
40101refresh token 已泄露/失效
40200需要付费 / 企业授权未激活
40300无权限
40400资源不存在
40900资源冲突
42200语义错误（业务校验未通过）
42900请求过于频繁（限流）
50000未知错误
50001内部错误
50300服务不可用
50400超时

分页数据 data 形态为 { "items": [...], "total": N, "page": 1, "page_size": 20, "total_pages": M }。

详细文档 ​