Initial GSP specification

2026-05-06 18:28:04 +08:00
commit 61b7a9a485
4 changed files with 456 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,15 @@
+# Generated toolkit outputs
+.gsp/
+
+# Build outputs
+bin/
+dist/
+build/
+*.exe
+
+# Logs
+*.log
+
+# OS noise
+.DS_Store
+Thumbs.db
--- a/README.md
+++ b/README.md
@@ -0,0 +1,166 @@
+# GSP
+
+GSP = Game Specification Protocol。
+
+GSP 是 AI 游戏制作引擎的底层游戏规格协议模块，用于在人类、AI、工具、H5、Unity、测试与验收之间传递游戏设计信息。
+
+README 面向准备使用 GSP 的人类和 AI。它说明 GSP 的用途、边界和基本写法。严格字段规范以 `gsp.schema.json` 为准。
+
+## 文件
+
+| 文件 | 作用 |
+|---|---|
+| `README.md` | GSP 使用前说明。给人类和 AI 阅读。 |
+| `gsp.schema.json` | GSP 第一版核心字段规范。使用 JSON Schema 表达，便于 AI、工具、编译器和实现模块识别。 |
+| `TOOLKIT.md` | GSP Toolkit 第一版设计草案。记录工具集目标、核心命令、输入输出和暂缓功能。 |
+
+## GSP 是什么
+
+GSP 是一种游戏规格协议，不是具体游戏引擎、代码框架或资源格式。
+
+它用于描述游戏制作中的设计对象和设计语境。一个 GSP 可以是：
+
+- 一句设计方向
+- 一个设计风格
+- 一个按钮
+- 一个页面
+- 一个功能
+- 一个玩法机制
+- 一个反馈设计
+- 一个音效表现
+- 一个震动表现
+- 一个集合或范围
+- 一个逐步细化中的设计对象
+
+GSP 不预设抽象和实体的硬边界。所有对象都先被视为 GSP，再由 `context`、`resolution`、`with`、`refines` 和当前任务共同解释。
+
+## GSP 用来做什么
+
+GSP 的核心作用是高效传递设计信息。
+
+它用于支持：
+
+- 人类和 AI 对齐游戏设计意图
+- AI 与 AI 之间传递上下文
+- 将模糊设计逐步细化为可实现规格
+- 让编译器检查缺失、引用和阶段门槛
+- 为 H5、Unity、测试、验收等后续模块提供统一输入
+
+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` | 可实现规格。足够交给 H5 / Unity / 生成模块执行初版实现。 |
+| `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`。
--- a/TOOLKIT.md
+++ b/TOOLKIT.md
@@ -0,0 +1,215 @@
+# GSP Toolkit 设计草案
+
+GSP Toolkit 是 GSP 的配套工具集。
+
+它不负责生成最终游戏代码，也不替代设计判断。它的第一目标是让人类、AI 和后续实现模块高效使用 `.gsp` 文件。
+
+## 1. 实现语言
+
+第一版使用 Go 实现。
+
+原因：
+
+- 单二进制分发
+- 跨平台运行
+- 适合 CLI 工具
+- 文件扫描、索引、JSON 输出和图结构处理足够稳定
+- 不要求人类或 AI 阅读源码，只需要使用命令行能力
+
+## 2. 输入
+
+核心输入：
+
+```text
+.gsp
+```
+
+`.gsp` 文件内部遵循 YAML 风格格式。
+
+严格字段规范参考：
+
+```text
+gsp.schema.json
+```
+
+项目级入口配置待讨论，暂定方向：
+
+```text
+gsp.manifest
+```
+
+manifest 可用于声明：
+
+- GSP 语言版本
+- Toolkit 版本
+- 项目入口 GSP
+- 扫描范围
+- 阶段规则
+- type 注册
+- 自定义字段注册
+- 输出目录
+
+## 3. 第一版核心功能
+
+### 3.1 validate
+
+检查 `.gsp` 文件是否符合核心规则。
+
+检查内容：
+
+- `id` 是否存在
+- `id` 是否唯一
+- YAML 格式是否合法
+- `resolution` 是否在允许范围内
+- `with` 引用是否存在
+- `refines` 引用是否存在
+- `refines` 是否为单一来源
+
+### 3.2 index
+
+扫描项目中的 `.gsp` 文件并建立索引。
+
+索引内容：
+
+- `id`
+- 文件路径
+- `type`
+- `resolution`
+- `with`
+- `refines`
+
+### 3.3 trace
+
+查询某个 GSP 的关联链路。
+
+用途：
+
+- 查看直接 `with`
+- 查看间接关联
+- 查看 `refines` 来源
+- 定位缺失引用
+
+### 3.4 flatten
+
+将某个 GSP 及其相关 GSP 展开为扁平上下文。
+
+用途：
+
+- 给 AI 提供完整上下文
+- 给 AI 集群拆分任务
+- 给实现模块提供输入
+
+基本能力：
+
+- 按深度展开
+- 去重
+- 检测循环
+- 保持稳定输出顺序
+- 支持白名单展开
+
+### 3.5 pack
+
+生成最小 AI 上下文包。
+
+用途：
+
+- 根据入口 GSP 生成 AI 可读上下文
+- 控制上下文大小
+- 裁剪无关内容
+- 可按任务目标过滤 type、resolution 或路径
+
+### 3.6 graph
+
+生成 GSP 关系图或架构图。
+
+输出形式：
+
+- JSON 图数据
+- Mermaid 图
+
+图类型：
+
+- `with` 关系图
+- `refines` 细化链
+- type 分布图
+- resolution 分布图
+- 缺失引用图
+- 阶段就绪图
+
+### 3.7 stage-check
+
+按阶段检查 GSP 是否达到最低可用程度。
+
+示例阶段：
+
+| 阶段 | 目标 |
+|---|---|
+| design | 允许 L0 / L1 |
+| integrate | 核心 GSP 达到 L2 |
+| implement | 实现链路 GSP 达到 L3 |
+| bind | 平台相关 GSP 达到 L4 |
+| release | 关键 GSP 达到 L5 |
+
+## 4. 第一版命令草案
+
+```bash
+gsp validate
+gsp index
+gsp trace <id>
+gsp flatten <id>
+gsp pack <id>
+gsp graph <id>
+gsp stage-check --stage implement
+```
+
+## 5. 输出
+
+第一版输出以机器可读和人类可读并重。
+
+建议输出目录：
+
+```text
+.gsp/
+```
+
+建议输出文件：
+
+```text
+.gsp/index.json
+.gsp/report.json
+.gsp/graph.json
+.gsp/graph.mmd
+.gsp/context-pack.json
+.gsp/flattened.json
+```
+
+## 6. 必须考虑的问题
+
+第一版不追求极致性能，但必须处理：
+
+- 循环引用
+- 重复引用去重
+- 展开深度限制
+- 白名单 / 黑名单过滤
+- 输出顺序稳定
+- 缺失引用定位
+- 大量 GSP 时的基础索引缓存
+- 图过大时的裁剪
+- AI 上下文预算
+
+## 7. 暂缓功能
+
+以下功能不进入第一版核心实现：
+
+- 自动生成游戏代码
+- 自动设计判断
+- 模块置信度
+- 自我纠错
+- 模块信誉
+- 历史归因
+- 复杂可视化编辑器
+- Unity importer
+- H5 runtime binding
+
+这些能力后续作为独立模块讨论。
+
--- a/gsp.schema.json
+++ b/gsp.schema.json
@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gsp.local/schema/gsp.schema.json",
+  "title": "GSP",
+  "description": "Game Specification Protocol core unit schema.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["id"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique GSP id in the current project."
+    },
+    "context": {
+      "type": "string",
+      "description": "Core design context. Optional. Empty or missing context means the GSP can be treated as a placeholder."
+    },
+    "resolution": {
+      "type": "string",
+      "enum": ["L0", "L1", "L2", "L3", "L4", "L5"],
+      "description": "Soft clarity level. Used by tools and agents for stage checks, not as proof of design quality."
+    },
+    "with": {
+      "type": "array",
+      "description": "General design-context relation. Items are GSP ids or local relation objects.",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "minLength": 1
+          },
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "context": {
+                "type": "string"
+              }
+            }
+          }
+        ]
+      }
+    },
+    "refines": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single GSP id refined by this GSP."
+    },
+    "type": {
+      "type": "string",
+      "description": "Optional helper category for search, display, compiler hints and context pruning."
+    }
+  }
+}