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.设计规格文档
This commit is contained in:
SpecialX
108
docs/architecture/issues/contracts/ai_contract.md
Normal file
108
docs/architecture/issues/contracts/ai_contract.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# ai 对接契约
|
||||
|
||||
> 负责人：ai12
|
||||
> 关联：[matrix.md](./matrix.md)、[ai.proto](../../../packages/shared-proto/proto/ai.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
|
||||
|
||||
---
|
||||
|
||||
## §1 我提供什么（对外接口）
|
||||
|
||||
### 1.1 gRPC 接口（如有）
|
||||
|
||||
| Service | RPC | 请求 | 响应 | 端口 |
|
||||
| --------- | ---------------------- | ----------------------------- | ------------------------ | ----- |
|
||||
| AiService | Chat | ChatRequest | ChatResponse | 50057 |
|
||||
| AiService | StreamChat | ChatRequest | stream ChatChunk | 50057 |
|
||||
| AiService | GenerateQuestion | GenerateQuestionRequest | GeneratedQuestion | 50057 |
|
||||
| AiService | OptimizeExpression | OptimizeExpressionRequest | OptimizedExpression | 50057 |
|
||||
| AiService | GenerateLessonPlan | GenerateLessonPlanRequest | LessonPlan | 50057 |
|
||||
| AiService | StreamGenerateQuestion | StreamGenerateQuestionRequest | stream GeneratedQuestion | 50057 |
|
||||
|
||||
### 1.2 HTTP 端点（如有）
|
||||
|
||||
无对外 HTTP 端点，仅 gRPC（含 2 个 Server Streaming RPC：StreamChat / StreamGenerateQuestion）。
|
||||
|
||||
### 1.3 GraphQL schema（如 BFF）
|
||||
|
||||
不适用。
|
||||
|
||||
### 1.4 Kafka 事件发布（如有）
|
||||
|
||||
| Topic | Event | 消费方 |
|
||||
| ------------------- | ---------------------------------------------------------------------------------------- | -------- |
|
||||
| edu.ai.usage.events | AIUsageEvent（operation: chat/generate_question/optimize_expression/lesson_preparation） | data-ana |
|
||||
|
||||
> 注：AIUsageEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
|
||||
|
||||
### 1.5 错误码前缀
|
||||
|
||||
`AI_`（如 AI_PROVIDER_UNAVAILABLE、AI_TOKEN_LIMIT_EXCEEDED、AI_CONTENT_FILTERED）
|
||||
|
||||
---
|
||||
|
||||
## §2 我消费什么（依赖上游）
|
||||
|
||||
### 2.1 gRPC 调用（同步）
|
||||
|
||||
| 被调用方 | Service.RPC | 用途 | mock 策略 |
|
||||
| --------------- | -------------------------------------- | ---------------------------- | ----------------------------------------------------------- |
|
||||
| content (ai09) | KnowledgeGraphService.GetPrerequisites | 生成题目时获取知识点前置依赖 | content 就绪前使用本地知识点 stub（固定 3 个前置知识点） |
|
||||
| content (ai09) | QuestionService.SearchQuestions | 备课时检索同类题目参考 | content 就绪前返回空列表 |
|
||||
| data-ana (ai11) | AnalyticsService.GetStudentWeakness | 个性化出题时获取学生薄弱点 | data-ana 就绪前使用本地薄弱点 stub（固定 2 个 weak_points） |
|
||||
|
||||
### 2.2 Kafka 事件订阅（异步）
|
||||
|
||||
| Topic | Event | 发布方 | mock 策略 |
|
||||
| ---------------------------------- | ------------------- | -------------- | -------------------------------------- |
|
||||
| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09) | content 就绪前不订阅，使用内置知识点表 |
|
||||
| edu.content.question.events | QuestionEvent | content (ai09) | content 就绪前忽略 |
|
||||
|
||||
### 2.3 HTTP 调用（如有）
|
||||
|
||||
| 被调用方 | Method.Path | 用途 | mock 策略 |
|
||||
| -------------------------------- | ------------------------- | ------------------ | ------------------------------------------------------------------ |
|
||||
| LLM Provider（OpenAI/百川/本地） | POST /v1/chat/completions | 调用大模型生成内容 | 开发期使用本地 mock server 返回固定 ChatResponse，不消耗真实 token |
|
||||
|
||||
---
|
||||
|
||||
## §3 就绪信号
|
||||
|
||||
### 3.1 我依赖的上游就绪标志
|
||||
|
||||
- [ ] content gRPC 50054 启用（ai09）—— 知识点维度 + 题库检索
|
||||
- [ ] edu.content.knowledge_point.events topic 有事件发布（ai09）
|
||||
- [ ] data-ana gRPC 50055 启用（ai11）—— 学生薄弱点（可选，ai 可先独立运行）
|
||||
|
||||
### 3.2 我的就绪标志（供下游消费）
|
||||
|
||||
- [ ] ai gRPC 50057 启用（HealthService.Check 返回 SERVING）
|
||||
- [ ] AiService.Chat / StreamChat 可调用（含流式响应）
|
||||
- [ ] AiService.GenerateQuestion / StreamGenerateQuestion 可调用
|
||||
- [ ] AiService.GenerateLessonPlan 可调用（P5 补全）
|
||||
- [ ] AiService.OptimizeExpression 可调用
|
||||
- [ ] edu.ai.usage.events topic 可发布（供 data-ana 统计 AI 用量）
|
||||
|
||||
---
|
||||
|
||||
## §4 Mock 策略
|
||||
|
||||
### 4.1 我提供的 mock
|
||||
|
||||
在 ai 真实服务就绪前，为下游（teacher-bff）提供以下 mock：
|
||||
|
||||
- **gRPC mock**：使用 grpc-mock 拦截 50057 端口
|
||||
- AiService.Chat 返回固定 ChatResponse（content="这是 AI 助手的模拟回复"）
|
||||
- AiService.StreamChat 返回固定流（3 个 ChatChunk，最后一个 done=true）
|
||||
- AiService.GenerateQuestion 返回固定 GeneratedQuestion（question/answer/explanation）
|
||||
- AiService.GenerateLessonPlan 返回固定 LessonPlan（3 个 LessonSection）
|
||||
- AiService.StreamGenerateQuestion 返回固定流（2 个 GeneratedQuestion）
|
||||
- **Kafka mock**：ai 就绪前不发布真实 AIUsageEvent，data-ana 仪表盘 AI 用量显示"暂无数据"
|
||||
|
||||
### 4.2 我消费的 mock
|
||||
|
||||
在真实上游就绪前，ai 使用以下 mock：
|
||||
|
||||
- **LLM Provider mock**：本地启动 mock server，POST /v1/chat/completions 返回固定 JSON（不消耗真实 token，不产生费用）
|
||||
- **content 知识点**：内置固定知识点表（数学 20 个知识点 + 前置依赖关系），不依赖 content gRPC
|
||||
- **data-ana 薄弱点**：内置固定学生薄弱点（2 个 weak_points），不依赖 data-ana gRPC
|
||||
- **事件订阅**：不订阅 content 事件，知识点维度表静态
|
||||
Reference in New Issue
Block a user