docs: ai 协作文档体系重构与多 ai 仲裁结果落地

1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md)

2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration)

3.各服务 01/02 文档补全

4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens)

5.Proto 契约补全

6.004 架构影响地图更新

7.端口分配表

8.设计规格文档

services/ai/docs/01-understanding.md

@@ -0,0 +1,384 @@
+# 模块理解确认书 — ai
+
+> AI 标识：ai12（复核与长期演进接手）← ai06（初稿，2026-07-09）
+> 负责模块：ai（P5）— 按 [ai-allocation.md §3.2](../../../docs/architecture/ai-allocation.md) v1.0 最新分配，ai 由 ai12 专责
+> 语言：Python 3.12+ / FastAPI 0.115+
+> 阶段：架构设计外包 · 阶段 1（全局理解，ai06 初稿 + ai12 长期演进复核）
+> 日期：2026-07-09（ai06 初稿）/ 2026-07-09（ai12 复核与补充）
+> 关联文档：[ai-allocation.md](../../../docs/architecture/ai-allocation.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features.md](../../../docs/architecture/roadmap/pending-features.md)、[coord 交叉审查报告](../../../docs/architecture/coord-cross-review.md)、[known-issues.md](../../../docs/troubleshooting/known-issues.md)
+>
+> **ai12 接手说明**：本确认书初稿由 ai06 在 ai-allocation v0.x 阶段（ai06 同时负责 data-ana + ai）撰写。ai-allocation.md v1.0 将 ai 模块独立分配给 ai12。ai12 在 ai06 初稿基础上执行：作者归属更正、长期架构演进补充、P5 交付物覆盖度核对、向前兼容性铺垫。**所有 ai12 新增内容用「ai12 增补」标注**，ai06 原文保留并标注「ai06 初稿」。
+
+---
+
+## 阶段 1 必读清单完成确认
+
+按 ai-allocation.md §4，ai12 必读 7 份全局文档 + 全部 `.proto` + `services/data-ana/`、`services/ai/` 骨架源码：
+
+| #   | 文档                                                                                 | 状态                                                                                |
+| --- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| 1   | [README.md](../../../README.md)                                                      | ✅ 已读                                                                             |
+| 2   | [MIGRATION_GUIDE.md](../../../MIGRATION_GUIDE.md)                                    | ✅ 已读                                                                             |
+| 3   | [004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)        | ✅ 已读（重点 §1.2/§4.1/§4.2/§7.2/§9.3/§11.5/§12.2/§15）                            |
+| 4   | [pending-features.md](../../../docs/architecture/roadmap/pending-features.md)        | ✅ 已读（重点 P5 沟通与 AI 阶段）                                                   |
+| 5   | [project_rules.md](../../../.trae/rules/project_rules.md)                            | ✅ 已读（workspace 规则，重点 §3.6 Python/§6 事件驱动/§9 问题记录/§10 AI 工作流程） |
+| 6   | [coding-standards.md](../../../docs/standards/coding-standards.md)                   | ✅ 已读（重点 §4 Python 规范）                                                      |
+| 7   | [multi-ai-collaboration.md](../../../docs/standards/multi-ai-collaboration.md)       | ✅ 已读                                                                             |
+| 8   | `packages/shared-proto/proto/*.proto`（8 份）                                        | ✅ 已读（重点 ai.proto/analytics.proto/content.proto/events.proto）                 |
+| 9   | `services/ai/src/` 全部源码（main.py/config.py/llm_client.py/health/health.py）      | ✅ 已读                                                                             |
+| 10  | `services/data-ana/src/` 全部源码（参考 Python 服务实现模式 + 跨服务 gRPC 契约对齐） | ✅ 已读（ai12 增补：跨服务 gRPC 契约对齐用）                                        |
+| 11  | [coord 交叉审查报告](../../../docs/architecture/coord-cross-review.md)               | ✅ 已读（ai12 增补：理解 7 项已仲裁共性问题）                                       |
+
+> ai12 与 ai06 不同：ai-allocation.md v1.0 §4 矩阵 ai06 列对黄金模板为 "—"，ai12 列同为 "—"（Python 服务无需对照 TS 黄金模板），但需对照 `services/data-ana/` 作为 Python 服务实现参考（lifespan/structlog/OTel/metrics 模式）。
+
+---
+
+## 1. 我在架构中的位置
+
+### 1.1 架构定位（ai06 初稿 + ai12 增补）
+
+- **层级**：业务微服务层（L5），属 **D6 智能洞察领域**（004 §1.1b，与 data-ana 共享领域）
+- **领域细分**（ai12 增补）：D6 内部分两个子域
+  - **D6.a 分析子域**（data-ana 负责）：基于历史数据计算学情、掌握度、趋势
+  - **D6.b 生成子域**（ai 负责）：基于学情上下文 + LLM 推理生成教学内容
+  - 两子域通过 gRPC 同步查询耦合，构成"分析→生成"闭环
+- **上游**：
+  - api-gateway 直接 HTTP 代理 `/api/v1/ai/*` → ai:3008（见 [api-gateway main.go](../../api-gateway/main.go)）
+  - teacher-bff 聚合 AI 出题/优化能力（004 §4.1：BFF → ai，P5 起转 gRPC）
+  - **ai12 增补**：student-bff（P3+）/ parent-bff（P4+）未来可能调用 AI 服务用于学生自适应学习、家长学情报告 AI 解读
+- **下游**：
+  - content 服务（gRPC 查询知识点 / 题库，004 §4.1：AI → Content gRPC）
+  - data-ana 服务（gRPC 查询学情数据，004 §4.1：AI → DataAna gRPC）
+  - LLM Provider（外部 HTTP，OpenAI 兼容 REST API）
+  - **ai12 增补**：iam 服务（gRPC 查询 `GetEffectiveDataScope`，用于多租户/多学校用量配额校验；当前 iam.proto 未提供此 RPC，coord 已仲裁 P4 补全）
+  - **ai12 增补**：msg 服务（Kafka 事件 `edu.notification.events` 由 msg 消费，ai 不直接调用；但 AI 异常告警可能走 msg 推送给管理员，长期可考虑）
+- **通信方式**：
+  - 入口：当前 REST（`/ai/chat`、`/ai/chat/stream`、`/ai/generate/question`、`/ai/optimize/expression`）；目标态（ai.proto）转 **gRPC** 暴露 `AiService`（含 `StreamChat` 流式 RPC），004 §4.2 明确 P5 启用
+  - 出口：gRPC 调 content / data-ana（**当前未实现，仅 LLM HTTP 调用**）；SSE 流式对前端；Kafka 事件外发用量计费
+- **端口**：3008（HTTP）+ 50058（gRPC，**ai12 增补**：004 §1.2 gRPC 端口规则 `HTTP+10050`，需在 §1.2 端口矩阵补登，提请 coord 同步）
+
+### 1.2 服务边界与无状态原则（ai12 增补）
+
+ai 是**严格无状态服务**，这与 data-ana 的"无 MySQL 写但有 ClickHouse 读模型"形成鲜明对比。无状态原则的含义与边界：
+
+| 维度       | ai（无状态）                                          | data-ana（有读模型）                      |
+| ---------- | ----------------------------------------------------- | ----------------------------------------- |
+| 持久化存储 | 无独占 DB                                             | ClickHouse 宽表（读模型）                 |
+| 会话状态   | 单次请求内（无跨请求会话，聊天历史由前端维护）        | 无                                        |
+| 缓存       | Redis（Prompt 模板、限流计数、响应缓存）              | Redis（DataScope 缓存）                   |
+| 事件发布   | `AIUsageRecorded`（派生数据，豁免 Outbox，004 §12.2） | `MasteryUpdated`（派生数据，豁免 Outbox） |
+| 水平扩展   | 直接加副本，无状态同步问题                            | CDC 消费者需 consumer group 协调          |
+
+**无状态原则的例外**（需 coord 长期跟踪）：
+
+- 长运行工作流（备课工作流的"教师审核"步骤可能跨越数小时甚至数天）的状态需持久化，不能依赖内存。ai12 提请 coord 在 P6 评估引入 Temporal 或自建 workflow_state 表（详见 02-architecture-design.md §2.4）
+
+## 2. 我的限界上下文
+
+### 2.1 聚合职责（ai06 初稿 + ai12 增补）
+
+- **聚合职责**：LLM 调用网关 + 教学场景 AI 编排（备课 / 出题 / 表达优化），承载 **D6 智能洞察领域**的"生成"子域
+- **聚合根 / 实体**：
+  - `ChatConversation`（聊天会话，**待实现**，当前无状态）
+  - `GeneratedQuestion`（生成的题目，待审核入库）
+  - `PromptTemplate`（Prompt 模板，**待实现**）
+  - `UsageRecord`（用量计费记录，**待实现**，通过事件外发不落本服务 DB）
+  - **ai12 增补**：`LessonPreparationWorkflow`（备课工作流实例，长运行状态需持久化）
+  - **ai12 增补**：`EvaluationResult`（生成结果质量评估结果，待实现，用于 RLHF 数据收集与质量门禁）
+- **业务领域**：D6 智能洞察（与 data-ana 共享，data-ana 偏"分析"，ai 偏"生成"）
+- **我不负责**：
+  - 不负责题库存储（→ content 服务，ai 生成后调 content.CreateQuestions 入库）
+  - 不负责学情计算（→ data-ana 服务，ai 查询学情用于个性化出题）
+  - 不负责通知投递（→ msg 服务）
+  - 不负责用户身份认证（→ iam + Gateway，ai 信任 `x-user-id`/`x-user-roles` 头）
+  - **ai12 增补**：不负责教学大纲管理（→ content 服务的 Textbook/Chapter/KnowledgePoint）
+  - **ai12 增补**：不负责学生作业批改（→ core-edu，ai 仅生成题目与解析，不批改学生作答）
+- **数据自治**：**无独占数据库**（设计上无状态；用量计费通过 Kafka 事件外发；长运行工作流状态待 P6 决策是否引入持久化）
+
+### 2.2 ai12 增补：与 content / data-ana / msg 的边界精细化
+
+为避免未来跨服务职责漂移，明确以下边界（参考 004 §1.1b D6/D4/D5 划分）：
+
+| 业务能力             | 归属服务   | 边界说明                                                          |
+| -------------------- | ---------- | ----------------------------------------------------------------- |
+| 题目生成（LLM 调用） | ai         | ai 调 LLM 生成题目文本，返回给 BFF；不入 content 题库             |
+| 题目入库             | content    | BFF 拿 ai 生成的题目 → 调 content.CreateQuestions 入库            |
+| 知识点前置依赖查询   | content    | ai 调 content.KnowledgeGraphService.GetPrerequisites              |
+| 学生学情查询         | data-ana   | ai 调 data-ana.AnalyticsService.GetStudentWeakness                |
+| 班级整体学情查询     | data-ana   | ai 调 data-ana.AnalyticsService.GetClassPerformance               |
+| 生成结果质量评估     | ai         | ai 内部 LLM-as-judge / 规则校验，不外发                           |
+| 用量计费落库         | data-ana   | ai 发 `edu.insight.ai.usage` 事件，data-ana 消费落 ClickHouse     |
+| AI 异常告警通知      | msg        | ai 异常 → 日志 + metrics，告警由 Prometheus Alertmanager 触发 msg |
+| 教师审核备课结果     | BFF + 前端 | ai 仅生成与暂存（Redis 短期），审核状态由 BFF 编排                |
+
+## 3. 我与外部的契约
+
+### 3.1 消费的 proto message（ai06 初稿 + ai12 增补）
+
+| 来源            | message / service                                          | 用途                                      | 状态                      |
+| --------------- | ---------------------------------------------------------- | ----------------------------------------- | ------------------------- |
+| content.proto   | `KnowledgeGraphService.GetPrerequisites`                   | 查询知识点前置依赖用于出题上下文          | proto 已定义              |
+| content.proto   | `KnowledgeGraphService.GetLearningPath`                    | 查询学生学习路径用于个性化出题            | proto 已定义              |
+| content.proto   | `TextbookService.ListTextbooks`                            | 查询教材上下文（章节关联知识点）          | proto 已定义（ai12 增补） |
+| analytics.proto | `AnalyticsService.GetStudentWeakness`                      | 查询学生薄弱知识点用于靶向出题            | proto 已定义              |
+| analytics.proto | `AnalyticsService.GetLearningTrend`                        | 查询学习趋势用于难度调节                  | proto 已定义              |
+| analytics.proto | `AnalyticsService.GetClassPerformance`                     | 查询班级整体学情用于备课工作流            | proto 已定义（ai12 增补） |
+| iam.proto       | `IamService.GetEffectiveDataScope`（**待 coord P4 补全**） | 查询用户 DataScope 用于多学校用量配额校验 | proto 待补全（ai12 增补） |
+| ai.proto        | `ChatRequest` 等                                           | gRPC 暴露契约（**待实现 gRPC server**）   | proto 已定义              |
+
+### 3.2 暴露的 API / 事件
+
+**HTTP 端点**（当前实现，见 [main.py](../src/ai/main.py)）：
+
+| method | path                      | 说明                         |
+| ------ | ------------------------- | ---------------------------- |
+| GET    | `/healthz`                | liveness                     |
+| GET    | `/readyz`                 | readiness（含 LLM 是否配置） |
+| GET    | `/metrics`                | Prometheus 指标              |
+| POST   | `/ai/chat`                | LLM 聊天（非流式）           |
+| POST   | `/ai/chat/stream`         | LLM 流式聊天（SSE）          |
+| POST   | `/ai/generate/question`   | 生成题目                     |
+| POST   | `/ai/optimize/expression` | 优化表达                     |
+
+**ai12 增补：待新增 HTTP 端点**（P5 交付）：
+
+| method | path                                  | 说明                                           |
+| ------ | ------------------------------------- | ---------------------------------------------- |
+| POST   | `/ai/lesson/preparation`              | 备课工作流启动（分析学情→推荐知识点→生成题目） |
+| GET    | `/ai/lesson/preparation/{id}`         | 查询备课工作流状态（异步流程）                 |
+| POST   | `/ai/lesson/preparation/{id}/confirm` | 教师确认入库（触发 content.CreateQuestions）   |
+| GET    | `/ai/prompts`                         | Prompt 模板列表（CRUD）                        |
+| POST   | `/ai/prompts`                         | 创建 Prompt 模板                               |
+| PUT    | `/ai/prompts/{id}`                    | 更新 Prompt 模板（版本化）                     |
+| GET    | `/ai/usage/me`                        | 当前用户用量统计（短期查询，长期查 data-ana）  |
+
+**gRPC 契约**（ai.proto，**待实现 server**）：
+
+- `Chat(ChatRequest) → ChatResponse`
+- `StreamChat(ChatRequest) → stream ChatChunk`（流式 RPC）
+- `GenerateQuestion(GenerateQuestionRequest) → GeneratedQuestion`
+- `OptimizeExpression(OptimizeExpressionRequest) → OptimizedExpression`
+
+**ai12 增补：proto 待补全项**（提请 coord 在 P5 前补全）：
+
+- `GenerateLessonPlan(GenerateLessonPlanRequest) → LessonPlanResponse`：备课工作流 RPC
+- `StreamGenerateQuestion(...) → stream GeneratedQuestionChunk`：题目逐字流式生成（满足 ai-allocation.md §5 "题目逐字生成"）
+- `ChatRequest` 增加可选字段：`user_id`（透传，用于个性化）、`session_id`（用于多轮对话上下文）、`data_scope`（透传 DataScope 元数据）
+- `GenerateQuestionRequest` 增加字段：`grade`、`knowledge_point_ids`、`question_type`、`count`
+
+**ai12 增补：发布的领域事件**
+
+- 当前无发布（ai06 初稿）
+- 设计上发布 `AIUsageRecorded` 事件（用量计费），由 data-ana 消费落 ClickHouse。**004 §7.2 已确认 topic `edu.insight.ai.usage`**（coord 仲裁已通过，§15.3 #4）
+- **ai12 增补：长期可发布事件**（P6+ 评估）：
+  - `AIContentGenerated`（topic: `edu.insight.ai.generated`）：生成内容审计事件，供 data-ana 落库用于质量分析
+  - `AIFeedbackRecorded`（topic: `edu.insight.ai.feedback`）：教师对生成结果的反馈（采纳/拒绝/修改），用于 RLHF 数据集构建
+
+- **错误码前缀**：`AI_*`（详见阶段 2 §6.2）
+- **降级策略**：LLM API key 为空或调用失败时返回 `degraded: true` 骨架响应（见 [llm_client.py](../src/ai/llm_client.py)）
+
+### 3.3 ai12 增补：响应信封对齐
+
+按 004 §11.5 强制约束（coord 仲裁：Python 服务信封必须改为 ActionState，禁止 `{success, data, degraded}` 偏离结构）：
+
+- 当前 ai 实现违反约束（main.py 返回 `{success: true, data: ..., degraded: false}`）
+- P5 实施必须改为 ActionState：
+  - 成功：`{success: true, data: T}`
+  - 失败：`{success: false, error: {code, message, details?, traceId?}}`
+  - 降级：`details: {degraded: true}`（degraded 作为 details 子字段，非顶层字段）
+- 提请 coord 在 known-issues.md §2.9 ai-gateway 分区记录此约束
+
+## 4. 我的技术栈
+
+### 4.1 当前技术栈（ai06 初稿）
+
+- 语言：Python 3.12+
+- 框架：FastAPI 0.115+ / uvicorn
+- LLM 客户端：`httpx` 异步直接调 OpenAI 兼容 REST API（**不依赖 openai SDK**，见 [llm_client.py:1-7](../src/ai/llm_client.py)）
+- 配置：`pydantic-settings` BaseSettings（env_prefix=""）
+- 可观测：
+  - 日志：`structlog`
+  - 指标：`prometheus-client` + `make_asgi_app()`
+  - 链路：`opentelemetry-sdk` + `OTLPSpanExporter` + `FastAPIInstrumentor`（dev_mode=true 时跳过 exporter 初始化避免本地无 collector 报错）
+- 流式响应：FastAPI `StreamingResponse` + `AsyncGenerator`，SSE 格式 `data: <chunk>\n\n`
+- 测试：pytest（**当前 0% 覆盖率**）
+
+### 4.2 ai12 增补：长期技术栈演进路线
+
+为支撑 P5 交付物 + 未来多模态/RAG/Agent 演进，规划如下技术栈演进：
+
+| 类别       | 当前       | P5（M14-M16）               | P6+（长期演进）                            | 选型理由                                                   |
+| ---------- | ---------- | --------------------------- | ------------------------------------------ | ---------------------------------------------------------- |
+| LLM 客户端 | httpx 直连 | LLMProvider 抽象 + 4 适配器 | + Embedding Provider + Multimodal Provider | 抽象隔离 Provider API 差异，便于切换                       |
+| 工作流编排 | 无         | FastAPI BackgroundTasks     | Temporal（如 coord 仲裁引入）              | 简单 4 步用 BackgroundTasks；长运行（教师审核）需 Temporal |
+| RAG 检索   | 无         | gRPC 调 content 查询        | + 向量库（pgvector / Chroma）+ Embedding   | P5 复用 content；P6+ 评估独立向量库支持语义检索            |
+| 模板管理   | 硬编码     | YAML 文件 + Jinja2          | + DB 持久化 + 版本化 + A/B 测试            | P5 用文件简单；P6+ 评估迁移 DB 支持动态更新                |
+| 缓存       | 无         | Redis（hash + 令牌桶）      | + 语义缓存（embedding 相似度）             | P5 用 hash 缓存；P6+ 评估语义缓存减少重复 LLM 调用         |
+| 限流       | 无         | Redis 令牌桶（用户/IP）     | + 学校级配额 + token 级预算                | P5 用户/IP 级；P6+ 多租户配额管理                          |
+| 评估       | 无         | 规则校验 + LLM-as-judge     | + 人工评估 + 在线指标 + RLHF 数据集        | P5 自动化校验；P6+ 闭环反馈持续提升质量                    |
+| 测试       | 0%         | pytest ≥ 80%                | + 集成测试 + 契约测试 + LLM 评估测试       | P5 单元 + 集成；P6+ 评估测试保证生成质量                   |
+
+**关键选型决策记录**（ai12 增补，供 coord 备案）：
+
+1. **不引入 openai SDK**：保持 httpx 直连，避免 SDK 版本绑定 + 减少 attack surface；OpenAI 兼容 REST API 已成为事实标准（百川/Ollama/vLLM 均兼容）
+2. **P5 不引入 LangChain**：LangChain 抽象过重，与 LLMProvider 抽象层职责重叠；按 004 §2.3 列出的 LangGraph 待 P6+ 评估时再决定
+3. **P5 不引入向量库**：RAG 检索复用 content 服务的 Neo4j + ES（content 已规划 ES），避免数据冗余
+4. **不引入 openai SDK 但保留兼容性**：所有 LLM Provider 适配器实现 OpenAI 兼容 REST 接口，便于切换；非兼容 Provider（如 Anthropic 原生 API）在适配器内部转换
+
+## 5. 我的阶段归属
+
+### 5.1 阶段定位（ai06 初稿 + ai12 增补）
+
+- **P5 沟通与 AI 阶段（M14-M16）**：建 AI 网关 + LLM Provider 适配 + 流式 SSE + 用量计费
+- **退出标准**（pending-features P5）：
+  - AI 辅助出题流式返回
+  - 题库全文检索 < 200ms（**注**：ES 部分由 content 服务承担，ai 不直接负责）
+  - AI 网关流式 SSE 三层透传（AI → BFF → 前端）
+  - **ai12 增补细化**（基于 ai-allocation.md §5 ai12 交付清单）：
+    - LLM Provider 适配器模式（OpenAI/百川/本地模型，统一接口）✅
+    - SSE 流式响应（题目逐字生成 + 前端打字机效果）✅
+    - 出题 Prompt 模板管理（模板 CRUD + 参数注入：年级/学科/难度/知识点）✅
+    - 备课工作流编排（分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库）✅
+    - 用量计费/频率限制（按用户/按 IP/按 token 消耗）✅
+- **依赖上游**：
+  - P1 地基：api-gateway 路由
+  - P2 身份：iam 服务（鉴权 + DataScope）
+  - P4 内容分析：content 服务（gRPC 查询知识点 / 题库）+ data-ana 服务（gRPC 查询学情）
+  - 外部：LLM Provider API key（OpenAI / Anthropic / 百川 / 本地模型 Ollama）
+- **下游依赖我**：
+  - P5 teacher-bff 聚合 AI 出题 mutation（004 §9.3：教师用 AI 出题并发布到班级）
+  - P5 teacher-portal SSE 流式 AI 对话（前端）
+  - **ai12 增补**：P5+ student-bff（学生自适应学习，未来阶段）
+  - **ai12 增补**：P5+ parent-bff（家长学情报告 AI 解读，未来阶段）
+
+### 5.2 ai12 增补：阶段交付里程碑细分
+
+将 P5（M14-M16，3 个月）细分为 3 个里程碑，便于优先级排序：
+
+| 里程碑 | 时间  | 交付内容                                                                                  | 退出标准                                        |
+| ------ | ----- | ----------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| M14    | 第1月 | LLMProvider 抽象 + OpenAI/百川/Ollama 适配器 + gRPC server（Chat/StreamChat）+ Redis 限流 | gRPC 流式 RPC 可调通，多 Provider 切换可用      |
+| M15    | 第2月 | Prompt 模板管理（YAML + Jinja2）+ 出题工作流 + 题目逐字流式生成 + 用量计费事件            | 教师可发起 AI 出题，流式返回，用量落 ClickHouse |
+| M16    | 第3月 | 备课工作流 4 步编排 + 教师审核 + 入库 + 评估框架（规则 + LLM-as-judge）                   | 备课工作流端到端跑通，质量门禁生效              |
+
+## 6. 我需要对齐的黄金模板项（对照 classes 服务 + Python 规范）
+
+### 6.1 对齐清单（ai06 初稿 + ai12 增补）
+
+- [ ] 权限装饰器等价物：**当前 HTTP 端点全部裸露，无权限校验**。阶段 2 需设计 FastAPI Depends 权限依赖（AI 出题需 `AI_QUESTION_GENERATE` 权限，表达优化需 `AI_EXPRESSION_OPTIMIZE`）
+- [ ] 错误码前缀统一：**当前无错误码体系**，降级时返回 `degraded: true` 但无业务错误码。**阶段 2 需定义 `AI_*` 错误码清单**
+- [x] logger / metrics / tracer 三支柱（已具备）
+- [x] `/healthz` + `/readyz` 健康检查（已具备，readyz 含 LLM 配置状态）
+- [ ] 优雅关闭 SIGTERM：当前 lifespan 无显式 drain（LLM 流式请求需等待完成）
+- [ ] 测试覆盖率 ≥ 80%：**当前 0%**，无 tests/ 目录
+- [ ] Dockerfile 多阶段构建：**当前单阶段**（`FROM python:3.12-slim`）
+- [ ] Pydantic 输入验证：**当前仅 `ChatRequest` 是 BaseModel，`generate/question` 和 `optimize/expression` 直接接收 `prompt: str` / `text: str` query param，无请求体模型**。阶段 2 需补完整 Pydantic 请求/响应模型
+- [x] 配置通过 pydantic-settings 管理（已具备）
+- [x] 异步优先（httpx async + AsyncGenerator stream）
+- [x] 类型注解强制（已基本符合，main.py 函数返回值已标注）
+- [ ] LLM Provider 适配器模式：**当前仅 OpenAI 兼容 REST**，未抽象 Provider 接口。阶段 2 需设计 `LLMProvider` 抽象 + OpenAI/Anthropic/百川/本地 多适配器
+- [ ] Prompt 模板管理：**当前 Prompt 硬编码在 main.py**，阶段 2 需设计模板管理（DB 或文件）
+- [ ] 用量计费 / 频率限制：**当前无用量记录和限流**，阶段 2 需设计（Kafka 事件 + Redis 限流）
+- [ ] 备课工作流：**当前未实现**，pending-features P5 要求"分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库"完整工作流
+- [ ] ruff check 零错误：需阶段 2 验证
+
+### 6.2 ai12 增补：响应信封对齐（P0 强制）
+
+- [ ] **响应信封改为 ActionState**（004 §11.5 强制约束）
+  - 当前违反：`{success: true, data: ..., degraded: false}` 顶层 degraded 字段
+  - 必须改为：`{success: true, data: ...}` + 失败时 `{success: false, error: {code, message, details: {degraded: true}, traceId}}`
+  - 影响：所有 HTTP 端点 + gRPC RPC 返回值
+  - 提请 coord 在 known-issues §2.9 记录
+
+### 6.3 ai12 增补：长期架构对齐项
+
+- [ ] **API 版本化策略**：当前无版本前缀，建议 P5 加 `/ai/v1/*` 前缀，便于未来破坏性变更
+- [ ] **gRPC server interceptor 透传 trace context**：当前 HTTP 用 FastAPIInstrumentor 自动埋点，gRPC server 需补 `grpc.aio.ServerInterceptor` 透传 W3C traceparent
+- [ ] **下游 gRPC client interceptor**：调 content / data-ana 的 gRPC client 需补 client interceptor 注入 trace context + 失败重试 + 熔断
+- [ ] **PII 脱敏**：学生姓名、家长手机号等 PII 数据在写入 prompt 前必须脱敏（防止泄露给 LLM Provider）
+- [ ] **Prompt 注入防御**：用户输入的 prompt 必须经 sanitize（去除 SQL/HTML/JS 注入模式）后再拼入 system prompt
+- [ ] **输出内容审核**：LLM 输出必须经敏感词过滤 + 安全校验后再返回（防止生成不当内容）
+- [ ] **生成结果质量门禁**：题目生成必须经规则校验（题型匹配/答案非空/解析合理）+ LLM-as-judge（质量评分），不达标重新生成或降级
+- [ ] **多租户用量配额**：按学校/年级/教师维度配置 token 预算，超额拒绝调用（避免单一学校耗尽预算）
+
+---
+
+## 服务审计表 — ai12（ai 部分）
+
+> 对照 ai-allocation.md §10 审计模板。ai 为 Python/FastAPI，黄金模板对齐按 Python 规范（coding-standards §4）评估。
+> 符号说明：✅ 已实现 | ❌ 缺失 | ⚠️ 部分实现 | 📋 P5 待实现 | 🔮 P6+ 长期演进
+
+| 服务 | 权限校验 | 错误码前缀 | logger       | metrics       | tracer              | /healthz | /readyz           | 优雅关闭            | 测试覆盖率 | Dockerfile | 响应信封 | gRPC server | Provider 适配 | Prompt 模板 | 限流/计费 | 备课工作流 | PII 脱敏 | 质量门禁 |
+| ---- | -------- | ---------- | ------------ | ------------- | ------------------- | -------- | ----------------- | ------------------- | ---------- | ---------- | -------- | ----------- | ------------- | ----------- | --------- | ---------- | -------- | -------- |
+| ai   | ❌       | ❌         | ✅ structlog | ✅ prometheus | ✅ OTel（dev 跳过） | ✅       | ✅（含 LLM 状态） | ⚠️ 仅 lifespan 关闭 | 0%         | ❌ 单阶段  | ❌ 偏离  | ❌ 待实现   | ❌ 待实现     | ❌ 硬编码   | ❌ 待实现 | ❌ 待实现  | ❌ 缺失  | ❌ 缺失  |
+
+### 审计发现的关键差距（按优先级）
+
+#### P0 阻塞 P5 交付（ai06 初稿 + ai12 增补）
+
+1. **P0 权限校验缺失**：所有 `/ai/*` 端点裸露，AI 出题等敏感操作无权限校验
+2. **P0 gRPC server 未实现**：ai.proto 定义了 `AiService`（含 `StreamChat` 流式 RPC）但 ai 当前仅 HTTP。阶段 2 需引入 `grpc.aio` 实现 gRPC server + 流式 RPC
+3. **P0 gRPC client 未实现**：004 §4.1 明确 AI → Content / AI → DataAna 走 gRPC，当前未实现。阶段 2 需设计 gRPC client 调用 content / data-ana
+4. **P0 响应信封偏离 ActionState**（ai12 增补）：004 §11.5 强制约束，当前违反
+5. **P0 LLM Provider 适配器缺失**：当前 `llm_client.py` 仅 OpenAI 兼容 REST，未抽象 Provider 接口。pending-features P5 + ai-allocation.md §5 要求"LLM Provider 适配（OpenAI/百川/本地模型）"
+6. **P0 Prompt 模板管理缺失**：system prompt 硬编码在 main.py，无模板管理。ai-allocation.md §5 要求"模板 CRUD + 参数注入：年级/学科/难度/知识点"
+7. **P0 备课工作流缺失**：pending-features P5 + ai-allocation.md §5 要求"分析学情 → 推荐知识点 → 生成题目 → 教师审核 → 入库"完整工作流，当前仅"生成题目"单步
+8. **P0 用量计费 / 频率限制缺失**：无用量记录（token 消耗）、无频率限制（用户可无限调用 LLM）。ai-allocation.md §5 要求"按用户/按 IP/按 token 消耗"
+
+#### P1 P5 阶段需补齐（ai12 增补）
+
+9. **P1 题目逐字流式生成缺失**：当前 `/ai/chat/stream` 仅支持聊天流式，未实现题目生成的逐字流式（ai-allocation.md §5 "题目逐字生成 + 前端打字机效果"）
+10. **P1 Prompt 模板 CRUD API 缺失**：ai-allocation.md §5 要求"模板 CRUD"，当前无 API
+11. **P1 多维度限流缺失**：ai-allocation.md §5 要求"按用户/按 IP/按 token 消耗"三维度，当前仅设计用户级
+12. **P1 测试覆盖率 0%**：无 tests/ 目录
+13. **P1 Dockerfile 单阶段**：未做多阶段构建
+14. **P1 Pydantic 输入验证不完整**：`generate/question` 和 `optimize/expression` 直接接收 query param，无请求体模型
+
+#### P2 P6+ 长期演进（ai12 增补）
+
+15. **P2 PII 脱敏缺失**：学生姓名/家长手机号等写入 prompt 前未脱敏，存在数据泄露风险
+16. **P2 Prompt 注入防御缺失**：用户输入未 sanitize，存在 SQL/HTML 注入风险
+17. **P2 输出内容审核缺失**：LLM 输出未过滤敏感词，存在生成不当内容风险
+18. **P2 生成结果质量门禁缺失**：题目未校验题型/答案/解析合理性，可能生成不可用题目
+19. **P2 多租户用量配额缺失**：无学校/年级级配额，单一学校可能耗尽预算
+20. **P2 评估框架缺失**：无 LLM-as-judge / 人工评估机制，无法持续提升生成质量
+21. **P2 RAG 语义检索缺失**：当前仅基于 content 知识点查询，无向量库语义检索
+22. **P2 多模态支持缺失**：未规划图片/音频题目生成（数学几何题/英语听力题）
+23. **P2 语义缓存缺失**：仅 hash 缓存，无基于 embedding 相似度的语义缓存
+24. **P2 A/B 测试基础设施缺失**：无法对比不同 prompt/模型的效果
+25. **P2 RLHF 数据收集缺失**：无教师反馈（采纳/拒绝/修改）记录机制
+26. **P2 长运行工作流持久化缺失**：备课工作流的"教师审核"步骤可能跨数小时/天，无持久化机制
+
+---
+
+## 阶段 1 待 coord 交叉审查的跨模块契约对齐项
+
+### ai06 初稿提请项（已在 coord 交叉审查报告中仲裁）
+
+| #   | 议题                                            | 涉及方                                         | 仲裁结论                                                                                                                                                             |
+| --- | ----------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2   | **ai 是否发布 `edu.insight.ai.usage` 用量事件** | ai → data-ana                                  | ✅ 已仲裁：coord 补登 topic，见 004 §7.2；events.proto 待补 `AIUsageEvent` message（coord 负责）                                                                     |
+| 3   | **data-ana / ai 是否需要实现 gRPC server**      | data-ana / ai ← teacher-bff / student-bff / ai | ✅ 已仲裁：分阶段启用，见 004 §4.2 gRPC 启用阶段矩阵；ai 在 P5 启用（含 StreamChat）                                                                                 |
+| 6   | **ai 备课工作流是否引入 Temporal**              | ai + coord                                     | ⚠️ 部分仲裁：004 §2.3 列出 Temporal 用于"工作流编排（考试生命周期、AI 编排）"，P3 已引入试点；ai12 建议简单工作流用 BackgroundTasks，长运行评估 Temporal，待 P6 决策 |
+| 7   | **LLM Provider 切换的配置化**                   | ai + coord                                     | ⚠️ 部分仲裁：ai12 设计 `LLMProvider` 抽象 + 配置化路由（按 model 名路由）；本地模型走 Ollama REST API；待 P6 评估是否提取到 shared-py                                |
+
+### ai12 新增提请项（待 coord 仲裁）
+
+| #   | 议题                                                                                                  | 涉及方                | ai12 建议                                                                                                      |
+| --- | ----------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
+| A1  | **ai gRPC 端口 50058**：004 §1.2 端口矩阵需补登                                                       | ai + coord            | ai HTTP 3008 + gRPC 50058（HTTP+10050 规则）；提请 coord 同步 004 §1.2 + 全局端口表 `infra/port-allocation.md` |
+| A2  | **ai.proto 待补全**：备课工作流 RPC + 题目逐字流式 RPC + ChatRequest/GenerateQuestionRequest 字段扩展 | ai + coord            | 见 §3.2 ai12 增补待补全项；建议 coord 在 P5 启动前完成 proto 升级到 v1 完整版                                  |
+| A3  | **events.proto 待补 `AIUsageEvent` message**：004 §7.2 已确认 topic 但 proto 未定义                   | ai + coord + data-ana | 协调 data-ana ai11 共同定义 payload schema；ai12 已在 02-architecture-design.md §5.2 给出建议 schema           |
+| A4  | **iam `GetEffectiveDataScope` gRPC RPC**：ai 需查询用户 DataScope 用于多租户配额校验                  | ai + coord + iam      | coord 已仲裁 P4 补全（§15.3 #5），ai12 在 P5 实施时调用                                                        |
+| A5  | **响应信封偏离 ActionState 强制整改**：004 §11.5 已约束，ai 当前违反                                  | ai + coord            | P5 实施时必须整改；提请 coord 在 known-issues §2.9 记录                                                        |
+| A6  | **Prompt 模板存储位置**：YAML 文件 vs DB                                                              | ai + coord            | ai12 建议 P5 用 YAML 文件（`services/ai/src/ai/prompts/*.yaml`），P6+ 评估迁移 DB；与 ai06 初稿一致            |
+| A7  | **长运行工作流持久化**：备课工作流"教师审核"步骤可能跨数小时/天                                       | ai + coord            | ai12 建议 P5 用 Redis 暂存（短期 24h TTL）+ BFF 编排审核状态；P6 评估迁移 Temporal 或自建 workflow_state 表    |
+| A8  | **多模态支持规划**：图片/音频题目生成（数学几何/英语听力）                                            | ai + coord            | ai12 建议 P5 仅文本，P6+ 评估多模态；proto v2 预留 `multimodal_content` 字段                                   |
+| A9  | **评估框架归属**：LLM-as-judge 在 ai 内部 vs 独立 evaluation 服务                                     | ai + coord            | ai12 建议 P5/P6 在 ai 内部实现（避免服务拆分过早）；P7+ 评估独立                                               |
+| A10 | **RLHF 数据收集**：教师反馈事件 `AIFeedbackRecorded` 是否新增 topic                                   | ai + coord + data-ana | ai12 建议 P6+ 评估；topic: `edu.insight.ai.feedback`；data-ana 落 ClickHouse 供未来 fine-tune                  |
+
+---
+
+**AI Agent**: ai12 (ai) ← ai06（初稿）
+**Branch**: 单仓库并行模式（直接提交 main）
+**Coordinator**: coord-ai