YScript VSCode 插件

为 YScript（网安专用脚本语言）提供 VSCode 完整支持：语法高亮、LSP 智能补全、悬停文档、跳转定义、代码片段。

当前适配 YScript 解释器 v0.1.5.3；VS Code 扩展包版本独立管理。扩展可识别并高亮 ysc.models / ysc.sum 项目依赖清单。

项目依赖清单

ysc.models 和 ysc.sum 使用独立的 yscmanifest 语法高亮，覆盖项目/依赖声明、版本、Git URL 与 h1: 校验值。依赖获取和同步由解释器命令 ysc mod get / ysc mod sync 执行。

YScript v0.1.5.3

• package 只声明源文件所属包；多文件包的声明文件无需单独包含 func main()，避免库文件和测试文件的入口误报。
• cli 支持 app.command() 子命令、自动转换 int / float / bool、choices 与数值范围校验、互斥参数组及 multi_option() 重复参数列表；同步命令行参数库文档与集成测试。
• 泛型函数与泛型结构体支持类型参数、实参/字段类型推导、内建约束（any / number / ordered / comparable）和结构化接口约束；语法高亮支持泛型声明、类型参数/实参及约束，编辑器新增泛型函数、结构体与约束代码片段。
• load 新增模块生命周期接口：load.install(path) 安装而不执行，load.start(path) 执行已安装模块，load.stop(path) 调用可选的模块级 stop()，load.uninstall(path) 必要时先停止再移除声明。
• ysc doc 支持按函数名关联任意位置的文档块：@functionName HEAD 到 @functionName END 之间的 # 注释会覆盖就近注释；注解标记有专用语法高亮。

YScript v0.1.5.2

• 识别 name <- expression 类型推断声明，提供语法诊断、变量符号/类型提示与自动补全。
• 同步无符号整数类型提示、OCR 与顶层代码诊断。
• 二进制命名空间补全新增 binary.FileCopy，支持大文件有界内存流式复制。
• sys 命名空间补充跨平台进程、同步命令执行、文件句柄、内存映射、信号、CPU 特性等系统接口。
• io 命名空间补充 Reader / Writer / Closer 契约、Pipe、TeeReader、MultiWriter、SectionReader、Discard / NopCloser、缓存流适配器与错误常量，方便流式处理与 sys 层桥接。
• 补全缓冲流 API：Reader / Writer 的容量查询与 Reset、Peek / 回退 / 分隔读取 / 逐行读取、WriteTo / ReadFrom / Flush，合并 ReadWriter，以及支持行、词、字节、rune 分割和缓冲区配置的 Scanner。
• 更新 package main 入口和函数代码片段说明。

load 命名空间补全和悬停文档覆盖全部接口。生命周期方法接收 YScript 源文件路径字符串：load.install(path) 解析、编译并注册模块，不执行初始化或顶层代码；load.start(path) 执行已安装模块的初始化和顶层代码；load.stop(path) 调用模块可选的 stop() 函数；load.uninstall(path) 在需要时先停止模块，再移除其声明。

兼容的既有热加载接口仍可使用：load.load(path) 加载模块并返回可调用的导出字典；源文件更新后调用 load.reload(path) 替换已加载模块；load.unload(path) 卸载模块并清空导出字典；load.loaded() 列出已加载路径。

功能

lstd. 补全和悬停覆盖白名单加载、名称/序号符号查找、签名绑定、调用、内存与回调接口。 安全策略和 ysc pkg -cgo 限制见 lstd 安全动态库调用指南。

代码片段速查

配置项

命令

• Reload Language YScript — 重启 YScript 语言服务器
• YScript: Show Output — 打开服务器输出面板
• YScript: Run (ysc) — 运行当前编辑的脚本（编辑器标题栏 ▶ 按钮）
• YScript: 格式化文档 (Format Document) — 使用已配置的 ysc 格式化当前 .ys 文档

程序入口

可执行文件使用 package main 和 func main() 作为入口。package 用于标记当前声明文件所属的包；同一包可由多个文件组成，库声明文件无需各自声明 func main()，导入后即可调用其函数。func main() 只能声明在 package main 中。文件顶层可声明全局 let 变量和 const 常量（在 main() 前初始化）；var 及其他执行语句应放入 main() 或其他函数中。插件语言服务器会在编辑时直接检查词法和常见语法错误，并提供自定义函数及方法的关联提示，不需要安装或启动 ysc -c 才能获得诊断。

package main
import ["ocr", "io"]

func main() {
  let image = io.read_bytes("sample.png")
  println(ocr.recognize(image))
}

func recognize_file(path) {
  return ocr.from_file(path, "eng", 6)
}

一键运行

在 .ys / .yscript 文件的编辑器标题栏点击 ▶ 按钮（或从命令面板执行 YScript: Run (ysc)），插件会先自动保存当前文件，再检查语言服务器提供的语法诊断；存在语法错误时会取消运行，否则在集成终端中调用 ysc 执行脚本。yscript.ysc.path、YSC_BIN 和 PATH 仅用于定位运行脚本所需的解释器。

