oak-assistant

oak-assistant 是面向 Oak 小程序项目的 VS Code 编辑器扩展。它为 index.xml、index.wxml 以及 Oak 页面/组件目录中的 WXML 模板提供语法高亮、诊断、补全、悬浮、跳转、格式化和 TypeScript 级别的模板智能提示。

当前项目是从 oak-cli/tooling/vscode/oak-wechat-mp-xml 拆出的独立插件项目，仓库目录保持为 oak-assistant-new，扩展市场 ID 为 oak-team.oak-assistant-new，用户显示名为 Oak Assistant (oak-team)，当前版本为 3.2.3。编辑器能力独立演进，但仍复用 Oak CLI 生成的 metadata、共享 WXML 分析器和虚拟 TSX runtime。

能力边界

插件和 Oak CLI 的职责分成两层：

层	负责内容	运行位置
Oak CLI	小程序编译期 WXML/XML 检查、原生组件属性数据、模板符号 metadata、虚拟 TSX、TypeScript build diagnostics、共享 LESS/WXML 分析器	`oak-cli` 构建流程
oak-assistant	VS Code 语言服务、编辑器诊断、补全、悬浮、跳转、格式化、语义着色、Rainbow Tags、tsserver plugin 接入	VS Code Extension Host

扩展把构建时选定的 @xuchangzju/oak-cli runtime 直接打包进 VSIX，并且运行时只从扩展自身的 node_modules/@xuchangzju/oak-cli 读取公开导出；不会读取用户项目、同级 checkout、全局安装或 OAK_CLI_ROOT。VSIX 中的快照只包含编辑器所需的虚拟 TSX、WXML/LESS 分析器和原生组件数据，不包含完整 CLI 命令行实现。

支持范围

扩展只把以下文件当作 Oak 小程序模板处理：

src/pages/**/index.xml
src/pages/**/index.wxml
src/components/**/index.xml
src/components/**/index.wxml
src/**/*.wxml

文件可以被 VS Code 识别为 xml、html 或 wxml。普通 XML 文件仍可使用格式化能力，但不会被当作 Oak 模板进行 TypeScript 语义检查。

已实现能力

WXML/XML 语言体验

WXML 语言注册、XML/HTML 注入语法和中性的 Mustache 大括号语法。
微信原生组件完整目录的标签、属性、属性类型、枚举/布尔值补全、悬浮说明和官方文档链接。
wx:if、wx:elif、wx:else、wx:for、wx:for-item、wx:for-index、wx:key 等指令的补全、悬浮和语义颜色。
bind*、catch*、mut-bind:*、capture-bind:*、capture-catch:* 事件属性的补全、函数语义 token 和文档说明。
当前模板 usingComponents 中 Oak 组件和微信组件的标签补全。
componentGenerics 抽象节点标签补全；存在 { default: '...' } 时，使用默认组件的真实 TypeScript props 提供属性补全、悬浮、诊断和定义跳转。支持 index.config.ts/js 与传统 index.json。
接受标签补全后自动插入对应闭合标签，并把光标放在标签内容区域。
XML/WXML 嵌套格式化、长属性列表换行、缩进和 CRLF 保留。
Rainbow Tags：同一嵌套深度使用低饱和度颜色，XML 与 WXML 均支持。

结构和资源诊断

标签缺失、错配、多余闭合标签和不完整标签检查。
wx:else/wx:elif 兄弟节点关系检查。
wx:for 作用域检查，默认变量 item/index，以及自定义 wx:for-item/wx:for-index 的词法跳转和重复声明诊断。
wx:key 是否存在、是否为合法字段，以及是否能从循环项类型中访问的字段检查。
class="..." 静态类名检查，解析同目录 index.less、相对 @import、node_modules LESS 和生成的选择器；支持跳转、悬浮和已解析类名的实线链接装饰。
<image src="./...">、<import src="...">、<include src="...">、<wxs src="..."> 等相对资源跳转和缺失文件诊断。
<template name>、<template is> 及 import/include 模板符号的定义跳转。
诊断、日志、状态提示和命令提示均通过 locales/zh_CN.json 与 locales/en_US.json 本地化；VS Code 中文变体统一使用中文，其他语言回退到英文。

OakComponent 与 TypeScript 智能能力

