用 Vault 系统构建 AI 时代的跨项目知识库

2026年4月10日

用 Vault 系统构建 AI 时代的跨项目知识库

临摹项目学习法正在成为主流，只是学习资料分散、上下文断裂的痛点让 AI 助手难以发挥最大价值。本文介绍 HagiCode 项目的 Vault 系统设计——通过统一的存储抽象层，让 AI 助手能够理解和访问所有学习资源，实现真正的跨项目知识复用。

背景

其实，在 AI 时代，我们学习新技术的方式正在悄然改变。传统的读书、看视频固然重要，但”临摹项目”——深入研究和学习优秀开源项目的代码、架构和设计模式——确实越来越高效。直接运行和修改高质量的开源项目，能让你最快理解真实世界的工程实践。

只是这种方式也带来了新的挑战。

学习资料太分散。笔记可能在 Obsidian 里，代码仓库散落在各个文件夹，AI 助手的对话历史又是一个独立的数据孤岛。每次需要 AI 帮助分析某个项目时，都得手动复制代码片段、整理上下文，过程相当繁琐。

上下文经常断掉。AI 助手无法直接访问本地学习资源，每次对话都得重新提供背景信息。临摹的代码仓库更新快，手动同步容易出错。更糟的是，多个学习项目之间难以共享知识——在 A 项目中学到的设计模式，AI 处理 B 项目时完全不知道。

这些问题的本质是”数据孤岛”。如果能有一个统一的存储抽象层，让 AI 助手能够理解和访问所有学习资源，问题就迎刃而解了。

为了解决这些痛点，我们在开发 HagiCode 时做了一个关键的设计决策：构建一个 Vault 系统作为统一的知识存储抽象层。这个决定带来的变化，可能比想象的还要大——稍后具体说。

关于 HagiCode

本文分享的方案来自在 HagiCode 项目中的实践经验。HagiCode 是一个基于 OpenSpec 工作流的 AI 代码助手，它的核心理念是让 AI 不仅会”说”，更会”做”——能够直接操作代码仓库、执行命令、运行测试。GitHub：github.com/HagiCode-org/site

在开发过程中，我们发现 AI 助手需要频繁访问用户的各类学习资源：代码仓库、笔记文档、配置文件等。如果每次都要用户手动提供，体验就太糟糕了。这促使设计了 Vault 系统。

核心设计

多类型支持

HagiCode 的 Vault 系统支持四种类型，分别对应不同的使用场景：

类型	用途	典型场景
folder	通用文件夹类型	临时学习资料、草稿
coderef	专门用于临摹代码项目	系统化学习某个开源项目
obsidian	与 Obsidian 笔记软件集成	现有笔记库的复用
system-managed	系统自动管理	项目配置、提示词模板等

其中 coderef 类型是 HagiCode 中最常用的，它为临摹代码项目提供了标准化的目录结构和 AI 可读的元数据描述。为什么要专门设计这个类型？因为临摹一个开源项目不是简单的”下载代码”，需要同时管理代码本身、学习笔记、配置文件等多种内容，coderef 把这些都规范好了。

持久化存储机制

Vault 的注册表以 JSON 格式持久化存储到文件系统：

_registryFilePath = Path.Combine(absoluteDataDir, "personal-data", "vaults", "registry.json");

这个设计看似简单，实则经过深思熟虑：

简单可靠。JSON 格式人类可读，便于调试和手动修改。当系统出现问题时，可以直接打开文件查看状态，甚至手动修复——这在开发阶段特别有用。

降低依赖。文件系统存储避免了数据库的复杂性。不需要额外安装和配置数据库服务，降低了系统复杂度和维护成本。

并发安全。使用 SemaphoreSlim 确保多线程安全。在 AI 代码助手的场景下，可能会有多个操作同时访问 vault 注册表，需要做好并发控制。

AI 上下文集成

系统的核心能力在于能够自动将 vault 信息注入到 AI 提案的上下文中：

