android2harmony 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import path4 from "node:path";
+import path10 from "node:path";
 
 // src/paths.ts
 import path from "node:path";
@@ -70,11 +70,609 @@ async function buildA2HEnvBase(deps) {
   return env;
 }
 
+// src/tools/a2h-app-feature-verify.ts
+import { spawn } from "node:child_process";
+import path4 from "node:path";
+var SCRIPT_PATH = path4.join(
+  PKG_ROOT,
+  "skills",
+  "hmos-incremental-ui-align",
+  "scripts",
+  "app_feature_verify.ts"
+);
+var SECRET_ENV = [
+  "HOMETRANS_MODEL_API_KEY",
+  "HOMETRANS_MODEL_NAME",
+  "HOMETRANS_MODEL_BASE_URL",
+  "GLM_API_KEY",
+  "TEST_API_KEY"
+];
+function cap(s, max = 5e4) {
+  if (s.length <= max) return s;
+  const half = Math.floor(max / 2);
+  return s.slice(0, half) + `
+\u2026[truncated ${s.length - max} chars]\u2026
+` + s.slice(-half);
+}
+function makeA2hAppFeatureVerifyTool(deps) {
+  return {
+    description: "Run the a2h UI feature-verification phone agent (app_feature_verify.ts) to navigate an app and verify a feature path on a connected device. The multimodal model apiKey is resolved from the host and piped to the script over stdin \u2014 it is never placed in env or argv, so it is not visible to the spawned adb/hdc subprocesses. Use this instead of running `node app_feature_verify.ts` directly. The script runs its internal agent loop (screenshot \u2192 model \u2192 action) up to maxSteps and prints per-step thinking + actions; the full stdout is returned on success. One of task/prompt/feature is required; app and package are required.",
+    args: {
+      type: "object",
+      properties: {
+        app: { type: "string", description: "\u76EE\u6807 app \u663E\u793A\u540D\uFF08required\uFF09" },
+        package: { type: "string", description: "\u76EE\u6807 app \u5305\u540D\uFF08required\uFF09" },
+        device: {
+          type: "string",
+          enum: ["hdc", "adb"],
+          default: "hdc",
+          description: "\u8BBE\u5907\u9A71\u52A8\uFF1Ahdc(HarmonyOS) / adb(Android)"
+        },
+        task: {
+          type: "string",
+          description: "L1/L2/L3 \u4EFB\u52A1\u8DEF\u5F84\uFF0C\u5982 L1\u76F8\u518C\u8BE6\u60C5L2\u66F4\u591A\uFF08\u4E0E prompt/feature \u4E09\u9009\u4E00\uFF09"
+        },
+        prompt: { type: "string", description: "\u81EA\u7531 prompt\uFF08\u4E0E task/feature \u4E09\u9009\u4E00\uFF09" },
+        feature: { type: "string", description: ".md \u529F\u80FD\u6E05\u5355\u8DEF\u5F84\uFF08\u4E0E task/prompt \u4E09\u9009\u4E00\uFF09" },
+        maxSteps: { type: "number", default: 30, description: "\u6700\u5927 agent \u6B65\u6570" },
+        appHints: { type: "string", description: "\u5E94\u7528\u5BFC\u822A\u63D0\u793A" },
+        serial: { type: "string", description: "\u8BBE\u5907\u5E8F\u5217\u53F7" },
+        limit: { type: "number", description: "--feature \u6A21\u5F0F\u4E0B\u53D6\u524D N \u6761" },
+        offset: { type: "number", default: 1, description: "--feature \u6A21\u5F0F\u4E0B\u504F\u79FB" },
+        quiet: { type: "boolean", default: false, description: "\u6291\u5236\u63D0\u793A\u6027\u8F93\u51FA" }
+      },
+      required: ["app", "package"]
+    },
+    execute: async (args, context) => {
+      const app = String(args.app ?? "");
+      const pkg = String(args.package ?? "");
+      if (!app || !pkg) {
+        throw new Error("a2h_app_feature_verify: `app` and `package` are required");
+      }
+      const task = args.task != null ? String(args.task) : null;
+      const prompt = args.prompt != null ? String(args.prompt) : null;
+      const feature = args.feature != null ? String(args.feature) : null;
+      if (!task && !prompt && !feature) {
+        throw new Error("a2h_app_feature_verify: one of `task` / `prompt` / `feature` is required");
+      }
+      const model = await deps.resolveModelParams(context.worktree);
+      if (!model || !model.apiKey) {
+        throw new Error("a2h_app_feature_verify: host did not provide model params (apiKey missing)");
+      }
+      const argv = ["--app", app, "--package", pkg, "--device", String(args.device ?? "hdc")];
+      if (task) argv.push("--task", task);
+      if (prompt) argv.push("--prompt", prompt);
+      if (feature) argv.push("--feature", feature);
+      if (args.maxSteps != null) argv.push("--max-steps", String(args.maxSteps));
+      if (args.appHints != null) argv.push("--app-hints", String(args.appHints));
+      if (args.serial != null) argv.push("--serial", String(args.serial));
+      if (args.limit != null) argv.push("--limit", String(args.limit));
+      if (args.offset != null) argv.push("--offset", String(args.offset));
+      if (args.quiet === true) argv.push("--quiet");
+      argv.push("--model-stdin");
+      const env = { ...process.env };
+      for (const k of SECRET_ENV) delete env[k];
+      const child = spawn("node", [SCRIPT_PATH, ...argv], {
+        cwd: context.directory,
+        env,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      child.stdin.end(
+        JSON.stringify({ apiKey: model.apiKey, modelName: model.modelName, baseURL: model.baseURL })
+      );
+      let stdout = "";
+      let stderr = "";
+      let spawnError = "";
+      const stepRe = /执行动作:\s*(.*)/g;
+      child.stdout.on("data", (chunk) => {
+        const text = chunk.toString("utf8");
+        stdout += text;
+        const matches = [...text.matchAll(stepRe)];
+        if (matches.length) {
+          const last = matches[matches.length - 1][1].trim();
+          try {
+            context.metadata({ title: `UI verify: ${last.slice(0, 80)}` });
+          } catch {
+          }
+        }
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+      });
+      const onAbort = () => {
+        if (!child.killed) child.kill("SIGTERM");
+      };
+      context.abort.addEventListener("abort", onAbort);
+      const code = await new Promise((resolve) => {
+        child.on("close", resolve);
+        child.on("error", (err) => {
+          spawnError = err.message;
+          resolve(-1);
+        });
+      });
+      context.abort.removeEventListener("abort", onAbort);
+      if (code !== 0) {
+        if (spawnError) {
+          throw new Error(`a2h_app_feature_verify: failed to spawn node \u2014 ${spawnError}`);
+        }
+        const tail = stderr.slice(-2e3);
+        throw new Error(`a2h_app_feature_verify failed (exit ${code}): ${tail || "(no stderr)"}`);
+      }
+      return { ok: true, exitCode: code, output: cap(stdout) };
+    }
+  };
+}
+
+// src/tools/a2h-autotest-resolve-metadata.ts
+import path6 from "node:path";
+
+// src/tools/autotest-shared.ts
+import { spawn as spawn2 } from "node:child_process";
+import path5 from "node:path";
+var AUTOTEST_ROOT = path5.join(PKG_ROOT, "tools", "autotest");
+var SECRET_ENV2 = [
+  "HOMETRANS_MODEL_API_KEY",
+  "HOMETRANS_MODEL_NAME",
+  "HOMETRANS_MODEL_BASE_URL",
+  "GLM_API_KEY",
+  "TEST_API_KEY"
+];
+function cap2(s, max = 5e4) {
+  if (s.length <= max) return s;
+  const half = Math.floor(max / 2);
+  return s.slice(0, half) + `
+\u2026[truncated ${s.length - max} chars]\u2026
+` + s.slice(-half);
+}
+function runAutotestScript(opts) {
+  return new Promise((resolve) => {
+    const scriptPath = path5.join(AUTOTEST_ROOT, opts.scriptRel);
+    const env = { ...process.env };
+    for (const k of SECRET_ENV2) delete env[k];
+    const child = spawn2("node", [scriptPath, ...opts.argv], {
+      cwd: opts.cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let spawnError = "";
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString("utf8");
+      stdout += text;
+      opts.onStdoutChunk?.(text);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.stdin.end(opts.stdin ?? "");
+    const onAbort = () => {
+      if (!child.killed) child.kill("SIGTERM");
+    };
+    opts.abort.addEventListener("abort", onAbort);
+    child.on("close", (code) => {
+      opts.abort.removeEventListener("abort", onAbort);
+      resolve({ ok: code === 0, exitCode: code ?? -1, stdout: cap2(stdout), stderr, spawnError });
+    });
+    child.on("error", (err) => {
+      opts.abort.removeEventListener("abort", onAbort);
+      spawnError = err.message;
+      resolve({ ok: false, exitCode: -1, stdout: cap2(stdout), stderr, spawnError });
+    });
+  });
+}
+function autotestToolError(toolId, r) {
+  if (r.spawnError) return new Error(`${toolId}: failed to spawn node \u2014 ${r.spawnError}`);
+  const tail = r.stderr.slice(-2e3);
+  return new Error(`${toolId} failed (exit ${r.exitCode}): ${tail || "(no stderr)"}`);
+}
+
+// src/tools/a2h-autotest-resolve-metadata.ts
+var SCRIPT_REL = path6.join("resolve-metadata-tool.ts");
+var TOOL_ID = "a2h_autotest_resolve_metadata";
+function makeA2hAutotestResolveMetadataTool(_deps) {
+  return {
+    description: "Resolve bundle_name / app_name from a HarmonyOS project (reads AppScope/app.json5 and resolves $string refs) and writes app-metadata.json. Pure metadata extraction \u2014 no model, no device. Use this instead of running `node resolve-metadata-tool.ts` directly. Returns the written metadata JSON path + stdout on success.",
+    args: {
+      type: "object",
+      properties: {
+        projectDir: {
+          type: "string",
+          description: "HarmonyOS \u5DE5\u7A0B\u6839\u76EE\u5F55\uFF08\u542B AppScope/app.json5\uFF09"
+        },
+        output: {
+          type: "string",
+          description: "app-metadata.json \u8F93\u51FA\u8DEF\u5F84"
+        }
+      },
+      required: ["projectDir", "output"]
+    },
+    execute: async (args, context) => {
+      const projectDir = String(args.projectDir ?? "");
+      const output = String(args.output ?? "");
+      if (!projectDir || !output) {
+        throw new Error(`${TOOL_ID}: \`projectDir\` and \`output\` are required`);
+      }
+      const argv = ["--project-dir", projectDir, "--output", output];
+      const r = await runAutotestScript({
+        scriptRel: SCRIPT_REL,
+        argv,
+        cwd: context.directory,
+        abort: context.abort
+      });
+      if (!r.ok) throw autotestToolError(TOOL_ID, r);
+      return { ok: true, exitCode: r.exitCode, output: r.stdout };
+    }
+  };
+}
+
+// src/tools/a2h-autotest-testcases.ts
+import path7 from "node:path";
+var SCRIPT_REL2 = path7.join("engine", "testcases-tool.ts");
+var TOOL_ID2 = "a2h_autotest_testcases";
+function makeA2hAutotestTestcasesTool(_deps) {
+  return {
+    description: "HarmonyOS self-test testcases.json engine \u2014 grouped by noun, dispatched on `action`. `generate`: build a schema-compliant testcases.json from extractor output ({ bundle_name, app_name, cases:[{case_name,actions,expected_results}] }); pass `validate` to validate in place. `validate`: check an existing testcases.json against the schema. No model, no device. Non-zero exit is a failure (thrown). Use this instead of running `node testcases-tool.ts` directly.",
+    args: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["generate", "validate"],
+          description: "generate=\u4ECE\u62BD\u53D6\u8F93\u51FA\u5EFA testcases.json\uFF1Bvalidate=\u6821\u9A8C\u5DF2\u6709 testcases.json"
+        },
+        input: { type: "string", description: "[generate] \u62BD\u53D6\u8F93\u51FA JSON \u8DEF\u5F84" },
+        output: { type: "string", description: "[generate] testcases.json \u8F93\u51FA\u8DEF\u5F84" },
+        validate: { type: "boolean", default: false, description: "[generate] \u5199\u5B8C\u540E\u5C31\u5730\u6821\u9A8C" },
+        path: { type: "string", description: "[validate] \u8981\u6821\u9A8C\u7684 testcases.json \u8DEF\u5F84" }
+      },
+      required: ["action"]
+    },
+    execute: async (args, context) => {
+      const action = String(args.action ?? "");
+      if (action === "generate") {
+        const input = String(args.input ?? "");
+        const output = String(args.output ?? "");
+        if (!input || !output) {
+          throw new Error(`${TOOL_ID2}: \`action:"generate"\` requires \`input\` and \`output\``);
+        }
+        const argv = ["generate", input, output];
+        if (args.validate === true) argv.push("--validate");
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL2,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (!r.ok) throw autotestToolError(TOOL_ID2, r);
+        return { ok: true, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "validate") {
+        const p = String(args.path ?? "");
+        if (!p) {
+          throw new Error(`${TOOL_ID2}: \`action:"validate"\` requires \`path\``);
+        }
+        const argv = ["validate", p];
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL2,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (!r.ok) throw autotestToolError(TOOL_ID2, r);
+        return { ok: true, exitCode: r.exitCode, output: r.stdout };
+      }
+      throw new Error(`${TOOL_ID2}: unknown \`action\` "${action}" (expected generate|validate)`);
+    }
+  };
+}
+
+// src/tools/a2h-autotest-report.ts
+import path8 from "node:path";
+var SCRIPT_REL3 = path8.join("engine", "report-tool.ts");
+var TOOL_ID3 = "a2h_autotest_report";
+function makeA2hAutotestReportTool(_deps) {
+  return {
+    description: "HarmonyOS self-test report engine \u2014 grouped by noun, dispatched on `action`. `generate`: render self-test-report.md from a task_<ts>/ directory (summary.json + task_results.jsonl + per-case judgment logs): overview, pre-cases, regular-cases, summary table, suggestions; pass `validate` to validate in place. `validate`: check an existing report.md's layout. No model, no device. Non-zero exit is a failure (thrown). Use this instead of running `node report-tool.ts` directly.",
+    args: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["generate", "validate"],
+          description: "generate=\u4ECE task \u76EE\u5F55\u6E32\u67D3 self-test-report.md\uFF1Bvalidate=\u6821\u9A8C\u5DF2\u6709 report.md \u5E03\u5C40"
+        },
+        taskSubdir: { type: "string", description: "[generate] task_<ts>/ \u76EE\u5F55\u8DEF\u5F84" },
+        appMetadata: { type: "string", description: "[generate] app-metadata.json \u8DEF\u5F84" },
+        hap: { type: "string", description: "[generate] HAP \u6587\u4EF6\u8DEF\u5F84" },
+        device: { type: "string", description: "[generate] \u8BBE\u5907\u6807\u8BC6\uFF08\u5982 127.0.0.1:5555\uFF09" },
+        suite: { type: "string", description: "[generate] \u6D4B\u8BD5\u5957\u4EF6\u6807\u9898" },
+        out: { type: "string", description: "[generate] self-test-report.md \u8F93\u51FA\u8DEF\u5F84" },
+        validate: { type: "boolean", default: false, description: "[generate] \u5199\u5B8C\u540E\u5C31\u5730\u6821\u9A8C" },
+        path: { type: "string", description: "[validate] \u8981\u6821\u9A8C\u7684 report.md \u8DEF\u5F84" }
+      },
+      required: ["action"]
+    },
+    execute: async (args, context) => {
+      const action = String(args.action ?? "");
+      if (action === "generate") {
+        const taskSubdir = String(args.taskSubdir ?? "");
+        const appMetadata = String(args.appMetadata ?? "");
+        const hap = String(args.hap ?? "");
+        const device = String(args.device ?? "");
+        const suite = String(args.suite ?? "");
+        const out = String(args.out ?? "");
+        if (!taskSubdir || !appMetadata || !hap || !device || !suite || !out) {
+          throw new Error(
+            `${TOOL_ID3}: \`action:"generate"\` requires \`taskSubdir\`, \`appMetadata\`, \`hap\`, \`device\`, \`suite\`, \`out\``
+          );
+        }
+        const argv = [
+          "generate",
+          "--task-subdir",
+          taskSubdir,
+          "--app-metadata",
+          appMetadata,
+          "--hap",
+          hap,
+          "--device",
+          device,
+          "--suite",
+          suite,
+          "--out",
+          out
+        ];
+        if (args.validate === true) argv.push("--validate");
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL3,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (!r.ok) throw autotestToolError(TOOL_ID3, r);
+        return { ok: true, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "validate") {
+        const p = String(args.path ?? "");
+        if (!p) {
+          throw new Error(`${TOOL_ID3}: \`action:"validate"\` requires \`path\``);
+        }
+        const argv = ["validate", p];
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL3,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (!r.ok) throw autotestToolError(TOOL_ID3, r);
+        return { ok: true, exitCode: r.exitCode, output: r.stdout };
+      }
+      throw new Error(`${TOOL_ID3}: unknown \`action\` "${action}" (expected generate|validate)`);
+    }
+  };
+}
+
+// src/tools/a2h-autotest-selftest.ts
+import { spawn as spawn3 } from "node:child_process";
+import path9 from "node:path";
+var SCRIPT_REL4 = path9.join("engine", "self-test-runner.ts");
+var TOOL_ID4 = "a2h_autotest_selftest";
+function makeA2hAutotestSelftestTool(deps) {
+  return {
+    description: "HarmonyOS on-device self-test engine \u2014 grouped by noun, dispatched on `action`. `run`: hdc uninstall+install of HAP, then a detached @autotest/agent batch (multimodal model resolved by the host, piped via stdin; never env/argv/disk). Without `timeout` returns RUNNING immediately (exit 2); with `timeout` blocks until terminal (0 COMPLETED / 1 FAILED / 3 CRASHED / 4 NOT_STARTED / 5 TIMEOUT). `status`: probe on-disk state (0/2/3/4). `kill`: tear down the batch tree. `check_hap`/`check_inputs`/`check_pre`: pre-flight validators (0 = passed). Exit codes are states, not errors \u2014 branch on `status` in the returned JSON. Only `run` needs a model. Use this instead of running `node self-test-runner.ts` directly.",
+    args: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["run", "status", "kill", "check_hap", "check_inputs", "check_pre"],
+          description: "run=\u88C5 HAP + \u8DD1 batch\uFF08\u9700\u6A21\u578B\uFF09\uFF1Bstatus=\u63A2\u72B6\u6001\uFF1Bkill=\u7EC8\u6B62 batch\uFF1Bcheck_hap=\u6821\u9A8C hap_path\uFF1Bcheck_inputs=\u6821\u9A8C testcases+metadata\uFF1Bcheck_pre=\u6821\u9A8C [PRE] \u8FDE\u7EED"
+        },
+        // ── run ──
+        testcases: { type: "string", description: "[run/check_inputs/check_pre] \u6D4B\u8BD5\u7528\u4F8B\u6587\u4EF6\uFF08JSON \u6570\u7EC4\u6216 JSONL\uFF09" },
+        hap: { type: "string", description: "[run/check_hap] \u7B7E\u540D\u5305\uFF08.hap/.hsp \u6587\u4EF6\u3001\u76EE\u5F55\uFF0C\u6216\u9017\u53F7\u5206\u9694\u591A\u9879\uFF09" },
+        bundleName: { type: "string", description: "[run] \u5305\u540D\uFF08bundle_name\uFF09" },
+        taskDir: {
+          type: "string",
+          description: "[run/status/kill] \u4EFB\u52A1\u76EE\u5F55\uFF08run \u5185\u90E8\u5EFA task_<ts> \u5B50\u76EE\u5F55\uFF1B\u4E0D\u4F20\u5219\u9ED8\u8BA4 'task'\uFF09\u3002status/kill \u636E\u6B64\u627E batch.pid"
+        },
+        outputDir: { type: "string", description: "[run/status] \u65E5\u5FD7\u76EE\u5F55\uFF08\u4E0D\u4F20\u5219\u540C taskDir\uFF09" },
+        category: { type: "string", description: "[run] \u6D4B\u8BD5\u5206\u7C7B\u540D\uFF0C\u4F20\u7ED9 batch-launcher" },
+        timeout: {
+          type: ["number", "string"],
+          description: '[run] \u963B\u585E\u81F3\u7EC8\u6001\u6216\u8D85\u65F6\u3002\u6570\u503C=\u79D2\u6570\uFF1B"auto"=\u5F15\u64CE\u89E3\u6790 testcases \u540E\u6309\u7528\u4F8B\u6570\xD7720s \u81EA\u52A8\u63A8\u5BFC\uFF08\u6BCF\u4F8B 10min + 20% \u4F59\u91CF\uFF09\u3002\u4E0D\u4F20\u5219\u7ACB\u5373\u8FD4\u56DE RUNNING\uFF1B\u8D85\u65F6\u540E\u81EA\u52A8 kill batch \u5E76\u8FD4\u56DE TIMEOUT\uFF08exit 5\uFF09'
+        },
+        deviceSn: { type: "string", description: "[run] \u8BBE\u5907\u5E8F\u5217\u53F7\uFF08\u2192 AutoTestAgent.deviceSn\uFF09" },
+        ip: { type: "string", description: "[run] \u8BBE\u5907 IP\uFF08\u2192 AutoTestAgent.ip\uFF09" },
+        port: { type: "string", description: "[run] \u8BBE\u5907\u7AEF\u53E3\uFF08\u2192 AutoTestAgent.port\uFF09" },
+        agentMode: { type: "string", description: "[run] agent \u6A21\u5F0F\uFF08\u9ED8\u8BA4 single\uFF09" },
+        maxSteps: { type: "number", description: "[run] \u5355\u7528\u4F8B\u6700\u5927\u6B65\u6570" },
+        promptVersion: { type: "string", description: "[run] prompt \u7248\u672C\uFF08\u9ED8\u8BA4 v2.0\uFF09" },
+        // ── check_inputs ──
+        metadata: { type: "string", description: "[check_inputs] app-metadata.json \u8DEF\u5F84" }
+      },
+      required: ["action"]
+    },
+    execute: async (args, context) => {
+      const action = String(args.action ?? "");
+      if (action === "run") {
+        const testcases = String(args.testcases ?? "");
+        const hap = String(args.hap ?? "");
+        const bundleName = String(args.bundleName ?? "");
+        if (!testcases || !hap || !bundleName) {
+          throw new Error(`${TOOL_ID4}: \`action:"run"\` requires \`testcases\`, \`hap\`, \`bundleName\``);
+        }
+        const taskDir = String(args.taskDir ?? "task");
+        const argv = [
+          "run",
+          "--testcases",
+          testcases,
+          "--hap",
+          hap,
+          "--bundle-name",
+          bundleName,
+          "--task-dir",
+          taskDir,
+          "--model-stdin"
+        ];
+        if (args.outputDir) argv.push("--output-dir", String(args.outputDir));
+        if (args.category) argv.push("--category", String(args.category));
+        if (args.deviceSn) argv.push("--device-sn", String(args.deviceSn));
+        if (args.ip) argv.push("--ip", String(args.ip));
+        if (args.port) argv.push("--port", String(args.port));
+        if (args.agentMode) argv.push("--agent-mode", String(args.agentMode));
+        if (args.maxSteps !== void 0 && args.maxSteps !== null) {
+          argv.push("--max-steps", String(args.maxSteps));
+        }
+        if (args.promptVersion) argv.push("--prompt-version", String(args.promptVersion));
+        if (args.timeout !== void 0 && args.timeout !== null) {
+          argv.push("--timeout", String(args.timeout));
+        }
+        const model = await deps.resolveModelParams(context.worktree);
+        if (!model) {
+          throw new Error(
+            `${TOOL_ID4}: \`action:"run"\` needs a model but deps.resolveModelParams returned null for worktree ${context.worktree ?? "(none)"} \u2014 configure the host's model provider`
+          );
+        }
+        const stdin = JSON.stringify({
+          apiKey: model.apiKey,
+          modelName: model.modelName,
+          baseURL: model.baseURL
+        });
+        const onAbortKill = () => {
+          try {
+            const env = { ...process.env };
+            delete env.HOMETRANS_MODEL_API_KEY;
+            delete env.HOMETRANS_MODEL_NAME;
+            delete env.HOMETRANS_MODEL_BASE_URL;
+            delete env.GLM_API_KEY;
+            delete env.TEST_API_KEY;
+            const k = spawn3(
+              "node",
+              [path9.join(AUTOTEST_ROOT, SCRIPT_REL4), "kill", "--task-dir", taskDir],
+              { cwd: context.directory, env, stdio: "ignore", detached: true, windowsHide: true }
+            );
+            k.on("error", () => {
+            });
+            k.unref();
+          } catch {
+          }
+        };
+        if (!context.abort.aborted) {
+          context.abort.addEventListener("abort", onAbortKill);
+        }
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL4,
+          argv,
+          cwd: context.directory,
+          abort: context.abort,
+          stdin
+        });
+        context.abort.removeEventListener("abort", onAbortKill);
+        if (r.spawnError) {
+          throw new Error(`${TOOL_ID4}: failed to spawn node \u2014 ${r.spawnError}`);
+        }
+        return { ok: r.exitCode === 0, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "status") {
+        const taskDir = String(args.taskDir ?? "");
+        if (!taskDir) {
+          throw new Error(`${TOOL_ID4}: \`action:"status"\` requires \`taskDir\``);
+        }
+        const argv = ["status", "--task-dir", taskDir];
+        if (args.outputDir) argv.push("--output-dir", String(args.outputDir));
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL4,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (r.spawnError) {
+          throw new Error(`${TOOL_ID4}: failed to spawn node \u2014 ${r.spawnError}`);
+        }
+        return { ok: r.exitCode === 0, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "kill") {
+        const taskDir = String(args.taskDir ?? "");
+        if (!taskDir) {
+          throw new Error(`${TOOL_ID4}: \`action:"kill"\` requires \`taskDir\``);
+        }
+        const argv = ["kill", "--task-dir", taskDir];
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL4,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (r.spawnError) {
+          throw new Error(`${TOOL_ID4}: failed to spawn node \u2014 ${r.spawnError}`);
+        }
+        return { ok: r.exitCode === 0, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "check_hap") {
+        const hap = String(args.hap ?? "");
+        if (!hap) {
+          throw new Error(`${TOOL_ID4}: \`action:"check_hap"\` requires \`hap\``);
+        }
+        const argv = ["check-hap", "--hap", hap];
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL4,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (r.spawnError) {
+          throw new Error(`${TOOL_ID4}: failed to spawn node \u2014 ${r.spawnError}`);
+        }
+        return { ok: r.exitCode === 0, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "check_inputs") {
+        const testcases = String(args.testcases ?? "");
+        const metadata = String(args.metadata ?? "");
+        if (!testcases || !metadata) {
+          throw new Error(`${TOOL_ID4}: \`action:"check_inputs"\` requires \`testcases\` and \`metadata\``);
+        }
+        const argv = ["check-inputs", "--testcases", testcases, "--metadata", metadata];
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL4,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (r.spawnError) {
+          throw new Error(`${TOOL_ID4}: failed to spawn node \u2014 ${r.spawnError}`);
+        }
+        return { ok: r.exitCode === 0, exitCode: r.exitCode, output: r.stdout };
+      }
+      if (action === "check_pre") {
+        const testcases = String(args.testcases ?? "");
+        if (!testcases) {
+          throw new Error(`${TOOL_ID4}: \`action:"check_pre"\` requires \`testcases\``);
+        }
+        const argv = ["check-pre", "--testcases", testcases];
+        const r = await runAutotestScript({
+          scriptRel: SCRIPT_REL4,
+          argv,
+          cwd: context.directory,
+          abort: context.abort
+        });
+        if (r.spawnError) {
+          throw new Error(`${TOOL_ID4}: failed to spawn node \u2014 ${r.spawnError}`);
+        }
+        return { ok: r.exitCode === 0, exitCode: r.exitCode, output: r.stdout };
+      }
+      throw new Error(
+        `${TOOL_ID4}: unknown \`action\` "${action}" (expected run|status|kill|check_hap|check_inputs|check_pre)`
+      );
+    }
+  };
+}
+
 // src/index.ts
 function createServer(deps) {
   return async (input) => {
-    const skillsRoot = path4.join(PKG_ROOT, "skills");
-    const agentsRoot = path4.join(PKG_ROOT, "agents");
+    const skillsRoot = path10.join(PKG_ROOT, "skills");
+    const agentsRoot = path10.join(PKG_ROOT, "agents");
     const agentPrompts = discoverA2HAgents(agentsRoot);
     return {
       dispose: async () => {
@@ -101,13 +699,33 @@ function createServer(deps) {
           }
         }
       },
-      // ── shell.env hook: inject DevEco Studio paths as env vars ──
-      // NOTE: deliberately uses the *base* env — the multimodal model apiKey
-      // is NOT injected into LLM shell sessions (would leak into every command
-      // and the transcript).
+      // ── shell.env hook: inject DevEco Studio paths + multimodal model ──
+      // params (from A2HHostDeps.resolveModelParams) as env vars, so the
+      // UI-alignment scripts (app_feature_verify.ts) can call the model
+      // without falling back to ~/.hometrans/config.json.
       "shell.env": async (shellInput, output) => {
         const a2hEnv = await buildA2HEnvBase(deps);
         Object.assign(output.env, a2hEnv);
+      },
+      // ── tool hook: run the UI-verification phone agent without leaking the
+      // model apiKey into env/argv — it is resolved from the host and piped to
+      // the script over stdin. See src/tools/a2h-app-feature-verify.ts.
+      //
+      // The autotest_* tools wrap the engine scripts under tools/autotest/
+      // (vendored from HomeTrans). They are grouped by noun — each tool
+      // dispatches on an `action` enum (e.g. `a2h_autotest_selftest` covers
+      // run|status|kill|check_hap|check_inputs|check_pre), so 11 engine
+      // subcommands surface as 4 plugin tools. Only `a2h_autotest_selftest`
+      // with `action:"run"` needs a model, resolved via deps.resolveModelParams
+      // and piped over stdin with the same secret-handling discipline; the
+      // rest are pure JSON/Markdown transforms or state probes with no model
+      // and no device.
+      tool: {
+        a2h_app_feature_verify: makeA2hAppFeatureVerifyTool(deps),
+        a2h_autotest_resolve_metadata: makeA2hAutotestResolveMetadataTool(deps),
+        a2h_autotest_testcases: makeA2hAutotestTestcasesTool(deps),
+        a2h_autotest_report: makeA2hAutotestReportTool(deps),
+        a2h_autotest_selftest: makeA2hAutotestSelftestTool(deps)
       }
     };
   };