Kebivo

Kebivo：面向 AI Agent 的可自托管知识缺口反馈

收集 AI 助手无法回答的问题。

Kebivo 通过 REST 或 MCP 收集 AI Agent 未能回答的问题和建议的知识修正。它会将重复报告归为一组，并通过管理收件箱、电子邮件或签名 Webhook 将其发送给知识维护人员。只需在一个容器中自行运行，无需云账户或 AI 提供商。

Kebivo 可与 Langfuse 和 Phoenix 等可观测性与追踪工具配合使用。这些工具会向工程师展示运行期间发生的情况。Kebivo 会收集 Agent 报告的知识缺口，并将其发送给知识维护人员。它不是 RAG 引擎：不会为追踪记录评分、检索文档或回答问题。请参阅它不会做什么。

在演示中，助手无法回答问题，Agent 便通过 MCP 调用 report_knowledge_gap。一条路由规则通过 Webhook 将报告发送给文档负责人。重复问题会归入同一组，因此计数增加，但不会再次触发提醒。负责人添加备注，并将该组标记为已解决。产品画面是运行真实 Kebivo 容器并使用合成数据生成的截图；聊天内容和片尾卡片为绘制内容。源文件位于 docs/assets/demo-src。

状态：0.1.0，首个版本。 运行已发布的镜像 ghcr.io/ocnai/kebivo:0.1.0（linux/amd64、linux/arm64），或从此仓库构建。基于 Apache-2.0 许可。

从快速入门开始。框架教程请参阅 Kebivo 指南。有关部署、API 行为和限制，请参阅技术文档。

为什么

助手无法回答问题时，文档负责人可能永远不会看到这个问题。同一个问题可能再次回答失败，而聊天中提出的修正也可能永远无法传达到内容维护人员手中。Kebivo 会将这些报告集中到一处，让负责人进行分流，并将其发送到他们使用的工具中。

AI 助手无法回答问题时，Kebivo 会将这些知识缺口发送给文档或支持负责人审核。它会将重复问题归为一组，让负责人了解哪些问题反复出现。它可以与 RAG 应用或 Agent 框架配合使用；但不会为你检索内容或更新知识库。

功能

• 通过 REST 从应用程序代码发送报告，或为 Agent 提供 Streamable HTTP MCP 工具 report_knowledge_gap 和 submit_knowledge_correction。
• 为每个助手或团队创建一个项目，设置默认标签、更正政策和承载令牌。令牌仅显示一次，并可设置过期时间和撤销。
• 使用有序规则、ANY/ALL 标签匹配、每条规则的多个目标、回退目标和试运行模拟器来路由报告。
• 将报告发送到带签名的 Webhook（使用带版本号的 JSON 负载）、SMTP 邮件或内置收件箱。投递失败后会持久化重试并采用退避策略；还支持重启后恢复、投递日志和手动重试。
• 相同的问题会自动分组。你也可以配置 LLM 提供商进行语义分组。
• 在收件箱中管理报告，支持搜索、筛选、状态、备注、标签、合并、拆分和删除。每个分组都有完整历史记录。
• 可按项目启用 OpenAI 兼容、Azure OpenAI 或本地（Ollama、LM Studio）提供商进行语义分组。此功能默认关闭。
• 运行一个容器并使用一个 SQLite 文件。支持启动时迁移、在线备份和校验恢复、数据保留（默认开启）、JSON Lines 导出和健康检查。

截图

所有截图均使用合成数据。

仪表板	收件箱
反馈分组	连接客户端
路由规则	投递失败

更多：目标、设置、LLM 设置、登录。使用 make e2e-ui SCREENSHOTS=1 重新生成。

它不会做什么

• 它不会回答问题、编辑你的知识库或应用更正。所有内容均由人审核。
• 它不是聊天机器人、工单系统或分析产品，而是将反馈交给你使用的工具。
• 不支持多用户账户、SSO 或角色：只有一个本地管理员。
• 不提供托管服务，不进行遥测，也不需要账户。默认安装不会建立任何出站连接，也不需要 AI 提供商。
• 不支持高可用：仅有一个进程，使用本地存储上的一个 SQLite 文件。

快速开始

你需要安装 Docker Compose、OpenSSL，并有一个空闲的 8000 端口。

1. 启动 Kebivo。

