LuckyAgent API
lh serve · /api/v1

接口参考

默认基址 http://127.0.0.1:9090。这页写调用时需要的方法、字段、响应和失败条件。没有 OpenAPI 或 Swagger。路由注册在 luckyagent-api,行为在 luckyagent-app。字段示例与仓库 docs/API.md 保持同一口径;两者不一致时以 handler 为准。

鉴权密钥放在头里。空密钥只允许本机回环。
对话SSE 不补发。可重试投递走 WebSocket。
变更插件和部分配置保存后要重启进程才进入运行时。

约定

所有应用路由都在 /api/v1。GET / 只返回一份简短路由摘要,不是这页的替代。

传输
项规则
JSON默认 2 MiB,必须是一个完整 JSON 值。显式不支持的 Content-Type 返回 415。省略该头的旧客户端仍可使用。
上传POST /api/v1/uploads 使用 multipart,单次请求上限 32 MiB。字段名是 file 或 files。
密钥查询字符串中的 API key 会被拒绝。响应不回传密钥、token、密码或额外请求头。
关联响应带 X-Request-ID。错误体里的 request_id 用同一个值。
最小检查
lh serve --addr 127.0.0.1:9090
curl http://127.0.0.1:9090/api/v1/health/live
curl http://127.0.0.1:9090/api/v1/health/ready

鉴权与错误

配置了 server.api_keys 时,每个业务请求都要带密钥。未配置时,只有回环连接、回环 Host、同源或缺失的 Origin,且没有转发头,才允许无密钥访问。同机反向代理也要配置密钥。

请求头
X-API-Key: <key>
Authorization: Bearer <key>

lh qr 签发的临时 key 只在进程内存中,默认 24 小时,重启后失效,不写入 config.json。GET/HEAD /、/health/live、/health/ready 公开。/health/detail 走普通鉴权。

错误体
{
  "error": "message",
  "code": 400,
  "error_code": "invalid_request",
  "request_id": "server-generated-id",
  "details": "optional details"
}
状态含义
400字段缺失、JSON 无效或业务校验失败。
401 / 403缺少密钥 / 密钥无效。
404 / 405 / 409 / 410资源不存在 / 方法不允许 / 冲突或版本过期 / 会话已被并发删除。
413 / 415 / 429请求体过大 / 媒体类型不支持 / 超过每分钟配额。429 带 Retry-After: 60。
500 / 502 / 503 / 504内部错误 / 上游连接失败 / 服务未初始化 / 操作超时。

聊天

POST/api/v1/chat

SSE 流式对话。省略 session_id 会新建会话。传入的会话不存在时,在调用模型前返回 404。max_iterations 取 0 到 300,0 使用配置默认值。

请求
字段说明
message用户文本。插件命令写成 /plugin:command args 时,会在内置斜杠路由之前按原样展开。
session_id可选。已有会话必须存在。
stream这个端点本身就是 SSE。
max_iterations0–300。
auto_approve是否自动批准本轮工具。
metadata调用方附加对象,例如 {"source":"http"}。
attachments先用上传接口拿到附件对象,再放进这个数组。WebSocket 单帧上限 64 KiB,文件字节不要直接塞进消息。
示例
curl -N http://127.0.0.1:9090/api/v1/chat \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <key>' \
  -d '{"message":"hello","max_iterations":8}'
每个 SSE 帧保留事件类型和内容,并带 run_id、event_id 和 id:。失败帧含字符串 error、error_code 和 status:"failed",后面不再跟成功的 complete。取消是 type:"cancelled"。只有完整结束的一轮才是 complete 且 status:"completed"。SSE 不重放持久游标,再次 POST 会开新一轮。
POST/api/v1/chat/sync

同步返回整包。请求字段与流式接口相同。成功响应使用实际保存消息的会话,没有无会话回退。

响应
{
  "response": "assistant response",
  "session_id": "session-id",
  "iterations": 1,
  "tokens_used": 0,
  "tool_calls": [],
  "duration": "1.2s"
}

