akb

AKB — Agent 知识库

面向 AI Agent 的组织记忆。 基于 PostgreSQL 的原生知识库，通过 Model Context Protocol（MCP） 提供服务 — Agent 可直接读取和写入， 并使用混合语义 + 关键词搜索、结构化表格、文件和 URI 图谱。可作为 Claude Code、Cursor、 Windsurf 及任何支持 MCP 的 Agent 的 Confluence / Notion 即用替代方案。

兼容

任何支持 MCP（Streamable HTTP 或 stdio） 的 Agent 客户端：

• Claude Code — CLI / VS Code / JetBrains
• Claude Desktop — macOS / Windows
• Cursor、Windsurf、Cline、Continue — 通过 akb-mcp stdio 代理
• 自定义 Agent — 使用 Bearer 令牌直接发送 HTTP POST /mcp/

默认流程使用个人访问令牌。通过 Keycloak 作为 AS 启用可选的 MCP OAuth 资源服务器路径（参见 docs/mcp-clients/web-connectors.md）的部署， 也支持 Claude Code 的 mcp add --transport http + mcp login 流程， 无需 PAT 即可完成全流程。

MCP 协议兼容性

AKB 在两个协议适配器后共用同一套工具和授权核心：

界面	现代版	旧版
直接 HTTP /mcp/	2026-07-28 无状态 server/discover，以及每个请求携带的 _meta，包含 Mcp-Protocol-Version / Mcp-Method（命名调用还包含 Mcp-Name）	2024-11-05、2025-03-26、2025-06-18、2025-11-25 初始化、无状态请求（无 Mcp-Session-Id 生命周期）
akb-mcp stdio 代理	2026-07-28 发现机制和每请求元数据	2025-06-18 初始化

代理会在本地响应任一握手，并在可用时将后端调用规范化为现代无状态契约。对于不支持现代发现机制的旧后端，代理可以回退到 旧版初始化；如果旧服务返回会话 ID，代理会保留该 ID。 当前后端的两个适配器均以无状态方式运行。单个进程 不能混用不同代协议；不支持的修订版或相互冲突的协议 证据会在工具或本地文件操作运行前触发安全失败。

插件

除了原始 MCP 访问能力，AKB 还为 Claude Code 和 Codex 提供现成的 Agent 插件，用于封装常见的知识库工作流：

• akb-wiki — 将来源（本地文件、网页 URL、GitHub PR / 发布版本 / 提交、Confluence 页面或 Jira 事项）导入知识库，作为结构化 文档；也可基于知识库内容回答问题，提供有依据、有引用的综合回答 （只读）。
• akb-sessions — 将编码会话整理为结构化笔记：会话 报告，以及后续任务、经验、想法和决策。
• akb-claude-code — Claude Code 生命周期桥接插件：钩子将每个 会话关联到你的 AKB 记忆知识库，在开始时注入偏好设置和近期经验， 并在结束时写入回顾。

/plugin marketplace add dnotitia/akb        # Claude Code
codex plugin marketplace add dnotitia/akb   # Codex

安装详情和凭据：plugins/。

在线体验

公共演示版运行于 akb-demo.agent.seahorse.dnotitia.ai。 浏览并搜索一个小型虚构组织的知识库，其中包含产品文档、公司手册、Agent 会话笔记和工程 Wiki，这些内容通过 URI 图相互关联。无需注册，直接在浏览器中使用。若要将其接入你自己的 Agent，请使用任意邮箱注册（临时邮箱也可以），然后将 akb-mcp 代理指向 https://akb-demo.agent.seahorse.dnotitia.ai/mcp/。

⚠️ 临时演示版。 它是公开的，每周都会清空并重新填充，且仅使用最低限度的资源运行，不保证正常运行时间、隐私或数据安全。请勿在其中放入任何真实或敏感内容——请将每次写入都视为公开且短暂的。 如需实际使用，请通过 Docker Compose 或 Kubernetes 自行托管。

为什么选择 AKB

大多数知识工具都是为人类通过界面点击操作而构建的。Agent 需要不同的形式：结构化文档、一次调用即可完成语义搜索和关键词搜索、显式关系，以及完整的版本历史。AKB 为 Agent 提供一组工具（akb_put、akb_search、akb_browse、akb_relations、……），用于操作基于 PostgreSQL 的原生修订存储和混合索引。现有部署仍可继续使用显式的 Bare Git 安装。

检索质量

只有检索到正确的笔记，记忆才有用。AKB 的混合检索（稠密检索 + BM25，按来源去重）在 LongMemEval-S 上进行了基准测试——包含 500 个长上下文问题，每个问题约对应 50 个聊天会话。Recall@5 = 98.4%，且未使用重排器。

