Project Intake Archiver

1. Skill 目的

本 Skill 用于把一个“外部已有项目”安全接入统一的 GameStudio 工作区。

目标结构：

GameStudio/
├─ STUDIO.md
├─ STUDIO_TASKS.md
├─ _shared/
│  └─ AGENTS.md
│
├─ 01_MainGame/
│  ├─ AGENTS.md
│  ├─ README.md
│  ├─ docs/
│  │  ├─ GAME.md
│  │  ├─ TASKS.md
│  │  ├─ BUGS.md
│  │  ├─ DECISIONS.md
│  │  └─ CHANGELOG.md
│  ├─ src/
│  ├─ assets/
│  ├─ tests/
│  └─ builds/
│
└─ ...

核心原则：

1. 外部项目先盘点，再归档。
2. 默认不删除、不覆盖原项目。
3. 不凭空补写游戏设定。
4. 不把不同项目的代码、需求、Bug、决策混在一起。
5. 项目文档和代码必须保持项目级隔离。
6. 归档过程中发现的信息必须区分：
   - 已确认事实
   - 从现有文件推断的信息
   - 尚未确认的信息
7. 不因为“目录看起来应该这样”而擅自重构代码。
8. 优先保持原项目可运行性。

2. 触发方式

当用户提出类似请求时使用本 Skill：

• “把这个项目接进我的 GameStudio”
• “整理这个外部小游戏项目”
• “把旧项目按我们的 AI 开发方案归档”
• “把这个项目接入 策划助手 + 执行代理 工作流”
• “把这个项目变成标准项目结构”
• “扫描这个项目并建立 GAME/TASKS/BUGS”

输入至少应包含：

外部项目路径

如果用户同时提供目标 GameStudio 路径，则直接使用。

如果没有提供目标 GameStudio 路径：

1. 优先询问目标工作区。
2. 不要擅自创建到系统未知位置。
3. 如果用户明确允许，可使用当前工作目录下的 GameStudio/。

3. 接入前安全规则

3.1 永远先扫描

第一阶段只读。

禁止在首次扫描阶段：

• 删除文件
• 移动文件
• 重命名文件
• 覆盖文件
• 修改代码
• 修改项目配置
• 安装依赖
• 执行可能改变项目状态的命令

只允许：

• 读取目录结构
• 读取文本文件
• 识别技术栈
• 识别已有文档
• 识别项目入口
• 识别构建方式
• 识别版本控制信息
• 统计资源

3.2 原项目保护

默认采用：

外部项目
   ↓
复制/整理
   ↓
GameStudio/项目名

而不是：

外部项目
   ↓
直接移动/重构

如果用户明确要求“原地整理”，必须先说明风险，并在执行前获得明确确认。

4. 第一阶段：项目扫描

扫描以下内容。

4.1 顶层目录

识别：

src/
Assets/
ProjectSettings/
Packages/
Scenes/
Scripts/
Resources/
StreamingAssets/
tests/
docs/
README*
package.json
package-lock.json
requirements.txt
pyproject.toml
Cargo.toml
*.csproj
*.sln
project.godot
*.uproject
*.unity
*.godot
*.html
*.js
*.ts

不要只依赖目录名称。

4.2 技术栈识别

根据文件判断：

• Unity
• Godot
• Unreal
• HTML5 / JavaScript
• TypeScript
• Python
• C#
• C++
• 其他

输出：

技术栈：
引擎：
主要语言：
构建系统：
依赖管理：

如果无法确认：

未知，待确认

禁止猜测。

4.3 项目入口

尝试识别：

• 主场景
• 主程序
• 游戏启动入口
• README中的运行方式
• package.json scripts
• Unity项目配置
• Godot项目配置
• Unreal项目配置

记录：

启动入口：
运行方式：
构建方式：

5. 第二阶段：识别已有项目文档

搜索：

