257 lines
4.7 KiB
Markdown
257 lines
4.7 KiB
Markdown
# 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
|
||
|
||
这些能力后续作为独立模块讨论。
|