API 参考

Base URL:http://<host>:8765。所有 /api/* 接口在启用鉴权后需携带请求头:

Authorization: Bearer <访问令牌>

令牌两种来源(都通过同一请求头携带):

限流:默认每用户 60 次 / 60 秒(服务端可配置),超限返回 429。 登录/注册接口按来源 IP 独立限流。 响应统一为 UTF-8 JSON;除 /api/chat 外均为普通 JSON 响应。


健康与状态

GET /healthz

健康检查,无需鉴权。

{"ok": true, "version": "0.9.233"}

GET /api/version

版本信息,无需鉴权。

{"name": "trueagt", "version": "0.9.233"}

GET /metrics

Prometheus 指标端点(text/plain; version=0.0.4)。配置了 server.metrics_token 时 需携带 Authorization: Bearer <指标令牌>,未配置则不校验。指标清单见《部署指南》。

# HELP trueagt_chat_total 对话执行总数
# TYPE trueagt_chat_total counter
trueagt_chat_total 42
...

GET /api/status

当前用户视角的智能体状态。

{
  "name": "TrueAGT",
  "model": "qwen3.8-27b-llamacpp",
  "demo": false,
  "user": "alice",
  "tools": ["calculate", "current_time", "http_get", "web_search", "note", "read_file", "recall", "write_file", "mcp__<server>__<tool>", "..."],
  "long_term_count": 12,
  "encryption": {"enabled": true, "fingerprint": "0990-F7BB"}
}

tools:当前会话可用的工具名列表,MCP 桥接的服务器会动态贡献 mcp__<server>__<tool> 形式的工具。encryption:静态加密状态。enabled=true 时会话/记忆密文落盘, fingerprint 为密钥指纹(本机密钥文件的身份标识)。

GET /api/usage

当前用户的累计用量。

{"requests": 42, "prompt_tokens": 38120, "completion_tokens": 9205}

用户与鉴权

GET /api/auth/config

鉴权方式与注册模式(公开,无需令牌)。前端据此决定展示登录页还是直接进入。

{"auth_required": true, "mode": "local", "registration": "invite", "demo": false}

mode:local(本机账号,默认)/ remote(中央注册服务器模式,账号由 server.auth.remote_url 指定的中央统一验证,本地不保存密码)。 registration:open(开放注册)/ invite(邀请码)/ closed(仅管理员创建)。

POST /api/auth/register

注册账号(公开;按来源地址限流)。成功即自动登录并返回动态令牌。 远程模式(mode=remote)下注册请求转发注册服务器,返回本地会话令牌。

POST /api/auth/register
{"username": "张三", "password": "secret123", "email": "zhangsan@example.com",
 "invite_code": "VIP-2026"}
201 {"token": "xK9…", "username": "张三", "role": "admin", "ttl_hours": 720,
     "recovery_code": "7K2M-9QX4-BR8T-3NVD", "user_id": "1000000001"}

规则:用户名(昵称)2–32 位(字母/数字/下划线/中文),允许重名,仅用于展示; 密码长度与复杂度遵循服务端口令策略(默认 8–64 位且须同时包含字母与数字,由 security.password 配置);邮箱与手机号至少提供一项,二者均为登录标识且各自 全局唯一;第一个注册的用户自动成为管理员(可配置关闭);邀请码一码限用一次, 用后自动从配置移除。成功响应含一次性 recovery_code,须提示用户离线保存。 错误:400 参数不合法、密码强度不足或联系方式缺失/格式错误 / 403 注册关闭、 邀请码无效或授权人数已满 / 402 试用或授权已过期 / 409 邮箱或手机号已被占用 / 502 注册服务器不可达(仅远程模式)。

POST /api/auth/login

登录换取动态令牌(公开;按来源地址限流)。远程模式下凭据提交注册服务器验证, 成功后建立本地会话(令牌库内只存哈希;断开时已登录会话按宽限期继续有效)。

登录标识支持邮箱、手机号或系统分配的用户 ID,由服务端解析后匹配账号; 管理员创建的用户账号另可使用其用户名登录。

POST /api/auth/login
{"login": "zhangsan@example.com", "password": "secret123"}
200 {"token": "xK9…", "username": "张三", "role": "admin", "ttl_hours": 720}

错误:401 登录标识或密码错误 / 403 账号已停用 / 429 登录失败次数超限被锁定(响应含 retry_after_minutes,同一用户连续 5 次或同一 IP 20 次失败触发,锁 15 分钟)/ 502 注册服务器不可达(仅远程模式)。