会话

GET/api/v1/sessionsPOST

列表支持 q、limit、offset。q 匹配标题、ID 和项目。置顶会话排在前面。条目含 format(legacy_md 或 segment_v1)、byte_size、pinned、project。

创建
{"title":"可选标题"}
GETPATCHDELETE/api/v1/sessions/{id}
查询说明
limit / offset从最新消息向前分页。offset 是从末尾跳过的条数。不带 limit 时返回全部消息。
include=full 或 full=1返回完整正文。默认按 context.history_preview_chars 截断,缺省 4000 个字符。
profile=1附加 agent_system_prompt。

响应含 content_truncated、format、byte_size。存储或解码失败返回 500,不会假装历史为空。句柄已被并发删除返回 410,未知 ID 返回 404。

修改,至少一个字段
{"title":"新名字","pinned":true,"project":"luckyagent"}

空 title 被拒绝。空 project 清除分组。改名和置顶只写元数据,不重写历史。删除返回 {"id","deleted":true},并取消这个 Agent 拥有的在途 HTTP 和 WebSocket 工作。删除存储失败时不取消任务。

GET/api/v1/sessions/{id}/activity

这个会话还没结束的聊天回合。不是任务列表,普通聊天也会出现。没有未结束回合时 runs 是空数组,不返回已完成历史。

字段说明
runs[].run_id持久化回合 ID。
runs[].state只有 queued 或 running。
runs[].updated_at这条回合记录的最后更新时间。
读持久化记录失败时返回 500,不会把失败伪装成没有正在工作。WebSocket 终态使用同一套词:completed、cancelled、error。重连回放的状态帧带 replay:true。
GET/api/v1/sessions/{id}/tools

分页工具轨迹。limit 默认 100,上限 200。offset 从最新调用向前跳。turn=first 只取原始首轮;压缩已经盖住原始轮次时返回 410。

响应字段说明
tools[]id、name、arguments、result、success、error、duration_ms、status、annotation。
statuspending、completed、failed。pending 只表示还没有记录结果。
汇总total_calls、returned、has_more、successes、failures、pending_calls、success_rate。
成功率和成功/失败计数只统计已有结果的调用。参数、结果和错误在序列化前截断。没有写入 duration_ms 的旧消息读出来是 0。轨迹不含未记录的内部推理。
备份与压缩
方法路径说明
GET/sessions/{id}/backups返回 backups 和 count。
POST/sessions/{id}/backups/{backup}/restore恢复后完整重写历史。响应含 message_count。
POST/sessions/{id}/compact体可含 dry_run、force_local。响应含 token 估计、summary_source 和 display。
GET/sessions/{id}/compact/latest没有记录时 404。

流式对话中的自动压缩会发 type:"compact",phase 为 start、progress、done、failed 或 degraded。WebSocket 把同样字段放在 data 里。

命令与插件

GETPOST/api/v1/commands

目录包含启动时加载的内置命令和已启用插件命令。GET 返回 commands 与 count。每项有 name、usage、description、group。插件项的 group 是 plugins,名称保持 plugin:command 的大小写和连字符。

执行
{
  "command": "starter:review",
  "args": "UI/HTTP-API.go --Keep-Case",
  "session_id": "optional-existing-session-id"
}

省略会话会新建。传入的会话不存在返回 404。成功和循环失败都可能是 HTTP 200,必须看 ok。带附件或每轮选项时改用 /chat/sync。

