arkts-syntax-assistant

用途

ArkTS 语法助手用于辅助 HarmonyOS/OpenHarmony 应用开发，围绕 ArkTS 语言提供语法、迁移与优化方面的指导。ArkTS 是 OpenHarmony 应用的默认开发语言，在 TypeScript 基础上增强了静态类型，以提升程序稳定性与性能。该技能在以下情况触发：.ets 文件、ArkTS 关键字、HarmonyOS/OpenHarmony 上下文等。

主要能力

ArkTS 的核心特性包括：

静态类型：所有类型在编译期确定，减少运行时检查。
无动态对象布局：对象结构在编译期固定，运行时不可修改。
受限运算符：部分运算符行为受限，以鼓励更清晰的代码语义。
不支持结构化类型：当前不支持结构化类型（structural typing）。

技能覆盖四类工作流：

语法问题：识别问题类型，查阅文档，提供代码示例。常见语法问题涉及变量声明（使用 let/const 并显式类型或推断）、函数定义（支持可选参数、默认值、剩余参数、箭头函数）、类与接口（字段必须初始化，支持继承与实现）、泛型（支持约束与默认值）、空安全（可空类型 (T | null)、非空断言 (!)、可选链 (?.)）。
TypeScript 迁移：识别 TS 代码，检查不兼容特性，查阅迁移规则，提供 ArkTS 替代方案。
性能优化：分析代码，识别性能问题，查阅优化指南，提供解决方案。
编译错误解决：获取错误信息，搜索迁移规则，查找相关案例，提供修复方案。

使用方式

技能提供参考文档，按场景查阅：

语法学习：references/en/introduction-to-arkts.md
快速概览：references/en/arkts-get-started.md
TS 迁移：references/en/typescript-to-arkts-migration-guide.md
迁移背景：references/en/arkts-migration-background.md
性能：references/en/arkts-high-performance-programming.md
更多案例：references/en/arkts-more-cases.md

回答指南要求：优先给出代码示例，展示正确与错误语法对比；引用官方文档，引导用户查阅 references/ 下对应文档；解释原因，说明 ArkTS 为何有此限制（性能、稳定性）；提供替代方案，对不支持的特性给出可行替代。

TypeScript 迁移规则速查

var x → let x
any/unknown → 具体类型
{n: 42} 对象字面量 → 先定义类/接口
[index: T]: U 索引签名 → Record<T, U>
A & B 交叉类型 → interface C extends A, B
function(){} 函数表达式 → () => {} 箭头函数
<Type>value 类型断言 → value as Type
解构 [a, b] = arr → 单独访问 arr[0], arr[1]
for..in → for 循环或 for..of
构造函数参数属性 → 显式字段声明

高性能编程要点

声明：不变量使用 const；避免整数与浮点数混用。
循环：提取循环不变量；避免数值溢出。
函数：优先参数传递而非闭包；避免可选参数。
数组：数值使用 TypedArray；避免稀疏数组和联合类型数组。
异常：避免在循环中抛出；改用返回值。

常见问题示例

JSON.parse 返回值处理：

// 错误
let data = JSON.parse(str);

// 正确
let data: Record<string, Object> = JSON.parse(str);

定义对象类型：

// TypeScript 语法（ArkTS 不支持）
type Person = { name: string, age: number }

// ArkTS 语法
interface Person {
  name: string;
  age: number;
}

// 使用对象字面量
let p: Person = { name: 'John', age: 25 };

替换 globalThis：

// 错误
globalThis.value = 'xxx';

// 使用单例模式
export class GlobalContext {
  private constructor() {}
  private static instance: GlobalContext;
  private _objects = new Map<string, Object>();

  public static getContext(): GlobalContext {
    if (!GlobalContext.instance) {
      GlobalContext.instance = new GlobalContext();
    }
    return GlobalContext.instance;
  }

  getObject(key: string): Object | undefined {
    return this._objects.get(key);
  }

  setObject(key: string, value: Object): void {
    this._objects.set(key, value);
  }
}

catch 中错误类型处理：

// 错误
try {} catch (e: BusinessError) {}

// 正确
try {} catch (error) {
  let e: BusinessError = error as BusinessError;
}

使用 Record 类型：

// TypeScript 索引签名
function foo(data: { [key: string]: string }) {}

// ArkTS Record
function foo(data: Record<string, string>) {}

// 使用示例
let map: Record<string, number> = {
  'John': 25,
  'Mary': 21,
};

用工厂函数替换构造函数签名：

// TypeScript 构造函数签名
type ControllerCtor = {
  new (value: string): Controller;
}

// ArkTS 工厂函数
type ControllerFactory = () => Controller;

class Menu {
  createController: ControllerFactory = () => {
    return new Controller('default');
  }
}

禁用的标准库 API

ArkTS 中禁用以下 API：

Global：eval
Object：proto、defineProperty、freeze、getPrototypeOf 等
Reflect：apply、construct、defineProperty 等
Proxy：所有 handler 方法

构建脚本

scripts 目录提供 ArkTS 项目的快速编译脚本（含依赖安装）：

macOS/Linux：scripts/run.sh，执行 ohpm install + hvigorw assembleApp
Windows：scripts/run.ps1，执行 ohpm install + hvigorw assembleApp

使用方式：

# macOS/Linux
bash scripts/run.sh

# Windows PowerShell
.\scripts\run.ps1

脚本执行步骤：安装依赖（ohpm install --all）、构建项目（hvigorw assembleApp）。

强制要求

当该技能生成 ArkTS 代码时，必须遵循以下工作流：

编译验证：生成代码后，必须使用构建脚本编译项目（macOS/Linux 用 bash scripts/run.sh，Windows 用 .\scripts\run.ps1）。
重试策略：若编译失败，分析错误输出，修复问题并重试编译，最多 3 次。
用户介入：3 次编译失败后，使用 AskUserQuestion 询问：编译在 3 次尝试后失败，希望如何继续？选项包括继续重试、手动介入、跳过编译。
错误报告：失败时始终显示完整的编译错误输出。

适用场景与限制

适用于 HarmonyOS/OpenHarmony 应用开发中的 ArkTS 语法查询、TypeScript 代码迁移、性能优化和编译错误排查。限制方面：ArkTS 不支持结构化类型、动态对象布局，部分运算符行为受限，且禁用若干标准库 API（如 eval、Proxy、Reflect 等）。技能本身采用 MIT 许可证，详见 LICENSE.txt。