插件按以下顺序定位 ysc 可执行文件：

1. 设置 yscript.ysc.path（在设置界面或 settings.json 中指定解释器绝对路径）
2. 环境变量 YSC_BIN（例如 export YSC_BIN=/usr/local/bin/ysc）
3. PATH 中的 ysc

如果以上都找不到 ysc，插件会弹窗提示：可直接打开 GitHub 下载页（https://github.com/xiguayiqiu/YScript）下载安装，或点击"选择解释器路径"手动指定 ysc 文件（选择后自动写入全局设置 yscript.ysc.path）。

运行输出显示在名为 YScript Run 的集成终端中。

调试

点击左侧字母 Y 图标打开 YScript Debug，再点“调试当前文件”即可启动当前 .ys / .yscript 文件；启动后会自动显示 Debug Console。也可在行号边栏设置断点后按 F5。可在调试控制台求值、在 WATCH 面板跟踪表达式，并在 VARIABLES 中查看或修改变量。launch 配置也支持 stopOnEntry、traceLines 和 traceCalls。远程 attach 需要提供目标机上的 program 路径；目标机运行 ysc debug-adapter --listen=tcp:127.0.0.1:4711 后，在 VS Code 选择 YScript: Attach。详细能力和安全边界见调试器文档。

文件识别

自动识别 .ys 和 .yscript 文件。

文件图标（侧边栏 logo）

插件自带一套 YScript File Icons 文件图标主题，为 .ys / .yscript 文件在资源管理器侧边栏显示 YS logo。安装插件后需要手动启用（图标主题无法由插件自动切换）：

1. 打开命令面板（Ctrl+Shift+P），执行 Preferences: File Icon Theme；
2. 选择 YScript File Icons。

也可以在 settings.json 中直接指定：

{
  "workbench.iconTheme": "yscript-icons"
}

未启用该主题时（例如使用默认 Seti 主题），.ys 文件仍会通过语言默认图标显示 YS logo。

维护：标准库成员数据从实现自动生成

命名空间成员表 server/src/ns_members.ts 由脚本从解释器源码生成，不要手工编辑：

cd yscript && python3 tools/gen_ns_members.py > ../vscode/server/src/ns_members.ts
cd ../vscode && npm run compile      # 或 ./node_modules/.bin/tsc -p server/tsconfig.json

提取来源：

1. MakeNS("ns", map[string]value.BuiltinFunc{...}) —— 各命名空间注册表
2. buildCFuncNames() —— c 模块（成员动态拼装，静态扫描抓不到）

这样改了 internal/std/*.go 后重新生成即可，不会再出现「插件漏收录新函数」。

新增代码片段前缀：c call、c callback、c header bind、c parse header、 ffi struct、ffi alloc、c variadic、raw pcap、worker。

自动 import 的行为

YScript 的标准库必须先 import 才能用。LSP 会自动帮你补上：

1. 自动导入：在代码中使用未导入的内置模块成员（如 binary.ReadFile(...)）后， 插件会自动在 package 声明后添加对应的 import ["binary"]，已有导入列表则会自动合并， 无需手动维护标准库导入。

2. 诊断与快速修复：自动导入未能应用时，该行会出现黄色波浪线，例如

未导入模块 "binary"，请先写 import ["binary"]（或用快速修复自动添加）

import ["string"] 之后实际用的是 strings.xxx； error 同理对应 import ["error"] 和 errors.xxx。

光标放在波浪线处按 Ctrl+.（或 Cmd+.），也可手动选择「添加 import "binary"」。 支持三种插入风格，且不会重复添加：

3. 补全联动：输入 binary. 时，若未导入，补全列表首项仍提供 ＋ 添加 import "binary"，按回车选中即自动写入 import 语句。

自动检测适用于插件已知的标准库命名空间；第三方脚本库的路径无法仅凭成员名推断， 仍需在 import [...] 中显式声明。

显式导入带别名的项目脚本库后，插件会分析导入的 .ys 文件并提供成员补全、悬停文档、 签名帮助与跳转定义。例如 import ["../lib/text/encoding_utils" as enc] 后输入 enc.， 可补全 base64_round_trip、hex_round_trip、decode_url_or、html_escape、 encoding_utils_encode_as 等库函数；函数的 @name HEAD 文档注解会显示在悬停中。

误报已排除：字符串内、注释内、局部变量遮蔽（let binary = 1）、 成员访问（foo.binary）均不会触发。

核心逻辑在 server/src/imports.ts（parseImports / findUnimportedUses / buildImportEdit），命名空间数据来自自动生成的 ns_members.ts。

#!permit 权限提示

编辑器会识别常见的文件读写、外部命令和网络调用。没有 #!permit 时显示信息提示，说明 YScript 默认不启用沙箱；已有策略但未声明该调用类别时显示警告，因为运行时可能拒绝调用。诊断快速修复会在文件开头（保留 shebang）插入 #!permit <类别>；此声明授权该类别的全部目标，建议按需改为具体路径或命令规则。提示属于静态分析，动态路径、io.open 模式以及命令行 --sandbox 覆盖规则仍以运行时为准。