{"command":"starter:review","ok":true,"output":"assistant response","session_id":"session-id"}
/api/v1/plugins
方法路径说明
GET / POST/plugins列出或安装。安装体最多 16 KiB:source 必填,可选 ref、subdir、trust。
GET / DELETE/plugins/{name}详情为 {plugin}。删除保留不可变缓存,响应里 plugin 为 null。
POST/plugins/{name}/enable保存启用。可发送 {}。
POST/plugins/{name}/disable保存停用。
POST/plugins/{name}/update按已记录来源更新。体最多 4 KiB,只接受 {"trust":false}。
清单中的一项
{
  "name": "starter",
  "version": "1.0.0",
  "source": "https://github.com/team/plugins.git",
  "ref": "v1.0.0",
  "revision": "resolved-commit",
  "enabled": true,
  "trusted": false,
  "skills": ["review"],
  "commands": ["review"],
  "mcp_servers": [],
  "hook_count": 0
}
名称是 1–48 位小写 slug。本地目录指服务器文件系统。不受信任的 MCP 或 hook 插件安装后保持停用;纯提示词插件可以不授予执行信任就启用。Git 与复制限时 90 秒。安装返回 201。这些接口不执行插件,也不重启进程。清单响应带 changes_require_restart: true。损坏项仍可管理并带 error。索引损坏返回错误,不会假装清单为空。

模型与配置

GET/api/v1/models

可选 kind、provider、refresh=1。响应含 models、count、source。发现失败时仍返回列表,并在 error 中说明。

GETPUT/api/v1/models/effort

稳定选项是 auto、none、minimal、low、medium、high、xhigh。auto 不向上游传该参数。当前协议不是 OpenAI 或兼容端点时,supported 为 false。PUT 体是 {"effort":"high"},会保存并作用于后续请求。上游仍可能按模型拒绝某个力度。

POST/api/v1/models/switch
{"kind":"chat","model":"gpt-5.4-mini","provider":"openai"}

GET/POST /api/v1/models/profiles 列出或应用配置档。应用体是 {"name":"profile-name"}。单次请求里的 profile_id 没有定义,不要塞进聊天体。

/api/v1/config
方法行为
GET返回脱敏后的运行配置,并带 ETag。
PUT完整替换,上限 2 MiB。先 GET,再修改,再提交整份文档。被打码的空密钥保留原值。
PATCHJSON Merge Patch。可直接提交补丁,或使用带并发控制的信封。
GET /schema字段路径、类型、默认值、是否敏感、是否热更新。敏感默认值始终是 null。路径分组为 hot、restart、unknown。
POST /reload不打断在途请求。无效配置被拒绝,原配置继续生效。响应列出已生效和仍需重启的组。
带并发控制和清密钥的 PATCH
{
  "patch": {"server": {"progress_summary_with_llm": true}},
  "if_match": "<etag>",
  "clear_secrets": ["models.endpoints.chat.api_key"],
  "dry_run": false
}

响应含脱敏 config、变更路径、hot_reloaded、restart_required、applied、persisted 和新 version。过期的 If-Match 返回 409。监听地址、鉴权、网关和启动期服务会保存,但要重启或重建服务。

工具、技能、MCP 与上传

GET/api/v1/tools

当前进程已注册、可供模型调用的工具。它不是会话里的调用轨迹;轨迹在 /sessions/{id}/tools。

/api/v1/skills
方法路径说明
GET/skills技能列表。
GET / DELETE/skills/{name}详情或卸载。卸载也接受 POST,体可含 {"purge":false}。
POST/skills/{name}/enable|disable|reload状态机拒绝时返回 409,不是 400。
POST/skills/{name}/rollback回滚到已记录版本。
GET/skills/{name}/versions版本记录。
POST/skills/install准备安装。install、installs、reload 是保留路径。
POST/skills/reload重载全部,返回 loaded 和 skills_dir。
GETPOST/api/v1/mcp/servers

只接受配置里已经声明的服务名。传输、命令和环境仍在配置中,不由这个接口改写。

{"name":"filesystem","action":"connect"}

action 只能是 connect、refresh、disconnect。未知动作返回 400。连接失败返回 502。成功后返回最新 servers 状态。

POST/api/v1/uploads

multipart 字段名是 file,多个文件可用 files。没有文件返回 400。文件按日期写到运行目录,响应含 attachments 和 count。把返回的附件对象放进聊天请求的 attachments。

