openharmonyinsight CTS开发修复技能
本技能提供ArkTS前端编译器(ets2panda)CTS测试用例修复的完整开发流程，涵盖问题定位、代码修改、测试验证和上库标准。
前置技能：Spec分析
当处理CTS用例失败时，必须先使用 spec-test-analyzer 技能，对失败用例进行spec规则召回和差异分析，生成「CTS缺陷Spec分析报告」。
本技能的修复工作基于该报告进行：
- 报告中的「责任模块判定」→ 确定修改哪个模块
- 报告中的「Spec与编译器行为差异分析」→ 理解根因
- 报告中的「补充测试场景」→ 确保修复覆盖边界条件
- 报告中的「Spec原文」→ 修复依据（spec-first原则）
如果尚未生成Spec分析报告，请先触发 spec-test-analyzer 技能。
重要约定
- 项目根目录: 包含
runtime_core/和ets_frontend/的目录（脚本自动检测，也可通过ARK_ROOT_DIR环境变量指定） - 编译器代码路径:
ets_frontend/ets2panda（不是ets_frontend/es2panda） - 涉及仓库:
ets_frontend和runtime_core - 编译命令执行路径:
runtime_core/static_core/ - 构建目标:
es2panda - 构建目录: 自动检测（优先级：
ARK_BUILD_DIR环境变量 >build_release>out） - 脚本位置: 所有脚本使用绝对路径，通过
common.sh自动检测项目根目录，可在任意目录执行
环境变量
| 变量 | 说明 | 示例 |
|---|---|---|
ARK_ROOT_DIR |
项目根目录（含runtime_core/和ets_frontend/） | /home/user/arkcompile |
ARK_BUILD_DIR |
构建输出目录（绝对路径） | /home/user/arkcompile/runtime_core/static_core/out |
编译模式
所有编译命令在 runtime_core/static_core/ 目录下执行：
# Release模式
cmake -B out -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchain/host_clang_default.cmake -GNinja . && cmake --build out
# Debug模式
cmake -B out -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchain/host_clang_default.cmake -GNinja . && cmake --build out
# Debug-ASAN模式
cmake -B cmake-build-debug -DPANDA_ENABLE_ADDRESS_SANITIZER=true -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./cmake/toolchain/host_clang_default.cmake -GNinja .
关键目录
| 路径 | 说明 |
|---|---|
ets_frontend/ets2panda |
编译器实现代码 |
ets_frontend/ets2panda/test/ |
编译器测试用例（ast/compiler/ets/） |
runtime_core/static_core/ |
测试命令执行根目录、编译根目录 |
runtime_core/static_core/plugins/ets/tests/ets-templates/ |
CTS测试用例模板 |
runtime_core/static_core/plugins/ets/doc/spec/ |
ArkTS语言规范文档 |
runtime_core/static_core/tests/tests-u-runner/ |
测试运行器 |
mktemp 生成的临时目录 |
当前运行渲染后的CTS用例代码目录（由 runtime.sh 自动创建和清理） |
开发流程
阶段零：准备基线（异步后台）
后台异步执行CTS全量测试保存基线结果，后续回归验证时对比：
SCRIPTS_DIR="...scripts目录绝对路径..."
$SCRIPTS_DIR/cts2.sh > baseline.txt 2>&1 &
阶段一：Spec分析（前置，由spec-test-analyzer执行）
本步骤由
spec-test-analyzer技能完成，不在此技能内执行。 如果用户直接提供了失败用例但未附带Spec分析报告，应先触发spec-test-analyzer生成报告。
输入：失败的CTS用例 + 错误信息 输出：CTS缺陷Spec分析报告（包含spec规则召回、行为差异分析、责任模块判定）
阶段二：问题定位与修复
- 阅读Spec分析报告: 获取
spec-test-analyzer输出的CTS缺陷Spec分析报告，重点关注：- 「责任模块判定」→ 确定是parser/checker/lowering中的哪个模块
- 「Spec与编译器行为差异分析」→ 理解期望行为vs实际行为的gap
- 「建议修复方向」→ 获取修复思路
- 复现问题: 使用对应测试脚本运行失败用例，确认问题可复现
SCRIPTS_DIR="...scripts目录绝对路径..." # CTS测试用例（支持 --test-file 或 --filter） $SCRIPTS_DIR/cts2.sh --test-file <用例路径> $SCRIPTS_DIR/cts2.sh --filter "*17.experimental_features/13.adding_functionality_to_existing_types*" # astchecker测试 $SCRIPTS_DIR/astcheck.sh --test-file <用例路径> # recheck测试 $SCRIPTS_DIR/recheck.sh --test-file <用例路径> # 单元测试 $SCRIPTS_DIR/ut.sh --test-file <用例路径> - 结合Spec报告定位根因: 将Spec报告中的差异点映射到具体代码位置
- Parser差异 → 查看
parser/ETSParser*.cpp - Checker差异 → 查看
checker/ETSAnalyzer*.cpp和checker/ets/*.cpp - Lowering差异 → 查看
compiler/lowering/ets/*Lowering.cpp
- Parser差异 → 查看
- 确定修改范围: 明确需要修改的文件和函数，参考
reference/architecture.md - 修改代码: 根据根因分析修改对应模块代码，严格遵循代码规范
- 增量编译:
$SCRIPTS_DIR/build_diff.sh - 确认目标用例通过: 反复修改+编译+测试，直到所有目标用例通过
阶段三：定向回归验证
确保修复的特定CTS子类用例全部通过（每步通过后才继续下一步）：
SCRIPTS_DIR="...scripts目录绝对路径..."
# 1. 目标CTS子类测试（如：adding_functionality_to_existing_types）
$SCRIPTS_DIR/cts2.sh --filter "*17.experimental_features/13.adding_functionality_to_existing_types*"
# 2. ets-runtime测试（约8分钟）
$SCRIPTS_DIR/runtime.sh
# 3. astchecker测试（约10分钟）
$SCRIPTS_DIR/astcheck.sh
阶段四：全量回归验证
按顺序执行全量回归测试：
SCRIPTS_DIR="...scripts目录绝对路径..."
# 1. CTS全量测试（约136分钟）
$SCRIPTS_DIR/cts2.sh
# 2. ets-func-tests（约30分钟）
# 直接在 static_core 下执行
cd $ARK_ROOT_DIR/runtime_core/static_core
tests/tests-u-runner/runner.sh --ets-func-tests --show-progress --build-dir out --processes=all
# 3. parser测试（约8分钟）
$SCRIPTS_DIR/parser.sh
阶段五：代码格式检查
在项目根目录（runtime_core/和ets_frontend/同级目录）执行格式检查：
SCRIPTS_DIR="...scripts目录绝对路径..."
# 检查所有仓库的修改文件格式（默认检查ets_frontend和runtime_core）
$SCRIPTS_DIR/format.sh
# 只检查ets_frontend
$SCRIPTS_DIR/format.sh --repo ets_frontend
# 只检查runtime_core
$SCRIPTS_DIR/format.sh --repo runtime_core
# 检查最后一次提交的文件
$SCRIPTS_DIR/format.sh log
# 检查最后一次提交，仅ets_frontend
$SCRIPTS_DIR/format.sh --repo ets_frontend log
根据检查结果修改代码，反复执行直到格式检查通过。
阶段六：生成代码修改报告
所有测试通过后，生成代码修改报告（模板见下方）。
测试脚本速查
所有脚本位于 scripts/ 目录，使用绝对路径，可在任意目录执行。
所有脚本通过 common.sh 自动检测项目根目录（向上查找含runtime_core/和ets_frontend/的目录）。
| 脚本 | 用途 | 参数 |
|---|---|---|
build_diff.sh |
增量编译es2panda | 无 |
build.sh |
全量编译 | 无 |
install_build.sh |
首次安装构建 | 无 |
cts2.sh |
CTS测试 | --test-file <路径> 或 --filter <模式> |
astcheck.sh |
astchecker测试 | --test-file <路径> |
parser.sh |
parser测试 | --test-file <路径> |
recheck.sh |
recheck测试 | --test-file <路径> |
runtime.sh |
ets-runtime测试 | 无 |
ut.sh |
单元测试 | --test-file <路径> |
declgen.sh |
声明生成测试 | --test-file <路径> |
runets.sh |
编译运行单个ets文件 | <文件路径> |
style.sh |
ninja clang-force-format | 无 |
format.sh |
代码格式检查（clang-format+clang-tidy） | --repo <仓库> log |
all_with_build.sh |
构建后运行全部测试 | 无 |
test.sh |
旧版全套测试（含format） | 无 |
common.sh |
共享函数（自动检测路径） | （被其他脚本source） |
代码规范
命名规范
- 新增函数命名不能过长
- 函数首个单词首字母大写，首个单词为动词（如
GetTypeFor...、Check...、Resolve...） - 不能有魔术数字、魔术字符串，必须定义为命名常量
复杂度规范
- 函数圈复杂度不超过10
- 代码缩进层级不超过5
- 单个函数不能超过49行
- 函数参数个数不超过5个
- 新增代码存在重复代码时要提取为函数
模块约束
- Checker: 不改AST形状、不新建AST节点，仅修改语义元数据
- Parser: 仅做语法解析（token→AST），不报告语义错误
- Lowering: AST→AST变换，新建节点后必须re-bind/re-check
- 详细模块约束见
reference/architecture.md
类型系统规则
- 使用
TypeRelationAPI（IsSupertypeOf、IsIdenticalTo）进行类型逻辑判断 - 不硬编码类型名（如
"escompat.Record"），不用指针比较类型 - 不引入新的状态标志（
CheckerStatus、AstNodeFlags等） - 不依赖
ToString()稳定性做语义判断，应使用类型结构/TypeRelation
通用工程规范
- 不使用显式
new/delete管理内存 - 优先使用文件级
static/私有辅助函数，不膨胀公共接口 - 使用arena allocation管理编译器对象
- Linux和Windows文本文件编码格式可能不同，注意换行符差异导致的crash
验收标准
必须通过项
- 修复命令中指定的所有失败用例均通过
- parser测试套无新增失败
- astchecker测试套无新增失败
- recheck测试套无新增失败
- ets-runtime测试套无新增失败
- CTS全量测试无回归（与基线对比无新增失败）
- 编译构建无error无warning
- 代码格式检查通过（format.sh）
代码质量项
- 圈复杂度 ≤ 10
- 函数行数 ≤ 49行
- 缩进层级 ≤ 5
- 无魔术数字/字符串
- 无冗余/重复代码
- 符合命名规范
Spec一致性项
- 行为符合最新技术预览规范（spec-first）
- 不引入spec之外的行为
- 不移除现有assertion
上库标准
Commit Message格式
[CTS] 简短描述（首行不超过50字符）
Issue: https://gitcode.com/openharmony/arkcompiler_runtime_core/issues/<编号>
Co-Authored-By: Agent
Signed-off-by: <姓名> <邮箱>
- 首行和正文之间有空行
- 首行字符数不超过50
- 关联Issue链接
必须包含
- 修复行为的对应测试用例
- spec规范依据（如涉及）
- 代码修改报告
代码修改报告
每次修复完成后，必须生成代码修改报告。报告中"Spec依据"部分应引用 spec-test-analyzer 输出的CTS缺陷Spec分析报告中的具体spec章节和规则。
模板如下：
# 代码修改报告
## 一、问题根因分析
### 1.1 问题描述
<!-- 描述CTS测试失败的现象：哪个用例、什么错误信息 -->
### 1.2 根因定位
<!-- 定位到具体模块（parser/checker/lowering）和具体函数/文件 -->
- **涉及模块**:
- **根因文件**:
- **根因函数**:
- **根因类型**: （逻辑错误 / 缺失功能 / 边界条件未处理 / spec实现不一致）
### 1.3 根因详细分析
<!-- 解释为什么会产生这个问题，从spec或编译器架构角度分析 -->
## 二、架构设计
### 2.1 修改方案
<!-- 描述修复方案的设计思路 -->
### 2.2 修改文件列表
| 文件路径 | 修改类型 | 说明 |
|----------|----------|------|
| | 新增/修改/删除 | |
### 2.3 模块影响分析
- **Parser影响**:
- **Checker影响**:
- **Lowering影响**:
- **其他模块影响**:
### 2.4 新增函数说明
| 函数签名 | 所在文件 | 职责 |
|----------|----------|------|
| | | |
## 三、影响范围
### 3.1 功能影响
<!-- 本次修改影响哪些语言特性/语法规则 -->
### 3.2 测试影响
- **新增测试用例**:
- **修改测试用例**:
- **预期影响的CTS章节**:
### 3.3 兼容性影响
<!-- 是否影响已有代码的编译行为 -->
### 3.4 回归测试结果
| 测试套 | 修复前结果 | 修复后结果 | 是否有回归 |
|--------|-----------|-----------|-----------|
| parser | | | |
| astchecker | | | |
| recheck | | | |
| ets-runtime | | | |
| CTS全量 | | | |
## 四、Spec依据
<!-- 引用spec-test-analyzer输出的CTS缺陷Spec分析报告中的具体spec章节和规则 -->
<!-- 包括：Spec章节编号、规则描述、原文引用 -->
<!-- 来源报告路径：{spec-test-analyzer输出的报告路径} -->
参考资源
- 前置技能:
../spec-test-analyzer/SKILL.md— Spec规则召回和分析，CTS修复的必经前置步骤 - 模块架构:
reference/architecture.md— checker/parser/lowering三大模块的详细架构知识 - 测试脚本:
scripts/— 所有可执行的测试和构建脚本（绝对路径，自动检测项目根目录） - 共享函数:
scripts/common.sh— 路径自动检测逻辑（detect_root_dir、detect_build_dir） - Spec规范:
runtime_core/static_core/plugins/ets/doc/spec/— ArkTS语言规范