gpt_image_playground: Instructions file for Codex

Agent Instructions for gpt-image-playground

本文件定义 AI 编码助手在此仓库中应遵循的工作方式。

项目概况

• React 19 + Vite + TypeScript 前端应用，使用 Zustand 状态管理、Tailwind CSS 样式。
• 源码在 src/，构建产物由 Vite 生成，不要手动编辑 dist/。
• 包管理器为 npm（有 package-lock.json），不要使用 yarn 或 pnpm。

常用命令

操作	命令
安装依赖	npm install
开发服务器	npm run dev
构建	npm run build
运行测试	npm test
监听测试	npm run test:watch
生成第三方许可清单（需要先安装 cargo-about：cargo install cargo-about --version 0.9.2 --locked --features cli）	npm run notices

• 测试使用 Vitest，已有多个 *.test.ts 文件。
• 不要新增 lint/formatter 配置文件，除非明确要求。

代码风格（强制）

简单优先

写出能工作的最简代码。少抽象、少包装。有疑问就内联。

• 不要为单次使用的 1-5 行逻辑创建独立函数，直接内联。
• 函数只有在多处调用且逻辑非平凡时才值得提取。
• 不要引入项目中不存在的设计模式或架构层。

完整实现

• 不要留 // TODO: implement later、// ... 或 stub 函数。
• 如果不确定某个细节，给出完整的最佳猜测实现。错误但完整的代码优于正确但残缺的骨架。

跟随现有风格

这是最高优先级规则。修改文件时，遵循该文件及周围代码的已有风格。

格式

• 2 空格缩进。
• 单引号（'hello'）。
• 无分号。
• 箭头函数始终加括号：(x) => x。
• 行宽不做硬性限制，但尽量保持可读。

TypeScript

• 使用 ESM import，const 优先，永远不用 var。
• Target ES2020（见 tsconfig.json）。
• 优先早返回，避免深层嵌套和 else 链。
• 尽量避免 any；需要时保持局部化。
• 利用类型推断，不写多余的类型注解。
• 共享类型放 src/types.ts，局部类型放文件顶部。

命名

• PascalCase：组件、类型、接口。
• camelCase：函数、变量、参数。
• UPPER_SNAKE_CASE：模块级常量。
• 文件名小写驼峰：apiProfiles.ts、maskPreprocess.ts。
• 局部变量优先短名：ctx、el、msg、idx、opts、err。多词名仅在单词不够清晰时使用。

解构

避免无必要的解构。优先点号访问以保留上下文。

// 好
profile.baseUrl
opts.settings

// 避免
const { baseUrl } = profile
const { settings } = opts

例外：React 组件 props、hooks 返回值、函数参数解构是可以的。

控制流

// 好：早返回
function getPreset(name: string) {
  if (!name) return defaultPreset
  return presets.find((p) => p.name === name)
}

// 避免：多余的 else
function getPreset(name: string) {
  if (!name) return defaultPreset
  else return presets.find((p) => p.name === name)
}

变量

优先 const，用三元或早返回代替 let 重赋值。

// 好
const params = hasInputImages
  ? { ...baseParams, image: inputImages }
  : baseParams

// 避免
let params
if (hasInputImages) params = { ...baseParams, image: inputImages }
else params = baseParams