Imported from WSks-ui/StarFinding (
AGENTS.md). Install upstream withnpx skills add WSks-ui/StarFinding. Copyright stays with the author.
开发约定
- 必要的实现说明和安全边界使用中文注释；容易随硬件或接口变化的代码应写清修改依据。
- Git 提交信息、分支说明和后续 GitHub 推送说明使用中文。
equatorial mount废弃工程不得作为依赖或复制来源；D 盘 OnStepX/StarLite 只读参考。
ArkTS/ets 语法约束（违反条目将无法编译通过）
- 不支持索引访问类型。请改用类型名称。
- 不支持环境模块声明，因为它有自己的与 JavaScript 互操作的机制。请从原始模块中导入所需的内容。
- 不支持
any和unknown类型。请显式指定类型。 - 不支持
as const断言，因为在标准 TypeScript 中，as const用于使用相应的字面量类型标注字面量，而 ArkTS 不支持字面量类型。请避免使用as const断言，改用字面量的显式类型标注。 - 不支持对象类型中的调用签名。请改用
class（类）来实现。 - 不支持类字面量。请显式引入新的命名类类型。
- 不支持将类用作对象（将其赋值给变量等）。这是因为在 ArkTS 中，类声明引入的是一种新类型，而不是一个值。请勿将类用作对象。
- 仅在
for循环中支持逗号运算符。在其他情况下，逗号运算符会使执行顺序更难理解。请在for循环之外使用显式执行顺序。 - 不支持条件类型别名。请显式引入带约束的新类型，或使用
Object重写逻辑。不支持infer关键字。 - 不支持在构造函数中声明类字段。请在类声明内部声明类字段。
- 不支持使用构造函数类型。请改用 lambda（匿名函数）。
- 不支持接口中的构造函数签名。请改用方法。
- 不支持对象类型中的构造函数签名。请改用
class（类）来实现。 - 不支持声明合并。请保持代码库中所有类和接口的定义紧凑。
- 不支持确定性赋值断言
let v!: T，因为它们被认为是过度的编译器提示。使用确定性赋值断言运算符（!）需要运行时类型检查，会产生额外运行时开销和警告。请改用带初始化的声明。如果使用了!，请确保实例属性在使用前已赋值，并注意运行时开销和警告。 - 假定对象布局在编译时已知且运行时不可更改，因此删除属性没有意义。若要模拟原始语义，可声明可空类型并赋值为
null以标记值缺失。 - 不支持解构赋值。请改用其他惯用法，例如在适用时使用临时变量。
- 不支持解构变量声明。这是依赖结构兼容性的动态特性。请创建中间对象并逐字段操作，不受名称限制。
- 要求参数直接传递给函数，并手动分配局部名称。请勿使用解构参数声明。
- 不支持枚举的声明合并。请保持代码库中每个枚举的声明紧凑。
- 不支持使用在程序运行时求值的表达式初始化枚举成员。此外，所有显式设置的初始化器必须是相同类型。请仅使用相同类型的编译时表达式初始化枚举成员。
- 不支持
export = ...语法。请改用普通的export和import语法。 - 不允许接口包含两个具有不可区分签名的方法，例如参数列表相同但返回类型不同。请避免接口扩展具有相同方法签名的其他接口，并重构方法名称或返回类型。
- 不支持通过
for .. in循环遍历对象内容。对象布局在编译时已知且运行时不可更改，无需运行时遍历属性。对于数组，请使用常规for循环迭代。 - 不支持
Function.apply或Function.call。这些 API 在标准库中用于显式设置被调用函数的this参数，而 ArkTS 将this语义限制为传统 OOP 风格，并禁止在独立函数中使用this。请遵循传统 OOP 风格。 - 不支持
Function.bind。该 API 在标准库中用于显式设置被调用函数的this参数，而 ArkTS 将this语义限制为传统 OOP 风格，并禁止在独立函数中使用this。请遵循传统 OOP 风格。 - 不支持函数表达式。请改用箭头函数来显式指定。
- 不支持在函数上声明属性，因为不支持具有动态更改布局的对象。函数对象同样不得在运行时更改布局。
- 当前不支持生成器函数。请使用
async/await机制进行多任务处理。 - 不支持全局作用域和
globalThis，因为不支持具有动态更改布局的无类型对象。请使用显式模块导出和导入在文件之间共享数据。 - 支持函数返回类型推断，但当前存在限制。特别是，当
return表达式调用了省略返回类型的函数或方法时会发生编译错误。遇到此类情况时，请显式指定函数返回类型。 - 不支持导入断言，因为导入在 ArkTS 中是编译时特性。请使用普通
import语法，导入正确性将在编译时检查。 - 不支持
in运算符，因为对象布局在编译时已知且运行时不可更改。若要检查类成员，请使用instanceof。 - 不允许索引签名。请改用数组。
- 函数调用时仅在泛型类型参数可从实参推断时允许省略泛型类型参数；否则会发生编译错误。特别禁止仅根据函数返回类型推断泛型类型参数。推断受限时，请显式指定类型。
- 当前不支持交叉类型。请使用继承替代。
- 不支持
is运算符，必须改用instanceof。使用对象字段前，必须通过as运算符转换为适当类型。 - 不支持 JSX 表达式。请勿使用 JSX。
- 不支持映射类型。请使用其他语言惯用法和常规类实现相同行为。
- 不支持重新分配对象方法。在静态类型语言中，对象布局固定，同一对象的所有实例必须共享每个方法的相同代码。若特定对象需要特定行为，请创建单独的包装函数或使用继承。
- 所有
import语句都应位于程序中其他语句之前。请将所有import放在文件开头。 - 不支持模块名称中的通配符，因为
import在 ArkTS 中是编译时特性。请改用普通的export语法。 - 不允许类初始化存在多个静态代码块。请将所有静态代码块语句合并到一个静态代码块中。
- 不支持嵌套函数。请改用 lambda（匿名函数）。
- 不支持
new.target，因为语言中没有运行时原型继承的概念，也没有直接替代方案。 - 如果数组字面量中至少有一个元素具有不可推断的类型，例如无类型对象字面量，则会发生编译错误。请确保所有元素类型可推断，或将元素显式转换为已定义类型。
- 不支持将命名空间用作对象。请将类或模块视为命名空间的类似物。
- 不支持命名空间中的语句。请使用函数执行语句。
- 不支持将对象字面量直接用作类型声明。请显式声明类和接口。
- 只允许一元运算符
+、-和~作用于数字类型。与 TypeScript 不同，此上下文不支持字符串隐式类型转换，必要时必须显式转换。 - 不支持以
#开头的私有标识符。请改用private关键字。 - 不支持动态字段声明和访问，也不支持通过索引访问对象字段（
obj["field"]）。请在类中立即声明所有字段，并使用obj.field语法访问。标准库中的类型化数组（如Int32Array）例外，可通过container[index]访问元素。 - 不支持原型赋值，因为语言中没有运行时原型继承。请使用类和/或接口静态组合方法与数据。
- 不支持通过
require导入，也不支持import赋值。请使用常规import语法。 - 展开运算符仅支持将数组或派生自数组的类展开到 rest 参数或数组字面量中。其他场景请手动从数组和对象中解包数据。
- 不支持在独立函数和静态方法中使用
this。this只能在实例方法中使用。 - 当前不支持结构化类型，编译器无法比较两个类型的公共 API 并判断它们是否相同。请使用继承、接口或类型别名。
- 不支持
Symbol()API，因为其常见用例在静态类型环境中没有意义。除Symbol.iterator外，请避免使用Symbol()。 - 目前，用标准 TypeScript 实现的代码库不得通过导入 ArkTS 代码库来依赖 ArkTS。请避免 TypeScript 代码依赖 ArkTS 代码；反向导入（ArkTS 导入 TS）受支持。
- 仅在表达式上下文中支持
typeof运算符，不支持使用typeof指定类型标注。请改用显式类型声明。 - 在 TypeScript 中，
catch子句变量类型标注必须是any或unknown（如果指定）。由于 ArkTS 不支持这些类型，请省略catch子句中的类型标注。 - 不支持使用
this关键字进行类型标注。请改用显式类型。 - 不支持通用模块定义（UMD），因为 ArkTS 没有“脚本”与“模块”相对的概念，且
import是编译时特性。请使用普通export和import语法。 - 支持对象字面量，前提是编译器可推断这些字面量对应的类或接口，否则会发生编译错误。以下上下文不支持使用字面量初始化类和接口：初始化
any、Object或object类型；初始化带方法的类或接口；初始化声明了带参数构造函数的类；初始化带readonly字段的类。请确保对象字面量对应显式声明的类或接口。 - 当前不支持 TypeScript 扩展标准库中的实用类型，
Partial、Required、Readonly和Record例外。对于Record<K, V>，索引表达式rec[index]的类型为V | undefined。请避免其他不受支持的实用类型。 - 不支持
var关键字。请改用let。 - 不支持
with语句。请使用其他语言惯用法实现相同行为。
HarmonyOS API 使用规范（必读条目）
- 优先使用 HarmonyOS 官方提供的 API、UI 组件、动画和代码模板。
- 调用 API 前，请根据官方文档确认入参、返回值、对应 API Level 和设备支持情况。
- 对任何不确定的语法和 API 用法，不得猜测或自行构造 API；应搜索并核对华为开发者官方文档。
- 使用 API 前，请确认是否需要在文件头添加
import语句。 - 调用 API 前，请确认是否需要对应权限，并在相应模块的
module.json5中检查权限配置。 - 如需使用依赖库，请确认依赖库存在且版本匹配，并在相应模块的
oh-package.json5中添加依赖配置。 - 使用
@Component和@ComponentV2时需要区分兼容性，并尽量与现有工程代码保持一致。 - UI 界面展示所引用的常量需要定义为
resources资源值并使用$r引用，一般不直接使用字面值。 - 新增国际化字符串资源时，需要在对应的每种语言资源中添加值，避免遗漏。
- 新增颜色等资源时，请确认是否需要支持深色主题（参考历史工程）；新工程默认建议同时支持深色和浅色主题。
ArkUI 动画规范（animateTo、transform、renderGroup、opacity）
- 优先使用 HarmonyOS 提供的原生动画 API 和高级模板。
- 优先使用 HarmonyOS 声明式 UI 和
@State驱动动画，通过改变状态变量触发动画。 - 对包含复杂子组件的动画设置
renderGroup(true)，减少渲染批次。 - 不得在动画过程中频繁改变组件的
width、height、padding、margin等布局属性，否则会严重影响性能。