Veritas Kanban REST API参考详解:认证、端点与WebSocket实时更新全攻略
Veritas Kanban REST API参考详解:认证、端点与WebSocket实时更新全攻略
Veritas Kanban 是一款轻量级 AI Agent 编排工具,让你掌握项目的"未过滤真相"。它的 REST API(基础地址 http://localhost:3001/api,/api/v1 与 /api 前缀等价)让 AI 代理、脚本和桌面客户端可以直接创建任务、跟踪工时、上报遥测,并通过 WebSocket 实时接收 Agent 运行输出。本文面向新手,讲清认证方式、核心端点、错误模型与实时推送机制,帮你快速完成第一个集成。
一、Veritas Kanban REST API 能做什么
Veritas Kanban 的 API 覆盖了看板协作的完整生命周期:
- 📋 任务管理:创建、更新、移动、批量归档任务,附带依赖关系与进度检查点
- ⏱️ 工时跟踪:开始/停止计时器、录入工时条目
- 📊 遥测与分析:上报
run.started、run.completed、Token 用量等事件,驱动仪表盘图表 - 🤖 Agent 协作:上下文读取、观察记录(observations)、变更轮询(change feed)
- 💬 聊天与共享运行:团队聊天、共享运行会话(run-sessions)
官方 API 权威文档位于 docs/API-REFERENCE.md(v6.1.3 版),工作流引擎端点详见 docs/API-WORKFLOWS.md。所有路由源码集中在 server/src/routes/ 目录,共 90+ 个模块,每个文件对应一组端点。
二、REST API 认证:4 种方法与 3 个角色
认证方法速查
| 方法 | 传递方式 | 适用场景 |
|---|---|---|
| 会话 Cookie | veritas_session Cookie |
本地所有者的浏览器登录 |
| API Key | X-API-Key: <key> 请求头 |
Agent 集成、脚本调用(最常用) |
| 设备会话 | Authorization: Bearer vk_dev_… |
已配对的桌面 / 移动 / PWA 客户端 |
| WS 查询参数 | ws://host:3001/ws?api_key=<key> |
WebSocket 连接 |
角色权限
| 角色 | 权限 |
|---|---|
admin |
全部端点、破坏性操作、深度健康检查 |
agent |
读写任务、工时、观察记录、聊天、遥测 |
read-only |
所有 GET 端点的只读访问 |
配置 API Key
通过环境变量即可开启认证,无需写代码:
# 管理员密钥
VERITAS_ADMIN_KEY=your-admin-key
# 追加密钥(格式:名称:密钥:角色,逗号分隔)
VERITAS_API_KEYS=agent1:key123:agent,readonly:key456:read-only
🔐 本机调试时可以开启本地绕过:设置 VERITAS_AUTH_LOCALHOST_BYPASS=true 后,来自 127.0.0.1 的请求会自动按 VERITAS_AUTH_LOCALHOST_ROLE(默认 read-only)认证。注意:生产环境请勿依赖本地绕过,远程客户端必须使用设备会话或带范围的 API Token。
密码会话管理界面见 assets/scr-settings_security.png 对应的安全设置页,支持修改密码与危险区重置。
三、核心端点与统一错误模型
任务端点(挂载于 /api/tasks)
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/tasks |
列出全部活动任务,支持查询过滤 |
GET |
/api/tasks/counts |
按状态分组的任务计数 |
POST |
/api/tasks |
创建任务(返回 201) |
GET |
/api/tasks/:id |
读取单个任务 |
PATCH |
/api/tasks/:id |
部分更新(标题、状态、优先级等) |
DELETE |
/api/tasks/:id |
删除任务 |
POST |
/api/tasks/:id/move |
在列间原子移动(乐观并发) |
POST |
/api/tasks/bulk-update |
批量更新 |
GET |
/api/tasks/:id/context |
获取 Agent 消费用的富上下文 |
其他常用组:/api/projects、/api/sprints、/api/backlog、/api/agents、/api/templates、/api/telemetry、/api/audit 等 40+ 组端点,完整清单见 docs/API-REFERENCE.md 的 "Additional Endpoint Groups" 章节。
统一错误模型
所有错误都返回一致的 JSON 结构:
{
"error": "人类可读的错误信息",
"code": "可选的错误码",
"details": {}
}
常见状态码:200 成功、201 已创建、400 请求体非法、401 未认证、403 角色不足、404 资源不存在、409 冲突(状态违规或版本过期)、429 触发限流、503 服务降级。
乐观并发控制(新手必看)
任务读写携带版本元数据:
- 读取与写入成功都会返回
ETag: "task:<taskId>:<revision>",同时以X-Resource-Revision头给出数字版本号 - 编辑时把最近读到的 ETag 放在
If-Match头中随请求提交 - 若任务已被别人改过,API 返回
409 CONFLICT,并在details.current中附最新资源,客户端可据此重新加载或重试
四、WebSocket 实时更新全攻略
连接方式
const ws = new WebSocket('ws://localhost:3001/ws?api_key=YOUR_API_KEY');
关键约束:
- 最大连接数:50
- 心跳机制:服务端每 30 秒 发送 ping,客户端须在 10 秒 内回复 pong
- 强制 Origin 校验,提供 CSWSH(跨站 WebSocket 劫持)防护
- WebSocket 因升级握手无法携带请求头,所以认证走
api_key查询参数
客户端 → 服务端:订阅消息
| 消息 | 说明 |
|---|---|
{"type":"subscribe","taskId":"TASK-001"} |
订阅任务运行输出,支持 attemptId(默认最新尝试)与 afterSequence 断点续传 |
{"type":"chat:subscribe","sessionId":"session-abc"} |
订阅聊天会话 |
{"type":"run-session:subscribe"} |
订阅共享运行会话事件 |
订阅任务输出时,服务端会先重放存储的历史事件再接上实时尾部,事件按序号去重且有序交付;subscribed 确认消息会返回解析后的 attemptId 和当前 cursor,方便断线重连。
服务端 → 客户端:推送事件
| 事件类型 | 用途 |
|---|---|
task:updated |
任务状态变更广播(如状态变为 done) |
agent:event |
持久化 Agent 事件(run-event/v1 信封,含 sequence、payloadHash、脱敏标记) |
agent:output |
传统 Agent 标准输出投影 |
agent:status |
Agent 状态变化(如 working)与活跃 Agent 列表 |
chat:message |
聊天新消息 |
run-session:event |
共享运行会话的协同事件 |
💡 UI 中的 "WebSocket 活动" 菜单可以直接查看每个连接的状态、延迟与最近事件,是排查实时同步问题的第一现场。
五、健康检查与速率限制
三级健康检查体系
| 端点 | 认证 | 用途 |
|---|---|---|
GET /health/live |
无 | 存活探测——进程是否在运行 |
GET /health/ready |
无 | 就绪探测——存储、磁盘、内存状态 |
GET /health/deep |
Admin | 完整诊断——版本、WS 连接数、熔断器状态 |
/health/ready 返回形如 {"status":"ok","checks":{"storage":"ok","memory":"ok","disk":"ok"}} 的结构,非常适合容器编排探活。
速率限制
| 层级 | 限制 | 适用范围 |
|---|---|---|
| 全局 | 300 次/分钟 | 所有端点(localhost 豁免) |
| 读 | 300 次/分钟 | GET 请求 |
| 写 | 60 次/分钟 | POST/PUT/PATCH/DELETE |
| 上传 | 20 次/分钟 | 文件上传端点 |
被限流时响应头包含 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset,客户端可据此做指数退避。
六、版本策略与学习资源
- 当前版本为 v1,主版本内不做破坏性变更
- 废弃流程:
Deprecation响应头 + Changelog 公告,至少提前 2 个次要版本才会移除 - v2 发布后,v1 将至少再保留 6 个月
下一步动手指南
- 先读 docs/API-REFERENCE.md 的 "Common Workflows" 章节,里面有完整的 Agent 任务生命周期 curl 示例
- 用
curl -H 'X-API-Key: YOUR_KEY' http://localhost:3001/api/tasks发出第一个请求 - 需要编排工作流时查阅 docs/API-WORKFLOWS.md
- 路由实现可对照 server/src/routes/tasks.ts、server/src/routes/auth.ts 等源码文件,自底向上理解每个端点
掌握以上认证、端点与 WebSocket 三块拼图,你就能把 Veritas Kanban 无缝接入自己的 AI Agent 工作流——从创建任务到实时观看 Agent 输出的全过程,尽在掌握。




