# OmniSupport Copilot

多模态企业支持知识层 + 工单联动 AI 系统（准生产级课程项目）

---

## 一句话定义

面向虚构企业 **Northstar Systems** 的准生产级多模态 AI 支持系统：
支持文档问答、证据引用、工单查询/创建/更新、指标查询、人工介入（HITL）、审计追踪、回归评测、版本与回滚。

---

## 前置条件

Week01 默认走 **Docker-only** 路线。学员不需要先配置本地 Python、PostgreSQL 或 MinIO。

必需：
- Docker Desktop / Docker Engine 24+
- Docker Compose V2（`docker compose` 可用）
- 现代浏览器（访问 Dagster / MinIO / Phoenix）

可选：
- `ANTHROPIC_API_KEY`
  - 留空：可完成 Week01 工程基线验证，RAG API 返回 fallback 响应
  - 填写：可继续验证真实生成链路

支持环境：
- macOS Apple Silicon / Intel
- Linux x86_64 / arm64
- Windows 11 + Docker Desktop / WSL2

Docker Desktop 受限环境：
- 如果公司电脑不允许安装 Docker Desktop，可以使用同一个 Git 仓库尝试 Podman Desktop / Podman CLI。
- Podman 路径是 best-effort 兼容，不单独维护非 Docker 源码分支。
- 兼容性验证和排障步骤见 [runbooks/podman-local.md](runbooks/podman-local.md)。

---

## 机器配置建议

| 场景 | CPU | 内存 | 磁盘空闲 | 说明 |
|------|-----|------|---------|------|
| Student Core Pack 最低配置 | 4 核 | 16 GB | 25 GB | 可完成 Week01-Week03 本地练习，首次构建会偏慢 |
| Student Core Pack 推荐配置 | 8 核 | 24 GB | 50 GB | 本地开发、反复重建、跑 contract test 更稳 |
| Instructor Scale Pack 推荐配置 | 8-12 核 | 32 GB+ | 80 GB+ | 适合更大数据包、更多 chunk、演示规模差异 |

说明：
- Student Core Pack 的目标规模是 `1,200–1,800` 源资产、`6–12 万` chunk，面向单机 Docker Compose。
- Instructor Scale Pack 的目标规模是 `6,000–10,000` 源资产、`20–50 万` chunk，更适合共享实验环境或高配机器。

---

## 快速启动（Week01 基线）

默认情况下，数据库只在 Docker 网络内可见，不要求也不依赖学员本机安装 PostgreSQL。

```bash
# 1. 复制环境变量
cp infra/env/.env.example infra/env/.env.local
# Week01 可先留空 ANTHROPIC_API_KEY
# 留空时，RAG API 会走 fallback 响应，不影响工程基线验证

# 2. 启动所有服务
docker compose --env-file infra/env/.env.local -f infra/docker-compose.yml up -d --build

# 3. 验证健康
curl http://localhost:8000/health   # RAG API
curl http://localhost:8001/health   # Tool API
# 在浏览器访问:
# http://localhost:3000  Dagster UI
# http://localhost:9001  MinIO Console
# http://localhost:6006  Phoenix (AI 可观测)

# 4. 生成种子工单数据（无本地依赖）
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python data/synthetic_generators/ticket_simulator.py --count 500 \
    --output data/canonization/tickets/tickets-seed-001.jsonl

# 5. dry-run seed loader（无本地依赖）
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.ingestion.seed_loader \
    --manifest-path data/seed_manifests/manifest_edge_gateway_pdf_v1.json \
    --manifest-path data/seed_manifests/manifest_tickets_synthetic_v1.json \
    --manifest-path data/seed_manifests/manifest_workspace_helpcenter_v1.json

# 6. 运行契约测试（无本地依赖）
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/contract/ -v
```

如果你仍然想在宿主机本地直接跑 Python 命令，再自行创建 `.venv`。默认文档路径不再要求学员这么做。

---

## 业务世界观

| 产品线 | 定位 | 典型数据 |
|--------|------|---------|
| **Northstar Workspace** | 企业协作 / 工单 / 自动化 SaaS | Help Center, FAQ, Release Notes, API 文档, 工单 |
| **Northstar Edge Gateway** | 边缘采集设备 / 网关硬件 | PDF 安装手册, 规格说明, 接线图, 故障排查视频 |
| **Northstar Studio** | 实施与监控产品 | 教学视频, 录屏教程, 错误码手册, 社区问答 |

---

## 架构总览（七层）

![OmniSupport Copilot 七层架构总览](docs/assets/readme-seven-layer-architecture.png)

详见 [docs/blueprints/project-blueprint.md](docs/blueprints/project-blueprint.md)

---

## 技术栈与选型理由

