仓库地图¶

快速导航

本页是 TTD 项目的完整结构参考。新成员建议从阅读顺序开始。

1. 仓库全景¶

the-ttd/
├── .github/                        # Copilot instructions + CI workflows
│   ├── copilot-instructions.md     # 根 Copilot 指令
│   ├── instructions/               # 按路径自动加载的子指令 (21 个)
│   │   ├── table-asset.instructions.md
│   │   ├── metric-asset.instructions.md
│   │   ├── business-terms.instructions.md
│   │   ├── few-shot.instructions.md
│   │   ├── join-rules.instructions.md
│   │   ├── term-relationships.instructions.md
│   │   ├── business-rules.instructions.md
│   │   ├── business-contexts.instructions.md
│   │   ├── backend-architecture.instructions.md
│   │   ├── backend-agents.instructions.md
│   │   ├── backend-api.instructions.md
│   │   ├── backend-skills.instructions.md
│   │   ├── backend-security.instructions.md
│   │   ├── backend-testing.instructions.md
│   │   ├── backend-memory.instructions.md
│   │   ├── backend-models-prompt.instructions.md
│   │   ├── backend-common-errors.instructions.md
│   │   ├── copilot-tips.instructions.md
│   │   ├── review-checklist.instructions.md
│   │   ├── common-errors.instructions.md
│   │   └── tui-client.instructions.md
│   └── workflows/
│       └── metadata-validation.yml
├── backend/                        # FastAPI + LangGraph Agentic BI 后端
│   ├── app/
│   │   ├── agents/                 # LangGraph Supervisor + Sub-agents
│   │   │   ├── builder.py          # 图拓扑定义
│   │   │   ├── supervisor.py       # Supervisor 节点
│   │   │   ├── state.py            # AgenticBIState 定义
│   │   │   ├── embedding.py        # Embedding agent
│   │   │   ├── sub_agents/         # 全部子 agent
│   │   │   │   ├── router.py       # 路由矩阵
│   │   │   │   ├── query_understanding.py
│   │   │   │   ├── data_retrieval.py
│   │   │   │   ├── sql_generation.py
│   │   │   │   ├── guardrails.py   # SQL 三层校验
│   │   │   │   ├── planner.py
│   │   │   │   ├── analytical.py
│   │   │   │   ├── visualization.py
│   │   │   │   ├── insights.py
│   │   │   │   ├── sql_explainer.py
│   │   │   │   ├── knowledge_qa.py
│   │   │   │   ├── followup.py
│   │   │   │   ├── suggest_followup.py
│   │   │   │   ├── schema_explorer.py
│   │   │   │   └── evaluators/     # 质量评估节点
│   │   │   │       ├── retrieval_evaluator.py
│   │   │   │       ├── sql_evaluator.py
│   │   │   │       └── answer_evaluator.py
│   │   │   └── semantic_plane/     # 元数据 Agent（YAML → DB）
│   │   ├── api/                    # FastAPI 端点
│   │   │   ├── router.py           # 路由汇总
│   │   │   ├── chats.py            # 对话 API
│   │   │   ├── feedback.py         # 用户反馈
│   │   │   └── admin/              # 管理面板 API
│   │   │       ├── evaluation.py   # 评估任务
│   │   │       └── feedbacks.py    # 反馈管理
│   │   ├── audit/                  # 结构化审计日志
│   │   ├── db/                     # SQLAlchemy models + engine
│   │   ├── memory/                 # 四层记忆系统 (MemoryFacade + Formation)
│   │   │   ├── facade.py           # MemoryFacade — 统一检索/写入/抑制/删除
│   │   │   ├── formation.py        # 记忆形成服务 (post-turn extraction)
│   │   │   ├── sql_cache.py        # SQL 缓存 (共享优化层)
│   │   │   └── long_term.py        # Legacy 兼容适配器 (向 MemoryFacade 迁移中)
│   │   ├── models/                 # 多模型注册表
│   │   │   └── registry.py         # ModelRegistry
│   │   ├── prompt/                 # Prompt 管理
│   │   ├── repositories/           # Data Access Layer
│   │   │   ├── chat_repo.py
│   │   │   ├── admin_repo.py
│   │   │   └── evaluation_repo.py
│   │   ├── security/               # 认证 + Guards + Policy
│   │   │   └── auth.py             # Better Auth JWKS 验签 + UserContext + require_admin
│   │   ├── services/               # 业务逻辑层
│   │   ├── session/                # 会话管理
│   │   ├── skills/                 # RAG、SQL 执行、ML 工具
│   │   │   ├── rag.py              # RAGRetriever
│   │   │   ├── reranker.py         # 重排序
│   │   │   ├── sql_executor.py     # DataPlaneExecutor
│   │   │   ├── graph_rag.py        # Apache AGE 图检索
│   │   │   ├── corrective_retrieval.py
│   │   │   └── metadata_cache.py   # 元数据缓存
│   │   ├── tools/                  # ML toolkit + interpreter
│   │   ├── config.py               # 应用配置
│   │   ├── deps.py                 # FastAPI 依赖注入
│   │   ├── errors.py               # 统一错误处理
│   │   ├── main.py                 # 应用入口 + lifespan
│   │   └── schemas.py              # Pydantic schemas
│   ├── alembic/                    # Database migrations
│   │   └── versions/               # Migration scripts
│   ├── tests/                      # 后端测试
│   │   ├── test_evaluators.py      # Evaluator 单元测试
│   │   └── test_admin_evaluation.py
│   ├── docker-compose.yml          # 后端容器编排
│   ├── Dockerfile
│   ├── Taskfile.yml
│   └── pyproject.toml              # ttd-backend 包配置
├── data-plane/                     # 本地数据执行环境
│   ├── docker/                     # 自定义 Docker 镜像
│   │   ├── postgres/               # Apache AGE + pgvector
│   │   └── pg-mooncake/             # pg_mooncake 初始化 SQL
│   ├── scripts/                    # 数据操作脚本
│   │   ├── publish_semantic_plane.py # YAML → S3 发布
│   │   └── load_hm_data.py          # H&M CSV → pg_mooncake
│   ├── sql/                        # DDL schemas
│   │   ├── 001_create_schema.sql     # 核心 schema (semlayer + ttd)
│   │   └── 100_hm_create_schema.sql  # H&M 数据表 (gold_hm)
│   ├── docker-compose.yml          # PostgreSQL + pg_mooncake + MinIO
│   ├── Taskfile.yml
│   └── pyproject.toml              # ttd-data-plane 包配置
├── deploy/                         # 部署编排（本地 + Swarm HA）
│   ├── docker-compose.yml          # 本地开发应用服务 (backend + web)
│   ├── swarm/                      # Swarm 高可用部署
│   │   ├── docker-compose.swarm.yml # Swarm stack (HAProxy + agent-runtime + web)
│   │   └── haproxy.cfg             # 一致性哈希路由 (by chat_id)
│   └── Taskfile.yml                # deploy:命名空间任务
├── docs/                           # MkDocs 文档源
│   ├── handbook/                   # TTD Handbook
│   │   ├── overview.md
│   │   ├── system-architecture.md
│   │   ├── design-decisions.md
│   │   ├── hm-dataset.md
│   │   ├── semantic-plane.md
│   │   ├── semantic-maintainer-manual.md
│   │   ├── data-plane.md
│   │   ├── backend.md
│   │   ├── web.md
│   │   ├── lambda-infra.md
│   │   ├── development-workflow.md
│   │   ├── operations.md
│   │   ├── quality-evaluation.md
│   │   ├── repository-map.md       # ← 本文件
│   │   └── legacy-mapping.md
│   └── index.md
├── scripts/                        # CI 校验与工具脚本
│   ├── validate_all_yaml.py        # JSON Schema 校验
│   ├── validate_sql_definitions.py # SQL 语法校验 (sqlparse)
│   ├── validate_cross_layer_refs.py # 跨层引用完整性
│   ├── check_version_bump.py       # SemVer 递增检查
│   ├── analyze_metadata_diff.py    # 元数据 diff 分析
│   ├── build_changeset.py          # 增量发布事件
│   └── build_full_changeset.py     # 全量发布事件
├── semantic-plane/                 # 三层治理元数据资产
│   ├── schemas/                    # JSON Schema 验证器 (8 个)
│   │   ├── table_asset.schema.json
│   │   ├── metric_asset.schema.json
│   │   ├── join_rule.schema.json
│   │   ├── business_term.schema.json
│   │   ├── few_shot_example.schema.json
│   │   ├── term_relationship.schema.json
│   │   ├── business_rule.schema.json
│   │   └── business_context.schema.json
│   ├── domains/                    # Layer 1: 表 + 指标资产
│   │   └── hm_fashion/            # H&M 域
│   │       ├── dim_article.yaml
│   │       ├── dim_customer.yaml
│   │       ├── fact_transaction.yaml
│   │       └── metrics/           # 指标定义
│   ├── terms/                      # Layer 1+2: 业务术语
│   ├── few_shots/                  # Layer 1: NL2SQL 示例对
│   ├── join_rules/                 # Layer 1: 表间关联规则
│   ├── business_rules/             # Layer 3: 业务规则
│   ├── business_contexts/          # Layer 3: 业务上下文
│   ├── term_relationships/         # Layer 2: 术语关系网络
│   └── Taskfile.yml
├── web/                            # Next.js 前端
│   ├── app/                        # Pages & routes (App Router)
│   │   ├── api/auth/[...all]/      # Better Auth API handler
│   │   ├── (auth)/                 # Auth pages (login, signup)
│   │   └── (chat)/                 # Chat + Admin (auth-protected)
│   ├── components/                 # React UI 组件
│   ├── hooks/                      # Custom React hooks
│   ├── lib/                        # API client + utilities
│   │   ├── auth.ts                 # Better Auth 服务端配置
│   │   ├── auth-client.ts          # Better Auth 客户端 SDK
│   │   └── api/client-config.ts    # API client + JWT 注入
│   ├── stores/                     # Zustand 状态管理
│   ├── package.json
│   ├── biome.json                  # Lint + format (Biome)
│   ├── openapi-ts.config.ts        # OpenAPI 代码生成配置
│   ├── Taskfile.yml
│   └── next.config.ts
├── .env.example                    # 环境变量模板
├── mkdocs.yml                      # MkDocs Material 配置
├── pyproject.toml                  # uv workspace 根配置
├── Taskfile.yml                    # 根 Taskfile（聚合命名空间）
├── uv.lock                         # uv 锁文件
└── README.md