git clone <REPOSITORY_URL> kebivo
cd kebivo
cp .env.example .env
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'ENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'ALLOWED_ORIGINS=http://127.0.0.1:8000\n' >> .env
docker compose up --build -d
curl -fsS http://127.0.0.1:8000/health/ready

<REPOSITORY_URL> 是你克隆仓库时使用的地址。首次构建需要几分钟。应用迁移后，就绪检查会返回 {"status":"ok",...}。

或者运行已发布的镜像，而不是克隆和构建。它是同一个容器；请妥善保管 kebivo.env，并将其与数据卷分开备份。

(umask 077; printf 'SECRET_KEY=%s\nENCRYPTION_KEY=%s\nALLOWED_ORIGINS=http://127.0.0.1:8000\n' \
  "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > kebivo.env)
docker run -d --name kebivo --restart unless-stopped -p 127.0.0.1:8000:8000 \
  -v kebivo-data:/data --env-file kebivo.env ghcr.io/ocnai/kebivo:0.1.0
curl -fsS --retry 30 --retry-all-errors --retry-delay 1 http://127.0.0.1:8000/health/ready

迁移运行期间，curl 可能会打印几条 Connection reset 错误，随后就绪检查会返回 {"status":"ok",...}。使用此容器时，将步骤 2 的命令改为 docker exec -it kebivo python -m kebivo.cli bootstrap --email [email protected]，并使用 docker stop kebivo 停止容器；数据会保留在 kebivo-data 卷中。

2. 创建管理员。 命令会提示你输入密码（至少 12 个字符）。

docker compose exec app python -m kebivo.cli bootstrap --email [email protected]

3. 创建项目和令牌。 打开 http://127.0.0.1:8000/（必须使用此地址：localhost 属于不同的来源，会导致登录失败），然后登录。创建项目，再在 项目令牌 下创建一个带有 feedback:gap 范围的令牌并复制。令牌只会显示一次。

4. 发送你的首个事件。

export KEBIVO_TOKEN='<PROJECT_TOKEN>'
curl -i http://127.0.0.1:8000/api/v1/feedback \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KEBIVO_TOKEN" \
  -H 'Idempotency-Key: first-event-001' \
  --data '{"event_type":"knowledge_gap","question":"How do I reset my corporate VPN?","tags":["it"]}'

响应为 202 Accepted，其中包含 event_id。5. 在 UI 中打开收件箱：问题会显示在独立分组中。添加一个目标和一条路由规则，将后续问题发送到电子邮件或 Webhook。

停止服务：运行 docker compose down（数据会保留）。运行 docker compose down --volumes 会删除所有数据。有关生产环境（TLS、备份、升级和所有设置），请阅读自托管指南。

通过 REST 收集 AI Agent 反馈

使用项目令牌发送 POST /api/v1/feedback。202 表示报告已可靠存储；路由和发送会在后台进行。发送 Idempotency-Key，并在重试时重复使用。对于 429 和 5xx 响应，请采用退避策略重试；其他 4xx 错误不要重试。

可运行的客户端示例包括 cURL、Python（标准库）和 TypeScript（Node.js 24，无需构建步骤），都位于 examples/ 中。UI 中的项目页面也会显示相同的代码片段，并替换为你的端点。REST 集成指南介绍了字段、身份验证、幂等性、错误、重试和速率限制。

通过 MCP 报告知识缺口

将 MCP 客户端指向 http://127.0.0.1:8000/mcp，并设置请求头 Authorization: Bearer <PROJECT_TOKEN>。对于 Claude Code：

claude mcp add --transport http kebivo http://127.0.0.1:8000/mcp --header "Authorization: Bearer <PROJECT_TOKEN>"

带有 feedback:gap 范围的令牌可以调用 report_knowledge_gap；调用 submit_knowledge_correction 还需要 feedback:correction 范围，且项目必须接受修正。模型可能不会在应该调用工具时调用它，因此每份报告都很重要时，请使用 REST。请参阅 MCP 指南、客户端配置、Python 客户端和可复制的 Agent 指令。

目标和路由

目标	发送内容
内置收件箱	始终可用；每个事件都会显示在管理员收件箱中。
Webhook	通过 HTTPS POST 发送版本化 JSON 负载，并使用 Standard Webhooks 签名；可选 Bearer 或自定义请求头。接收端示例会验证这两种签名。
SMTP 电子邮件	通过 STARTTLS、隐式 TLS 或未进行身份验证的本地中继，向 1–20 个收件人发送消息（纯文本，并附带转义后的 HTML 版本）。

每个项目都有一组按顺序排列的规则：规则匹配其任意或全部标签，并将事件发送到一个或多个目标，也可以选择停止评估。未匹配的事件会发送到后备目标。例如，it → IT 电子邮件，customer-service → 支持 Webhook。每个目标都可以选择仅对新分组发送，或对每次出现都发送。请参阅路由和目标。

可选 AI

默认情况下不会调用任何模型。若要将措辞不同的问题归为一组，请配置 LLM 提供商（UI 中的 LLM settings），并在确认问题文本会发送给该提供商后，将项目切换为语义去重。如果提供商调用失败，事件仍保留自己的分组，并会照常路由和交付。请参阅去重和LLM 提供商。

安全

• 在 TLS 反向代理后运行，并确保应用端口仅绑定到环回地址（指南）。
• 妥善保管 .env。将 SECRET_KEY 和 ENCRYPTION_KEY 单独备份，不要与数据库备份放在一起。
• 反馈以未加密形式存储在 SQLite 中。请保护存储卷和备份，并且不要让助手发送机密信息或不必要的个人数据。
• 为每个客户端分配独立令牌，仅向面向客户的 Agent 授予 feedback:gap 权限，并撤销不再使用的令牌。
• 除非针对某个目标地址或提供商单独选择允许，否则 Webhook 和 LLM 提供商无法访问私有地址或环回地址；云元数据地址始终会被屏蔽，SMTP 也不例外。管理员写入操作需要配置的 Origin 和 CSRF 令牌。
• 日志中不会包含反馈内容或凭据。

请按照 SECURITY.md 中的说明报告漏洞。

数据、保留与导出

默认启用数据保留策略：每天删除超过 180 天的反馈、超过 30 天的已完成交付尝试详情，以及超过 90 天的审计条目。可通过环境变量更改或禁用各项策略（设为 0 即可关闭）。保留策略不会影响已创建的备份。管理员可以将项目反馈导出为 JSON Lines。请参阅保留策略和导出。

已知限制

• 至少交付一次。 接收方可能会收到重复交付；请根据 Webhook ID 或交付 ID 去重。
• 仅支持一名管理员、一个实例，以及一个存储在本地的 SQLite 文件。不支持副本和网络文件系统。
• MCP 需要手动配置 bearer 令牌；仅支持 OAuth 的客户端无法连接。响应为无状态 JSON，不包含流式通知。
• 速率限制在内存中计数，容器重启后会重置。
• 已删除的反馈无法从已接收该反馈的目标位置或现有备份中撤回。
• 反馈内容静态存储时不会加密。

文档

框架教程请参阅网站上的指南。可运行的客户端和框架示例位于 examples/。以下页面介绍技术细节。

指南	内容
自托管	要求、所有设置、TLS 代理、机密信息、备份与恢复、升级、凭据轮换、故障排查
REST API	身份验证、字段、幂等性、错误、重试、示例
MCP	连接客户端、工具与权限、测试、限制
路由和目标位置	规则、回退、Webhook、签名、SMTP
去重和LLM 提供商	精确分组与语义分组、提供商、隐私
反馈管理	分组、搜索语法、状态、合并、拆分、删除
保留策略和导出	自动删除、JSON Lines 导出
发布	版本管理、镜像标签、发布与升级检查
第三方许可证	随附依赖项清单
变更日志	各版本中用户可见的更改

贡献

开发环境设置、make 目标、代码风格、测试和文档规则见 CONTRIBUTING.md。简而言之：先运行 make install，然后在每次提交前运行 make check，并在同一次变更中更新文档。根据 Developer Certificate of Origin，每次提交都要签署（git commit -s）；无需签署 CLA。

所有参与者都必须遵守行为准则。正在考虑但尚未确定的想法见路线图。

许可证

Kebivo 根据 Apache License 2.0 授权。接受的贡献也采用同一许可证，并须根据 Developer Certificate of Origin 签署；无需签署 CLA。第三方许可证清单列出了该镜像所包含所有内容的许可证。