Tối ưu hóa việc học từ dự án trong kỷ nguyên AI với hệ thống Vault

Tối ưu hóa việc học từ dự án trong kỷ nguyên AI với hệ thống Vault

Trong kỷ nguyên phát triển phần mềm được hỗ trợ bởi AI, làm thế nào để giúp các trợ lý AI hiểu rõ hơn về tài nguyên học tập của chúng ta? Dự án HagiCode đã triển khai một lớp trừu tượng lưu trữ kiến thức thống nhất và dễ hiểu cho AI thông qua hệ thống Vault, giúp cải thiện đáng kể hiệu quả học tập khi nghiên cứu các dự án mã nguồn.

Bối cảnh: Thay đổi trong cách học lập trình

Trong kỷ nguyên AI, cách các nhà phát triển tiếp cận với công nghệ và kiến trúc mới đang thay đổi sâu sắc. Phương pháp "học từ dự án" — nghiên cứu sâu mã nguồn, kiến trúc và các mẫu thiết kế từ các dự án mã nguồn mở xuất sắc — đã trở thành một cách học hiệu quả. So với việc đọc sách hay xem video truyền thống, việc đọc và chạy trực tiếp các dự án mã nguồn mở chất lượng cao giúp bạn hiểu rõ thực tế kỹ thuật nhanh hơn nhiều.

Tuy nhiên, phương pháp học này cũng đối mặt với nhiều thách thức lớn.

Tài liệu học tập quá phân tán. Ghi chú của bạn có thể nằm trên Obsidian, các kho chứa mã (repository) rải rác ở nhiều thư mục khác nhau, trong khi lịch sử trò chuyện với trợ lý AI lại là một "hòn đảo dữ liệu" biệt lập khác. Khi bạn muốn AI giúp phân tích một dự án, bạn phải sao chép thủ công các đoạn mã và sắp xếp ngữ cảnh — một quy trình khá tẻ nhạt.

Điều rắc rối hơn nữa là sự phân mảnh ngữ cảnh (context fragmentation). Các trợ lý AI không thể truy cập trực tiếp vào tài nguyên học tập cục bộ của bạn, do đó bạn phải cung cấp thông tin nền tảng mới cho mỗi cuộc trò chuyện. Hơn nữa, các kho mã bạn đang nghiên cứu cập nhật rất nhanh, đồng bộ hóa thủ công dễ gây lỗi và khó chia sẻ kiến thức giữa nhiều dự án học tập khác nhau.

Vấn đề cốt lõi ở đây là do "kho chứa dữ liệu biệt lập" (data silos). Nếu có một lớp trừu tượng lưu trữ thống nhất mà AI có thể hiểu và truy cập tất cả tài nguyên học tập, những vấn đề này sẽ được giải quyết triệt để.

Giới thiệu về HagiCode

Hệ thống Vault được chia sẻ trong bài viết này là một giải pháp được phát triển trong quá trình xây dựng HagiCode — một dự án trợ lý mã AI. Trong quá trình phát triển hàng ngày, nhóm thường cần học hỏi và tham khảo từ các dự án mã nguồn mở khác nhau. Để giúp các trợ lý AI hiểu rõ hơn về những tài nguyên học tập này, họ đã thiết kế hệ thống lưu trữ liên tục Vault.

Giải pháp này đã được kiểm chứng trong thực tế tại HagiCode. Nếu bạn đang gặp các thách thức tương tự trong quản lý tri thức, hy vọng những kinh nghiệm này sẽ mang lại một số cảm hứng.

Triết lý thiết kế của hệ thống Vault

Ý tưởng cốt lõi của Vault rất đơn giản: tạo ra một lớp trừu tượng lưu trữ kiến thức thống nhất, dễ hiểu cho AI. Về mặt triển khai, hệ thống có một số tính năng chính.

Hỗ trợ đa dạng kiểu Vault

Hệ thống hỗ trợ bốn loại vault, tương ứng với các trường hợp sử dụng khác nhau:

• folder: Loại thư mục chung.
• coderef: Loại dành riêng cho việc nghiên cứu dự án mã nguồn.
• obsidian: Tích hợp với phần mềm ghi chú Obsidian.
• system-managed: Vault được quản lý tự động bởi hệ thống.

Trong đó, loại coderef được sử dụng nhiều nhất trong HagiCode. Nó được thiết kế riêng để nghiên cứu mã nguồn, cung cấp cấu trúc thư mục chuẩn hóa và siêu dữ liệu mô tả mà AI có thể đọc được.

Cơ chế lưu trữ liên tục (Persistent Storage)

Sổ đăng ký vault được lưu trữ liên tục dưới định dạng JSON, đảm bảo cấu hình vẫn còn đó sau khi ứng dụng khởi động lại.

public class VaultRegistryStore : IVaultRegistryStore
{
    private readonly string _registryFilePath;

