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 验证基线

• 提交前最小基线是：

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 本地开发

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 验证

docker compose up -d --build

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

6.3 常用检查

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/。