GS Language 3.0.8（有限范围试用）

GS 语言的 VS Code 插件。提供 native 原文语言服务、安全重命名、语法/metadata 诊断及注释、PKG/工程文档生成。lint 强制暂停，旧 gs.lint.enable=true 也不能开启。

支持 .gs、.gsh、.gsd 文件。VS Code 最低版本为 1.138.0，本轮试用范围为 Windows x64；其他平台尚未验收。真实工程响应性和长期使用证据尚未达到正式发布要求，试用证据和保留问题见源码仓库 docs/release-3.0.8-trial.md。

安装与开始使用

使用下方独立目录命令打开试用 VS Code，扩展视图选择 从 VSIX 安装，选取 gs-lang-3.0.8.vsix。
重载窗口，打开 GS 工程文件夹或 .code-workspace 工作区。
打开 GS 源文件，语言服务会自动启动。

也可在安装包所在目录执行：

code --user-data-dir .\trial-3.0.8\user-data --extensions-dir .\trial-3.0.8\extensions --install-extension .\gs-lang-3.0.8.vsix --force
code --user-data-dir .\trial-3.0.8\user-data --extensions-dir .\trial-3.0.8\extensions <工程路径>

编辑功能无需先安装 GS driver。调试需要与工程匹配的 GS runtime 及其 debuggee 模块。

语言功能

功能	当前支持范围
代码高亮	TextMate 语法高亮与语义高亮
定义跳转	当前文件、源码模块及可解析的依赖；builtin 打开只读声明视图
引用查找	完整项目索引中的引用，包含未打开的使用者文件
代码补全	关键字、声明、import/alias 模块成员、builtin qualified/static/instance 成员、类型、宏和可见枚举；支持半截标识符补全
悬停提示	源码声明、模块来源，以及 builtin 签名、种类和文档状态
参数提示	裸调用、已绑定导入调用、跨文件类及声明类型成员/返回值链、已知内置类型成员的参数列表和当前参数位置
大纲与符号搜索	当前文件大纲及预算范围内的项目符号
诊断与快速修复	lint 暂停且不支持配置开启；语法及声明 metadata schema 诊断继续提供
格式化	原文 CST 空白编辑；保留 metadata、指令与注释。存在 recovery 或没有后续分号的 implicit 语句时保留全文
重命名	完整项目中可证明的普通源码函数、变量及参数；所有被修改文件须已打开且版本/原文一致。未知动态目标、关闭文件、跨根共享、类/枚举/扩展方法及 override 家族保守拒绝
调试	launch / attach、断点、调用栈、变量、求值、单步与继续运行

语言服务使用本地 stdio LSP 子进程。未保存的文本、配置变化、文件增删和服务重启均参与更新。 stdio 和 in-process 使用同一套 native 项目查询；服务异常时使用进程内 native 查询恢复。lint 暂停期间，语言启动不执行旧 builtin 探测、缓存恢复或工程扫描。

native 语法与符号/依赖摘要使用独立的持久化缓存。重开项目会优先预热打开文件及其依赖，后台校验先前索引的其他文件；未保存文本优先，配置与内容变化会重新绑定。缓存损坏或不可写时自动回到正常解析。T3 expanded 不作为默认语义输入，宏生成内容不能据此视为已经完整展开或可编辑。生成注释、变量调试打印和工程文档仍可在关闭诊断时使用。

项目与诊断配置

现有项目配置继续可用。多根工作区可在各文件夹的设置中配置不同的 mount、宏文件和声明；通用配置可放在工作区设置中。

配置项	用途
`gs.start.mount`	与工程 GS 启动参数对应的 mount 目录
`gs.start.declarations`	工程的全局宏声明
`gs.start.macrofiles`	预加载宏文件
`gs.common.roots`	多根工作区中公共目录所属的父工程，例如 `{ "common": ["server", "client"] }`
`gs.languageServer.transport`	`stdio` 为默认语言服务；`in-process` 使用相同 native 查询在编辑器进程内运行
`gs.language.builtinProfile`	目标构建的 platform、architecture、clientMode 和 features；按文件夹独立配置
`gs.language.builtinSourceManifest`	与内建原文工件匹配的目标构建和装载声明；为空时不使用源码工件 fallback
`gs.format.rules`	换行、缩进、括号样式等格式化设置
`gs.declarationMetadata.schema`	项目的声明 metadata schema JSON 路径，相对工作区；留空时只保留语法，不推断 schema
`gs.logging.level`	输出面板的日志级别

旧项目的 gslang.starup_arguments 仍保留兼容。lint 暂停且不支持配置开启，旧设置中的 gs.lint.enable=true 也不会执行 lint；规则、路由和宿主配置保留给后续迁移，当前不能启用检查。语法及声明 metadata schema 诊断、导航、补全、格式化和调试独立工作。源码模块支持显式重导出、多段 mount 和未保存的依赖文本；私有或歧义成员不会猜测跳转。 builtin 定义视图来自现有 catalog，包含 compiler 来源证据；C++ 证据位置不作为本机 GS 源文件路径。

例如服务端 Windows 构建可明确配置（具体值应由目标构建提供）：

"gs.language.builtinProfile": {
  "version": 1, "platform": "windows", "architecture": "x64",
  "clientMode": false, "features": { "debug": true }
}