README
README.md
DESIGN
DESIGN.md
GDD
GDD.md
GAME
GAME.md
TASK
TASKS
TODO
BUG
BUGS
CHANGELOG
DECISION
DECISIONS
ROADMAP
PLAN
NOTES

同时检查：

docs/
documentation/
design/
notes/

不要假设已有文件一定可靠。

6. 文档分类原则

把旧项目中的信息映射到新结构。

GAME.md

放：

• 游戏概述
• 核心玩法
• 玩家目标
• 玩家操作
• 胜负条件
• Gameplay Loop
• 关卡规则
• 数值规则
• UI
• 美术方向
• 音频方向
• 技术要求

TASKS.md

放：

• TODO
• 待开发功能
• 未完成系统
• Roadmap中的开发事项
• 明确需要实现的功能

每项转换成：

## T-XXX 任务名称

状态：TODO
优先级：待定

来源：
原文件/原任务

要求：
...

验收：
待定义

如果原项目没有明确验收条件：

验收：待定义

不要自行编造。

BUGS.md

放：

• 已知Bug
• TODO中的明确Bug
• Issue记录
• 开发日志中明确记录的异常

每个Bug使用：

## BUG-XXX

状态：OPEN

来源：
原文件/Issue

问题：
...

复现步骤：
未记录

预期：
未记录

实际：
...

影响：
待评估

DECISIONS.md

只放已经明确作出的设计/技术决定。

例如：

“玩家使用WASD移动”
“项目使用Unity”
“第20关后启用动态高度坐标”

如果只是讨论或候选方案：

不要放入 DECISIONS.md。

可以记录为：

待决策：
...

CHANGELOG.md

保留已有版本变更记录。

如果没有：

# CHANGELOG.md

## 接入记录

日期：
YYYY-MM-DD

说明：
项目首次接入 GameStudio。

原项目版本：
未知

不得伪造历史版本。

7. 第三阶段：建立项目名称

优先级：

1. 用户指定名称
2. 原项目名称
3. README中的正式名称
4. 项目配置中的名称
5. 文件夹名称
6. 使用临时名称并标记“待确认”

不要根据代码内容自行创造正式游戏名称。

目录建议：

01_ProjectName/
02_ProjectName/
03_ProjectName/

编号由 GameStudio 当前已有项目决定。

如果是第一个正式主项目：

01_MainGame/

如果只是实验项目：

02_Prototype/

如果只是Idea：

03_Idea/

8. 第四阶段：创建标准项目结构

创建：

Project/
├─ AGENTS.md
├─ README.md
├─ docs/
│  ├─ GAME.md
│  ├─ TASKS.md
│  ├─ BUGS.md
│  ├─ DECISIONS.md
│  └─ CHANGELOG.md
├─ src/
├─ assets/
├─ tests/
└─ builds/

但是：

不要强制移动代码

如果原项目已有成熟结构：

Assets/
Packages/
ProjectSettings/

应优先保留原结构。

例如 Unity 项目：

01_MainGame/
├─ AGENTS.md
├─ README.md
├─ docs/
├─ Assets/
├─ Packages/
├─ ProjectSettings/
└─ ...

而不是为了模板强行改成：

src/
assets/

原则：

> 文档结构标准化，代码结构尊重原引擎。

9. 第五阶段：生成项目级 AGENTS.md

根据项目技术栈生成。

基础内容：

# AGENTS.md

## 项目身份

本项目是 GameStudio 中的独立游戏项目。

## 文档优先级

1. 本文件
2. docs/GAME.md
3. docs/DECISIONS.md
4. docs/TASKS.md
5. docs/BUGS.md
6. 当前代码

## 开发原则

- 最小修改
- 优先复用
- 不修改无关系统
- 不擅自改变核心玩法
- 不擅自增加需求
- 修改后测试

## 项目边界

本项目独立于 GameStudio 中其他游戏。

不得读取其他项目的 GAME.md、TASKS.md、BUGS.md 或 DECISIONS.md，
除非用户明确要求进行跨项目比较或复用。