GET /api/v1/artifacts 读取已经生成或上传的产物。

任务、自治与审批

GET/api/v1/tasks

查询参数 source、status、parent_id、limit。响应是 {"tasks":[],"count":0}。单个任务、树、事件、规划轨迹、结果和观察分别是:

GET /api/v1/tasks/{id}
GET /api/v1/tasks/{id}/tree
GET /api/v1/tasks/{id}/events
GET /api/v1/tasks/{id}/trace
GET /api/v1/tasks/{id}/result
GET /api/v1/tasks/{id}/observation
反馈与取消
POST /api/v1/tasks/{id}/feedback
{"status":"completed","verified":true,"verifier":"user","user_feedback":"accepted","score":0.9,"recommended_next":"finalize"}

POST /api/v1/tasks/{id}/cancel
{"reason":"stop now"}
模型工具 delegate_task 创建的任务,不一定出现在 HTTP /api/v1/agents/tasks。查运行时任务用这里的 /tasks。
GET/api/v1/autonomy/dashboard

只读队列、worker、心跳和任务快照。可选 state=ready|in_progress|blocked|done 和 limit,默认上限 200。它不启动也不改变自治运行时。GET /autonomy/tasks/{id} 返回操作摘要和是否有检查点,不返回完整检查点载荷。GET /api/v1/cron 列出定时任务。创建、暂停、恢复和删除由 Agent 的 AddCronJob / PauseCronJob / ResumeCronJob / RemoveCronJob 提供,HTTP 写路由在 API 模块接线后开放。

GETPOST/api/v1/approvals

GET 可按 provider、session_id 过滤,返回 approvals 和 count。POST 与 POST /approvals/resolve 都解决一条审批。

{"provider":"codex","approval_id":"a1","decision":"allow","input":"session-id"}

provider、approval_id、decision 都必填。值对客户端保持中立,Android 可以用同一张审批卡渲染。

记忆、上下文与 RAG

GETPOST/api/v1/memory

GET 返回短、中、长期计数。POST 保存一条记忆。content 必填,category 缺省为 user。long_term:true 写入长期层。

{"content":"Remember this","category":"project","long_term":false}

GET /memory/recall?q=project 召回,q 必填。还有 GET /memory/recall/trace、/memory/stats、/memory/graph。

GET/api/v1/contextPOST/api/v1/context/fit
查询说明
session_id使用该会话历史。未知 ID 返回 404,不创建会话。
inspect=1附加 usage 和 sections。否则只返回配置。
message假设的下一条用户消息。空值只检查手上的上下文。
include_messages=1把完整段落放进 sections[].content。默认只给 160 字预览。

usage 是本地规划估计,不是供应商账单。usage.ratio 是 total_tokens / available_tokens。桶有 system、project、history、memory、rag、tool_result、user。检查不写记忆、会话或上下文缓存。

装入窗口
{"messages":[{"role":"user","content":"hello","priority":1,"category":"chat"}],"strategy":"sliding_window"}

strategy 可以是 oldest_first、low_priority_first、sliding_window、summarize。这个接口不组装当前规划器的实时上下文。

/api/v1/rag
索引
POST /api/v1/rag/index
{"source":"docs/API.md","title":"API","content":"...","dir":"docs"}

dir 索引目录,content 索引内联文本,source 索引单个文件。删除体是 {"doc_id":"..."},方法为 DELETE。

检索
POST /api/v1/rag/search
{"query":"programming language","top_k":5,"min_score":0.1,"use_mmr":true,"mmr_lambda":0.5,"source":"optional"}

GET /rag/stats 和 GET/POST /rag/store 读取或操作持久存储。流式索引器必须已初始化,路径有 /rag/stream/watch、scan、start、stop、status、index、queue、process。watch 体是 {"dir":"..."},立即索引体是 {"path":"..."},处理队列体是 {"batch":10}。

WebSocket 与 gRPC

GET/api/v1/ws
ws://127.0.0.1:9090/api/v1/ws?session=<session-id>

