@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-xts-code/references/SUBAGENT_PROMPT_TEMPLATE.md

@@ -0,0 +1,276 @@
+# Subagent Prompt 模板
+
+## 使用说明
+
+Orchestrator 将本模板的 `{PLACEHOLDER}` 填充后作为 `general` 类型 subagent 的 prompt。
+模板本身不含任何库特定内容，适用于任意 ArkTS 三方库的 XTS 测试代码分批生成。
+
+> **前置条件**：Orchestrator 已完成 Phase 1（解析报告、预检访问修饰符、生成框架文件），
+> 并将框架文件路径、排除清单、用例描述等注入本模板。
+
+---
+
+## 模板正文
+
+以下为 Orchestrator 填充后发给 subagent 的 prompt 内容。
+`{PLACEHOLDER}` 部分由 Orchestrator 在 dispatch 前替换。
+
+---
+
+你是一个 ArkTS XTS 测试代码生成 subagent。你的任务是为库 `{LIBRARY_NAME}` 生成 `{BATCH_SIZE}` 个测试函数的代码。
+
+你只能输出 `it()` 函数体（含 JSDoc 注释），不要输出 imports、describe、beforeAll、afterAll — 这些已由 orchestrator 在框架文件中预生成。
+
+---
+
+### 步骤 1：系统 API 预检（强制，不可跳过）
+
+在写任何代码之前，你需要通过读库源码（步骤 2）识别本批用例涉及的所有 `@ohos.*` / `@kit.*` 系统 API。
+
+对每个系统 API，执行以下操作：
+
+1. 调用 `script_deveco_docs` 工具：
+   - `action=search`
+   - `keywords` = 系统 API 名称或模块名（如 `"createGattClientDevice"` 或 `"ble GattClientDevice"`）
+   - `catalog` = `"harmonyos-references"`
+   - `limit` = `3`
+   - `documentId` = `""`
+   - `section` = `""`
+2. 从搜索结果取首条命中的 `documentId`
+3. 调用 `script_deveco_docs` 工具：
+   - `action=read`
+   - `documentId` = 步骤 2 获取的值
+   - `section` = 目标接口名或枚举名（精确定位，避免返回全文）
+   - 其余参数填空字符串或默认值
+4. 记录确认：方法签名、参数类型、返回类型、import 路径（`#### 导入模块`小节）、枚举成员名、权限要求
+
+> **若 `script_deveco_docs` 返回"未找到"**：hypium、库自身 API 不在系统语料中，直接按库源码签名编写，不强制查询。
+
+> **若你无法访问 `script_deveco_docs` 工具**：退化为仅按库源码签名编写，并在返回结果中标注 `"API 未预检"`。
+
+**禁止凭训练记忆编写系统 API 调用。必须先查证再写。**
+
+---
+
+### 步骤 2：读库源码
+
+读取以下源文件，确认每个接口的：
+- 精确方法签名（参数名、类型、可选性、返回类型）
+- 访问修饰符（`public` / `private` / `protected`，无修饰符 = `public`）
+- 静态（`static`）还是实例方法
+- 构造函数参数
+- 字段的访问修饰符（`private` 字段禁止直接访问，必须通过 public getter/setter 间接验证）
+
+源文件路径：
+```
+{SOURCE_FILE_PATHS}
+```
+
+> 同时阅读框架文件 `{FRAMEWORK_FILE_PATH}`，了解已预定义的 helper class（callback 子类、exception 子类等），你在代码中直接引用这些类，不要重复定义。
+
+---
+
+### 步骤 3：ArkTS 规则清单（违反任何一条 = 编译失败）
+
+#### 3.1 断言 API（hypium 框架，最高频违反项）
+
+| 场景 | 正确写法 | 错误写法（编译失败） |
+|------|---------|-------------------|
+| 严格相等 | `expect(x).assertEqual(y)` | `toBe`、`toEqual` |
+| null 判断 | `expect(x).assertNull()` | `toBeNull`、`assertNotNull` |
+| 布尔真 | `expect(x).assertTrue()` | `toBeTruthy` |
+| 布尔假 | `expect(x).assertFalse()` | `toBeFalsy` |
+| 大于 | `expect(x).assertLarger(y)` | `toBeGreaterThan` |
+| 小于（反转方向） | `expect(y).assertLarger(x)` | `toBeLessThan` |
+| 包含 | `expect(x).assertContain(y)` | `toContain` |
+| undefined | `expect(x).assertUndefined()` | — |
+| 非 null | `expect(x !== null).assertTrue()` | `not.toBeNull` |
+| 不等于 | `expect(x === y).assertFalse()` | `not.toBe` |
+| 抛异常 | `try-catch` + 布尔标记（见 3.4） | `toThrow` |
+
+> ⚠️ `expect()` 对象上**不存在** Jest 风格方法。`assertNotNull` **不存在**于 hypium。
+
+> ⚠️ **断言必须链式调用，禁止裸函数调用**。hypium 断言方法只存在于 `expect()` 返回的对象上，**不存在独立全局函数**。裸调用 `assertTrue(x)` / `assertEqual(a, b)` 会产生批量编译错误（`Cannot find name 'assertTrue'`）：
+>
+> ```typescript
+> // ✅ 正确（唯一合法形式）
+> expect(result).assertEqual(5);
+> expect(caught).assertTrue();
+>
+> // ❌ 错误（编译失败：Cannot find name 'assertTrue'）
+> // assertEqual(result, 5);
+> // assertTrue(caught);
+> ```
+
+#### 3.2 类型禁止
+
+| 禁止 | 原因 | 替代方案 |
+|------|------|---------|
+| `any` | `arkts-no-any` | 具体类型或泛型 `T` |
+| `Object` | `arkts-no-esobj` | 定义 `interface` 或使用具体类型 |
+| `unknown` | `arkts-no-any-unknown` | 禁止（含 `as unknown as T` 双重转换） |
+| `ESObject` 作为变量声明类型 | `arkts-limited-esobj` | 仅用于 `null as ESObject as SomeType` 转型场景 |
+
+#### 3.3 对象字面量禁止
+
+```typescript
+// ❌ 禁止：无类型对象字面量（arkts-no-untyped-obj-literals）
+let x: SomeType = { key: value } as SomeType;
+
+// ✅ 正确：用构造函数或系统 API 创建对象
+let x: SomeType = new SomeClass(args);
+let x: SomeSystemType = someSystemApi.createXxx(args);
+```
+
+#### 3.4 异常处理
+
+```typescript
+// ❌ 禁止：catch 中 throw e（arkts-limited-throw）
+try { ... } catch (e) { throw e; }
+
+// ❌ 禁止：catch 带类型注解（arkts-no-types-in-catch）
+try { ... } catch (e: Error) { ... }
+
+// ✅ 正确：try-catch + 布尔标记
+let caught: boolean = false;
+try {
+  someCall();
+} catch (e) {           // 无类型注解
+  caught = true;
+}
+expect(caught).assertTrue();
+```
+
+#### 3.5 测试函数格式
+
+```typescript
+// ✅ 必须：三参数 it()，省略 filter（第二个参数 0）会导致部分设备崩溃
+it('function_snake_case_001', 0, () => {
+  hilog.info(DOMAIN, TAG, 'Test 001 started');
+  // ... 测试逻辑 ...
+  hilog.info(DOMAIN, TAG, 'Test 001 passed');
+});
+```
+
+#### 3.6 其他
+
+- `hilog` 导入：`import { hilog } from '@kit.PerformanceAnalysisKit'`（禁止 `@ohos.hilog`）
+- 文件扩展名：`.test.ets`（禁止 `.ts` 或 `.ets`）
+- 返回类型含 `| undefined` 或 `| null` 时：访问属性前必须 `if (result)` 判空
+- 枚举成员直接 `===` 比较会报 `types have no overlap`：用 `(Enum.A as number) !== (Enum.B as number)` 转型后比较
+- `null as SomeType` 强转会报类型不兼容：改用系统 API 创建对象，或 `null as ESObject as SomeType`
+- **禁止向库 API 传 `null` 实参**：即使库源码有 `@ts-nocheck`，测试文件调用处仍受严格空值检查约束（`Argument of type 'null' is not assignable to parameter of type 'string'`）。库内部用 `if (x)` 判空时，空串 `''` / 空数组 `[]` 与 null 语义等价 → 改传等价 falsy 值覆盖同一守卫路径，并在注释中说明等价性依据
+
+---
+
+### Access Modifier 排除清单
+
+以下成员为 `private` 或 `protected`，**禁止直接访问**，**跳过这些成员、不生成用例**。
+
+排除清单：
+```
+{ACCESS_MODIFIER_EXCLUSION_LIST}
+```
+
+> Orchestrator 补充说明（从源码额外发现的 private 成员）：
+> {ADDITIONAL_PRIVATE_MEMBERS}
+
+---
+
+### 本批用例
+
+```
+{TEST_CASE_DESCRIPTIONS}
+```
+
+每个用例包含：
+- 序号（三位数字，如 `001`）
+- 用例名称
+- 涉及接口及签名（从 XTS 报告提取）
+- 预期结果（用于设计 `expect` 断言）
+- 源码路径（如未在步骤 2 中列出，需额外 `read`）
+
+---
+
+### 输出要求
+
+1. **输出文件**：`{OUTPUT_FILE_PATH}`
+   > ⚠️ 该路径由 orchestrator 指定，位于工作目录内（`{outputDir}/.xts-batches/`）。
+   > **禁止将文件写到工作目录之外的路径**（如系统 temp 目录），否则人工审核无法追溯写权限。
+2. **仅输出 `it()` 函数体**（含 JSDoc 注释），不要输出以下内容（已在框架文件中预生成）：
+   - `import` 语句
+   - `describe()` 块
+   - `beforeAll` / `afterAll` / `beforeEach` / `afterEach`
+   - 日志常量 `DOMAIN` / `TAG` 定义
+   - helper class 定义（callback 子类、exception 子类等）
+3. **测试函数命名**：`{英文功能描述_snake_case}_{序号}`
+   - 英文功能描述：小写字母+下划线，≤20 字符，体现核心功能；多接口用例可合并描述
+   - 序号：三位数字，与本批用例描述中的用例序号对应
+   - 示例：`chunk_basic_001`、`get_set_path_007`
+4. 每个 `it()` 函数前必须有 JSDoc 注释：
+   ```typescript
+   /**
+    * 用例 {SEQ}: {用例名称}
+    *
+    * 涉及接口：{接口签名列表}
+    * 预期结果：
+    *   1. {预期结果 1}
+    *   2. {预期结果 2}
+    */
+   ```
+5. 每个函数开头和结尾有 `hilog.info` 日志
+6. `DOMAIN = {DOMAIN}`，`TAG = '{TAG}'`
+7. 需要的 helper class 已在框架文件中预定义，直接使用类名引用
+
+---
+
+### 自检清单（写完后必须逐项检查并自行修复）
+
+完成代码后，逐项检查以下内容。发现违反则自行修复后再返回。
+
+- [ ] 是否有 `assertNotNull` / `toBe` / `toEqual` / `toThrow` / `toBeNull` / `toBeTruthy` 等 Jest 风格方法？
+  → 替换为 hypium API（见 3.1 表格）
+- [ ] 断言是否全部为 `expect(x).assertXxx()` 链式调用？
+  → 裸调用 `assertTrue(x)` / `assertEqual(a, b)` 是编译错误（Cannot find name），必须改为链式
+- [ ] 是否向库 API 传了 `null` 实参？
+  → 库内部 `if (x)` 判空时空串/空数组与 null 等价，改传等价 falsy 值并注释等价依据
+- [ ] 是否有 `any` / `Object` / `unknown` 类型声明？
+  → 替换为具体类型
+- [ ] 是否有 `{ ... } as Type` 无类型对象字面量？
+  → 替换为 `new Class()` 或系统 API 创建
+- [ ] 是否有 `catch(e) { throw e }` 或 `catch(e: Type)`？
+  → 改为 `catch (e)` 无注解 + 布尔标记，不 throw
+- [ ] `it()` 是否三参数格式 `it('name', 0, () => {})` ？
+  → 补 `0`
+- [ ] 排除清单中的 private/protected 成员是否被直接访问了？
+  → 删除对它们的访问，跳过相关用例
+- [ ] 返回类型含 `| undefined` / `| null` 的接口，属性访问前是否判空？
+  → 添加 `if (result) { ... }` 守卫
+- [ ] 是否有 `null as SomeType` 直接强转？
+  → 改为系统 API 创建 或 `null as ESObject as SomeType`
+
+---
+
+### 返回格式
+
+完成自检后，返回以下信息：
+
+```
+输出文件：{OUTPUT_FILE_PATH}
+本批用例数：{N}
+自检结果：
+  [✓/✗] 无 Jest 风格断言方法
+  [✓/✗] 断言全部链式调用（无裸 assertTrue/assertEqual）
+  [✓/✗] 无 null 实参直传库 API
+  [✓/✗] 无 any/Object/unknown 类型
+  [✓/✗] 无无类型对象字面量
+  [✓/✗] 无 catch throw / catch 类型注解
+  [✓/✗] it() 三参数格式
+  [✓/✗] private 成员已跳过（未生成用例）
+  [✓/✗] undefined/null 返回值守卫
+  [✓/✗] 无 null as Type 直接强转
+系统 API 预检：
+  查询 API 数：{M}
+  查询结果摘要：{简述查了哪些 API，关键签名确认}
+  未预检 API（如有）：{列表}
+```

