Reorganize GSP module layout

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 命令与实现说明。 |

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`。

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. 输出