跳转至

TTD 统一手册

欢迎来到 TTD 统一手册 👋

本手册是什么

TTD 是一套企业级 NL2SQL + Agentic BI 端到端系统。
本手册将分散在仓库各处的架构设计、开发规范、运维指南统一为 单一可信来源（Single Source of Truth），覆盖从语义治理到前端交互的完整链路。

项目一句话

用户用自然语言提问 → 系统通过三层语义治理 + R/V/G 三引擎检索 → AI Agent 编排生成可信 SQL → 安全执行并返回图表与洞察。

五大子项目

# 子项目 路径 简述
1 Semantic Plane semantic-plane/ 三层治理元数据资产：表/指标 → 术语关系 → 业务规则与上下文
2 Data Plane data-plane/ 本地数据执行环境（PostgreSQL + AGE + pgvector + pg_mooncake + MinIO）
3 Backend backend/ AI Agent 编排服务（FastAPI + LangGraph Supervisor + Sub-agents + 多模型 + 元数据发布管道）
4 Web web/ 对话式分析前端（Next.js 16 + React 19 + Zustand + shadcn/ui）

角色阅读路径

  1. 项目概览 — 建立整体认知
  2. 系统架构 — 理解在线/离线两条链路
  3. 按负责子系统深入：Backend / Web / Data Plane
  4. 开发与协作流程 — 分支策略、CI/CD、PR 规范
  5. 关键设计决策 — 了解"为什么这样做"
  1. 项目概览 — 理解三层治理模型
  2. Semantic Plane — 资产类型与 Schema 规范
  3. 语义层开发者维护手册 — 日常编写、校验、发布
  4. H&M 测试数据集 — 示例数据与约束
  5. 质量评估体系 — LLM-as-a-Judge + 回归基线
  1. 项目概览 → 系统架构
  2. Data Plane — 本地数据执行环境
  3. 运行与安全 — 可观测性、安全策略、回滚方案
  4. 仓库地图 — 快速定位文件与模块

本地预览

# 使用 uv 一键启动 MkDocs 开发服务器
uvx --with mkdocs-material mkdocs serve

快速验证

启动后访问 http://127.0.0.1:8000，支持热更新——保存 Markdown 后浏览器自动刷新。

文档治理说明

范畴 策略
当前维护入口 本 handbook（docs/handbook/）
历史文档 docs/talk-to-data-*.md 保留供考古，已从 nav 排除
构建排除 mkdocs.yml 的 exclude_docs 已忽略旧文件
贡献方式 修改 docs/ 下 Markdown → PR → 自动部署