---

由 Brad Groux 创作 — Digital Meld 的 CEO，以及 Start Small, Think Big 播客的主持人 · LinkedIn · Twitter · YouTube

---

⚡ 快速入门

想走捷径吗？只需让您的代理（比如 OpenClaw）执行以下指令：

在本地克隆并设置 Veritas 看板。使用 pnpm 安装依赖项，复制 .env.example 文件，并启动开发服务器。确认它正在 localhost:3000 上运行。

想自己动手吗？不到 5 分钟即可上手：

git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban
pnpm install
cp server/.env.example server/.env   # 编辑以更改 VERITAS_ADMIN_KEY
pnpm dev

打开 http://localhost:3000 — 就完成了。首次运行时，看板会自动填充示例任务，方便您立即开始探索。

想要一个干净的起点？ 删除示例任务：rm tasks/active/task_example_*.md 并刷新页面。 想重新填充示例任务？ 运行 pnpm seed 即可恢复示例任务（仅在看板为空时有效）。

注意： 绝不要提交 .env 文件。请使用 .env.example 作为模板——它包含安全的占位符值和每个变量的说明。

---

📚 文档地图

• MCP 服务器指南 — 包含 33+ 工具、架构、快速入门、工具目录、安全模型和故障排除方法。
• API 参考 — 认证、端点、请求/响应示例、WebSocket 以及常见工作流程。
• 自托管指南 — 生产环境部署、反向代理、认证加固、Docker 和备份。
• 入门指南 — 从零到具备代理能力只需 5 分钟，附带健康检查和提示注册表技巧。
• 代理任务工作流标准操作程序 — 生命周期、API/CLI 片段和提示。
• 小队聊天协议 — 代理消息传递、系统事件（生成/完成/失败）、模型归属以及辅助脚本。
• 冲刺计划标准操作程序 — 巨型项目 → 冲刺 → 任务分解。
• 多代理编排 — 项目经理与工作者之间的交接。
• 跨模型代码审查 — 强制执行 Claude ↔ GPT 互审。
• 代理治理标准操作程序 — 策略引擎、行为漂移检测、决策审计、输出评估、用户反馈。
• 运营标准操作程序 — 广播、授权、交付成果、提示注册表、小队聊天、系统健康监测。
• 最佳实践 和 技巧与窍门 — 模式、快捷方式和集成。
• 实际案例 — 可直接复制粘贴的代理工作流程。
• 故障排除 — 当出现问题时提供更深入的诊断信息。

⚠️ 代理式 AI 安全

[!CAUTION] AI 代理可以编写代码、执行命令并修改您的系统。 虽然像 Veritas 看板这样的工具使代理式工作流功能强大，但如果没有适当的保护措施，也可能造成严重损害。在授予任何 AI 代理对您环境的访问权限之前，请务必阅读本文。

代理式 AI 最佳实践

1. 先在本地运行。 在完全理解其行为之前，将您的看板和代理保留在自己的机器上。切勿将未经身份验证的实例暴露于互联网。Veritas 看板不包含速率限制 — 如果您公开部署，请在其前面添加带有速率限制的反向代理（Nginx、Caddy 或 Cloudflare）。

2. 切勿从不受控的输入触发代理。 不要让传入的电子邮件、来自第三方的 Webhook 或公共表单提交自动触发代理工作。能够构造输入的攻击者可以控制您的代理。

3. 最小权限原则。 仅授予代理所需的最低权限。API 密钥应使用 agent 角色（而非 admin）。限制文件系统的访问权限。不要以 root 用户身份运行代理。

4. 合并前审核。 代理可以编写代码——但这并不意味着代码是正确或安全的。在将其合并到生产分支之前，务必审核代理生成的代码。使用内置的代码审查工作流。

5. 对破坏性操作设定界限。 代理不应拥有对 rm、git push --force、数据库删除或生产部署的无监督访问权限。对于不可逆的操作，必须获得人工批准。

6. 监控与审计。 使用时间跟踪和活动日志来了解代理在做什么。审查代理已完成的任务。在推送之前检查 Git 差异。

7. 定期轮换凭据。 如果代理有权访问 API 密钥、令牌或机密，请按计划进行轮换。切勿在任务描述或提示中嵌入真实凭据。

8. 隔离环境。 尽可能在容器、虚拟机或沙盒环境中运行代理。将代理的工作空间与敏感数据分开。

总结： 代理式 AI 具有变革性，但它会同时放大您的能力和错误。请相应地规划，从小处着手，并在建立对保护措施的信心后逐步增加自主性。

---

✨ 功能亮点

🛡️ 代理治理（v4.0 新功能）

