Edu/services/ai/docs/01-understanding.md

模块理解确认书 — ai

AI 标识：ai12（复核与长期演进接手）← ai06（初稿，2026-07-09） 负责模块：ai（P5）— 按 ai-allocation.md §3.2 v1.0 最新分配，ai 由 ai12 专责 语言：Python 3.12+ / FastAPI 0.115+ 阶段：架构设计外包 · 阶段 1（全局理解，ai06 初稿 + ai12 长期演进复核） 日期：2026-07-09（ai06 初稿）/ 2026-07-09（ai12 复核与补充） 关联文档：ai-allocation.md、004 架构影响地图、pending-features.md、coord 交叉审查报告、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	✅ 已读
2	MIGRATION_GUIDE.md	✅ 已读
3	004 架构影响地图	✅ 已读（重点 §1.2/§4.1/§4.2/§7.2/§9.3/§11.5/§12.2/§15）
4	pending-features.md	✅ 已读（重点 P5 沟通与 AI 阶段）
5	project_rules.md	✅ 已读（workspace 规则，重点 §3.6 Python/§6 事件驱动/§9 问题记录/§10 AI 工作流程）
6	coding-standards.md	✅ 已读（重点 §4 Python 规范）
7	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 交叉审查报告	✅ 已读（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）
  • 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）：

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）

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）
• 配置：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_* 错误码清单
• logger / metrics / tracer 三支柱（已具备）
• /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 请求/响应模型
• 配置通过 pydantic-settings 管理（已具备）
• 异步优先（httpx async + AsyncGenerator stream）
• 类型注解强制（已基本符合，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