@deveco-test/deveco-code 1.0.2 → 1.0.4

package/resources/deveco/skills/hmos-runtime-fix-skill/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: hmos-runtime-fix-skill
+description: Load for ArkTS/JavaScript jscrash, runtime crash, uncaught exception, stack trace, faultlog, or hilog diagnosis. Also load when the app 闪退/崩溃/白屏, exits after 点击/启动/launch, or build succeeds but runtime fails (no compile error). Use before broad Read/Glob on crash-only tasks.
+---
+
+# Harmony JSCrash Fixes
+
+Use this skill to diagnose and fix ArkTS or JavaScript runtime crashes with minimal edits.
+
+Use `devecocli` for device discovery and log acquisition. Use this skill's private Node scripts under `skills/hmos-runtime-fix-skill/scripts/` only to parse evidence or save a hilog snapshot.
+
+If `node` is unavailable, stop and explain that the private scripts cannot run.
+
+## When To Load
+
+Load this skill when the issue looks like one of these:
+
+- Runtime logs show `TypeError`, `ReferenceError`, `RangeError`, `SyntaxError`, `BusinessError`, or similar exceptions.
+- The app exits, flashes back, or white-screens during launch or after a tap.
+- The user provides a `jscrash` log, stack trace, or a temporary log file with `@file`.
+- Build succeeds, but runtime behavior fails immediately.
+
+## Core Approach
+
+Prefer a concrete crash anchor before broad code exploration. A good anchor can come from:
+
+- a provided crash log
+- a stack trace
+- a clear page or module named by the user
+- a recent device-side faultlog or hilog when no better evidence is available
+
+Avoid broad `Read` / `Glob` / `Explore` across the whole project until you have at least one concrete anchor such as:
+
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`
+- or a clearly named crash entry point from the user
+
+Do not over-collect logs. If the user already gave enough crash evidence, parse that evidence first and move into focused reading and minimal fixes.
+
+## CLI And Script Contract
+
+Run `devecocli` through Shell. Do not call `hdc`, read `DEVECO_HOME`, or use DevEco Code-specific device/log tools directly.
+
+### Private Node scripts
+
+Run the private scripts through Shell like this:
+
+```bash
+node "{SKILL_DIR}/scripts/<script>.mjs" ...
+```
+
+`{SKILL_DIR}` is the absolute path of this skill directory at runtime.
+
+Scripts print stable `key: value` text to stdout. A non-zero exit code means the current step could not continue and the agent should report the reason instead of guessing.
+
+## Preferred Flows
+
+### Case A: The user already provided raw crash text
+
+```bash
+node "{SKILL_DIR}/scripts/jscrash-report.mjs" --log-text "{crashLog}" --bundle-name "{bundleName}" --include-text
+```
+
+### Case B: The user provided `@file` or a local log path
+
+```bash
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{logFilePath}" --bundle-name "{bundleName}" --include-text
+```
+
+### Case C: The user only described symptoms and did not provide logs
+
+Log collection is optional here. Use it when you still need a concrete runtime anchor.
+
+Before collecting device evidence:
+
+1. Read `AppScope/app.json5` and take the exact `app.bundleName` value (for example `com.example.hmos.sample`). Use that string as `{bundleName}` in every script below.
+2. Do not guess `bundleName` from `vendor`, module folder names, or prefixes such as `com.example`.
+3. Resolve the target device:
+   - If the user provided a `deviceId`, use it for every device-side command.
+   - If no `deviceId` is provided, run `devecocli device list` first.
+   - If exactly one device is connected, use that device.
+   - If multiple devices are connected, ask the user which device to inspect. Do not collect logs until the user selects a device.
+   - If no devices are connected, report that device-side evidence cannot be collected and ask for a connected device or a local crash log.
+
+After the user reproduces the crash on the selected device, fetch and parse the latest matching crash log:
+
+```bash
+node "{SKILL_DIR}/scripts/jscrash-report.mjs" --bundle-name "{bundleName}" --device-id "{deviceId}" --include-text
+```
+
+With no `--log-text` or `--log-file`, `jscrash-report.mjs` runs `devecocli log --crash --device ... --bundle-name ...` and parses its output. If no matching crash is returned, ask the user to reproduce and retry immediately; do not guess from symptoms alone.
+
+If the crash log is unavailable or insufficient, fall back to hilog. The collector runs `devecocli log --device ... --tail ...` and only handles the local snapshot file itself:
+
+```bash
+node "{SKILL_DIR}/scripts/collect-hilog.mjs" --device-id "{deviceId}" --lines "4000" --output-dir "{tempDir}"
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{hilogPathFromCollect}" --bundle-name "{bundleName}" --source hilog --include-text
+```
+
+## Output Contract
+
+The leading `key: value` block from `jscrash-report.mjs` and `parse-jscrash-log.mjs` includes:
+
+- `status`: `detected` | `no_crash_signature` | `parse_failed`
+- `source`: `file` | `text` | `hilog` and similar sources
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`: `|`-joined frames
+- `keywords`: comma-separated
+- `next_action`
+
+`--include-text` appends a human-readable summary after the structured block.
+
+If `status: no_crash_signature`, explain that the evidence is weak and ask for a better log, clearer repro, or an additional runtime clue before broad code reading.
+
+## JSCrash Fix Knowledge Base
+
+Knowledge source (synced): [hmos-jscrash-analysis](https://gitcode.com/HarmonyOS_Skills/harmonyos-agent-skills/tree/main/03-solutions/quality/stability/hmos-jscrash-analysis).
+
+After parsing crash evidence and obtaining `error_type`, match patterns from the knowledge base and apply the corresponding fix. Do not invent root causes or fixes outside these references.
+
+### Using the Fix Knowledge Base
+
+1. Parse crash evidence with scripts to obtain `error_type`, `error_message`, and `top_stack`.
+2. Read [reference/fault-mode-library.md](./reference/fault-mode-library.md) first. Match `JSError` → secondary cause → tertiary cause using `Reason` / `Error name` / `Error message`.
+3. Based on `error_type`, read only the corresponding patterns file:
+   - `ReferenceError` → [reference/referenceerror_patterns.md](./reference/referenceerror_patterns.md)
+   - `TypeError` → [reference/typeerror_patterns.md](./reference/typeerror_patterns.md)
+   - `Error` → [reference/error_patterns.md](./reference/error_patterns.md)
+   - `BusinessError` → [reference/businesserror_patterns.md](./reference/businesserror_patterns.md)
+   - `SyntaxError` → [reference/syntaxerror_patterns.md](./reference/syntaxerror_patterns.md)
+   - `RangeError` → [reference/rangeerror_patterns.md](./reference/rangeerror_patterns.md)
+   - `OutOfMemoryError` → [reference/outofmemoryerror_patterns.md](./reference/outofmemoryerror_patterns.md)
+   - `URIError` → [reference/urierror_patterns.md](./reference/urierror_patterns.md)
+4. When multiple patterns match, prefer the one supported by `Error message` + `Error code` + top application stack frame simultaneously (see credibility rules in each reference file).
+5. Apply a minimal fix to the suspected file from the stack. Do not refactor broadly.
+
+### Quick Reference
+
+| Error type / message keyword | Root cause | Reference |
+|---|---|---|
+| ReferenceError + `@Provide` / `@Consume` | Missing or duplicate @Provide/@Consume | [referenceerror_patterns.md](./reference/referenceerror_patterns.md) |
+| ReferenceError + `is not initialized` | Variable used before assignment | [referenceerror_patterns.md](./reference/referenceerror_patterns.md) |
+| ReferenceError + `<name> is not defined` | Variable scope or import missing | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| ReferenceError + `super()` before `this` | super() not called before this | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| TypeError + `Cannot read property` / `null or undefined` | Accessing property on undefined/null | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| TypeError + `is not callable` | Calling a non-function value | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| TypeError + `circular structure` | Circular reference in JSON.stringify | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| TypeError + `Receiver is not a JSObject` / N-API scope | N-API receiver type mismatch | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| SyntaxError + `Unexpected Text in JSON` / `Invalid Token` | Malformed JSON.parse input | [syntaxerror_patterns.md](./reference/syntaxerror_patterns.md) |
+| RangeError + `Invalid array length` | Negative or non-integer array length | [rangeerror_patterns.md](./reference/rangeerror_patterns.md) |
+| RangeError + `Stack overflow` | Unbounded recursion | [rangeerror_patterns.md](./reference/rangeerror_patterns.md) |
+| URIError + `DecodeURI: invalid character` | Malformed URI in decodeURI | [urierror_patterns.md](./reference/urierror_patterns.md) |
+| Error + `UI execution context not found` / `100001` | UI context not bound to router | [error_patterns.md](./reference/error_patterns.md) |
+| Error + `WebviewController must be associated` / `17100001` | WebviewController not linked to Web component | [error_patterns.md](./reference/error_patterns.md) |
+| Error + `ForEach id` / id generator | ForEach keyGenerator missing or invalid | [error_patterns.md](./reference/error_patterns.md) |
+| Error + `ArrayBuffer is null or detached` | Using detached ArrayBuffer | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| Error + `Map's constructor cannot be directly invoked` | ArkTS Map constructor misuse | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| Error + SQLite / RDB / resource ID / window state | DB handle, resource ID, or window API misuse | [error_patterns.md](./reference/error_patterns.md) |
+| BusinessError + `Parameter error` / URL / JSON / XML | Invalid API parameter type or value | [businesserror_patterns.md](./reference/businesserror_patterns.md) |
+| OutOfMemoryError + allocate / leak | Heap allocation failure or memory leak | [outofmemoryerror_patterns.md](./reference/outofmemoryerror_patterns.md) |
+| TerminationError + `Terminate execution!` | Forced termination by runtime | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| AggregateError + `Promise.any()` all rejected | All promises in Promise.any() rejected | [fault-mode-library.md](./reference/fault-mode-library.md) |
+
+## Interpretation Rules
+
+- Prefer application frames over framework noise.
+- Treat the first concrete `.ets`, `.ts`, or `.js` path as the starting point, not the final truth.
+- If the user gave repro steps, trust them over a simplistic stack-only guess.
+- If the stack points to a non-entry page, assume an interaction-triggered path unless evidence proves a cold-start crash.
+- Do not refactor broadly. Fix the crash path first.
+
+## Conversational Shape
+
+1. Say what evidence you already have.
+2. If logs are missing, say whether you are using a crash log or hilog to get a better anchor.
+3. Once you have an anchor, switch into focused code reading and minimal fixing.
+
+## Constraints
+
+- Never claim a crash fix from prompt reasoning alone.
+- Never replace a root-cause fix with retries, arbitrary delays, or broad defensive rewrites.
+- If unfamiliar `@ohos.*` or `@kit.*` APIs are involved, check their constraints before editing.
+- This skill does not decide the final compile / run / verification order; the primary agent owns that.

package/resources/deveco/skills/hmos-runtime-fix-skill/SKILL_CN.md

@@ -0,0 +1,160 @@
+---
+name: hmos-runtime-fix-skill-cn
+description: ArkTS Runtime Fix 的中文参考版本，仅用于保留中文说明，不作为主入口 skill。
+---
+
+# ArkTS Runtime Fix（中文参考）
+
+本技能通过 `devecocli` 完成设备发现与日志采集，通过 **skill 私有脚本**（Node）完成结构化解析和本地快照处理。不得直接调用 `hdc`、读取 `DEVECO_HOME` 或依赖 DevEco Code 专用 Tool。执行前若环境无 `node`，须停止并向用户说明。
+
+## 症状与触发
+
+在以下情况必须加载本技能：
+
+- 日志中出现 `TypeError`、`ReferenceError`、`RangeError`、`SyntaxError`、`BusinessError` 等运行时异常
+- 应用启动闪退、白屏、点击后崩溃
+- 用户提供 `jscrash` 日志、堆栈、`@file` 临时日志文件
+- 构建成功但运行期立即失败
+
+## 证据优先约束
+
+在已拿到以下锚点之前，避免对工程做大规模 `Read` / `Glob` / `Explore`：
+
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`
+- 或者用户明确指出的崩溃页面 / 模块
+
+在证据不足时，可以执行本节的私有脚本、向用户追问复现与包名、或读取用户已显式给出的单个日志文件路径。
+
+一旦锚点齐备，再定向读取疑似 `ets/ts/js` 与相关导航入口，做最小修改。
+
+## 私有脚本执行约定
+
+所有脚本和 `devecocli` 命令均通过 Shell 执行：
+
+```bash
+node "{SKILL_DIR}/scripts/<script>.mjs" ...
+```
+
+`{SKILL_DIR}` 由执行环境替换为当前技能根目录的绝对路径。脚本 `stdout` 采用稳定 `key: value` 行文本；退出码非 0 表示当前步骤无法继续，应向用户报告 `next_action` 中的原因并停止。
+
+## 场景 A：用户已提供原始日志文本
+
+```bash
+node "{SKILL_DIR}/scripts/jscrash-report.mjs" --log-text "{crashLog}" --bundle-name "{bundleName}" --include-text
+```
+
+## 场景 B：用户提供 `@file` 或本地日志路径
+
+```bash
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{logFilePath}" --bundle-name "{bundleName}" --include-text
+```
+
+## 场景 C：仅有症状，无日志
+
+设备采证前必须先读取 `AppScope/app.json5` 中的 `app.bundleName`，作为后续 `--bundle-name` 的精确值；禁止用 `vendor`、`com.example` 或模块目录名猜测。
+
+若用户未指定设备，先运行 `devecocli device list`。只有一个设备时直接使用；多个设备时须请用户选择；无设备时请求连接设备或提供本地日志。
+
+用户在选定设备上复现后，获取并解析最新的匹配崩溃日志：
+
+```bash
+node "{SKILL_DIR}/scripts/jscrash-report.mjs" --bundle-name "{bundleName}" --device-id "{deviceId}" --include-text
+```
+
+未提供 `--log-text` 或 `--log-file` 时，`jscrash-report.mjs` 内部执行 `devecocli log --crash --device ... --bundle-name ...` 并解析输出。若没有匹配日志，应让用户立即复现后重试，不得仅凭症状猜测。
+
+若崩溃日志不可用或证据不足，再进入 hilog 兜底采集。采集脚本内部执行 `devecocli log --device ... --tail ...`，自身仅负责写入本地快照：
+
+```bash
+node "{SKILL_DIR}/scripts/collect-hilog.mjs" --device-id "{deviceId}" --lines "4000" --output-dir "{tempDir}"
+node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{hilogPathFromCollect}" --bundle-name "{bundleName}" --source hilog --include-text
+```
+
+## 解析输出字段契约
+
+`jscrash-report.mjs` 和 `parse-jscrash-log.mjs` 首段 `key: value` 行包含：
+
+- `status`: `detected` | `no_crash_signature` | `parse_failed`
+- `source`: `file` | `text` | `hilog` 等
+- `error_type`
+- `error_message`
+- `suspected_file`
+- `top_stack`: 以 `|` 分隔的帧列表
+- `keywords`: 逗号分隔
+- `next_action`
+
+`--include-text` 会在其后追加人类可读完整报告。
+
+若 `status: no_crash_signature`，须向用户说明证据不足，请求复现或更完整日志后再读代码。
+
+## JSCrash 修复知识库
+
+知识来源（已同步）：[hmos-jscrash-analysis](https://gitcode.com/HarmonyOS_Skills/harmonyos-agent-skills/tree/main/03-solutions/quality/stability/hmos-jscrash-analysis)。
+
+解析崩溃证据并获取 `error_type` 后，必须按知识库匹配模式并应用对应修复建议。不得编造知识库以外的根因或修复方案。
+
+### 知识库使用方法
+
+1. 通过脚本解析崩溃证据，获取 `error_type`、`error_message` 和 `top_stack`。
+2. 先读取 [reference/fault-mode-library.md](./reference/fault-mode-library.md)，按 `Reason` / `Error name` / `Error message` 匹配 `JSError` → 二级根因 → 三级根因。
+3. 根据 `error_type`，只读对应的 patterns 文件：
+   - `ReferenceError` → [reference/referenceerror_patterns.md](./reference/referenceerror_patterns.md)
+   - `TypeError` → [reference/typeerror_patterns.md](./reference/typeerror_patterns.md)
+   - `Error` → [reference/error_patterns.md](./reference/error_patterns.md)
+   - `BusinessError` → [reference/businesserror_patterns.md](./reference/businesserror_patterns.md)
+   - `SyntaxError` → [reference/syntaxerror_patterns.md](./reference/syntaxerror_patterns.md)
+   - `RangeError` → [reference/rangeerror_patterns.md](./reference/rangeerror_patterns.md)
+   - `OutOfMemoryError` → [reference/outofmemoryerror_patterns.md](./reference/outofmemoryerror_patterns.md)
+   - `URIError` → [reference/urierror_patterns.md](./reference/urierror_patterns.md)
+4. 多个模式命中时，优先选择 `Error message` + `Error code` + 栈顶应用帧同时支持的结论（见各 reference 文件可信度规则）。
+5. 对堆栈中的疑似文件做最小定向修复，不做大范围重构。
+
+### 快速参考
+
+| 错误类型 / message 关键词 | 根因 | Reference 文件 |
+|---|---|---|
+| ReferenceError + `@Provide` / `@Consume` | @Provide/@Consume 缺失或重复 | [referenceerror_patterns.md](./reference/referenceerror_patterns.md) |
+| ReferenceError + `is not initialized` | 变量在赋值前使用 | [referenceerror_patterns.md](./reference/referenceerror_patterns.md) |
+| ReferenceError + `<name> is not defined` | 变量作用域或 import 缺失 | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| ReferenceError + `super()` 前访问 `this` | super() 未先于 this 调用 | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| TypeError + `Cannot read property` / `null or undefined` | 访问 undefined/null 的属性 | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| TypeError + `is not callable` | 调用了非函数值 | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| TypeError + `circular structure` | JSON.stringify 遇到循环引用 | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| TypeError + `Receiver is not a JSObject` / N-API scope | N-API receiver 类型不匹配 | [typeerror_patterns.md](./reference/typeerror_patterns.md) |
+| SyntaxError + `Unexpected Text in JSON` / `Invalid Token` | JSON.parse 输入格式错误 | [syntaxerror_patterns.md](./reference/syntaxerror_patterns.md) |
+| RangeError + `Invalid array length` | 数组长度为负或非整数 | [rangeerror_patterns.md](./reference/rangeerror_patterns.md) |
+| RangeError + `Stack overflow` | 无限递归 | [rangeerror_patterns.md](./reference/rangeerror_patterns.md) |
+| URIError + `DecodeURI: invalid character` | decodeURI 输入格式错误 | [urierror_patterns.md](./reference/urierror_patterns.md) |
+| Error + `UI execution context not found` / `100001` | UI 上下文未绑定到 router | [error_patterns.md](./reference/error_patterns.md) |
+| Error + `WebviewController must be associated` / `17100001` | WebviewController 未关联 Web 组件 | [error_patterns.md](./reference/error_patterns.md) |
+| Error + `ForEach id` / id 生成函数 | ForEach keyGenerator 缺失或无效 | [error_patterns.md](./reference/error_patterns.md) |
+| Error + `ArrayBuffer is null or detached` | 使用了已 detach 的 ArrayBuffer | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| Error + `Map's constructor cannot be directly invoked` | ArkTS Map 构造函数误用 | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| Error + SQLite / RDB / 资源 ID / 窗口状态 | DB 句柄、资源 ID 或窗口 API 误用 | [error_patterns.md](./reference/error_patterns.md) |
+| BusinessError + `Parameter error` / URL / JSON / XML | API 参数类型或值无效 | [businesserror_patterns.md](./reference/businesserror_patterns.md) |
+| OutOfMemoryError + 分配 / 泄漏 | 堆内存分配失败或内存泄漏 | [outofmemoryerror_patterns.md](./reference/outofmemoryerror_patterns.md) |
+| TerminationError + `Terminate execution!` | 运行时强制终止 | [fault-mode-library.md](./reference/fault-mode-library.md) |
+| AggregateError + `Promise.any()` 全部 reject | Promise.any() 中所有 promise 均 reject | [fault-mode-library.md](./reference/fault-mode-library.md) |
+
+## 解释规则
+
+- 应用栈优先于框架噪声；首个具体 `.ets/.ts/.js` 路径是起点而非唯一根因。
+- 若用户给出复现步骤，步骤优先于单纯堆栈推断。
+- 若堆栈指向非入口页，默认视为交互触发路径，除非证据表明仅冷启动。
+- 不做大范围重构，先消除崩溃路径。
+
+## 交互建议
+
+1. 先说明当前已有的证据。
+2. 如果证据不足，再说明是否按需检查 faultlogger 或 hilog。
+3. 一旦拿到锚点，就切换到定向读代码和最小修复。
+
+## 约束
+
+- 不得仅凭推理声称已修复崩溃。
+- 不得用重试、随意延时或大面积防御性改写替代根因修复。
+- 涉及不熟悉的 `@ohos.*` / `@kit.*` API 时，应先查证约束再改代码。
+- 本技能不决定最终的编译 / 运行 / 验证顺序；主 Agent 负责后续验证。

package/resources/deveco/skills/hmos-runtime-fix-skill/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "hmos-runtime-fix-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "点击应用就闪退，没有日志",
+      "expected_output": "加载 hmos-runtime-fix-skill；优先从用户现有证据中建立 crash anchor；若缺少可用日志，使用 devecocli device list 选择设备，并在复现后通过 devecocli log --crash 获取最新崩溃日志，仍不足时再通过 devecocli log 获取 hilog；在拿到明确 anchor 前不大范围 Read/Glob 工程",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "这是 jscrash 日志：TypeError ... at entry/src/main/ets/pages/Index.ets:10:5",
+      "expected_output": "直接 node 执行 jscrash-report.mjs（--log-text）或 parse-jscrash-log.mjs（--log-file），基于现有日志建立 anchor，再定向读取 Index.ets 相关入口，不额外拉取设备日志",
+      "files": []
+    }
+  ]
+}

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/businesserror_patterns.md

