这份文档是什么：把 BIE 拆成"组件（用什么库/服务）+ 契约（按什么协议对接）+ 骨架（怎么分层）"三张清单。目的是让你知道——搭一套生产级 DDD 系统，该选哪些零件、零件之间按什么协议说话。
已按要求剔除 AI 业务功能（llm_runtime、memos、LangGraph 编排等），它们单列在文末"可选/AI 专用"里，默认不算核心骨架。
一、骨架（结构，一眼版）
后端 = 模块化单体 前端 = Feature-Sliced Design
app/ src/
├── core/ 技术内核 ├── app/ 装配
├── shared/ 横切设施 ├── routes/ 路由
│ ├── outbox/ 事件出箱 ├── widgets/ 复合区块
│ ├── observability/ 追踪 ├── features/ 用户能做的事
│ └── jobs/ 异步任务 ├── entities/ 前端限界上下文
└── modules/<ctx>/ └── shared/ 底座(api/ui/lib)
├── api/ 接口 └── api/
├── application/ 用例(CQRS) ├── generated/ 契约生成(不可改)
├── domain/ 业务规则 ├── adapters/ 防腐层
└── infrastructure/ 持久化 └── client.ts 统一出入口
结构的两条不变量：边界（每层只依赖该依赖的，工具强制）+ 一致（前后端共用机器契约）。详见 README。
二、后端组件清单（基础设施零件）
| 类别 | BIE 选型（真实依赖） | 作用 | 常见替代 |
|---|---|---|---|
| Web 框架 | FastAPI + uvicorn + python-multipart | HTTP 接口、自动产出 OpenAPI | Flask / Django / Litestar |
| ORM / 数据库 | SQLAlchemy[asyncio] + asyncpg + psycopg | 异步 ORM，接 PostgreSQL | Tortoise / SQLModel |
| 迁移 | Alembic | 数据库 schema 版本管理 | — |
| 缓存 / KV | Redis | 缓存、限流、分布式锁、token 存储 | — |
| 任务运行时 | Taskiq[metrics] + taskiq-redis | 异步后台任务、事件消费（worker 进程） | Celery / Arq / Dramatiq |
| 可观测 | OpenTelemetry（api/sdk + 一堆 instrumentation：fastapi/asyncpg/httpx/redis/sqlalchemy/logging）+ OTLP exporter | 全链路追踪、指标、结构化日志 | — |
| 对象存储 | aioboto3 + aiofiles | S3 兼容存储（MinIO/OSS），文件与产物 | — |
| HTTP 客户端 | httpx + socksio | 调外部服务 | aiohttp |
| 认证 | python-jose[cryptography]（JWT）+ passlib[bcrypt]（密码哈希） | 签发/校验 token、密码加密 | pyjwt / authlib |
| 配置 / 序列化 | pydantic + pydantic-settings + orjson | 配置、DTO 校验、快 JSON | — |
| ID 生成 | uuid-utils（UUIDv7） | 有序唯一 ID（事件/聚合） | ulid |
| 实时推送 | Centrifugo（独立服务）+ core/centrifugo.py 客户端 |
服务端 → 浏览器 WebSocket 推送 | Socket.IO / 自建 WS |
| 文档处理 | python-docx + mistletoe + markitdown | Markdown/Word 转换（产物导出） | — |
运行时拓扑（docker compose 真实服务）：
backend+taskiq-worker+postgres+redis+minio+centrifugo，前面挂frontend，外加bootstrap（初始化）。
三、前端组件清单（FSD 零件）
| 类别 | BIE 选型 | 作用 | 备注 |
|---|---|---|---|
| UI 框架 | React + react-dom | 视图 | — |
| 服务端状态 | @tanstack/react-query | 缓存/失效/去重，唯一"服务端真相源" | 不往 store 塞服务端数据 |
| 客户端状态 | zustand | 仅放 UI 偏好等"客户端状态" | — |
| 路由 | @tanstack/react-router（+ router-generator/plugin 代码生成路由） | 类型安全路由 | — |
| 契约生成 | orval（读 OpenAPI 生成 React Query hooks）+ datamodel-code-generator | 前端 api 层不手写、零漂移 | 见契约章 |
| 接口 mock | msw | 按契约 mock，后端没好也能开发 | orval 自动生成 |
| HTTP | axios（orval 的 customInstance） | 统一 baseURL/鉴权/错误 | shared/api/client.ts |
| 运行期校验 | zod（+ @hookform/resolvers + react-hook-form） | 表单 + 响应运行期校验 | “相信契约 → 验证契约” |
| 实时 | centrifuge（Centrifugo 客户端） | 订阅服务端推送 | 对接后端 outbox→centrifugo |
| 设计系统 | shadcn + radix-ui + tailwindcss + cva + clsx + tailwind-merge | 组件库与样式 | 放 shared/ui |
| 富文本/Markdown | tiptap / novel；react-markdown + remark + unified | 编辑器、渲染 | — |
| 动画 | framer-motion / motion | 交互动效 | — |
| 测试 | vitest（单测）+ @playwright/test（e2e）+ coverage | — | — |
| Lint/Format | Biome + ESLint | 代码规范 | 建议补 FSD 边界 linter |
四、协议与契约清单（零件之间"按什么说话"）★重点
这是把各组件缝成一个系统的关键——每条都是一份"接口合同"：
| 协议 / 契约 | 是什么 | 在 BIE 哪里用 | 它保证了什么 |
|---|---|---|---|
| OpenAPI | 后端 HTTP 接口的机器可读规范 | FastAPI 自动产出 /openapi.json → orval 生成前端客户端 |
前后端零漂移：契约即代码，改字段编译期就报错 |
| CloudEvents 1.0 | 标准化的"事件信封"格式（type/source/subject/data…） | shared/outbox 出箱事件的封装；relay 推送时拼 CE JSON |
事件跨服务可识别、可路由，不绑定私有格式 |
| W3C TraceContext | traceparent 头，跨进程传递链路 ID |
OpenTelemetry 注入 HTTP；出箱事件表存 traceparent 列；taskiq 中间件透传 |
全链路可追踪：一次请求串起 HTTP→事件→异步任务 |
| JWT (Bearer) | 无状态身份令牌 | auth 模块签发；前端 client.ts 注入 Authorization 头 |
无状态鉴权，前后端一致的身份契约 |
| 架构契约（import-linter） | 用配置声明"哪层不许依赖哪层" | 后端 pyproject.toml 的 contracts，CI 执法 |
边界机器执法：分层规则违反即红灯 |
| WebSocket（Centrifugo 协议） | 服务端 → 浏览器实时推送 | 后端 outbox relay → Centrifugo；前端 centrifuge 订阅 channel |
实时性，且与业务事件（出箱）解耦 |
| SSE / 流式响应 | HTTP 流式返回（逐块） | chat 类接口的流式输出 | 大模型/长任务的渐进式返回 |
| MCP（Model Context Protocol） | 给 AI 接外部工具的标准协议 | modules/mcp + langchain-mcp-adapters |
工具接入标准化（⚠️ 偏 AI，见文末） |
| AG-UI Protocol | Agent ↔ 前端 UI 的交互协议 | 后端 ag-ui-protocol；前端 @ag-ui/client |
Agent 交互标准化（⚠️ 偏 AI，见文末） |
| mock 契约（msw） | 按 OpenAPI 生成的假接口 | 前端 openapi:mock |
前后端并行开发，mock 与真契约同源 |
五、组件 ↔ 契约 ↔ DDD 分层 对应（把三张清单缝起来）
[前端 features/entities] ──React Query/axios──┐
│ 协议：OpenAPI（orval 生成）
[后端 api 接口层 (FastAPI)] ◄───────────────────┘ 契约：JWT 鉴权、统一响应信封
│
[application 用例层 (CQRS)] ──写──► domain 规则 ──► infrastructure (SQLAlchemy→PostgreSQL)
│ ▲
└──发事件──► shared/outbox ──CloudEvents──► relay ──┬──► Centrifugo (WebSocket) ──► 前端
(和业务同一事务/UoW) └──► Taskiq worker (异步消费)
│
全程贯穿：OpenTelemetry + W3C TraceContext（HTTP→事件→任务 一条链路）
全程守护：import-linter（后端边界）/ FSD linter（前端边界，建议补）
六、可选 / AI 专用组件（本骨架默认剔除）
按你的要求，下面这些是 BIE 的 AI 业务功能，不属于"通用生产骨架"，需要做 AI 时再加：
| 组件 / 模块 | 作用 | 归类 |
|---|---|---|
core/llm_runtime |
统一 LLM 运行时（langchain-openai 等） | ❌ 剔除 |
core/memos |
长期记忆治理（接 MemOS：neo4j+qdrant） | ❌ 剔除 |
studio/ + chat/infrastructure/graphs |
LangGraph 编排（langgraph + checkpoint-postgres） | ❌ 剔除 |
modules/mcp + langchain-mcp-adapters |
MCP 工具接入 | ⚠️ AI 相关，可选 |
| ag-ui-protocol / @ag-ui/client | Agent-UI 交互协议 | ⚠️ AI 相关，可选 |
| tavily-python / volcengine / markitdown | 搜索 / 云厂商 / 文档解析 | ⚠️ 业务相关，可选 |
剔除后，剩下的第二~五章那些组件和契约，就是一套与业务无关、可复用到任何项目的生产级 DDD 系统骨架的"零件 + 接口"全集。
七、最小起步该选哪几样
不用一次上全。优先级：
- 必备：FastAPI + SQLAlchemy + PostgreSQL + Alembic + pydantic + OpenAPI 契约（FastAPI 自带）+ orval（前端）+ import-linter（边界）。
- 要可靠性：加 outbox（CloudEvents 信封）+ UoW（事务）。
- 要规模：加 Taskiq（异步）+ Redis（缓存）+ 对象存储。
- 要可观测：加 OpenTelemetry（W3C TraceContext 贯穿）。
- 要实时：加 Centrifugo（WebSocket）。
🪞 一句话：组件是"零件"，协议契约是"零件之间的接口标准"。 选对零件不难，难的是让它们按统一契约说话——OpenAPI 缝前后端、CloudEvents 缝事件、TraceContext 缝可观测、import-linter 焊边界。记住这四条契约，这套系统就立住了。