| 层 | 技术 | 为什么这样选 |
|----|------|-------------|
| 对象存储 | MinIO | 本地可跑，接口与 S3 兼容，后续切云端对象存储时迁移成本低 |
| 结构化 + 向量检索 | PostgreSQL + pgvector | Week01-Week08 阶段单机可跑，既能保留结构化数据，也能承接向量检索与 FTS |
| 湖仓层 | Apache Iceberg | 支持快照、时间旅行、Schema Evolution，契合课程后续治理与回滚章节 |
| 编排层 | Dagster | 资产化编排更适合课程讲“依赖、回填、血缘、DoD” |
| 服务层 | FastAPI | 契约清晰、调试成本低、适合本地教学和 API smoke test |
| 可观测 | OpenTelemetry + Phoenix | 从 Week01 就预埋 `trace_id / release_id`，后续能自然衔接 tracing 与 bad case replay |
| 契约层 | JSON Schema | 数据契约、工具契约、发布契约都能机读校验，适合课程工程化落地 |
| 本地工具执行 | Docker `devbox` | 学员不必先配本地 Python 环境，命令路径统一 |

选型原则：
- 先保证 **Student Core Pack 本地可跑**
- 再保证后续章节能自然扩展到治理、评测、Tracing、回滚
- 不为“演示规模”单独写另一套代码路径

---

## 本地部署拓扑

![OmniSupport Copilot 本地部署拓扑](docs/assets/readme-local-deployment-topology.png)

默认对宿主机开放的端口：
- `8000` — RAG API
- `8001` — Tool API
- `3000` — Dagster
- `9000/9001` — MinIO API / Console
- `6006` — Phoenix

默认不对宿主机开放：
- PostgreSQL `5432`
  - 只在 Docker 网络内可见，避免与学员本机数据库冲突

---

## 课程交付与 Repo 逻辑图

![AI 数据工程课程 Repo 逻辑链路总图](docs/assets/readme-course-repo-logic-map.png)

这张图不是单纯的目录树，而是把三层关系放在一起看：
- 课程站点（Quarto）如何展开到周页、课时页、实验页、Live 演示页
- `omnisupport-copilot` 主仓库如何按周推进到数据契约、采集、湖仓、解析、检索、工具、评测与治理
- 横切能力如何在 `docs/`、`tests/`、`runbooks/`、`observability/`、`contracts/release/` 之间复用

阅读建议：
- 想先理解系统能力边界：看上面的“七层架构总览”
- 想理解本地怎么跑起来：看上面的“本地部署拓扑”
- 想理解课程与主仓库如何逐周对齐：看这张“Repo 逻辑图”
- 想理解 `omnisupport-copilot` 单仓内部怎么从目录走到运行链路：看下面的“单仓代码与组件总览”
- 想直接定位文件夹：继续看下面的“仓库结构”

---

## 单仓代码与组件总览

![OmniSupport Copilot Repo 总体代码与组件规划图](docs/assets/readme-repo-code-component-map.png)

这张图是 `omnisupport-copilot` 的单仓放大视图，重点不是课程站点，而是：
- 仓库目录如何按 `infra / contracts / data / pipelines / services / docs / tests` 组织
- 主运行链路如何从 `source -> ingestion -> lakehouse -> semantic -> retrieval -> application -> delivery` 逐层推进
- PostgreSQL、MinIO、Dagster、FastAPI、Phoenix / OTel 这些运行时组件在仓库中的落点和职责
- `contracts / docs / tests / runbooks / observability / governance` 这些横切能力如何贯穿全链路

如果上一张图回答的是“课程如何和主仓库对齐交付”，这张图回答的是“主仓库内部到底怎么组织代码、组件和运行主线”。

---

## 仓库结构

```
omnisupport-copilot/
├── infra/                      # Docker Compose + 数据库 migrations + 环境变量
├── services/
│   ├── rag_api/                # FastAPI RAG 检索生成服务 (port 8000)
│   └── tool_api/               # FastAPI 工单工具 + HITL + 审计 (port 8001)
├── pipelines/                  # Dagster 资产化 pipeline
│   ├── ingestion/              # Seed loader + 采集资产
│   ├── data_factory/           # Week06 资产化编排、partition、backfill、checks、evidence
│   ├── resources/              # Pipeline runtime resources / env config
│   ├── parse_normalize/        # 文档解析 + 切片 + 证据链
│   ├── lakehouse/              # Iceberg Bronze/Silver/Gold 表
│   └── indexing/               # 向量索引构建
├── analytics/                  # Week05 dbt Core 项目 + KPI mart + metric registry
├── contracts/                  # JSON Schema 数据/工具/发布契约
│   ├── data/                   # 四类数据契约 (doc/ticket/audio/video)
│   ├── tools/                  # 工具契约规范 + 具体工具定义
│   ├── release/                # Release Manifest Schema
│   └── run_evidence/           # Week06 运行证据契约
├── data/
│   ├── seed_manifests/         # 种子数据清单
│   ├── synthetic_generators/   # 合成工单/音频生成器
│   └── canonization/           # 规范化后的课程资产
├── observability/              # OTel Collector 配置 + Phoenix + dashboards
├── evals/                      # 评测集 + eval harness + 回归报告
├── tests/
│   ├── contract/               # JSON Schema 契约测试
│   ├── integration/            # API smoke tests
│   └── eval_regression/        # 回归评测测试
├── docs/blueprints/            # 项目蓝图 + 风险边界清单
└── runbooks/                   # 运维操作手册
```

---