@@ -0,0 +1,17 @@
+# BusinessError Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `Unexpected Text in JSON` + `SyntaxError` | 应用捕获 JSON `SyntaxError` 后通过 `BusinessError` 抛出，未处理导致闪退。 | 结合栈顶代码定位异常抛出位置；解析 JSON 前校验格式，并在抛出点捕获处理。 |
+| `Parameter error` | 参数类型或取值错误，未处理导致闪退。 | 对照接口文档传入正确参数类型和范围；在调用前校验。 |
+| `unterminated entity ref` | XML/HTML 中特殊字符未正确转义。 | 检查解析文本中的特殊字符，例如 `&` 需要正确转义为 `&`。 |
+| `Syntax Error. Invalid Url string` / `10200002` | URL 字符串格式非法。 | 检查 URL 格式是否符合 `parseURL` 等接口要求。 |
+| `Syntax Error. Invalid Uri string` / `10200002` | URI 字符串非法，例如 path 不符合规则或 `#` 位于首字符。 | 检查 URI 格式、路径、片段和编码，按 `@ohos.uri` 规范构造。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/error_patterns.md

@@ -0,0 +1,31 @@
+# Error (Framework / API) Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| 应用自定义错误，如 `ApiError ...` | 应用业务代码主动抛出异常且未处理，导致闪退。 | 避免异常路径直达进程边界；使用 `try-catch` 捕获并转为可恢复状态或错误提示。 |
+| `Invalid parameter` / `The parameter invalid` / `Invalid argument` | 非法参数触发异常，通常需结合栈顶代码确认具体入参。 | 修正参数类型、范围和必填项；调用前做输入校验。 |
+| `No such file or directory` | 目录或文件不存在。 | 检查路径、权限、解压/下载时序；用 `try-catch` 处理缺失文件。 |
+| `WebviewController must be associated with a Web component` / `17100001` | `WebviewController` 尚未和具体 Web 组件关联。 | 检查关联时序，可通过 `onControllerAttached()` 确认后再操作。 |
+| `Invalid url` / `17100002` | URL 无效，或 URL 长度超过限制。 | 校验 URL 格式、协议、编码和长度，避免传入空值或超长值。 |
+| `ForEach id` + `Need to specify id generator function` | 提供的数据结构不能被默认键值生成函数处理。 | 确保数据可被默认 key 生成函数序列化，或显式传入 `ForEach` 第三个参数作为自定义 key 生成函数。 |
+| `SQLite: Generic error` / `14800021` | SQL 执行过程中出现通用错误。 | 分析并修正 SQL 语句、表结构、参数绑定和事务状态。 |
+| `Column out of bounds` / `14800013` | 当前列号超出 `[0, columnCount - 1]`，或列值/列类型与接口不兼容。 | 检查 ResultSet 当前列号、列名、列数量和查询结果。 |
+| `Invalid resource ID` | 传入资源 ID 不存在或不适用于当前包形态。 | 排查 HAR 开启混淆、中间码 HAR、字节码 HAR、跨 HAP/HSP 包等场景；优先通过资源名称方法如 `getStringByName()` 获取资源。 |
+| `UI execution context not found` / `100001` | 在上下文不明确处使用全局 Router 等 UI 上下文相关能力。 | 推荐使用 `Navigation` 作为路由框架；或通过 `UIContext.getRouter()` 获取当前上下文关联的 Router。 |
+| `Session not config` | 在会话未配置前调用需要会话配置的操作。 | 先调用对应 `commitConfig` 等配置接口，再执行后续操作。 |
+| `This window state is abnormal` | 目标窗口未创建或已被销毁。 | 操作窗口前检查窗口存在且状态正常。 |
+| `Already closed` / `14800014` | 数据库或 ResultSet 已关闭。 | 重新打开 `RdbStore` 或重新查询获取 `ResultSet`，确保对象未 `close`。 |
+| `Invalid relative path` | 传入相对路径不符合预期。 | 校验相对路径格式、根目录和调用接口要求。 |
+| `Service exception` + `invalid N-API status` | 服务或 N-API 调用状态异常，文档示例指向 motion 接口调用逻辑问题。 | 检查相关接口的参数、调用时序，尤其是 `on` / `off` 配对和状态管理。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+
+## Related Files
+
+- [Fault mode library](./fault-mode-library.md) — covers `ArrayBuffer detached`, `Map constructor`

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/fault-mode-library.md

