oak-assistant

中文说明

Oak Assistant 是面向 Oak 项目的 VS Code 编辑器扩展。它为 src/entities/*.ts 提供即时 Schema 语义诊断，并为 index.xml、index.wxml 以及 Oak 页面/组件目录中的 WXML 模板提供语法高亮、诊断、补全、悬浮、跳转、格式化和 TypeScript 级别的模板智能提示。它也为 Web、Web PC、Native 和 Desktop Render 提供 props、LESS/SCSS 和 i18n 智能能力。

当前项目是独立维护和发布的 Oak Assistant 插件，扩展市场 ID 为 oak-team.oak-assistant-new，显示名为 Oak Assistant (oak-team)，当前版本为 3.8.5。VSIX 内置与发布时一致的 Oak CLI 编译 runtime；安装后的编辑器不会动态依赖用户机器上的 Oak CLI 版本。

当前版本重点

支持从业务包发布的 src/components/**/index.ts 递归复用 Oak 组件源码，同时保留消费项目自己的 Render、XML/WXML、config、style 和 locales。
Render 合同虚拟文件始终位于消费组件目录，最终复用源码只用于定义跳转、source map 和诊断，不会因依赖包路径越过消费项目的 rootDir。
支持 Web/Native Render props 注入并保留 data/properties 的显式命名类型，同时提供 LESS/SCSS 类型与作用域、i18n 诊断和 hover、实体 Schema 诊断、WXML wx:key/标签/资源检查，以及 Create OakComponent。
TypeScript 6 及以下启用完整 tsserver plugin；TypeScript 7/tsgo 保留 metadata/native fallback，并显示本地化提示。

English Overview

Oak Assistant is the official VS Code extension for Oak projects. It provides immediate Entity Schema diagnostics, WXML/XML language features, TypeScript-backed template checking, Render props inference, CSS Module type injection, i18n navigation, and Oak component scaffolding.

The extension is published as oak-team.oak-assistant-new with the display name Oak Assistant (oak-team). The current version is 3.8.5 and bundles the Oak CLI compiler runtime used by the editor, so an installed VSIX does not dynamically load an arbitrary Oak CLI version from the workspace or a sibling checkout.

Current capabilities include recursive source reuse from published src/components/**/index.ts, precise Web/Web PC/Native/Desktop Render contracts with explicit data/properties aliases preserved, LESS and Sass selector scopes, locale diagnostics and JSON navigation, SchemaBuilder-style entity diagnostics, WXML wx:key and tag/resource checks, the guided Create Oak Component command, and an Explorer migration command that converts legacy page index.json files into typed index.config.ts files without deleting the source JSON. Reused Render contracts are generated beside the consuming wrapper, while definitions and source maps still target the final reused source.

TypeScript 6 and earlier enable the full tsserver plugin. TypeScript 7/tsgo keeps metadata and native fallbacks and shows a localized compatibility message. See the detailed Chinese capability sections below for configuration, build flags, debug artifacts, testing, and troubleshooting.

安装 / Installation

在 VS Code Marketplace 搜索 Oak Assistant (oak-team)，或执行：

Search for Oak Assistant (oak-team) in the VS Code Marketplace, or run:

code --install-extension oak-team.oak-assistant-new

安装或升级后执行 Developer: Reload Window。完整类型能力需要工作区 TypeScript 6 或更低版本，并关闭 tsgo；TypeScript 7 用户仍可使用原生组件、metadata、格式化和基础诊断。

After installing or upgrading, run Developer: Reload Window. Full type features require workspace TypeScript 6 or earlier with tsgo disabled; TypeScript 7 users retain native-component, metadata, formatting, and basic diagnostic fallbacks.

能力边界

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

层	负责内容	运行位置
Oak CLI	WXML/XML 与 Render 编译期检查、组件源码复用、props/LESS/SCSS/i18n 类型合同、原生组件数据、metadata、虚拟 TSX 和 source map	`oak-cli` 构建流程及 VSIX 内置 runtime
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 快照包含编辑器所需的 WXML、Render、componentReuse、LESS/Sass、i18n、source map 和原生组件数据，不包含完整 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 语义检查。