锁定响应示例:

429 {"error": "失败次数过多,已锁定 15 分钟", "locked": true, "retry_after_minutes": 15}

POST /api/auth/recover

自助找回密码(公开;同一账号连续多次使用错误恢复码同样触发临时锁定)。 远程模式下转发注册服务器处理。

POST /api/auth/recover
{"login": "zhangsan@example.com", "code": "7K2M-9QX4-BR8T-3NVD",
 "new_password": "new-pass-99"}
200 {"ok": true, "recovery_code": "新恢复码(请离线保存)"}

恢复码一次性使用;重置成功后该用户全部旧令牌吊销,并自动重新发放恢复码。 错误:401 登录标识或恢复码不正确(统一文案,不暴露用户是否存在)/ 400 新密码不满足策略 / 429 尝试过多被锁定。

POST /api/auth/recovery-code

重新生成恢复码(需令牌 + 当前密码)。远程模式下转发中央服务器。

POST /api/auth/recovery-code
{"password": "当前密码"}
200 {"ok": true, "recovery_code": "新恢复码(旧码立即作废)"}

POST /api/auth/logout

注销当前动态令牌(需令牌)。远程模式下同时尽力注销中央令牌。

200 {"ok": true}

GET /api/auth/me

当前用户信息(需令牌)。

{"username": "张三", "role": "admin", "auth_mode": "local", "registration": "open",
 "created_at": "2026-08-25T22:10:00", "last_login_at": "2026-08-26T09:00:00"}

auth_mode:local / remote(账号由中央注册服务器统一管理)。

GET /api/users

用户列表(管理员;远程模式下返回 403——用户由注册服务器统一管理)。 静态令牌持有者视为管理员。

{"users": [{"username": "张三", "role": "admin", "status": "active",
            "created_at": "2026-08-25T22:10:00", "last_login_at": "…"}],
 "invite_codes": ["VIP-2026"]}

POST /api/users

创建用户(管理员;远程模式下返回 403)。

POST /api/users
{"username": "user2", "email": "user2@example.com", "password": "pass123", "role": "user"}
email 与 phone 至少提供一项,用于登录标识与找回通道(格式校验、全局唯一,重复报 409);管理员创建的用户账号可凭该用户名直接登录。
201 {"ok": true, "username": "user2", "email": "user2@example.com", "role": "user", "status": "active"}

POST /api/users/{name}/status

启用 / 停用用户(管理员;远程模式下返回 403)。停用后其全部动态令牌立即失效。

POST /api/users/user2/status
{"status": "disabled"}   // 或 "active"

POST /api/users/{name}/password

重置密码(管理员;远程模式下返回 403)。

POST /api/users/user2/password
{"password": "newpass456"}

DELETE /api/users/{name}

删除用户(管理员;远程模式下返回 403)。不能删除自己;系统至少保留一名管理员。

200 {"ok": true}

授权与运维

GET /api/license

授权状态(需令牌;管理员返回完整信息,普通用户返回摘要)。

{"state": "trial", "days_left": 12, "trial_days": 14, "enforce": true}

state:off(未启用管控)/ trial(试用中)/ trial_expired(试用结束)/ licensed(已授权)/ expired(已到期,服务停止)/ invalid(授权文件无效)。 无宽限期:试用结束或授权到期即停服。 已授权时另含 customer / edition / expires / max_users。

POST /api/license/activate

激活授权码(管理员)。

POST /api/license/activate
{"key": "eyJ...长授权码..."}
200 {"ok": true, "state": "licensed", "customer": "客户名", "days_left": 365}

错误:400 授权码无效/已过期/与本产品不匹配。

GET /api/alerts

最近告警与统计(管理员)。

{"alerts": [{"ts": "…", "level": "warn", "title": "磁盘剩余不足", "detail": "…"}],
 "status": {"enabled": true, "total": 3}}

GET /api/audit

审计日志(管理员;远程模式下返回 403)。可选 ?action= 过滤动作类型、 ?limit= 控制条数(默认 100)。

GET /api/audit?action=login_blocked
{"events": [{"ts": "…", "user": "张三", "action": "login_blocked",
             "detail": "ip=1.2.3.4", "ip": "1.2.3.4"}]}

记录的动作包括:register / register_denied / login_ok / login_failed / login_blocked / logout / password_reset / password_recovered / recovery_regen / user_created / user_status / user_deleted / license_activated / license_activate_failed。