@@ -0,0 +1,57 @@
+# JSError 故障模式库
+
+本库用于 JS Crash / ArkTS 异常崩溃的三级根因匹配。输入来源是 appevent、errorManager 或 faultlogger 中的 `Reason`、`Error name`、`Error message`、`Error code`、`Stacktrace`、`HybridStack` 等字段。
+
+## 匹配规则
+
+1. 优先用 `Reason` 或 `Error name` 匹配二级根因。
+2. 再用 `Error message` 做三级根因匹配；带 `<name>`、`<string>`、`<size>`、`<heap-type>` 的条目按通配模板匹配。
+3. 如果 `Error message` 只命中二级根因，三级根因输出为“未收录子类”，并继续结合调用栈判断责任代码。
+4. `Stacktrace` / `HybridStack` 用于确认调用来源和责任模块；不能只凭错误类型定界。
+
+## 一级根因
+
+| 一级根因 | 说明 |
+| --- | --- |
+| `JSError` | appevent、errorManager 上报的 ArkTS 异常导致应用异常崩溃。 |
+
+## 二级根因索引
+
+| 二级根因 | 说明 |
+| --- | --- |
+| `ReferenceError` | 引用错误。 |
+| `URIError` | 无效 URL / URI 相关错误。 |
+| `Error` | 自定义 Error 或 builtins 错误。 |
+| `OutOfMemoryError` | ArkTS 虚拟机堆内存不足。 |
+| `TerminationError` | 终止错误，通常由于进程或虚拟机执行被强制终止。 |
+| `AggregateError` | 多个错误对象被包装为一个错误。 |
+
+## 三级根因库
+
+| 一级根因 | 二级根因 | Error message 模式 | 三级根因 | 分析要点 / 修复方向 |
+| --- | --- | --- | --- | --- |
+| `JSError` | `ReferenceError` | `undefinedsub-class must call super before use 'this'` | 子类构造函数中使用 `this` 之前未调用 `super()`。 | 检查继承类构造函数，确保访问 `this` 或实例成员前先调用一次 `super()`。 |
+| `JSError` | `ReferenceError` | `super() forbidden re-bind 'this'` | 子类构造函数中多次调用 `super()`。 | 检查构造函数分支，保证 `super()` 只调用一次，避免条件分支重复调用。 |
+| `JSError` | `ReferenceError` | `<name> is not defined` | 尝试访问未定义变量。 | 根据 `<name>` 和栈顶应用帧检查变量声明、作用域、导入导出、条件编译或初始化时序。 |
+| `JSError` | `URIError` | `DecodeURI: invalid character: <string>` | URI 解码异常。 | 检查传入 `DecodeURI` / URI 解析接口的字符串是否真实有效、编码合法；对外部输入加校验并用 `try-catch` 兜底。 |
+| `JSError` | `Error` | `The underlying ArrayBuffer is null or detached.` | `ArrayBuffer` 被分离或释放后继续使用。 | 检查 ArrayBuffer 生命周期、跨线程/转移后访问、Native/JS 边界对象释放时序；使用前确认 buffer 未 detached。 |
+| `JSError` | `Error` | `The ArkTS Map's constructor cannot be directly invoked.` | 不可直接调用 ArkTS `Map` 构造函数。 | 检查是否以错误方式直接调用构造函数；按 ArkTS 语法使用 `new Map()` 或正确集合初始化方式。 |
+| `JSError` | `OutOfMemoryError` | `OutOfMemory when trying to allocate <size> bytes function name: <name>, <heap-type> oom, total size <size> bytes, used size <size> bytes` | ArkTS 虚拟机堆内存不足，产生 OOM 异常。 | 结合分配函数、申请大小、堆类型和堆栈判断高频分配或泄漏路径；稳定堆栈看具体代码，不稳定堆栈用 Snapshot / heapsnapshot 对比泄漏对象。 |
+| `JSError` | `TerminationError` | `Terminate execution!` | 虚拟机被强制终止执行。 | 通过 faultlogger 中的 `Stacktrace` 或 `HybridStack` 查看调用来源，定位是谁触发终止和终止前的业务状态。 |
+| `JSError` | `AggregateError` | `None` | `PromiseAny()` 中所有 promise 均 reject 时产生 `AggregateError`。 | 此类 Error 通常不会产生 FaultLog 文件；开发者应从 `AggregateError.errors` 取出所有异常并做自定义处理。 |
+
+## 输出要求
+
+命中本库时，在报告的“关键证据链”中补充：
+
+```text
+错误模式匹配：JSError -> <二级根因> -> <Error message 模式>
+三级根因：<三级根因说明>
+```
+
+如果只命中二级根因，输出：
+
+```text
+错误模式匹配：JSError -> <二级根因> -> 未收录子类
+三级根因：需结合 Error message 与栈顶应用帧继续判断
+```

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/outofmemoryerror_patterns.md