package/vendor/Server/Skills/arkts-library-xts-code/references/SYSTEM_API_LOOKUP.md

@@ -0,0 +1,93 @@
+# 系统 API 检索指南（SYSTEM_API_LOOKUP）
+
+> 编写 XTS 测试代码时，查证 HarmonyOS 系统 API（`@kit.*` / `@ohos.*` / `@hms.*`）的权威途径。
+> 通过 MCP 工具 `script_deveco_docs` 调用，语料为 HarmonyOS 官方 API 参考文档（本地离线）。
+
+---
+
+## 1. 检索工具 `script_deveco_docs`
+
+> 由 MCP Gateway 的 `MCP/scripts/deveco_docs.js` 脚本提供，封装 `devecocli docs`，**内置降噪排序与小节精确定位**。opencode 通过 MCP 协议自动发现并主动调用，无需手动执行 shell 命令。
+
+### 1.1 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `action` | string | 是 | `search`（检索）\| `read`（读取文档） |
+| `keywords` | string | search 必填 | 检索关键词，多个用空格分隔（如 `"ImageFit"`、`"AudioRenderer createAudioRenderer"`） |
+| `catalog` | string | 否 | 文档类别，默认 `harmonyos-references`（API 参考） |
+| `limit` | number | 否 | 返回条数上限，默认 10 |
+| `documentId` | string | read 必填 | 文档 ID（来自 search 结果的 `documentId` 字段） |
+| `section` | string | read 可选 | 按小节名精确定位（如 `ImageFit`），返回该小节而非全文 |
+
+### 1.2 调用示例
+
+> 工具实际名称以 MCP 工具列表为准（opencode 中可能带 server 前缀，实际为 `mcp-gateway_script_deveco_docs`）。下述以无前缀名 `script_deveco_docs` 说明。
+
+```
+工具: script_deveco_docs
+参数: { "action": "search", "keywords": "ImageFit", "catalog": "harmonyos-references", "limit": 8 }
+
+工具: script_deveco_docs
+参数: { "action": "read", "documentId": "API参考/.../ts-appendix-enums", "section": "ImageFit" }
+```
+
+### 1.3 返回结构
+
+**search** 返回 `{ tool, action, query, total, results: [{ title, documentId, sectionTitle, snippet }] }`，结果已按标题相关性从高到低排序（命中 title > 命中 sectionTitle > 内容匹配）。
+
+**read** 返回 `{ tool, action, documentId, section, contentLength, content }`；提供 `section` 时 `content` 仅含该小节（如单个枚举定义），否则为全文（截断保护 20000 字符）。
+
+### 1.4 环境依赖
+
+- `devecocli` 需已全局安装（`npm install -g @deveco/deveco-cli`）
+- 脚本自动定位 `@deveco/deveco-cli/dist/cli.js` 并用 node 直接运行，规避 Windows 下 `.cmd` 的中文编码问题（documentId 含中文时也可正常 read）
+- 可用 `DEVECO_CLI_PATH` 环境变量显式指定 cli.js 路径
+- 若 MCP Gateway 已启动（`hotReload: true`），脚本放入 `MCP/scripts/` 后自动注册，无需重启
+
+---
+
+## 2. 常用系统 API 速查
+
+XTS 测试代码中高频出现的系统 API 依赖及其典型 import 路径（以 `script_deveco_docs` 检索结果为准，下表为常见形态）：
+
+| 系统 API | 典型 import | 用途 | 检索关键词 |
+|---------|------------|------|-----------|
+| `hilog` | `import { hilog } from '@kit.PerformanceAnalysisKit'` | 日志输出 | `hilog` |
+| `abilityDelegatorRegistry` | `import { abilityDelegatorRegistry } from '@kit.TestKit'` | 获取测试上下文 | `abilityDelegatorRegistry` |
+| `common.UIAbilityContext` | `import { common } from '@kit.AbilityKit'` | 应用上下文 | `UIAbilityContext` |
+| `common.Context` | `import { common } from '@kit.AbilityKit'` | 通用上下文 | `common Context` |
+| `ImageFit` | ArkUI 组件属性枚举 | 图片填充效果 | `ImageFit` |
+| `hypium`（describe/it/expect） | `import { describe, it, expect } from '@ohos/hypium'` | 测试框架 | **不在系统语料，不检索** |
+
+> ⚠️ **检索边界**：`hypium`/`@ohos.hypium`（测试框架）与**被测试库自身 API** 不在 HarmonyOS 系统 API 语料中，`script_deveco_docs` 会返回"未找到相关文档"。这类 API 直接按接口规格文档/库源码编写，不要检索。
+
+---
+
+## 3. 降噪策略
+
+`devecocli docs search` 原生返回含噪声（如搜 `ImageFit` 会命中 `ImageParticleParameters`、`RichEditorImageSpanStyleResult` 等含 "Image" 的无关文档）。`script_deveco_docs` 已内置以下降噪手段：
+
+1. **相关性排序**：命中结果 `title` 的排在 `sectionTitle` 命中之前，多关键词全命中优先
+2. **取第一条**：排序后第一条通常即目标；若首条 `title`/`sectionTitle` 与目标不符，逐条检查 `sectionTitle` 匹配项
+3. **`--catalog harmonyos-references`**：限定在 API 参考语料内检索（默认），排除 FAQ/指南/最佳实践等非签名文档
+4. **多关键词组合**：用"模块名 + 接口名"（如 `AudioRenderer createAudioRenderer`）可显著提升精确度
+
+---
+
+## 4. 大文档精确定位
+
+- 聚合文档（`Enums`、`Types`、`公共定义` 等）可达数十 KB（如 `ts-appendix-enums` 47 KB）
+- **read 必须带 `section=<目标名>`**：脚本会从文档中定位 `#### <section>` 小节并只返回该小节（如 `ImageFit` 枚举定义约 2 KB），避免浪费 token
+- 若 `section` 未命中（返回 `section: null`），再考虑全文读取或换关键词
+
+---
+
+## 5. 常见问题
+
+| 问题 | 原因 | 处理 |
+|------|------|------|
+| `search` 返回空 | API 不是系统 API（hypium、库自身 API）、或关键词不准确 | 按接口规格文档/库源码编写，不检索 |
+| `read` 提示 Document not found | documentId 被截断或路径不完整 | 从最新 `search` 结果的 `documentId` 完整复制 |
+| `search` 结果第一条不相关 | 关键词过泛 | 用"模块名 + 接口名"多关键词重试 |
+| 工具不可用（tools 列表无 `script_deveco_docs`） | MCP Gateway 未重启 | 重启 opencode / 检查 `MCP/scripts/` 脚本存在且带 `@tool` 注释 |