GSP/README.md

GSP

GSP = Game Specification Protocol。

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

目录结构

GSP/
  specs/         GSP 版本化协议规范与 schema
  toolkit/       GSP Toolkit Go CLI 源码
  examples/      示例 GSP 工程

生成产物默认放在：

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

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

如何生成 Toolkit

需要本机安装 Go。

从仓库根目录执行：

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

生成后得到：

bin/gsp.exe

如何生成 GSP 输出

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

.\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 graph page.lottery.main --root examples\lottery --format md --out .gsp\graph.md
.\bin\gsp.exe graph page.lottery.main --root examples\lottery --format canvas --out .gsp\graph.canvas
.\bin\gsp.exe stage-check --root examples\lottery --stage implement --out .gsp\stage-report.json
.\bin\gsp.exe completion powershell

输出文件：

.gsp/report.json
.gsp/index.json
.gsp/flattened.json
.gsp/context-pack.json
.gsp/graph.mmd
.gsp/graph.md
.gsp/graph.canvas
.gsp/stage-report.json

文档入口

文档	作用
specs/README.md	GSP 规范版本入口。
specs/versions/0.1/README.md	GSP 0.1 语言说明。
specs/versions/0.1/gsp.schema.json	GSP 0.1 核心字段 schema。
specs/versions/0.1/gsp.manifest.schema.json	GSP 0.1 工程 manifest schema。
specs/versions/0.1/commands.md	GSP 0.1 命令规范。
specs/versions/0.1/ai-usage.md	GSP 0.1 AI 使用规则。
toolkit/README.md	GSP Toolkit 命令与实现说明。

GSP 工程结构

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

project/
  gsp.manifest
  design/
    *.gsp

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

AI 使用入口

给当前 GSP 工程生成 AI 友好入口：

gsp ai-init

默认生成：

README.md
AI_USAGE.md

可选生成代理说明或 skill 入口：

gsp ai-init --agents
gsp ai-init --skill generic
gsp ai-init --skill codex
gsp ai-init --all

安装为命令

Windows：

powershell -ExecutionPolicy Bypass -File .\toolkit\scripts\install.ps1
gsp version

macOS：

sh ./toolkit/scripts/install.sh
gsp version

安装后可以在任意目录使用：

gsp init
gsp ai-init
gsp version
gsp completion install powershell
gsp validate
gsp index
gsp flatten <id>
gsp graph <id>
gsp stage-check --stage implement

初始化 GSP 工程

在当前目录初始化：

gsp init

在指定目录初始化：

gsp init path/to/project --name project-name --entry project.entry

初始化结果：

project/
  gsp.manifest
  design/
    project.entry.gsp

已有 gsp.manifest 或入口 .gsp 时，gsp init 默认不会覆盖。需要重建初始化文件时使用：

gsp init path/to/project --force

命令补全

输出补全脚本：

gsp completion powershell
gsp completion bash
gsp completion zsh
gsp completion fish

安装 PowerShell 补全：

gsp completion install powershell

安装后重新打开 PowerShell，gsp <Tab> 会补全子命令，gsp graph --format <Tab> 会补全格式，gsp graph <Tab> 会读取当前工程的 GSP id。