开发与协作流程¶

适用对象

本文档面向 Backend Developer、Data Product Owner、Data Steward 和前端开发者，提供从环境搭建到 CI/CD 的完整开发指引。

1. 环境准备 (Environment Setup)¶

1.1 Prerequisites¶

开始开发前，请确保本地已安装以下工具：

工具	最低版本	用途	安装方式
Python	3.12+	Backend + Data Plane	推荐通过 `uv` 管理
Node.js / Bun	Node 20+ / Bun 1.x	Web Frontend	bun.sh
Docker	24+	本地服务容器化	docker.com
Docker Compose	v2+	多容器编排	Docker Desktop 自带
uv	0.4+	Python 依赖管理与虚拟环境	`curl -LsSf https://astral.sh/uv/install.sh \\| sh`
Task	3.x	任务运行器 (替代 Makefile)	taskfile.dev
pg_mooncake	-	本地列存查询引擎	使用官方 Docker 镜像

pg_mooncake 镜像

pg_mooncake 使用官方 Docker 镜像，无需本地构建：

docker pull mooncakelabs/pg_mooncake:latest

1.2 初始化步骤¶

# 1. Clone 仓库并安装依赖
git clone https://github.com/zhiweio/the-ttd.git
cd the-ttd
uv sync                    # Python 依赖 (root workspace + backend + data-plane)
task web:install           # 前端依赖 (bun install)

# 2. 配置环境变量
cp .env.example .env       # 编辑 .env，填入必要的 API Key

1.3 关键环境变量说明¶

必填变量清单

变量	说明	示例
`TTD_DASHSCOPE_API_KEY`	阿里云 DashScope API Key（Qwen 系列模型）	`sk-xxxx`
`TTD_ANTHROPIC_API_KEY`	Anthropic API Key（Claude 模型，可选）	`sk-ant-xxxx`
`TTD_JWT_SECRET`	JWT 签名密钥（生产环境必须修改）	32+ 字符随机串
`TTD_AURORA_DSN`	PostgreSQL 连接串 (Supernode)	`postgresql://postgres:postgres@localhost:5435/ttd_db`
`TTD_PG_MOONCAKE_DSN`	pg_mooncake 连接串 (Data Plane)	`postgresql://postgres:postgres@localhost:5436/ttd_lake`

其余变量均有合理默认值，参见 .env.example。

1.4 验证安装¶

# 验证 uv 和 Python
uv run python --version    # 应输出 Python 3.12+

# 验证 Task
task --version             # 应输出 Task version 3.x

# 验证 Docker
docker compose version     # 应输出 Docker Compose version v2.x

2. 全栈本地启动 (Full Stack Local Startup)¶

启动顺序很重要

各服务间存在依赖关系，请严格按照以下顺序启动。

2.1 启动流程¶

graph LR
    A[Data Plane] --> B[Publish Metadata]
    B --> C[Load Test Data]
    C --> D[Backend]
    D --> E[Web Frontend]

Step 1: 启动 Data Plane 基础设施¶

task dp:up

启动 PostgreSQL (Aurora 替代) + pg_mooncake + MinIO 三个容器。

验证方式查看容器状态

task dp:psql
# 若成功连接 psql shell，输入 \q 退出

task dp:ps

Step 2: 发布语义元数据¶

task dp:publish-sp

将 semantic-plane/ 下的 YAML 资产发布到 S3，Backend 自动检测变更后执行 R/V/G pipeline 写入 PostgreSQL。

验证方式

task dp:psql

SELECT count(*) FROM semlayer.table_asset;
-- 应返回 > 0
SELECT count(*) FROM semlayer.metric_asset;
-- 应返回 > 0

Step 3: 加载 H&M 测试数据¶

task dp:load-hm

将 H&M 数据集 CSV 加载到 pg_mooncake（模拟 Redshift 查询层）。

验证方式

task dp:psql:mooncake

