zwt13703
59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# AGENTS.md — doc-forge
|
||
|
||
你正在参与一个外包项目，客户需要一套完整的 AI 文档模板生成系统。
|
||
|
||
## 你的角色
|
||
全栈开发 AI 助手，负责生成 Vue 3 + Ant Design Vue 前端代码和 Python FastAPI 后端代码。
|
||
|
||
## 基础设施
|
||
|
||
### MySQL
|
||
- 数据库名：`doc_forge`，字符集 `utf8mb4`
|
||
- 异步驱动：`asyncmy`
|
||
- 连接池：pool_size=10, max_overflow=20
|
||
- 本地开发：`docker-compose up mysql`
|
||
- DDL 见 `init.sql`
|
||
|
||
### MinIO（对象存储）
|
||
- 三个 bucket：`doc-forge-templates`（模板）/ `doc-forge-uploads`（参考文件）/ `doc-forge-outputs`（导出文档）
|
||
- 文件路径规则：`{bucket}/{YYYYMMDD}/{uuid}.{ext}`
|
||
- 预签名 URL 用于前端下载，过期 1 小时
|
||
- 本地开发：`docker-compose up minio`，Console http://localhost:9001
|
||
- SDK：`from minio import Minio`，客户端在 `services/minio_client.py`
|
||
|
||
### Docker
|
||
- `docker-compose up -d mysql minio` 启动开发依赖
|
||
- `docker-compose up backend web` 启动全栈
|
||
|
||
## 通讯协议
|
||
- 所有 API 响应格式：`{ code: 0, data: {...}, message: "ok" }`
|
||
- 错误响应：`{ code: -1, message: "错误描述" }`
|
||
- 分页响应：`{ code: 0, data: { items: [], total: N, page: 1, page_size: 20 } }`
|
||
|
||
## 必须遵守的规则
|
||
|
||
1. **AI 输出格式** — AI 必须返回 JSON，不得返回纯文本。前端解析 `content` 数组，按 type 分段渲染。
|
||
2. **Word 导出** — 严禁重新生成文档。从 MinIO 拉取原始模板，只替换对应位置的文本节点。
|
||
3. **段落边界** — 只认 Word 标题样式（Heading）。不要尝试用正则或关键词判断段落。
|
||
4. **API Key 安全** — 所有 API Key 用 `cryptography.fernet.Fernet` 加密存储，前端只展示脱敏字符串。
|
||
5. **并发控制** — 段落生成使用 `asyncio.gather` + `Semaphore`，单文档最大并发 5。
|
||
6. **文件存储** — 所有用户文件存 MinIO，后端本地只做临时缓存。
|
||
7. docs/规范与约束/开发规范.md
|
||
8. docs/需求与设计/02-模板格式规范.md
|
||
|
||
## 段落配置字段
|
||
每个 paragraph 包含：
|
||
- `edit_mode`: 'manual' | 'ai'
|
||
- `model_id`: int | null（null 表示使用系统默认模型）
|
||
- `need_prompt`: boolean + `prompt_text`: string
|
||
- `need_file`: boolean + `file_note`: string（备注提示上传什么文件）
|
||
- `output_format`: 'text' | 'table' | 'mixed' | 'chart'
|
||
|
||
## 容易踩的坑
|
||
- python-docx 中文字体名在 `run.fonts.eastAsia`，不是 `run.fonts.name`
|
||
- Ant Design Vue 4.x 的 modal 使用 `v-model:open`，不是 `v-model:visible`
|
||
- SSE 事件流要用 `sse-starlette` 的 `EventSourceResponse`
|
||
- asyncio 中不能混用同步的 openpyxl，Excel 解析放在线程池执行 (`run_in_executor`)
|
||
- MinIO SDK 是同步的，用 `run_in_executor` 包装，不要直接 in asyncio
|
||
- asyncmy 连接 MySQL 需要 `charset=utf8mb4`，不然中文会乱码
|