arkts-code-check

name	arkts-code-check
description	ArkTS 代码审查技能。当用户需要审查 ArkTS/TS 代码、排查编译错误、检查代码规范、诊断编译问题时使用此技能。专注于 Critical 级别语言合规性检查（禁用特性、类型系统、导入导出、ArkUI 装饰器约束、Sendable 并发限制）。生成带修复建议的 Markdown 报告。适用场景：ArkTS 代码审查、编译错误排查、类型系统验证。

ArkTS Code Review 技能

核心能力

本技能为本地 ArkTS 代码提供 Critical 级别静态分析，专注于检测会导致编译失败的语法和语言规范违规。

1. 编译问题诊断（Critical 级别）

检测会导致编译失败的语法和语言规范违规：

• 禁用特性检测：

  • any 类型使用（仅 .ets 文件，.ts 文件豁免）
  • var 声明（仅 .ets 文件，.ts 文件豁免）
  • 禁止的全局对象（eval、with、Proxy、Reflect 部分方法；Reflect.get/set/has/ownKeys 允许使用）
  • 运行时对象布局变更

• 类型系统检查：

  • 缺失类型注解（函数参数、返回值、变量）
  • 泛型使用错误（Array/Map/Set 缺少类型参数）
  • 类型断言滥用（undefined 类型、this 类型）
  • Symbol 类型使用、计算属性名

• ArkUI 约束检查：

  • build()/@Builder 内禁止局部变量、console、switch、三元组件选择、本地作用域
  • @Builder/@BuilderParam 使用约束
  • 装饰器组合限制（@ComponentV2 禁混 V1 装饰器、@Once 须配 @Param 等）
  • 持久化存储装饰器规范

• Sendable 并发约束：

  • 继承限制、接口实现、字段初始化
  • @Concurrent 函数不能访问闭包变量
  • TaskPool/Worker 限制

审查流程

输入格式

接受以下输入：

1. 单个文件路径：

   /path/to/file.ets
   

2. 目录路径（递归审查所有 .ets/.ts 文件）：

   /path/to/project/
   

3. 文件列表（多个文件）：

   /path/to/file1.ets /path/to/file2.ts
   

4. 内联代码（用户直接粘贴代码片段）： 将代码写入临时文件后审查：

   cat > /tmp/inline_review.ets << 'EOF'
   <粘贴的代码>
   EOF
   python3 tools/review_engine.py /tmp/inline_review.ets
   

执行步骤

1. 文件收集：

   • 解析输入路径
   • 递归查找 .ets 和 .ts 文件
   • 排除 node_modules、build、dist 等目录

2. 多层次分析：

   • 语法层：禁用特性、类型声明
   • 语义层：类型兼容性、作用域规则

3. 问题分级：

   • Critical：必须修复（编译阻断）

4. 报告生成：

   • 生成结构化 Markdown 报告
   • 包含代码片段、修复建议、参考文档

输出格式

生成的 Markdown 报告结构：

# ArkTS Code Review Report

**审查时间**: <时间戳>
**技能版本**: arkts-code-check v1.5.0

---

## 📈 TOP20 命中规则

| 排名 | 规则ID | 规则名称 | 命中次数 |
|-----|--------|---------|----------|
| 1 | `C-TYPE-001` | 禁止使用 any 类型 | 5 |
| ... | ... | ... | ... |

---

## 📊 审查摘要

| 严重级别 | 数量 | 状态 |
|---------|------|------|
| 🔴 Critical | X | ❌ 必须修复 / ✅ 通过 |

**总体评估**: <状态说明>

---

## 🔴 Critical Issues

**这些问题会导致编译失败，必须立即修复！**

### [C-TYPE-001] 禁止使用 any 类型

**位置**: `file.ets:行号:列号`

**分类**: <问题分类>

**问题代码**:

