998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
# 必读文档清单
|
||
|
||
## 核心规划文档
|
||
|
||
这些文档包含了项目的重要设计决策，所有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` 为准，旧路由通过网关短期兼容，按里程碑收敛。
|