GSP/specs/versions/0.1/README.md

# GSP

GSP = Game Specification Protocol。

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

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

## 文件

| 文件 | 作用 |
|---|---|
| `README.md` | GSP 语言使用前说明。给人类和 AI 阅读。 |
| `gsp.schema.json` | GSP 第一版核心字段规范。使用 JSON Schema 表达，便于 AI、工具、编译器和实现模块识别。 |
| `gsp.manifest.schema.json` | GSP 工程 manifest 字段规范。 |
| `gsp.message.schema.json` | GSP agent 通信消息字段规范。 |
| `commands.md` | GSP Toolkit 命令规范。 |
| `ai-usage.md` | GSP 项目 AI 使用规则。 |
| `message.md` | GSP Message 说明。 |

## GSP 是什么

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

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

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

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

## GSP 用来做什么

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

它用于支持：

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

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

## 最小 GSP

最小合法 GSP 只有 `id`。

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

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

默认情况下，`.gsp` 文件放在 GSP 工程根目录的 `design/` 目录下。

## 基础 GSP

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

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

## 字段速览

| 字段 | 必需 | 作用 |
|---|---|---|
| `id` | 是 | 唯一身份。 |
| `title` | 否 | 展示标题。 |
| `context` | 否 | 核心设计内容。 |
| `resolution` | 否 | 清晰度 / 细化程度。 |
| `with` | 否 | 通用设计语境关系。 |
| `refines` | 否 | 单一细化来源。 |
| `type` | 否 | 辅助分类。 |
| `links` | 否 | 关联路径、文件夹、URL 或外部地址。 |

## 核心边界

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

## resolution

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

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

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

## title

`title` 表示 GSP 的展示标题。

```yaml
id: page.lottery.main
title: 抽奖页面
```

工具在图形、索引和 AI 入口中优先使用 `title` 展示。没有 `title` 时使用 `id`。

## links

`links` 表示当前 GSP 关联到的路径、文件夹、URL 或外部地址。

```yaml
links: assets/ui/button_primary.png
```

```yaml
links:
  - assets/ui/button_primary.png
  - https://example.com/style-guide
```

```yaml
links:
  - path: runtime/ui/RewardButton.prefab
    role: binding
  - path: docs/reward-style.md
    role: reference
```

对象写法只使用 `path`、`role` 和 `context`。`role` 默认是 `reference`。

内置 `role`：

| role | 含义 |
|---|---|
| `reference` | 参考资料。 |
| `source` | 原始来源或素材来源。 |
| `binding` | 与实现对象绑定。 |
| `output` | 输出物。 |
| `evidence` | 验收、测试或结论依据。 |

## 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. 再读 `title`，确认展示名称。
3. 再读 `context`，理解核心设计语义。
4. 查看 `resolution`，判断当前细化程度。
5. 展开 `with`，补齐相关设计语境。
6. 查看 `refines`，确认是否来自某个更早或更粗的 GSP。
7. 需要严格校验时使用 `gsp.schema.json`。