读取 Oak CLI 生成的 wechat-mp-component-props.json，区分 OakComponent 和微信原生 Component，避免给原生组件错误追加 Oak runtime 属性。
优先使用虚拟 TSX 直接导入当前 usingComponents 及 componentGenerics.*.default 的组件类型；有 metadata 时读取 Oak CLI 生成结果，没有 metadata 时会从同级 index.config.* 或 index.json 的静态配置解析组件来源，再交给 tsserver；TypeScript 不可用时保留 metadata/config/native fallback。
自定义组件静态属性值直接使用真实 TypeScript props 类型补全；字符串字面量联合会在引号内提供候选并精确替换当前输入，同时保留布尔值和数字字符串的类型转换与诊断。
对同级 index.ts/index.tsx 中的 properties、data、methods 提供模板表达式补全、悬浮和定义跳转；formData 会参与源映射和未声明数据检查，formData-only 字段不会被无条件当作稳定 data 补全来源。
bindchange="onHotelChange" 等事件处理器会按函数语义处理，不再显示成普通字符串；事件函数和数据字段都映射回原始 TypeScript 范围。
虚拟 TSX 保留嵌套 wx:for 作用域、默认 item/index、wx:key 字段访问、Oak 注入的 t 和模板全局变量。
虚拟 TSX 使用源映射将 tsserver 的补全、悬浮、定义和诊断精确映射回 WXML。
标准 Oak Render 中默认导入的 *.less 会注入为精确 CSS Module 类型；Styles.container 支持 TypeScript 原生补全、hover、缺失 class 诊断和 Ctrl+点击跳转到 LESS 定义，hover 同时显示首个定义的声明内容。虚拟类型保留 compound selector、后代/直接子代/相邻兄弟/普通兄弟、:is/:where/:not/:local/:global 和 Fragment/条件 JSX 结构；父 scope 使用 interface 继承，同时条件使用交叉类型，互斥条件使用联合类型。连字符 class 同时提供与 Vite 一致的 camelCase 属性并保持精确 LESS 跳转。
TypeScript 6 及以下启用 Oak tsserver plugin；TypeScript 7 或 tsgo 显示本地化警告并保留 metadata/native fallback，避免整个编辑器功能失效。

Render i18n 检查

对当前打开的 web.tsx、web.pc.tsx、web.mobile.tsx、render.native.tsx 等标准 Oak render 检查标识符 t(...)；不会把普通对象的 helper.t(...) 当作 Oak 翻译调用。
对当前打开且可识别为 OakComponent(...) 的组件 index.ts/index.tsx 检查 this.t(...)；普通 TypeScript 文件和其他对象的 .t(...) 不会误报。
XML/WXML 也是 render 输入。模板中的 {{t('key')}} 会在虚拟 TSX 中以 ctx.t(...) 复用同一检查器，诊断范围再精确映射回原模板。
支持组件同级 locale、common::key 公共 namespace 和 entity:key 实体 locale；静态字符串、字符串字面量联合、模板字符串、字符串拼接和 placeholder 参数均会检查。
缺失 key、无法静态确定的 key 或 placeholder 参数问题以 warning 显示；鼠标悬浮 t(...) 的静态 key 参数会逐行显示 zh_CN、en_US 等已有语言值，每行可点击跳转到对应 JSON 字段。
静态 key 参数默认显示与 LESS class 相同的实线下划线；t 函数本身保持 TypeScript 默认 hover，Ctrl+点击 key 可跳转到各语言 JSON 定义，动态或缺失 key 不显示伪链接。
诊断只针对当前打开的 render、template 或 OakComponent 入口计算，并按 tsserver Project、源码版本和 locale 文件签名缓存；在父目录同时打开多个 Oak 项目时不会串用其他项目的 locale。

Oak CLI 编译期能力

Oak CLI 在构建小程序时会复用同一套模型：

