跳到正文

参考

网关 API

本地网关的 HTTP 接口、WebSocket RPC 与推送事件、方法一览。Quetzal App、网页控制台与飞书通道使用的就是这一套。

#概览

网关的明文 HTTP 只监听本机 127.0.0.1:<gateway.port>(默认 7788,另有 [::1])。

对局域网开放时(gateway.lan 为真,或 gateway.host 不是回环地址,如 0.0.0.0),网关另在 <gateway.host>:<gateway.lanPort>(默认 7789)开 HTTPS / WSS,接口完全相同,局域网上没有明文。证书是运行基座自己生成的自签名证书(ECDSA P-256,10 年,secrets/gateway-tls.key / gateway-tls.crt);指纹是证书 DER 的 SHA-256,写成小写十六进制,原生控制台钉住它。

所有控制入口(App、网页控制台、飞书、主机工具)共用同一个操作层,行为一致,都写审计。main.cjs 旁边有 web/index.html(npm 安装器放的网页控制台)时,网关同时托管这些静态文件。

#HTTP

方法路径说明
GET/health{ok, version, safeMode, mode},无需令牌
GET/auth/local{ok, token}:只在本机明文监听上提供,只给同一台机器上的浏览器(连接来自回环地址、Host 是本机名、有 Origin 时也是本机),让网页控制台打开即登录;其他来源返回 403。本机进程本来就读得到令牌文件,所以信任边界没有扩大;ssh 隧道转发来的连接也算本机
GET/、/<静态文件>网页控制台(web/ 存在时):没有扩展名的未知路径回退到 index.html,带 ETag
GET/pair/info{ok, fingerprint, short, body, version, tls: true},无需令牌:证书指纹(完整与「1a2b 3c4d 5e6f 7a8b」短格式)、身体名、版本
POST/pair/start生成 8 位配对码(字母数字,5 分钟有效;有效期内重复申请不换码,输错多次会锁定),连同证书短指纹通过适配器通知与飞书下发
POST/pair/finish{proof}(或本机明文连接上的 {code})→ {ok, token, fingerprint};proof = hex(PBKDF2-HMAC-SHA256(配对码(大写、去掉空格与连字符), "quetzal-pair-v2|" + 客户端握手时看到的证书指纹, 100000 次, 32 字节))。HTTPS 上只收 proof(带 code 回 400),中间人换了证书就对不上;客户端再核对返回的 fingerprint。400 缺少证明、403 不正确、410 失效或尝试超过 5 次、429 锁定
POST/upload?name=&token=上传一个附件(≤ 50 MiB)→ {ok, file: {id, name, path, rel, mime, size, kind}}
GET/uploads/<rel>?token=下载附件(只能访问 uploads 目录;文档按下载处理,带文件名)

#WebSocket /rpc?token=<令牌>

json
{ "id": 1, "method": "status", "params": {} }
{ "id": 1, "result": { } }
{ "id": 1, "error": { "code": "", "message": "" } }
{ "event": "state", "data": { } }

#推送事件

事件数据
hello{version, safeMode}
state与 status 相同的完整状态(去抖 500ms)
timeline新的时间线条目 {id, ts, kind, title, detail}
approval审批 {id, action, reason, args, status}
sayta 主动说的话
activity进展 {session, conv, origin, channel, ts, kind, …},kind 见下
secret保密输入状态(永远不含值)
canvas.changed一份 canvas 变了 {doc, conv, kind, author?}(kind:新建、修改、改名、删除、评论、运行、从其他身体复制来)
feishu.qr / feishu.registered / feishu.error飞书一键接入

activity.kind:start / queued / steer / step / delta(流式片段)/ text / tool(执行中与执行后各一条)/ alive(15 秒心跳)/ done / error。进行中的每一轮同时保存为快照(sessions.live),客户端随时可以用它完整重建界面。

#方法

观察

方法参数返回
status—{agent, version, body, adapter, heart, physical, stopped, paused, activity, usage, budget, approvals, soul, models, thought}
timeline{limit?, before?, kind?}时间线(倒序),detail 含过程与每步工具调用
messages{limit?}最近对话
audit{limit?, action?}审计记录;action: "sentinel.review" 只看审核结论

