jzcheck-lsp — VS Code Extension

JZ8P 系列 OTP 微控制器汇编语言的 VS Code 扩展，基于 jzcheck Python 包提供完整的 IDE 支持。

前置依赖

无需手动安装。扩展内置自举部署，首次打开 .asm 文件时自动完成：

自动检测系统 Python（>=3.12），创建虚拟环境并安装 jzcheck
无系统 Python 时自动下载嵌入版 Python 3.12.0 并部署

所有依赖缓存在扩展专属目录，对系统无污染。

功能

语法高亮

指令 / 伪指令 / 寄存器 / 标签 / 立即数 / 注释分色高亮
自定义 TextMate 语法规则（syntaxes/asm.tmLanguage.json）

实时诊断

打开或编辑 .asm 文件时自动推送：词法错误 / 语法错误 / 语义错误 / 内存 / 堆栈警告
错误波浪线 + 问题面板

代码补全

指令助记符（43 基础 + 24 EM78P153 别名 + INT）
寄存器名称（来自芯片配置）
工作区符号（标签 / EQU 常量）
位索引（.0–.7，含命名字段）

悬停信息

指令说明 + 操作数模式 + 影响标志位
符号值 + 定义行
宏展开内容
寄存器地址 + 位字段
$ 表达式相对偏移

跳转到定义

标签 / EQU 常量 → 定义文件位置
宏名 → MACRO 定义位置

文档符号（大纲）

标签显示为函数
EQU 常量显示为常量

CodeLens — 堆栈深度

每个函数上方显示静态堆栈深度
显示最差调用路径
递归函数标记 oo
状态栏实时显示主程序 + 中断合计深度

代码格式化

规范化缩进 / 大小写 / 对齐（四列对齐）
通过 VS Code 设置配置：
- jzcheck-lsp.format.enable — 启用格式化
- jzcheck-lsp.format.tabSize — 缩进宽度
- jzcheck-lsp.format.operandColumn — 操作数对齐列
- jzcheck-lsp.format.commentColumn — 注释对齐列
- jzcheck-lsp.format.uppercaseMnemonics — 指令大写
- jzcheck-lsp.format.uppercaseRegisters — 寄存器大写

符号重命名

跨文件重命名标签 / EQU 常量 / 宏名
保留标签定义中的冒号

调用图

基于 Mermaid 的可视化调用关系图
支持缩放 / 拖拽，位置双向持久化缓存

ROM 使用分析

按芯片型号显示 ROM 使用率
256 字节多行高亮同步模式
7 色高对比光谱设计

常见错误检查

集中展示当前项目所有文件的诊断结果（错误 / 警告 / 信息）
支持折叠分区和点击跳转到源码位置

实验性功能

编译项目功能需启用 jzcheck-lsp.experimentalFeatures 设置项（默认关闭）方可使用。启用后，状态栏和编辑器标题栏会显示「编译」按钮，支持一键编译 .mpj 项目生成 HEX / LST / XBIN / JZ 烧录文件。

使用编译功能前，需先配置 JZIDE 安装路径（jzcheck-lsp.jzIdePath）例如: "C:\JZIDE\JZ_C_IDE_V1.9.4.260511"。注意,每次更新ide后需要手动调整路径以使用最新版本编译器。

⚠️ 实验性功能不适用于生产环境。
此功能处于开发阶段，编译结果可能存在差异。请勿将其用于量产项目的编译流程。

使用

打开包含 .mpj 项目文件的文件夹（作为 VS Code 工作区根目录）
打开任意 .asm 源文件
扩展自动启动 jzcheck-lsp 语言服务器

状态栏右下角显示 ROM 使用率和堆栈深度摘要：

ROM:45%  堆栈:3/5

扩展会在工作区 .vscode/settings.json 中自动设置以下默认值：

文件编码 gb2312
.asm / .ash / .inc 文件关联为 asm 语言
LSP 通信日志级别为 off

设置项

