JetBrains 集成（LSP Support + YAML DSL LSP）¶

0) 前置条件¶

• 二选一：
• uv 已安装（uvx 可用，推荐）
• 可执行命令 scalim-yaml-dsl-lsp 已在 PATH 中（installed 模式）
• IDE 已启用/安装 YAML plugin（用于 schema/结构体验）
• 安装 JetBrains Marketplace 插件：LSP Support（用于运行自定义 LSP server）

1) 最小配置（stdio）¶

在 LSP Support 的设置页中添加一个 server definition（不同 IDE/版本 UI 可能略有差异,关键词通常为 Language Server Protocol / LSP Support）：

• Command: uvx
• Arguments: scalim-yaml-dsl-lsp serve --log-level INFO
• Scope / File pattern（建议）：
• scalim.yaml
• demand/**/*.y*ml
• workflow/**/*.y*ml
• Working directory / Root（若可配置）：设为项目根目录（包含 scalim.yaml 的目录）

installed 模式等价写法：

• Command: scalim-yaml-dsl-lsp
• Arguments: serve --log-level INFO

1.1) 推荐：长 call_by 用 block scalar（不丢跳转）¶

当 call_by 参数很长时,推荐用 YAML block scalar（|/>）拆成多行；LSP 仍可在 block scalar 内对 head reference 与 kwargs RHS field-id 提供跳转/hover/补全。

推荐写法（示例）：

• 参数行允许 Python 风格 # 注释（不在 string literal 内）
• trailing comma 可选

call_by: |
  ..loaders:xx(
    a=a,
    b=b,  # trailing comma optional
  )

2) Schema vs LSP：推荐组合¶

JetBrains YAML plugin 负责结构校验/补全；YAML DSL LSP 负责语义能力（diagnostics + Python 引用跳转/hover/补全 + actions）。

建议在 YAML 文件头写入 $schema modeline（示例）：

# $schema: /ABS/PATH/TO/src/scalim/dsl/yaml_dsl/schema/demand.gen.json

提示：仓库内提供了批量写入/更新 modeline 的 CLI（见 docs/doc/yaml-dsl/cli-reference.gen.md 的 yaml-dsl upsert-lsp-comment）。

3) 日志与排障¶

若发现 server 启动但功能不生效,优先获取 discovery 摘要：

uvx scalim-yaml-dsl-lsp dump-discovery path/to/demo.yaml --json
# installed: scalim-yaml-dsl-lsp dump-discovery path/to/demo.yaml --json

如需更详细日志,可在 server 启动参数中加：

• --log-level DEBUG
• --log-file /tmp/scalim-yaml-dsl-lsp.log

更多排障项见：Troubleshooting