策略引擎 — 定义代理可以执行与禁止执行的操作。支持 allow、deny 和 require-approval 三种防护规则的可配置工具/动作策略。所有策略决策都会被记录。 决策审计追踪 — 记录代理的决策，包括置信度分数、支持性证据和所作假设。事后记录执行结果，以验证假设是否成立。 行为漂移检测 — 设置指标基线和阈值；当代理行为出现偏差时，系统会发出告警。 用户反馈循环 — 收集对代理输出的反馈，结合情感标签和分类分析。 输出评估 — 根据加权标准配置文件（正则表达式、关键词、数值范围、自定义表达式）对代理输出进行评分。

🤖 代理编排

为任务启动自主编码代理。通过多代理仪表板实时跟踪代理状态——包括状态指示器、可展开的代理卡片以及模型归属信息。Squad Chat 为代理提供共享通信通道，并集成系统生命周期事件通知（如代理启动、完成或失败）。您可以为每个任务分配多个代理，设置权限级别（实习生/专家/负责人），并让它们协同工作。

📊 可定制仪表板（v4.0 新功能）

可拖拽且可调整大小的组件网格 — 通过拖放操作重新排列和调整仪表板组件的大小。布局在不同会话间保持一致。您可以从组件库中添加所需组件，或移除不需要的组件。 全局系统健康状态栏 — 持续显示的头部状态栏，包含五个健康等级（稳定 → 警报），覆盖三大信号类别：系统资源、代理可用性和运行成功率。

📝 提示模板注册表（v4.0 新功能）

版本控制的提示模板，支持变量提取、完整的版本历史及回滚功能、使用情况跟踪，以及带示例变量注入的预览渲染。以管理代码的方式管理您的提示库。

⚡ 工作流引擎

将多步骤代理流水线定义为版本控制的 YAML 文件。支持顺序步骤、并行分支展开/合并、集合上的循环迭代、人工介入审批节点以及重试路由等功能。类似于 GitHub Actions，但专为 AI 代理设计。提供实时执行视图，展示每一步的进度。监控仪表板则显示成功率、当前运行数以及每个工作流的健康指标。

📋 任务智能

不仅仅是看板上的卡片。任务拥有依赖关系图，具备环路检测、崩溃恢复检查点（自动清理敏感信息）、重要性评分的观察记忆、时间跟踪以及完整的活动日志。强制性检查点（审查关卡、委派执行、自动遥测）提供了生产环境的安全保障——全部可选，均可开关控制。

🔀 原生 Git 开发

每个任务使用独立的工作树——无需切换分支，也不会产生冲突。内置代码评审功能，提供统一的差异查看器和内联评论。审批工作流（批准、请求修改、拒绝）。可视化解决合并冲突。可以直接从任务详情面板创建 GitHub Pull Request。双向同步 GitHub Issues，并支持标签映射。

📁 零基础设施

任务以 Markdown 文件存储，设置以 JSON 格式保存，工作流则用 YAML 描述。无需数据库、Docker 或 Redis。克隆仓库后，运行 pnpm install 和 pnpm dev 即可完成部署。所有内容都易于 grep 搜索、版本控制且人类可读。只需执行 git push，即可备份整个看板。

🔌 三种集成接口

• MCP 服务器 — 通过模型上下文协议接入 7 大类中的 33+ 种工具（v4.0 新增项目管理和评论 CRUD 功能）
• CLI — 使用 vk begin <id> / vk done <id> "summary" 替代原本需要 6 次 API 调用的操作，仅需 2 条命令
• REST API — 提供完整的生命周期管理。任何能够发起 HTTP 请求的系统都可以驱动该平台。

📋 包含所有配置选项的完整功能参考： docs/FEATURES.md

📋 完整功能列表

核心看板

• 拖放式看板 — 在待办、进行中、阻塞、已完成之间移动任务
• Markdown 存储 — 人类可读的任务文件，附带 YAML 前言
• 深色/浅色模式 — 在设置中切换深色与浅色主题

代码工作流

• Git 工作树 — 每个任务使用独立分支，自动清理
• 代码评审 — 统一差异查看器，支持内联评论
• 审批工作流 — 批准、要求修改或拒绝
• 合并冲突 — 提供可视化的冲突解决界面
• GitHub PRs — 直接从任务详情创建拉取请求

AI 代理