设置	默认	说明
`jzcheck-lsp.trace.server`	`verbose`	LSP 通信日志级别
`jzcheck-lsp.format.enable`	`true`	启用代码格式化
`jzcheck-lsp.format.tabSize`	`8`	缩进宽度
`jzcheck-lsp.format.operandColumn`	`12`	操作数对齐列
`jzcheck-lsp.format.commentColumn`	`40`	注释对齐列
`jzcheck-lsp.format.uppercaseMnemonics`	`true`	指令转大写
`jzcheck-lsp.format.uppercaseRegisters`	`true`	寄存器转大写

文件编码

默认使用 gb2312 编码（JZ 汇编项目常见编码），可在 VS Code 设置中修改：

"[asm]": {
    "files.encoding": "gb2312"
}

系统要求

VS Code ^1.85.0

自举部署机制（v0.9+）

扩展首次激活时自动完成运行环境准备，无需用户手动安装 Python 或 jzcheck。

扩展激活
  └─ _ensureRuntime()
       ├─ 1. 检查缓存（provisioned-version.json）
       │    之前装好的环境还在不在？
       │    ├─ 有 + 扩展版本一致  → 直接用（快路径）
       │    ├─ 有 + 扩展版本变了  → pip install --upgrade jzcheck
       │    └─ 缓存失效          → 走第 2 步
       │
       ├─ 2. 尝试系统 Python
       │    查找 python / python3 / py -3
       │    ├─ 找到 → 创建虚拟环境
       │    │    └─ 路径: {globalStorage}/jzcheck-runtime/venv/
       │    │    └─ pip install jzcheck>=0.9.0,<1.0.0
       │    └─ 没找到 → 走第 3 步
       │
       └─ 3. 下载嵌入版 Python 3.12.10
             ├─ 从 python.org 静默安装到 {globalStorage}/jzcheck-runtime/
             ├─ 不加入 PATH，不影响系统
             └─ pip install jzcheck>=0.9.0,<1.0.0

运行目录

所有自举产物位于扩展专属缓存目录，对系统无污染：

{globalStorage}/jz-assembly.jzcheck-lsp/jzcheck-runtime/
├── venv/                      ← 基于系统 Python 的虚拟环境
│   ├── Scripts/python.exe
│   └── Lib/site-packages/jzcheck/
├── provisioned-version.json   ← 缓存版本信息
└── (Python 3.12.10/)          ← 仅在无系统 Python 时出现

更新历史

0.9.4

新增独立的 Option 配置面板，支持编辑并保存当前工程的 Option 配置

0.9.3

ISR 嵌套检测优化：combined 深度改为 main_depth + 1 + isr_call_count，更准确反映真实堆栈深度；EI 检测增加下一条指令是否为 RET 的判断，避免误报
新增编译功能（实验性）：需启用 jzcheck-lsp.experimentalFeatures 设置

0.9.2

新增扩展自举部署文档说明
自动更新 jzcheck：扩展更新时自动升级 Python 包版本
开发者模式：检测到本地源码时自动切换可编辑模式
修复首次配置 jzIdePath 后同步工程失败的竞态问题
同步完成后自动重新检查所有已打开文件的诊断
补全关键字大小写可通过 assemblyKeywordsUpperCase 配置
LSP 配置改为握手后动态加载，实时响应设置变更

0.9.0

新增「常见错误检查」视图，替代原有的时序分析视图，集中展示所有文件的诊断结果，支持折叠分区和点击跳转
新增位操作配对检查（BTS/BTC 成对检测）、死码检测（寄存器写后未读）、EQU 常量重复定义检查
同步项目功能增强：路径解析支持多级回退，同步结果实时状态栏反馈，自动修复旧路径漂移
支持未引号 INCLUDE 文件名（如 INCLUDE Display.ASH），兼容 #include 和 INCLUDE 两种写法
修复 CALL 收集误吞查表代码的问题（ret 后停止收集 CALL），减少误报
支持 CLR 指令 Bank 1 寄存器编码，裸数字 0-7 正确识别为位索引
扩展内置 Python 自举部署，无需手动安装 Python 和 jzcheck

0.7.2

修复调用图缩放/平移状态在 Mermaid 重新渲染时被重置的问题。改用 mm.render 替代 mm.run，避免 transform 属性被覆写。

0.7.1

初始发布

JZ Assembly

jz-assembly