系统	R@5	n	重排器	来源
AKB 混合检索	98.4%	500	否	本仓库
MemPalace 混合检索 + 重排	98.4%	450	是	MemPalace
gbrain 混合检索	97.6%	500	否	gbrain-evals
gbrain 向量检索	97.4%	500	否	gbrain-evals

方法说明、分类结果明细，以及一条命令即可复现的测试工具位于 eval/longmemeval/。各系统使用的嵌入模型有所不同（AKB：bge-m3@1024），因此请将此结果视为技术栈层面的比较。

设计理念

保持核心精简；通过扩展而非内置自动化来实现灵活性。 AKB 不附带自己的整合器、摘要器或“知识园丁”——而是将每次写入都记录为 PostgreSQL outbox 中的结构化事件。配置 redis_url 后，发布器会将这些事件分发到 Redis Stream（akb:events）。运营人员可在此基础上接入任何外部消费者（定期综合机器人、文档过期清理器、每周摘要 Agent、审计跟踪等），无需修改核心代码。基础契约是一个读写存储；至于如何处理这些知识，则由外部决定。

架构

┌──────────────────────────────────────────────────────────┐
│                  Access Layer                            │
│   MCP Server  │  REST API  │  Web UI                     │
├──────────────────────────────────────────────────────────┤
│                  Core Services                           │
│   Document (Put/Get)  │  Search (Hybrid: dense+BM25)     │
│   Relations (graph)   │  Session  │  Publications        │
├──────────────────────────────────────────────────────────┤
│                  Storage Layer                           │
│   Native revisions     │  PostgreSQL 16 (text + meta SoT)│
│                        │  Vector store (driver):         │
│                        │    pgvector        (default, PG)│
│                        │    qdrant          (optional)   │
│                        │    seahorse-cloud  (managed)    │
│                        │    seahorse-db     (self-hosted)│
│                        │    seahorse-db-grpc(experimental)│
└──────────────────────────────────────────────────────────┘

PostgreSQL 是事实来源——其中存储分块文本、元数据和 BM25 词汇表。 向量存储是可插拔驱动的派生索引，用于保存稠密嵌入和语料库侧的稀疏向量。若向量存储完全丢失，可通过将 chunks.vector_indexed_at = NULL 设为 NULL，并让索引工作进程重新填充索引，从 PG 中恢复。

核心概念

• Vault — 访问控制和知识组织的基本单位。原生版本记录存储在 PostgreSQL 中；旧版后端则为每个 vault 使用一个裸 Git 仓库。
• Collection — vault 内的目录，用于按主题对文档分组。
• Document — Markdown + YAML frontmatter，针对 Agent 的读写进行了优化。
• Hybrid Search — 在一次调用中通过 RRF 融合稠密（语义）搜索与 BM25（词法）搜索。
• Relations — frontmatter 中的 depends_on、related_to、implements 构成显式知识图谱。
• akb_sql 中的 vault 隔离 — 由 PostgreSQL ACL 强制实施。每个 AKB 用户都有对应的 PG 角色（akb_user_<uid>），每个 vault 都有三个组角色（akb_vault_<vid>_{reader,writer,admin}）。akb_sql 使用 SET LOCAL ROLE，在事务中运行用户的 SQL；跨 vault 引用会直接返回 PG 42501。应用端不会使用正则表达式检查用户 SQL 中是否包含禁止的标识符。详见 docs/designs/pg-native-rbac/。

MCP 工具（节选）

工具	描述
akb_list_vaults / akb_create_vault	Vault 管理
akb_put / akb_get / akb_update / akb_delete	文档 CRUD（版本记录 + 索引）
akb_put_file / akb_get_file / akb_update_file / akb_delete_file	文件附件 — 代理端处理（需要本地文件系统）
akb_put_image / akb_discard_image	经过验证的内嵌 Markdown 图片 — 在 akb-mcp 2.2+ 中由代理端处理
akb_create_table / akb_alter_table / akb_drop_table / akb_sql	表格内容 — 每篇文档的表格 + SQL
akb_browse	树形遍历（collection → 文档）
akb_search / akb_grep	混合搜索（稠密 + BM25）/ 字面 grep
akb_drill_down	章节级检索
akb_relations / akb_link / akb_unlink / akb_graph	知识图谱
akb_edit / akb_diff / akb_history	原位编辑、差异、版本历史
akb_grant / akb_revoke / akb_set_public	权限边界 — 按用户、按组织、公开
akb_publish / akb_unpublish	公开发布

Agent 记忆和会话生命周期不是 MCP 工具 — 它们通过专用的 /api/v1/agent-sessions REST 接口提供，由 AKB 生命周期插件（akb-claude-code、akb-cursor、……）驱动；这些插件会挂接到 Agent 自身的 SessionStart / PreCompact / SessionEnd 事件。作为 Agent，你自己的记忆 vault（agent-memory-{username}）可以通过标准的 akb_search / akb_browse / akb_get 工具浏览，方式与其他 vault 完全相同。

