古叶脚本助手

本文档适用于“古叶脚本助手”VS Code 扩展，说明安装、初始化、编辑、诊断、导航、配置、离线更新及常见问题处理方法。

1. 安装扩展

1.1 从 VSIX 安装

获取带版本号的安装包，例如 guye-script-assistant-1.11.4.vsix。
打开 VS Code。
按 Command+Shift+P；Windows/Linux 按 Ctrl+Shift+P。
输入“扩展：从 VSIX 安装”。
选择对应版本的 VSIX 文件。
安装完成后重新加载 VS Code 窗口。

打开命令面板后输入 Reload Window，选择“开发人员: 重新加载窗口” （Developer: Reload Window）。如果右下角出现“重新加载”按钮，也可以直接点击。

1.2 命令行安装

已安装 code 命令时，可以执行：

code --install-extension guye-script-assistant-1.11.4.vsix

1.3 离线使用

普通使用者只需要 VSIX 文件，不需要单独复制帮助文档、API 数据、Icon 或扩展源码。离线安装不会自动更新；获得新版 VSIX 后重新安装即可覆盖旧版本。

2. 初始化当前项目

2.1 自动初始化

安装并重新加载后，如果当前项目没有关联古叶脚本，扩展会显示：

当前项目尚未关联古叶 TXT 脚本，是否自动创建 .vscode/settings.json？

点击“创建配置”。普通单文件夹窗口会创建或更新：

当前项目/.vscode/settings.json

多根工作区会把配置写入当前 .code-workspace 文件。

初始化会合并已有设置，不会删除其他语言、文件关联或配色规则。

2.2 使用命令初始化

自动提示没有出现时：

打开命令面板。
输入“古叶脚本: 初始化当前项目配置”。
执行命令。

如果尚未打开项目文件夹，扩展会提示先使用“文件 → 打开文件夹”。

2.3 手动初始化

在项目根目录创建 .vscode/settings.json，至少加入：

{
  "files.associations": {
    "*.txt": "guye-script"
  }
}

.vscode 是隐藏目录。macOS Finder 中按 Command+Shift+. 可以切换显示隐藏文件；VS Code 文件列表通常会直接显示该目录。

3. 确认扩展已经启用

打开 TXT 脚本后，查看 VS Code 右下角的语言模式：

古叶脚本

如果显示“纯文本”：

点击右下角“纯文本”。
选择“古叶脚本”。
或执行“古叶脚本: 初始化当前项目配置”后重新打开文件。

4. 语法高亮

扩展会识别并区分以下内容：

帮助文档中定义的脚本命令
[标记定义]
静态标记引用
#脚本变量#
<内置变量>
<带[参数|参数]的内置变量>
// 注释
比较、算术和布尔参数
数字
「名称」
/ 参数分隔符

不同命令类别使用不同语义颜色，例如流程控制、移动、等待、状态设置和数据操作。最终颜色会受到当前 VS Code 主题及项目的 editor.tokenColorCustomizations 影响。

5. 自动缩进与格式化

5.1 输入标记后自动缩进

输入标记并按回车：

[开始]

下一行会自动缩进 4 个空格：

[开始]
    启动保护

5.2 格式化规则

格式化器会：

将 [标记] 放到行首。
将标记下的非空内容统一缩进 4 个空格。
删除空行上的多余空白。
保留文件原有的 CRLF 或 LF 换行格式。

5.3 执行格式化

保存文件：启用 editor.formatOnSave 时自动格式化。
命令面板：执行“格式化文档”。
macOS 默认快捷键：Shift+Option+F。
Windows 默认快捷键：Shift+Alt+F。

6. 命令智能补全

6.1 搜索命令

在命令行开始位置输入文字，扩展会显示命令候选、参数数量、说明和范例。

支持三种匹配：

前缀匹配：移动到 → 移动到坐标
中间位置匹配：坐标 → 移动到坐标
字符顺序匹配：移坐 → 移动到坐标

搜索也会参考命令用法和参数说明。

6.2 接受或取消补全

方向键：选择候选项。
Enter 或 Tab：插入选中的补全项。
Esc：关闭建议列表，保持 VS Code 默认行为。
建议没有自动显示时：从命令面板执行“触发建议”。

6.3 查看候选详情

建议列表打开后，先选中一个命令：

macOS：按 Command+Shift+I
Windows/Linux：按 Ctrl+Shift+I

再次按相同快捷键可收起详情。详情包含命令格式、参数、用法和范例。

6.4 参数模板

选择带参数的命令后会插入参数占位符：

移动到坐标/系统X坐标/系统y坐标/系统z坐标/最大移动次数/允许的距离偏差

按 Tab 可以依次填写参数。

6.5 参数值候选

输入 / 后，扩展会根据参数位置提示：

是、否
开、关
大于、小于、等于、不等于
存在、不存在、完成
动作、模式等帮助文档候选值
帮助文档范例中出现过的参数值
当前文件已经定义的静态标记

标签参数只提示当前文件真实存在的标记，不会混入帮助文档范例中的无效标签。

6.6 脚本变量补全