2. Task 命名空间¶

项目使用 Task 做多子项目任务编排，根 Taskfile.yml 通过 includes 聚合各命名空间：

2.1 命名空间总览¶

命名空间	子项目	目录	说明
`be:*`	Backend	`backend/`	FastAPI 后端服务
`dp:*`	Data Plane	`data-plane/`	本地数据面基础设施
`deploy:*`	Deploy	`deploy/`	部署编排（本地 + Swarm HA）
`sp:*`	Semantic Plane	`semantic-plane/`	元数据治理与校验
`web:*`	Web Frontend	`web/`	Next.js 前端

2.2 Backend (`be:*`)¶

命令	功能
`task be:dev`	启动 debug 模式
`task be:lint`	Ruff 检查
`task be:lint:fix`	Ruff 自动修复
`task be:format`	Ruff 格式化
`task be:typecheck`	ty 类型检查
`task be:test`	Pytest 运行
`task be:test:cov`	带覆盖率测试
`task be:db:migrate`	Alembic migrate
`task be:db:rollback`	Alembic rollback
`task be:db:revision`	创建 migration
`task be:build:docker`	构建 Backend Docker 镜像
`task web:build:docker`	构建 Web Docker 镜像
`task up`	启动所有服务 (data-plane + backend + web)
`task down`	停止所有服务