升级分发

GET /api/update/latest

最新版本清单(公开)。内容即发布目录中的 manifest.json:

{"version": "0.9.233", "file": "trueagt-0.9.233-win-setup.zip",
 "sha256": "ab12…", "size": 10878976, "notes": "更新说明",
 "released_at": "2026-09-20T00:00:00+08:00", "entries": 12}

未发布过版本时返回 404 {"error": "no update published"}。

GET /api/update/download(别名 /download)

下载最新安装包(公开,application/zip,附 Content-Disposition)。 首次安装的用户可直接用浏览器访问 /download 获取安装包。

GET /api/update/check

检查新版本(需令牌)。返回当前版本与服务端最新版本的对比:

{"current_version": "0.9.233", "mode": "manual", "url": "http://…/api/update/latest",
 "last_check": 1787674594.2, "latest": {"version": "0.9.233", "notes": "…", …},
 "available": true, "error": ""}

POST /api/update/apply

立即升级并重启(管理员;仅独立 exe 安装支持,非安装包部署返回 400)。

200 {"restarting": true, "version": "0.9.233"}

流程:下载 → SHA256 校验 → 派生后台替换脚本(等待进程退出 → 备份旧版程序 → 覆盖程序文件、保留 config.json/data/logs → 自动重启)。 响应发送约 3 秒后服务退出,随后自动恢复。


会话管理

GET /api/sessions

会话列表(按更新时间倒序)。

{"sessions": [{"id": "2603934cc408", "title": "测试会话", "updated_at": "2026-08-24T22:10:00"}]}

POST /api/sessions

新建会话。请求体(可选):

{"title": "可选标题"}

返回 {"id": "<12位会话ID>", "title": "..."}。

GET /api/sessions/{id}

会话详情:消息列表 + 事件回放(不含逐 token 的 llm_delta)。

{
  "id": "...",
  "title": "...",
  "messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}],
  "events": [{"type": "user_input", "text": "..."}, {"type": "final_answer", "text": "..."}]
}

DELETE /api/sessions/{id}

删除会话,不可恢复。返回 {"ok": true};会话不存在返回 404。


对话

POST /api/plan

只生成执行计划,不执行(供人工确认)。

请求体:

{"session_id": "<会话ID>", "message": "帮我调研并总结..."}

返回:

{"steps": ["步骤一:...", "步骤二:...", "步骤三:..."]}

POST /api/chat

对话主接口,响应为 SSE 事件流(text/event-stream)。

请求体:

{
  "session_id": "<会话ID>",
  "message": "用户消息",
  "plan": ["可选:已批准的计划步骤"],
  "attachments": [
    {"filename": "pic.png", "mime": "image/png", "data_base64": "<base64 数据>"},
    {"filename": "doc.txt", "mime": "text/plain", "data_base64": "<base64 数据>"}
  ]
}