扩展会收集当前文件中通过 设置变量 定义的变量：

设置变量/当前环/1
设置变量/当前任务ID/45773

变量根据使用位置采用两种补全形式：

在直接接收变量的参数中补全裸变量名，例如 变量运算/当前环/加/1 和 判断跳转/当前环/大于/100/结束。 判断跳转 的第1、3个数据参数均支持裸变量补全。
在文本或动态名称中输入 #，补全为 #变量名#，例如 记录信息/当前环：#当前环# 和 标记跳转/第#当前环#环。

如果 VS Code 已经自动补上右侧 #，扩展只插入变量名称，不会产生重复的 ##。补全详情会显示变量首次定义的行号和初始值。同一个变量多次执行 设置变量 属于重新赋值，不会被视为重复定义。

6.7 `<>` 内置指令补全

输入 < 后，扩展会显示帮助文档中的全部 <> 内置指令，例如：

<取时间>
<队伍人数>
<自身职业>
<目标距离>
<取说[物品名称/ID]明>
<替换[原文本或变量|需要替换的文本|用来替换的文本]文本>

带 [] 参数的指令会生成可按 Tab 依次填写的参数占位符。VS Code 已经自动补上右侧 > 时，扩展不会重复插入 >。候选指令及说明由 脚本命令帮助文档.md 自动生成。

6.8 保存自定义代码块

在古叶 TXT 脚本中选中要重复使用的内容。
右键选择“古叶脚本: 保存所选内容为代码块”。
输入代码块名称。
输入用于补全的触发词。
输入说明；不需要时可以留空。

扩展会自动创建或合并：

当前项目/.vscode/guye-script.code-snippets

保存后，在古叶脚本中输入触发词即可从建议列表插入整个代码块。代码块只属于当前项目；同名代码块会先询问是否覆盖。保存完成后可以选择“打开代码片段文件” 查看或手动加入 ${1:参数}、${2|选项1,选项2|} 等高级占位符。

右键菜单只有在满足以下条件时才会显示：

当前文件语言模式为“古叶脚本”。
已经选中非空脚本内容。
当前文件属于已打开的项目文件夹。

也可以选中内容后打开命令面板，执行“古叶脚本: 保存所选内容为代码块”。

7. 启动和关闭命令配对

当帮助数据中同时存在 启动X 与 关闭X 时，补全 启动X 会同时生成：

启动保护
关闭保护

两条命令保持相同缩进。光标停在启动命令末尾，按回车可在两条命令之间继续编写：

启动保护
// 这里继续编写
关闭保护

如不需要自动配对，可关闭：

"guyeScript.pairedCommands.enabled": false

8. 命令帮助

8.1 鼠标悬停

将鼠标停在命令名称上，会显示：

简短命令格式
每个参数的完整说明
命令用途
使用范例

8.2 光标自动显示

使用键盘或鼠标把文本光标移动到命令名称内，停留一段时间后也会自动显示相同帮助。默认延迟为 350 毫秒。

输入文字或填写补全片段时，提示会延后，减少与建议列表重叠。

关闭或修改延迟：

{
  "guyeScript.cursorHover.enabled": true,
  "guyeScript.cursorHover.delay": 350
}

允许的延迟范围为 100～3000 毫秒。

9. 实时脚本检查

扩展会在编辑时检查：

未知命令
参数数量错误
文档明确要求的必填参数为空
明确的逻辑、动作和开关值无效
重复定义标记
跳转到不存在的静态标记
未被引用的标记
引用了尚未通过 设置变量 定义的变量

问题会显示波浪线，并出现在 VS Code“问题”面板中。

9.1 参数数量

参数范围会综合帮助文档中的参数个数、参数说明和全部范例推导，以兼容文档中声明数量与实际范例不一致的情况。

旧版脚本可能使用历史参数格式。如不希望显示参数诊断：

"guyeScript.diagnostics.parameters": false

9.2 参数快速修复

参数值不在明确候选范围内时：

将光标移到问题位置。
macOS 按 Command+.；Windows/Linux 按 Ctrl+.。
选择正确值。

9.3 创建缺失标记

跳转到不存在的静态标记时，使用快速修复“创建标记”，扩展会在文件末尾插入：

[缺失的标记名称]

9.4 诊断设置

{
  "guyeScript.diagnostics.enabled": true,
  "guyeScript.diagnostics.parameters": true,
  "guyeScript.diagnostics.variables": true,
  "guyeScript.diagnostics.unusedLabels": true
}

10. 标记导航

10.1 转到定义

在静态标签引用上：

按 F12
或按住 Command/Ctrl 后点击

即可跳转到对应的 [标记定义]。

10.2 查找所有引用

在标记定义或引用上按 Shift+F12，查看当前文件中的所有静态引用。

10.3 重命名标记

在标记定义或静态引用上按 F2：

输入新名称。
确认。
扩展同步修改定义和所有静态引用。

标记名称不能包含 [、]、/、| 或换行。

10.4 大纲

所有标记都会显示在 VS Code“大纲”及“转到符号”列表中，可用于快速浏览长脚本。