2.3 Data Plane (`dp:*`)¶

命令	功能
`task dp:up`	启动 PostgreSQL + pg_mooncake + MinIO
`task dp:up:obs`	启动 Data Plane + Observability (AutoMQ)
`task dp:down`	停止所有 data-plane 服务
`task dp:down:obs`	停止 Data Plane + Observability
`task dp:build:docker`	构建 Data Plane 自定义镜像 (age-pgvector)
`task dp:logs`	查看服务日志
`task dp:ps`	查看运行容器
`task dp:publish-sp`	发布 semantic-plane YAML 到 S3
`task dp:load-hm`	加载 H&M 数据 (CSV → pg_mooncake)
`task dp:psql`	连接 Aurora 替代实例 (5435)
`task dp:psql:mooncake`	连接 pg_mooncake (5436)

2.4 Semantic Plane (`sp:*`)¶

命令	功能
`task sp:validate`	运行全部校验（yaml + sql + refs）
`task sp:validate:yaml`	JSON Schema 合规性
`task sp:validate:sql`	SQL 语法可解析
`task sp:validate:refs`	跨层引用完整性
`task sp:check:version`	SemVer 版本递增
`task sp:diff`	元数据 diff 分析
`task sp:changeset`	构建增量 changeset
`task sp:changeset:full`	构建全量 changeset

2.5 Web Frontend (`web:*`)¶