交流

方法参数说明
chat.send{text, conv?, turn?, attachments?, mode?}mode:steer(默认,插话)/ queue / interrupt
sessions / sessions.create / sessions.rename / sessions.archive…会话管理;sessions 可按通道、进行中、置顶、项目、时间筛选,按最近更新、创建时间、标题排序(置顶的总在最前)
sessions.pin / sessions.move{id, pinned?} / {id, project}置顶与取消;把会话归到项目或移出
sessions.search{query, limit?}按标题与内容搜索会话,每个会话一条最好的命中(片段与高亮位置、消息 id)
sessions.messages{id, limit?, before?, from?}某会话的对话(含过程记录);from 为消息 id 时从那条消息附近取起(定位搜索结果);attachments 里 ta 生成、随回复发出的文件带 by: "agent"
projects / projects.create / projects.update / projects.delete…项目:名字、简介、项目说明(注入这个项目下会话的系统提示)、颜色与图标、归档;删除不删会话,只解除归属
sessions.live—进行中轮次的快照
poke{note?}戳一下

Canvas(见使用指南)

方法参数说明
canvas.list / canvas.get / canvas.versions{conv?} / {id, version?} / {id}一个会话的 canvas、一份的完整内容(含评论与最近几次运行)、版本历史
canvas.create / canvas.edit / canvas.update / canvas.delete / canvas.restore…新建;保存为新版本(带 base:她刚改过时照样保存,返回 conflict);改标题或语言;删除;恢复到某一版
canvas.run / canvas.runImage{id, version?, timeout?} / {run, name}在沙箱里运行代码(按「执行命令」权限过闸门);取运行生成的图片
canvas.comment / canvas.reply / canvas.resolve / canvas.apply…选中一段加评论(缺省发给 ta)、回复、解决、采纳 ta 的编辑建议
uploads.preview{rel, max?}附件的轻量预览:抽出开头的文字(xlsx 为各工作表的前几行),控制台文件卡片的「预览」用它

保密库:secrets、secrets.delete、secrets.pending、secrets.end。

语音:speech / setSpeech、speechVoices、speechTest。

调节与安全

方法参数
activity{value}(0–4)
pause{paused}
personality{changes: {"tau.curiosity": 2, …}}(有界)
stop / unstop{reason?} / —
permissions / setPermission— / {id, level: allow|review|ask|deny}
sentinel / setSentinel— / {enabled?, model?, timeoutMs?, classes?, onFailure?, hostMode?}:安全审核的配置、可选的风险类别与审核模型
approvals / decide— / {id, approve, note?}
budget / setBudget— / {dailyTokens?, dailyCostUsd?, minBattery?, maxTempC?}
config / setConfig— / {timezone?, brain?, heart?}
restart—
selfUpdate—
supervision / setSupervision— / {enabled}

记忆

方法说明
memory / editMemory / setSoul常驻记忆与人格
journalList / journal日记
notes / note / search笔记与检索
soulConfig / setSoulConfig / soulKey / syncSoul灵魂仓库地址(只接受 SSH)与访问方式 sshMode(deploy / custom + sshKeyPath / system)、本机公钥、立即同步
agent / setAgent身份
bodies登记的身体
soulHistory / soulShow / soulRevert记忆历史、差异、撤销

模型

方法说明
providers / saveProviders读取 / 整份保存(带版本号,不符返回 STALE_CONFIG)
catalog / refreshCatalog / remoteModels模型目录
testModel{ok, latencyMs, message}
moveModel / toggleModel全局顺序与启停

供应商配置结构:

typescript
interface Provider {
  id: string; catalogId: string; name: string; baseUrl: string; enabled: boolean;
  protocol: "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai";
  keys: { id: string; label: string; lastFour: string; enabled: boolean; secret?: string }[];
  models: { id: string; name: string; enabled: boolean; context: number; maxTokens: number; sortOrder: number; cost?: { input: number; output: number } }[];
}
interface ProviderConfig { providers: Provider[]; quickModelId?: string }

飞书:feishu.status、feishu.register、feishu.set。

本页是概览。字段级的完整描述见仓库里的 docs/API.md,两者不一致时以代码为准。