适合谁
- 希望为代码库建立可维护知识图谱的团队与个人开发者
- 使用编码 agent 并希望其获得稳定、可检索上下文的使用者
- 以 Markdown 为文档载体、希望文档与源码保持同步的项目
- 需要在离线环境下做语义检索（默认使用本地 WASM 嵌入模型）的场景
L
62FMRS · C
lat.md 是一个以 Markdown 编写、面向代码库的知识图谱工具，由 Vercel Labs 仓库发布（MIT 许可，npm 包名 lat.md）。它把领域知识拆成 lat.md/ 目录下互相链接的 Markdown 文件，用 [[wiki links]]、源码符号链接和 // @lat: 反向注释把文档与代码绑定，并靠 lat check 强制一致性。CLI 还提供 lat search 语义检索、lat expand 展开引用以及 lat mcp 启动 MCP 服务器供编辑器集成。语义检索默认完全离线（内置 all-MiniLM-L6-v2 的 WASM 版本），也支持通过 OpenAI 或 Vercel AI Gateway 密钥使用托管嵌入。README 未提供 MCP 服务器的清单、工具列表或客户端配置示例，因此本档案不含具体工具名与安装配置。总体适合使用编码 agent、且愿意以 Markdown 维护领域知识的团队；对不愿在源码中加注释或不需要 agent 的场景价值有限。
lat.md 是一个以 Markdown 编写、面向代码库的知识图谱工具。它在项目根目录创建 lat.md/ 目录，用互相链接的 Markdown 文件描述架构、业务逻辑与测试规格：小节之间用 [[wiki links]] 相连，文档可链接到源码符号（如 [[src/auth.ts#validateToken]]），源码则用 // @lat: [[section-id]] 注释（Python 为 # @lat: [[section-id]]）反向引用，并通过 lat check 保证引用与文档不漂移。其目标是解决单个 AGENTS.md 文件随代码库增长而难以维护的问题，让 agent 通过知识图谱而非反复 grep 来获取设计决策、约束与领域上下文。CLI 提供 lat init、lat check、lat locate、lat section、lat refs、lat search、lat expand 等命令；其中 lat mcp 用于启动 MCP 服务器以集成编辑器。语义检索默认离线运行，使用内置的 all-MiniLM-L6-v2 本地嵌入模型（编译为 WebAssembly，无需网络与原生二进制）；也可通过 OpenAI 或 Vercel AI Gateway 密钥切换到托管嵌入。
安装接入
- 全局安装：npm install -g lat.md
- 在要使用 lat 的仓库中运行 lat init，为常用编码 agent 配置钩子与指令。
- lat init 会生成 lat.md/ 目录，在其中编写描述架构、业务逻辑、测试规格的 Markdown 文件。
- 使用 [[file#Section#Subsection]] 在小节间互链，用 [[src/auth.ts#validateToken]] 链接源码符号。
- 在源码中添加 // @lat: [[section-id]] 注释（Python 用 # @lat: [[section-id]]）建立实现与概念的关联。
- 运行 lat check 校验图谱与文档一致性。
- 需要编辑器集成时运行 lat mcp 启动 MCP 服务器。
开发环境要求 Node.js 22、pnpm，以及通过 rustup 安装的 Rust；构建命令为 pnpm install、pnpm buildall、pnpm test。
选型与风险
不适合谁
- 只想维护单个扁平 AGENTS.md 文件的小型项目（知识图谱的收益有限）
- 不使用编码 agent、也不打算维护 Markdown 领域文档的团队
- 期望开箱即用托管服务或云端多人协同文档平台的用户
- 不愿在源码中添加 // @lat: 注释的项目
所需权限
- 对项目仓库的读写权限（lat init 会创建 lat.md/ 目录并配置编码 agent 的钩子与指令）
- 在配置托管嵌入时读取 API 密钥：LAT_LLM_KEY 环境变量、LAT_LLM_KEY_FILE 指定的文件，或执行 LAT_LLM_KEY_HELPER 指定的 shell 命令
- 写入本地索引/配置（lat reindex、lat config 涉及本地缓存与配置文件）
风险与副作用
- 若使用托管嵌入（OpenAI 或 Vercel AI Gateway）并配置密钥，相关文本可能被发送至外部服务；默认离线本地模型无网络请求
- LAT_LLM_KEY_HELPER 会执行 shell 命令以打印密钥，若该变量被不受信任的来源设置，存在命令执行风险
- 密钥文件若权限配置不当可能被其他本地进程读取
- 知识图谱若长期不运行 lat check 维护，可能与代码实际状态漂移，误导 agent
- lat init 会修改编码 agent 的钩子与指令配置，可能影响既有工作流
常见排障
- lat check 报错：表示存在引用不一致或缺少 // @lat: 反向引用的规格，按提示补齐链接或注释
- 语义检索结果不理想：尝试用 lat reindex 重建索引；如需更高质量可用 --remote 切换托管嵌入，或 --local 强制离线模型
- 找不到密钥：确认 LAT_LLM_KEY、LAT_LLM_KEY_FILE、LAT_LLM_KEY_HELPER 的解析顺序，或运行 lat config 查看配置文件位置
- 编译或运行失败：确认 Node.js 版本为 22，已安装 pnpm，且 Rust 通过 rustup 安装并具备对应 WASM 目标
- lat mcp 无法在编辑器中使用：确认命令已在项目根目录启动，且客户端配置指向该 MCP 服务器
- 无法定位小节：先用 lat locate 做精确或模糊查找，再用 lat section 查看该小节的链接与引用
使用场景
让 agent 通过知识图谱快速检索设计决策、约束与领域上下文，而不是反复 grep 代码库
在评审 diff 时先看 lat.md/ 中的语义变更，理解改了什么、为什么改
让 agent 在会话结束时把提示中的上下文与推理写入图谱，供后续会话复用
把测试用例写成 lat.md/ 中的小节并标记 require-code-mention: true，由 lat check 检查测试代码是否有 // @lat: 反向引用
构建 pre-commit 钩子、GitHub 机器人或 CI 任务在后台维护知识图谱
通过 lat search 做语义检索，通过 lat expand 在提示中展开 [[refs]]