export function buildTargetVaultsText(
  vaults: VaultForText[],
  template: VaultPromptTemplate = DEFAULT_VAULT_PROMPT_TEMPLATE,
): string {
  const readOnlyVaults = vaults.filter((vault) => vault.accessType === 'read');
  const editableVaults = vaults.filter((vault) => vault.accessType === 'write');

  const sections = [
    buildVaultSection(readOnlyVaults, template.reference),
    buildVaultSection(editableVaults, template.editable),
  ].filter(Boolean);

  return `\n\n### ${template.heading}\n\n${sections.join('\n')}`;
}

这样 AI 助手就能自动理解可用的学习资源，无需用户每次手动提供上下文。这个设计让 HagiCode 的体验变得特别自然——告诉 AI “帮我分析 React 的并发渲染”，AI 就能自动找到之前注册的 React 学习 vault，而不是一遍遍贴代码。

访问控制机制

系统将 vault 分为两种访问类型：

• reference（只读）：AI 仅用于分析和理解，不能修改内容
• editable（可编辑）：AI 可以根据任务需要修改内容

这种区分让 AI 知道哪些内容是”只读参考”，哪些是”可以动手改的”，避免了误操作风险。比如注册了一个开源项目的 vault 作为学习材料，肯定不希望 AI 随手修改里面的代码——那就标记为 reference。但如果是自己的项目 vault，就可以标记为 editable，让 AI 帮着改代码。

实践指南

CodeRef Vault 的标准化结构

对于 coderef 类型的 vault，系统提供了一套标准化的目录结构：

my-coderef-vault/
├── index.yaml          # vault 元数据描述
├── AGENTS.md           # AI 助手的操作指南
├── docs/               # 存放学习笔记和文档
└── repos/              # 通过 Git 子模块管理临摹的代码仓库

这个结构的设计理念是什么？

docs/ 存放学习笔记，用 Markdown 格式记录对代码的理解、架构分析、踩坑经验。这些笔记不仅自己看，AI 也能读懂——在处理相关任务时会自动参考。

repos/ 通过 Git 子模块管理临摹的仓库，而不是直接复制代码。这样做有两个好处：一是保持与上游同步，一个 git submodule update 就能拿到最新代码；二是节省空间，多个 vault 可以引用同一个仓库的不同版本。

index.yaml 包含 vault 的元数据，让 AI 助手快速理解用途和内容。相当于给 vault 写了个”自我介绍”，AI 第一次见到就知道这是干嘛的。

AGENTS.md 是专门写给 AI 助手看的指南，说明如何处理 vault 中的内容。可以在这里告诉 AI：“分析这个项目时重点关注性能优化相关的代码”或者”不要修改测试文件”。

创建和使用 Vault

创建一个 CodeRef vault 很简单：

const createCodeRefVault = async () => {
  const response = await VaultService.postApiVaults({
    requestBody: {
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/Users/developer/vaults/react-learning",
      gitUrl: "https://github.com/facebook/react.git"
    }
  });

  // 系统会自动：
  // 1. 克隆 React 仓库到 vault/repos/react
  // 2. 创建 docs/ 目录用于笔记
  // 3. 生成 index.yaml 元数据
  // 4. 创建 AGENTS.md 指南文件

  return response;
};

然后在 AI 提案中引用这个 vault：

const proposal = composeProposalChiefComplaint({
  chiefComplaint: "帮我分析 React 的并发渲染机制",
  repositories: [
    { id: "react", gitUrl: "https://github.com/facebook/react.git" }
  ],
  vaults: [
    {
      id: "react-learning",
      name: "React Learning Vault",
      type: "coderef",
      physicalPath: "/vaults/react-learning",
      accessType: "read"  // AI 只能读取，不能修改
    }
  ],
  quickRequestText: "重点关注 fiber 架构和 scheduler 实现"
});

典型使用场景

场景一：系统化学习开源项目

创建一个 CodeRef vault，通过 Git 子模块管理目标仓库，在 docs/ 目录记录学习笔记。AI 可以同时访问代码和笔记，提供更精准的分析。在学习某个模块时写的笔记，AI 后续分析相关代码时会自动参考——就像有个”助手”记住了之前的思考。

