Files
fruit-pop-googleplay/AGENTS.md
T
2026-11-20 15:13:11 +08:00

55 lines
4.2 KiB
Markdown

# 项目开发规则
## 协作状态机
- 每个新需求默认进入“需求理解、讨论阶段”,不是实施阶段。
- 需求理解阶段允许读取代码、配置、Git 状态、场景数据和资源信息,以便理解需求并制定可靠方案。
- 讨论阶段允许读取代码、配置、Git 状态、场景数据和资源信息,以便理解需求并制定可靠方案。
- 讨论阶段禁止修改、创建、删除、移动或格式化文件;禁止复制资源、安装依赖、保存场景、启动构建以及调用任何会改变项目状态的工具。
- 收到需求后,先完整理解需求和边界,再说明实现方案、取舍、风险、预计修改范围和验证方式。
- 讨论回复结尾必须标记:`当前状态:等待“开始实施”授权`。
- 只有当用户发送一条去除首尾空白后完全等于 `开始实施` 的单独消息时,才进入实施阶段。
- `可以`、`没问题`、`没有异议`、`继续`、`按这个方案`、`确认方案` 等表达都不构成实施授权。
- 不得根据语气、上下文或方案已达成一致而推断用户授权实施。
- 进入实施阶段后,只执行已讨论并获准的范围。需求范围发生实质变化时,重新回到讨论阶段。
- 用户说“先分析”“先讨论”“不要修改”时,始终保持讨论阶段。
## 项目范围
- 这是一个 PinK 工程,使用 TypeScript 和 2D 竖屏界面;项目元数据中的 3d 类型不代表玩法使用 3D。
- 修改必须限定在已获准的功能范围内。
- 除非任务确实需要,否则不要扫描 `node_modules`、`dist` 或大型资源目录。
- 只加载当前任务需要的 Skill,不要预先读取整套 Skill。
- 永久禁止加载、读取或执行 `skill-game-factory` 及任何 Factory 命令或状态工作流;此前已加载的 Factory 指令不适用于本项目。
- `E:\ProjectPhaser\ricochet-circuit` 严格只读:仅可读取源码、包配置或执行只读 Git 命令;禁止修改文件、安装依赖、构建、测试、同步及任何可能写入该目录的命令。
- 保留用户已有修改,不清理或覆盖无关工作区内容。
## PinK 场景与资源
- 使用 PinK 场景、资源及构建工具;场景编辑前明确绑定目标场景。
- 场景通过领域工具创建、修改与保存,不手工编辑 `.scene` 文件。
- 脚本资源通过资源工具创建,后续 TypeScript 逻辑使用文本补丁维护。
- 占位版界面由场景组件生成,符号 ID 与显示分离,后续可替换美术。
- 查询后再修改节点或组件属性,完整写入值类型;完成一批场景修改后保存并复核。
- 操作结果不确定时先查询状态,不盲目重试。保留用户已有场景修改。
- 如果工程连接失效或目标项目错误,停止相关操作并报告阻塞。
## Token 与工具调用控制
- 先形成批量修改计划,再执行工具调用;不要为每个对象分别开启一个工具回合。
- 能通过对象数据、坐标和场景尺寸验证时,不获取截图。
- 每个功能阶段默认最多获取两次截图:必要的修改前基准图和最终验收图。
- 同一张截图最多读取一次,不要重复使用 `view_image` 查看相同图片。
- 不要把图片二进制、Base64、大型完整 JSON 或无关终端输出带入上下文。
- 使用定向搜索和有限输出,不要重复读取已经掌握且没有变化的内容。
- 如果任务明显变成多个独立阶段,完成当前阶段后先总结,再建议新建会话继续。
## 验证
- 依赖和脚本命令统一使用 `pnpm@11.17.0`,根目录维护唯一的 `pnpm-lock.yaml`;当前没有原生子工程,不要创建 npm/yarn 锁文件。
- 首次运行先在当前项目根目录执行 `pnpm install`;依赖构建脚本仅允许 `pnpm-workspace.yaml` 中明确批准的 `esbuild`。
- 本地运行使用 PinK 场景预览;不要假设当前工程包含独立 Web 开发服务器。
- 修改 TypeScript 后运行 `pnpm typecheck`。
- 修改行为逻辑后运行 `pnpm test`。
- 可能影响编译或资源的修改完成后通过 PinK 构建工具构建,未指定平台时使用 `web-mobile`。
- 只执行与本次修改风险相匹配的验证,并报告未执行的命令及原因。