diff --git a/README.md b/README.md index c9ab7df..b455a65 100644 --- a/README.md +++ b/README.md @@ -2,189 +2,72 @@ GSP = Game Specification Protocol。 -GSP 是 AI 游戏制作引擎的底层游戏规格协议模块，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。 +GSP 是一个通用游戏规格协议与配套工具链，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。 -README 面向准备使用 GSP 的人类和 AI。它说明 GSP 的用途、边界和基本写法。严格字段规范以 `gsp.schema.json` 为准。 +## 目录结构 -## 文件 +```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 +``` + +## 文档入口 + +| 文档 | 作用 | |---|---| -| `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`。 +| `language/README.md` | GSP 语言说明。 | +| `language/gsp.schema.json` | GSP 核心字段 schema。 | +| `toolkit/README.md` | GSP Toolkit 命令与实现说明。 | diff --git a/language/README.md b/language/README.md new file mode 100644 index 0000000..dd201f1 --- /dev/null +++ b/language/README.md @@ -0,0 +1,165 @@ +# 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、工具、编译器和实现模块识别。 | + +## 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`。 diff --git a/gsp.schema.json b/language/gsp.schema.json similarity index 100% rename from gsp.schema.json rename to language/gsp.schema.json diff --git a/TOOLKIT.md b/toolkit/README.md similarity index 91% rename from TOOLKIT.md rename to toolkit/README.md index 14396b3..8985585 100644 --- a/TOOLKIT.md +++ b/toolkit/README.md @@ -29,7 +29,7 @@ GSP Toolkit 是 GSP 的配套工具集。 严格字段规范参考： ```text -gsp.schema.json +../language/gsp.schema.json ``` 项目级入口配置待讨论，暂定方向： @@ -167,9 +167,10 @@ gsp stage-check --stage implement 示例： ```bash -gsp validate --root examples/lottery -gsp flatten page.lottery.main --root examples/lottery --depth -1 --out .gsp/flattened.json -gsp graph page.lottery.main --root examples/lottery --format mermaid --out .gsp/graph.mmd +go build -o ../bin/gsp ./cmd/gsp +../bin/gsp validate --root ../examples/lottery +../bin/gsp flatten page.lottery.main --root ../examples/lottery --depth -1 --out ../.gsp/flattened.json +../bin/gsp graph page.lottery.main --root ../examples/lottery --format mermaid --out ../.gsp/graph.mmd ``` ## 5. 输出 diff --git a/cmd/gsp/main.go b/toolkit/cmd/gsp/main.go similarity index 100% rename from cmd/gsp/main.go rename to toolkit/cmd/gsp/main.go diff --git a/go.mod b/toolkit/go.mod similarity index 100% rename from go.mod rename to toolkit/go.mod diff --git a/go.sum b/toolkit/go.sum similarity index 100% rename from go.sum rename to toolkit/go.sum diff --git a/internal/gsp/graph.go b/toolkit/internal/gsp/graph.go similarity index 100% rename from internal/gsp/graph.go rename to toolkit/internal/gsp/graph.go diff --git a/internal/gsp/load.go b/toolkit/internal/gsp/load.go similarity index 100% rename from internal/gsp/load.go rename to toolkit/internal/gsp/load.go diff --git a/internal/gsp/model.go b/toolkit/internal/gsp/model.go similarity index 100% rename from internal/gsp/model.go rename to toolkit/internal/gsp/model.go diff --git a/internal/gsp/project.go b/toolkit/internal/gsp/project.go similarity index 100% rename from internal/gsp/project.go rename to toolkit/internal/gsp/project.go diff --git a/internal/gsp/project_test.go b/toolkit/internal/gsp/project_test.go similarity index 100% rename from internal/gsp/project_test.go rename to toolkit/internal/gsp/project_test.go