场景二：复用 Obsidian 笔记库

如果已经在用 Obsidian 管理笔记，直接把现有的 vault 注册到 HagiCode 中就行。AI 可以直接访问知识库，无需手动复制粘贴。这个功能特别实用，很多人都有积累多年的笔记库，接入之后 AI 就能”读”懂知识体系。

场景三：跨项目知识复用

多个 AI 提案可以引用同一个 vault，实现知识的跨项目复用。比如创建了一个”设计模式学习 vault”，里面记录了各种设计模式的笔记和代码示例。无论在分析哪个项目，AI 都能参考这个 vault 中的内容——知识不用重复积累。

路径安全机制

系统严格校验路径，防止路径穿越攻击：

private static string ResolveFilePath(string vaultRoot, string relativePath)
{
    var rootPath = EnsureTrailingSeparator(Path.GetFullPath(vaultRoot));
    var combinedPath = Path.GetFullPath(Path.Combine(rootPath, relativePath));
    if (!combinedPath.StartsWith(rootPath, StringComparison.OrdinalIgnoreCase))
    {
        throw new BusinessException(VaultRelativePathTraversalCode,
            "Vault file paths must stay inside the registered vault root.");
    }
    return combinedPath;
}

这确保了所有文件操作都在 vault 的根目录范围内，防止恶意路径访问。安全这块不能马虎，AI 助手要操作文件系统，必须把边界划清楚。

注意事项

使用 HagiCode Vault 系统时，有几点需要特别注意：

1. 路径安全：确保自定义路径在允许的范围内，否则系统会拒绝操作。这是为了防止误操作和潜在的安全风险。

2. Git 子模块管理：CodeRef vault 推荐使用 Git 子模块而非直接复制代码。好处前面说过——保持同步、节省空间。只是子模块有自己的使用方式，第一次使用可能需要熟悉一下。

3. 文件预览限制：系统限制文件大小（256KB）和数量（500个），超大文件需分批处理。这个限制是为了性能考虑，如果遇到超大文件，可以手动拆分或者用其他方式处理。

4. 诊断信息：创建 vault 会返回诊断信息，失败时可用于调试。遇到问题时先看诊断信息，大部分情况下都能找到线索。

总结

HagiCode 的 Vault 系统本质上是在解决一个简单但深刻的问题：如何让 AI 助手理解和使用本地知识资源。

通过统一的存储抽象层、标准化的目录结构、自动化的上下文注入，实现了”一次注册，处处复用”的知识管理方式。创建一个 vault 后，无论是学习笔记、代码仓库还是文档资料，AI 都能自动访问和理解。

这种设计带来的体验提升是明显的。不再需要手动复制代码片段、重复解释背景信息——AI 助手就像一个真正了解项目情况的同事，能够基于已有知识提供更有价值的帮助。

本文分享的 Vault 系统，正是开发 HagiCode 过程中实际踩坑、实际优化出来的方案。如果觉得这套设计有价值，说明工程实力还不错——那么 HagiCode 本身也值得关注一下。

参考资料

• HagiCode GitHub：github.com/HagiCode-org/site
• HagiCode 官网：hagicode.com
• 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
• Docker Compose 安装指南：docs.hagicode.com/installation/docker-compose
• Desktop 桌面端快速安装：hagicode.com/desktop/

如果本文对你有帮助：

• 来 GitHub 给个 Star：github.com/HagiCode-org/site
• 访问官网了解更多：hagicode.com
• 观看实战演示视频：www.bilibili.com/video/BV1pirZBuEzq/
• 一键安装体验：docs.hagicode.com/installation/docker-compose
• Desktop 桌面端快速安装：hagicode.com/desktop/

公测已开始，欢迎安装体验。

版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
• 原文链接: https://docs.hagicode.com/blog/2026-04-10-vault-system-ai-knowledge-base/
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

标签:

• HagiCode
• Vault
• AI
• 知识管理
• 系统设计

在 Web 界面直接编辑 DESIGN.md：从思路到实现