Base URL:http://<host>:8765。所有 /api/* 接口在启用鉴权后需携带请求头:
Authorization: Bearer <访问令牌>
令牌两种来源(都通过同一请求头携带):
POST /api/auth/login 或注册签发(见「用户与鉴权」);config.json → server.auth_tokens 配置 {"令牌": "用户名"}。限流:默认每用户 60 次 / 60 秒(服务端可配置),超限返回 429。 登录/注册接口按来源 IP 独立限流。 响应统一为 UTF-8 JSON;除 /api/chat 外均为普通 JSON 响应。
健康检查,无需鉴权。
{"ok": true, "version": "0.9.233"}
版本信息,无需鉴权。
{"name": "trueagt", "version": "0.9.233"}
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
...
当前用户视角的智能体状态。
{
"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 为密钥指纹(本机密钥文件的身份标识)。
当前用户的累计用量。
{"requests": 42, "prompt_tokens": 38120, "completion_tokens": 9205}
鉴权方式与注册模式(公开,无需令牌)。前端据此决定展示登录页还是直接进入。
{"auth_required": true, "mode": "local", "registration": "invite", "demo": false}
mode:local(本机账号,默认)/ remote(中央注册服务器模式,账号由 server.auth.remote_url 指定的中央统一验证,本地不保存密码)。 registration:open(开放注册)/ invite(邀请码)/ closed(仅管理员创建)。
注册账号(公开;按来源地址限流)。成功即自动登录并返回动态令牌。 远程模式(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 注册服务器不可达(仅远程模式)。
登录换取动态令牌(公开;按来源地址限流)。远程模式下凭据提交注册服务器验证, 成功后建立本地会话(令牌库内只存哈希;断开时已登录会话按宽限期继续有效)。
登录标识支持邮箱、手机号或系统分配的用户 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
{"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
{"password": "当前密码"}
200 {"ok": true, "recovery_code": "新恢复码(旧码立即作废)"}
注销当前动态令牌(需令牌)。远程模式下同时尽力注销中央令牌。
200 {"ok": true}
当前用户信息(需令牌)。
{"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(账号由中央注册服务器统一管理)。
用户列表(管理员;远程模式下返回 403——用户由注册服务器统一管理)。 静态令牌持有者视为管理员。
{"users": [{"username": "张三", "role": "admin", "status": "active",
"created_at": "2026-08-25T22:10:00", "last_login_at": "…"}],
"invite_codes": ["VIP-2026"]}
创建用户(管理员;远程模式下返回 403)。
POST /api/users
{"username": "user2", "email": "user2@example.com", "password": "pass123", "role": "user"}
phone至少提供一项,用于登录标识与找回通道(格式校验、全局唯一,重复报409);管理员创建的用户账号可凭该用户名直接登录。
201 {"ok": true, "username": "user2", "email": "user2@example.com", "role": "user", "status": "active"}
启用 / 停用用户(管理员;远程模式下返回 403)。停用后其全部动态令牌立即失效。
POST /api/users/user2/status
{"status": "disabled"} // 或 "active"
重置密码(管理员;远程模式下返回 403)。
POST /api/users/user2/password
{"password": "newpass456"}
删除用户(管理员;远程模式下返回 403)。不能删除自己;系统至少保留一名管理员。
200 {"ok": true}
授权状态(需令牌;管理员返回完整信息,普通用户返回摘要)。
{"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
{"key": "eyJ...长授权码..."}
200 {"ok": true, "state": "licensed", "customer": "客户名", "days_left": 365}
错误:400 授权码无效/已过期/与本产品不匹配。
最近告警与统计(管理员)。
{"alerts": [{"ts": "…", "level": "warn", "title": "磁盘剩余不足", "detail": "…"}],
"status": {"enabled": true, "total": 3}}
审计日志(管理员;远程模式下返回 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。
最新版本清单(公开)。内容即发布目录中的 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"}。
下载最新安装包(公开,application/zip,附 Content-Disposition)。 首次安装的用户可直接用浏览器访问 /download 获取安装包。
检查新版本(需令牌)。返回当前版本与服务端最新版本的对比:
{"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": ""}
立即升级并重启(管理员;仅独立 exe 安装支持,非安装包部署返回 400)。
200 {"restarting": true, "version": "0.9.233"}
流程:下载 → SHA256 校验 → 派生后台替换脚本(等待进程退出 → 备份旧版程序 → 覆盖程序文件、保留 config.json/data/logs → 自动重启)。 响应发送约 3 秒后服务退出,随后自动恢复。
会话列表(按更新时间倒序)。
{"sessions": [{"id": "2603934cc408", "title": "测试会话", "updated_at": "2026-08-24T22:10:00"}]}
新建会话。请求体(可选):
{"title": "可选标题"}
返回 {"id": "<12位会话ID>", "title": "..."}。
会话详情:消息列表 + 事件回放(不含逐 token 的 llm_delta)。
{
"id": "...",
"title": "...",
"messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}],
"events": [{"type": "user_input", "text": "..."}, {"type": "final_answer", "text": "..."}]
}
删除会话,不可恢复。返回 {"ok": true};会话不存在返回 404。
只生成执行计划,不执行(供人工确认)。
请求体:
{"session_id": "<会话ID>", "message": "帮我调研并总结..."}
返回:
{"steps": ["步骤一:...", "步骤二:...", "步骤三:..."]}
对话主接口,响应为 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 会被自动剔除,仅保留文本说明。
每个事件为 data: <JSON>\n\n,按发生顺序推送:
| type | 载荷 | 说明 |
|---|---|---|
user_input | text | 用户消息回显(首个事件) |
plan | steps: [str] | 执行计划 |
llm_delta | iteration, delta | 流式增量文本 |
llm_response | iteration, content, tool_calls: [[名称, 参数], ...] | 本轮完整响应 |
tool_result | result | 工具执行结果 |
reflection | done: bool, advice | 周期性反思结论 |
usage | prompt_tokens, completion_tokens | 本轮 Token 用量 |
max_iterations | — | 达到迭代上限,强制收敛 |
final_answer | text | 最终回答 |
cancelled | — | 已被取消 |
error | error | 执行异常 |
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"}'
取消当前用户正在执行的生成。
{"cancelled": true}
返回 false 表示当前没有进行中的任务。
定时/周期触发对话或任务。所有接口需管理员令牌(静态令牌持有者视为管理员)。
列出全部自动化任务。
{"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": "..."}]}
创建任务,返回 201。请求体字段:
| 字段 | 说明 |
|---|---|
name | 任务名称 |
prompt | 到点执行的提示词(即一次智能体对话输入) |
schedule_type | once(指定时间触发一次)/ interval(每隔 N 秒)/ daily(每日时刻) |
scheduled_at | once 用,ISO 时间 |
interval_seconds | interval 用,间隔秒数 |
hour / minute | daily 用,每日触发时刻(本机时区) |
POST /api/automations
{"name": "每日简报", "schedule_type": "daily", "hour": 9, "minute": 0,
"prompt": "请生成今天的技术简报"}
201 {"ok": true, "id": "a1b2c3", "name": "每日简报", "schedule_type": "daily", ...}
立即手动执行一次(不依赖调度),返回执行输出。
POST /api/automations/a1b2c3/run
{"ok": true, "output": "..."}
删除任务,返回 {"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 | 远程模式中央注册服务器不可达 |
本章节按模块列出代码中实际注册的全部端点,便于检索。权限列说明:公开 无需令牌; 登录 需有效令牌;管理员 需 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} | 登录 | 单个自动化任务 |
| 方法 | 端点 | 权限 | 说明 |
|---|---|---|---|
| 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 | 登录/节点凭证 | 协作任务创建与拉取 |