# AGENTS.md

本文件适用于整个仓库。修改子目录前，还应遵守该子目录中更具体的 `AGENTS.md`（如后续存在）。

## 项目定位

- 产品名称：梦畅AIGC
- 项目类型：AIGC 内容生成 Web 平台
- 仓库模式：前后端单仓库

## 技术约束

- `apps/web-vue/`：Vue 3 + TypeScript 主前端，内嵌 React + TypeScript 子模块。
- `services/api/`：Spring Boot 模块化单体主业务后端，JDK 21，Maven。
- `services/agent/`：Python 3.11+ Agent 进程，使用 LangChain 和 LangGraph，由 Java 主业务后端调用。
- Maven 坐标约定：`groupId=mc`、`artifactId=mcaigc`。
- Java 基础包名约定：`mc.mcaigc`。
- PostgreSQL 是主数据库，Redis 用于缓存，MinIO 用于对象存储。
- `infra/docker/` 只承载本地开发环境相关文件。

### Java DDD 模块

- `services/api/mcaigc-domain/`：领域模型和领域端口，不依赖 Spring。
- `services/api/mcaigc-application/`：应用服务和用例编排，依赖领域层。
- `services/api/mcaigc-infrastructure/`：数据库、缓存、对象存储等技术适配，依赖领域层。
- `services/api/mcaigc-interfaces/`：HTTP 接口、DTO 和参数适配，依赖应用层。
- `services/api/mcaigc-boot/`：Spring Boot 启动模块，组装各层并提供可运行入口。

具体业务服务出现后，应在此骨架内按业务边界拆分模块，不跨领域直接引用内部实现。

## 修改原则

1. 目录、源代码标识符和配置键使用英文；项目文档使用中文。
2. React 子模块与 Vue 主应用之间通过明确的公开契约交互，不直接依赖彼此的内部实现。
3. Java 主业务后端负责认证授权、业务 API、业务规则和持久化；Python Agent 负责智能体编排、工具调用和模型交互。
4. 用户和前端不得直接调用 Agent；请求必须先经过 Java 主业务后端认证和授权，再由 Java 调用 Agent。
5. Agent 不建立独立的用户认证体系，不直接修改主业务数据库；需要读写业务数据时通过 Java 主业务后端的公开 HTTP API 完成。
6. Java 与 Agent 通过内部、版本化的 HTTP/JSON 契约通信；用户和前端不得绕过 Java 直接访问 Agent。
7. 后端模块不得绕过既定分层直接访问其他模块内部实现。
8. 原始资料只追加、不覆盖，按 `resources/raw/YYYY/YYYY-MM-DD/` 归档。
9. 不为尚未确认的需求预建模块、依赖或抽象。
10. 修改项目结构、核心技术选型或跨模块契约时，同步更新 `docs/` 中的相关文档。

## 验证要求

- 只运行与改动范围相匹配的最小验证。
- 新增业务代码后，应为关键分支、数据转换和边界条件补充自动化测试。
- 在工具链尚未初始化前，不编造不可执行的构建或测试命令。
- Java 骨架验证：`cd services/api && mvn verify`。
- Agent 骨架验证：安装开发依赖后运行 `cd services/agent && python -m pytest`。
