FishTools

FishTools 是面向 Itasca PFC 数据文件的 VS Code 语言扩展。它为 fish 代码提供随编辑器主题变化的高亮、导航和基础补全，不需要联网或配置颜色。

源码、完整说明与问题反馈：GitHub — FishTools。

安装与开始使用

从 VS Code 扩展市场安装后，打开 .fis、.fish、.p2dat、.p3dat 或 .dat 文件即可自动启用。也可以在右下角语言模式中手动选择 fish。

本扩展包可作为 .vsix 离线安装；运行时只含编译后的扩展代码、语法文件、语言配置和图标，不依赖开发环境中的 node_modules。

版本选择

在设置中搜索 fishtools.docsVersion，选择目标 PFC 版本：

• PFC 6.0：正式支持，使用 PFC 6.0 的命令和 fish 内置接口词典。
• PFC 7.0：已测试预览，使用独立词典；适合试用，但仍建议在实际工程中确认结果。

切换版本后，高亮、补全和内置函数名称提示都会使用对应的本地词典。FLAC3D、3DEC 与其他 Itasca 产品暂不支持。

编辑功能

主题跟随高亮

扩展只识别语言成分的类别，不指定任何颜色，因此浅色、深色和自定义 VS Code 主题都会决定最终配色。

科学计数法会作为一个完整数值处理；注释中的括号和方括号保持注释色。call "file.fis" 中的文件名被当作一个整体，不会出现常驻下划线。

导航、结构与补全

• 使用 F12 或 Cmd/Ctrl+单击跳转到当前文件或工作区中的 def / define 函数；@函数名 也可跳转。
• call "file.fis" 可跳转到存在的本地数据文件；目标不存在时不会创建无效链接。
• 大纲显示自定义函数和 global 变量；引用查找会优先扫描当前文档，再受限扫描工作区。
• if、loop、command 等块结构可折叠和匹配，命令面板提供跳转到配对块的命令。
• Ctrl+Space 提供命令、内置接口、控制语句、已定义函数与基础函数骨架补全。

本地调用 PFC

在编辑器中右键（或命令面板）运行本机安装的 PFC：

• Run PFC Script：在集成终端中用控制台版运行当前数据文件（pfc3d600_console.exe -f 文件），每条命令实时回显。每次运行都会先终止同维度的旧 PFC 会话再全新启动——即使上一个 PFC 卡在长时间计算或窗口重载后仍在运行，也能干净重启（旧进程的模型状态会丢失；要保留状态请用 Run PFC Selection 或 model save）。文件执行完后停留在 pfc> 提示符，可继续输入命令，文件内写 quit 则退出。
• Run PFC Selection：选中一段代码（含 def … end 块）后右键运行——选区写入临时文件并以 call 方式发送到正在运行的 PFC 会话（沿用上次 Run PFC Script 的模型状态），适合在已有模型基础上增量调试；若没有活动会话（如重载窗口后），会自动先运行整个文件建立状态，再执行选区。
• Open PFC GUI：以当前数据文件为参数启动 GUI 版（可视化查看与操作）。

维度自动对应：.p2dat → 2D、.p3dat → 3D；.fis / .fish / .dat 使用设置 fishtools.pfc.defaultDimension（默认 3D）。安装路径默认无需配置：激活时自动检测（注册表 HKLM\SOFTWARE\Itasca\PFC600 / PFC700 的 InstallDir64），检测到就把 exe 路径回填到 fishtools.pfc.executable；仅当检测不到（如绿色版、非默认安装）时由用户通过 FishTools: Set PFC Executable Path 选择或手动填写。PFC 版本跟随 fishtools.docsVersion（未安装对应版本时提示设置）。PFC 仅支持 Windows。

工作原理

扩展通过 VS Code 集成终端与 PFC 控制台交互，不直接管理 PFC 进程：

• 连接：createTerminal 创建集成终端，sendText 向终端输入流发送命令；PFC 控制台作为终端 shell 的前台子进程运行，从标准输入读取命令、向标准输出回显结果（Windows 上经 ConPTY 转发）。
• 交互：扩展发送的命令与手动键盘输入走同一输入流，因此 pfc> 提示符下的手敲与扩展命令完全等价。多行 def … end 选区通过写入临时 .fis 文件后单行 call 执行（逐行发送会在 PFC 的 Def> 连续输入模式下丢行）；quit 与 d（退出确认）按终端输入队列顺序由 PFC 依次处理；Stop 按钮发送 \x03，由 ConPTY 翻译为 Ctrl+C 中断当前命令（进程保留）。
• 进程生命周期：Run PFC Script 每次干净重启（先终止同维度旧会话，避免长计算中的 PFC 无法接受新命令）；Reload Window 保留终端进程（VS Code persistent session reconnection），会话与模型状态可继续使用；关闭 VS Code 时扩展在 deactivate 中强制终止 PFC 进程树，不留孤儿进程。

不同电脑的适配（安装目录检测顺序）

扩展按以下顺序定位 PFC 可执行文件，大多数机器零配置：

1. fishtools.pfc.executable —— 唯一需要关心的设置。扩展激活时会自动检测一次：检测到标准安装就把 exe 完整路径回填到该设置（用户可在设置里看到并随时修改）；检测不到则保持为空，由用户通过命令面板 FishTools: Set PFC Executable Path 在文件对话框中选择，或手动填写。
2. 注册表自动检测 —— 内部步骤：HKLM\SOFTWARE\Itasca\PFC600（64 位视图）、HKLM\SOFTWARE\WOW6432Node\Itasca\PFC600（32 位视图）、HKCU\SOFTWARE\Itasca\PFC600 的 InstallDir64 / InstallDir32，找到后推导出 exe 并回填到 fishtools.pfc.executable。无需用户干预。

只要 fishtools.pfc.executable 非空，就始终以它为准（自动回填的值也可被用户覆盖）。

常见场景：

找不到时，错误提示会说明具体查过哪些位置（注册表根、安装目录、exe 候选子目录），并按提示一键打开对应设置。

性能与稳定性

语义高亮按文档版本缓存；切回未改动标签不会重新分析。工作区函数索引只在真正使用跳转、引用或补全时读取，且对文件数量、文件大小、行长度和令牌数均有限制。超过 5,000 行的文件自动回退到轻量语法高亮，以避免长文件或复杂主题造成卡顿。

局限性

• 仅支持 PFC 6.0 和已测试预览的 PFC 7.0；不能将其用于 FLAC3D、3DEC 或其他版本的兼容性保证。
• 不提供诊断、格式化、调试、重构、系统函数源码或完整签名查询。
• 复杂命令参数不会完整解析；少数同名词在特定位置可能按命令类别显示。
• 这不是完整语言服务器。补全与导航是面向 fish 编辑的轻量辅助，不能取代官方文档或运行时验证。

开发与发布

以下命令均在包含 package.json 的 FishTools 项目根目录运行：

npm ci                  # 按 package-lock.json 安装开发依赖
npm run compile         # 将 TypeScript 源码编译到 out/
npm run package         # 编译并在项目根目录生成 VSIX

发布前应先更新 package.json 的版本号，并在完整的本地开发副本中完成测试和人工验收。打包不会自动发布，仍需由开发者明确上传到 GitHub 或 VS Code Marketplace。