SELECT count(*) FROM gold_hm.fact_transaction;
-- 应返回 > 0 (约 3.1 万条)

Step 4: 启动 Backend¶

task be:dev

启动 FastAPI 开发服务器，监听 0.0.0.0:8000，支持 auto-reload。

验证方式

curl -s http://localhost:8000/api/v1/health | python -m json.tool

预期输出：

{
    "status": "healthy",
    "version": "...",
    "uptime_seconds": ...
}

Step 5: 启动 Web Frontend¶

task web:dev

启动 Next.js 开发服务器 (Turbopack)，监听 localhost:3000。

验证方式

浏览器打开 http://localhost:3000，应看到聊天界面。

2.2 一键启动 (快捷方式)¶

# 启动所有后台服务（data-plane + backend + web Docker 容器）
task up

# 停止所有服务
task down

Note

task up 启动 data-plane 容器和 deploy 应用容器（backend + web），仍需手动执行 task dp:publish-sp 发布元数据。

2.3 高可用模式 (Docker Swarm HA)¶

用于本地模拟生产高可用部署：

# 一键启动：data-plane + Swarm HA stack (3× agent-runtime + HAProxy + 2× web)
task ha:up

# 一键关闭并清理 Swarm
task ha:down

互斥模式

本地开发 (task up) 和 Swarm HA (task ha:up) 是互斥的。切换前需先执行对应的 down 命令。

3. 元数据修改工作流 (Metadata Modification Workflow)¶

元数据（Semantic Plane）是系统的核心知识库。修改需遵循严格的治理流程。

3.1 标准流程¶

graph TD
    A[创建 Feature Branch] --> B[编辑 YAML 文件]
    B --> C[运行校验 sp:validate]
    C --> D{校验通过?}
    D -->|否| B
    D -->|是| E[递增 version 字段]
    E --> F[本地 Publish 验证]
    F --> G[端到端测试]
    G --> H[提交 PR]
    H --> I[CI 自动校验]
    I --> J[Code Review]
    J --> K[Merge → 发布到 S3 → Backend 自动同步]

3.2 详细步骤¶

① 创建 Feature Branch

git checkout -b feat/sp-add-gmv-metric

② 编辑 YAML 文件

在 semantic-plane/ 下对应目录编辑。Copilot 会自动加载对应的 .instructions.md 模板。

# 示例：添加新指标
vim semantic-plane/domains/sales/metrics/met_sales_gmv.yaml

③ 运行校验

task sp:validate

包含三项检查：

validate:yaml — JSON Schema 校验
validate:sql — SQL 语法校验（指标定义中的 SQL）
validate:refs — 跨层引用完整性（Layer 1→2→3）

④ 递增 version

根据变更类型递增版本号：

变更类型	版本变化	示例
typo / reviewed_at 更新	PATCH	`1.0.0` → `1.0.1`
描述更新、新增同义词	MINOR	`1.0.1` → `1.1.0`
SQL 逻辑 / rule_expression 变更	MAJOR	`1.1.0` → `2.0.0`

# 检查 version bump 是否合规
task sp:check:version

⑤ 本地发布验证

task dp:publish-sp

⑥ 端到端测试

启动 Backend 后，通过 API 或 Web 界面提问一个依赖该资产的问题，确认回答正确。

⑦ 提交 PR

git add semantic-plane/
git commit -m "feat(sp): add GMV metric definition"
git push origin feat/sp-add-gmv-metric

3.3 CI 自动校验内容¶

PR 创建后，GitHub Actions 会自动执行：

MAJOR 变更审批

涉及指标逻辑、rule_expression、bound_assets 等 MAJOR 变更，需要 Governance Lead 审批。Layer 3 MAJOR 变更还需 Domain SME 审批。

4. 后端开发流程 (Backend Development Workflow)¶

4.1 日常开发循环¶

# 启动开发服务器（auto-reload on save）
task be:dev

# 运行测试
task be:test

# 代码检查
task be:lint
task be:typecheck

