开发前必装：Oak Assistant

Oak 项目不能只依靠普通 TypeScript、React 和 XML 插件完成编辑期检查。Oak 编译器会根据实体、同目录 index.ts、平台 render、XML/WXML、Less 和 locale 生成额外的类型合同；普通编辑器并不知道这些合同。

因此，在第一次编写实体或页面之前，请安装：

Oak Assistant (oak-team)

VS Code Marketplace ID：oak-team.oak-assistant-new

当前审计版本是 3.5.0。旧的 oak-assistant 仓库和相似名称扩展不是当前语言服务入口；排错时先在扩展详情页确认 Marketplace ID 和版本。

如果没有安装它，代码可能在编辑器中看起来没有问题，直到执行 npm run build 才集中出现实体定义、render props、XML 事件、组件属性、样式类名或翻译键错误。这会把本来应该边写边修的小问题拖到最后一起处理。

1. 它和编译器分别负责什么

可以把两者理解为同一套规则的两个入口：

插件不能代替构建。它让反馈更早，构建则是提交代码前的最终结论。

2. 安装插件

方法一：在 VS Code 中安装

1. 打开 VS Code。
2. 打开左侧“扩展”。
3. 搜索 Oak Assistant (oak-team)。
4. 确认发布者是 oak-team。
5. 点击安装。
6. 安装或升级完成后执行 Developer: Reload Window。

不要只按名字安装历史版本或相似名称插件。当前 Marketplace ID 是 oak-team.oak-assistant-new。

方法二：通过命令安装

如果本机的 code 命令已经加入 PATH，可以执行：

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

然后重新加载 VS Code 窗口。

为团队推荐插件

在项目中创建 .vscode/extensions.json：

{
    "recommendations": [
        "oak-team.oak-assistant-new"
    ]
}

这个文件不会替同事静默安装插件，但在他们打开项目时会显示推荐提示，避免团队中只有部分人拥有 Oak 编辑期检查。

3. 选择工作区 TypeScript

Oak Assistant 的完整实体语义检查和虚拟 TSX 能力依赖 VS Code 的 TypeScript Server 插件机制。当前 TypeScript 7/tsgo 不能加载这类插件，所以初学者应使用项目安装的 TypeScript 6 或更低版本。

操作步骤：

1. 先在项目根目录执行 npm install，确保 node_modules/typescript 存在。
2. 在 VS Code 中打开任意 .ts 或 .tsx 文件。
3. 打开命令面板。
4. 执行 TypeScript: Select TypeScript Version。
5. 选择“Use Workspace Version”。
6. 执行 Developer: Reload Window。

推荐在 .vscode/settings.json 中写明：

{
    "typescript.tsdk": "node_modules/typescript/lib",
    "js/ts.experimental.useTsgo": false,
    "oak-assistant.metadataPath": "node_modules/.cache/oak-cli-wechat-mp-props/wechat-mp-component-props.json",
    "oak-assistant.hoverComponentTags": true,
    "oak-assistant.rainbowTags.enabled": true,
    "oak-assistant.format.maxLineLength": 120,
    "oak-assistant.debug.enabled": false
}

为什么关闭 tsgo？不是因为 Oak 不支持新 TypeScript 语法，而是 TypeScript 7 当前没有向 VS Code 扩展开放同样的 tsserver 插件加载能力。未切换时，原生组件 metadata、基础 WXML 诊断和格式化仍可工作，但完整实体语义、虚拟 render TSX 和精确类型映射会缺失。

4. 确认插件真正生效

安装成功不等于当前工作区已经正确加载。请执行：

oak-assistant: Show Status

状态页应能识别当前 Oak 项目、metadata 路径和已发现的组件。然后依次确认：

1. VS Code 状态栏使用的是工作区 TypeScript。
2. 项目已经执行过 npm install。
3. 新增小程序 workspace 后已经执行过一次对应构建或 metadata 生成流程。
4. 修改设置或插件版本后已经重新加载窗口。

如果仍然没有诊断，打开“输出”面板并选择 oak-assistant 通道查看原因。

5. 它会检查哪些文件

实体文件