@@ -0,0 +1,19 @@
+# OutOfMemoryError Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `OutOfMemory when trying to allocate` | 应用分配内存时超过 Heap 空间上限；手机设备主线程 OldSpaceSize 上限通常接近 350MB。 | 如果 OOM 堆栈稳定，优先分析高频调用和潜在泄漏路径；如果堆栈不稳定，通过 Snapshot 对比操作前后的内存快照定位泄漏对象。 |
+| `AllocateHugeObject` | 尝试分配大对象时超过大对象空间阈值。 | 检查大数组、大字符串、大图片/缓存等一次性分配，拆分或释放不必要对象。 |
+| `AllocateYoungOrHugeObject` | 年轻代或大对象空间分配失败，即使小对象也可能因堆空间耗尽失败。 | 排查生命周期过长对象、列表复用、缓存释放、组件销毁释放和闭包持有。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+
+## Related Files
+
+- [Fault mode library](./fault-mode-library.md) — OOM template with heap type breakdown

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/rangeerror_patterns.md

@@ -0,0 +1,15 @@
+# RangeError Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `Invalid array length` | 数组长度为负数或超长。 | 检查长度计算逻辑，限制数组长度范围。 |
+| `Stack overflow` | 函数递归调用导致栈空间溢出。 | 检查递归终止条件；必要时改写为循环形式。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/referenceerror_patterns.md