任何 MCP 客户端都可以通过 akb_help() 获取完整的工具目录。

MCP 中的内嵌文档图片

内嵌图片是隐藏的文档附件，不是可浏览的文件。上传本地 PNG、JPEG、GIF 或 WebP 文件（最大 10 MiB），然后插入返回的 Markdown，不要自行重构其资源 URL：

image = akb_put_image(
  parent="akb://eng/coll/specs",
  file_path="/workspace/architecture.png",
  alt_text="Request processing architecture")

akb_put(
  parent="akb://eng/coll/specs",
  title="Request Processing",
  content="# Architecture\n\n" + image.markdown)

对于现有文档，请先使用 akb_get，再通过指定 base_commit=... 的 akb_edit 定向编辑。不要只将图片片段传给 akb_update(content=...)，因为这会替换整个正文。图片字节不可变：替换图片意味着上传新图片并编辑 Markdown 引用。删除图片时，请移除其 Markdown 表达式；只有在上传未能成功提交到文档时，才使用 akb_discard_image。运行 akb_help(topic="images")，了解保留和发布行为。

图片工具需要匹配的后端版本以及 akb-mcp 2.2 或更高版本。升级时，请先部署后端，然后发布/安装代理，并重启现有 MCP 进程，使其加载更新后的工具列表。

文档格式

每个知识库资源都有一个感知位置的 AKB URI，这是所有工具使用并存储在关系中的规范句柄。截至 0.3.0：

akb://{vault}                                          vault root (browse target)
akb://{vault}/coll/{coll_path}                         collection (browse target)
akb://{vault}[/coll/{coll_path}]/doc/{filename}        document
akb://{vault}[/coll/{coll_path}]/table/{name}          table
akb://{vault}[/coll/{coll_path}]/file/{uuid}           file

对于位于知识库根目录的资源，会省略 /coll/{coll_path} 段。沿着 URI 向上查找其父集合只是纯字符串操作——将父级 URI 粘贴到 akb_browse(uri=...)，即可列出同级资源，无需额外查询。

对于大型知识库，请从 akb_browse(uri=..., depth=0, page_size=100) 开始，并不断跟进 next_cursor，直到 complete=true，或深入某个集合。有关分页、部分结果和保护性 grep 错误，请参阅有界导航和字面搜索范围限制。

---
title: "Payment API v2 migration plan"
type: plan              # note | report | decision | spec | plan | session | task | reference
status: active          # draft | active | archived | superseded
tags: [payments, api]
domain: engineering
summary: "REST → gRPC transition plan."
depends_on: ["akb://eng/coll/specs/doc/payment-api-v2.md"]
related_to: ["akb://eng/coll/meetings/doc/2026-05-01-payments.md"]
---

# Payment API v2 migration plan
...

兼容 Open Knowledge Format（OKF）

使用显式的 Bare Git 后端时，知识库会存储为由 .md 文件和 YAML-frontmatter 文件组成的 git 树，文件路径即其身份——这与 Google Cloud 的 Open Knowledge Format（OKF v0.1）采用相同的模型。AKB 在规范出现之前便独立得出了这一模型。由 AKB 编写的捆绑包符合 OKF 的全部三项 MUST 规则。服务端的 akb_export({"vault": "<vault>", "format": "okf"}) 和经过身份验证的 GET /api/v1/vaults/{vault}/export?format=okf，通过文档服务同时支持 PostgreSQL Native 和 Bare Git。捆绑包包含文档，以及以概念文档表示的表格和文件。

下方的离线 CLI 会读取现有的 Bare Git 工作树；它不会读取 Native 存储。请从 backend/ 目录运行：

cd backend
uv run python -m app.cli okf-export --from-git /data/vaults/_worktrees/<vault> \
    --vault <vault> --out ./okf-out/
uv run python -m app.cli okf-validate ./okf-out/

OKF 和 AKB 相辅相成——OKF 标准化的是知识的书写方式；AKB 则负责存储、版本管理、搜索、治理知识，并将其提供给 Agent。映射关系和示例捆绑包见 okf/。

快速开始

全新安装使用 PostgreSQL Native，并配有持久化的安装身份和显式的数据库引导配置。请使用新的 Compose 项目和从未使用过的数据库。现有安装必须先按照升级前保留数据的操作流程操作，然后才能使用此版本；更改默认值不会迁移现有数据。

推荐的技术栈运行 PostgreSQL（带 pgvector）、MinIO、API、独立的工作进程和前端。一次性服务会在应用启动前准备 File 存储桶和 Native 权威数据。需要 Docker Compose 2.24.4+。请配置兼容 OpenAI 的嵌入端点以启用密集搜索；嵌入不可用时，pgvector 和 Qdrant 会降级为仅使用 BM25 的词法搜索。