## 报告

完成任务后报告：

### 完成
### 修改
### 测试
### 注意

再加入技术栈特定规则。

例如 Unity：

## Unity

- 不修改 ProjectSettings 中与当前任务无关的配置。
- 修改场景前先确认场景用途。
- 修改 Prefab 前检查其引用关系。
- 不删除未确认是否使用的资源。

10. 第六阶段：建立 README.md

格式：

# 项目名称

## 项目状态

IDEA / PROTOTYPE / MVP / VERTICAL_SLICE / PRODUCTION / RELEASE / PAUSED

## 项目类型

...

## 技术栈

...

## 原始项目

来源：
...

接入日期：
YYYY-MM-DD

## 当前目标

...

## AI工作方式

策划助手：
- 策划
- 需求分析
- 任务拆解
- Bug分析

执行代理：
- 编程
- Debug
- 测试

用户：
- 最终决策
- 游戏体验验收

11. 第七阶段：生成接入报告

必须创建：

docs/INTAKE_REPORT.md

内容：

# 项目接入报告

## 1. 基本信息

项目名称：
原始路径：
归档路径：
接入日期：

## 2. 技术栈

引擎：
语言：
构建系统：

## 3. 项目状态

判断：
依据：

## 4. 已发现文档

- ...

## 5. 已迁移内容

GAME：
TASKS：
BUGS：
DECISIONS：
CHANGELOG：

## 6. 未确定信息

- ...

## 7. 风险

- ...

## 8. 待用户确认

- ...

## 9. 未修改内容

- ...

12. 项目状态判断

只能依据实际证据。

IDEA

只有：

• 想法
• 设计文档
• 少量原型

PROTOTYPE

已有：

• 可运行原型
• 核心玩法雏形

MVP

已经：

• 核心Gameplay Loop完整
• 可以进行基本游戏

VERTICAL_SLICE

已经：

• 一个完整体验切片
• 接近最终品质

PRODUCTION

核心玩法确定并进入正式内容生产。

RELEASE

已有正式可发布版本。

如果无法判断：

状态：待确认

13. 项目之间的隔离规则

这是本 Skill 最重要的规则之一。

假设：

GameStudio/
├─ 01_MainGame/
├─ 02_Prototype/
└─ 03_Experiment/

处理 01_MainGame 时：

默认只读取：

01_MainGame/
_shared/

不要读取：

02_Prototype/
03_Experiment/

除非用户明确要求：

• 对比两个项目
• 迁移公共系统
• 复用某个工具
• 分析项目差异

14. 跨项目复用规则

发现某项目存在可复用系统时：

不要立即复制。

先标记：

## 可复用候选

系统：
SaveSystem

来源：
01_MainGame

成熟度：
待验证

建议：
项目完成验证后再抽取至 _shared/

只有用户确认后才：

Project
↓
验证
↓
抽取
↓
_shared/
↓
其他项目使用

15. 外部项目已有 Git 时

优先保留 Git。

检查：

.git/
.gitignore
.gitmodules

不要删除。

如果归档操作会导致 Git 历史变化，应明确说明。

如果只是复制项目：

默认保留原Git历史

如果目标 GameStudio 本身需要统一 Git：

先询问用户

不要自动合并两个 Git 仓库。

16. 外部项目存在敏感配置时

识别：

.env
*.key
*.pem
credentials
secrets
API key
token
password

默认：

• 不复制敏感凭据
• 不在报告中输出完整密钥
• 保留 .env.example（如果存在）
• 告知用户发现敏感配置

报告：

发现敏感配置：
.env

处理：
未将真实凭据写入归档文档。

建议：
使用环境变量或 .env.example。

17. 最终验收

归档完成后检查：

A. 项目是否独立

项目A不能依赖项目B的文档才能理解。

B. 文档是否齐全

AGENTS.md
README.md
GAME.md
TASKS.md
BUGS.md
DECISIONS.md
CHANGELOG.md
INTAKE_REPORT.md

