跳转至

Init

init 是初始化项目工作区的轻量方式。它读取项目里的 SQL 脚本、文档和数据库，写下一份简洁的项目说明：该用哪些表、表之间怎么关联、有哪些规则必须遵守。这样后续会话一开始就带着写 SQL 所需的上下文，而不必构建较重的向量知识库。

在 REPL 中使用 /init 命令运行。

功能作用

  • 用 upsert_lineage 工具把项目里的 SQL（ETL 脚本和 Python DAG 中的 SQL）静态分析成持久化的表级血缘图，再用 query_lineage 读取。关联条件、过滤条件、映射、窗口及作者注释从 SQL 原文读取。不执行任何 SQL。
  • 阅读项目中人写的文档（业务规则、指标定义、数据字典）。
  • 用几十条只读小查询核对这些发现：哪个版本的表存在且在更新、表的粒度、关联的基数、编码的实际取值。
  • 在项目根目录写一份 AGENTS.md：数据架构、核心表、跨业务域的规则，以及知识索引。
  • 每个业务域写一个 knowledge/<domain>.md：表卡片（用途、粒度、时间、编码、必带过滤）、关联关系、血缘、指标定义、业务规则，以及已知问题（例如文档和数据库对不上的地方）。

它属于轻量层级：不建向量索引、无确认门。一百个左右脚本的项目需要几分钟。需要向量索引的知识库时，请使用 /build-kb。

血缘图保存在 lineage/lineage.json，整个项目共用一个文件。每个被分析的文件（或保存下来的一段 SQL）是一个来源：upsert_lineage 只重新分析内容、方言、默认库或解析器版本有变化的来源，并整份替换这个来源之前贡献的内容，所以 SQL 里删掉的语句，对应的血缘也会消失。方言和默认库作为项目设置保存在文件里，之后的调用不传这两个参数时，仍按同样的设置分析。prune_missing=True 会同时清理源文件已删除的来源，delete_lineage 可以按来源 ID 或 glob 删除。文件分四部分：settings（方言和默认库）、sources（内容 hash、方言、默认库、解析问题）、nodes（表、视图，以及代表纯查询的 query:<hash> 节点，label 取自作者注释）和 edges（上游 → 下游，每条边带着产生它的语句：来源、行号、加载方式和折叠的临时表；不读任何表的写入没有上游）。来源 ID 相对于项目根目录。文件里只有从 SQL 推导出的内容，没有时间戳或计数器，可以提交到版本库；如果合并后文件无法解析，可以用 upsert_lineage(paths=[...], rebuild=True) 从 SQL 文件重建。

query_lineage 返回指定表周围的子图（不传表则返回整张表级图）：每条语句一条记录，出处格式为 文件ID:行号，并给出每张表的角色、所属连通子图，以及有多少条已保存的查询读取它。complete=false 表示可能涉及所查表的来源（包括没有被任何返回语句引用的来源）在分析后有改动、是按其他设置分析的，或有语句没能解析。

在 normal 权限模式下，upsert_lineage 和 delete_lineage 写 lineage/lineage.json 前会先询问；auto 模式下 upsert_lineage 直接执行，delete_lineage 仍会询问。

不兼容的变化： extract_sql_lineage 由 upsert_lineage、delete_lineage 和 query_lineage 取代。血缘工具不再返回关联关系：init 从 SQL 原文读取关联条件，并到数据库核实基数。参数条件不证明增量加载，单独的 ROW_NUMBER 定义也不证明表粒度。

何时使用

  • 新项目工作区还没有 AGENTS.md。
  • 你明确想要初始化或重新扫描项目。
  • 脚本、文档或表结构有较大变化，项目说明已过时。

当一份最新的 AGENTS.md 已存在且没有实质变化时，可以跳过它。

如何使用

/init

你可以在命令后附加自由文本提示——一个目标、一个范围，或要重点关注的文件 / 表：

/init focus on the sales and finance schemas

不带提示时，init 覆盖整个项目和当前数据源；带提示时，只更新 AGENTS.md 和 knowledge 文件中范围内的部分。

Init 与 Build KB 的区别

init /build-kb
速度 数分钟 更长
产出 AGENTS.md + knowledge/*.md 向量知识库：语义模型、指标、参考 SQL
确认 无 生成清单确认门
向量索引 否 是
时机 最先、总是先做 init 之后，当你需要语义检索时

典型流程：先运行 /init 获得即时上下文，需要向量索引知识库时再运行 /build-kb。

注意事项

  • knowledge 以 markdown 文件存放在 knowledge/ 下，由 AGENTS.md 索引；每个会话只加载 AGENTS.md 的前 200 行，所以细节放在 knowledge 文件里。
  • 文档、SQL、数据库三者不一致时，init 会把冲突记在对应业务域的"已知问题"里，而不是悄悄选一边。
  • init 只执行只读查询（SELECT / SHOW / EXPLAIN）。
  • 生成语义模型、指标和参考 SQL 是 /build-kb 的职责。