第 13 章 开发与协作流程

本章学习目标 - 掌握 TTD 的环境搭建与五步启动流程 - 理解 CI/CD 管道与代码质量工具链 - 掌握 Task 命令体系（唯一权威表） - 理解元数据修改工作流与离线发布管道

前置知识：第 9 章 Semantic Plane、第 10 章 Data Plane 关联代码：Taskfile.yml、.github/workflows/、scripts/、.pre-commit-config.yaml

本章定位

本章是 Task 命令与 CI 校验脚本的唯一权威表。其他章节引用此处。

---

13.1 环境搭建

13.1.1 前置依赖

工具	用途	安装
uv	Python 包管理（workspace）	curl -LsSf https://astral.sh/uv/install.sh \| sh
bun / npm	前端包管理	bun.sh
Docker	数据面容器	docker.com
Task	任务编排	taskfile.dev

13.1.2 环境变量

复制 .env.example 为 .env，填写关键变量（完整参考见 附录 B）：

cp .env.example .env
# 必填：TTD_DASHSCOPE_API_KEY
# 开发：TTD_DATA_PLANE_BACKEND=pg_mooncake, TTD_DEBUG=true

---

13.2 五步启动

执行以下命令，依次启动数据面、发布语义资产、加载数据、启动后端与前端：

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#e8f0fe','primaryTextColor':'#202124','primaryBorderColor':'#1a73e8','lineColor':'#5f6368','secondaryColor':'#e0f2f1','tertiaryColor':'#f8f9fa'}}}%%
flowchart LR
    S1["1. dp:up<br/>启动数据面<br/>PG + pg_mooncake + MinIO"] --> S2["2. publish-sp<br/>发布语义资产<br/>YAML → S3"]
    S2 --> S3["3. load-hm<br/>加载 H&M 数据<br/>CSV → 列存镜像"]
    S3 --> S4["4. be:dev<br/>启动后端<br/>FastAPI · debug 模式"]
    S4 --> S5["5. web:dev<br/>启动前端<br/>Next.js 16 · Turbopack"]

    classDef bpProcess  fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px,color:#202124
    class S1,S2,S3,S4,S5 bpProcess

# 1. 启动数据面（PG Supernode + pg_mooncake + MinIO）
task dp:up

# 2. 发布语义资产到 S3（触发 Backend 自动同步）
task dp:publish-sp

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

# 4. 启动后端（debug 模式，免 JWT）
task be:dev

# 5. 启动前端
task web:dev

启动后：

• 前端：http://localhost:3000
• 后端 API：http://localhost:8000/api/v1
• 后端 Docs：http://localhost:8000/docs
• Metrics：http://localhost:8000/metrics

---

13.3 Task 命令体系

Task 命令是 TTD 的统一操作入口，分 6 个命名空间。本章是唯一权威表：

13.3.1 数据面（dp）

命令	说明
task dp:up	启动数据面容器
task dp:down	停止数据面
task dp:publish-sp	发布语义资产到 S3
task dp:load-hm	加载 H&M 数据
task dp:psql	进入 PG Supernode psql

13.3.2 语义面（sp）

命令	说明
task sp:validate	本地校验所有 YAML 资产
task sp:build-changeset	构建增量 changeset

13.3.3 后端（be）

命令	说明
task be:dev	启动开发服务器（debug）
task be:lint / be:lint:fix	ruff 检查 / 自动修复
task be:format	格式化
task be:typecheck	类型检查（ty）
task be:test / be:test:cov	pytest / 含覆盖率
task be:db:migrate	Alembic 迁移
task be:db:rollback	回滚最近迁移
task be:db:current	查看迁移版本
task be:ci	完整 CI 检查
task be:build:docker	构建 Docker 镜像

13.3.4 前端（web）

命令	说明
task web:dev	启动开发服务器
task web:build	构建
task web:lint	Biome 检查
task web:test	测试

13.3.5 部署（deploy）

命令	说明
task up	启动所有服务（data-plane + backend + web）
task down	停止所有服务
task ha:up	启动 Swarm HA 模式
task ha:down	停止 Swarm
task deploy:swarm:scale	扩缩容（N=5）
task deploy:swarm:update	滚动更新
task deploy:swarm:status	查看实例状态
task deploy:swarm:logs	查看日志

13.3.6 根级

命令	说明
task docs:serve	本地预览文档
task docs:build	构建文档

---

13.4 CI/CD 管道

13.4.1 GitHub Actions

Workflow	触发	作用
metadata-validation.yml	语义资产 PR	运行 4 个校验脚本 + pre-commit hooks
docs.yml	docs/ 变更	构建 MkDocs 站点