profile 为空时继续只选 core；不根据编辑器 OS 或启动参数猜测构建特性。它只选择 catalog 的条件语言符号，不代替工程预处理宏配置。 54 个 builtin 和 12 个基础 internal scripts 原文另有独立工件。其目标装载声明必须含 version: 1、 sourcesHash、compilerCommit、compilerVersion、catalogHash 及布尔值 providers.builtin、providers.internal，身份取自随插件提供的 facts/gs-builtin-sources.pin.json，且目标实际构建/装载必须对应这份原文。声明由用户或构建提供；插件不自动探测进程。匹配后 import gs.util.base64 等查询使用同一 native 依赖解析，定义打开只读原文；磁盘、未保存文本、mount 和显式 provider 保持优先。未匹配配置会显示诊断并保留 core 能力。

声明 Metadata

自 3.0.0 起接入编译器 facts v2，支持相邻的 #[...]；3.0.2 继续提供以下能力。提供 class、field、method、enum、enum_value 的 metadata 原文保留、 schema 名称和递归参数补全、悬停、高亮及跳转到所附声明。metadata 名称和值不参与普通引用和重命名；运行时 <Attribute(...)> 保留普通调用语义。

通过 gs.declarationMetadata.schema 指定宿主 JSON 文件，格式为 { "schemaVersion": "1", "schemas": [...] }。 schema 的目标、类型、必选和重复参数诊断独立于 lint 开关；文件变化会重新校验。插件不内置测试 Meta.* 或 UE 宏名单。没有 schema 时校验状态为未知；复杂常量表达式、特殊转义字符串的求值、完整类型身份和布局仍不可用。宏生成 metadata 已保留在 expanded syntax 中，其编辑不能越过原文映射边界；编辑器 metadata 查询以 raw source 附着为准。

调试

在 运行和调试 视图创建 Gs-Debugger 配置，或编辑项目的 .vscode/launch.json。使用工程配套的 gs.exe，并保证 debuggee 已加载。

以下 launch 示例需按工程修改 driver 路径、入口文件和启动参数：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "gsdebug",
      "name": "GS Launch",
      "request": "launch",
      "root_path": "${workspaceFolder}",
      "execute_path": {
        "win32": "D:/GS/gs.exe"
      },
      "command_line": "/e /main.gs --require all",
      "with_debug": true,
      "debug_port": 20001,
      "listen_port": 23337,
      "detach_shell": false
    }
  ]
}

--require all 是已验证示例的 debuggee 加载方式，实际项目应采用配套 runtime 的参数。root_path 决定源码映射根目录；command_line 中的相对路径应与工程启动环境一致。

附加到已有 GS 进程时，目标必须已开启 debugger 监听：

{
  "type": "gsdebug",
  "name": "GS Attach",
  "request": "attach",
  "root_path": "${workspaceFolder}",
  "program": "20001",
  "debug_port": 20001,
  "listen_port": 23337
}

program 填目标 debugger 端口；源码应与目标进程加载的版本一致。

当前限制与排障

大型工程、动态依赖、缺失依赖或超出索引预算时，完整引用集与项目级重命名可能不可用；当前文件及可解析依赖的导航仍可使用。
复杂动态成员和运行时模块提供者需要额外信息，补全与悬停不能覆盖所有动态行为。
builtin profile 和 source manifest 需目标工程明确提供。原文工件提供程序及类的源码查询；编译后的完整声明 inventory、构建生成脚本、条件 shell、builtin_pkgs 和 ToGs 动态注册仍未覆盖。
已支持可证明的跨文件类、继承可见性和声明类型字段/返回值链。动态、下标、强制转换 receiver 及丢失依赖证据的恢复输入仍拒绝猜测；成员 dispatch 的完整引用和重命名尚未开放。
Raw 宽容语法可能漏报缺分号；malformed 函数内部的恢复符号可能分类不准确。语法提示不替代 GS compiler 校验。格式化遇到解析恢复或无分号 implicit 语句时保留全文；不提供旧 printer 的全部布局选项。
缓存恢复后仍校验当前源码并重新绑定，不恢复旧分析状态或把历史完整性直接用于引用/重命名；已有自动化检查不替代长期日常使用验证。
独立 LSP 提供语言请求和当前 native 诊断；插件格式化与 DAP 调试使用各自入口。

语言服务异常时，查看输出面板的 gs-lang 日志并执行 重启语言服务。需要进程内运行时，在设置中将 gs.languageServer.transport 改为 in-process 后重启语言服务。

升级前保留已验证的旧 VSIX 和设置。回退时关闭 GS 编辑窗口，从扩展视图安装保留的旧 VSIX（或 code --install-extension <旧包路径> --force），然后重载窗口。根目录旧 gs-lang-3.0.6.vsix 早于本轮源码，不包含新诊断和生成模块，不能作为本版发布物。隔离试用可为 code 同时指定新的 --user-data-dir 与 --extensions-dir；本轮不会覆盖日常安装。

开发与反馈

源码仓库使用 Node.js 和 npm 10.9.3，以 package-lock.json 为唯一依赖锁文件。在依赖已就绪的仓库中执行：

npm run compile
npm run test:parser-conformance
npm run package

打包使用已安装的全局 @vscode/vsce（兼容旧 vsce），校验 WASM、编译、构建并运行语言产品回归后，将发布资产和 npm 生产依赖复制到临时目录生成 VSIX，最后检查运行时资产与当前构建是否一致。请使用 npm run package；旧版全局 vsce package 会在应用忽略规则前遍历整个仓库，历史测试宿主和构建目录可能导致长时间无输出。无需重新安装项目依赖。重构阶段、事实来源、规则进度及验收记录见源码仓库的 AGENTS.md 和 docs/；3.0.0 版本号不代表全部规则已验证或兼容入口已移除。

版本变更见扩展详情页的 更改日志 或安装目录中的 CHANGELOG.md。问题与建议反馈：飞书 @fanrj；已有 GsLint 规则说明。

gs

shenyq