chore(meta): 添加项目 AI 助手元数据与技能定义
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
---
|
||||
name: "source-command-split-commit"
|
||||
description: "将当前未提交改动拆分为多个符合规范的原子提交"
|
||||
---
|
||||
|
||||
# source-command-split-commit
|
||||
|
||||
Use this skill when the user asks to run the migrated source command `split-commit`.
|
||||
|
||||
## Command Template
|
||||
|
||||
将当前未提交改动拆分为多个原子提交。执行前会分析变更、生成分组方案，经用户确认后逐组提交。
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Step 1: 前置检查
|
||||
|
||||
1. **清理残留文件**：若存在 `msg.txt`，先 `rm -f msg.txt`
|
||||
2. **读取规范**：确认 `COMMIT_CONVENTION.md` 存在且可读
|
||||
|
||||
### Step 2: 保护分支检查
|
||||
|
||||
保护分支列表（按优先级）：`AGENTS.md` > `.cursor/rules/` > `.git/config branch.protected` > 默认(`master|main|develop`)
|
||||
|
||||
若当前在保护分支，询问用户：
|
||||
- **A** - 创建 feature 分支后继续拆分（推荐）
|
||||
- **B** - 转移到新分支后压成单提交
|
||||
- **C** - 取消
|
||||
|
||||
### Step 3: 盘点变更
|
||||
|
||||
执行以下命令分析：
|
||||
- `git status` - 整体状态
|
||||
- `git diff --stat` - 文件统计
|
||||
- `git diff` - 详细改动
|
||||
- `git diff --cached` - 已暂存改动
|
||||
|
||||
### Step 4: 规则化分组
|
||||
|
||||
按"意图一致"原则分组，**优先按 type 分，再按 scope 分**。
|
||||
|
||||
**必须拆分的情况**：
|
||||
- 同一组可归属多个 type
|
||||
- 同文件包含多个独立目的（如功能+重构）
|
||||
- 资源替换与代码逻辑混合
|
||||
|
||||
**可以合并的情况**（最小拆分原则）：
|
||||
- 同一功能的多文件改动（脚本+Prefab）
|
||||
- 同一模块的多个相关 Bug 修复
|
||||
|
||||
### Step 5: 生成方案表格
|
||||
|
||||
以表格形式展示拆分方案：
|
||||
|
||||
| 顺序 | 文件 | 变更目的 | 提交头 | 依据 | 方式 |
|
||||
|------|------|----------|--------|------|------|
|
||||
| 1 | `路径` | 描述 | `type(scope): subject` | 原因 | `git add`/`git add -p` |
|
||||
|
||||
**Type 选择优先级**：`fix` > `feat` > `art` > `audio` > `scene` > `yarn` > `perf|refactor|...`
|
||||
|
||||
**Scope 规则**：单模块用模块名（如 `blockpuzzle`），跨模块省略。
|
||||
|
||||
### Step 6: 用户确认
|
||||
|
||||
询问：`[Y 执行 / n 取消 / 提出调整]`
|
||||
|
||||
- 若调整：根据反馈修改方案，再次确认
|
||||
- 若执行：进入 Step 7
|
||||
- 若取消：清理并退出
|
||||
|
||||
### Step 7: 逐组提交
|
||||
|
||||
对每组执行：
|
||||
1. `git add <file>` 或 `git add -p <file>`
|
||||
2. 复查：`git diff --cached --stat` 和 `git diff --cached`
|
||||
3. 写入 `msg.txt` 并提交：`git commit -F msg.txt`
|
||||
4. 检查状态：`git status`
|
||||
|
||||
**失败处理**：
|
||||
- `git add -p` 跳过关键 hunk → 暂停，提示处理方案
|
||||
- pre-commit hook 失败 → 询问 [R]重试 [S]跳过 [A]中止
|
||||
|
||||
### Step 8: 结果校验
|
||||
|
||||
输出：
|
||||
1. `git log --oneline -<N>`
|
||||
2. 回放清单（验证 type/scope/subject 合规性）
|
||||
3. 若不合规，询问是否修正
|
||||
|
||||
### Step 9: 清理
|
||||
|
||||
`rm -f msg.txt`
|
||||
|
||||
---
|
||||
|
||||
## Unity 改动速查表
|
||||
|
||||
| 改动类型 | type | scope 示例 |
|
||||
|----------|------|-----------|
|
||||
| 脚本逻辑修复 | `fix` | `blockpuzzle`, `dialog` |
|
||||
| 脚本新功能 | `feat` | `huoshan`, `clue` |
|
||||
| 美术资源（贴图/模型/动画） | `art` | 对应模块或省略 |
|
||||
| 音频资源 | `audio` | `audio-kit` 或省略 |
|
||||
| 场景配置（灯光/镜头） | `scene` | 对应模块或省略 |
|
||||
| Yarn 对话 | `yarn` | `dialog` |
|
||||
| 测试代码 | `test` | 对应模块 |
|
||||
|
||||
---
|
||||
|
||||
## 规范校验清单（执行前检查）
|
||||
|
||||
- [ ] 格式：`<type>(<scope>): <subject>` 或 `<type>: <subject>`
|
||||
- [ ] type ∈ {`feat`,`fix`,`art`,`audio`,`scene`,`yarn`,`perf`,`refactor`,`style`,`docs`,`build`,`chore`,`test`}
|
||||
- [ ] subject：中文、动词开头、≤50字、无句号
|
||||
- [ ] 一次提交只做一件事
|
||||
|
||||
---
|
||||
|
||||
## 中文提交方法
|
||||
|
||||
由于 PowerShell 中文乱码问题，统一使用文件方式：
|
||||
|
||||
```bash
|
||||
echo "type(scope): 描述" > msg.txt
|
||||
git commit -F msg.txt
|
||||
rm -f msg.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关于 Pre-commit Hooks
|
||||
|
||||
若配置了 husky/lint-staged：
|
||||
- 每次提交都会触发检查
|
||||
- 如需跳过（**不推荐**）：`git commit -F msg.txt --no-verify`
|
||||
- 跳过可能导致 CI 失败
|
||||
|
||||
---
|
||||
|
||||
开始执行请回复 **"开始"**，或告知需要的调整。
|
||||
@@ -0,0 +1,152 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
AIBIS Dream (also known as "AllOurBrokenParts") is a Unity-based narrative adventure game with investigative elements. The project uses Yarn Spinner for dialogue, features a custom framework with modular systems, and includes multiple mini-games and a modular repair/fix system.
|
||||
|
||||
**Unity Version:** 2022.3.7f1c1 (Universal Render Pipeline)
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Framework (Assets/Scripts/Framework/)
|
||||
|
||||
Modular framework with Kit-pattern utilities:
|
||||
|
||||
- **ActionKit**: Action sequencing and command pattern
|
||||
- **AudioKit**: Audio management (includes FMOD integration)
|
||||
- **Config / Core**: Configuration and core utilities
|
||||
- **EventSystemKit**: Decoupled event system
|
||||
- **LogKit**: Structured logging with categories
|
||||
- **PoolKit**: Object pooling
|
||||
- **ResourceKit**: Asset loading via `ResourceSystem` (Addressables-based)
|
||||
- **Note**: New code must use `ResourceSystem`, never `Resources.Load`. See [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md). Asset placement rules in [Resource Management Spec](Docs/ResourceManagementSpec.md).
|
||||
- **SelectorKit**: Weighted/batch/non-repeat random selection
|
||||
- **SingletonKit**: Singleton base classes
|
||||
- **StateMachineKit**: State management
|
||||
- **OtherKit**: Miscellaneous utilities (`CameraKit`, `AnimatorKit`, `FadeKit`, `LocalizationKit`, etc.)
|
||||
- **Attribute**: Custom editor attributes
|
||||
|
||||
### Key Game Systems
|
||||
|
||||
- **Game Loop** (Scripts/Game Loop/): `GameManager` (Singleton entry), `YarnVariableStorage` (Yarn variables), `SaveRestoreOrchestrator` / `SaveSystem` (save snapshots), `SceneLoader`, `ChapterController`, `TalkSceneSO`
|
||||
- **Dialog System** (Scripts/Dialog System/): Yarn Spinner integration — `DialogController`, `LineRunner`, `LocalisedLineProvider`, `BaseYarnCommand`
|
||||
- **SceneManagement** (Scripts/SceneManagement/): `ActorKit/`, `AnimatorKit/`, `EnvironmentKit/`, `SpawnerKit/`, `TimelineKit/`, `SceneCenter/`, `DreamDoorSystem`
|
||||
- **UI** (Scripts/UI/): `DialogUI/`, `Panel/`, `Form/`, `Components/`, `Cursor/`, `UIManager`
|
||||
- **MiniGame** (Scripts/MiniGame/): `HuoShan/` (language particles, EmotionWave), `BlockPuzzle/`, `Peipei/` (Eye, CutLine, Memory)
|
||||
- **FixSystem** (Scripts/FixSystem/): Legacy — HeatMap, PunchTape, Memory, screen effects
|
||||
- **FixSystemNew** (Scripts/FixSystemNew/): Active repair system — `FixSystemCenter`, `BodyModule/`, `Cable/`, `WhackMole/`, `Screen System/`, `Open/`, `Clinic/`
|
||||
- **AssetRefs** (Scripts/AssetRefs/): Addressable key constants (`ConstRef`, `FixAssetRef`, `TimelineAssetRef`)
|
||||
|
||||
### Content & Localization
|
||||
|
||||
- **Assets/GameContent/**: Runtime assets by scope (`Common/`, `UI/`, `Scene_{Name}/`, `Feature_{Name}/`)
|
||||
- **Assets/Language/**: Unity Localization tables (runtime active: `UIText/`, `Locales/`, `Sprite/`; `Dialog/`、`ActorName/`、`Params/` currently kept as migration backups)
|
||||
- **Assets/Resources/Yarn/**: Current Yarn dialogue files (target migration to `Assets/Narrative/` per spec, not yet complete)
|
||||
- **Assets/StreamingAssets/Config/**: CSV-driven localized gameplay data (`character.csv` for actor names, `params.csv` for `l10n.*` substitution terms)
|
||||
- **Assets/Prototype/**: HTML/JS prototypes for mechanic testing
|
||||
|
||||
## Critical Dependencies
|
||||
|
||||
### Unity Packages
|
||||
- **Yarn Spinner** 3.2.2 (OpenUPM), **Addressables** 1.21.21, **Cinemachine** 2.9.7
|
||||
- **URP** 14.0.8, **TextMesh Pro** 3.0.6, **Timeline** 1.7.5, **Localization** 1.4.5
|
||||
- **Visual Effect Graph** 14.0.8, **Visual Scripting** 1.8.0
|
||||
|
||||
### Third-Party
|
||||
- **FMOD** (audio engine), **DOTween** (tweening), **Shapes** (vector graphics)
|
||||
- **More Mountains Feedbacks** (game feel), **Destructible 2D**
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Organization
|
||||
1. Each major system self-contained in its own folder under `Assets/Scripts/`
|
||||
2. Kit-pattern utilities in `Framework/` — reusable across systems
|
||||
3. Singleton pattern for global managers (derived from `SingletonKit`)
|
||||
4. Favor composition over inheritance
|
||||
5. All runtime asset loading via `ResourceSystem` — never `Resources.Load`
|
||||
|
||||
### Scene Structure
|
||||
- Scenes in `Assets/Scenes/`; `Persistence` scene hosts global managers and Persistent Loader
|
||||
- Fix scenes: `{Character}FixScene` (e.g. `HuoShanFixScene`, `PeipeiFixScene`, `ExpressFixScene`)
|
||||
- Test scenes: `languageTest`, `HuoShanExpressionTest`, `wavetest`, etc.
|
||||
|
||||
### Addressables
|
||||
- Config in `Assets/AddressableAssetsData/`; Groups: `Core`, `Scene_*`, `Feature_*`, `Shared_*`, `Localization-*`
|
||||
- Key format: `Category/Path` (e.g. `Animation/Peipei`, `Timeline/BlockPuzzle/PanelOpen`)
|
||||
- Scene keys use bare PascalCase names (e.g. `ClinicOut`)
|
||||
- Details in [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md)
|
||||
|
||||
### Yarn Dialogue Files
|
||||
- Current path: `Assets/Resources/Yarn/` (migration to `Assets/Narrative/Yarn/` planned)
|
||||
- Pattern: `{Character}_{Stage}.yarn`; UTF-8 encoding required for Chinese
|
||||
|
||||
#### Yarn Line Tag Maintenance
|
||||
- **Line tags** (`#line:xxxxxxx`) must be unique across the entire file. Duplicate tags break Yarn Spinner localization.
|
||||
- Duplicates typically occur when copying an existing node to create a variant (e.g. `地铁ver1` → `地铁ver3`).
|
||||
- **Use the dedup tool** (`Tools/dedup_yarn_tags.py`) for bulk cleanup:
|
||||
```bash
|
||||
# Preview duplicates from a specific node onward
|
||||
python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/Fiction_Day1_begin/Fiction_Day1_begin.yarn --from-node 地铁ver4
|
||||
# Fix duplicates from a specific line onward
|
||||
python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/Fiction_Day1_begin/Fiction_Day1_begin.yarn --from-line 535 --fix
|
||||
# Scan an entire directory (preview only)
|
||||
python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/ --scan-all
|
||||
```
|
||||
|
||||
#### Yarn Script Generation
|
||||
- **Do NOT add `#line:` tags when generating or editing Yarn dialogue.** Leave all line-tag generation to the user's localization workflow (Unity Localization + Yarn Spinner import tools).
|
||||
- When creating new `.yarn` files, write plain dialogue lines without any `#line:` suffixes.
|
||||
|
||||
### Asset Naming
|
||||
- **Scripts**: PascalCase (e.g. `DialogController.cs`)
|
||||
- **Addressable Keys**: `Category/Path` — no spaces, no extensions, ≤3 levels
|
||||
- **Addressable Groups**: `{Type}_{PascalCaseName}`
|
||||
|
||||
### Git & Commits
|
||||
- LFS for large binaries; ignored: Library/, Temp/, Build/, *.csproj, *.sln
|
||||
- **Commit format**: `<type>(<scope>): <subject>` — subject in Chinese, type/scope in English
|
||||
- Extended types: `feat`, `fix`, `art`, `audio`, `scene`, `yarn`, `perf`, `refactor`, `style`, `docs`, `build`, `chore`, `test`
|
||||
- See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for full details
|
||||
|
||||
## Key Build Commands
|
||||
|
||||
```bash
|
||||
# Windows build
|
||||
"C:\Program Files\Unity\Hub\Editor\2022.3.7f1c1\Editor\Unity.exe" -batchmode -quit -projectPath . -buildWindows64Player "Build/AIBIS_Dream.exe" -logFile Build/log.txt
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Mini-Game
|
||||
1. Create `Assets/Scripts/MiniGame/{GameName}/`
|
||||
2. Add assets to `Assets/GameContent/Feature_{GameName}/`
|
||||
3. Create Addressable Group `Feature_{GameName}`
|
||||
4. Create test scene in `Assets/Scenes/`
|
||||
|
||||
### Adding Yarn Dialogue
|
||||
1. Create `.yarn` in `Assets/Resources/Yarn/{Module}/`
|
||||
2. Ensure YarnProject localization assets/CSV are updated (Unity `Assets/Language/Dialog/` is backup-only during migration)
|
||||
3. Reference in scene's `DialogueRunner`; test with `DialogController`
|
||||
|
||||
## Debugging & Performance
|
||||
- `LogKit` for structured logging; Addressables Event Viewer for resource debugging
|
||||
- Monitor `SceneResourceLoader.TotalHandleCount` for leak detection
|
||||
- Always use PoolKit for frequent instantiation; `LoadUncachedAsync` + `EarlyRelease` for large Timeline assets
|
||||
- Use `LoadAsync<GameObject>` + `Instantiate` for prefabs, never `InstantiateAsync`
|
||||
|
||||
## Important Notes
|
||||
- Narrative-focused game — dialogue and story take precedence
|
||||
- `FixSystemNew` is the active repair architecture; `FixSystem` is legacy
|
||||
- `YarnVariableStorage` holds Yarn runtime variables; save/load flows through `SaveRestoreOrchestrator` and `SaveSystem`
|
||||
|
||||
## Reference Documents
|
||||
- [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md) — `ResourceSystem` API, Key/Group/Label naming, lifecycle
|
||||
- [Resource Management Spec](Docs/ResourceManagementSpec.md) — Asset placement: `GameContent/`, `Narrative/`, `_Archive/`
|
||||
- [Commit Convention](COMMIT_CONVENTION.md) — Commit message format and branch naming
|
||||
- [HuoShan Docs](Docs/HuoShan/) — Narrative flow, resources, test flowcharts
|
||||
|
||||
---
|
||||
|
||||
*This document provides guidance for Codex when working with the AIBIS Dream codebase.*
|
||||
Reference in New Issue
Block a user