已实现能力

右键创建 Oak 组件

在资源管理器的 Oak 项目 src/components/** 或 src/pages/** 文件夹上右键，选择 oak-assistant：创建 Oak 组件。
创建流程依次选择相对组件路径、关联实体和一个或多个平台；只有关联真实实体时才继续选择 Single/List，虚拟组件会直接跳过节点类型。组件路径支持 mobile/upsert 形式，并生成 MobileUpsert 这样的 Render 函数名。
实体候选首项为虚拟组件；其余候选来自右键所在项目的 src/entities，以及该项目 Oak 业务依赖递归提供的 src/es/lib entities。多项目工作区按最近项目根隔离，不会混入相邻项目实体。
Web PC 生成 web.pc.tsx 与 web.pc.module.less，小程序生成 index.xml 与 index.less，Native 生成 render.native.tsx 与 render.native.scss，Desktop 生成 render.desktop.tsx 与 render.desktop.module.less。公共 index.ts、index.config.ts 只生成一次；页面使用 CreatePageConfig，组件使用 CreateComponentConfig。所有组件和页面都会生成 locales/zh_CN.json、locales/en_US.json，示例 Render/XML 通过 t('title') 使用对应文案。
目标路径必须保持在当前 components/pages 根内；目标目录已存在时不会覆盖或合并任何文件。

迁移旧页面 index.json

在 Oak 项目 src/pages/<namespace>/**/index.json 文件上右键，选择“转换为config.ts”，插件会在同目录创建 index.config.ts，原 index.json 保持不变。
历史 path 转换为 route.path，enablePullDownRefresh 保留为页面配置的兼容顶层字段，其余 usingComponents、导航栏、抽象节点和其他微信页面配置统一放入 mp。
非页面 JSON、namespace 根配置和 src/components 下的组件 JSON 不显示该菜单；同目录已有 index.config.ts 时不会覆盖。

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。
本地组件可通过 import OakComponent from '@oak-general-business/components/...'; export default OakComponent; 复用依赖组件逻辑，并在同目录自定义 Web、Web PC、Native、Desktop Render 或 XML/WXML。插件内置的 Oak CLI runtime 会递归读取依赖包发布的 src/components/**/index.ts，展开到最终 OakComponent({...})，并重写为稳定的相对或包模块 import；中间复用壳不参与合同，当前组件继续使用自己的 Render、XML、config、style 和 locales。省略类型的 Render props 以及 XML/WXML 上下文都能获得精确 hover、补全、诊断和定义跳转。
标准 Oak Render 中默认导入的 *.less 会注入为精确 CSS Module 类型；递归 @import 会按最近 TypeScript 项目的 baseUrl / paths（含 tsconfig extends）解析。Styles.container 与静态 Styles['article-selected'] 共享 TypeScript 原生补全、hover、缺失 class 诊断、JSX 祖先作用域和 Ctrl+点击 LESS 定义，动态索引不伪造 class。虚拟类型保留 compound selector、后代/直接子代/相邻兄弟/普通兄弟、:is/:where/:not/:local/:global 和 Fragment/条件 JSX 结构；父 scope 使用 interface 继承，同时条件使用交叉类型，互斥条件使用联合类型。连字符 class 同时提供与 Vite 一致的 camelCase 属性并保持精确 LESS 跳转。
render.native.tsx、render.ios.tsx 和 render.android.tsx 中默认导入的 .scss / .sass 会先经 Dart Sass 真实编译，再注入为精确 Native 样式模块；变量、partials、@use、imports 和项目路径别名均参与分析。每个可导出的独立 class 返回 ViewStyle & TextStyle & ImageStyle，可直接用于 React Native View、Text、Image 的 style，并提供 class 补全、声明 hover、缺失诊断、SCSS 定义跳转和依赖变更刷新。
TypeScript 6 及以下启用 Oak tsserver plugin；TypeScript 7 或 tsgo 显示本地化警告并保留 metadata/native fallback，避免整个编辑器功能失效。

