打造 AI 驱动的公司知识库实战教程

一、核心概述

本教程演示如何基于 Fuma Docs 搭建美观的文档站点，并通过 Sanity 实现内容管理与语义搜索，最终在站点上嵌入 AI 聊天小部件，实现“问我任何关于公司内部信息”。整个过程全部使用 AI 代理完成，零代码或极少代码即可上手。

二、实操步骤与核心流程详解

1. 环境准备

• 安装 Node.js（官网下载对应系统的 LTS 版本）。
• 推荐使用 Cursor、VS Code 等编辑器，亦可直接在终端操作。

2. 初始化 Fuma Docs 项目

npx create-fuma-docs@latest my-company-knowledge-base \
  --template default \
  --install
cd my-company-knowledge-base
npm run dev   # 本地预览，默认 http://localhost:3000

• 访问 http://localhost:3000 可看到带有暗/亮主题切换的文档首页。
• 通过编辑 content/docs/*.md 文件即可增删页面，Fuma Docs 会自动热更新。

3. 了解项目结构

• content/docs/：Markdown 文档根目录，支持 front‑matter（title、description、owner）。
• pages/、components/：自定义页面与 React 组件。
• public/：静态资源。

4. 将内容迁移至 Sanity

• 注册 Sanity 账号，创建项目 Company Knowledge Base。
• 在项目设置中获取 API Token（Developer 权限） 与 Project ID，写入 .env：

SANITY_PROJECT_ID=yourProjectId
SANITY_API_TOKEN=yourToken

• 在本地项目根目录执行：

npm run sanity:setup   # 创建 dataset、导入 schema
npm run sanity:import  # 将本地 Markdown 同步到 Sanity
npm run sanity:status  # 验证导入成功

• 启动 Sanity Studio 本地预览：npm run studio → http://localhost:3333，可在 UI 中直接编辑页面、修改 owner、添加新部门等，无需触碰代码。

5. 切换数据源

• 将 .env 中 CONTENT_SOURCE 改为 sanity，保存后重启 npm run dev。
• 此时站点已从本地 Markdown 读取数据，删除本地文件不影响页面展示，说明已成功对接 Sanity。

6. 添加 AI 聊天小部件

• 在项目根目录创建 widgets/ai-chat.tsx（或 .js），使用 OpenAI/Claude 等模型的 Embedding 与 检索 接口。
• 关键配置：
  • Embedding：Sanity 中的每篇文档在导入时会自动生成向量。
  • 检索 API：调用向量相似度搜索返回最相关的文档片段。
  • 前端 UI：在 pages/_app.tsx 中挂载聊天弹窗组件，支持 Command+K 快捷键呼出。
• 部署后，用户可在任意页面输入自然语言提问，系统会检索 Sanity 中的文档并返回答案。

7. 本地调试与部署

• 本地调试完成后，使用 Vercel、Netlify 或自建服务器部署 npm run build && npm start。
• 将 Sanity Studio 也部署到公开地址（sanity deploy），为非技术人员提供内容编辑入口。

三、实战技巧与核心小结

• AI 代理全程辅助：在任何步骤卡住时，可把本段文字或命令粘贴给 ChatGPT，让其帮你完成环境配置、错误排查。
• 分支管理：建议在 Git 中为每次大改动创建新分支，防止误删 Markdown 文件导致数据不一致。
• 权限控制：Sanity 支持细粒度角色，给部门负责人分配 editor 权限，仅能编辑自己负责的文档。
• 向量成本：使用 Sanity 免费 60 天试用期可免除向量生成费用，正式上线后可评估是否继续使用或自行部署开源向量库（如 Milvus）。
• 常见坑点：
  1. 环境变量未生效 → 确认 .env 已在根目录，重启 dev server。
  2. API Token 权限不足 → 必须勾选 Developer 权限，否则导入会失败。
  3. 本地端口冲突 → 通过 PORT=4000 npm run dev 更改端口。
• 总结：本套方案利用 Fuma Docs 的快速文档搭建、Sanity 的可视化内容管理与向量搜索、以及 AI 聊天小部件 的自然语言交互，实现了从零代码到企业级知识库的完整闭环，适合技术团队与业务团队协同维护。