GSP/README.md

# GSP

GSP = Game Specification Protocol。

GSP 是 AI 游戏制作引擎的底层游戏规格协议模块，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。

README 面向准备使用 GSP 的人类和 AI。它说明 GSP 的用途、边界和基本写法。严格字段规范以 `gsp.schema.json` 为准。

## 文件

| 文件 | 作用 |
|---|---|
| `README.md` | GSP 使用前说明。给人类和 AI 阅读。 |
| `gsp.schema.json` | GSP 第一版核心字段规范。使用 JSON Schema 表达，便于 AI、工具、编译器和实现模块识别。 |
| `TOOLKIT.md` | GSP Toolkit 第一版设计草案。记录工具集目标、核心命令、输入输出和暂缓功能。 |

## Toolkit 快速使用

第一版 Toolkit 使用 Go 实现。

构建：

```bash
go build -o bin/gsp ./cmd/gsp
```

常用命令：

```bash
gsp validate --root examples/lottery
gsp index --root examples/lottery --out .gsp/index.json
gsp trace page.lottery.main --root examples/lottery --depth -1
gsp flatten page.lottery.main --root examples/lottery --depth -1
gsp pack page.lottery.main --root examples/lottery --budget 12000
gsp graph page.lottery.main --root examples/lottery --format mermaid
gsp stage-check --root examples/lottery --stage implement
```

Toolkit 输出目录 `.gsp/` 默认不进入 Git。

## GSP 是什么

GSP 是一种游戏规格协议，不是具体游戏引擎、代码框架或资源格式。

它用于描述游戏制作中的设计对象和设计语境。一个 GSP 可以是：

- 一句设计方向
- 一个设计风格
- 一个按钮
- 一个页面
- 一个功能
- 一个玩法机制
- 一个反馈设计
- 一个音效表现
- 一个震动表现
- 一个集合或范围
- 一个逐步细化中的设计对象

GSP 不预设抽象和实体的硬边界。所有对象都先被视为 GSP，再由 `context`、`resolution`、`with`、`refines` 和当前任务共同解释。

## GSP 用来做什么

GSP 的核心作用是高效传递设计信息。

它用于支持：

- 人类和 AI 对齐游戏设计意图
- AI 与 AI 之间传递上下文
- 将模糊设计逐步细化为可实现规格
- 让编译器检查缺失、引用和阶段门槛
- 为运行时、目标平台、测试、验收等后续模块提供统一输入

GSP 不负责承载复杂的模块置信度、自我纠错、模块信誉、历史归因等机制。这些能力属于外部模块。

## 最小 GSP

最小合法 GSP 只有 `id`。

```yaml
id: feedback.positive
```

只有 `id` 的 GSP 是占位声明。它表示该设计对象存在，但尚未被细化。

## 基础 GSP

`context` 用于写入核心设计内容。

```yaml
id: feedback.positive
context: 积极反馈。用于让玩家在操作后获得明确、正向、值得继续的感受。
```

## 字段速览

| 字段 | 必需 | 作用 |
|---|---|---|
| `id` | 是 | 唯一身份。 |
| `context` | 否 | 核心设计内容。 |
| `resolution` | 否 | 清晰度 / 细化程度。 |
| `with` | 否 | 通用设计语境关系。 |
| `refines` | 否 | 单一细化来源。 |
| `type` | 否 | 辅助分类。 |

## 核心边界

- GSP 是单文件、单格式的设计协议。
- `id` 是唯一强制字段。
- `context` 可选。
- `resolution` 是清晰度软指标。
- `with` 是通用设计语境关系。
- `refines` 是单一细化来源。
- `type` 是辅助分类字段。
- GSP 不预设抽象和实体的硬边界。
- 置信度、自我纠错、模块信誉和历史归因属于外部模块，不进入 GSP 核心协议。

## resolution

`resolution` 表示 GSP 当前的清晰度。它是软指标，由人类或 AI 执行者声明。

| 等级 | 含义 |
|---|---|
| `L0` | 占位。只有 `id`，或几乎没有可用设计信息。 |
| `L1` | 有基础语义。能说明大概是什么。 |
| `L2` | 有结构化设计。能说明用途、边界和关联对象。 |
| `L3` | 可实现规格。足够交给目标平台或生成模块执行初版实现。 |
| `L4` | 平台绑定规格。已经明确组件、资源、事件、配置或实现约束。 |
| `L5` | 已实现并通过验证。 |

编译器可以按阶段检查 `resolution`，但 `resolution` 不证明设计质量。

## with

`with` 表示当前 GSP 需要与哪些 GSP 一起进入设计语境。

`with` 不区分使用、包含、依赖、分组、实体或抽象。

```yaml
id: page.lottery.main
context: 抽奖页面，需要表达奖励期待、抽取行为和结果反馈。
with:
  - ui.button.primary
  - feedback.positive
  - style.reward.light
```

`with` 也可以带局部说明：

```yaml
with:
  - id: ui.button.primary
    context: 用作主要抽奖操作入口。
```

## refines

`refines` 表示当前 GSP 是对另一个 GSP 的进一步细化。

`refines` 只支持单一来源。

```yaml
id: ui.button.reward_primary
refines: ui.button.primary
context: 奖励场景下的主按钮，比普通主按钮更强调正向点击反馈。
```

多个相关 GSP 写入 `with`。

## 注释

GSP 可以使用 YAML 注释。

```yaml
id: style.reward.light
context: 奖励表现要轻快、积极，但不要过度刺激。
# ai: 生成时控制节奏，不堆叠过多闪光和震动。
```

注释是辅助信息，可被编译器或上下文裁剪流程丢弃。核心内容写入正式字段。

## 使用顺序

使用 GSP 时按以下顺序理解：

1. 先读 `id`，确认身份。
2. 再读 `context`，理解核心设计语义。
3. 查看 `resolution`，判断当前细化程度。
4. 展开 `with`，补齐相关设计语境。
5. 查看 `refines`，确认是否来自某个更早或更粗的 GSP。
6. 需要严格校验时使用 `gsp.schema.json`。