## 逐周进度

| Week | 状态 | 主要产出 |
|------|------|---------|
| W01 | ✅ | 工程基线、契约、seed manifest、蓝图 |
| W02-03 | 🔄 | 四类数据契约、ingest pipeline |
| W04 | 🔄 | PyIceberg SQL Catalog、MinIO warehouse、Bronze/Silver 四表物化、snapshot/time travel/schema evolution |
| W05 | 🔄 | dbt Core、support KPI mart、metric registry、受控 KPI 查询工具 |
| W06 | 🔄 | 资产化编排、daily partitions、backfill dry-run、asset checks、run evidence |
| W07-08 | 📅 | 多模态解析、混合检索、RAG API |
| W09-15 | 📅 | Tool层、评测、Tracing、GraphRAG、治理、Capstone |

## Week04 Lakehouse 最小闭环

Week04 的学生主路径仍然是 Docker devbox，不要求宿主机安装 Python / PostgreSQL / MinIO。

```bash
# 1. 启动 Lakehouse 依赖
docker compose --env-file infra/env/.env.local -f infra/docker-compose.yml up -d --build postgres minio minio_init

# 2. 校验 Week04 环境契约
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.lakehouse.settings --check

# 3. 加载 PyIceberg SQL Catalog 并确保 namespace / core tables
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.lakehouse.catalog --smoke

# 4. 物化四张核心 Iceberg 表
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.lakehouse.materialize --all-core --report-json reports/week04/materialization_report.json

# 5. 查看 snapshot / files / baseline
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.lakehouse.inspect_metadata --table silver.ticket_fact --view snapshots
```

Week04 runbook: [runbooks/week04/README.md](runbooks/week04/README.md)

边界说明：
- Week04 主执行路径是 `devbox` CLI。
- Dagster 当前使用上游镜像，是 thin wrapper，不作为 PyIceberg 写入主路径。
- 不引入 Spark / Hive / Nessie / Trino / REST catalog，不抢跑 Week05-08。

---

## Week05 Analytics Engineering 最小闭环

Week05 在不改变 Week01-Week04 主路径的前提下，新增 `analytics/` dbt Core 项目，并把 PostgreSQL 中的工单事实表转换为可治理的 KPI mart。

```bash
# 1. 构建 dbt 模型和测试
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  bash -lc 'cd analytics && DBT_PROFILES_DIR=. dbt build --select tag:week05'

# 2. 校验 metric registry
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python analytics/scripts/validate_metric_registry.py --json

# 3. 调用受控 KPI 查询工具
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  bash -lc 'PYTHONPATH=services/tool_api python -m app.kpi_query --example valid'
```

Week05 runbook: [runbooks/week05/README.md](runbooks/week05/README.md)

边界说明：
- Agent 只能通过 `query_support_kpis_v1` 查询 `analytics.agent_tool_input_view`。
- 不接受 raw SQL，不暴露 PII 字段，不绕过 `metric_registry_v1.yml`。
- dbt `target/` 和本地运行日志是临时产物，不提交。

---

## Week06 Data Factory 最小闭环

Week06 在 Week03-Week05 的可执行路径之上新增资产化编排层：Dagster asset graph、daily partition、backfill dry-run、asset checks 和 run evidence。默认仍然走 Docker `devbox`，不要求学员宿主机安装 Python。

```bash
# 1. 校验 Week06 run evidence 契约
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/contract/test_week06_run_evidence_schema.py -q

# 2. 校验 Dagster definitions 可加载
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/integration/test_week06_definitions_loadable.py -q

# 3. 生成 backfill dry-run plan
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  python -m pipelines.data_factory.backfill_plan --partition 2026-04-17 --mode dry-run

# 4. 跑 Week06 asset graph smoke
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/integration/test_week06_asset_graph_smoke.py -q
```

Week06 runbook: [runbooks/week06-data-factory.md](runbooks/week06-data-factory.md)

边界说明：
- Week06 复用 `pipelines/ingestion/ticket_ingest.py`，不复制或重写 Week03 业务写入逻辑。
- 默认 `WEEK06_INGEST_DRY_RUN=true`，因此不会修改 PostgreSQL。
- Week04 lakehouse / Week05 analytics 在 Week06 中是 optional observation，缺失时必须写 `not_available`，不能伪造成 passed。
- Podman 使用同一个 compose 文件，详见 [runbooks/podman-local.md](runbooks/podman-local.md)。

---

## 核心实施原则

1. **Data-first** — 先数据层，再生成层
2. **Workflow-first** — 先稳定工作流，再复杂 Agent
3. **Evidence-first** — 所有回答必须带 `evidence_anchor` / `citation`
4. **Release-aware** — 所有服务预埋 `release_id`, `trace_id`
5. **Dual-scale** — Student Core Pack（本地可跑）+ Instructor Scale Pack（规模演示）

---

## 非功能性要求

- **可重复**：同 release 组合离线评测可复现
- **可观测**：所有请求携带 `trace_id`，关键 span 可查
- **可回滚**：30 分钟内可回滚到上一稳定 release
- **可审计**：高风险操作记录完整审计日志