# Agent-Coze 提示词（极简版）

## 必读引用
@子agent/00-通用基础/base_prompt.md
@子agent/00-通用基础/essential_docs.md
@考培练系统规划/后端开发拆分策略/模块分工指南.md
@考培练系统规划/后端开发拆分策略/协作机制设计.md

## 你的角色
- 本模块职责：封装 Coze 客户端（会话/消息/流式），支撑陪练与课程对话
- 依赖模块：Auth
- 对外输出：课程对话与陪练网关 API（供前端与第三方解耦）

## 交付内容
- 代码：`app/services/ai/coze/` 下客户端与服务；`app/api/v1/` 网关路由
- 契约：本目录 `api_contract.yaml`（OpenAPI 3.0）
- 文档与测试：`checklist.md` 全通过，单元测试覆盖率 ≥ 80%

## 验收标准（最小集）
- API 与 `api_contract.yaml` 一致并通过基本集成测试
- 认证/权限依赖正常（读写需登录）
- 输入校验、统一异常、结构化日志符合通用规范

## 可复用资产与迁移要点
- 后端可复用（`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-backend/`）
  - 认证封装：`auth.py` 的 `CozeAuthManager`（优先 JWT，fallback PAT；自动设置 `NO_PROXY` 直连 `*.coze.cn`）。建议直接复用到 `app/services/ai/coze/client.py` 或在依赖注入处统一获取 `Coze` 客户端。
  - 流式聊天与卡片输出：`main.py` 中 SSE 事件流（`conversation.message.delta/completed` 等）及对 `card_type` 的检测（将 `content_type` 标识为 `card`）可原样迁移，支撑动态考题与课程对话的“卡片”富结果。
  - 会话管理与上传：`/api/conversations` 创建/删除、`/agent/v1/cozechat/create-conversation` 兼容端点、`/agent/v1/cozechat/upload-file` 文件上传，均可作为本模块网关能力的底层实现。
  - 兼容端点保留策略：现有 `/agent/v1/cozechat/*` 可经由本模块网关路由转发，逐步收敛至 `api_contract.yaml` 形态。
- 网关映射（旧 → 新）
  - 课程对话创建：旧 `POST /api/conversations` 或 `GET /agent/v1/cozechat/create-conversation` → 新 `POST /api/v1/course-chat/sessions`
  - 陪练会话创建：旧 `POST /agent/v1/cozechat/create-conversation` → 新 `POST /api/v1/training/sessions`
  - 陪练会话结束：旧无统一端点 → 新 `POST /api/v1/training/sessions/{id}/end`
  - 可按需扩展：`POST /api/v1/course-chat/messages`（发送/流式）、`WS /ws/v1/*`（文本/语音）。若扩展，请同步更新本目录 `api_contract.yaml`。
- 前端可复用（`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-frontend/`）
  - 页面与逻辑：`src/pages/Training/*`（语音/文本陪练）、`src/pages/NewChat/*`（通用对话）、`src/pages/Exam/*`（动态考题）可直接参考；保留 SSE 解析与“卡片”渲染分支。
  - API 封装：`src/server/api.ts`、`src/server/global.ts` 中的会话/聊天/上传请求与中断逻辑；迁移时仅需切换到本模块网关的新端点。
  - Store 模式：`src/stores/*Store.ts` 的流式拼接、滚动、失败重试与中断处理可复用。
- 配置与安全
  - 环境变量：复用 `COZE_API_BASE`、`COZE_WORKSPACE_ID`、`COZE_API_TOKEN` 或 OAuth 三件套（`COZE_OAUTH_CLIENT_ID`、`COZE_OAUTH_PUBLIC_KEY_ID`、`COZE_OAUTH_PRIVATE_KEY_PATH`）。
  - 认证：对外统一走 Auth 的 Bearer 鉴权；前端“开发用 PAT 获取”接口仅限本地调试，生产关闭。
- 稳定性与观测
  - 为外部调用加入限流/超时/重试与断路器；将 Coze 错误映射为统一异常；输出结构化日志与成功率/延迟/错误率指标（按通用规范）。

## 整合并入系统（当前阶段）
- 后端并入（立即执行）
  - 新建 `app/services/ai/coze/{client.py,service.py,exceptions.py,models.py}`，迁移认证（OAuth 优先、PAT 回退、`NO_PROXY` 直连）与 SSE/卡片/中断实现。
  - 新建 `app/api/v1/coze_gateway.py`，按本目录 `api_contract.yaml` 提供路由；短期保留 `/agent/v1/cozechat/*`、`/api/*` 兼容转发。
  - 统一鉴权（Bearer）、环境变量与结构化日志；将 SDK 错误映射为统一异常；外部调用加限流/超时/重试。
- 前端接入（立即执行）
  - 将 `coze-chat-frontend` 以子应用挂载到主站（如 `/ai-chat/*`），复用现有页面与 Store；仅切换 API 基址到新网关，复用主站登录态。
  - 验证 SSE 流消息、卡片消息渲染与“中断”动作在本地 `localhost` 正常工作。
- 验收
  - 新网关端点可用并通过基本集成测试；子应用集成后在本地环境稳定运行。