• 代理编排 — 为任务启动自主编码代理
• 自定义代理 — 可以添加任意名称和命令的自定义代理，不限于内置类型
• 跨平台 API — REST 端点适用于任何代理平台
• 原生 OpenClaw 支持 — 与 OpenClaw 原生集成
• Squad Chat — 实时代理间通信，支持 WebSocket 更新、系统生命周期事件、每条消息的模型归属信息以及可配置的显示名称
• @提及通知 — 解析评论中的 @agent-name，并支持线程订阅
• 广播通知 — 基于优先级的持久化通知，带有已读回执和针对特定代理的送达机制
• Squad Chat Webhook — 可配置的 Webhook（通用 HTTP 或 OpenClaw Direct），用于外部代理集成
• 代理注册表 — 提供服务发现功能，包括心跳监测、能力描述和实时状态
• 多代理仪表板 — 实时侧边栏，包含可展开的代理卡片和状态指示器
• 多代理任务分配 — 为每个任务分配多个代理，并用不同颜色的芯片区分
• 权限级别 — 实习生/专家/负责人三个层级，配备审批工作流
• 错误学习 — 结构化失败分析，支持相似性搜索
• 任务生命周期钩子 — 内置 7 个钩子、8 种事件，以及自定义钩子 API
• 任务交付物 — 一类优先级的交付对象，可追踪类型和状态（代码、文档、数据等）
• 高效轮询 — /api/changes?since=... 端点支持 ETag，优化代理轮询
• 审批委派 — 支持假期模式下的分权审批及自动路由
• OpenClaw 集成 — 提供直接网关唤醒功能，实现实时 Squad Chat 通知和代理编排
• 反向代理就绪 — 可部署在 nginx、Caddy、Traefik 或任何反向代理之后，只需启用 TRUST_PROXY
• 多次尝试 — 可以更换不同代理重试，并保留历史记录
• 运行指示器 — 当代理正在工作时，提供视觉反馈

工作流引擎

• YAML 工作流定义 — 将多步骤的代理编排流水线定义为受版本控制的 YAML 文件
• 可视化执行 — 实时运行视图，显示逐步进度、状态指示器和输出预览
• 顺序与高级步骤类型 — 代理步骤、循环迭代、门控审批、并行扇出/扇入
• 循环步骤 — 遍历集合，并支持可配置的完成策略（全部完成、任意完成、首次成功）
• 门控步骤 — 基于条件的阻塞，结合人工审批、超时升级以及基于表达式的条件判断
• 并行步骤 — 并发执行多个子步骤，支持多种完成条件（全部完成、任意完成、N 个中的 M 个）
• 运行状态管理 — 持久化运行状态可在服务器重启后恢复，支持指数退避重试，并可恢复被阻塞的运行
• 工具权限策略 — 基于角色的工具限制（默认 5 种角色：规划者、开发者、评审者、测试者、部署者），并支持自定义角色的 CRUD 操作
• 会话隔离 — 每个工作流步骤都在全新的 OpenClaw 会话中运行，支持可配置的上下文注入
• 监控仪表板 — 包含摘要卡片、实时活跃运行列表、近期历史记录以及按工作流划分的健康指标
• 实时更新 — 以 WebSocket 为主，回退至轮询；连接时 API 调用次数减少 75%
• 工作流 API — 提供 9 个 CRUD 端点，用于管理工作流定义、运行及控制
• 增强的验收标准 — 支持正则表达式模式、JSON Path 等值检查以及子字符串匹配，用于步骤验证
• 安全加固 — 提供 ReDoS 防护、防止表达式注入、并行 DoS 限制以及门控审批验证机制
• 进度文件跟踪 — 每次运行共享一个 progress.md 文件，用于在步骤间传递上下文
• 审计日志 — 所有工作流变更都会记录到 .veritas-kanban/workflows/.audit.jsonl
• RBAC — 基于角色的访问控制，适用于工作流的执行、编辑和查看

强制性门控

• squadChat — 自动将任务生命周期事件发布到 squad chat
• reviewGate — 在任务完成前需获得 4x10 的评审分数
• closingComments — 在完成前需提供 ≥20 字的交付物摘要
• autoTelemetry — 在状态变更时自动发出 run.started/run.completed 事件
• autoTimeTracking — 根据状态变化自动启动或停止计时器
• orchestratorDelegation — 当编排者直接执行实现工作而非委派时发出警告

可见性与自动化

• GitHub Issues 同步 — 在 GitHub Issues 与您的看板之间实现双向同步
• 活动页面 — 包含可点击的任务导航、颜色编码徽章和每日摘要的状态历史
• 每日站会摘要 — 可通过 API 或 CLI 生成站会报告（vk summary standup）
• 任务模板 — 创建可复用的模板，支持默认值、子任务和多任务蓝图
• 文档新鲜度 — 通过新鲜度头信息和自动化过时检测来维护工作流文档
• 成本预测 — 对任务进行多因素成本估算

仪表板

• 时间去向 — 根据遥测数据按项目细分的时间分布
• 活动时钟 — 24 小时甜甜圈图，展示代理的工作模式
• 每小时活动 — 按小时统计事件数量的柱状图
• 墙时切换 — 显示代理总工作时间及平均运行时长
• 会话指标 — 会话数量、成功率以及完成情况追踪
• Markdown 渲染 — 在任务描述和评论中支持富文本 Markdown
• 时区感知指标 — 服务器报告本地时区；客户端可通过 ?tz= 参数请求任何时区的指标
• 分析 API — 提供时间线可视化及聚合指标（并行度、吞吐量、前置时间）