4.2 代码结构导航¶

backend/app/
├── agents/       # LangGraph Supervisor + Sub-agents
├── api/          # FastAPI 路由端点
├── audit/        # 审计日志
├── memory/       # 四层记忆系统 (working/profile/episodic/correction + cache)
├── models/       # 多模型注册表
├── prompt/       # Prompt 管理
├── security/     # 安全模块 (JWT, Guard, Policy)
├── session/      # 会话管理
├── skills/       # MCP 工具/技能
├── config.py     # Settings (Pydantic)
├── errors.py     # 异常层次结构
└── main.py       # 应用入口

4.3 Database Migration (Alembic)¶

# 创建新 migration
task be:db:revision MESSAGE="add user preferences table"

# 执行 migration
task be:db:migrate

# 回滚上一个 migration
task be:db:rollback

# 查看当前版本
task be:db:current

# 查看历史
task be:db:history

4.4 API 契约变更¶

当 Backend API 签名发生变化时：

修改 FastAPI 端点
启动 Backend，确认 OpenAPI spec 已更新
在 Web 项目中重新生成 API Client：

task web:generate:api

4.5 添加新 Sub-Agent¶

参考 .github/instructions/backend-agents.instructions.md 中的模板，核心步骤：

在 backend/app/agents/sub_agents/ 创建新模块
定义 Agent 状态、系统 Prompt、工具绑定
在 Supervisor 中注册路由
编写测试用例

4.6 添加新 Skill (MCP Tool)¶

参考 .github/instructions/backend-skills.instructions.md，在 backend/app/skills/ 下创建新工具模块。

5. 前端开发流程 (Frontend Development Workflow)¶

5.1 日常开发¶

# 启动开发服务器 (Turbopack hot reload)
task web:dev

# 代码检查
task web:check

# 格式化
task web:format

# 类型检查
task web:typecheck

5.2 API Client 重新生成¶

后端 API 变更后，需要重新生成 TypeScript 客户端：

task web:generate:api

该命令会从 Backend 的 OpenAPI spec 自动生成类型安全的 API Client。

5.3 Production Build 验证¶

task web:build

Tip

建议在提交 PR 前运行 task web:build，确保生产构建无报错。

5.4 代码规范¶

Linter / Formatter: Biome (替代 ESLint + Prettier)
Type Check: TypeScript strict mode
Runtime: Bun (替代 npm/yarn)

6. CI/CD 流程 (CI/CD Pipeline)¶

6.1 本地全量 CI¶

task ci

等价于：

task lint       # be:lint + web:check + sp:validate
task typecheck  # be:typecheck + web:typecheck
task test       # be:test

6.2 GitHub Actions Pipeline¶

graph LR
    A[Push / PR] --> B[Validate YAML]
    B --> C[Check Version Bump]
    C --> D[Backend Lint + TypeCheck]
    D --> E[Backend Tests]
    E --> F[Frontend Check + TypeCheck]
    F --> G{Merge to main?}
    G -->|是| H[Publish to S3]
    H --> I[Backend Auto-Sync: R+V+G]

6.3 各阶段说明¶

阶段	命令	说明
YAML 校验	`task sp:validate`	JSON Schema + SQL + 跨层引用
Version 检查	`task sp:check:version`	确保已修改的 YAML 有 version bump
Backend Lint	`task be:lint`	Ruff linter
Backend TypeCheck	`task be:typecheck`	ty type checker
Backend Test	`task be:test`	pytest
Frontend Check	`task web:check`	Biome lint + format
Frontend TypeCheck	`task web:typecheck`	tsc --noEmit
Build Changeset	`task sp:changeset`	生成增量 changeset
Full Changeset	`task sp:changeset:full`	全量 changeset（灾备恢复用）

6.4 Merge 后自动发布¶

PR 合并到 main 后：