    public VaultRegistryStore(IConfiguration configuration, ILogger<VaultRegistryStore> logger)
    {
        var dataDir = configuration["DataDir"] ?? "./data";
        var absoluteDataDir = Path.IsPathRooted(dataDir)
            ? dataDir
            : Path.GetFullPath(Path.Combine(Directory.GetCurrentDirectory(), dataDir));

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

Lợi ích của thiết kế này là sự đơn giản và độ tin cậy. Định dạng JSON dễ đọc cho con người, thuận lợi cho việc gỡ lỗi và sửa đổi thủ công; lưu trữ trên hệ thống tệp giúp tránh sự phức tạp của cơ sở dữ liệu, giảm thiểu sự phụ thuộc của hệ thống. Đôi khi, giản đơn là tốt nhất.

Tích hợp ngữ cảnh AI

Quan trọng nhất, hệ thống có thể tự động chèn thông tin vault vào ngữ cảnh đề xuất của 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');

  if (readOnlyVaults.length === 0 && editableVaults.length === 0) {
    return '';
  }

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

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

Điều này đạt được một tính năng quan trọng: các trợ lý AI có thể tự động hiểu các tài nguyên học tập có sẵn mà người dùng không cần cung cấp ngữ cảnh thủ công.

Cấu trúc chuẩn hóa của CodeRef Vault

Đối với các vault loại coderef, HagiCode cung cấp cấu trúc thư mục chuẩn hóa:

my-coderef-vault/
├── index.yaml          # Mô tả siêu dữ liệu của vault
├── AGENTS.md           # Hướng dẫn hoạt động cho trợ lý AI
├── docs/               # Lưu trữ ghi chú và tài liệu học tập
└── repos/              # Quản lý các kho mã đã nghiên cứu qua Git submodules

Khi tạo một vault, hệ thống sẽ tự động khởi tạo cấu trúc này:

private async Task EnsureCodeRefStructureAsync(
    string vaultName,
    string physicalPath,
    ICollection<VaultBootstrapDiagnosticDto> diagnostics,
    CancellationToken cancellationToken)
{
    Directory.CreateDirectory(physicalPath);

    var indexPath = Path.Combine(physicalPath, CodeRefIndexFileName);
    var docsPath = Path.Combine(physicalPath, CodeRefDocsDirectoryName);
    var reposPath = Path.Combine(physicalPath, CodeRefReposDirectoryName);

    // Tạo cấu trúc thư mục chuẩn
    if (!Directory.Exists(docsPath))
    {
        Directory.CreateDirectory(docsPath);
    }

    if (!Directory.Exists(reposPath))
    {
        Directory.CreateDirectory(reposPath);
    }

    // Tạo hướng dẫn AGENTS.md
    await EnsureCodeRefAgentsDocumentAsync(physicalPath, cancellationToken);

    // Tạo siêu dữ liệu index.yaml
    await WriteCodeRefIndexDocumentAsync(indexPath, mergedDocument, cancellationToken);
}

Thiết kế cấu trúc này có ý định cụ thể:

• Thư mục docs/ lưu trữ ghi chú học tập của bạn, có thể ghi lại sự hiểu mã, phân tích kiến trúc, các lỗi và kinh nghiệm dưới dạng Markdown.
• Thư mục repos/ quản lý các kho lưu trữ đã nghiên cứu thông qua Git submodules thay vì sao chép mã trực tiếp. Điều này giúp giữ cho mã được đồng bộ hóa đồng thời tiết kiệm không gian.
• index.yaml chứa siêu dữ liệu vault, giúp trợ lý AI nhanh chóng hiểu mục đích và nội dung của vault.
• AGENTS.md là hướng dẫn được viết riêng cho trợ lý AI, giải thích cách xử lý nội dung trong vault này.

Khởi tạo tự động bởi hệ thống

Ngoài việc tạo vault thủ công, HagiCode cũng hỗ trợ các vault được quản lý tự động bởi hệ thống:

public async Task<IReadOnlyList<VaultRegistryEntry>> EnsureAllSystemManagedVaultsAsync(
    CancellationToken cancellationToken = default)
{
    var definitions = GetAllResolvedDefinitions();
    var entries = new List<VaultRegistryEntry>(definitions.Count);

    foreach (var definition in definitions)
    {
        entries.Add(await EnsureResolvedSystemManagedVaultAsync(definition, cancellationToken));
    }

    return entries;
}

Hệ thống tự động tạo và quản lý các vault sau:

• hagiprojectdata: Lưu trữ dữ liệu dự án để lưu cấu hình và trạng thái dự án.
• personaldata: Lưu trữ dữ liệu cá nhân để lưu tùy chọn của người dùng.
• hbsprompt: Thư viện mẫu Prompt để quản lý các lệnh AI thường dùng.

Các vault này được khởi tạo tự động khi hệ thống khởi động mà không cần cấu hình thủ công từ người dùng.

Cơ chế kiểm soát quyền truy cập

Một thiết kế quan trọng là kiểm soát quyền truy cập. Hệ thống chia vault thành hai loại quyền truy cập:

export interface VaultForText {
  id: string;
  name: string;
  type: string;
  physicalPath: string;
  accessType: 'read' | 'write';  // Khóa: phân biệt chỉ đọc và có thể chỉnh sửa
}

• reference (chỉ đọc): AI chỉ sử dụng để phân tích và hiểu, không thể sửa đổi nội dung. Phù hợp cho tham chiếu các dự án mã nguồn mở, tài liệu, v.v.
• editable (có thể chỉnh sửa): AI có thể sửa đổi nội dung theo nhu cầu cho các tác vụ. Phù hợp cho ghi chú, bản nháp của bạn.

Sự phân biệt này rất quan trọng. Nó giúp AI biết nội dung nào là "tham khảo chỉ đọc" và nội dung nào "có thể được sửa đổi", tránh rủi ro thao tác nhầm.

Thực hành: Tạo và sử dụng Vault

Sau khi đã tìm hiểu nguyên lý, hãy cùng nhìn vào cách sử dụng thực tế.

Tạo một CodeRef Vault

Dưới đây là ví dụ gọi frontend hoàn chỉnh:

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"
    }
  });

  // Hệ thống sẽ tự động:
  // 1. Clone kho React vào vault/repos/react
  // 2. Tạo thư mục docs/ để ghi chú
  // 3. Tạo siêu dữ liệu index.yaml
  // 4. Tạo tệp hướng dẫn AGENTS.md

  return response;
};