对于 src/entities/*.ts，插件会检查：

• Schema 是否正确继承 EntityShape；
• 字段、反向指针和继承关系是否合法；
• Action、State、Relation、索引和 locale 是否匹配；
• 是否使用系统保留名称；
• 多重继承或循环关系是否冲突。

这对应传统后端或 ORM 开发中的“模型定义检查”。区别是 Oak 还会由实体继续生成前后端共享类型，所以实体错误会传播到页面、权限和数据库定义。

当前实体诊断会把同一文件的独立问题分别显示为 TS9300 - TS9327，范围落在实体名、属性、继承、ActionDef、locale 或 index 的真实节点。插件只读源码，不会替你运行或修改 make:domain 产物。

TSX render

插件会分析 web.tsx、web.pc.tsx、web.mobile.tsx、render.desktop.tsx、render.native.tsx 等 render 文件，并根据同目录 index.ts 生成 props 合同。

当前规范是：

export default function Render(props) {
    return <div>{props.data.title}</div>;
}

不要再手写一个宽泛的 WebComponentProps。如果 title 没有声明，应该判断它到底来自：

• properties：由上层组件传入；
• data：组件自己的状态；
• formData：查询结果整理后的渲染数据；
• methods：组件方法；
• Oak 框架注入字段。

修复真实来源后，编译器和插件生成的合同才会一致。

复用已有 Oak 组件时

有时你只想复用公共包或另一个目录里的 Oak 逻辑，并在本地换一份平台 render。当前 CLI 和 Oak Assistant 支持下面这种精确的转发写法：

import OakComponent from '@oak-general-business/components/example';

export default OakComponent;

本地同目录可以直接写未标注 props 的 render：

export default function Render(props) {
    return (
        <button onClick={() => props.methods.submit()}>
            {props.data.title}
        </button>
    );
}

插件会把原组件对应平台的 render props 继承到本地文件，因此 title、submit 等成员仍有补全、hover、跳转和错误诊断。不要为了让这个 wrapper 通过检查再复制一份 WebComponentProps，否则公共组件升级后，本地手写类型很容易与真实合同分叉。

这不是任意导出的自动猜测。当前必须同时满足：默认导入名是 OakComponent，并且直接写 export default OakComponent。如果本地 index.ts 自己定义了 OakComponent({...})，本地定义优先；如果你需要增加新的 properties 或改动业务行为，就应建立本地真实组件合同，而不是继续把它当作透明转发。

Less Module

插件会检查 Styles.page 对应的类名是否真实存在，支持补全、悬浮和跳转，也理解嵌套选择器的作用域。

这和普通 CSS 的区别是：类名不再只是运行时字符串，而是 render 合同的一部分。拼错 Styles.compoesr 应当在编辑时被发现，而不是上线后才看到样式丢失。

XML/WXML

插件会检查：

• 标签和原生属性；
• usingComponents 和 Oak 自定义组件 properties；
• data、properties、methods、formData；
• bindtap、bindinput 等事件方法；
• wx:for 循环变量作用域；
• wx:key；
• XML 使用的 class 是否存在于 Less；
• 图片、模板等资源路径；
• Mustache 表达式的 TypeScript 类型。

传统小程序开发中，模板经常被当成字符串文件；Oak 会把模板转换为虚拟 TSX 做类型检查，因此 item.completed、事件 dataset 和组件属性都能与 index.ts 对齐。

国际化

render 和 XML/WXML 中的 t('key')，以及 OakComponent 入口中的 this.t('key')，会检查对应 locale key 是否存在。相对 key、common::key 和实体 locale 都有各自的查找规则。

鼠标悬浮静态 key 会逐行显示现有语言文本，Ctrl+点击 key 可跳到 locale JSON 的真实字段。动态 key、缺失 key 或 placeholder 参数不匹配会给出 warning，但不会生成误导性的定义链接。

6. 看懂一个典型错误

假设 render 写了：

<span>{props.data.ownerName}</span>

但 index.ts 没有 ownerName。不要先增加类型断言，而是先问：“这个值是谁提供的？”

如果由父组件传入：

export default OakComponent({
    properties: {
        ownerName: '',
    },
});

如果由查询结果整理得到：

export default OakComponent({
    data: {
        ownerName: '',
    },
    formData({ data }) {
        return {
            ownerName: data?.owner?.name || '',
        };
    },
});

这一步训练的是“组件合同”意识：渲染层不能凭空使用字段。Oak Assistant 只是把原来隐藏在运行时的问题提前展示出来。

7. 调试模式只在排错时开启

当诊断映射难以理解时，可以临时设置：

{
    "oak-assistant.debug.enabled": true
}

插件会输出虚拟文件：

node_modules/.cache/oak-mp-debug
node_modules/.cache/oak-render-debug

这些文件用于查看插件如何把 XML 或 render 转换成类型检查输入，不是项目源码，不要提交到 Git。排错结束后关闭调试模式。

常用命令：

8. 本节知识归纳

最终结论：Oak Assistant 负责早发现，npm run build 负责最终确认。两者都要使用。

下一步回到新手入门主线，从创建项目开始完成任务清单。