```typescript
<原始代码片段>

问题说明: <详细说明>

修复建议: <修复建议文本>

参考文档: 文档路径

---

✅ 修复优先级建议

1. 立即修复（阻止编译）

• [C-TYPE-001] 禁止使用 any 类型 (file.ets:10)
• ...

---

报告生成器版本: report_generator.py v1.5.0

### 自动修复流程（可选）

报告输出后，使用 `AskUserQuestion` 询问用户是否启动 AI 自动修复。

#### 触发条件
- 用户确认允许修复
- 报告中存在 Critical 问题

#### 修复原则

| 原则 | 说明 |
|------|------|
| **保守修复** | 最小化改动、语义等价优先 |
| **不确定跳过** | 复杂场景、多文件依赖、上下文不明确时跳过 |
| **读后再写** | 修复前必须使用 `Read` 工具读取目标文件完整内容 |
| **单文件单次** | 每个文件每轮只修复一次，避免累积错误 |

#### 修复流程（最多 3 轮）

第 N 轮开始 ↓

1. 解析报告，按规则分组 ↓
2. 逐规则读取对应参考文档（使用 rules_registry.yaml 定位） ↓
3. 理解修复意图，执行修复（应用保守原则） ↓
4. 重新执行检测（python3 tools/review_engine.py） ↓
5. 统计 error 数量变化 ├── 修复前：N 个 ├── 修复后：M 个 └── 变化：减少 X 个 / 新增 Y 个 ↓
6. 输出新报告 ↓
7. 若仍有 error 且未达 3 轮上限 → 询问是否继续

#### 3 轮上限说明

防止"修复引入新 error → 再修 → 再引入"的无限循环。每轮应尽量处理当前报告中所有可确定修复的 error。

#### 示例交互

检测报告输出后

检测完成，发现 15 个 Critical 问题。

? 是否允许 AI 自动修复？

• 是，开始自动修复（推荐）
• 否，我将手动修复
• 查看详细报告后决定

用户选择"是"

开始第 1 轮自动修复...

• 读取规则 C-TYPE-001 参考文档: arkts_code_check_references/learning-arkts/ArkTS编程规范.md
• 修复 5 处 any 类型问题
• 读取规则 C-TYPE-002 参考文档...
• 修复 3 处 var 声明问题 ...

重新检测中...

═══════════════════════════════════════ 第 1 轮修复完成 ═══════════════════════════════════════ 修复前：15 个 Critical 修复后：4 个 Critical 减少：11 个 ═══════════════════════════════════════

剩余 4 个问题需要更复杂的上下文分析。 是否继续第 2 轮？

• 是，继续修复
• 否，结束修复流程

## 参考文档索引

本技能使用以下核心索引文件快速定位规则和指南：

### Tier 1: 编译问题核心（高频引用）

- **`arkts_code_check_indexes/language-rules-index.md`**
  ArkTS 语法规则速查表，包含禁用特性清单、类型系统约束、决策树式检查流程

- **`arkts_code_check_indexes/compilation-errors-guide.md`**
  编译错误诊断手册，映射错误码 → 根因 → 修复方案

### Tier 2: 原始参考文档（按需引用）

- **`arkts_code_check_references/learning-arkts/`**
  ArkTS 语言介绍（类型系统、Null Safety、禁用特性）

- **`arkts_code_check_references/应用框架/ArkTS（方舟编程语言）/ArkTS并发/`**
  Sendable 协议、TaskPool、Worker 使用规范

### 使用策略

1. **检测到 Critical 问题**：优先查阅 `language-rules-index.md` 和 `compilation-errors-guide.md`
2. **遇到未知错误码**：使用 `compilation-errors-guide.md` 查找映射关系

## 工具脚本

本技能包含以下工具脚本（位于 `tools/` 目录）：

### 1. `review_engine.py` - 入口脚本

主要功能：
- 解析命令行参数（文件或目录路径）
- 调用 `detectors/` 模块包执行检测
- 保存 JSON 中间结果（`review_results.json`）
- **直接生成 Markdown 审查报告**（`review_report.md`）

使用方式：
```bash
python3 tools/review_engine.py <文件路径或目录>
# 输出：review_results.json（中间结果）+ review_report.md（最终报告）

1.1 detectors/ - 检测器模块包

文件/目录	内容
base.py	基础类：Severity、CodeIssue、ArkTSParser
critical_type.py	Critical 类型系统检测器入口（代理到 critical/ 子模块）
critical/	Critical 类型系统检测器子模块（58 个规则）
├─ rule_id.py	规则 ID 常量定义（C001-C058）
├─ type_system.py	类型系统检测器（any、var、泛型、类型注解等）
├─ destructuring.py	解构赋值检测器（数组/对象解构）
├─ language_features.py	语言特性检测器（for...in、globalThis、import type）
├─ advanced_types.py	高级类型检测器（映射类型、类型查询、调用签名等）
├─ object_literals.py	对象字面量检测器（内联类型、类型注解等）
└─ other_rules.py	其他规则检测器（一元操作符、throw 语句等）
critical_arkui.py	Critical ArkUI/build()/@Builder 检测器（24 个）
critical_concurrent.py	Critical Sendable/TaskPool/Worker 检测器（10 个）
__init__.py	包入口，聚合为统一 CriticalDetector 接口

2. generate_indexes.py - 文档索引生成器

主要功能：

• 扫描 arkts_code_check_references/ 目录（335 个 Markdown 文件）
• 生成以下索引到 arkts_code_check_indexes/：
  • language-rules-index.md - 禁用特性清单、类型规则决策树
  • compilation-errors-guide.md - 错误码 → 修复映射

使用方式：

python3 tools/generate_indexes.py

3. report_generator.py - Markdown 报告生成器

主要功能：

• 读取 JSON 结果文件，格式化为分类 Markdown 报告
• 添加带行号的代码片段
• 插入参考文档链接
• 生成摘要统计和优先级建议

注意：review_engine.py 已内置调用此脚本，正常审查无需单独执行。 仅在需要对已有 JSON 结果重新生成报告时独立使用：

python3 tools/report_generator.py review_results.json

4. check_staleness.py - 规则陈旧检测工具

主要功能：