命令	功能
`task web:dev`	Next.js Turbopack 开发服务器
`task web:build`	生产构建
`task web:install`	bun install
`task web:check`	Biome lint + format 检查
`task web:format`	Biome 格式化
`task web:typecheck`	TypeScript 类型检查
`task web:generate:api`	从 OpenAPI spec 生成 API client
`task web:build:docker`	构建 Web Docker 镜像

2.6 Deploy (`deploy:*`)¶

命令	功能
`task deploy:up`	启动本地应用容器 (backend + web on bridge ttd-net)
`task deploy:down`	停止本地应用容器
`task deploy:swarm:init`	初始化 Docker Swarm (首次)
`task deploy:swarm:deploy`	部署 HA Stack (HAProxy + 3× agent-runtime + 2× web)
`task deploy:swarm:scale`	扩缩容 agent-runtime (`N=5 task deploy:swarm:scale`)
`task deploy:swarm:update`	滚动更新 agent-runtime 镜像
`task deploy:swarm:status`	查看 Swarm 服务状态
`task deploy:swarm:logs`	Tail agent-runtime 日志
`task deploy:swarm:rm`	移除 TTD Stack
`task deploy:swarm:teardown`	完整拆除 (rm stack + leave swarm + 清理网络)

2.7 根级聚合命令¶

命令	功能
`task setup`	安装全部依赖 (uv + bun)
`task lint`	全量 lint (be + web + sp)
`task format`	全量格式化 (be + web)
`task test`	全量测试
`task typecheck`	全量类型检查 (be + web)
`task up`	启动全部本地服务 (data-plane + backend + web)
`task down`	停止全部本地服务
`task ha:up`	Swarm HA 部署 (data-plane + HAProxy + 3× agent-runtime + 2× web)
`task ha:down`	拆除 Swarm 并停止 data-plane
`task build:docker`	构建所有 Docker 镜像
`task ci`	CI 流水线 (lint + typecheck + test)

3. 关键文件速查¶

3.1 Backend 核心文件¶

文件	用途
`app/main.py`	应用入口、lifespan hook、依赖初始化
`app/config.py`	应用配置（环境变量映射）
`app/deps.py`	FastAPI 依赖注入
`app/schemas.py`	全局 Pydantic request/response schemas
`app/errors.py`	统一错误处理与 compact SQL
`app/api/router.py`	API 路由汇总
`app/agents/builder.py`	LangGraph 图拓扑定义
`app/agents/state.py`	`AgenticBIState` TypedDict
`app/agents/supervisor.py`	Supervisor 节点逻辑
`app/agents/sub_agents/router.py`	路由矩阵与快路径策略
`app/agents/sub_agents/guardrails.py`	SQL 三层校验 (syntax + safety + business)
`app/skills/rag.py`	RAGRetriever (pgvector 检索)
`app/skills/sql_executor.py`	DataPlaneExecutor (pg_mooncake 执行)
`app/skills/graph_rag.py`	Apache AGE 图推理
`app/memory/sql_cache.py`	SQL Cache (相似查询复用，共享优化层)
`app/memory/facade.py`	MemoryFacade — 统一记忆检索、写入、抑制、删除
`app/memory/formation.py`	MemoryFormationService — post-turn 记忆提取
`app/memory/long_term.py`	Legacy 兼容适配器 (向 MemoryFacade 迁移中)
`app/security/auth.py`	认证上下文 + ABAC
`app/models/registry.py`	多模型注册表 (LLM + Embedding + Reranker)
`app/db/models.py`	SQLAlchemy ORM 模型

3.2 Semantic Plane 核心文件¶

文件	用途
`schemas/*.schema.json`	8 个 JSON Schema 验证器（勿手动修改）
`domains/hm_fashion/*.yaml`	H&M 表资产定义
`domains/hm_fashion/metrics/*.yaml`	H&M 指标资产
`terms/hm_fashion_terms.yaml`	H&M 域业务术语
`few_shots/hm_fashion_examples.yaml`	NL2SQL 示例对
`join_rules/hm_fashion_joins.yaml`	表间关联规则
`business_rules/hm_fashion_rules.yaml`	Layer 3 业务规则
`business_contexts/hm_fashion_contexts.yaml`	Layer 3 上下文
`term_relationships/hm_fashion_rels.yaml`	术语关系网络

3.3 Data Plane 核心文件¶