13.4.2 CI 校验脚本

脚本	作用	失败处理
scripts/validate_all_yaml.py	JSON Schema 校验所有 YAML	阻断 PR
scripts/validate_sql_definitions.py	metric SQL 语法验证（sqlglot 解析）	阻断 PR
scripts/validate_cross_layer_refs.py	跨层引用完整性	阻断 PR
scripts/check_version_bump.py	版本号递增检查	强制 bump
scripts/build_changeset.py	增量 changeset（git diff）	—
scripts/analyze_metadata_diff.py	变更影响分析	—

13.4.3 代码质量工具

工具	语言	用途
ruff	Python	linter + formatter
ty	Python	类型检查
pytest	Python	单元测试
Biome	TypeScript	linter + formatter
DeepEval	Python	LLM 评估（详见 第 15 章）
Ragas	Python	RAG 评估
pre-commit	多语言	提交前钩子（ruff + ty + YAML 校验）

---

13.5 元数据修改工作流

这是语义资产从编辑到生效的完整工作流（与 第 9 章发布管道 呼应），全程通过 Git 版本控制 + CI/CD 自动化：

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#e8f0fe','primaryTextColor':'#202124','primaryBorderColor':'#1a73e8','lineColor':'#5f6368','secondaryColor':'#e0f2f1','tertiaryColor':'#f8f9fa'}}}%%
flowchart LR
    EDIT["编辑 semantic-plane/<br/>YAML 资产"] --> HOOK["pre-commit hooks<br/>本地快速校验"]
    HOOK --> COMMIT["git commit + push<br/>创建 PR"]
    COMMIT --> CI["GitHub Actions CI<br/>4 个校验脚本"]
    CI --> REVIEW["PR Review<br/>Governance Lead 审批"]
    REVIEW --> MERGE["合并到 main"]
    MERGE --> PUB["自动发布到 S3<br/>语义资产快照"]
    PUB --> SYNC["Backend 检测变更<br/>自动同步 R+V+G 索引"]

    classDef bpProcess  fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px,color:#202124
    classDef bpDecision fill:#fef7e0,stroke:#f9ab00,stroke-width:2px,color:#202124
    classDef bpSuccess  fill:#e6f4ea,stroke:#1e8e3e,stroke-width:2px,color:#202124

    class EDIT,HOOK,COMMIT bpProcess
    class CI,REVIEW bpDecision
    class MERGE,PUB,SYNC bpSuccess

13.5.1 增量 vs 全量 changeset

• 增量（build_changeset.py）：基于 git diff，只发布变更资产
• 全量（build_full_changeset.py）：首次发布或 MAJOR 变更时全量发布

13.5.2 Backend 自动同步

Backend 后台服务（semantic_sync.py）定时轮询 S3 manifest hash，检测变更后自动执行 R/V/G pipeline 同步索引（详见 第 9 章）。开发者合并 PR 后无需任何手动操作，系统自动完成索引更新。

---

13.6 离线发布管道

语义资产的端到端发布管道由以下环节组成（详见 第 9 章 完整说明）：

1. 业务开发在 semantic-plane/ 编辑 YAML
2. pre-commit hooks 本地快速校验
3. GitHub Actions CI 运行 4 个校验脚本
4. PR Review（MAJOR 变更需 Governance Lead 审批）
5. 合并后自动发布到 S3
6. Backend 后台轮询 S3 manifest hash，检测变更后自动执行 R/V/G pipeline
7. 索引同步到 Engine R（关系表）/ Engine G（AGE 图）/ Engine V（pgvector）

Semantic datasource 是全局单例——系统范围内仅一个活跃语义数据源。

---

13.7 预发布检查清单

发布前确认以下事项：

• task sp:validate 通过
• task be:ci 通过（lint + typecheck + test）
• task web:lint 通过
• 数据库迁移已测试（task be:db:migrate）
• 环境变量已更新（参考 附录 B）
• 文档已更新（task docs:build 通过）

---

13.8 小结

本章要点：

1. 五步启动：dp:up → publish-sp → load-hm → be:dev → web:dev。
2. Task 命令分 6 命名空间（dp/sp/be/web/deploy/根），本章是唯一权威表。
3. CI 含 4 个语义资产校验脚本 + pre-commit hooks + 代码质量工具链（ruff/ty/Biome/DeepEval/Ragas）。
4. 元数据修改工作流：编辑 → hooks → CI → PR Review → 合并 → 自动发布 S3 → Backend 自动同步 R/V/G 索引。
5. 开发者合并 PR 后无需手动操作，系统自动完成索引更新。

下一章：第 14 章 运行与安全——三层防御、认证、SQL 安全、可观测性与运维手册。