Add GSP init and AI usage tooling

2026-05-06 19:40:55 +08:00
parent 67a1bf2600
commit 1478972e53
17 changed files with 870 additions and 8 deletions
--- a/specs/README.md
+++ b/specs/README.md
@@ -0,0 +1,7 @@
+# GSP Specs
+
+GSP specifications are versioned under `versions/`.
+
+Current version: `0.1`.
+
+Each toolkit release declares its default GSP version and supported GSP versions. A GSP project declares its protocol version in `gsp.manifest`.
--- a/specs/versions/0.1/README.md
+++ b/specs/versions/0.1/README.md
@@ -0,0 +1,170 @@
+# GSP
+
+GSP = Game Specification Protocol。
+
+GSP 是通用游戏规格协议，用于在人类、AI、工具、运行时、实现模块、测试与验收之间传递游戏设计信息。
+
+README 面向准备使用 GSP 语言的人类和 AI。它说明 GSP 的用途、边界和基本写法。严格字段规范以 `gsp.schema.json` 为准。
+
+## 文件
+
+| 文件 | 作用 |
+|---|---|
+| `README.md` | GSP 语言使用前说明。给人类和 AI 阅读。 |
+| `gsp.schema.json` | GSP 第一版核心字段规范。使用 JSON Schema 表达，便于 AI、工具、编译器和实现模块识别。 |
+| `gsp.manifest.schema.json` | GSP 工程 manifest 字段规范。 |
+| `commands.md` | GSP Toolkit 命令规范。 |
+| `ai-usage.md` | GSP 项目 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` 文件放在 GSP 工程根目录的 `design/` 目录下。
+
+## 基础 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`。
--- a/specs/versions/0.1/ai-usage.md
+++ b/specs/versions/0.1/ai-usage.md
@@ -0,0 +1,18 @@
+# AI Usage 0.1
+
+- Read `gsp.manifest` first.
+- Treat `design/` as the default GSP source directory.
+- `.gsp` files use YAML.
+- Preserve `id`; do not rename it unless explicitly requested.
+- `id` is the unique identity of a GSP unit.
+- Use only fields valid for the declared GSP version.
+- `with` means related design context.
+- `refines` means single-source refinement.
+- Empty `context` means placeholder.
+- Do not invent missing referenced GSPs silently.
+- Use `gsp validate` after editing GSP files.
+- Use `gsp index` to locate GSP units.
+- Use `gsp trace <id>` to inspect relations.
+- Use `gsp flatten <id>` before implementation or task splitting.
+- Use `gsp pack <id>` when a compact AI context is needed.
+- Use `gsp stage-check --stage <stage>` before stage handoff.
--- a/specs/versions/0.1/commands.md
+++ b/specs/versions/0.1/commands.md
@@ -0,0 +1,106 @@
+# GSP Commands 0.1
+
+## init
+
+Create a minimal GSP project.
+
+```bash
+gsp init [path] [--name project-name] [--entry project.entry] [--force]
+```
+
+Generated structure:
+
+```text
+project/
+  gsp.manifest
+  design/
+    project.entry.gsp
+```
+
+## ai-init
+
+Create AI-facing usage files for a GSP project.
+
+```bash
+gsp ai-init [--root .] [--agents] [--skill generic|codex] [--all] [--force]
+```
+
+Default output:
+
+```text
+README.md
+AI_USAGE.md
+```
+
+Optional output:
+
+```text
+AGENTS.md
+skills/gsp/SKILL.md
+.codex/skills/gsp/SKILL.md
+```
+
+## version
+
+Print toolkit and protocol versions.
+
+```bash
+gsp version
+gsp version --json
+```
+
+## validate
+
+Validate GSP files and references.
+
+```bash
+gsp validate [--root .] [--out report.json]
+```
+
+## index
+
+Build a stable GSP index.
+
+```bash
+gsp index [--root .] [--out index.json]
+```
+
+## trace
+
+Inspect relation chains from one GSP id.
+
+```bash
+gsp trace <id> [--root .] [--depth 3] [--out trace.json]
+```
+
+## flatten
+
+Expand one GSP id into a flat context.
+
+```bash
+gsp flatten <id> [--root .] [--depth 3] [--include-type a,b] [--exclude-type a,b] [--out flattened.json]
+```
+
+## pack
+
+Create a compact AI context pack.
+
+```bash
+gsp pack <id> [--root .] [--depth 3] [--budget 12000] [--out context-pack.json]
+```
+
+## graph
+
+Generate a relation graph.
+
+```bash
+gsp graph [id] [--root .] [--depth 3] [--format json|mermaid] [--out graph.json]
+```
+
+## stage-check
+
+Check minimum resolution for a stage.
+
+```bash
+gsp stage-check --stage implement [--root .] [--out stage-report.json]
+```
--- a/specs/versions/0.1/gsp.manifest.schema.json
+++ b/specs/versions/0.1/gsp.manifest.schema.json
@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gsp.local/schema/gsp.manifest.schema.json",
+  "title": "GSP Manifest",
+  "description": "Game Specification Protocol project manifest schema.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "gspVersion": {
+      "type": "string",
+      "description": "GSP language version used by this project."
+    },
+    "toolkitVersion": {
+      "type": "string",
+      "description": "Expected GSP Toolkit version."
+    },
+    "project": {
+      "type": "string",
+      "description": "Project id or name."
+    },
+    "entry": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Entry GSP ids."
+    },
+    "scan": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Directories or files scanned by the Toolkit. Defaults to design."
+    },
+    "stageRules": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "minResolution": {
+            "type": "string",
+            "enum": ["L0", "L1", "L2", "L3", "L4", "L5"]
+          }
+        }
+      }
+    },
+    "types": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "output": {
+      "type": "string",
+      "description": "Default Toolkit output directory."
+    }
+  }
+}
--- a/specs/versions/0.1/gsp.schema.json
+++ b/specs/versions/0.1/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."
+    }
+  }
+}