GSP/README.md

# GSP

GSP = Game Specification Protocol。

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

## 目录结构

```text
GSP/
  language/      GSP 语言定义与 schema
  toolkit/       GSP Toolkit Go CLI 源码
  examples/      示例 GSP 工程
```

生成产物默认放在：

```text
bin/             本地构建出的 CLI，可删除
.gsp/            Toolkit 输出结果，可删除
```

这两个目录默认不进入 Git。

## 如何生成 Toolkit

需要本机安装 Go。

从仓库根目录执行：

```powershell
cd toolkit
go build -o ..\bin\gsp.exe .\cmd\gsp
cd ..
```

生成后得到：

```text
bin/gsp.exe
```

## 如何生成 GSP 输出

使用示例目录生成检查报告、索引、扁平上下文、上下文包和关系图：

```powershell
.\bin\gsp.exe validate --root examples\lottery --out .gsp\report.json
.\bin\gsp.exe index --root examples\lottery --out .gsp\index.json
.\bin\gsp.exe flatten page.lottery.main --root examples\lottery --depth -1 --out .gsp\flattened.json
.\bin\gsp.exe pack page.lottery.main --root examples\lottery --depth -1 --budget 12000 --out .gsp\context-pack.json
.\bin\gsp.exe graph page.lottery.main --root examples\lottery --format mermaid --out .gsp\graph.mmd
.\bin\gsp.exe stage-check --root examples\lottery --stage implement --out .gsp\stage-report.json
```

输出文件：

```text
.gsp/report.json
.gsp/index.json
.gsp/flattened.json
.gsp/context-pack.json
.gsp/graph.mmd
.gsp/stage-report.json
```

## 文档入口

| 文档 | 作用 |
|---|---|
| `language/README.md` | GSP 语言说明。 |
| `language/gsp.schema.json` | GSP 核心字段 schema。 |
| `language/gsp.manifest.schema.json` | GSP 工程 manifest schema。 |
| `toolkit/README.md` | GSP Toolkit 命令与实现说明。 |

## GSP 工程结构

GSP 工程默认使用以下结构：

```text
project/
  gsp.manifest
  design/
    *.gsp
```

Toolkit 默认从工程根目录的 `design/` 目录扫描 `.gsp` 文件。`gsp.manifest` 可声明语言版本、Toolkit 版本、入口 GSP、扫描范围、阶段规则和 type 列表。