Lệnh gọi API này hoàn thành một loạt thao tác: tạo cấu trúc thư mục, khởi tạo Git submodules, tạo tệp siêu dữ liệu, v.v. Bạn chỉ cần cung cấp thông tin cơ bản, hệ thống sẽ xử lý phần còn lại.

Sử dụng Vault trong các đề xuất AI

Khi vault đã được tạo, bạn có thể tham chiếu nó trong các đề xuất AI:

const proposal = composeProposalChiefComplaint({
  chiefComplaint: "Help me analyze React's concurrent rendering mechanism",
  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 chỉ có thể đọc, không sửa đổi
    }
  ],
  quickRequestText: "Focus on fiber architecture and scheduler implementation"
});

Hệ thống tự động chèn thông tin vault vào ngữ cảnh của AI, để AI biết bạn có những tài nguyên học tập nào.

Các phương pháp tốt nhất và lưu ý

Trong quá trình sử dụng hệ thống Vault, đã có vài bài học kinh nghiệm được đúc kết.

An toàn đường dẫn (Path Safety)

Hệ thống kiểm tra nghiêm ngặt các đường dẫn để ngăn chặn các cuộc tấn công duyệt đường dẫn (path traversal):

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;
}

Điều này rất quan trọng. Nếu bạn tùy chỉnh đường dẫn vault, hãy đảm bảo đường dẫn nằm trong phạm vi cho phép, nếu không hệ thống sẽ từ chối thao tác.

Quản lý Git Submodule

Các vault CodeRef khuyến nghị sử dụng Git submodules thay vì sao chép mã trực tiếp. Cách tiếp cận này có several lợi ích: giữ cho mã đồng bộ với thượng nguồn (upstream), tiết kiệm dung lượng đĩa và tạo điều kiện thuận lợi cho việc quản lý nhiều phiên bản mã.

Giới hạn xem trước tệp

Để ngăn ngừa các vấn đề về hiệu suất, hệ thống giới hạn kích thước và loại tệp. Nếu vault của bạn chứa số lượng tệp lớn hoặc các tệp rất lớn, hiệu suất chức năng xem trước có thể bị ảnh hưởng.

Tóm tắt

Hệ thống Vault giải quyết các nỗi đau cốt lõi của việc học dự án trong kỷ nguyên AI thông qua một lớp trừu tượng lưu trữ thống nhất:

• Quản lý tri thức tập trung: Tất cả tài nguyên học tập được tập trung ở một nơi, không còn phân tán.
• Tự động chèn ngữ cảnh AI: Các trợ lý AI có thể tự động hiểu tài nguyên học tập có sẵn mà không cần cung cấp ngữ cảnh thủ công.
• Tái sử dụng tri thức liên dự án: Nhiều dự án học tập có thể chia sẻ và tái sử dụng kiến thức.
• Cấu trúc thư mục chuẩn hóa: Cung cấp cấu trúc thư mục nhất quán, giảm chi phí học tập.

Giải pháp này đã được kiểm chứng trong thực tế tại dự án HagiCode. Nếu bạn cũng đang làm việc trên các công cụ phát triển được hỗ trợ bởi AI hoặc gặp các thách thức quản lý tri thức tương tự, hy vọng những kinh nghiệm này sẽ cung cấp một số tham khảo hữu ích.