se-dev-script

SE Dev Script Skill

Space Engineers 1 中的游戏内脚本（可编程方块，简称 PB）开发。

⚠️ 重要：命令在 UNIX shell 中运行。请使用 bash 语法。在 Windows 上使用 BusyBox；在 Linux 上使用原生 shell。

示例：

• ✅ test -f file.txt && echo exists
• ✅ ls -la | head -10
• ❌ if exist file.txt (echo exists) - 无法运行

操作：

• prepare：执行一次性准备（Windows 上运行 Prepare.bat，Linux 上运行 prepare.sh）
• bash：通过 busybox 运行 UNIX shell 命令
• search：使用 search_scripts.py 搜索脚本代码

路由决策

按顺序检查这些模式——匹配到的第一个模式优先：

优先级	模式	示例	路由
1	空调用或不带参数的调用	se-dev-script	显示此帮助
2	准备相关关键词	se-dev-script prepare、se-dev-script setup、se-dev-script init	prepare
3	bash/shell 相关关键词	se-dev-script bash、se-dev-script grep、se-dev-script cat	bash
4	搜索相关关键词	se-dev-script search、se-dev-script find class、se-dev-script lookup	search

开始使用

⚠️ 重要：运行任何命令前，请先阅读 CommandExecution.md，以避免常见错误导致命令失败。

如果此文件夹中缺少 Prepare.DONE 文件，必须先执行一次性准备步骤。请参阅 prepare 操作。

必备文档

• CommandExecution.md - ⚠️ 请先阅读此文档 - Windows 命令执行详情；在 Linux 上请保持使用 bash 语法并运行 prepare.sh

脚本开发

只能使用符合 PB API 白名单的名称：PBApiWhitelist.txt 白名单由 MDK2 的 Mdk.Extractor 从游戏版本 1.208.015 导出。

游戏内（PB）脚本会发布到 Steam Workshop 或 Mod.IO，主要发布在前者。 游戏会在加载到 PB 或加载世界时编译游戏内脚本（前提是 PB 已加载脚本）， 并强制执行 PB 脚本 API 白名单，以确保安全性。 脚本不会导致游戏崩溃，因为游戏会捕获任何异常并终止脚本。 如果玩家或服务管理员没有设置具体的资源使用限制，脚本仍可能导致游戏卡顿。

玩家加载脚本时，源代码大小限制为 100,000 字节。ScriptDev 插件可以从本地文件加载 更多代码到离线（本地）游戏中进行测试，因此无需压缩源代码即可测试脚本， 便于获取完整详细的异常回溯信息。

使用 se-dev-game-code 阅读你所调用的确切代码。如果已安装 se-dev-game-book 手册，请先阅读以了解游戏系统的工作原理以及涉及哪些类型；如果未安装，则也要搜索游戏代码以了解这些内容。 为提高效率，请只搜索与 PB API 白名单中的名称对应的游戏代码。

Graphify 图谱

准备过程会为本地 PB 脚本文件夹（或 SE_DEV_SCRIPT_PROJECT_ROOT）单独构建 Graphify 图谱。使用快速 Rust 聚类后端（通过 uv 使用 Python 3.12， 并自动配置）时，准备过程会自动构建图谱；这个语料库很小，因此无论哪种方式都很快。如果无法使用快速后端，则需通过 SE_DEV_GRAPHIFY=1 选择启用；SE_DEV_GRAPHIFY=0 可禁用。按需阅读——日常搜索时可跳过：通过 GraphifyPrepare.md 构建，通过 GraphifyUsage.md 查询。

文件夹结构

• Data/ — 指向每用户持久化脚本数据文件夹的联接/符号链接（Windows 上为 %USERPROFILE%\.se-dev\script，Linux 上为 ~/.se-dev/script）。持久化技能数据存储于此：
  • Data/scripts.json — 所有已安装 PB 脚本的快速清单。
  • Data/script_hashes.json — 每个脚本的聚合 sha1，供索引器检测更改。
  • Data/CodeIndex/ — 完整的 Tree-sitter C# 索引（每个类别一个 CSV，以及层级树）。
• LocalScripts/ — 指向游戏本地脚本文件夹的联接/符号链接（Windows 上为 %AppData%\SpaceEngineers\IngameScripts\local，Linux 上为 Proton 对应的 appdata 路径）。
• Steam 创意工坊内容直接从 Steam 文件夹读取；不会复制到技能目录中，也不会创建符号链接 。通过每个数字命名的创意工坊文件夹内是否存在顶层 Script.cs 文件来检测 PB 脚本。创意工坊文件夹路径从 SE_GAME_ROOT （环境变量）或 app id 244850 对应的 Steam 注册表项中解析。

参考资料

• Script Template 仓库 用于启动新项目的 PB 脚本模板仓库。参见 ScriptTemplate.md
• Script Merge 工具 将 C# 项目中的 PB 脚本合并到单个文件，并可选择压缩代码。参见 ScriptMerge.md
• Script Dev 插件 自动将脚本加载到游戏内 PB 中，便于测试。参见 ScriptDev.md
• Mod Development Kit (MDK2)
• Programmable Block API
• 脚本编写 Wiki

脚本代码搜索

搜索 Steam 和本地 PB 脚本的源代码，查找示例和模式：

# Search for patterns
uv run search_scripts.py class declaration Program
uv run search_scripts.py method usage Main
uv run search_scripts.py class children MyGridProgram

# Count results before viewing (useful for large result sets)
uv run search_scripts.py class usage Program --count

# Limit number of results
uv run search_scripts.py class usage GridTerminalSystem --limit 30

搜索前，请确保索引已存在。如果缺少 Data/CodeIndex/，请运行：

uv run list_scripts.py     # quick inventory (always cheap)
uv run index_scripts.py    # full code index (incremental: only changed scripts reparsed)

订阅新内容后重新建立索引： 在 Steam 创意工坊订阅新脚本后， 请在游戏世界中加载一次（使游戏下载这些脚本），然后重新运行上面的两个命令 （或运行 Prepare.bat）。索引器会计算每个脚本的 .cs 文件哈希，仅重新解析 自上次运行以来哈希发生变化的脚本，因此再次运行会很快。

完整文档请参见搜索操作。

操作参考

请按照以下详细说明操作：

• 准备操作 - 一次性准备
• bash 操作 - 通过 busybox 运行 UNIX shell 命令
• 搜索操作 - 搜索脚本代码以查找示例

备注

此技能的原始来源：https://github.com/CometWorks/skills