输出组件属性和模板符号 metadata 到 node_modules/.cache/oak-cli-wechat-mp-props/wechat-mp-component-props.json。
对 XML/WXML 做原生组件属性、标签结构、循环作用域、wx:key、LESS 类名、资源引用和模板关系检查。
生成虚拟 TSX 并运行 TypeScript diagnostics，将错误按 tscBuilder 风格映射回 XML/WXML。
oak-cli build ... --check-style-less 可在 tscBuilder/Vite diagnostics 中启用与编辑器一致的 Render LESS Module class 及嵌套 JSX 作用域检查；默认构建不新增该诊断。
共享 WXML/LESS 源码位于 oak-cli/src/vscode/wechatMpShared，由 Oak CLI 构建到 lib/vscode/wechatMpShared；VS Code 和编译器均通过四个明确的 @xuchangzju/oak-cli/wechat-mp/shared/* 公共入口复用编译产物，内部模块不对外导出。

配置

在 VS Code settings.json 中配置：

{
  // 可以是相对工作区路径、绝对路径或路径数组
  "oak-assistant.metadataPath": "node_modules/.cache/oak-cli-wechat-mp-props/wechat-mp-component-props.json",

  // 是否在组件标签名上显示完整属性悬浮
  "oak-assistant.hoverComponentTags": true,

  // 是否启用 Rainbow Tags
  "oak-assistant.rainbowTags.enabled": true,

  // XML/WXML 格式化的最大行宽
  "oak-assistant.format.maxLineLength": 120,

  // 输出 WXML/render 虚拟代码和 source map 到 node_modules/.cache
  "oak-assistant.debug.enabled": false
}

调试模式会按源文件相对最近 Oak 项目根目录的结构输出文件。WXML 写入 node_modules/.cache/oak-mp-debug；非小程序 render 写入 node_modules/.cache/oak-render-debug，包含虚拟 render TSX、index.__oak_render_<platform>_types.ts 合同、*.__oak_less_module_*.ts LESS Module 类型和 render/contract source map。调试文件仅用于查看生成结果，不应提交到 Git。

可用命令：

oak-assistant: Reload Metadata：重新读取 metadata 并刷新所有诊断。
oak-assistant: Show Status：查看当前工作区、组件数量和 metadata 路径。
oak-assistant: Show Current Props：查看光标所在组件的属性来源。
oak-assistant: Pick Current Prop：打开当前标签的属性补全。
oak-assistant: Toggle Component Tag Hover：切换组件标签悬浮详情。

本地开发

目录结构要求如下：

oak/
├── oak-assistant-new/
└── oak-cli/

安装插件项目自身依赖：

npm install

本地开发时，插件的开发依赖通过 file:../oak-cli 安装，打包脚本会把同级 Oak CLI 的编译产物复制为 VSIX 内置 runtime：

npm install
npm test

修改 Oak CLI 的 TypeScript runtime 后，先在 oak-cli 生成最新 lib/vscode/wechatMpTypeScript；插件会直接读取该公开导出，不需要再执行同步脚本。

测试和打包

# 契约/单元测试
npm run test:contracts

# 两套 VS Code Extension Host：正常 TypeScript + TypeScript 7 fallback
npm run test:vscode

# 真实 VS Code 复杂多项目性能测试（P50/P95/max）
npm run test:performance

# 完整验证
npm test

# 生成 VSIX
npm run package:vsix

Extension Host 测试默认使用 VS Code 1.129.0。可以通过 OAK_VSCODE_EXECUTABLE 指定本机 Code.exe；如果已经安装了打包后的扩展，可以通过 OAK_MP_XML_EXTENSION_PATH 让测试直接加载安装目录：

$env:OAK_MP_XML_EXTENSION_PATH = "$env:USERPROFILE\.vscode\extensions\oak-team.oak-assistant-new-3.2.3"
$env:OAK_VSCODE_EXECUTABLE = 'D:\Develop\Projects\oak\oak-cli\.vscode-test\vscode-win32-x64-archive-1.129.0\Code.exe'
npm run test:vscode

性能测试会创建 3 个 Oak 项目、72 个额外组件、144 个 Render 文件和一个包含 5000 个字段的复杂类型，并通过真实 VS Code command/provider 链路统计 XML/WXML、Render TSX、多项目切换、补全、hover、跳转、签名、诊断及缓存刷新的耗时。采样和报告规则见 docs/performance-testing.md。

打包：

npm run package:vsix
code --install-extension .\oak-assistant-new-3.2.3.vsix --force

发布到 VS Code Marketplace 前配置 VSCE_PAT，然后执行 npm run publish:marketplace。该命令复用与本地打包相同的 staging 流程，先生成完整 VSIX，再以 oak-team.oak-assistant-new 身份发布。

VSIX 使用临时 staging 目录，包含扩展运行文件、生产依赖、@xuchangzju/oak-cli 公共 WXML/runtime 快照、语法文件和语言包；完整 Oak CLI、测试、.vscode-test、package-lock.json、构建脚本和项目进度文档不会进入安装包。无论工作区如何组织，运行时都固定使用该 VSIX 内置版本。

故障排查

输出 `Invalid argument` 但编辑器没有红线

先执行 oak-assistant: Show Status，确认当前文件命中了 Oak 模板路径，并确认 metadata 文件存在。插件会把分析异常写入 oak-assistant 输出通道，并发布 oak-wxml-analysis-failed 可见诊断；如果仍无红线，请检查 VS Code 是否加载了新 VSIX 而不是旧版本。

TypeScript 7 警告

TypeScript 7/tsgo 当前不能加载 VS Code TypeScript server plugin。请在 TypeScript 版本选择器中切换到 TypeScript 6 或更低版本并重启 VS Code，以启用虚拟 TSX、完整类型诊断和精确映射。未切换时，原生组件提示、metadata 属性提示、基础 WXML 诊断和格式化仍然可用。

XML 第一行提示 tsserver 崩溃

这通常表示同级 index.ts 的类型递归或展开过深。诊断会列出可执行的处理建议：为 formData 显式声明返回值类型，为 data、properties、methods 和复杂泛型补充明确类型，并减少深层交叉、递归或循环引用。修改并保存 index.ts 后重新编辑或打开 XML/WXML；原始 tsserver 错误仍保留在 oak-assistant 输出通道中。

组件属性没有提示

确认：

VSIX 内置的 @xuchangzju/oak-cli runtime 必须存在并包含 wechat-mp/runtime 和 wechat-mp/shared/* 导出；用户项目中的同名依赖不会被读取。
没有 metadata 时，组件所在目录应存在静态 index.config.ts/js 或 index.json，并在 mp.usingComponents/usingComponents 中声明普通组件，或在 mp.componentGenerics/componentGenerics 中声明抽象节点；插件会直接解析相对路径、@project 和 @oak-* 包别名。
当前组件出现在模板 metadata/config 的 usingComponents 中，或属于当前 componentGenerics；抽象节点有 default 时会导入默认组件类型，没有 default 时只保留抽象标签识别和通用 WXML 能力。
OakComponent 类型能从同级 index.ts 和组件相对路径解析；若组件只有 WeChat Component 的 JS 实现，则至少需要可解析的组件来源或构建 metadata 才能显示完整属性表。

虚拟 TSX 与源代码不一致

打开 oak-assistant.debug.enabled 后触发对应文件的 TypeScript 检查。WXML 产物位于所属 Oak 项目（向上最近的 package.json）的 node_modules/.cache/oak-mp-debug/；web.tsx、web.pc.tsx、render.native.tsx 等 render 产物位于同一项目的 node_modules/.cache/oak-render-debug/。该目录同时包含可读的 OakLessType_<classPath> LESS scope 虚拟类型。map 中包含标准 source map、sourcesContent 和 x_oakMappings 可读映射，render TSX 指向原 render，平台合同指向同级 index.ts。

项目结构

extension.ts                          # VS Code 激活入口和 provider 注册
oak-cli-resolver.ts                   # 从 VSIX 内置 runtime 解析 Oak CLI 公开导出
src/analysis/                         # WXML、LESS、资源和 Oak 模板分析（TypeScript）
src/metadata/                         # oak-cli metadata 读取、缓存和作用域筛选
src/providers/                        # 补全、悬浮、跳转、诊断、格式化、Rainbow Tags、TS
src/support/                          # 路径、工作区、常量、i18n 辅助和 debug 输出
typescript-plugin/index.ts            # VS Code TypeScript server plugin 源码
scripts/package-vsix.ts               # TypeScript staging 打包脚本
dist/                                 # tsc 生成的运行时 JavaScript（不提交）
syntaxes/                             # WXML TextMate grammar 和语言配置
locales/                              # 运行时诊断和提示的中英文资源
test/                                 # TypeScript 契约测试、Extension Host 测试和回退模式测试

仓库内维护的扩展、provider、Oak CLI resolver、tsserver plugin、VSIX staging 脚本和测试全部使用 ES Module 风格的 TypeScript import/export。生产 tsconfig.json 开启 strict 与 noImplicitAny，所有生产函数参数、回调参数和公共动态边界都必须有可验证的类型；测试 mock 使用独立的 tsconfig.test.json 编译，避免动态 VS Code 桩污染生产类型门禁。同步动态加载统一通过 createRequire 隔离；tsserver plugin 仅在 VS Code 要求的 callable CommonJS 模块边界使用 TypeScript export =。npm run build 会先清理 dist/，再分别用两个 tsc 配置编译生产和测试 JavaScript；Node、VS Code 和 VSIX 最终只执行 dist/**/*.js。VSIX staging 会排除 dist/test 与 dist/scripts，不会把测试或打包工具带入安装包。

许可证

GPL-3.0-or-later，详见仓库根目录的 LICENSE。

Oak Assistant (oak-team)

oak-team