C. 原项目是否可运行

如果进行了复制：

优先从归档项目运行一次。

如果无法运行：

必须说明：

未验证成功
原因：
...

D. 是否有未确认内容

全部进入：

INTAKE_REPORT.md

18. 最终输出格式

Skill完成后，只向用户报告：

项目接入完成。

项目：
ProjectName

归档位置：
GameStudio/XX_ProjectName

状态：
PROTOTYPE

技术栈：
Unity / C#

已整理：
- GAME.md
- TASKS.md
- BUGS.md
- DECISIONS.md
- CHANGELOG.md
- AGENTS.md

发现的问题：
- ...

待确认：
- ...

原项目：
未修改

不要把整个项目扫描结果全部塞进聊天。

详细信息放：

docs/INTAKE_REPORT.md

19. 典型调用方式

用户：

把 <外部项目路径> 接入我的 GameStudio。

Skill执行：

扫描 <外部项目路径>
↓
识别 Unity
↓
识别已有 README/GDD/TODO
↓
判断项目状态
↓
创建 GameStudio/02_OldGame
↓
保留 Unity 原始结构
↓
建立 docs/
↓
整理 GDD → GAME.md
↓
整理 TODO → TASKS.md
↓
整理Bug → BUGS.md
↓
整理已确定决策 → DECISIONS.md
↓
生成 AGENTS.md
↓
生成 README.md
↓
生成 INTAKE_REPORT.md
↓
验证项目
↓
更新 STUDIO.md
↓
完成

20. 严禁行为

本 Skill 默认禁止：

• 删除原项目文件
• 覆盖原项目
• 擅自修改核心玩法
• 擅自修改游戏数值
• 擅自重构代码
• 擅自升级引擎
• 擅自安装依赖
• 擅自合并 Git
• 把多个项目合并成一个项目
• 把推测写成确定事实
• 把讨论方案写入 DECISIONS.md
• 为了填满 GAME.md 而编造设计内容

21. 最终原则

这个 Skill 的核心不是“整理文件夹”。

而是：

外部项目
    ↓
扫描
    ↓
识别
    ↓
保留原项目结构
    ↓
补充标准AI文档层
    ↓
项目隔离
    ↓
进入GameStudio
    ↓
策划助手负责策划
    ↓
执行代理负责执行

最终形成：

GameStudio
│
├─ Studio层
│   ├─ STUDIO.md
│   └─ STUDIO_TASKS.md
│
├─ Project A
│   ├─ GAME.md
│   ├─ TASKS.md
│   ├─ BUGS.md
│   └─ DECISIONS.md
│
├─ Project B
│   ├─ GAME.md
│   ├─ TASKS.md
│   ├─ BUGS.md
│   └─ DECISIONS.md
│
└─ Project C
    ├─ GAME.md
    ├─ TASKS.md
    ├─ BUGS.md
    └─ DECISIONS.md

核心目标：让“接入一个新项目”变成标准化动作，而不是每次重新设计一套文件结构。

22. 美术资产归档补充

归档外部项目时，美术部分只做只读盘点与文档补层：

1. 扫描现有素材目录、图片格式、命名与尺寸，识别 .aseprite / .ase 源文件与导出产物。
2. 不移动、不重命名、不重绘、不改色、不裁切、不缩放、不删除任何素材。
3. 只补缺失的美术文档层：docs/ART_GUIDE.md、docs/ASSET_REGISTRY.md。模板来源：GameStudio/_shared/templates/。
4. 已有素材逐条登记 ASSET-XXX，记录源文件、导出文件、规格与状态；来源不明或未验证的写"待确认"。
5. 引擎原生资源目录（如 Unity Assets/、Godot assets/）优先保留，不强行改造成 assets/source/aseprite/。
6. 素材整理与状态流转交由 art-asset-manager 处理。
7. 归档本身不构成开发授权，不调用 执行代理。