MinIO 使用镜像，并在 Quay 移除该镜像后固定原始上游服务器的摘要。 本地、评估、CI 和全功能构建使用同一制品；存储桶引导配置和全功能构建使用该服务器镜像中捆绑的 mc。

# 1. Build this checkout's images. For a registry installation, use a backend
# image pinned as registry.example.com/akb-backend@sha256:... instead.
docker build -t akb-backend:native-local ./backend
docker compose -p my-native-install build frontend postgres
export AKB_NATIVE_IMAGE="$(docker image inspect akb-backend:native-local --format '{{.Id}}')"
export AKB_NATIVE_CONFIG_DIR="$PWD/config/native"

# 2. Prepare installation assets ONCE. Keep them and the original template.
mkdir -p "$AKB_NATIVE_CONFIG_DIR"
cp config/app.yaml.example "$AKB_NATIVE_CONFIG_DIR/template.yaml"
cp config/secret.yaml.example "$AKB_NATIVE_CONFIG_DIR/secret.yaml"
$EDITOR "$AKB_NATIVE_CONFIG_DIR/template.yaml" # provider and public URL settings
$EDITOR "$AKB_NATIVE_CONFIG_DIR/secret.yaml"   # credentials and independent secrets

docker run --rm -v "$AKB_NATIVE_CONFIG_DIR:/installation" \
  "$AKB_NATIVE_IMAGE" python -m app.cli generate-local-session-keyset \
  --output-dir /installation/local-session
docker run --rm -v "$AKB_NATIVE_CONFIG_DIR:/installation" \
  "$AKB_NATIVE_IMAGE" python -m app.cli prepare-native-config \
  --source /installation/template.yaml --secret /installation/secret.yaml \
  --output /installation/app.yaml --tenant-id my-installation --namespace akb \
  --image-digest "${AKB_NATIVE_IMAGE##*@}"

# 3. Use the same project, files and environment on every subsequent operation.
docker compose -p my-native-install \
  -f docker-compose.yaml -f docker-compose.native.yaml up -d --no-build

# 4. Provision the local recovery administrator with an operator-owned password.
docker compose -p my-native-install \
  -f docker-compose.yaml -f docker-compose.native.yaml \
  exec -T backend python -m app.cli provision-recovery-admin local \
  --username recovery-admin --email [email protected] \
  --password-file - < /secure/operator/recovery-admin.password

open http://localhost:3000

升级时，请更新检出内容，并在执行第 3 步之前重复第 1 步。up --no-build 绝不会进行构建，因此无法获取新检出内容所构建的镜像（frontend、postgres）：缺少镜像会导致失败，旧镜像则会继续运行。在将 PostgreSQL 改为构建镜像的那次升级中，跳过第 1 步会使 API（backend）停止运行，随后报错 No such image: my-native-install-postgres:latest，导致 API 无法运行。

本地镜像 ID 固定的是本地构建的字节内容，而非注册表摘要。对于分布式安装，请先构建并推送，然后使用注册表摘要作为 AKB_NATIVE_IMAGE。升级工作负载镜像时，请保持生成的初始化镜像凭据不变。重启时切勿重新生成身份或本地会话密钥。在 Linux 上，请确保操作员能够读取并备份容器创建的资产（或使用操作员的 UID/GID 运行准备程序）。 生成的 app.yaml 和配套的 secret.yaml 是应用配置的唯一来源，并以只读方式挂载到 /etc/akb。 AKB_PROCESS_ROLE=all|api|worker 仅用于选择进程组合； AKB_TOKENIZER_PROCESSES=1..4 可降低 tokenizer 并发数。修订版本选择不通过环境变量切换。

有关镜像升级、引导恢复和 Kubernetes，请参阅原生安装指南。 Compose 指南保留了明确的 Bare Git 升级路径。在此版本中，Helm、all-in-one 和独立 SSO 仍是 旧版 Bare Git 兼容路径。原生模式不支持文档模板或外部 Git 导入；其发现机制和 API 会拒绝这些功能。现有的迁移、历史记录、差异和活动记录兼容性仍予以保留。

常规注册始终会创建非管理员帐户，包括数据库为空时。管理员引导仅可通过运维 CLI 完成；没有未经身份验证的 HTTP 引导端点。CLI 配置必须与 auth_mode 匹配：

# Local: have AKB generate the password only when an operator-owned output
# file is explicitly requested. A new file is created with mode 0600 and the
# password is not written to stdout, stderr, logs, or application config.
python -m app.cli provision-recovery-admin local \
  --username recovery-admin --email [email protected] \
  --generate-password-file /secure/operator/recovery-admin.password