组织管理

• 子任务 — 将复杂工作分解并跟踪进度
• 任务依赖关系 — 双向依赖关系图，具备环路检测、递归树 API 和可视化徽章功能
• 崩溃恢复检查点 — 保存/恢复/清除代理状态，并自动清理敏感信息
• 观察记忆 — 为每个任务记录观察内容，支持重要性评分、全文搜索和时间线视图
• 冲刺管理 — 通过 CLI 和 MCP 提供完整的冲刺 CRUD 功能，并配备建议引擎
• 归档 — 可搜索的归档库，支持一键恢复
• 时间跟踪 — 支持启动/停止计时器或手动录入
• 活动日志 — 记录任务事件的完整历史

设置与定制

• 模块化设置 — 分为 8 个专注标签页（通用、看板、任务、代理、数据、通知、安全、管理）
• 安全加固 — 防止 XSS 攻击、路径遍历和原型污染
• WCAG 2.1 AA — 全面的无障碍设计，包括 ARIA 标签和键盘导航
• 错误边界 — 每个标签页独立处理崩溃，并提供恢复选项
• 性能优化 — 标签页懒加载、组件记忆化以及保存操作防抖
• 导入/导出 — 支持备份和恢复所有设置，并进行验证

集成

• CLI — 使用 vk 命令进行终端工作流操作
• MCP 服务器 — 通过 Model Context Protocol 集成 7 大类共 33+ 种工具
• 通知 — 支持 Teams 集成，用于任务更新

---

🛠️ 技术栈

层级	技术	版本
前端	React、Vite、Tailwind CSS、Shadcn UI	React 19、Vite 7.3、Tailwind 4.2
后端	Express、WebSocket	Express 5.2
语言	TypeScript（严格模式）	5.7
存储	带有 YAML 前置元数据的 Markdown 文件	gray-matter
Git	simple-git、工作树管理	—
测试	Playwright（端到端）、Vitest（单元）	Playwright 1.58、Vitest 4
运行时	Node.js	22+
包管理器	pnpm	9+

---

🏆 为什么选择 Veritas Kanban？

大多数代理型 AI 工具通常属于以下两类之一：一是功能强大但“隐形”的编排框架（如 CrewAI、AutoGen、LangGraph）；二是界面美观但完全缺乏代理意识的项目看板工具（如 Jira、Linear、Notion）。

Veritas Kanban 则介于两者之间。它是一个代理工作的可视化指挥中心——在这里，您可以清晰地看到代理正在做什么、已经完成了什么以及即将执行什么，同时拥有完整的审计轨迹和生产环境的安全保障措施。

VK 有何不同之处

	Veritas Kanban	CrewAI / AutoGen / LangGraph	Jira / Linear / Plane
可视化任务看板	✅ 拖拽式看板	❌ 仅代码，无 UI	✅ 看板 UI
AI 代理编排	✅ 原生，多模型	✅ 核心功能	❌ 无代理工作流
YAML 工作流管道	✅ 循环、门控、并行	⚠️ 仅代码定义	❌
实时代理仪表盘	✅ 状态、模型归属	❌	❌
代理间通信	✅ 小队聊天与生命周期事件	⚠️ 仅内部通信	❌
MCP 服务器	✅ 33+ 工具	❌	❌
CLI	✅ 全生命周期	❌	⚠️ 有限
Git 工作树 + 代码评审	✅ 内置	❌	❌
任务持久化	✅ Markdown 文件	❌ 内存中	✅ 数据库
强制性门控机制	✅ 6 种可配置门控	❌	❌
时间和成本跟踪	✅ 每任务、每模型	❌	⚠️ 基本
无需数据库	✅ 磁盘上的文件	✅	❌ 需要 DB
开源	✅ MIT	⚠️ 不同	⚠️ 不同
平台无关性	✅ 任何代理、任何模型	⚠️ 受框架限制	N/A

总结： 编排框架让你执行代理任务，却缺乏可见性。项目看板提供可见性，却无法执行代理任务。而 Veritas Kanban 则兼具两者——同时还具备生产级代理工作所需的护栏、遥测和审计追踪。

基于 OpenClaw 构建并经过实战检验。适用于任何能够发起 HTTP 请求的平台。

---

🔄 工作原理

  任意 AI 代理 / CLI / MCP 客户端
           │
           ▼