@@ -0,0 +1,23 @@
+# ReferenceError Crash Patterns
+
+## Background
+
+- `@Provide` / `@Consume` 用于父组件与后代组件双向数据同步，变量名或别名必须正确匹配。
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `missing @Provide property` / `Fail to resolve @Consume` | 初始化 `@Consume` 变量时，没有定义对应名称的 `@Provide` 变量。 | 检查变量是否存在；若存在，在父组件中定义并赋值对应 `@Provide`。 |
+| `duplicate @Provide property` / `@Provide override not allowed` | 同名 `@Provide` 属性在祖先组件中已存在，不允许重复提供或覆盖。 | 删除重复 `@Provide`，或更改变量名/别名，避免祖先链路冲突。 |
+| `is not initialized` | 变量未初始化即被访问。 | 初始化对应变量，或在使用前增加空值/状态校验。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+
+## Related Files
+
+- [Fault mode library](./fault-mode-library.md) — covers `super()` before `this`, `<name> is not defined`

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/syntaxerror_patterns.md

@@ -0,0 +1,14 @@
+# SyntaxError Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `Unexpected Text in JSON` / `Invalid Token` | 字符串格式不符合 JSON 语法，常在 `JSON.parse` 时触发。 | 解析前检查内容是否为有效 JSON，避免解析非 JSON 数据或包含非法字符的数据。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/typeerror_patterns.md

