zwt13703
2.8 KiB
2.8 KiB
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 } }
必须遵守的规则
- AI 输出格式 — AI 必须返回 JSON，不得返回纯文本。前端解析
content数组，按 type 分段渲染。 - Word 导出 — 严禁重新生成文档。从 MinIO 拉取原始模板，只替换对应位置的文本节点。
- 段落边界 — 只认 Word 标题样式（Heading）。不要尝试用正则或关键词判断段落。
- API Key 安全 — 所有 API Key 用
cryptography.fernet.Fernet加密存储，前端只展示脱敏字符串。 - 并发控制 — 段落生成使用
asyncio.gather+Semaphore，单文档最大并发 5。 - 文件存储 — 所有用户文件存 MinIO，后端本地只做临时缓存。
- docs/规范与约束/开发规范.md
- docs/需求与设计/02-模板格式规范.md
段落配置字段
每个 paragraph 包含：
edit_mode: 'manual' | 'ai'model_id: int | null（null 表示使用系统默认模型）need_prompt: boolean +prompt_text: stringneed_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，不然中文会乱码