升级请求使用与 HTTP 相同的鉴权头。为每次聊天选择稳定的请求 id。

情况结果
同一会话、同一 ID、同一输入返回已接受的运行和已存储输出,不重复执行。
同一 ID、不同输入REQUEST_CONFLICT。
初始写入失败PERSIST_FAILED,不会排队。运行状态写入成功后才执行。
后续事件写入失败同样报 PERSIST_FAILED,停止执行,不再发送成功输出。
重连type:"reconnect",data.last_message_id 填最后实际收到的事件。服务端有界重放并去重。客户端也要按 event_id 去重。恢复失败是 RECOVERY_FAILED。

type:"lucky" 先收集同一会话的多条消息,data.action 为 on、off、status 或 cancel。收集期间普通聊天先存储,off 时合并成一轮。收集状态只在当前进程内存里。

Agent 已提供 ChatEvent.Duration,中立 turn 适配器会保留这个值。实时 WebSocket 的 data.duration_ms、SSE 的 observe.duration_ms 和 SDK 耗时还需要配套 API/app 接入;只更新 Agent 不会自动增加这些字段。当前 launcher 选择的 app 尚未包含该接入。字段接通后以毫秒计,0 可能表示未测量或不足 1 毫秒;旧消息也可能省略。运行中的工具不补造耗时,失败保留实测值,恢复已完成操作沿用原记录。

任务入库后向所有连接推送 type:"task_event",data 含 type、task_id、parent_id、status、mode、message、progress、session_id、description。定时消息进入会话时仍是没有 run id 的 stream_end。

运行记录保存在运行目录的 JSON 快照和增量 JSONL journal。两者都要备份。旧二进制不能读取新 journal 在最后一个快照之后的条目。保留期 7 天,活跃工作会留下。请求去重不能让进程崩溃后的外部工具副作用变成事务。GET /api/v1/ws/stats 返回 Hub 统计。
gRPC

lh serve 不监听 gRPC。嵌入方使用 luckyagent-app/api/grpc 的 NewGRPCServer,继承应用密钥和配额。Chat 使用真实会话。ChatStream 转发有效 UTF-8,并以一个终止的 Done 结束。错误和取消返回 gRPC 状态。max_iterations 仍是 0–300。非空 metadata 会被拒绝,因为它没有定义语义。

健康、网关与其余资源

方法路径说明
GET/health/live /health/ready公开探针。Docker healthcheck 走容器内 127.0.0.1:9090。
GET/health/detail详细健康,需要普通鉴权。
GET/metrics /stats指标快照和服务统计。
GET/proactive/status?limit=5主动运行状态。
GET/soulname 来自身份 Name: 行,否则取第一处粗体名。system_prompt 是全文。
GET / POST/soul/templates /soul/templates/{id}人格模板。
GET/gateways当前进程内的网关。
POST/gateways/{name}/start在 lh serve 进程内启动。已运行返回 409。不要同时再跑 lh msg-gateway start。其他通道发送 {} 即使用宿主配置。
GET / POST/agents 及 register delegate tasks cancel协作注册表。HTTP 委派和模型工具 delegate_task 的任务视图没有完全打通。
GET / POST/workflows /workflow-instances工作流定义和实例。
GET / POST/embedders /register /switch嵌入器列表、注册和切换。
GET / POST/fc /fc/tools /fc/history函数调用摘要、执行、工具和历史。
函数调用执行体
{"message":"Use available tools to inspect the repo","auto_approve":false,"max_iterations":8}

pprof 不属于 /api/v1。设置 LA_PPROF_ADDR=127.0.0.1:6060 后,该地址才提供 /debug/pprof/、/goroutine、/profile 和 /heap。

核对日期 2026-10-23。字段来自公开包 v1.5.42 选中的 app 159015485c70 与 api 5bc49550b485,页面随主仓文档发布。Android 通过这些 HTTP 和 WebSocket 字段消费后端,不导入 Go 模块。