GSP/toolkit

GSP Toolkit

GSP Toolkit 是 GSP 的配套工具集。

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

1. 实现语言

第一版使用 Go 实现。

原因：

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

2. 输入

核心输入：

.gsp

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

默认工程结构：

project/
  gsp.manifest
  design/
    *.gsp

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

严格字段规范参考：

../specs/versions/0.1/gsp.schema.json
../specs/versions/0.1/gsp.manifest.schema.json

项目级入口配置：

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

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. 第一版命令

gsp init
gsp validate
gsp ai-init
gsp version
gsp index
gsp trace <id>
gsp flatten <id>
gsp pack <id>
gsp graph <id>
gsp stage-check --stage implement

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

示例：

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 graph page.lottery.main --root ../examples/lottery --format mermaid --out ../.gsp/graph.mmd

5. 输出

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

建议输出目录：

.gsp/

建议输出文件：

.gsp/index.json
.gsp/report.json
.gsp/graph.json
.gsp/graph.mmd
.gsp/context-pack.json
.gsp/flattened.json

6. 必须考虑的问题

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

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

7. 暂缓功能

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

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

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