AGENTS.md

# AGENTS.md - 仓库执行约束

## 1. 核心原则

- 全程使用中文沟通，结论必须基于代码、测试、构建、运行结果或 git 证据。
- 禁止为“先跑通”添加静默降级、隐藏回退、伪造成功路径或吞没异常后继续。
- 先保证行为等价和真实失败可见，再做性能、体验或结构优化。
- 每次只处理一个明确任务，先确认边界，再修改，再做最小充分验证。
- 不顺手修正无关问题；发现范围外问题时单独记录，不混入当前任务。
- 代码、注释、日志字符串和 Markdown 不使用 Emoji 或装饰性 Unicode 符号。

## 2. 项目事实

- 项目是 Next.js 16 + React 19 的本地图片服务，默认端口 `4783`。
- 包管理工具是 `npm`，锁文件是 `package-lock.json`。
- Node 版本要求是 `>=22.15.0`。
- 主要页面入口是 `src/app/page.tsx`。
- 图片 API 入口是 `src/app/api/images/route.ts`。
- Agent API 位于 `src/app/api/agent/`。
- 图片请求校验位于 `src/lib/image-request-utils.ts`。
- 多渠道路由位于 `src/lib/channel-router.ts` 和 `src/lib/server-channel-router.ts`。
- 仓库自带 agent skill：`skills/gpt-image-playground-agent/SKILL.md`。

## 3. 任务工作流

### 3.1 任务来源

- 当前仓库没有独立的 `tasks.md`、`issues.csv` 或等价任务跟踪文件。
- 在未新增任务文件前，以用户当前回合明确指定的单一任务为唯一任务来源。
- 若后续新增任务跟踪文件，任务优先级切换为：任务文件状态 > git 提交证据 > 当前代码事实。

### 3.2 原子任务循环

- 每次只处理一个原子任务，流程固定为：读取上下文 -> 锁定范围 -> 实现或审计 -> 验证 -> 自审 -> 结束任务。
- 修改前先确认影响文件和验证方式。
- 修改后只在当前任务边界内收敛，不并行推进其他需求。

### 3.3 自审要求

- 对照用户给出的验收标准逐条确认。
- 运行最小相关验证，并记录命令与结果。
- 用 `git diff --name-only` 和 `git diff --check` 确认没有范围外改动和明显格式问题。
- 所有验证通过后，才可以声明完成。

### 3.4 Code Review 模式

- 当任务标题或用户指令包含 `[Code Review]` 时，默认进入审计模式，不直接修改业务代码，除非用户明确要求修复。
- 审计依据依次为：目标 diff、`AGENTS.md`、任务验收标准、相关测试和构建结果。
- 当前仓库没有 `docs/review_checklist.md`；如需输出审计报告，放在 `docs/reviews/CR-{ID}.md`，目录不存在时按需创建。

## 4. 质量红线

### 4.1 开发边界

- 禁止为迎合测试或截图而硬编码业务结果。
- 只修改完成当前任务所必需的文件。
- 不保留无用兼容分支、死代码或无法解释的兜底逻辑。
- 外部输入失败必须显式报错，不能静默改写后继续。

### 4.2 工程基线

- 遵循 SOLID、DRY、关注点分离和 YAGNI。
- 命名清晰，抽象务实，只在不直观处补简洁注释。
- 核心逻辑优先放在 `src/lib/`，UI 组件保持展示职责清晰。
- 能通过纯函数或依赖注入表达的逻辑，不要直接绑死到全局状态或具体实现。

### 4.3 安全基线

- 严禁在源码、文档示例、测试快照里写入真实 API Key、token 或密码。
- 自定义 API URL 和自定义 API Key 必须成对出现，避免服务端密钥被转发到未知地址。
- 所有用户输入、上传文件、URL、文件名、尺寸、格式和上游响应都要在边界处校验。
- 仅当密钥被写入仓库文件时，才视为泄漏事故；会话内临时调试输入不算源码泄漏。

## 5. 测试与验证

### 5.1 测试布局

- 当前仓库测试采用同目录 `node:test` 方案，命名为 `*.test.ts`。
- 测试文件主要位于 `src/lib/**/*.test.ts`、`src/app/api/**/*.test.ts`。
- 新增测试优先沿用现有同目录模式，不额外引入第二套测试目录约定。

### 5.2 验证基线

- 提交前最小基线是：

```bash
npm run install-scripts:check
npm run npm-install-policy:check
npm run dependencies:check
npm test
npm run lint
npm run format:check
npm run lint:scripts
npm run build
git diff --check
```

- 若只改动局部模块，先跑最小相关测试；准备收尾时再跑上述全量基线。
- 不能用“看起来没问题”代替自动化验证；不能把单项通过误报为整体通过。

### 5.3 数据与契约校验

- 处理 JSON、multipart、流式响应、数据库记录或 Agent API 合同时，必须明确字段含义、类型和分支语义。
- 若逻辑依赖真实 Postgres 行为、类型转换或驱动序列化，至少补充离线契约测试；若未连真实库，必须明确说明“仅覆盖语义，未覆盖真实数据库行为”。
- 不能把 `npm test` 全绿直接表述为线上、Docker 或真实上游接口已通过。

## 6. 环境与运行

### 6.1 本地开发

```bash
npm run install-scripts:check
npm run npm-install-policy:check
npm ci --strict-allow-scripts
npm run dependencies:check
npm run dev
```

- 本地默认访问地址是 `http://localhost:4783`。
- `npm run dev` 使用 Turbopack，并固定端口 `4783`。

### 6.2 Docker 验证

```bash
docker compose up -d --build
```

- 需要容器验证时，以最新代码重建后再做页面或接口检查。
- 不能只看容器启动成功就声称验证完成，必须补至少一项真实访问或真实请求证据。

### 6.3 常用检查

```bash
npm test
npm run lint
npm run format:check
npm run lint:scripts
npm run build
git diff --check
```

## 7. 提交与文件卫生

- 每个原子任务单独提交，提交信息应直接说明本次改动。
- 提交前确认 `git diff --name-only` 只包含任务范围内文件。
- 默认不提交临时产物、日志、缓存、截图、生成图片、个人配置或本地数据库文件，除非任务明确要求。
- 修改 README、CHANGELOG、版本号或发布产物定义时，必须同时核对 `package.json`、`package-lock.json` 和相关文档口径。

## 8. 仓库内文档与技能

- 开始任务前，先检查仓库内是否已有相关文档或 skill 可复用。
- 当前已知技能入口是 `skills/gpt-image-playground-agent/SKILL.md`，命中 Agent API 调用场景时必须先阅读。
- 阶段性计划当前位于 `docs/superpowers/plans/`；它们只用于补充上下文，不替代代码事实和用户当前任务。

## 9. 历史踩坑记录

- 重要踩坑应记录现象、根因、修复方式和相关文件或提交。
- 当前仓库若需要新增长期审计或复盘文档，统一放在 `docs/reviews/`。