# 知识库指南

创建知识库、上传技术文档、发布带版本的条目，并让 agent 能够检索带有来源溯源的引用事实。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/knowledge-bases
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 1867d8b68c37e8f52cb96a448217aeea61bf2b42608d8931313472d77f22d9c6
- Edition-Digest: 9ed98c9a7d8b58a4e9d1b868afb25abd8ce95631f983c9f393a960f7eb279a1c
- Source-Revision: sha256:c0d24fff7e465ea3dbb6daf903fbcba1cab87eecc6514e3b935a312cafc20ddd

## 用户目标

在个人或团队工作区中维护结构化知识库，摄取 markdown 和格式化文档，发布经过验证的不可变修订版本，并配置自主 agent 以检索带有来源归属的引用事实。

## 可用性与前提条件

如果您的账户启用了 Knowledge，则可在 Web 控制台的 https://xmemo.dev/me#knowledge（个人工作区）或 https://xmemo.dev/me?space=<team_id>#knowledge（团队工作区）中进行知识库的编写和检查。在开始之前，请确认满足以下前提条件：

- 认证要求：需要处于活动状态的用户会话。未认证的访问将被重定向到 /login（登录页面）。
- 令牌作用域：编程式访问需要 knowledge:read 用于搜索和寻址读取，以及 knowledge:write 用于创建或编辑条目。
- 支持的文件格式：浏览器内文本/代码阅读器支持 .md、.markdown、.txt、.json、.csv、.py、.js、.ts、.tsx、.html、.yaml、.yml 和 .toml。文档内容提取支持 .pdf、.docx、.pptx 和 .xlsx。
- 拖放界面：控制台显示 "Drag & drop files here" 并附带帮助文本 "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)"。

## 1. 在 Web 控制台中创建知识库

在浏览器中导航至 https://xmemo.dev/me#knowledge。点击 "Create Knowledge Base" 打开创建对话框。在 Name 中输入 "Engineering Runbooks"，在 Description 中输入 "Operational runbooks and deployment procedures."。确认创建以初始化活动知识库。

```bash
# Access personal knowledge workspace
https://xmemo.dev/me#knowledge

# Access team knowledge workspace with explicit space parameter
https://xmemo.dev/me?space=<team_id>#knowledge
```

## 2. 添加并发布合成知识条目

打开新创建的 "Engineering Runbooks" 知识库，点击 "Create Knowledge item" 从 markdown 或本地文件创建条目。输入 Title "Deployment Guidelines" 并粘贴初始合成说明。条目以状态 "draft" 初始化：

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.
```

## 3. 发布草稿条目供 agent 检索

在 "draft" 状态下，该条目仅人类编辑者可见。要使其可供 agent 发现，请点击 "Publish"。控制台会显示提示 "Published content becomes eligible for authorized Knowledge search."。确认后，条目状态进入 "published"，将修订版本 1 确立为当前可搜索的修订版本。

- 草稿私密性：草稿条目被排除在 agent 发现和查询搜索之外。
- 发布操作：发布会将条目状态更新为 "published"，并将 current_revision_id 设置为修订版本 1。
- 不可变修订：修订版本 1 的规范内容、哈希值和元数据保持不可变。

## 4. 通过 agent 引用检索知识

在公开 search_knowledge 的客户端环境（如 cursor-plugin 或 ordinary-full）中，经授权的 agent 可以查询已发布的运行手册。该工具会返回带有明确引用参考指针的排序摘录：

```bash
# Query knowledge via standalone Skill CLI
node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true
```

## 5. 更新内容并发布不可变的新修订版本

当技术流程发生变更时，打开 "Deployment Guidelines" 并点击 "Edit Knowledge item"。更新内容以反映新的操作要求。点击 "Save new revision"。控制台显示 "Saving content creates an immutable new revision. Metadata changes do not create a revision."：

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification.
```

## 可观察结果

在 Web 控制台和通过 agent 搜索验证已发布的条目及其修订版本来源溯源：