┌──────────────────────────────┐
│      REST API + WebSocket    │
│    http://localhost:3001     │
│                              │
│  ┌───────┐  ┌───────────┐    │
│  │ 任务  │  │ 工作流  │    │
│  │  API  │  │ 引擎  │    │
│  └───┬───┘  └─────┬─────┘    │
│      │            │          │
│      ▼            ▼          │
│   Markdown    YAML 工作流 │
│    文件       + 运行状态   │
└──────────────────────────────┘
           │
           ▼
   React 19 + Vite 前端
   http://localhost:3000

看板是事实真相的来源。代理通过 REST API 交互——创建任务、启动工作流、更新状态、记录时间、提交完成情况。工作流编排多步骤代理流水线，支持循环、门控和并行执行。前端通过 WebSocket 实时反映所有内容。无供应商锁定：只要能发起 HTTP 请求，就能驱动看板。

---

🏗️ 架构

veritas-kanban/                  ← pnpm 单体仓库
│
├── web/                         ← React 19 + Vite 前端
│   └── src/
│       ├── components/          ← UI 组件（Shadcn + 自定义）
│       ├── hooks/               ← React Query 钩子，WebSocket
│       └── lib/                 ← 工具函数，API 客户端
│
├── server/                      ← Express + WebSocket API
│   └── src/
│       ├── routes/              ← REST 端点 (/api/v1/*)
│       ├── services/            ← 业务逻辑
│       └── middleware/          ← 认证、限流、安全
│
├── shared/                      ← TypeScript 类型与契约
│   └── src/types/               ← Web 和服务器共享
│
├── cli/                         ← `vk` CLI 工具
├── mcp/                         ← 用于 AI 助手的 MCP 服务器
├── docs/                        ← Sprint 和审计文档
│
├── tasks/                       ← 任务存储（Markdown 文件）
│   ├── active/                  ← 当前任务（.gitignored）
│   ├── archive/                 ← 归档任务（.gitignored）
│   └── examples/                ← 首次运行的示例任务
│
└── .veritas-kanban/             ← 运行时配置与数据
    ├── config.json
    ├── workflows/               ← YAML 工作流定义
    ├── workflow-runs/           ← 运行状态及步骤输出
    ├── tool-policies/           ← 基于角色的工具限制
    ├── worktrees/
    ├── logs/
    └── agent-requests/

数据流： Web ↔ REST API / WebSocket ↔ 服务器 ↔ 磁盘上的 Markdown/YAML 文件

---

📖 API 版本控制

所有 API 端点均支持版本化路径。当前（也是默认）版本为 v1。

路径	描述
/api/v1/tasks	规范的版本化端点
/api/tasks	向后兼容的别名（与 v1 相同）

每个响应都包含 X-API-Version: v1 头部。客户端也可以选择请求特定版本：

curl -H "X-API-Version: v1" http://localhost:3001/api/tasks

• 非破坏性更改（新增字段、新增端点）会添加到当前版本。
• 破坏性更改将推出新版本（如 v2）。旧版本将在弃用期内继续可用。
• 未版本化的 /api/... 别名始终指向最新稳定版本。

---

💻 CLI

📖 完整 CLI 指南： docs/CLI-GUIDE.md — 包括安装、所有命令、脚本示例和使用技巧。

只需两条命令即可管理整个任务生命周期。

# 全局安装
cd cli && npm link

设置与入门

vk setup                         # 引导式环境检查 + 示例任务
vk setup --skip-task             # 仅检查，不创建示例任务
vk setup --json                  # 机器可读输出

验证 Node.js 版本、服务器健康状况、API 认证，并可选地创建欢迎任务以帮助你快速上手。

工作流命令

vk begin 和 vk done 命令将多步骤的 API 工作流简化为单个命令。这一设计灵感来源于 Boris Cherny（Claude Code 的创建者）的理念：“凡是重复两次的事情，就自动化它。”

之前（6 个独立的 curl 请求）：

curl -X PATCH http://localhost:3001/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"in-progress"}'
curl -X POST http://localhost:3001/api/tasks/<id>/time/start
curl -X POST http://localhost:3001/api/agent/status -H "Content-Type: application/json" -d '{"status":"working","taskId":"<id>","taskTitle":"Title"}'
# ... 工作进行中 ...
curl -X POST http://localhost:3001/api/tasks/<id>/time/stop
curl -X PATCH http://localhost:3001/api/tasks/<id> -H "Content-Type: application/json" -d '{"status":"done"}'
curl -X POST http://localhost:3001/api/tasks/<id>/comments -H "Content-Type: application/json" -d '{"author":"agent","text":"summary"}'

之后（2 个命令）：

vk begin <id>                    # → 进行中 + 计时器 + 代理工作状态
vk done <id> "Added OAuth"       # → 计时器停止 + 完成 + 添加评论 + 代理空闲状态

命令	功能
vk begin <id>	设置任务为进行中 + 启动计时器 + 代理状态设为工作
vk done <id> "summary"	停止计时器 + 设置任务为完成 + 添加评论 + 代理状态设为空闲
vk block <id> "reason"	设置任务为阻塞 + 添加带有原因的评论
vk unblock <id>	设置任务为进行中 + 重新启动计时器

基本任务管理

vk list                          # 列出所有任务
vk list --status in-progress     # 按状态筛选
vk show <id>                     # 查看任务详情
vk create "Title" --type code    # 创建任务
vk update <id> --status review   # 更新任务

时间跟踪

vk time start <id>               # 开始时间跟踪
vk time stop <id>                # 停止时间跟踪
vk time entry <id> 3600 "desc"   # 手动添加时间记录（秒）
vk time show <id>                # 显示时间汇总

评论

vk comment <id> "Fixed the bug"           # 添加评论
vk comment <id> "Done" --author Veritas    # 指定作者

代理状态

vk agent status                  # 显示当前代理状态
vk agent working <id>            # 设置为工作状态（自动获取任务标题）
vk agent idle                    # 设置为空闲状态
vk agent sub-agent 3             # 设置子代理模式，并指定数量

项目管理

vk project list                  # 列出所有项目
vk project create "my-app" --color "#7c3aed" --description "Main app"

GitHub 同步

vk github sync                   # 触发手动同步
vk github status                 # 显示同步状态
vk github config                 # 查看或更新配置
vk github mappings               # 列出 issue↔任务映射关系

代理相关命令

vk agents:pending                # 列出待处理的代理请求
vk agents:status <id>            # 检查代理是否正在运行
vk agents:complete <id> -s       # 标记代理已完成

实用工具

vk summary                       # 项目统计信息
vk summary standup               # 每日站会摘要
vk notify:pending                # 检查未读通知

所有命令都支持 --json 参数，便于脚本化和机器消费。

---

🤖 代理集成

Veritas Kanban 可与任何能够发起 HTTP 请求的代理平台协同工作。REST API 覆盖了完整的任务生命周期——创建、更新、时间跟踪、完成。

该系统基于 OpenClaw（原 Clawdbot/Moltbot）构建并测试过，后者通过 sessions_spawn 提供原生编排功能。内置的代理服务专为 OpenClaw 设计——欢迎为其他平台开发适配器。

工作原理

1. 启动代理 — 在 UI 中点击代码任务上的“启动代理”按钮（或直接调用 API）
2. 创建请求 — 服务器将请求写入 .veritas-kanban/agent-requests/
3. 代理接收 — 您的代理读取请求并开始工作
4. 执行工作 — 代理更新任务状态、跟踪时间、提交代码
5. 完成任务 — 代理调用完成端点并返回结果
6. 更新任务 — 任务状态变为“评审”，同时发送通知

任意平台（REST API）

💡 使用 CLI？ 跳过 curl 命令——vk begin <id> 和 vk done <id> "summary" 可以一步完成整个生命周期。详细信息请参阅 CLI 指南。

# 创建任务
curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"title": "Implement feature X", "type": "code", "status": "in-progress"}'

# 开始时间跟踪
curl -X POST http://localhost:3001/api/tasks/<id>/time/start \
  -H "X-API-Key: $YOUR_KEY"

# 标记完成
curl -X POST http://localhost:3001/api/agents/<id>/complete \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $YOUR_KEY" \
  -d '{"success": true, "summary": "What was done"}'

GitHub Issues 同步

# 触发手动同步
curl -X POST http://localhost:3001/api/github/sync \
  -H "X-API-Key: $YOUR_KEY"

# 查看同步状态
curl http://localhost:3001/api/github/sync/status \
  -H "X-API-Key: $YOUR_KEY"

带有 kanban 标签的 GitHub Issues 会被导入为任务。状态变化会反向同步（完成 → 关闭，重新打开为待办/进行中/阻塞）。诸如 priority:high 和 type:story 等标签会映射到任务字段。可在 .veritas-kanban/integrations.json 中进行配置。

OpenClaw（原生支持）

# 检查待处理的代理请求
vk agents:pending

# OpenClaw 子代理使用 sessions_spawn 执行工作，
# 并自动调用完成端点。

---

🔗 MCP 服务器

通过 Model Context Protocol 提供跨 7 个类别（任务、代理、自动化、通知、摘要、冲刺、项目）的 33+ 种工具。

→ 完整 MCP 文档 — 包括架构、快速入门、带示例的工具目录、安全模型和故障排除。

快速配置（Claude Desktop / Cursor / OpenClaw）：

{
  "mcpServers": {
    "veritas-kanban": {
      "command": "node",
      "args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
      "env": {
        "VK_API_URL": "http://localhost:3001"
      }
    }
  }
}

添加配置后，重启 OpenClaw：

openclaw gateway restart

使用 openclaw mcp list 验证发现。如果服务器未显示，请参阅 故障排除。

MCP 连接问题故障排除：

• MCP 配置更改后务必重启 OpenClaw — MCP 服务器在启动时被发现
• 验证工具是否可用： 运行 openclaw mcp list 确认 26 个 Veritas Kanban 工具已出现
• 报告问题时，请提供：
  • OpenClaw 版本 (openclaw --version)
  • VK 版本和健康状态 (curl http://localhost:3001/api/health)
  • MCP 日志 (~/.openclaw/logs/mcp.log 在 macOS/Linux 上)
  • API 可访问性测试 (curl -H "X-API-Key: your-key" http://localhost:3001/api/tasks)

详情请参阅 完整的 MCP 故障排除指南。

📄 任务格式

任务是带有 YAML 前言的 Markdown 文件：

---
id: 'task_20260126_abc123'
title: '实现功能 X'
type: 'code'
status: 'in-progress'
priority: 'high'
project: 'rubicon'
git:
  repo: 'my-project'
  branch: 'feature/task_abc123'
  baseBranch: 'main'
---

## 描述

任务详情在此...

---

🧑‍💻 开发

pnpm dev        # 启动开发服务器（Web 和 API 并发）
pnpm build      # 生产构建
pnpm typecheck  # TypeScript 严格检查
pnpm lint       # ESLint
pnpm test       # 单元测试（Vitest）
pnpm test:e2e   # 端到端测试（Playwright）

---

📚 文档

文档	描述
功能	完整的功能参考
API 参考	认证、端点、WebSocket 文档
CLI 指南	全面的 CLI 使用指南
自托管指南	生产部署、反向代理、Docker
部署	Docker、裸金属、环境配置
故障排除	常见问题及解决方案
贡献指南	如何贡献、PR 指南
安全策略	漏洞报告
行为准则	社区指导原则
变更日志	发布历史
冲刺文档	冲刺计划与审计报告

---

📸 截图

点击展开截图

板概览

任务管理

任务附加功能

指标与仪表盘

设置

菜单与活动

---

🗺️ 路线图

请参阅 公开问题 了解接下来的计划。欢迎社区贡献！

在 v4.0.0 中发布

• #178 — 代理策略与防护引擎 — 可配置的工具/动作策略，支持允许、拒绝和需审批的防护规则
• #179 — 带假设跟踪的决策审计轨迹 — 记录决策及其置信度分数、证据和结果跟踪
• #180 — 代理输出评估与评分框架 — 带加权标准的综合评分体系
• #181 — 行为漂移检测与告警 — 基于指标基线的可配置告警阈值
• #182 — 带情感分析的用户反馈循环 — 收集反馈并进行情感标签化及聚合分析
• #183 — 可拖拽且可调整大小的仪表盘组件网格 — 拖放式布局并支持状态持久化
• #184 — 带版本控制的提示模板注册表 — 版本化的模板，支持回滚和使用情况跟踪
• #185 — 全局系统健康状态栏 — 覆盖系统、代理和操作信号的五级健康状态
• #186 — 升级至 shadcn/ui CLI v4.0 — 所有组件均已更新，集成 Tailwind v4

待办事项

• WCAG 2.1 AA 无障碍标准 — 完整的键盘导航、屏幕阅读器支持、色彩对比度
• 示例视频 — 在 YouTube 或 Vimeo 上托管的演示视频

在 v3.3.x 中发布

• 任务依赖关系图 — 双向依赖模型，具备环路检测、递归树 API 和可视化标记功能
• 崩溃恢复检查点机制 — 保存/恢复/清除代理状态，自动清理敏感信息，限制为 1MB，有效期 24 小时
• 观察记忆 — 每个任务的观察记录，带重要性评分（1–10），支持全文搜索和时间线视图
• 代理筛选器 — 可通过 ?agent=name 参数按代理名称查询任务
• 冲刺管理 CLI + MCP — 从命令行和 MCP 实现完整的冲刺 CRUD 操作（列出、创建、更新、删除、关闭、建议）
• 任务↔代理状态同步 — 双向同步引擎，确保任务状态与代理执行保持一致
• 编排器委派强制执行 — 完整的强制执行门控，支持委派违规报告
• Express 5 + Vite 7 + Tailwind 4 + Zod 4 迁移 — 重大依赖库升级
• SSRF Webhook 防护 — 服务器端请求伪造防护措施
• WebSocket 广播批处理 — 防止高频更新导致事件循环阻塞

在 v3.2.0 中发布

• Markdown 编辑器 — 丰富的编辑工具栏、实时预览以及用于任务描述和评论的快捷键（Ctrl+B/I/K）
• 共享资源注册表 — 可复用资源（提示、指南、模板），可在不同项目间挂载使用
• 文档新鲜度 — 新鲜度追踪，提供新鲜度评分、告警并自动生成审核任务
• Docker 认证持久化 — 修复了容器重建时认证状态被清除的问题；新增自动迁移功能

在 v2.1.2 中发布

• Docker 路径解析 — 修复了容器化部署中 .veritas-kanban 目录的 WORKDIR 解析问题

在 v2.1.1 中发布

• 反向代理支持 — 添加了 TRUST_PROXY 环境变量，适用于 nginx、Caddy、Traefik 等反向代理
• 提示模板注册表 — 集中式提示模板，支持版本管理和代理特定定制

在 v2.0.0 中发布

• 仪表盘小部件切换开关 · 多代理仪表盘 · 多代理任务分配 · @提及通知 · 代理权限级别 · 代理自我报告 · CLI 使用情况报告 · Markdown 渲染 · 成本预测 · 错误学习 · 任务生命周期钩子 · 文档新鲜度 · 时间去哪了 · 活动时钟 · 每小时活动 · 真实时间切换 · 会话指标 · 生产环境绑定

在 v1.6.0 中发布

• 模型使用模式与 API · 全局使用量汇总 · 仪表盘模型使用情况 · 站立会议附带成本 · 按模型划分的成本表格 · 仪表盘筛选栏 · 健康状况端点

在 v1.1.0–v1.3.0 版本中发布

• API 响应封装 · 熔断器 · 负载测试 (k6) · Prometheus/OTel · 存储抽象层 · GitHub Issues 同步 · 活动动态 · 每日站会

---

💬 支持

所有支持与功能请求均通过 GitHub 进行：

• 🐛 Bug 报告 — 新建议题
• 💡 功能请求 — 新建议题
• ❓ 问题与讨论 — GitHub Discussions

注意： 我们不通过电子邮件或社交媒体提供支持。GitHub 是本项目所有沟通的唯一权威来源。

---

🙏 致谢

特别感谢 Peter Steinberger 和 OpenClaw（前身为 Clawdbot/Moltbot）——正是这个平台启发了本项目，并让自主代理编排仿佛魔法一般。

---

📜 许可证

MIT © 2026 Digital Meld

---

Veritas Kanban 快速上手指南

Veritas Kanban 是一个本地优先的任务管理与 AI Agent 编排平台，专为希望结合可视化看板与自主编码代理的开发者设计。它无需数据库，所有数据以 Markdown 和 JSON 文件形式存储，便于版本控制。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: macOS, Linux 或 Windows (WSL2 推荐)
• Node.js: 建议安装最新 LTS 版本 (项目基于 TypeScript 5.7+)
• 包管理器: 必须安装 pnpm (项目未使用 npm/yarn)

  # 如果未安装 pnpm，可通过 npm 全局安装
  npm install -g pnpm
  

• Git: 用于克隆仓库及管理任务文件版本

国内加速提示：如果访问 GitHub 克隆速度慢，建议使用国内镜像源（如 Gitee 镜像）或配置 Git 代理。安装 pnpm 时若遇网络问题，可切换淘宝镜像： npm config set registry https://registry.npmmirror.com

2. 安装步骤

只需几分钟即可完成本地部署：

1. 克隆项目仓库

   git clone https://github.com/BradGroux/veritas-kanban.git
   cd veritas-kanban
   

2. 安装依赖

   pnpm install
   

3. 配置环境变量 复制示例配置文件到服务器目录，并根据需要修改管理员密钥（VERITAS_ADMIN_KEY）。

   cp server/.env.example server/.env
   # 使用编辑器修改 server/.env 文件，强烈建议更改默认密钥
   

4. 启动开发服务器

   pnpm dev
   

3. 基本使用

启动成功后，终端会显示服务地址。

1. 访问看板 打开浏览器访问：http://localhost:3000

   • 首次运行时，看板会自动填充示例任务供你探索。

2. 清理示例数据（可选） 如果你希望从一个空白看板开始，删除示例任务文件并刷新页面：

   rm tasks/active/task_example_*.md
   

   (Windows PowerShell 用户请使用: Remove-Item tasks/active/task_example_*.md)

3. 核心工作流

   • 创建任务：在看板上直接新建卡片，任务将以 .md 文件形式保存在 tasks/ 目录。
   • 编排 Agent：在任务详情页中，可以召唤自主编码 Agent（如 OpenClaw）执行代码编写、修复或审查工作。
   • Git 原生开发：每个任务自动关联独立的 Git Worktree，支持在看板内直接进行代码审查、解决冲突并提交 PR。

4. 恢复示例数据 如果需要重新查看示例任务（仅在看板为空时有效）：

   pnpm seed
   

安全提示：切勿将 .env 文件提交到版本控制系统。AI Agent 拥有执行代码和修改文件的权限，请在受控的本地环境中运行，并遵循最小权限原则。