• 检测 arkts_code_check_references/ 中的来源文档是否发生变更
• 定位哪些检测规则可能需要同步更新
• 读取 rules_registry.yaml 中 51 条规则与来源文档的映射关系
• 维护 doc_hashes.json 文件记录文档 SHA-256 快照

使用方式：

# 检查是否有文档变更（日常使用）
python3 tools/check_staleness.py

# 更新哈希快照（修改检测器后运行）
python3 tools/check_staleness.py --update

# 查看完整的规则-文档映射表
python3 tools/check_staleness.py --report

# 首次初始化（等同 --update）
python3 tools/check_staleness.py --init

5. rules_registry.yaml - 规则注册表

记录 51 条 Critical 检测规则与 arkts_code_check_references/ 来源文档的可溯源映射。

结构说明：

- id: "C-TYPE-001"
  title: "禁止使用 any 类型"
  detector: "CriticalTypeDetector"
  method: "detect_any_type"
  source_docs:
    - path: "arkts_code_check_references/learning-arkts/ArkTS编程规范.md"
      section: "禁止使用 any 类型"
  last_reviewed: "2026-03-16"

当参考文档更新时，通过 check_staleness.py 定位受影响规则，手动更新对应 detect_* 方法后刷新哈希。

使用示例

示例 1: 审查单个文件

用户输入：

请审查 src/components/UserProfile.ets

执行流程：

1. 使用 review_engine.py 分析文件，自动生成报告
2. 检测到问题：
   • Critical: 使用了 any 类型

输出： 包含 Critical 问题的 Markdown 报告，每个问题附带修复建议和参考文档链接。

示例 2: 审查整个目录

用户输入：

审查 src/pages/ 目录下的所有 ArkTS 文件

执行流程：

1. 递归查找所有 .ets 文件（15 个文件）
2. 逐个分析，聚合问题
3. 生成汇总报告

输出： 按文件分组的问题列表，包含统计摘要和全局优先级建议。

示例 3: 编译错误诊断

用户输入：

编译失败，帮我找出问题：src/services/DataSync.ets

执行流程：

1. 分析文件，专注 Critical 级别问题
2. 查阅 compilation-errors-guide.md 匹配错误模式
3. 提供精确修复方案

输出： 优先显示编译阻断问题，提供立即可用的修复代码。

技能触发场景

本技能应在以下场景被触发：

1. 明确审查请求：

   • "审查这个 ArkTS 文件"
   • "检查代码规范"
   • "帮我 review 一下这段代码"

2. 编译问题求助：

   • "编译失败了，帮我看看"
   • "这个文件报错，不知道怎么修"
   • "为什么编译不通过"

3. 代码质量检查：

   • "这段代码有问题吗"
   • "符合 ArkTS 规范吗"
   • "有没有性能问题"

4. 批量检查：

   • "审查整个项目"
   • "检查所有 .ets 文件"
   • "扫描代码找问题"

5. 内联代码审查（直接粘贴代码）：

   • "帮我看看这段代码有没有问题"
   • "这段 ArkTS 代码写得对吗"
   • "检查一下这个函数" → 将粘贴的代码写入 /tmp/inline_review.ets 后执行审查

关键约束

ArkTS 核心限制（必须强制执行）

1. 禁止 any 类型：所有变量、参数、返回值必须显式类型
2. 禁止 var 声明：只能使用 let 或 const
3. 禁止运行时布局变更：不能动态添加/删除对象属性

检测规则优先级

1. 仅检测 Critical 问题：报告编译阻断问题
2. 聚合相同类型问题：避免重复报告相同规则违规
3. 上下文相关建议：根据代码上下文调整修复建议

报告质量要求

1. 每个问题必须包含：

   • 精确位置（文件:行:列）
   • 问题代码片段（带行号）
   • 清晰的问题说明
   • 可操作的修复建议
   • 参考文档链接

2. 避免误报：

   • 验证问题是否真实存在
   • 区分 ArkTS 特有规则和通用 TypeScript 规则
   • 考虑框架特定模式（如 @State 装饰器）

3. 修复建议质量：

   • 提供完整、可编译的修复代码
   • 保持原有代码逻辑不变
   • 遵循最佳实践

检测器统计

本技能包含 92 个 Critical 检测规则，覆盖 ArkTS 语言规范的编译阻断约束：

按检测域分类

• Critical (92 个): 编译阻断问题检测
  • 类型系统 (58 个): any类型、var声明、Symbol、计算属性名、非空断言、undefined类型、arguments对象、解构赋值、for...in、globalThis、import type、映射类型、类型查询、调用签名、对象字面量类型等
  • ArkUI装饰器 (24 个): @State/@Link/@Prop Function类型、@Link初始化、@Builder状态定义、build()本地变量、console、switch、三元表达式、状态变更等
  • 并发限制 (10 个): Sendable继承限制、接口实现、字面量初始化、布局变更、TaskPool/Worker限制等

检测器质量

• 准确率: 高（多轮误报优化验证）
• 误报率: <2% (从>20%持续优化)
• 性能: 单文件 < 2s（中等复杂度代码）