ttd-publish-sp 将 semantic-plane YAML 发布到 S3
Admin Backend 检测 S3 manifest 变更，自动触发 semantic_plane agent
Agent 执行完整 R/V/G pipeline（关系 upsert + 图谱同步 + Embedding 生成）
S3 快照中缺失的资产被标记 deleted_at（软删除）

7. 代码质量工具 (Code Quality Tools)¶

7.1 Python (Backend + Data Plane)¶

工具	用途	配置位置	命令
Ruff	Linting + Formatting	`pyproject.toml`	`task be:lint` / `task be:format`
ty	Type Checking	-	`task be:typecheck`
pytest	单元测试/集成测试	`backend/tests/`	`task be:test`
pytest-asyncio	异步测试支持	-	自动检测 async fixtures
DeepEval	LLM 评估框架	-	评估 SQL 质量与回答相关性
Ragas	RAG 评估	-	评估检索质量

7.2 TypeScript / JavaScript (Web)¶

工具	用途	配置位置	命令
Biome	Linting + Formatting	`web/biome.json`	`task web:check` / `task web:format`
TypeScript	Type Checking	`web/tsconfig.json`	`task web:typecheck`

7.3 Metadata (Semantic Plane)¶

工具	用途	命令
`validate_all_yaml.py`	JSON Schema 校验	`task sp:validate:yaml`
`validate_sql_definitions.py`	SQL 语法校验	`task sp:validate:sql`
`validate_cross_layer_refs.py`	跨层引用校验	`task sp:validate:refs`
`check_version_bump.py`	版本递增检查	`task sp:check:version`
`analyze_metadata_diff.py`	变更影响分析	`task sp:diff`

8. 常用 Task 命令速查 (Task Commands Quick Reference)¶

8.1 Root 命令¶

命令	说明
`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 镜像 (data-plane + backend + web)
`task ci`	完整 CI 流程 (lint + typecheck + test)

8.2 Backend (`be:*`)¶

命令	说明
`task be:dev`	启动开发服务器 (auto-reload)
`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`	执行数据库迁移
`task be:db:rollback`	回滚上一次迁移
`task be:db:revision`	创建新 migration
`task be:db:current`	查看当前 migration 版本
`task be:db:history`	查看 migration 历史
`task be:build:docker`	构建 Backend Docker 镜像
`task be:ci`	Backend 完整 CI (lint + typecheck + test)

8.3 Data Plane (`dp:*`)¶

命令	说明
`task dp:up`	启动 Data Plane 容器 (PG + 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`	查看容器日志 (tail)
`task dp:ps`	查看容器运行状态
`task dp:publish-sp`	发布 semantic-plane YAML 到 S3
`task dp:load-hm`	加载 H&M 测试数据 (CSV → pg_mooncake)
`task dp:psql`	连接 Aurora 替代 (port 5435)
`task dp:psql:mooncake`	连接 pg_mooncake (port 5436)