若请求体携带 plan 数组,则跳过规划直接按该计划执行。 attachments 为可选数组:图片(image/*)以 data URI 直接透传给支持视觉的模型;文本类文件(.txt/.md/.py/.csv 等)解码后作为上下文注入;无 message 但带 attachments 时消息也可为空。落盘时图片 base64 会被自动剔除,仅保留文本说明。

SSE 事件协议

每个事件为 data: <JSON>\n\n,按发生顺序推送:

type载荷说明
user_inputtext用户消息回显(首个事件)
plansteps: [str]执行计划
llm_deltaiteration, delta流式增量文本
llm_responseiteration, content, tool_calls: [[名称, 参数], ...]本轮完整响应
tool_resultresult工具执行结果
reflectiondone: bool, advice周期性反思结论
usageprompt_tokens, completion_tokens本轮 Token 用量
max_iterations—达到迭代上限,强制收敛
final_answertext最终回答
cancelled—已被取消
errorerror执行异常
done—流结束标志(最后一个事件)

消费示例(curl):

curl -N -X POST http://127.0.0.1:8765/api/chat \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "<id>", "message": "帮我算 12345 × 67"}'

POST /api/stop

取消当前用户正在执行的生成。

{"cancelled": true}

返回 false 表示当前没有进行中的任务。


自动化任务(管理员)

定时/周期触发对话或任务。所有接口需管理员令牌(静态令牌持有者视为管理员)。

GET /api/automations

列出全部自动化任务。

{"automations": [{"id": "a1b2c3", "name": "每日简报", "schedule_type": "daily",
 "hour": 9, "minute": 0, "enabled": true, "next_run": "2026-08-28T09:00:00",
 "last_status": "ok", "last_output": "..."}]}

POST /api/automations

创建任务,返回 201。请求体字段:

字段说明
name任务名称
prompt到点执行的提示词(即一次智能体对话输入)
schedule_typeonce(指定时间触发一次)/ interval(每隔 N 秒)/ daily(每日时刻)
scheduled_atonce 用,ISO 时间
interval_secondsinterval 用,间隔秒数
hour / minutedaily 用,每日触发时刻(本机时区)
POST /api/automations
{"name": "每日简报", "schedule_type": "daily", "hour": 9, "minute": 0,
 "prompt": "请生成今天的技术简报"}
201 {"ok": true, "id": "a1b2c3", "name": "每日简报", "schedule_type": "daily", ...}

POST /api/automations/{id}/run

立即手动执行一次(不依赖调度),返回执行输出。

POST /api/automations/a1b2c3/run
{"ok": true, "output": "..."}

DELETE /api/automations/{id}

删除任务,返回 {"ok": true};不存在返回 404。

任务持久化在 data/automations.json,进程重启可恢复;once 任务触发后自动停用。


错误码

状态码含义
400请求体非法(空消息且无附件 / plan 非数组 / attachments 非数组 / 非 JSON / 用户名密码不合规或强度不足 / 授权码无效 / 非安装包部署执行升级)
401未携带令牌或令牌无效(含登录密码错误、令牌过期、账号停用、恢复码错误)
402试用或授权已过期(新对话/注册被拒)
403无权限(非管理员访问管理接口;注册已关闭;邀请码无效;账号被停用;授权人数已满)
404会话不存在或接口不存在(升级未发布时 /api/update/latest 亦返回 404)
409用户名已被占用;同一用户并发执行(BusyError)
429触发限流或登录锁定(含登录/注册按 IP 限流、登录失败超限锁定、恢复码尝试超限,响应附 retry_after_minutes)
500服务端执行异常(SSE 流中以 error 事件返回)
502远程模式中央注册服务器不可达

附录:端点总览(对齐 0.9.233)

本章节按模块列出代码中实际注册的全部端点,便于检索。权限列说明:公开 无需令牌; 登录 需有效令牌;管理员 需 admin 或 super_admin;超级管理员 仅 super_admin。 {id} {n} 为路径参数。

权限判定的最终依据是 web.py 中的路由实现;本表用于快速检索,如有出入以代码为准。

健康与状态

方法端点权限说明
GET/healthz公开健康检查
GET/api/version公开版本信息
GET/api/status登录当前用户视角的智能体状态
GET/api/usage登录当前用户累计用量
GET/metrics令牌可选Prometheus 指标(配置 metrics_token 时需令牌)
GET/api/integrity公开前端静态资源完整性校验值
GET/api/entitlement/status公开授权闸门状态
GET/api/alerts管理员最近告警

会话与对话

方法端点权限说明
GET/POST/api/sessions登录会话列表 / 新建
GET/POST/PUT/DELETE/api/sessions/{id}登录详情 / 更新 / 归档 / 删除
GET/api/sessions/search登录会话检索
POST/api/chat登录对话(SSE 流式)
POST/api/plan登录生成执行计划(不执行)
POST/api/stop登录取消正在执行的生成
GET/api/trace/list登录思维链回放列表
GET/api/trace/export登录导出回放

用户与鉴权

方法端点权限说明
GET/api/auth/config公开鉴权方式与注册模式
POST/api/auth/register公开注册(模式 open/invite)
POST/api/auth/login公开登录换取动态令牌
POST/api/auth/logout登录注销当前令牌
GET/api/auth/me登录当前用户信息
GET/PUT/api/auth/profile登录个人资料读写
PUT/api/auth/password登录修改本人密码
POST/api/auth/delete登录注销账号(密码二次校验)
POST/api/auth/recovery-code登录重新生成恢复码
POST/api/auth/recover公开凭恢复码自助重置密码
GET/api/auth/wechat/authorize公开微信登录授权跳转(302 跳转至微信授权端点)
POST/api/auth/wechat/callback公开微信 OAuth 回调:用 code 换码登录(服务端持 secret 换取 unionid,命中或自动注册)
POST/api/auth/recover-prepare公开自助重置前置准备
PUT/api/auth/data-recovery-key登录数据恢复密钥
GET/api/permissions登录权限目录(下发界面语言键名,供前端按当前语言显示)

模型与配置

方法端点权限说明
GET/POST/api/config/model登录模型配置读写(热生效)
POST/api/config/model/test登录模型连通性测试
GET/api/models登录模型清单
POST/api/models/{id}登录模型操作
POST/api/models/test登录连通性测试
GET/POST/api/config/presets登录预设模型读写
DELETE/api/config/presets/{id}登录删除预设
GET/POST/api/config/search登录联网搜索配置
GET/POST/api/storage管理员存储位置与迁移
GET/POST/api/config/team登录多智能体角色名册
GET/POST/api/config/collab登录多节点协作配置
POST/api/config/collab/test登录协作连通性测试
GET/api/docs/collab-guide登录协作配置指南
GET/POST/api/config/advanced登录高级配置
GET/POST/api/config/contact管理员验证码/通知通道配置读写(保存后即时生效)
POST/api/config/contact/test管理员通道连通性测试(向指定接收地址真实发送一条测试消息校验凭据)
GET/api/tools登录工具清单

能力扩展

方法端点权限说明
GET/POST/api/custom-tools登录自定义工具列表 / 创建
POST/DELETE/api/custom-tools/{id}登录更新 / 启停 / 删除
GET/api/kb/stats登录知识库统计
GET/api/kb/list登录知识库文档列表
POST/api/kb/ingest登录导入文档
POST/api/kb/clear登录清空知识库
DELETE/api/kb/{id}登录删除文档
GET/api/skills登录技能库
GET/api/skills/catalog登录技能市场目录
POST/api/skills/import管理员导入技能
DELETE/api/skills/{id}管理员删除技能
POST/api/skills/review登录技能审核
GET/api/skills/recommendations登录技能推荐
GET/api/skills/reputation登录信誉分
GET/POST/api/automations登录自动化任务
GET/POST/DELETE/api/automations/{id}登录单个自动化任务

API 密钥

方法端点权限说明
GET/api/keys登录当前用户的密钥列表(脱敏预览)
POST/api/keys登录签发新密钥,明文仅此一次可见(前缀 tak-)
DELETE/api/keys/{id}登录吊销密钥

用户与权限管理

方法端点权限说明
GET/api/users管理员用户列表(普通用户仅返回本人)
POST/api/users管理员创建用户
POST/api/users/{n}/status管理员启用 / 停用
POST/api/users/{n}/password见下重置密码:超级管理员可重置任何人;用户本人可重置自己;普通管理员不得重置他人(403)
POST/api/users/{n}/role超级管理员变更角色(特权档仅 super 可授予/变更)
DELETE/api/users/{n}超级管理员删除用户
GET/api/admin/overview管理员管理总览
GET/POST/DELETE/api/admin/secrets管理员密钥保险库

审计、处置与合规

方法端点权限说明
GET/api/audit管理员审计日志(?action= 过滤)
GET/api/audit/verify管理员审计链完整性校验
GET/POST/api/disposition管理员内容处置概览 / 补录处置
GET/api/disposition/export管理员处置全量导出(供主管部门出示)
GET/api/marking登录内容标识配置(AIGC 标识)
POST/api/report登录提交举报
GET/api/reports/mine登录我的举报
GET/api/admin/reports管理员举报列表
POST/api/admin/reports/resolve管理员处置举报

授权、升级与其他

方法端点权限说明
GET/api/license管理员授权状态(试用/已授权/到期天数)
POST/api/license/activate管理员激活授权码
GET/api/update/latest公开最新版本清单
GET/api/update/download公开下载安装包
GET/api/update/check登录检查新版本
POST/api/update/apply管理员立即升级并重启
POST/api/export/office登录导出 Office 文档
GET/api/share登录只读分享
POST/api/usage/report节点凭证用量上报(节点→中央)
GET/POST/api/sso/config管理员单点登录配置
GET/api/sso/authorize /api/sso/callback公开SSO 跳转与回调
POST/api/inbound/*渠道凭证多端入站(企微/飞书/Webhook,独立于 Bearer 鉴权)
POST/api/nodes/register /api/nodes/heartbeat节点凭证节点注册与心跳
GET/api/nodes登录节点目录
POST/api/collab/tasks /api/collab/poll登录/节点凭证协作任务创建与拉取
本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。