docs: refresh repository documentation

.github/workflows/python.yml

@@ -0,0 +1,37 @@
+name: Python validation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install dependencies
+        run: python -m pip install -r requirements-dev.txt
+
+      - name: Test module and console pytest entry points
+        run: |
+          python -m pytest -q
+          pytest -q
+
+      - name: Compile Python sources
+        run: python -m compileall -q main.py src game_content tools
+
+      - name: Validate project assets
+        run: python tools/validate_assets.py

.gitignore

@@ -9,12 +9,18 @@
 *.py[cod]
 *.nbc
 *.nbi
+.pytest_cache/
+/build/
+/dist/
+/*.egg-info/
 tmpclaude-*-cwd
 
 # Node / VitePress docs build output
 node_modules/
 docs/.vitepress/cache/
+docs/.vitepress/.temp/
 docs/.vitepress/dist/
+vscode_in/out/
 
 # Local report/export artifacts
 .edge-headless/
@@ -41,6 +47,8 @@ tests/test_window_key_sync.py
 /userdata/settings.json
 /userdata/progress.json
 /userdata/replays/
+/userdata/audio_cache/
+/userdata/hiscore.json
 
 # 本地 Claude Code 项目说明（不分发）
 /CLAUDE.md

.vscode/tasks.json

@@ -0,0 +1,30 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "PythonSTG: Open Scene Editor",
+            "type": "shell",
+            "command": "python tools/scene_editor.py",
+            "problemMatcher": []
+        },
+        {
+            "label": "PythonSTG: Preview Current File",
+            "type": "shell",
+            "command": "python tools/preview.py ${file}",
+            "problemMatcher": []
+        },
+        {
+            "label": "PythonSTG: Preview Current Spell",
+            "type": "shell",
+            "command": "python tools/preview.py ${file} --spell ${input:spellClass}",
+            "problemMatcher": []
+        }
+    ],
+    "inputs": [
+        {
+            "id": "spellClass",
+            "type": "promptString",
+            "description": "SpellCard class name to preview"
+        }
+    ]
+}

CLAUDE.md

@@ -22,16 +22,19 @@ python main.py --debug
 python main.py --profile
 
 # 运行测试
-pytest
-pytest -m smoke  # 仅快速回归测试
+python -m pytest -q
+python -m pytest -m smoke -q  # 仅快速回归测试
 
 # 安装依赖（开发环境）
 pip install -r requirements-dev.txt
 
 # 生成子弹/敌人图片画廊
 python tools/asset/generate_combat_gallery.py
 
-# 启动可视化编辑器
+# 启动统一场景编辑器工作台
+python tools/scene_editor.py
+
+# 旧版独立工具启动器仍可用
 python tools/editor_launcher.py
 ```
 
@@ -47,9 +50,11 @@ main.py                         ← 入口、主循环、游戏状态机
 │   ├── bullet/                 ← 子弹池（Numba JIT，NumPy 结构数组）
 │   ├── stage/                  ← 关卡系统核心（stage_base, context, wave_base, spellcard, boss_base）
 │   ├── player/                 ← 玩家、射击系统、Option、动画状态机
-│   ├── laser/                  ← 激光系统（直线/曲线）
-│   ├── item/                   ← 道具系统
-│   └── audio/                  ← 双层音频（全局 bank + 关卡私有 bank）
+│   ├── background_render/      ← 数据驱动背景与正式预览渲染
+│   ├── emoji_danmaku/          ← 外部弹幕输入与子弹桥接
+│   ├── laser.py                ← 直线/曲线激光
+│   ├── item.py                 ← 道具系统
+│   └── audio.py                ← 双层音频（全局 bank + 关卡私有 bank）
 ├── src/render/                 ← OpenGL 渲染管线（实例化渲染）
 ├── src/ui/                     ← HUD、对话框、主菜单
 └── game_content/stages/        ← 关卡内容脚本（与引擎解耦）
@@ -104,3 +109,5 @@ game_content/stages/stageN/
 - `docs/STAGE_SCRIPTING_GUIDE.md` — 完整 API 参考与示例
 - `docs/ENEMY_PRESET_SYSTEM.md` — 预设敌人配置说明
 - `docs/TEXTURE_ASSET_SYSTEM.md` — 精灵/图集管理原理
+- `docs/SCENE_EDITOR_MVP.md` — 场景编辑器当前能力与边界
+- `docs/EDITOR_TOOLS_GUIDE.md` — 工作台与专用编辑器入口

README.md

@@ -29,6 +29,7 @@ PySTG 是一个面向**关卡内容创作者**和**引擎二次开发者**的弹
 - 🌟 **激光系统** — 直线激光（三段式：展开→持续→收缩）+ 曲线激光
 - 📦 **数据驱动资产** — 纹理图集、精灵动画、弹幕别名表全部 JSON 配置
 - 🎨 **可视化编辑器** — 弹幕别名管理器、纹理资产编辑器、自机编辑器、对话立绘编辑器
+- 🧩 **统一插件工作台** — Scene、Inspector、资源浏览器、JSON 子资源和现有编辑工具统一入口
 - 🔊 **双层音频** — 全局 bank + 关卡私有 bank，关卡音效可覆盖全局同名音效
 - 🌅 **3D 背景** — 透视投影 + 雾效 + 程序化生成（如湖面反射）
 - 🛠 **Debug 模式** — 一键跳转任意 Wave / Boss / 符卡，加速开发迭代
@@ -65,13 +66,30 @@ python main.py --debug
 
 # 性能分析
 python main.py --profile
+
+# 打开统一场景编辑器（需要开发依赖）
+python tools/scene_editor.py
 ```
 
+场景编辑器同时是编辑工具工作台：
+
+- 底部 **Assets** 浏览 `assets/` 与 `game_content/`，支持搜索、类型/目录过滤，以及 JSON 内的 sprite/animation 子资源。
+- 双击图片或 sprite 会创建 Sprite；选中已有 Sprite 时会设置其 `texture`。
+- 从 Assets 拖图片或 sprite 到 Scene 会按落点创建 Sprite；选中 SpellCard 后可双击或拖入 Python 脚本设置 `script`。
+- **Tools** 菜单内嵌弹幕别名管理器，并以独立进程打开纹理、自机、敌人、背景、弹幕脚本、对话和 UI 布局工具。
+- 所有旧工具脚本和 `tools/editor_launcher.py` 仍可独立启动。
+
 ### 开发依赖（编辑器与测试）
 
 ```bash
 pip install -r requirements-dev.txt
-pip install PyQt5   # 编辑器工具
+```
+
+如果希望使用安装后的命令入口，再执行：
+
+```bash
+pip install -e .
+pystg-editor
 ```
 
 ---
@@ -117,14 +135,17 @@ flowchart TB
 | [快速开始](docs/getting-started.md) | 环境搭建、第一份脚本、目录约定 |
 | [弹幕脚本开发指南](docs/STAGE_SCRIPTING_GUIDE.md) | 完整 API 参考、符卡/波次/敌人/Boss 编写方法 |
 | [敌人预设系统](docs/ENEMY_PRESET_SYSTEM.md) | 用 JSON 预设快速创建杂兵 |
-| [编辑器工具](docs/EDITOR_TOOLS_GUIDE.md) | 弹幕别名管理器、纹理编辑器、自机编辑器 |
+| [编辑器工具](docs/EDITOR_TOOLS_GUIDE.md) | 统一工作台与专用编辑器 |
+| [场景编辑器](docs/SCENE_EDITOR_MVP.md) | Scene、Inspector、资源浏览和预览边界 |
 
 ### 给引擎开发者（修引擎 / 加新模块）
 
 | 文档 | 内容 |
 |------|------|
 | [架构概览](docs/architecture.md) | 引擎分层、模块依赖、数据流 |
 | [纹理资产系统](docs/TEXTURE_ASSET_SYSTEM.md) | 图集加载、精灵定义、动画配置 |
+| [开发工具链](docs/DEVTOOLS_PHASE1.md) | 资源校验、热重载、Pattern Lab 和符卡预览 |
+| [编辑器架构边界](docs/EDITOR_ARCHITECTURE.md) | 编辑器、文档、运行时和资源服务的依赖约束 |
 
 也可以本地启动 VitePress 文档站点：
 
@@ -323,7 +344,7 @@ async def _(event: MessageEvent):
 
 - Replay 录像系统
 - 游戏设置界面（按键绑定、画质）
-- 可视化关卡编辑器
+- 将场景编辑器从 MVP 扩展为可编排关卡内容的正式工作流
 - 更多可选自机
 
 ---
@@ -340,8 +361,8 @@ async def _(event: MessageEvent):
 跑测试：
 
 ```bash
-pytest                # 全量
-pytest -m smoke       # 仅快速回归
+python -m pytest -q             # 全量
+python -m pytest -m smoke -q    # 仅快速回归
 ```
 
 ---

assets/bullet_aliases.json

@@ -453,6 +453,42 @@
       "white":      "ball_light8",
       "black":      "ball_light8",
       "pink":       "ball_light2"
+    },
+    "scale_s": {
+      "red":      "ball_mid1",
+      "blue":     "ball_mid2",
+      "green":    "ball_mid3",
+      "yellow":   "ball_mid4",
+      "purple":   "ball_mid5",
+      "white":    "ball_mid6",
+      "darkblue": "ball_mid7",
+      "orange":   "ball_mid8",
+      "cyan":     "ball_mid1",
+      "pink":     "ball_mid5"
+    },
+    "rice_s": {
+      "red":      "ball_mid1",
+      "blue":     "ball_mid2",
+      "green":    "ball_mid3",
+      "yellow":   "ball_mid4",
+      "purple":   "ball_mid5",
+      "white":    "ball_mid6",
+      "darkblue": "ball_mid7",
+      "orange":   "ball_mid8",
+      "cyan":     "ball_mid1",
+      "pink":     "ball_mid5"
+    },
+    "scale_m": {
+      "red":      "ball_mid1",
+      "blue":     "ball_mid2",
+      "green":    "ball_mid3",
+      "yellow":   "ball_mid4",
+      "purple":   "ball_mid5",
+      "white":    "ball_mid6",
+      "darkblue": "ball_mid7",
+      "orange":   "ball_mid8",
+      "cyan":     "ball_mid1",
+      "pink":     "ball_mid5"
     }
   }
 }

docs/.vitepress/config.mts

@@ -51,7 +51,10 @@ export default defineConfig({
         items: [
           { text: '弹幕脚本开发指南', link: '/STAGE_SCRIPTING_GUIDE' },
           { text: '敌人预设系统', link: '/ENEMY_PRESET_SYSTEM' },
-          { text: '编辑器工具', link: '/EDITOR_TOOLS_GUIDE' }
+          { text: '统一场景编辑器', link: '/SCENE_EDITOR_MVP' },
+          { text: '编辑器工具', link: '/EDITOR_TOOLS_GUIDE' },
+          { text: '开发工具链', link: '/DEVTOOLS_PHASE1' },
+          { text: '编辑器架构边界', link: '/EDITOR_ARCHITECTURE' }
         ]
       },
       {
@@ -60,7 +63,7 @@ export default defineConfig({
           { text: '架构概览', link: '/architecture' },
           { text: '纹理资产系统', link: '/TEXTURE_ASSET_SYSTEM' }
         ]
-      }
+      },
     ],
     socialLinks: [
       { icon: 'github', link: 'https://github.com/qwqpap/PythonSTG' }