# 必读文档清单

## 核心规划文档

这些文档包含了项目的重要设计决策，所有Agent都应该了解：

### 1. 架构设计文档

- `../../协作机制设计.md` - **必读** - 模块间协作机制、全局上下文、错误处理
- `../../项目脚手架结构.md` - **必读** - 详细的目录结构和文件组织
- `../../模块分工指南.md` - **必读** - 各模块的职责边界和接口定义
- `../../开发规范文档.md` - **必读** - 详细的编码规范和最佳实践

### 2. 业务理解文档

- `../../../README.md` - 项目整体介绍
- `../../../../kaopeilian-frontend/页面与按钮速查.md` - 前端页面框架和功能
- `../../../../kaopeilian-frontend/前后端接口约定.md` - 前后端接口约定

### 3. 质量保证文档

- `../../质量保证机制.md` - 代码审查和测试要求
- `../../统一基础代码.md` - 可复用的代码模板

### 4. 配置管理文档

- `../../配置一致性检查清单.md` - **必读** - 所有需要保持一致的配置项清单
- `../../配置管理使用说明.md` - **必读** - 配置管理工具使用指南和最佳实践

## 使用建议

### 对于每个Agent

1. **开发前必读**：

   - 本目录的 `base_prompt.md`
   - 本目录的 `project_structure.md`
   - `../../协作机制设计.md`
   - `../../模块分工指南.md`
   - `../../配置一致性检查清单.md`
   
2. **开发中参考**：

   - `../../开发规范文档.md`
   - `../../统一基础代码.md`
   - `../../配置管理使用说明.md`
   - 相关模块的接口定义
   
3. **遇到问题时**：

   - 先运行配置检查脚本：`../../../../../check-config.sh`
   - 查看 `../../配置一致性检查清单.md`
   - 参考 `../../配置管理使用说明.md`
   
4. **集成时查看**：

   - 依赖模块的API契约
   - `../../质量保证机制.md`

### 文档引用示例

```markdown
# 在对话中引用
@考培练系统规划/后端开发拆分策略/协作机制设计.md
@考培练系统规划/后端开发拆分策略/模块分工指南.md
@子agent/01-Agent-Auth/prompt.md

我已了解项目的协作机制和模块分工，开始开发Auth模块。
```

## 重要提醒

- 这些文档包含了项目的核心设计理念
- 遵循这些文档可以确保代码的一致性
- 有疑问时优先查阅这些文档而不是自行决定
- 禁止在各模块文档中重复粘贴通用规范，统一通过本目录进行引用，避免信息漂移

## 可复用资产索引（Coze 并入）
- 代码位置
  - 后端（完整可并入）：`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-backend/`
    - 关键文件：`auth.py`（OAuth/JWT 优先，PAT 回退，直连 *.coze.cn）、`main.py`（SSE/卡片/会话/上传/中断）、`config.py`/`local_config.py`（本地/环境配置）。
    - 目标映射：
      - → `kaopeilian-backend/app/services/ai/coze/{client.py,service.py,exceptions.py,models.py}`
      - → `kaopeilian-backend/app/api/v1/coze_gateway.py`
  - 前端（可快速接入或重写）：`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-frontend/`
    - 页面：`src/pages/{NewChat,Exam,Training}`
    - Store：`src/stores/{NewChatStore,ExamStore,TrainingStore}.ts`
    - API：`src/server/{api.ts,global.ts}`（SSE/中断/上传）
    - 目标策略：
      - 快速：以子应用挂载 `/ai-chat/*`；
      - 稳定：迁移为 Vue3 + Pinia，复用 SSE/卡片渲染逻辑。
- 配置项（本地/环境变量）
  - `COZE_API_BASE`、`COZE_WORKSPACE_ID`、`COZE_API_TOKEN`
  - `COZE_OAUTH_CLIENT_ID`、`COZE_OAUTH_PUBLIC_KEY_ID`、`COZE_OAUTH_PRIVATE_KEY_PATH`
  - 建议：生产关闭“开发用 PAT 获取”，统一 `Bearer` 鉴权，设置 `NO_PROXY=localhost,127.0.0.1,api.coze.cn,.coze.cn`。
- 参考说明
  - 根目录：`配置说明.md`、`README.md`（已含运行与映射说明）
  - 并入后务必以各模块 `api_contract.yaml` 为准，旧路由通过网关短期兼容，按里程碑收敛。