Entity Schema 即时诊断

TypeScript 项目会把所属 Oak 项目下直接的 src/entities/*.ts/*.tsx 加入分析；没有 tsconfig 的文件夹也通过 tsserver getExternalFiles 发现实体文件。
诊断覆盖 Schema 缺失和继承形式、循环/多继承冲突、属性和反向指针、Action/State/ActionDef、Relation、entityDesc/locale、索引、继承元数据、系统保留名称及反向数组目标。
同一实体的独立问题会一次返回为多条 TS9300–TS9327 诊断，不沿用 schemaBuilder 的“首错即停”；分析器内部异常使用 TS9399 显示在文件首部。
依赖包的 Schema as Alias 继承会通过当前 TypeChecker 继续解析；ActionDef 自动产生的状态属性、Oak 固有索引字段和 diamond 继承均按 schemaBuilder 行为处理。
等价继承的 ActionDef 状态字段按枚举值去重；string[]、本地值对象数组等 T[] 作为普通存储属性，只有元素实际解析到实体 Schema 时才作为反向关系。普通反向关系目标不要求声明动态 entity/entityId 指针。
每条诊断使用 source oak-assistant，范围落在实体名、属性、继承项、ActionDef、locale/index 字段等实际节点；中英文消息随插件 locale 切换。
每个 tsserver Program 按 Oak 项目根隔离，并按 Program + projectVersion + locale revision 缓存。打开父目录或多项目 workspace 时不会把另一个项目的实体、locale 或继承关系混入当前项目。
这项能力只读取源码，不调用或修改 schemaBuilder，也不写入生成目录；make:domain 仍是最终生成和编译验证。TypeScript 7/tsgo 暂时不能加载 tsserver plugin，因此不提供完整实体语义诊断。

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 参数均会检查。
在 t('...')、this.t('...') 和 XML/WXML 模板翻译调用内提供 key 候选；本地 key 直接补全，共享 locale 与实体 locale 按 namespace:: / entity: 前缀分层加载，未闭合字符串在编写过程中也能继续补全。
缺失 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。
为标准 Web/Web PC/Native/Desktop Render 注入 props、LESS/SCSS 和 i18n 类型检查；--emit-injection-types 可将推导后的 Render contract 写入最终声明文件。
对 import OakComponent from '...'; export default OakComponent; 递归展开依赖包发布的 src/components/**/index.ts，并把虚拟合同放在消费 wrapper 目录，避免跨项目 rootDir 诊断。
oak-cli build ... --check-style-less 可在 tscBuilder/Vite diagnostics 中启用与编辑器一致的 Render LESS Module class、嵌套 JSX 作用域及 Native SCSS/Sass 检查；本地函数/箭头辅助组件、普通 JSX helper，以及数组字面量/push 中先生成再作为 JSX 子节点插入的元素，会沿静态调用链和所有同函数插入点继承 LESS 作用域；任一可达上下文不满足 selector 时仍会诊断；默认构建不新增该诊断。
共享 WXML/LESS/Render 源码位于 Oak CLI src/vscode，由 TypeScript 编译到 lib/vscode；VS Code 和编译器只通过 @xuchangzju/oak-cli 的公开 lib 导出复用，内部模块不对外导出。

配置

在 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。复用组件的合同位于消费组件目录，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 执行 npm run build 生成最新 lib；插件打包脚本会把需要的公开 lib/vscode runtime staging 到 VSIX，不需要手工复制源码或运行同步脚本。

测试和打包

# 契约/单元测试
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.8.5"
$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.8.5.vsix --force

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

VSIX 使用临时 staging 目录，包含扩展运行文件、生产依赖、@xuchangzju/oak-cli 公共 WXML/Render/componentReuse/LESS/Sass 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 或 OakNativeScssType Native Sass 虚拟类型。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/                    # VS Code tsserver 组合入口、实体诊断器和独立 i18n loader
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