10.5 动态标记

扩展能够识别动态模板：

标记跳转/第#当前环#环

该模板会被认为可能引用：

[第1环]
[第2环]
...
[第100环]

因此这些标记不会被错误提示为“未使用”。动态引用无法确定唯一目标，所以不参与 F12 跳转、查找引用和 F2 重命名。

10.6 变量导航与重命名

变量定义、#变量名# 引用，以及 变量运算、判断跳转 等位置的裸变量引用均支持：

F12 或 Command/Ctrl+点击：跳转到第一次 设置变量/变量名/...。
Shift+F12：查找当前文件内的全部赋值和引用。
F2：同步重命名裸变量名以及 #变量名# 内的名称。

变量名称不能包含 #、<、>、/、| 或换行。

11. 完整扩展设置

在 VS Code 设置中搜索“古叶脚本”，或写入 .vscode/settings.json：

{
  "guyeScript.diagnostics.enabled": true,
  "guyeScript.diagnostics.unusedLabels": true,
  "guyeScript.diagnostics.parameters": true,
  "guyeScript.diagnostics.variables": true,
  "guyeScript.cursorHover.enabled": true,
  "guyeScript.cursorHover.delay": 350,
  "guyeScript.pairedCommands.enabled": true,
  "guyeScript.setup.promptOnStartup": true
}

12. 自动创建的项目配置

自动初始化会合并以下主要配置：

{
  "files.encoding": "utf8",
  "files.autoGuessEncoding": true,
  "editor.mouseWheelZoom": true,
  "files.associations": {
    "*.txt": "guye-script"
  },
  "[guye-script]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 4,
    "editor.detectIndentation": false,
    "editor.autoIndent": "full",
    "editor.defaultFormatter": "guye-script-assistant.guye-script-assistant",
    "editor.formatOnSave": true,
    "editor.wordWrap": "on"
  }
}

扩展还会合并标记定义、引用和括号的颜色规则。已有的其他 TextMate 配色规则会被保留。

13. 编码说明

扩展处理的是 VS Code 已经解码后的文本：

工作区推荐使用 UTF-8。
files.autoGuessEncoding 可以帮助 VS Code 识别其他编码。
如果文件显示乱码，请先确认右下角编码，并使用“通过编码重新打开”选择正确编码。
Git clean/smudge filter 的转码发生在 Git 检出和提交阶段，与扩展语法分析是两个独立过程。

不要在确认原始编码前直接“以 UTF-8 保存”，否则可能改变文件内容。

14. 扩展命令

打开命令面板后可以使用：

古叶脚本: 初始化当前项目配置
古叶脚本: 查看更新说明
古叶脚本: 保存所选内容为代码块
格式化文档
触发建议
开发人员: 重新加载窗口

15. 更新扩展

未发布到 Marketplace 时：

获取新版且带版本号的 VSIX 文件。
再次执行“扩展：从 VSIX 安装”。
选择新版文件。
重新加载窗口。

新版的版本号必须高于已安装版本。项目中的 .vscode/settings.json 会保留。首次启动新版本时会显示版本提示；点击“查看更新说明”可在 VS Code 中打开随安装包提供的更新日志。也可以随时从命令面板执行“古叶脚本: 查看更新说明”。

16. 卸载

打开 VS Code 扩展页面。
找到“古叶脚本助手”。
点击“卸载”。
重新加载窗口。

卸载扩展不会自动删除项目中的 .vscode/settings.json。如果不再需要 TXT 文件关联，可以手动删除其中的古叶脚本相关字段。

17. 常见问题

17.1 TXT 文件没有高亮

检查右下角语言模式是否为“古叶脚本”。
执行“古叶脚本: 初始化当前项目配置”。
确认 .vscode/settings.json 中存在 "*.txt": "guye-script"。
重新加载窗口并重新打开文件。

17.2 没有自动创建提示

确认已经使用“文件 → 打开文件夹”，而不是只打开单个 TXT 文件。
手动执行“古叶脚本: 初始化当前项目配置”。
检查 guyeScript.setup.promptOnStartup 是否为 true。

17.3 补全详情没有显示

先用方向键选中建议项。
macOS 按 Command+Shift+I。
Windows/Linux 按 Ctrl+Shift+I。
插入命令后也可以使用鼠标悬停查看。

17.4 启动和关闭命令缩进不一致

确认安装的是最新版本。
执行“格式化文档”。
检查 editor.detectIndentation 是否为 false。

17.5 旧脚本出现大量参数警告

旧脚本可能使用历史命令格式，可关闭参数诊断：

"guyeScript.diagnostics.parameters": false

未知命令和标记诊断仍然保留。

17.6 配置创建失败

确认安装版本不低于 v1.8.1。files.associations 必须写入工作区域：

单文件夹窗口写入 .vscode/settings.json。
多根工作区写入 .code-workspace。

17.7 扩展报错后仍然使用旧行为

重新安装新版 VSIX，然后执行“开发人员: 重新加载窗口”。必要时先卸载旧版本，重新加载，再安装新版。

古叶脚本助手