面向企业级离线数仓「代码杂乱、无血缘目录约定」场景的轻量级字段血缘追溯方案。 一个 Agent 可加载的 Skill + 一个确定性的 CLI 工具（Python + SQLGlot），追溯某表某字段的血缘直至源端， 结果在本地 SQLite 结构化沉淀，支持快速复用与血缘漂移检测。
- 列级（字段级）血缘，后向追溯至「不可追为止」的源端边界，全程带证据（文件/行号/SQL 片段）；
- 单文件 SQLite 存储：追溯结果指纹缓存秒回；代码更新后自动发现漂移、重算并保留新旧 diff；
- 极轻量：运行时仅 1 个纯 Python 依赖（sqlglot），无服务器、无网络，可完全离线部署；
- 面向弱模型（如 DeepSeek V4 Flash 级别）设计：解析/追踪 100% 确定性代码，模型只做编排与判断，错误码驱动的机械恢复路径；
- 内置验收基准「脏仓库」examples/messy_repo，混乱风格（大小写混用、反引号、模板变量、CTE/UNION、跨文件多写）可回归。
# 1. 初始化本地库（SQLite 单文件）
python -m lineage_cli init --repo examples/messy_repo
# 2. 增量扫描 + 抽取列级血缘边
python -m lineage_cli scan --repo examples/messy_repo
python -m lineage_cli analyze --repo examples/messy_repo
# 3. 后向追溯某个字段（JSON 机读 / text 链路摘要）
python -m lineage_cli trace --repo examples/messy_repo --table dms.daily_report --column amount --format json完整安装（在线/离线）、命令详解与常见问题见 docs/使用手册.md； 架构与算法细节见 docs/架构设计.md； 设计背景与选型分析见 docs/需求方案.md。
lineage init --repo <path> [--db <path>] 初始化本地库
lineage scan --repo <path> [--full|--path P] 增量/定向扫描入库
lineage analyze [--repo <path>] 抽取列级血缘边入库
lineage list --tables|--columns [--like P] 列出已知表/列（补全与消歧）
lineage trace --table T --column C [--max-depth N] [--max-branches B]
[--format json|text] [--no-cache|--rescan] 后向追溯
lineage check --table T --column C 校验缓存是否仍有效
lineage diff --table T --column C 与最近一次追溯做漂移对比
lineage export --format jsonl [--out F] 导出全图/子图（占位，后续版本）
lineage clean [--stale] 清理失效缓存（占位，后续版本）
统一 JSON 协议（字段定义见 docs/schemas/ 下 JSON Schema）：成功 {"ok": true, "data": ...}（退出码 0）， 失败 {"ok": false, "error": {"code": "E_XXX", ...}}（退出码 1，E_ARGS 为 2）。
sql-lineage-skill/
├── docs/ # 需求方案、架构设计、使用手册
│ └── schemas/ # CLI 输出 JSON Schema（envelope/scan/analyze/trace/check/diff）
├── lineage_cli/ # Python 包（errors/config/naming/storage/scanner/extractor/tracer/cli）
├── skill/ # Agent 技能包（SKILL.md + references 决策树/错误码/CLI 手册）
├── tests/ # 可直接运行的回归测试（test_*.py）
├── examples/ # 演示用脏仓库 messy_repo（验收基准）
├── scripts/ # 依赖抓取与离线打包/安装脚本
├── .vendor_py/ # 预装 sqlglot（离线零安装依赖供应）
└── pyproject.toml # 打包配置（T5.3）
- SQLGlot：纯 Python SQL 解析/转译器， 提供多方言解析与 sqlglot.lineage 列级血缘 API，是本工具唯一的运行时依赖。