# SSO: pre-bind the product administrator to the exact external identity.
# Username and email are snapshots; issuer + subject are the identity key.
python -m app.cli provision-recovery-admin sso \
  --username recovery-admin --email [email protected] \
  --issuer https://issuer.example.com/realms/akb \
  --subject exact-provider-subject

完全相同的身份信息具有幂等性。指定的身份类型不同、用户名或电子邮件已存在，或者外部身份已绑定时，操作都会安全失败。SSO 命令不会存储可用的本地密码，也不会联系身份提供商。生成的输出文件仅在创建时写入，绝不会覆盖；若文件已存在而需要重试，请通过 --password-file 传入该文件。

两种本地形式还有一个区别。使用 --generate-password-file 时，AKB 会生成凭据并交付给调用者，因此它创建的帐户必须更换该凭据：首次使用该凭据打开的会话只能进入密码更改页面，无法访问其他内容，行为与密码重置完全相同。使用 --password-file 时，安装的是调用者已经持有的值——AKB 不会将其交付给任何人——因此不会要求更换凭据；若安装期间使用此帐户登录以引导服务身份，该登录仍可正常使用。若要强制更换以这种方式提供的凭据，请随后使用下方命令轮换；轮换后帐户始终需要更改密码。

如果该凭据之后泄露、丢失或需要撤销，请轮换凭据，而不是重新配置帐户：

# Break-glass: replace the credential and print the new one once. Nothing
# stores or logs the value, and the machine-readable report omits it.
python -m app.cli issue-recovery-admin-credential \
  --expected-username recovery-admin \
  --expected-email [email protected]

轮换操作会指明预期帐户，并拒绝任何不匹配，因此不会误操作其他帐户。被替换的凭据会立即失效，包括当前正在使用的凭据；轮换前持有的会话也会被撤销——这两项都是应对凭据泄露所必需的。同一操作也可通过 POST /admin/recovery-admin/issue-credential 执行，但需要独立的服务管理员令牌，而不是人工会话。sso 模式下无法轮换：凭据由身份提供商持有，运行中的 AKB 无法替换它。

打开 /admin 以访问独立的产品管理界面。在 local 模式下，该界面接受已配置的本地管理员，并返回本地人工身份验证使用的同一 local-session-rs256-v2 配置，但会拒绝非管理员帐户。在 sso 模式下不存在本地凭据：/admin 使用带有 PKCE 和 nonce 的专用机密 akb-admin Keycloak 客户端进行身份验证，随后只接受精确预绑定的 (issuer, subject)，且对应的 AKB 帐户必须仍处于启用状态并满足 is_admin=true。 在 SSO 模式下，同一个 /admin 界面可以配置内置上游 IdP、将其保存为禁用状态、查看其准确的 broker 重定向 URI，并启用或禁用其普通登录选项，而无需重新部署 AKB。只有在服务端浏览器会话功能就绪后，该选项才会成为可用按钮。客户端密钥只允许写入，不允许读取；重新配置已启用的提供方前，必须先将其禁用。 请参阅 SSO 提供方指南、基于标准的 通用 OIDC 集成，以及更严格的 Keycloak OIDC 参考。现有 Kubernetes 安装还应遵循 从本地认证切换到 SSO 的操作手册，而不要将 auth_mode 视为一次滚动部署中的单行配置变更。

专用管理回调不会存储 Keycloak 访问令牌、刷新令牌或 ID 令牌。它会创建一个短期、不透明的 HttpOnly 管理 Cookie 和一个 CSRF 令牌； PostgreSQL 只存储它们的哈希值和准确的身份快照，并在每次请求时重新检查账户、未变更的外部绑定以及管理员标志。一次性 OIDC 状态也会绑定到一个短期 HttpOnly Cookie，因此复制到其他浏览器的回调会在令牌交换前失败。 配置 keycloak_admin_client_secret，在专用客户端中注册 <public_base_url>/api/v1/admin/auth/keycloak/callback 和 <public_base_url>/admin，并确保管理客户端 ID 不会进入任何 API/MCP 资源客户端路径。除明确允许的回环开发例外情况外，面向浏览器的 AKB 和 Keycloak URL 必须使用 HTTPS。

普通 SSO 登录使用独立的 akb-web 客户端。浏览器只会收到不透明的 HttpOnly AKB 会话和可读取的 CSRF 值；SSO 不会签发 AKB 用户 JWT。AKB 使用独立的 sso_browser_session_encryption_key 加密 Keycloak 刷新令牌/ID 令牌集，且绝不会持久化访问令牌。客户端必须使用 oidc-usersessionmodel-note-mapper，将 Keycloak 的 identity_provider 用户会话备注映射到 ID 令牌和访问令牌；AKB 会在回调时以及每次刷新时，将该已签名的 broker 别名绑定到所选的已启用提供方。生产环境的 HTTPS Cookie 使用浏览器强制要求的 __Host- 前缀、Secure、不设置 Domain，并使用 Path=/；回环 HTTP 则使用隔离的开发环境名称。将密钥生成为 32 个随机字节，并以无填充的 base64url 编码；在重启期间保持密钥不变。有关刷新、注销和后端通道撤销的详情，请参阅 Keycloak 边界。

