starraid/AGENTS.md

AGENTS.md — Star Raid 工作区

这个工作区只做一个项目：Star Raid（像素风竖版弹幕射击游戏）。 无关项目已移至 ~/Desktop/测试1，不要在这里新建其他项目的文件。

项目概述

• 客户端：纯 HTML5 Canvas + 原生 JavaScript，无构建、无依赖、无框架
• 服务端：零 npm 依赖 Node 原生（node:http + node:sqlite，要求 Node≥22.5），SQLite 存储
• 240×320 像素画布，竖版弹幕射击（主武器/副武器/僚机/Boss 战/Boss Rush 模式）
• 账号系统：注册/登陆（用户名+邮箱+密码）、大厅排行榜 Top100、图鉴收集点亮同步
• 游戏本体在 star-raid/ 子目录，后端在 star-raid/server/，部署见 star-raid/DEPLOY.md

常用命令

cd star-raid

# 语法检查（每次改完 JS 必须跑；server/ 也要查）
for f in js/*.js server/*.js; do node --check "$f" || echo "FAIL $f"; done

# 启动完整版（游戏+后端，Node≥22.5，自动读取 star-raid/.env）
node server/server.js   # 或 npm start；访问 http://localhost:8643
# 注意：8643 现由 node server 占用；旧 python http.server 试玩方式已废弃
# 数据库：默认 ~/.starraid/starraid.db（源码树之外，.env 的 DATA_DIR 可改）
# 警告：WAL 模式，备份/迁移库文件前必须停服或 wal_checkpoint，直接拷主库会丢数据

# Git（仓库根 = 工作区根目录，游戏在子目录）
git add -A && git commit -m "提交信息"

验证规则（最高优先级，违反会被用户骂）

1. 游戏视觉/手感禁止 Agent 验收——用户亲自验收。但账号/大厅/排行榜/结算上报等功能流允许 playwright 测试（用户 2026-08-06 明确授权）：注册/登陆/数据断言可跑，只是不许用截图评判游戏画面效果。
2. 交付时必须诚实标注验证状态。
3. 完成了操作 ≠ 任务完成，未经验证不得说“修复了/完成了”。

项目结构

star-raid/
├── index.html          # 入口 + 全部覆盖层 UI 结构
├── css/style.css       # 全部样式（像素风 UI 变量配色）
├── server/             # 后端（零依赖 node:http+node:sqlite）
│   ├── server.js       # 入口：静态白名单+/api路由+安全头
│   ├── env.js          # .env 加载（启动最先加载，环境变量优先）
│   ├── db.js           # SQLite schema（users/sessions/user_stats/codex_unlocks/runs）
│   ├── auth.js         # scrypt密码哈希+服务端session
│   ├── api.js          # API处理器；CODEX_KEYS 白名单（新增装备必须同步！）
│   └── util.js         # body解析/限流/输入校验
├── .env                # 本机配置（不进 git；模板 .env.example）
├── js/
│   ├── config.js       # BAL 平衡参数、常量
│   ├── data.js         # WEAPONS/SUBS/DRONES 装备数据表
│   ├── core.js         # 游戏状态 G、发射逻辑、explodeFx 爆炸特效库
│   ├── combat.js       # 子弹运动/碰撞/光束判定/zones 区域效果
│   ├── enemies.js      # ENEMIES 杂兵表、BOSSES 表、bossMain/bossMinor 攻击库
│   ├── render.js       # 世界渲染（battleUI 门控只在战斗界面绘制游戏对象）
│   ├── boss_art.js     # Boss 美术库（drawProgenitor/drawAssault/drawPiano/drawUsurper/drawSaucer）
│   ├── sprites.js      # 像素字符画 bake 系统、SPR 精灵表、BHALO 弹光晕
│   ├── audio.js        # SFX 音效（WebAudio 合成）
│   ├── net.js          # NET：API 客户端（fetch 封装/图鉴同步/submitRun）
│   ├── auth.js         # 认证流程（登陆/注册/登出 + boot 引导）
│   ├── home.js         # 大厅：排行榜 + 图鉴展柜背景（drawHomeShowcase）
│   └── ui.js           # 菜单/图鉴/rush 选择/老虎机/结算（submitRun 上报）
├── demo/               # 动作设计 demo（不在静态白名单，公网不可见）
├── DEPLOY.md           # 部署指南（公网/HTTPS/安全边界）
└── research/           # Boss 参考图与调研（不进 git）

代码规范

• 单文件不超过 500 行；新增大功能先考虑拆模块
• 严格 "use strict"；全局函数跨文件直接调用（无模块系统，script 标签顺序加载）
• 编辑技巧：edit_file 的 old_string 必须先 grep/sed 读原文确认（含中文注释易有不可见差异）；整批替换任一失败则全部不写入

设计禁忌（用户铁律）

1. AoE 区域效果禁止画圆形区域——用纯粒子、不规则雾团、电弧（钢琴蓄力圈是唯一批准的例外）
2. 禁止恢复已删除的武器：弹跳光碟、钻头弹、感应水雷、全息诱饵、圣水领域
3. 武器命中禁止屏幕白闪（玩家受伤/Boss 死亡的闪光保留）
4. 子弹差异化是最高优先级：颜色/形状/运动/拖尾/命中效果五轴都要拉开
5. Boss 变形=同一几何体连续演化（裂开/展开/伸长/滑开露出），禁止部件凭空出现；俯视图禁止画立体尖塔

Boss 设计标准

设计或修改任何 Boss 前，必须读取项目记忆 .astrion/memory/boss_design_standard.md（视觉公式/攻击节奏/判定同源原则/小兵差异化）。触手扫击类动作设计参考 star-raid/demo/tentacle-sweep.html 的"前摇→释放→后摇"三段式。

核心原则一句话：视觉 = 判定（碰撞坐标每帧只算一份，渲染与判定同源）。

工作流约定

• 大改动先讨论方案再动手；视觉效果由用户验收后再迭代
• 每完成一个逻辑单元立即 git 提交（提交信息写清改了什么+为什么）
• 项目记忆（.astrion/memory/）沉淀重要约定，发现新约定主动更新

后端约定（2026-08-06 后端化）

• 客户端流程：boot → /api/me → 未登录 o-auth（登陆/注册）→ 已登录 o-home（大厅：用户面板+排行榜）→ o-title（基地菜单）
• 结算上报：submitRun()（ui.js）在 endRun 与 rush 胜利（enemies.js killBoss）两处调用；G.submitted 防重
• 图鉴：服务端 codex_unlocks 为准，登陆时与本地 SAVE.codex 并集合并；未收集=剪影+???不可演示
• 背景规则：render() 用 battleUI() 门控；主页/基地背景=实战模拟（home.js startHomeSim：随机3主Lv3+3副Lv3+2僚Lv2，G.homeSim 标记，复用 demoSim 自动驾驶刷怪，AU.simMute 静音，不伤/不计分/不上报，主循环看门狗自动重建）；其余空闲=星空。离场必须 G=null（b-home/b-quit/buildRush 已处理）
• 新增装备时必须同步 server/api.js 的 CODEX_KEYS 白名单（现 25+17+13+8=63）
• 星币/机体/选中机体/永久强化/本地纪录已上服务端（POST /api/state → player_state 表，服务端权威整体替换，登出清空；客户端 persist() 钩子防抖600ms上传）
• 无尽断点续玩（2026-08-06）：run_saves 表（每账号1栏位，不分难度），GET/POST/DELETE /api/run_save。波次检查点：startWave 开头 maybeSaveRun() 拍快照（仅无尽+登录态）；中途“放弃任务”不结算（星币/分数留快照）；出击页 resume-slot 卡片续玩（resumeSavedRun：该波从头重打，bossN 不偏移）；新开无尽（不分难度）弹 o-unsaved 确认→settleSavedRun 直接结算旧档（星币入账+上报排行榜+删档）；死亡/通关 endRun 删档。NET._rsQ 串行队列防删建竞态。闯关/rush 不产生云档
• server/api.js SHIP_KEYS 含全部5机体（曾漏 asura 会致修罗云同步被白名单丢弃，2026-08-06 修）