@@ -0,0 +1,19 @@
+# TypeError Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `Cannot read property` + `undefined/null` / `Cannot load property of null or undefined` | 变量不是预期对象，不能访问目标属性。 | 使用变量前校验对象存在，并检查接口返回、异步时序和默认值。 |
+| `is not callable` | 变量或 `this` 不是预期函数对象，不能调用目标方法。 | 检查方法是否存在、`this` 绑定是否正确、对象类型是否符合预期。 |
+| `Receiver is not a JSObject` | 传入值不是有效 JavaScript 对象。 | 校验传入对象类型和结构，必要时在边界处做严格数据校验。 |
+| `Can not get Prototype on non ECMA Object` | `napi_value` 的使用范围可能超出 `napi_handle_scope` 作用域。 | 检查 N-API handle scope 的打开、关闭和 `napi_value` 生命周期。 |
+| `Cannot convert a illegal value to a Primitive` | 非法值无法转换为原始类型。 | 确保对象正确实现 `valueOf()` 或 `toString()`，且返回有效原始值。 |
+| `stack contains value` / `circular structure` | 对象存在循环引用，常在 `JSON.stringify` 或深拷贝时触发。 | 使用 `WeakSet` 检测并过滤循环引用，或重构数据结构避免环。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+

package/resources/deveco/skills/hmos-runtime-fix-skill/reference/urierror_patterns.md

@@ -0,0 +1,17 @@
+# URIError Crash Patterns
+
+## Pattern Matrix
+
+| Error message keyword | Analysis conclusion | Fix suggestion |
+| --- | --- | --- |
+| `DecodeURI: invalid character` | URL 无效，`DecodeURI` 抛出异常导致闪退。 | 确保 URL 真实有效、编码合法；使用 `try-catch` 捕获并处理异常。 |
+
+## Credibility Rules
+
+- HIGH: `Reason`, complete `Error message`, `Error code` (if any) and top application stack frame all support the same pattern.
+- MEDIUM: Missing error code or stack frame, but `Reason` and `Error message` clearly match a pattern.
+- LOW: Only fragmented log, or needs SourceMap / business code to confirm.
+
+## Related Files
+
+- [Fault mode library](./fault-mode-library.md) — covers `DecodeURI: invalid character: <string>`