Knowledge Bases

Base、Item 与 Revision 架构

Knowledge Base 是 owner-scoped 或 team-scoped 的参考文档、规范和 runbook 集合。它将技术知识组织为三个不同的分层实体：

• Knowledge Base：顶层容器（例如 "Engineering Runbooks"）。base 具有名称、描述、状态（active 或 archived）以及空间所有权（Personal 或 Team）。
• Knowledge Item：base 内的独立文档或规范（例如 "Deployment Guidelines"）。item 具有标题、定位符（locator）、状态（draft、published 或 archived）、来源类型（user_created 或 file）以及 current_revision_id 指针。
• Knowledge Revision：包含规范内容（canonical content）、revision 编号、内容格式（如 markdown）、内容哈希、来源元数据和出处来源（provenance）的不可变快照。
• 发布生命周期：item 最初处于 draft 状态。发布后，其当前 revision 即可供 agent 发现。后续编辑会创建不可变的新 revision 并推进当前指针，而不会更改历史 revision。

发布边界与 Agent 可见性

Knowledge Base 在人工编写与自主 agent 检索之间实施严格的发布边界。调用方可在 query search 与 addressed read 之间进行选择。Query search 通过仅评估处于当前活动 revision 的已发布 item 来保证新鲜度：

• 仅限活动 base：已归档（archived）的 base 会被排除在 agent 发现之外。归档会暂停所有包含 item 的检索，而不会销毁内容。
• 仅限已发布 item：草稿（draft）item 在明确发布之前对作者和团队编辑保持私密。Agent 无法在 query search 中发现或引用草稿 item。
• 默认评估当前 revision：Query search 仅评估由 current_revision_id 引用的 revision。被替代的历史 revision 不会作为 query search 结果出现。
• 寻址读取（Addressed read）：寻址读取可以通过在提供 knowledge_item_id 的同时提供 knowledge_revision_id 来检查精确的历史 revision，从而保留可复现的引用。

query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)

检索模式：Hybrid、RRF、Semantic 和 Lexical

搜索运行时支持四种检索模式，以平衡词法精度与语义理解：

• hybrid（默认）：使用参数 alpha（默认 0.5）对归一化词法得分与语义得分进行线性组合。alpha 越接近 1 越偏向精确词法重合，alpha 越接近 0 越偏向概念语义相似度。当向量分数不可用时回退到词法检索。
• rrf（倒数排名融合，Reciprocal Rank Fusion）：使用排名常数 k（默认 60）融合独立的词法与语义排名列表，确保平衡排序而无需分数校准。
• semantic：基于嵌入表示的向量相似度排名，在未配置嵌入时回退到词法匹配。
• lexical：针对精确符号、函数名、错误代码和配置键优化的归一化 token 与短语匹配。

支持的文件类型与上传管线

Knowledge item 可以直接以 markdown 编写，也可以通过两种不同的摄取机制从本地文件导入：

• 浏览器读取的文本与代码文件：纯文本和代码文件（.md、.markdown、.txt、.json、.csv、.py、.js、.ts、.tsx、.html、.yaml、.yml、.toml）直接在浏览器中读取，并保存为规范 markdown 内容。
• 文档提取管线：格式化文档（.pdf、.docx、.pptx、.xlsx）通过 Documents API 上传，经文本提取 worker 处理，一旦提取成功便快照为 Knowledge item。
• 文件边界：摄取边界适用于客户端和服务器环境。为保证可靠处理，请将知识组织为集中、模块化的文档，而不是整块的文件转储。

Agent 访问接口与客户端 Profile

授权的 agent 通过专用的 MCP 工具与独立 Skill 命令访问 Knowledge：

• MCP search_knowledge：专用的只读搜索工具，需要 knowledge:read 令牌范围。特别在 cursor-plugin 和 ordinary-full 客户端 profile（config/mcp-documentation-contract.json）中公开；未在 chatgpt-public 或 generic-public profile 中公开。
• MCP recall_context：当您的账户启用了 Knowledge 且令牌包含 knowledge:read 时，自动在情景记忆之外包含相关 Knowledge item。
• 独立 XMemo Skill：使用显式知识包含执行 recall-context：node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true。
• 范围强制：并非每次 recall 都会自动查询 Knowledge；仅在配置允许、令牌范围许可且受活动客户端 profile 支持时才执行检索。
• REST 配套端点：经过身份验证的配套端点 POST /api/v1/knowledge/search 为后端服务和自定义工具提供对知识搜索的直接编程式访问。

{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}

团队角色、空间与生命周期操作

Knowledge Base 支持具有基于角色的访问控制的个人与协作工作区：

• 角色权能：Owner 与 Admin 拥有 base:admin 和 item:write 权限（创建、归档、更新、删除 base 与 item）。Member 拥有 item:write 权限（创建、编辑和发布 item，但无法删除或归档 base）。Viewer 仅拥有读取权限。
• 空间边界：个人空间（/me#knowledge）对所有者私有。团队空间（?space=<team_id>#knowledge）在经过身份验证的团队成员之间共享已发布的文档。
• 归档与永久删除：归档 base 会将状态设为 archived，立即将所有 item 排除在 agent 查询之外，同时允许完全恢复。永久删除会在物理上不可逆地销毁 base 及所有关联 revision。

与项目记忆的区别

Knowledge Base 提供经过整理的参考文档，其运作机制遵循不同于对话式项目记忆的保障：

• Knowledge Base item：经过整理、版本化的参考文档（例如 runbook、设计文档和编码规范），具有多 revision 历史记录与精确引用关联（knowledge:<item-id>@<revision-id>）。
• 项目 Knowledge/Working 记忆：在项目工作区内分类为持久上下文（knowledge）与瞬态任务状态（working 记忆）的对话式记忆记录。
• 独立性：从项目中移除记忆记录或取消文档关联不会修改、归档或删除底层 Knowledge Base item。

可用性与运行时启用

Knowledge Base 被记录为核心功能，而非 Preview。如果您的账户启用了 Knowledge，则可用性处于活动状态。当后端知识运行时未配置或被禁用时，请求将返回 HTTP 503 与错误代码 knowledge_runtime_disabled。目录方案标识（例如 Plus 方案配额）代表方案许可额度而非运行时强制执行机制；没有任何 API 路由强制执行方案等级。