本地 JWT 迁移与轮换

本地登录仅签发版本化的 local-session-rs256-v2 配置文件：使用由安装方持有的 RSA-3072 密钥进行 RS256 签名，包含 RFC 7638 kid、准确的部署签发者/受众、jti，并在 GET /api/v1/auth/jwks 提供仅含公钥的 JWKS。从不受信任的令牌 alg 标头中选择验证器。由 HS256 版本升级会触发明确的强制重新登录边界：在发布前生成并持久化 v2 密钥集，设置 jwt_algorithm: RS256，并同时重启所有后端。现有 HS256 用户会话随后会收到 401，用户必须重新登录；PAT 和服务密钥不会被撤销。旧的 jwt_secret 仅可保留一个版本，用作短期内部 HMAC 功能的迁移输入，或原样重命名为 system_hmac_secret；它绝不会用作人类会话的签名材料。

常规轮换 v2 密钥时，生成新目录，同时保留当前公开的 JWKS，发布新的不可变 Secret/配置修订版本，并将所有后端滚动部署到这一准确的配置对：

cd backend
uv run python -m app.cli generate-local-session-keyset \
  --output-dir /secure/akb/local-session-next \
  --retain-jwks /secure/akb/local-session-current/jwks.json

至少保留公钥至 jwt_expire_hours 加上部署滚动时间偏差后，再在后续协调的密钥集修订版本中移除它。回滚方式是恢复之前的私钥/JWKS 配对；绝不要原地覆盖密钥文件。

向量存储（驱动可插拔）

有关权重约定、外部统计信息消费者和 posting 回滚要求，请参阅 BM25 统计信息和仅使用 VChord 的部署。

混合搜索（稠密 + BM25 稀疏，使用 RRF 融合）通过驱动接口运行。提供五种驱动，可在配置时选择：

• pgvector（默认）——使用存储应用数据的同一个 Postgres 容器。安装流程会根据 deploy/postgres/Dockerfile 构建该容器的镜像：包含 pgvector 和 vchord_bm25 BM25 索引，因此新数据库默认使用 vchord 稀疏形态。该驱动会创建单独的 vector_index schema，因此主 chunks 表仍是纯 PostgreSQL。RRF 融合在应用端运行。无需运维外部服务。
• qdrant——运行单独的 Qdrant 容器；通过 Query API 原生支持 RRF。适合已经在运行 Qdrant，或希望独立于 Postgres 扩展向量存储的场景。
• seahorse-cloud——通过 BFF 管理 API 和每个表的数据平面主机（Bearer 身份验证）连接到托管的 Seahorse Cloud 表。无需自行运行基础设施；在 Seahorse 控制台中创建表（或由驱动自动创建），AKB 会将其分块存储在那里。原生支持 RRF 和服务端 BM25。端到端设置指南（注册 → 令牌 → schema → 配置）请参阅 docs/vector-store-seahorse.md。
• seahorse-db——通过 Coral 协调器 HTTP API 连接到自托管的 SeahorseDB 集群。需要自行运行 Coral、Writer、Reader(s)、Redis、Kafka 和稀疏嵌入服务（SeahorseDB 单体仓库的 deploy/docker-compose.yml 会启动最精简的单机栈）。原生支持稠密 + 稀疏混合搜索。与其他驱动不同，它在嵌入 API 不可用时不支持仅使用 BM25 回退（其稀疏路径在服务端运行，并在结构上依赖可用的嵌入步骤）——使用此驱动时，请确保嵌入端点始终可访问。
• seahorse-db-grpc（实验性）——使用与 seahorse-db 相同的 Coral 协调器和 seahorsedb_* 设置，但通过 gRPC 而非 REST/JSONL 通信。Coral 将 axum 和 tonic 合并到同一个监听器，因此端口不变，只有线缆格式不同。它以类型化 protobuf 消息和 Arrow IPC 流式结果，取代 JSON 解析路径（以及 INT64 符号不匹配、Arrow JSON 解码器边缘情况等一类易出错问题）。在 gRPC 版本通过自身的 QPS / 召回率基准测试之前，生产环境请优先使用 REST 驱动。它与 REST 驱动具有相同的 CRUD 功能对等性（通过了相同的 25 个场景混合端到端测试），但尚未像 REST 驱动那样经过生产规模的验证。