文件	用途
`docker-compose.yml`	PostgreSQL + pg_mooncake + MinIO 编排
`docker/postgres/`	Apache AGE + pgvector 自定义镜像
`docker/pg-mooncake/`	pg_mooncake 初始化
`scripts/publish_semantic_plane.py`	YAML → S3 发布
`scripts/load_hm_data.py`	H&M CSV → pg_mooncake
`sql/001_create_schema.sql`	核心 schema DDL
`sql/100_hm_create_schema.sql`	H&M 数据表 DDL (gold_hm)

3.4 CI/CD 核心文件¶

文件	用途
`scripts/validate_all_yaml.py`	Schema 合规校验
`scripts/validate_sql_definitions.py`	SQL 文本校验
`scripts/validate_cross_layer_refs.py`	跨层引用完整性
`scripts/check_version_bump.py`	版本递增合规
`scripts/build_changeset.py`	增量发布事件构建
`scripts/build_full_changeset.py`	全量发布事件
`scripts/analyze_metadata_diff.py`	元数据 diff 分析
`.github/workflows/metadata-validation.yml`	CI 流水线定义

3.5 Web 前端核心文件¶

文件	用途
`app/`	Next.js App Router 页面
`components/`	React UI 组件库
`hooks/`	Custom hooks (useChat, useStream 等)
`lib/`	API client + 工具函数
`stores/`	Zustand 全局状态
`biome.json`	Biome lint/format 配置
`openapi-ts.config.ts`	OpenAPI TypeScript 代码生成

4. 技术栈总结¶

层级	技术	版本要求
包管理	uv (Python) + bun (JS)	uv ≥ 0.4
任务运行	Task (Taskfile)	v3
后端框架	FastAPI + Uvicorn	Python 3.12+
Agent 编排	LangGraph	≥ 0.2
数据库 ORM	SQLAlchemy 2.0	async
数据库迁移	Alembic	auto-generate
向量检索	pgvector	PostgreSQL 扩展
图数据库	Apache AGE	PostgreSQL 扩展
数据湖	pg_mooncake + columnstore	MinIO S3 存储
前端框架	Next.js (App Router)	14+
前端状态	Zustand
前端 Lint	Biome
文档	MkDocs Material
IaC	Docker Swarm

5. 新成员阅读顺序¶

推荐路径

按以下顺序阅读 Handbook，可在最短时间建立全局认知。

5.1 通用路径（所有角色）¶

步骤	文档	目标
1	仓库地图（本页）	了解项目结构与命名空间
2	项目概览	理解产品定位与核心价值
3	系统架构	掌握整体技术架构
4	设计决策	理解关键技术选型 why
5	H&M 数据集	熟悉测试数据与业务约束

5.2 按角色深入¶

Backend 开发前端开发语义治理 (DPO / Data Steward)DevOps / Infra

6. 常用开发流程速查¶

6.1 首次环境搭建¶

# 1. 安装全部依赖
task setup

# 2. 启动数据面
task dp:up

# 3. 发布语义元数据到 S3
task dp:publish-sp

# 4. 加载 H&M 测试数据
task dp:load-hm

# 5. 启动后端
task be:dev

# 6. 启动前端 (另一终端)
task web:dev

6.2 日常开发循环¶

# Backend 修改后
task be:lint:fix && task be:test

# 前端修改后
task web:check && task web:typecheck

# 元数据修改后
task sp:validate

6.3 提交前检查¶

# 全量 CI 模拟
task ci

仓库地图¶

1. 仓库全景¶

2. Task 命名空间¶

2.1 命名空间总览¶

2.2 Backend (be:*)¶

2.3 Data Plane (dp:*)¶

2.4 Semantic Plane (sp:*)¶

2.5 Web Frontend (web:*)¶

2.6 Deploy (deploy:*)¶

2.7 根级聚合命令¶

3. 关键文件速查¶

3.1 Backend 核心文件¶

3.2 Semantic Plane 核心文件¶

3.3 Data Plane 核心文件¶

3.4 CI/CD 核心文件¶

3.5 Web 前端核心文件¶

4. 技术栈总结¶

5. 新成员阅读顺序¶

5.1 通用路径（所有角色）¶

5.2 按角色深入¶

6. 常用开发流程速查¶

6.1 首次环境搭建¶

6.2 日常开发循环¶

6.3 提交前检查¶

2.2 Backend (`be:*`)¶

2.3 Data Plane (`dp:*`)¶

2.4 Semantic Plane (`sp:*`)¶

2.5 Web Frontend (`web:*`)¶

2.6 Deploy (`deploy:*`)¶