> ## Documentation Index
> Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code 扩展

> Fluxon 语法高亮、补全与命令配置

Fluxon 官方 VS Code 扩展为 `.fs` 文件与 YAML 嵌入块带来语法高亮、智能补全、注解/片段模板与函数目录同步能力。
本章总结其安装方式、常用配置及维护流程，便于团队快速统一开发体验。

## 功能概览

* **语法高亮**：覆盖关键字、变量引用、运算符与注解块。
* **基本补全**：关键字、系统函数、扩展函数、链式 `::` 调用及当前工作区的 `def`/`fun` 块均可被建议，并附带参数占位符。
* **注解提示**：输入 `@` 即出现内置注解（默认 `@except`）模板。
* **代码片段**：`def`、`when`、`try` 等前缀可展开为常用结构；括号与引号自动闭合。
* **YAML 嵌入**：在 YAML 中使用 `: ;` 启用 Fluxon 区块，补全与语法提示与 `.fs` 文件一致。

示例：

```yaml theme={null}
script:
	onLoad: ;print("Hello Fluxon")
	onTick: ;for i in 1..10 { print(&i) }
```

## 安装与更新

<img src="https://mintcdn.com/taboolib/b7i2pBBkQ0j4FUtH/image/vscode.png?fit=max&auto=format&n=b7i2pBBkQ0j4FUtH&q=85&s=9c4d3ae2ec0227aecdb40c1d3f7bfd01" alt="" width="937" height="275" data-path="image/vscode.png" />

1. 在 VS Code 的扩展视图搜索 “Fluxon” 并安装，或手动导入 `.vsix` 包。
2. 若需本地构建：

```bash theme={null}
pnpm install
pnpm run prepackage   # 同步函数目录 + 编译
pnpm run package      # 生成 dist/fluxon-*.vsix
```

3. 打开 “扩展” 视图 → 右上角 `…` → “从 VSIX 安装” 选择生成的包。

<Note>仓库附带 `vscode-extension/demo/` 与 `vscode-extension/data/fluxon-functions.json`，便于测试补全是否生效。</Note>

## 命令与快捷操作

| 命令                                 | 说明                                          |
| ---------------------------------- | ------------------------------------------- |
| `Fluxon: Refresh Function Catalog` | 立即重新加载 `fluxon-functions.json`，在添加新函数后刷新补全。 |
| `Toggle Line Comment`              | 针对 Fluxon 语法插入 `#` 注释。                      |
| `Toggle Block Comment`             | 插入 `/* ... */` 区块注释，支持多光标。                  |

常用片段前缀：`def`、`defb`、`async`、`for`、`when`、`try`、`import`、`@`。

## 配置选项

在 `settings.json` 中搜索 `Fluxon` 可调节以下参数：

| 键                                       | 默认值    | 作用                            |
| --------------------------------------- | ------ | ----------------------------- |
| `fluxonCompletion.catalogPath`          | *(空)*  | 自定义函数目录路径。                    |
| `fluxonCompletion.showNamespaces`       | `true` | 在补全项中显示命名空间，方便区分系统/扩展函数。      |
| `fluxonCompletion.enableExtensions`     | `true` | 控制是否在 `object::` 上下文提供扩展函数提示。 |
| `fluxonCompletion.includeUserFunctions` | `true` | 扫描当前工作区 `.fs` 文件并补全用户自定义函数。   |
| `fluxonCompletion.trace`                | `off`  | 补全日志级别。                       |

## 函数目录同步

补全依赖运行时导出的 `fluxon-functions.json`。新增函数时需重新生成并同步：

```bash theme={null}
# 在仓库根目录
./gradlew :core:dumpFluxonCatalog

# 同步到 VS Code 扩展
cd vscode-extension
pnpm run sync-catalog
```

更新后执行命令面板中的 `Fluxon: Refresh Function Catalog` 以刷新内存缓存。

## 本地调试流程

1. 在 `vscode-extension` 中运行 `pnpm run watch`，保持 TypeScript 编译。
2. 在 VS Code 中按 `F5` 启动 “扩展开发主机”。
3. 在新窗口打开 `.fs` 或 `demo/test.yml`，验证补全与语法高亮。
4. 修改代码后调试窗口会自动热重载，如需重新拉取目录可重复执行上节命令。

## 常见问题

* **`.fs` 误识别为 F#**：点击状态栏语言模式，手动切换为 “Fluxon”。
* **补全缺少新函数**：确认已执行 `dumpFluxonCatalog` 与 `sync-catalog`，并运行刷新命令。
* **YAML 中无补全**：确保 Fluxon 代码前加 `;`，例如 `onLoad: ;print('hi')`。

通过以上步骤即可维护一份可靠的 Fluxon VS Code 扩展环境，享受一致的语法体验。