• AI 应用
• AI Agent
• 人工智能
• 后端
• 前端

Knowledge Agent Template 是一个开源的文件系统与知识库驱动的 AI Agent 模板，帮你构建始终与自己的知识库保持同步的 AI 助手。它最大的亮点是基于文件的检索——不需要向量数据库、不需要 embedding 模型，AI 直接在隔离沙箱中用grep、find、cat搜索你的文档，结果确定、可解释、且几乎零基础设施成本。本文带你完成 Knowledge Agent Template 的本地开发环境配置，只需配置 3 个核心环境变量，就能让自己的知识库被 AI 检索问答。

为什么值得本地跑起来一个知识库 AI 助手？

传统 RAG 方案要维护向量库、分词管道、embedding 模型，链路长且黑盒。Knowledge Agent Template 换了一条路：

• 🔍文件式检索：所有知识源（GitHub 仓库、YouTube 字幕、自定义 API）最终都变成沙箱里的文件，AI 像人一样用命令行去搜、去读
• 🤖多平台部署：同一套 Agent，既能当 Web 聊天应用，也能当 GitHub Bot、Discord Bot
• ⚙️内置管理后台：数据源管理、同步控制、用量统计、API 密钥管理一应俱全
• ⚡实时工具可视化：聊天界面会实时展示 AI 读了哪些文件、跑了哪些命令，没有黑盒

完整架构细节可参考 docs/ARCHITECTURE.md

准备工作：安装依赖并克隆项目

先确保本地已安装 Node.js 运行环境（项目默认使用 bun 作为包管理器），然后克隆仓库：

git clone https://gitcode.com/gh_mirrors/kn/knowledge-agent-template cd knowledge-agent-template bun install

项目由三个包组成：@savoir/sdk（AI SDK 兼容工具）、@savoir/agent（路由、提示词、工具核心）、apps/app（统一的 Nuxt 应用，含聊天 UI + API + 机器人）。bun install会一次性把整个 workspace 装好。

配置 3 个必需环境变量

项目自带了一份环境变量模板，直接复制即可：

cp apps/app/.env.example apps/app/.env

打开apps/app/.env，只需填 3 个必填项（详见 apps/app/.env.example）：

💡 注意要创建GitHub App（不是 OAuth App），同一个 App 后续还能直接驱动 GitHub Bot。配置细节见 docs/ENVIRONMENT.md。

⚠️本地开发需要多填一个可选变量AI_GATEWAY_API_KEY（Vercel AI Gateway 的 API key）。部署到 Vercel 时平台会通过 OIDC 自动鉴权、无需此 key，但本地跑模型路由必须手动填入。

一键启动本地开发服务器

配置完成后，一条命令启动：

bun run dev

应用会运行在http://localhost:3000，数据库迁移（Drizzle ORM）会在启动时自动执行，无需手动操作。第一个注册的用户会自动获得管理员权限，登录后就能进入/admin管理后台。

添加知识源：让 AI 检索你自己的内容

知识源（Source）是知识库的内容定义。进入/admin后台：

1. 打开Sources区域，点击Add source
2. 选择类型：GitHub 仓库（拉取 Markdown 文档）或 YouTube 频道（拉取视频字幕）
3. 填写仓库地址（owner/repo格式）、分支、内容目录等参数
4. 点击Sync触发同步

同步流程会创建一个沙箱、克隆并更新源仓库、把内容过滤后推送到快照仓库。值得留意的是：同步时只保留文档类文件（.md、.mdx、.yml、.yaml、.json），源码、图片、二进制文件都会被自动剔除，保证快照仓库始终"干净"。各字段的完整说明见 docs/SOURCES.md。

开始提问：实时查看 AI 的检索过程

同步完成后，直接在聊天界面提问。界面会实时展示 Agent 的每一步动作：

• 正在grep哪些关键词、cat哪些文件
• 每个工具调用的耗时
• 最终合成带引用的自然语言回答

这就是文件式检索的透明优势：你可以清楚看到答案来自哪份文档，而不是一个"模型感觉"。

小结：3 步跑通本地知识库 Agent

跑通之后，你可以继续探索：通过管理后台定制 Agent 行为、用@savoir/sdk把能力集成进自己的应用、或照着 docs/CUSTOMIZATION.md 添加 Slack、Linear 等新平台适配器。Knowledge Agent Template 就是为"Fork 它、定制它、部署你自己的知识库 AI"而生的。

• AI 应用
• AI Agent
• 人工智能
• 后端
• 前端