GSP/toolkit/README.md

# GSP Toolkit

GSP Toolkit 是 GSP 的配套工具集。

它不负责生成最终游戏代码，也不替代设计判断。它的第一目标是让人类、AI 和后续实现模块高效使用 `.gsp` 文件。

## 1. 实现语言

第一版使用 Go 实现。

原因：

- 单二进制分发
- 跨平台运行
- 适合 CLI 工具
- 文件扫描、索引、JSON 输出和图结构处理足够稳定
- 不要求人类或 AI 阅读源码，只需要使用命令行能力

## 2. 输入

核心输入：

```text
.gsp
```

`.gsp` 文件内部遵循 YAML 风格格式。

默认工程结构：

```text
project/
  gsp.manifest
  design/
    *.gsp
```

未提供 manifest 时，Toolkit 默认扫描工程根目录下的 `design/`。

严格字段规范参考：

```text
../specs/versions/0.1/gsp.schema.json
../specs/versions/0.1/gsp.manifest.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`
- `title`
- 文件路径
- `type`
- `resolution`
- `with`
- `refines`

### 3.3 trace

查询某个 GSP 的关联链路。

用途：

- 查看直接 `with`
- 查看间接关联
- 查看 `refines` 来源
- 定位缺失引用

### 3.4 flatten

将某个 GSP 及其相关 GSP 展开为扁平上下文。

用途：

- 给 AI 提供完整上下文
- 给 AI 集群拆分任务
- 给实现模块提供输入

基本能力：

- 按深度展开
- 去重
- 检测循环
- 保持稳定输出顺序
- 支持白名单展开

### 3.5 pack

生成最小 AI 上下文包。

用途：

- 根据入口 GSP 生成 AI 可读上下文
- 控制上下文大小
- 裁剪无关内容
- 可按任务目标过滤 type

### 3.6 graph

生成 GSP 关系图或架构图。

输出形式：

- JSON 图数据
- Mermaid 图
- Markdown Mermaid 图
- Obsidian Canvas 图

图类型：

- `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 init
gsp validate
gsp ai-init
gsp version
gsp completion powershell
gsp index
gsp trace <id>
gsp flatten <id>
gsp pack <id>
gsp impact <id>
gsp message validate <file>
gsp graph <id>
gsp stage-check --stage implement
```

命令可使用 `--root` 指定扫描目录，使用 `--out` 输出文件。

示例：

```bash
go build -o ../bin/gsp ./cmd/gsp
../bin/gsp version
../bin/gsp validate --root ../examples/lottery
../bin/gsp flatten page.lottery.main --root ../examples/lottery --depth -1 --out ../.gsp/flattened.json
../bin/gsp pack page.lottery.main --root ../examples/lottery --for implement --format md --out ../.gsp/context-pack.md
../bin/gsp impact feedback.positive --root ../examples/lottery --format md --out ../.gsp/impact.md
../bin/gsp graph page.lottery.main --root ../examples/lottery --format mermaid --out ../.gsp/graph.mmd
../bin/gsp graph page.lottery.main --root ../examples/lottery --format md --out ../.gsp/graph.md
../bin/gsp graph page.lottery.main --root ../examples/lottery --format canvas --out ../.gsp/graph.canvas
../bin/gsp completion install powershell
```

## 5. 输出

第一版输出以机器可读和人类可读并重。

建议输出目录：

```text
.gsp/
```

建议输出文件：

```text
.gsp/index.json
.gsp/report.json
.gsp/graph.json
.gsp/graph.mmd
.gsp/graph.md
.gsp/graph.canvas
.gsp/context-pack.json
.gsp/context-pack.md
.gsp/flattened.json
.gsp/impact.md
```

## 6. 必须考虑的问题

第一版不追求极致性能，但必须处理：

- 循环引用
- 重复引用去重
- 展开深度限制
- 白名单 / 黑名单过滤
- 输出顺序稳定
- 缺失引用定位
- 大量 GSP 时的基础索引缓存
- 图过大时的裁剪
- AI 上下文预算

## 7. 暂缓功能

以下功能不进入第一版核心实现：

- 自动生成游戏代码
- 自动设计判断
- 模块置信度
- 自我纠错
- 模块信誉
- 历史归因
- 复杂可视化编辑器
- 具体平台 importer
- 具体 runtime binding

这些能力后续作为独立模块讨论。