219 lines
5.2 KiB
Markdown
219 lines
5.2 KiB
Markdown
# GSP
|
||
|
||
GSP = Game Specification Protocol。
|
||
|
||
GSP 是一个通用游戏规格协议与配套工具链，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
GSP/
|
||
specs/ 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 pack page.lottery.main --root examples\lottery --for implement --stage implement --format md --out .gsp\context-pack.md
|
||
.\bin\gsp.exe links page.lottery.main --root examples\lottery --format md --out .gsp\links.md
|
||
.\bin\gsp.exe impact feedback.positive --root examples\lottery --format md --out .gsp\impact.md
|
||
.\bin\gsp.exe impact feedback.positive --root examples\lottery --format canvas --out .gsp\impact.canvas
|
||
.\bin\gsp.exe message validate messages\implement-page.gspmsg --root examples\lottery --out .gsp\message-report.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
|
||
```
|
||
|
||
输出文件：
|
||
|
||
```text
|
||
.gsp/report.json
|
||
.gsp/index.json
|
||
.gsp/flattened.json
|
||
.gsp/context-pack.json
|
||
.gsp/context-pack.md
|
||
.gsp/links.md
|
||
.gsp/impact.md
|
||
.gsp/impact.canvas
|
||
.gsp/message-report.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/gsp.fields.schema.json` | GSP 0.1 自定义字段注册 schema。 |
|
||
| `specs/versions/0.1/gsp.message.schema.json` | GSP 0.1 agent 通信消息 schema。 |
|
||
| `specs/versions/0.1/commands.md` | GSP 0.1 命令规范。 |
|
||
| `specs/versions/0.1/ai-usage.md` | GSP 0.1 AI 使用规则。 |
|
||
| `specs/versions/0.1/message.md` | GSP Message 说明。 |
|
||
| `toolkit/README.md` | GSP Toolkit 命令与实现说明。 |
|
||
|
||
## GSP 工程结构
|
||
|
||
GSP 工程默认使用以下结构：
|
||
|
||
```text
|
||
project/
|
||
gsp.manifest
|
||
gsp.fields
|
||
design/
|
||
*.gsp
|
||
```
|
||
|
||
Toolkit 默认从工程根目录的 `design/` 目录扫描 `.gsp` 文件。`gsp.manifest` 可声明语言版本、Toolkit 版本、入口 GSP、扫描范围、阶段规则和 type 列表。
|
||
|
||
## AI 使用入口
|
||
|
||
给当前 GSP 工程生成 AI 友好入口：
|
||
|
||
```bash
|
||
gsp ai-init
|
||
```
|
||
|
||
默认生成：
|
||
|
||
```text
|
||
README.md
|
||
AI_USAGE.md
|
||
```
|
||
|
||
可选生成代理说明或 skill 入口：
|
||
|
||
```bash
|
||
gsp ai-init --agents
|
||
gsp ai-init --skill generic
|
||
gsp ai-init --skill codex
|
||
gsp ai-init --all
|
||
```
|
||
|
||
## 安装为命令
|
||
|
||
Windows：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\toolkit\scripts\install.ps1
|
||
gsp version
|
||
```
|
||
|
||
macOS：
|
||
|
||
```bash
|
||
sh ./toolkit/scripts/install.sh
|
||
gsp version
|
||
```
|
||
|
||
安装后可以在任意目录使用：
|
||
|
||
```bash
|
||
gsp init
|
||
gsp ai-init
|
||
gsp version
|
||
gsp completion install powershell
|
||
gsp validate
|
||
gsp index
|
||
gsp fields list
|
||
gsp fields validate
|
||
gsp flatten <id>
|
||
gsp pack <id> --for implement --format md
|
||
gsp links <id> --format md
|
||
gsp impact <id> --format md
|
||
gsp message validate message.gspmsg
|
||
gsp graph <id>
|
||
gsp stage-check --stage implement
|
||
```
|
||
|
||
## 初始化 GSP 工程
|
||
|
||
在当前目录初始化：
|
||
|
||
```bash
|
||
gsp init
|
||
```
|
||
|
||
在指定目录初始化：
|
||
|
||
```bash
|
||
gsp init path/to/project --name project-name --entry project.entry
|
||
```
|
||
|
||
初始化结果：
|
||
|
||
```text
|
||
project/
|
||
gsp.manifest
|
||
gsp.fields
|
||
design/
|
||
project.entry.gsp
|
||
```
|
||
|
||
已有 `gsp.manifest` 或入口 `.gsp` 时，`gsp init` 默认不会覆盖。需要重建初始化文件时使用：
|
||
|
||
```bash
|
||
gsp init path/to/project --force
|
||
```
|
||
|
||
## 命令补全
|
||
|
||
输出补全脚本：
|
||
|
||
```bash
|
||
gsp completion powershell
|
||
gsp completion bash
|
||
gsp completion zsh
|
||
gsp completion fish
|
||
```
|
||
|
||
安装 PowerShell 补全：
|
||
|
||
```powershell
|
||
gsp completion install powershell
|
||
```
|
||
|
||
安装后重新打开 PowerShell，`gsp <Tab>` 会补全子命令，`gsp graph --format <Tab>` 会补全格式，`gsp graph <Tab>` 会读取当前工程的 GSP id。
|