- 控制台徽章：条目卡片显示状态徽章 "Published" 并指向当前活动的修订版本。
- 修订版本谱系：打开 "Revision history" 会将修订版本 2 显示为当前版本，将修订版本 1 显示为历史版本，并附带时间戳和作者归属。
- Agent 搜索结果：查询搜索仅评估修订版本 2。历史修订版本 1 仍可通过指定确切 knowledge_revision_id 的寻址读取进行访问。

## Agent 可以访问的内容

知识库针对 agent 集成强制执行严格的访问和可见性边界：

- 仅限已发布条目：Agent 无法访问草稿条目。查询搜索仅评估活动知识库中已发布的条目。
- 当前修订版本边界：查询搜索会自动解析至 current_revision_id。被取代的修订版本不会出现在查询搜索结果中。
- 配置文件可用性：只读 MCP 工具 search_knowledge 严格在 cursor-plugin 和 ordinary-full 客户端配置文件中可用 (config/mcp-documentation-contract.json)。其他客户端配置文件使用 recall_context，在启用并授权时会自动包含 Knowledge。
- Recall 行为：当您的账户启用了 Knowledge 且令牌包含 knowledge:read 时，MCP recall_context 会自动包含 Knowledge。并非每个 recall 都会搜索 Knowledge。

## 共享与存储边界

知识库保持严格的空间隔离和管理角色边界：

- 个人空间与团队空间：个人知识库 (/me#knowledge) 对该账户私有。团队知识库 (?space=<team_id>#knowledge) 强制执行团队角色访问控制 (routes/knowledge.py:129-134)。
- 角色能力：Owner 和 Admin 拥有 base:admin 和 item:write 权限（创建、归档、更新、删除知识库和条目）。Member 拥有 item:write 权限（创建、编辑和发布条目）。Viewer 仅拥有读取权限。
- 归档与永久删除：归档（"Are you sure you want to archive knowledge base '<name>'? Archived bases will no longer be retrieved by agents."）可暂停检索而不会丢失数据。永久删除（"Are you sure you want to permanently delete knowledge base '<name>' and all its items? This action cannot be undone."）会物理移除数据。
- 项目记忆独立性：知识库独立于项目的 working/knowledge 记忆分区运行。从项目中取消关联记忆不会触及知识库文档。

## 故障恢复

使用以下诊断步骤解决常见的知识库访问和提取问题：

- 文档内容提取进行中：上传 .pdf、.docx、.pptx 或 .xlsx 文档时，请在显示 "Extraction is still in progress. Try again when it succeeds." 时等待。
- 文档内容提取失败：如果处理失败，控制台会显示 "Extraction failed. Retry the Document from its existing Document surface first."。请验证文件完整性或上传纯 markdown 文本。
- 条目未在 agent 查询中返回：验证条目状态为 "Published"（而非 "draft"），知识库处于活动状态（未归档），并且客户端令牌包含 knowledge:read 作用域。
- 并发更新冲突：如果其他用户或 agent 在您打开编辑时更新了该条目，控制台会显示 "This Knowledge item changed elsewhere. Refresh it and try again."。刷新页面并重新应用更改。
- 搜索模式选择：如果混合搜索遗漏了确切的运行手册符号或配置键，请切换到词法模式 (mode="lexical") 进行精确 token 匹配。

## 相关参考

继续了解知识库概念、相关工具和工作区管理：

- 概念：知识库 (/docs/concepts/knowledge-bases) — 架构模型、修订版本 DAG 和检索模式。
- 工具：search_knowledge (/docs/tools/search-knowledge) — 寻址读取和搜索参数的工具参考。
- 工具：recall_context (/docs/tools/recall-context) — 具备自动 Knowledge 检索功能的上下文打包工具。
- 指南：Memory Console (/docs/guides/memory-console) — 完整的 Web 控制台导航指南。
- 概念：来源溯源与归属 (/docs/concepts/provenance-attribution) — 引用封装与作者归属。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。