Lat.md：Agent Lattice：为你的代码库构建的知识图谱，使用 Markdown 编写

Source: Hacker News

一个用 Markdown 编写的代码库知识图谱。

问题

AGENTS.md 无法扩展。单个平面文件可以描述小项目，但随着代码库的增长，维护一个单体文档变得不切实际。关键设计决策被埋没，业务逻辑没有文档记录，代理会产生本该能够查找的上下文幻觉。

思路

将关于程序领域的知识压缩成 图谱 —— 一组相互连接的 Markdown 文件，放在项目根目录的 lat.md/ 目录下。章节之间使用 [[wiki 链接]] 互相链接，源文件使用 // @lat: 注释回指，lat check 确保没有内容不同步。

最终得到一个结构化的知识库，具备：

• 📈 可扩展 — 可以根据需要将知识拆分到任意数量的文件和章节
• 🔗 交叉引用 — wiki 链接（[[cli#search#Indexing]]）将概念连接成可导航的图谱
• ✅ 保持同步 — lat check 验证所有链接都能解析，且所需的代码引用存在
• 🔍 可搜索 — 在所有章节中进行精确、模糊和语义（向量）搜索
• 🤝 适用于人和机器 — 在任何编辑器（或 Obsidian）中可读，代理可通过 lat CLI 查询

安装

npm install -g lat.md

然后在想要使用 lat 的仓库中运行 lat init。

工作原理

运行 lat init 来创建 lat.md/ 目录，然后编写描述架构、业务逻辑、测试规范等的 Markdown 文件——任何重要的内容。使用 [[file#Section#Subsection]] 语法在章节之间建立链接。使用 [[src/auth.ts#validateToken]] 链接到源代码符号。通过在源代码中添加 // @lat: [[section-id]]（Python 中为 # @lat: [[section-id]]）注释，将实现与概念关联起来。

my-project/
├── lat.md/
│   ├── architecture.md    # 系统设计，关键决策
│   ├── auth.md            # 认证与授权逻辑
│   └── tests.md           # 测试规范（require-code-mention: true）
├── src/
│   ├── auth.ts            # // @lat: [[auth#OAuth Flow]]
│   └── server.ts          # // @lat: [[architecture#Request Pipeline]]
└── ...

CLI

lat init                        # 脚手架生成 lat.md/ 目录
lat check                       # 验证所有 wiki 链接和代码引用
lat locate "OAuth Flow"         # 按名称查找章节（精确、模糊）
lat section "auth#OAuth Flow"   # 显示章节及其链接和引用
lat refs "auth#OAuth Flow"      # 查找引用该章节的内容
lat search "how do we auth?"    # 通过嵌入进行语义搜索
lat expand "fix [[OAuth Flow]]" # 在提示中展开 [[refs]] 供代理使用
lat mcp                         # 启动 MCP 服务器以供编辑器集成

配置

语义搜索（lat search）需要 OpenAI（sk-...）或 Vercel AI Gateway（vck_...）的 API 密钥。密钥的解析顺序如下：

1. LAT_LLM_KEY 环境变量 — 直接的值
2. LAT_LLM_KEY_FILE 环境变量 — 包含密钥的文件路径
3. LAT_LLM_KEY_HELPER 环境变量 — 输出密钥的 shell 命令（10 秒超时）
4. 配置文件 — 由 lat init 保存。运行 lat config 查看其位置。

开发

需要 Node.js 22+ 和 pnpm。

pnpm install
pnpm build
pnpm test