8.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`	检查 version bump
`task sp:diff`	分析 metadata 变更
`task sp:changeset`	构建增量 changeset
`task sp:changeset:full`	构建全量 changeset

8.5 Web Frontend (`web:*`)¶

命令	说明
`task web:dev`	Next.js 开发服务器 (Turbopack)
`task web:build`	生产构建
`task web:start`	启动生产服务器
`task web:install`	安装 npm 依赖 (bun)
`task web:check`	Biome lint + format 检查
`task web:format`	Biome 格式化
`task web:typecheck`	TypeScript 类型检查
`task web:generate:api`	从 OpenAPI 生成 API Client
`task web:db:migrate`	运行 better-auth 数据库迁移
`task web:build:docker`	构建 Web Docker 镜像
`task web:ci`	Frontend 完整 CI (check + typecheck)

8.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 到 Swarm (HAProxy + agent-runtime + 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 + 清理网络)

9. 发布前检查清单 (Pre-Release Checklist)¶

# 1. 语义层校验
task sp:validate

# 2. Backend CI
task be:ci

# 3. Frontend CI
task web:ci

# 4. 文档构建
uvx --with mkdocs-material mkdocs build --strict

# 5. 全量 CI (综合)
task ci

10. 文档维护原则¶

新的架构/设计说明优先写入 docs/handbook/，不再增加平行的"大而全"文档
子项目 README 仅保留短入口，详细内容统一指向 Handbook
若调整系统边界或路由策略，必须同步更新：
- handbook/system-architecture.md
- handbook/backend.md
- handbook/design-decisions.md

本地预览文档：

uvx --with mkdocs-material mkdocs serve
# 浏览器打开 http://localhost:8001

11. 常见问题 (FAQ)¶

Docker 容器启动失败

检查端口占用：

lsof -i :5435  # Aurora 替代
lsof -i :5436  # pg_mooncake
lsof -i :9000  # MinIO

确保无其他进程占用这些端口。

dp:publish-sp 报错

确认 Data Plane 容器已启动：task dp:ps（MinIO 需要运行）
确认 S3 配置正确（MinIO endpoint 和 bucket）
检查 semantic-plane/ YAML 文件是否通过校验：task sp:validate

Backend 启动报 DB 连接失败

确认 Data Plane 容器已启动：task dp:ps
确认 .env 中 TTD_AURORA_DSN 指向正确端口 (5435)
重启容器：task dp:down && task dp:up

Web 端 API 请求 404

确认 Backend 正在运行：curl http://localhost:8000/api/v1/health
确认环境变量中 API base URL 配置正确
重新生成 API Client：task web:generate:api

开发与协作流程¶

1. 环境准备 (Environment Setup)¶

1.1 Prerequisites¶

1.2 初始化步骤¶

1.3 关键环境变量说明¶

1.4 验证安装¶

2. 全栈本地启动 (Full Stack Local Startup)¶

2.1 启动流程¶

Step 1: 启动 Data Plane 基础设施¶

Step 2: 发布语义元数据¶

Step 3: 加载 H&M 测试数据¶

Step 4: 启动 Backend¶

Step 5: 启动 Web Frontend¶

2.2 一键启动 (快捷方式)¶

2.3 高可用模式 (Docker Swarm HA)¶

3. 元数据修改工作流 (Metadata Modification Workflow)¶

3.1 标准流程¶

3.2 详细步骤¶

3.3 CI 自动校验内容¶

4. 后端开发流程 (Backend Development Workflow)¶

4.1 日常开发循环¶

4.2 代码结构导航¶

4.3 Database Migration (Alembic)¶

4.4 API 契约变更¶

4.5 添加新 Sub-Agent¶

4.6 添加新 Skill (MCP Tool)¶

5. 前端开发流程 (Frontend Development Workflow)¶

5.1 日常开发¶

5.2 API Client 重新生成¶

5.3 Production Build 验证¶

5.4 代码规范¶

6. CI/CD 流程 (CI/CD Pipeline)¶

6.1 本地全量 CI¶

6.2 GitHub Actions Pipeline¶

6.3 各阶段说明¶

6.4 Merge 后自动发布¶

7. 代码质量工具 (Code Quality Tools)¶

7.1 Python (Backend + Data Plane)¶

7.2 TypeScript / JavaScript (Web)¶

7.3 Metadata (Semantic Plane)¶

8. 常用 Task 命令速查 (Task Commands Quick Reference)¶

8.1 Root 命令¶

8.2 Backend (be:*)¶

8.3 Data Plane (dp:*)¶

8.4 Semantic Plane (sp:*)¶

8.5 Web Frontend (web:*)¶

8.6 Deploy (deploy:*)¶

9. 发布前检查清单 (Pre-Release Checklist)¶

10. 文档维护原则¶

11. 常见问题 (FAQ)¶

8.2 Backend (`be:*`)¶

8.3 Data Plane (`dp:*`)¶

8.4 Semantic Plane (`sp:*`)¶

8.5 Web Frontend (`web:*`)¶

8.6 Deploy (`deploy:*`)¶