切换驱动只需修改配置（无需迁移主数据库的 schema）：

# Default flow targets pgvector.
docker compose up

# Qdrant:
docker compose -f docker-compose.yaml -f docker-compose.qdrant.yaml up
$EDITOR config/app.yaml     # vector_store_driver: qdrant
                            # vector_url: http://qdrant:6333

# Seahorse Cloud (managed; full guide in docs/vector-store-seahorse.md):
docker compose up           # no extra container needed
$EDITOR config/app.yaml     # vector_store_driver: seahorse-cloud
                            # seahorse_cloud_tenant_uuid: <your tenant>
                            # seahorse_cloud_table_name: <your table>
$EDITOR config/secret.yaml  # seahorse_cloud_token: shsk_<...>

# SeahorseDB (self-hosted cluster reached via the Coral coordinator):
docker compose up           # run the SeahorseDB stack separately
$EDITOR config/app.yaml     # vector_store_driver: seahorse-db
                            # seahorsedb_coordinator_url: http://localhost:3003
                            # seahorsedb_table_name: akb_chunks

嵌入模型和维度也可通过 embed_base_url / embed_model / embed_dimensions 完全插拔——代码库没有硬编码模型。对于使用 HNSW 的 pgvector，请将 embed_dimensions ≤ 2000（使用 halfvec 时为 4000）；维度更大的模型会回退到精确扫描。Qdrant / Seahorse（cloud 或 db）没有此限制（Qdrant 最高支持 65536，Seahorse 最高支持其表定义的维度）。

大模型功能（可选）

大模型仅由 metadata_worker 用于自动标记通过外部 Git 镜像导入的文档。核心 CRUD／搜索功能无需大模型即可运行。要启用此功能，请在 app.yaml 中设置 llm_base_url／llm_model，并在 secret.yaml 中设置 llm_api_key。

独立部署默认采用 model_api_governance_mode: external_metering，并可将嵌入、聊天和重排功能指向任何兼容的提供商。托管控制平面则可以设置 platform_hard 和精确的 platform_gateway_base_url。在该模式下，如果活动模型路由指向其他位置或缺少凭证，AKB 将无法启动；每次模型调用都会携带由调用方生成的 Idempotency-Key，用于网关的持久化预留／结算。网关策略或预算拒绝绝不会被拆分为针对每个项目的重试。

事件分发（可选）

PG events outbox 始终会写入数据。在 app.yaml 中设置 redis_url，即可让 events_publisher 工作进程将 outbox 数据排入 Redis Stream（akb:events），以便外部服务通过 XREAD／consumer groups 订阅。留空则禁用 Redis 分发；经过身份验证的 GET /api/v1/events/{vault} SSE 尾随接口会读取同一个 PG outbox。原生文档写入会在权威事务边界参与此 outbox。关于受支持的文件／文档操作、移动时的身份标识、重试语义和消费者恢复，请参阅变更事件契约。

审计日志（可选）

默认关闭。在 app.yaml 中设置 audit.enabled: true，即可在 MCP 分发关口生成结构化、仅追加的哈希链式 JSON 行审计日志，统一记录每次读取、写入和身份验证拒绝。AKB 仅作为生成方：它不会存储、查询或保留审计数据；由你的 SIEM（Splunk／QRadar／Elastic）抓取数据流，并根据自身的合规制度负责保留。每行都带有单调递增的 seq 和 sha256(prev ‖ line)，因此可验证数据链中是否有行被丢弃或篡改，并可在重启后从磁盘重新建立链。还可以将每日轮换的文件移交到 WORM 对象存储存储桶（audit.bucket——使用 Object Lock 和仅写密钥进行配置，以获得真正不可变的审计记录）；只有确认上传成功后，才会清理本地缓冲区。日志捕获尽力而为，绝不会影响服务请求流程。完整的 audit: 配置块请参阅 config/app.yaml.example。

生产环境部署

对于 Kubernetes，请从部署指南开始。AKB 通过 Helm 和 Kustomize 提供独立本地资源集和独立 SSO 资源集。

• 对于标准的 helm upgrade --install 工作流，请使用无依赖的 AKB Helm chart。
• 对于独立 Kustomization，请使用 deploy/k8s；对于由安装方管理的 Keycloak 堆栈，请使用 deploy/k8s/standalone-sso。
• 两种方式都会使用预先存在、由运维人员管理的 Kubernetes Secrets。AKB 不会安装或运行凭证服务或同步控制器。

真实主机名、镜像仓库、存储类、TLS 签发方和提供商设置应写入 Helm values 或由运维人员管理的 Kustomize overlay；请勿将生产凭证提交到此仓库。

项目结构

