Veritas Kanban REST API参考详解:认证、端点与WebSocket实时更新全攻略

原创2026-10-25 11:17:301,959 阅读

Veritas Kanban REST API参考详解:认证、端点与WebSocket实时更新全攻略

Veritas Kanban 是一款轻量级 AI Agent 编排工具,让你掌握项目的"未过滤真相"。它的 REST API(基础地址 http://localhost:3001/api,/api/v1 与 /api 前缀等价)让 AI 代理、脚本和桌面客户端可以直接创建任务、跟踪工时、上报遥测,并通过 WebSocket 实时接收 Agent 运行输出。本文面向新手,讲清认证方式、核心端点、错误模型与实时推送机制,帮你快速完成第一个集成。

Veritas Kanban 看板总览,展示任务卡片与状态列

一、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+ 个模块,每个文件对应一组端点。

Veritas Kanban 任务详情页,展示任务字段与操作

二、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 对应的安全设置页,支持修改密码与危险区重置。

Veritas Kanban 安全设置页,展示密码修改选项

三、核心端点与统一错误模型

任务端点(挂载于 /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 中附最新资源,客户端可据此重新加载或重试

Veritas Kanban 任务详情视图,展示状态与元数据

四、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 活动" 菜单可以直接查看每个连接的状态、延迟与最近事件,是排查实时同步问题的第一现场。

Veritas Kanban 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 个月

下一步动手指南

  1. 先读 docs/API-REFERENCE.md 的 "Common Workflows" 章节,里面有完整的 Agent 任务生命周期 curl 示例
  2. 用 curl -H 'X-API-Key: YOUR_KEY' http://localhost:3001/api/tasks 发出第一个请求
  3. 需要编排工作流时查阅 docs/API-WORKFLOWS.md
  4. 路由实现可对照 server/src/routes/tasks.ts、server/src/routes/auth.ts 等源码文件,自底向上理解每个端点

掌握以上认证、端点与 WebSocket 三块拼图,你就能把 Veritas Kanban 无缝接入自己的 AI Agent 工作流——从创建任务到实时观看 Agent 输出的全过程,尽在掌握。

登录后查看全文
veritas-kanban