akb/
├── backend/                  # Python 3.14 / FastAPI / asyncpg / GitPython
│   ├── app/
│   │   ├── api/routes/       # REST endpoints
│   │   ├── services/         # Business logic + workers
│   │   └── db/               # PostgreSQL schema + migrations
│   ├── mcp_server/           # Streamable HTTP MCP server
│   └── tests/                # E2E shell tests
├── frontend/                 # React 19 + TypeScript + Vite + Tailwind
├── packages/
│   ├── akb-client/           # REST SDK boundary (npm: @akb/client)
│   └── akb-mcp-client/       # stdio ↔ HTTP MCP proxy (npm: akb-mcp)
├── agents/                   # Reference Python agent runtime (think/act loop over MCP)
├── plugins/                  # Claude Code / Codex agent plugins (ingest, query, session capture, lifecycle)
├── templates/                # Doc templates (ADR, PRD, runbook, …) and vault profiles
├── okf/                      # Open Knowledge Format interop: positioning + sample bundle
├── design-system/            # Frontend design system docs
├── config/
│   ├── app.yaml.example      # Non-secret runtime settings
│   └── secret.yaml.example   # API keys, passwords (gitignored when not .example)
├── deploy/
│   ├── all-in-one/           # Single-container demo image
│   ├── helm/
│   │   └── akb/              # AKB chart with local and standalone-SSO profiles
│   └── k8s/
│       ├── *.yaml            # Standalone AKB + PostgreSQL resources
│       └── standalone-sso/   # Standalone plus owned Keycloak and its database
└── docker-compose.yaml       # Local stack (PG + MinIO + API + worker + frontend)

技术栈

• 后端：Python 3.14、FastAPI、Uvicorn、asyncpg、GitPython、MCP SDK
• 数据库：PostgreSQL 16（主数据库无需扩展；同一个 pgvector/pgvector 镜像承载可选的 vector_index 架构）
• 向量存储：驱动可插拔（默认使用 pgvector；可选 Qdrant、 Seahorse Cloud 或可自托管的 SeahorseDB — 混合稠密向量 + BM25 稀疏检索、RRF 融合；嵌入服务不可用时回退为仅 BM25）
• 事件流（可选）：PG events 发件箱 + Redis Streams 扇出
• 审计日志（可选）：在 MCP 调度点生成哈希链式、只追加的 JSONL + 可选的 WORM S3 交接；仅负责生成（由 SIEM 负责保留）
• 前端：React 19、TypeScript、Vite、Tailwind CSS v4、Radix UI
• 身份验证：本地 RS256 会话或 Keycloak SSO，以及用于 API 和 MCP 访问的个人访问令牌 （PAT）
• MCP：可流式 HTTP（后端）+ stdio 代理（npm 上的 akb-mcp）

版本控制

AKB 遵循 SemVer。后端产品版本位于 backend/pyproject.toml（[project].version）。协调发布时使用 scripts/bump-version.sh <x.y.z> 同步更新该版本与 frontend/package.json。启用镜像构建后，每次运行 deploy/k8s/deploy.sh 都会为 Docker 镜像同时打上显式后端版本 （:${VERSION}）和 :latest 标签，以便仍可拉取历史构建版本用于回滚。

packages/akb-mcp-client（akb-mcp npm 代理）遵循自身的 npm 语义化版本生命周期，不与产品版本绑定。

许可证

AKB 后端、前端和部署清单根据 Business Source License 1.1 许可 — 源码可用，并附带额外使用授权，允许生产环境使用（商业或 非商业），但须低于席位数门槛；每个版本首次公开发布四年后， 将自动转换为 Apache License 2.0。

npm akb-mcp 代理（packages/akb-mcp-client/）单独采用 MIT License 许可，因此可不受限制地自由嵌入任何 Agent 客户端。

后端可免费用于生产环境 — 只要你的部署合计服务的 命名席位少于 100 个（每个部署中 users 表内的不同人类用户账户；服务账户和 90 天未活动的账户除外 — 精确定义请参见 LICENSE）。

以下情况需要商业许可证：

• 后端在生产环境中的命名席位达到或超过 100 个。
• 将 AKB（无论是否修改）作为托管服务、本地部署产品、 嵌入式组件或重新品牌发行版提供给第三方 — 不论席位数多少。

商标 — “AKB”、“Dnotitia”和“Seahorse”是 Dnotitia, Inc. 的商标。软件许可证不授予商标权。 分支和衍生作品必须以不同名称发行。 请参见 TRADEMARKS.md。

有关商业许可、BSL 转换的原因或商标许可申请，请参见 LICENSE-CHANGE.md，或联系 [email protected]。

安全

发现漏洞？请参见 SECURITY.md — 请私下报告， 不要通过公开问题反馈。

参与贡献

请参见 CONTRIBUTING.md。