@runweave/server-linux-x64 0.1.8 → 0.1.9

package/payload/plugins/toolkit/skills/acceptance/templates/reader.js

@@ -0,0 +1,326 @@
+/* A portable renderer: task content is always text, never markup. */
+/* global document, matchMedia, location, addEventListener, console */
+(() => {
+  "use strict";
+  const byId = (id) => document.getElementById(id);
+  const el = (tag, text, className) => {
+    const node = document.createElement(tag);
+    if (text !== undefined) node.textContent = text;
+    if (className) node.className = className;
+    return node;
+  };
+  try {
+    const data = JSON.parse(byId("gallery-data").textContent);
+    const assets = new Map(data.assets.map((asset) => [asset.id, asset]));
+    const viewer = el("dialog", undefined, "asset-viewer");
+    viewer.setAttribute("aria-labelledby", "asset-title");
+    const toolbar = el("div", undefined, "asset-toolbar");
+    const title = el("h2");
+    title.id = "asset-title";
+    const zoom = el("button", "实际尺寸");
+    zoom.type = "button";
+    zoom.setAttribute("aria-pressed", "false");
+    const close = el("button", "关闭原始材料");
+    close.type = "button";
+    const content = el("div", undefined, "asset-content");
+    let returnFocus;
+    toolbar.append(title, zoom, close);
+    viewer.append(toolbar, content);
+    document.body.append(viewer);
+    close.addEventListener("click", () => viewer.close());
+    viewer.addEventListener("close", () => {
+      document.body.classList.remove("viewing-asset");
+      returnFocus?.focus({ preventScroll: true });
+    });
+    zoom.addEventListener("click", () => {
+      const actual = viewer.classList.toggle("actual-size");
+      zoom.textContent = actual ? "适应屏幕" : "实际尺寸";
+      zoom.setAttribute("aria-pressed", String(actual));
+    });
+    const link = (label, asset) => {
+      const node = el("a", label);
+      node.href = asset.path;
+      node.addEventListener("click", (event) => {
+        event.preventDefault();
+        returnFocus = node;
+        title.textContent = asset.label;
+        content.replaceChildren();
+        viewer.classList.remove("actual-size");
+        zoom.hidden = asset.kind !== "image";
+        zoom.textContent = "实际尺寸";
+        zoom.setAttribute("aria-pressed", "false");
+        if (asset.kind === "image") {
+          const img = el("img");
+          img.src = asset.path;
+          img.alt = asset.label;
+          content.append(img);
+        } else content.append(el("pre", asset.text, "text-evidence"));
+        viewer.showModal();
+        document.body.classList.add("viewing-asset");
+        content.scrollTop = 0;
+        content.scrollLeft = 0;
+        close.focus();
+      });
+      return node;
+    };
+    const pageNodes = [],
+      headings = [],
+      directoryLinks = [];
+    let selected = 0,
+      expanded = false;
+    const types = {
+      single: "单图",
+      compare: "对照",
+      sequence: "关键状态",
+      text: "文字证据",
+    };
+    const limits = (values) => {
+      const box = el("div", undefined, "limits");
+      const list = el("ul");
+      values.forEach((value) => list.append(el("li", value)));
+      box.append(list);
+      return box;
+    };
+    const origin = (asset) => {
+      const { surface, capturedAt, sourceRef } = asset.origin;
+      return `来源：${surface || "未记录运行端"} · 时间：${capturedAt || "未记录"} · ${sourceRef || "未记录来源位置"}`;
+    };
+    const media = (item) => {
+      const asset = assets.get(item.assetId);
+      const figure = el("figure");
+      const caption = el("figcaption");
+      caption.append(
+        el("strong", item.label),
+        link(asset.kind === "image" ? "打开原图" : "打开原文", asset),
+      );
+      figure.append(caption);
+      if (asset.kind === "text") {
+        figure.append(el("pre", asset.text, "text-evidence"));
+        return figure;
+      }
+      const stage = el("div", undefined, "image-stage");
+      const anchor = link("", asset);
+      anchor.setAttribute("aria-label", `打开原图：${item.label}`);
+      const img = el("img");
+      img.alt = item.alt;
+      img.width = asset.width;
+      img.height = asset.height;
+      img.addEventListener("error", () => {
+        stage.replaceChildren(
+          el(
+            "p",
+            `图片不可用：${item.label}。请核对成果目录中的原图文件。`,
+            "media-error",
+          ),
+        );
+      });
+      if (item.crop) {
+        const crop = item.crop;
+        const viewport = el("div", undefined, "crop");
+        viewport.style.width = `${crop.width}px`;
+        viewport.style.aspectRatio = `${crop.width} / ${crop.height}`;
+        img.style.width = `${(asset.width / crop.width) * 100}%`;
+        img.style.left = `${(-crop.x / crop.width) * 100}%`;
+        img.style.top = `${(-crop.y / crop.height) * 100}%`;
+        viewport.append(img);
+        anchor.append(viewport);
+      } else anchor.append(img);
+      img.src = asset.path;
+      stage.append(anchor);
+      figure.append(stage);
+      if (item.crop)
+        figure.append(el("p", "局部取景 · 完整原图保持不变", "crop-note"));
+      figure.append(el("p", asset.origin.surface || "运行端未记录", "origin"));
+      return figure;
+    };
+    byId("task-title").textContent = data.task.title;
+    byId("task-scope").textContent = data.task.scope;
+    byId("material-kind").textContent =
+      data.task.materialKind === "historical" ? "历史示例" : "当前任务";
+    if (data.task.limitations.length) {
+      byId("task-limits").hidden = false;
+      data.task.limitations.forEach((value) =>
+        byId("task-limits").querySelector("ul").append(el("li", value)),
+      );
+    }
+    data.pages.forEach((page, index) => {
+      const section = el("article", undefined, "page");
+      section.id = `page-${page.id}`;
+      section.dataset.pageId = page.id;
+      section.dataset.type = page.type;
+      section.setAttribute("aria-labelledby", `heading-${page.id}`);
+      const heading = el("h2", page.title, "page-heading");
+      heading.id = `heading-${page.id}`;
+      heading.tabIndex = -1;
+      section.append(
+        el(
+          "p",
+          `${String(index + 1).padStart(2, "0")} / ${types[page.type]}`,
+          "eyebrow",
+        ),
+        heading,
+      );
+      if (page.evidenceState !== "observed")
+        section.append(
+          el(
+            "p",
+            page.evidenceState === "not-run" ? "此项未执行" : "此项证据不足",
+            "evidence-label",
+          ),
+        );
+      section.append(el("p", page.description, "description"));
+      if (page.limitations?.length) section.append(limits(page.limitations));
+      if (page.type === "sequence")
+        section.append(
+          el(
+            "p",
+            "以下为离散关键状态，不代表连续录像或实际等待时长。",
+            "sequence-note",
+          ),
+        );
+      const grid = el("div", undefined, `media-grid ${page.type}`);
+      page.items.forEach((item) => grid.append(media(item)));
+      section.append(grid);
+      if (page.lookAt)
+        section.append(el("p", `看这里：${page.lookAt}`, "look-at"));
+      const details = el("details", undefined, "sources");
+      details.append(el("summary", "查看来源与条件"));
+      const ids = new Set([
+        ...page.items.map((item) => item.assetId),
+        ...page.sourceIds,
+      ]);
+      ids.forEach((id) => {
+        const asset = assets.get(id);
+        const item = el("div", undefined, "source-item");
+        item.append(link(asset.label, asset), el("p", origin(asset)));
+        if (asset.kind === "text")
+          item.append(el("pre", asset.text, "text-evidence"));
+        details.append(item);
+      });
+      section.append(details);
+      byId("pages").append(section);
+      pageNodes.push(section);
+      headings.push(heading);
+      const entry = el("a");
+      entry.href = `#page=${page.id}`;
+      entry.append(
+        el("span", String(index + 1).padStart(2, "0")),
+        el("span", page.title),
+      );
+      entry.addEventListener("click", (event) => {
+        event.preventDefault();
+        select(index, true);
+        if (matchMedia("(max-width:760px)").matches)
+          byId("directory-details").open = false;
+      });
+      byId("directory").append(entry);
+      directoryLinks.push(entry);
+    });
+    function render(focus = false) {
+      pageNodes.forEach((node, i) => {
+        node.hidden = !expanded && i !== selected;
+      });
+      directoryLinks.forEach((node, i) => {
+        if (i === selected) node.setAttribute("aria-current", "page");
+        else node.removeAttribute("aria-current");
+      });
+      const total = data.pages.length;
+      byId("page-count").textContent = `${selected + 1} / ${total}`;
+      byId("page-name").textContent = data.pages[selected].title;
+      byId("previous").disabled = selected === 0;
+      byId("next").disabled = selected === total - 1;
+      byId("navigation").hidden = total === 1 || expanded;
+      byId("expand").hidden = total === 1;
+      byId("expand").textContent = expanded ? "返回分页" : "展开全部";
+      byId("expand").setAttribute("aria-pressed", String(expanded));
+      document.body.classList.toggle("expanded", expanded);
+      document.body.classList.toggle("single-task", total === 1);
+      byId("announcement").textContent =
+        `${expanded ? "全部展开，当前定位" : "第"} ${selected + 1} / ${total} 页：${data.pages[selected].title}`;
+      if (focus) {
+        headings[selected].focus({ preventScroll: true });
+        pageNodes[selected].scrollIntoView({ block: "start" });
+      }
+    }
+    function select(index, focus) {
+      selected = Math.max(0, Math.min(data.pages.length - 1, index));
+      const hash = `#page=${data.pages[selected].id}`;
+      if (location.hash !== hash) location.hash = hash;
+      byId("notice").hidden = true;
+      render(focus);
+    }
+    function readHash(focus) {
+      let id = "";
+      try {
+        id = decodeURIComponent(location.hash.replace(/^#page=/, ""));
+      } catch {
+        id = "invalid";
+      }
+      const index = data.pages.findIndex((page) => page.id === id);
+      if (location.hash && index < 0) {
+        select(0, focus);
+        byId("notice").textContent = "没有找到该页，已返回第一页。";
+        byId("notice").hidden = false;
+      } else {
+        selected = Math.max(0, index);
+        render(focus);
+      }
+    }
+    byId("previous").addEventListener("click", () =>
+      select(selected - 1, true),
+    );
+    byId("next").addEventListener("click", () => select(selected + 1, true));
+    document.querySelector(".skip-link").addEventListener("click", (event) => {
+      event.preventDefault();
+      render(true);
+    });
+    byId("expand").addEventListener("click", () => {
+      expanded = !expanded;
+      render(!expanded);
+    });
+    addEventListener("hashchange", () => readHash(true));
+    addEventListener("keydown", (event) => {
+      if (
+        viewer.open ||
+        expanded ||
+        event.altKey ||
+        event.ctrlKey ||
+        event.metaKey ||
+        event.shiftKey ||
+        event.target.closest(
+          "input,textarea,select,[contenteditable]:not([contenteditable=false]),pre",
+        )
+      )
+        return;
+      if (event.key === "ArrowRight" || event.key === "ArrowLeft") {
+        event.preventDefault();
+        select(selected + (event.key === "ArrowRight" ? 1 : -1), true);
+      }
+    });
+    let printDetails = [];
+    addEventListener("beforeprint", () => {
+      printDetails = [...document.querySelectorAll("details")].map((node) => [
+        node,
+        node.open,
+      ]);
+      printDetails.forEach(([node]) => {
+        node.open = true;
+      });
+    });
+    addEventListener("afterprint", () =>
+      printDetails.forEach(([node, open]) => {
+        node.open = open;
+      }),
+    );
+    if (matchMedia("(max-width:760px)").matches)
+      byId("directory-details").open = false;
+    readHash(false);
+  } catch (error) {
+    byId("pages").replaceChildren(
+      el("p", "材料无法读取。请从 task.json 重新校验并生成成果。", "fatal"),
+    );
+    byId("navigation").hidden = true;
+    byId("expand").hidden = true;
+    console.error("Gallery render failed", error);
+  }
+})();

package/payload/plugins/toolkit/skills/acceptance/templates/viewer.css

@@ -0,0 +1,55 @@
+/* Keep original assets inside the reader; preview sandboxes may block popups. */
+body.viewing-asset {
+  overflow: hidden;
+}
+.asset-viewer {
+  width: min(96vw, 1100px);
+  max-width: 96vw;
+  max-height: 94dvh;
+  padding: 0;
+  border: 1px solid #cbd5e1;
+  border-radius: 12px;
+  background: #fff;
+  color: #172033;
+}
+.asset-viewer::backdrop {
+  background: rgb(10 18 32 / 78%);
+}
+.asset-toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  padding: 12px;
+  border-bottom: 1px solid #d9e2ee;
+}
+.asset-toolbar h2 {
+  flex: 1 1 180px;
+  margin: 0;
+  font-size: 16px;
+  overflow-wrap: anywhere;
+}
+.asset-content {
+  max-height: 70dvh;
+  overflow: auto;
+  padding: 12px;
+}
+.asset-content img {
+  display: block;
+  max-width: 100%;
+  max-height: 65dvh;
+  width: auto;
+  height: auto;
+  margin: auto;
+  object-fit: contain;
+}
+.asset-viewer.actual-size img {
+  max-width: none;
+  max-height: none;
+  margin: 0;
+}
+@media print {
+  .asset-viewer {
+    display: none;
+  }
+}

package/payload/plugins/toolkit/skills/acceptance-gallery/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: acceptance-gallery
+description: 兼容 acceptance-gallery 旧名称，将图文材料请求转到 toolkit:acceptance。仅用于旧名称兼容；新请求使用统一入口。
+---
+
+# 旧名称兼容
+
+读取[统一验收材料 Skill](../acceptance/SKILL.md)，按用户本次范围执行。旧名称表示本次偏好图文，不扩大授权，不额外制作用户未要求的产物。原有脚本路径转发到统一实现。

package/payload/plugins/toolkit/skills/acceptance-gallery/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "acceptance-gallery（兼容）"
+  short_description: "旧名称兼容入口，当前规则与实现统一维护在验收材料 Skill 中"
+  default_prompt: "使用 $acceptance，按我请求的图文形式交付本次验收材料。"
+policy:
+  allow_implicit_invocation: false

package/payload/plugins/toolkit/skills/acceptance-gallery/references/capture-and-copy.md

@@ -0,0 +1,3 @@
+# 兼容引用
+
+当前规则已迁入统一验收材料 Skill，见[对应说明](../../acceptance/references/gallery-copy.md)。请按当前入口选择图文、视频或原始录屏，不在此维护第二套规则。

package/payload/plugins/toolkit/skills/acceptance-gallery/references/content-contract.md

@@ -0,0 +1,3 @@
+# 兼容引用
+
+当前规则已迁入统一验收材料 Skill，见[对应说明](../../acceptance/references/gallery-contract.md)。请按当前入口选择图文、视频或原始录屏，不在此维护第二套规则。

package/payload/plugins/toolkit/skills/acceptance-gallery/scripts/gallery.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""Compatibility path; canonical implementation lives in the acceptance skill."""
+from pathlib import Path
+import runpy
+import sys
+sys.dont_write_bytecode = True
+script = Path(__file__).resolve().parents[2] / 'acceptance' / 'scripts' / 'gallery.py'
+sys.path.insert(0, str(script.parent))
+runpy.run_path(str(script), run_name='__main__')

package/payload/plugins/toolkit/skills/acceptance-video/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: acceptance-video
+description: 兼容 acceptance-video 旧名称，将验收视频请求转到 toolkit:acceptance。仅用于旧名称兼容；新请求使用统一入口。
+---
+
+# 旧名称兼容
+
+读取[统一验收材料 Skill](../acceptance/SKILL.md)，按用户本次范围执行。旧名称表示本次偏好视频，不扩大授权，不额外制作用户未要求的产物。原有脚本路径转发到统一实现。

package/payload/plugins/toolkit/skills/acceptance-video/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "acceptance-video（兼容）"
+  short_description: "旧名称兼容入口，当前规则与实现统一维护在验收材料 Skill 中"
+  default_prompt: "使用 $acceptance，按我请求的视频形式交付本次验收材料。"
+policy:
+  allow_implicit_invocation: false

package/payload/plugins/toolkit/skills/acceptance-video/references/input-and-capture.md

@@ -0,0 +1,3 @@
+# 兼容引用
+
+当前规则已迁入统一验收材料 Skill，见[对应说明](../../acceptance/references/video.md)。请按当前入口选择图文、视频或原始录屏，不在此维护第二套规则。

package/payload/plugins/toolkit/skills/acceptance-video/references/mobile-review.md

@@ -0,0 +1,3 @@
+# 兼容引用
+
+当前规则已迁入统一验收材料 Skill，见[对应说明](../../acceptance/references/delivery.md)。请按当前入口选择图文、视频或原始录屏，不在此维护第二套规则。

package/payload/plugins/toolkit/skills/acceptance-video/scripts/capture.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""Compatibility path; canonical implementation lives in the acceptance skill."""
+from pathlib import Path
+import runpy
+import sys
+sys.dont_write_bytecode = True
+script = Path(__file__).resolve().parents[2] / 'acceptance' / 'scripts' / 'capture.py'
+sys.path.insert(0, str(script.parent))
+runpy.run_path(str(script), run_name='__main__')

package/payload/plugins/toolkit/skills/acceptance-video/scripts/video.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""Compatibility path; canonical implementation lives in the acceptance skill."""
+from pathlib import Path
+import runpy
+import sys
+sys.dont_write_bytecode = True
+script = Path(__file__).resolve().parents[2] / 'acceptance' / 'scripts' / 'video.py'
+sys.path.insert(0, str(script.parent))
+runpy.run_path(str(script), run_name='__main__')

package/payload/plugins/toolkit/skills/agent-device/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: agent-device
+description: 使用 agent-device CLI 在 iOS 模拟器和真机上复现问题、检查修复及执行有 Agent 监督的原生 UI 验收；提供设备预检、独立会话和证据记录。Web 页面使用 playwright-cli，固定 XCTest 回归保持原入口。
+---
+
+# iOS 交互验收
+
+用真实界面完成用户指定流程，并核对每个关键动作的结果。已验证工具版本为 **agent-device 0.21.3**；本技能的辅助脚本只支持 iOS，不把上游其他平台能力当作已验证能力。它是交互取证入口，不是无人值守 CI 或业务通过判定器。
+
+## 建立目标
+
+1. 先读工作区和目标包的 AGENTS.md。区分已安装 App 验收与当前代码验收；后者先按包入口构建、安装，记录产物来源。Runweave Native 是 `com.runweave.app.native`，独立随记是 `com.runweave.suiji`。
+2. 用 `xcrun simctl list devices` 或 `xcrun devicectl list devices` 发现设备；真机硬件 UDID 可从 `xcrun devicectl device info details --device <发现的ID> --json-output <本机文件>` 获得。必须指定目标，不以同名设备或第一台设备替代。
+3. Runweave 仓库的模拟器先运行 `node scripts/ios-simulators/cli.mjs start --app runweave --task-dir <绝对任务路径> --json`，随记将 app 参数改为 suiji；再按对应 iOS 包入口 `run --task-dir <同一目录>` 构建安装。使用本次返回的 UDID；两个 App 均可使用池中任一设备，所有 linked worktree 共用两台设备。两台都忙且安全回收失败时等待，不新建或克隆。其他项目仍遵循各自设备策略。
+4. 选择独立任务目录，通常为工作区 `.runweave/mobile-qa/<任务名>`。Runweave 模拟器使用 start 已创建的目录；其他目标由辅助脚本首次创建目录并固定设备、App 和随机 session；已有目录不覆盖。真机签名读 [iOS 准备与恢复](references/ios-setup.md)。
+
+下面的 `SKILL_DIR` 是本次实际加载的技能目录；`RUN_DIR` 是绝对路径。将示例占位符换成刚确认的目标：
+
+```bash
+python3 "$SKILL_DIR/scripts/device.py" init "$RUN_DIR" \
+  --kind device --udid "$IOS_UDID" --app com.runweave.suiji \
+  --team-id "$IOS_TEAM_ID"
+# 模拟器改为 --kind simulator，省略签名参数；先启动本任务拥有的模拟器。
+python3 "$SKILL_DIR/scripts/device.py" check "$RUN_DIR"
+python3 "$SKILL_DIR/scripts/device.py" run "$RUN_DIR" -- open --foreground
+```
+
+真机 UI 自动化固定共用 `com.runweave.agentdevice`，签名团队登记于 `~/.runweave/agent-device/runners/`。只传 `--team-id` 即可；显式 `--runner-id` 只允许这个固定值，禁止按 App、日期或任务新建身份。旧任务的其他 Runner ID 只允许 stop，不再用于 UI；重新 init 使用共享身份。任务仍保留独立 session 和证据目录。真机从首次托管 run 到 stop 持有跨 worktree 的设备锁；失败保留归属，使用原 task-dir stop，不按 PID 消失抢锁。
+
+辅助脚本要求 PATH 上的 CLI 版本匹配；不会自动安装、升级或启用权限。预检只检查当前工具与目标可达性，**不证明签名可安装、UI Automation 已授权或没有其他 XCTest 占用**。先检查已知运行任务，冲突时等待占用者结束；项目配置了设备池时不得另建设备绕过，不能杀掉他人 runner。首次 open 只有返回真实目标树后才证明本轮连接可用。
+
+## 无线更新后的仅启动检查
+
+真机无线 `localNetwork` 与 USB `wired` 均可使用，不把 USB 作为硬性前置。区分两个目标：
+
+- **安装/更新后启动 App**：按原生包入口完成构建安装、核对产物后，用 `launch` 直接走 CoreDevice，不创建 XCTest runner。可用不带 `--team-id` / `--runner-id` 的新任务目录执行 `init --kind device --udid <硬件UDID> --app <BundleID>`；这里只省略自动化 runner 签名，产品 App 的安装签名要求不变。
+- **页面操作或 UI 验收**：仍使用带 runner 签名的任务和 `run -- open --foreground`、快照及实际交互；不能用 `launch` 替代。操作前确认没有其他任务正在使用目标手机。
+
+```bash
+python3 "$SKILL_DIR/scripts/device.py" launch "$RUN_DIR"
+```
+
+`launch` 不安装、不强制重启、不自动重试；返回本次设备连接方式、进程 PID 和原生结果文件，明确标记 `uiVerified: false` / `automationReady: false`。它不启动 agent-device daemon，纯 launch 任务无需 `stop`。无线启动成功不等于 UI 自动化可用，更不等于完整更新/业务验收通过。
+
+`open` 失败时，包装器检查**本次调用新增**的 runner 日志；code 74 / IDE 通道断开会返回 `ios_xctest_bootstrap_failed` 诊断及日志位置，不再仅依赖笼统的连接超时提示。原错误退出状态保留，不自动降级为 launch 成功，不自动重放动作。私密命令不写额外诊断文件。无线 XCTest 失败不阻止另行执行明确的仅启动检查；只有确实需要 UI 时才排查无线调试链路或选择 USB 对照。
+
+## 操作与判定
+
+```bash
+python3 "$SKILL_DIR/scripts/device.py" run "$RUN_DIR" -- snapshot -i
+python3 "$SKILL_DIR/scripts/device.py" run "$RUN_DIR" -- press @e12 --settle
+python3 "$SKILL_DIR/scripts/device.py" run "$RUN_DIR" -- wait 'role="button" label="预期控件"' 5000
+python3 "$SKILL_DIR/scripts/device.py" run "$RUN_DIR" -- snapshot --json
+python3 "$SKILL_DIR/scripts/device.py" run "$RUN_DIR" -- screenshot "$RUN_DIR/final.png"
+```
+
+- 使用最新快照或差异中的 ref；UI 变化后旧 ref 不再可靠。同名控件加 role 或读取完整树确认唯一目标。需要其他命令时读已安装版本的 `agent-device help <command>`。
+- `snapshot -i` 会省略真实可见控件。找不到按钮、命中父容器或标签歧义时，读取完整 `snapshot --json`；必要时查看截图，用已观察到的边界选点。卡片中有链接或完成按钮时避开重叠区域，不能盲点卡片中心。
+- 快照可能仍来自绑定 App，而屏幕已跳到浏览器。跨 App 跳转、点击后无变化或树与预期矛盾时，实际查看 screenshot，再决定是否重新 `open --foreground` 返回目标。截图像素与树的逻辑坐标可能有倍率差异。
+- `open` exit 0 可能带初始快照失败警告；`--settle` 超时和 `XCTEST_RECORDED_FAILURE` 都可能发生在动作已生效之后。**先重新观察实际状态，再决定下一步；对保存、删除、完成待办等写操作，不因报错自动重试。** 必要时用获授权的只读 API 确認记录 ID、版本或删除状态。
+- 包装器将上游初始快照失败和 settle 超时转为非零退出，但不能识别所有业务失败。命令成功、元素存在、截图都不是业务后置条件的替代品。
+- 账号和环境沿用用户意图。正式数据优先只读；草稿验证先确认空白或隔离原草稿，使用唯一标记，验收后清理自己的草稿。不保存测试记录到正式服务，除非任务已授权该写入。
+- 登录优先由用户在设备输入凭据。不得将密码、token 写进技能、脚本、配置、回放或 Git。截图/树可能含用户内容，证据留在本机任务目录；敏感步骤用 `run "$RUN_DIR" --private -- <命令>` 跳过包装器输出落盘，但它不保证上游 daemon 没有日志，不能当成密码保密方案。
+- 验证重启恢复时明确使用 `open --relaunch`，等自动连接完成，再检查登录和草稿；普通 open/close 不能替代进程重启。
+
+## 录制、收尾与交付
+
+只有需要可重复流程时才录制：关闭现有会话后，用 fresh session 的 `open --foreground --save-script "$RUN_DIR/flow.ad"` 开始，完成必要状态断言，再执行 `session save-script`。检查生成脚本：失败动作可能没被录入，敏感输入不能进入脚本。
+
+从明确前置状态执行 `replay "$RUN_DIR/flow.ad" --json`；保留原始结果和实际步骤数。遇到 `REPLAY_DIVERGENCE/identity-mismatch`，读取新树分析或重新录制，不删除身份元数据来制造通过。一次回放成功不证明 CI 稳定性；自动录制 `.ad` 是本机产物，不替代仓库 YAML 验收合同。
+
+```bash
+python3 "$SKILL_DIR/scripts/device.py" stop "$RUN_DIR"
+```
+
+Runweave 模拟器完成任务后执行 `node scripts/ios-simulators/cli.mjs finish --task-dir <任务目录> --json`；它清理本任务自动化并释放 lease，异常恢复按仓库 `docs/cli/ios-simulators.md`。
+
+stop 只清理该任务 state-dir 的会话、daemon 和 runner，不卸载 App，也不关闭模拟器。仅在本任务创建/拥有的模拟器上另行 shutdown。签名执行器按用户意图保留，不能为腾名额自动卸载其他 App。
+
+交付说明：测试的设备、App/构建来源、业务后置条件及证据、失败/未执行项、清理结果。任务目录的 `metrics.jsonl` 只记录命令类型、耗时和退出码，不记录命令参数；编号 `.log` 是 CLI 原始输出。业务结论由 Agent 结合实际状态填写，不把命令 exit 0 自动标成用例通过。
+
+## 历史产物维护
+
+使用技能的 `scripts/resources.py status --workspace <仓库路径>` 查看任务与 Runner 缓存，`prune --workspace <仓库路径>` 先生成回收清单，`prune --workspace <仓库路径> --apply` 执行。任务及 `~/.agent-device/logs/qa-*` 自动化日志分别保留最近 20 个、14 天且各不超过 1 GiB；设备锁保护的任务和对应日志不删除。每个签名团队/平台只保留最新共享 Runner 构建；旧身份缓存删除。清理时有 Xcode/XCTest/Agent Device 进程则阻塞，不终止其他任务。stop 成功后自动按这些上限回收已登记任务与缓存；手动 prune 可跨 linked worktree 发现历史目录。其他活动任务导致清理推迟时，会给出提示，随后执行 prune；仅更新脚本不会回收历史磁盘。
+
+`--all-history --apply` 是维护者明确要求删除全部历史证据时的一次性入口，不用于日常收尾。该入口额外删除仓库 `.runweave` 下由 Xcode `info.plist` 与 Build 目录确认的历史 DerivedData；保留当前包 `.build`。它仍保留占用任务和共享 Runner 构建，不卸载产品 App，不擦除模拟器，也不删除业务数据库。工具不会自动卸载手机上的旧 Runner；迁移时核对空闲、明确 Bundle ID 清单，再由维护者卸载。小型清理清单位于 `~/.runweave/agent-device/last-cleanup.json`。

package/payload/plugins/toolkit/skills/agent-device/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "iOS Agent Device"
+  short_description: "用独立设备会话完成 iOS 交互验收，保存证据并确认动作结果"
+  default_prompt: "使用 $agent-device 验证指定 iOS App 的功能，记录真实后置状态、失败和清理结果。"

package/payload/plugins/toolkit/skills/agent-device/references/ios-setup.md

@@ -0,0 +1,36 @@
+# iOS 准备与恢复
+
+## 工具与签名
+
+验证基线：agent-device 0.21.3、Node 22.12+、macOS/Xcode。先用已安装 CLI 的 `help physical-device` 和 `help <command>` 核对行为。需要安装时使用 `npm install -g agent-device@0.21.3`；若本机 npm 是内部镜像 shim，检查 `command -v npm` 后可直接调用当前 Node 安装的 `npm-cli.js` 并指定官方 registry，不修改全局 registry。
+
+真机需要信任配对、Developer Mode、可用签名、设备连接与必要的解锁。`DevToolsSecurity -status` 为 disabled 时，按当前任务已有授权处理；启用需要管理员权限，系统密码由用户在系统界面输入。不能把全部连接超时都归因于锁屏或 UI Automation 提示。
+
+从当前工程/有效 provisioning profile 确认 Team ID，**证书名称括号里的 ID 不一定是 provisioning 的 Team ID**。真机自动化复用固定 `com.runweave.agentdevice`，基础 App 与 `com.runweave.agentdevice.uitests.xctrunner` 都需要可用签名；不要改变产品 App 的 Bundle ID 或重签成新安装。
+
+若 CLI `xcodebuild` 报 `No Accounts`，先检查 Xcode Apple Accounts，不能直接断言用户未登录。GUI 已登录而新描述文件缺失时，可复制上游包内 `dist/apple` 到本机任务目录（保留相对 Swift package 路径），仅修改副本的 Team，基础 Bundle ID 固定为共享身份，用 Xcode Signing & Capabilities 自动签名，并在指定真机上 Build For Testing。成功后再回到原 CLI 验证；不要修改已安装上游源码。个人签名值只放本机任务配置。
+
+免费开发者签名可能因设备已有 App 数量达到上限而拒绝安装。先列出冲突 App；若要替换旧测试 runner，确认它空闲、找到可恢复安装包并验证签名，依据用户授权再卸载。不能卸载 Runweave/随记来绕过限制，也不能用另一个工具的 Bundle ID 静默覆盖旧 runner。
+
+预检未检查 provisioning 配额/有效期、UI Automation 授权和全部占用者；首次真实 open/快照是必要验证。`check` 输出的 `automationReady: false` 表示尚未在这一预检中证明 UI 可操作，不表示操作必然失败。
+
+## 恢复边界
+
+| 证据                                   | 下一步                                                                                                           |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| devicectl unavailable、网络查找设备    | 重新确认线缆或同一网络、设备解锁，不新建同名模拟器冒充真机                                                       |
+| 原生 Mac 窗口工具找不到窗口            | 检查 Mac 是否锁屏，不能混同 iPhone 离线                                                                          |
+| 系统明确提示输入密码启用 UI Automation | 用户在手机完成，保留正在启动的 runner 并等待；没有提示证据时先看日志                                             |
+| open exit 0，但初始 snapshot 失败      | 当前不能算 UI 连接成功；检查任务 state/sessions 下 runner.log 的本次末尾                                         |
+| 真机无线已安装 App，只需检查启动       | 使用辅助脚本 launch，直接经 CoreDevice 启动；不依赖 XCTest，不宣称 UI 验收通过                                   |
+| runner code 74 / IDE 通道断开          | 检查本次 .diagnostic.json 和 runner.log；先区分 App 启动与 XCTest 握手，不靠延长超时、重复重签或重放业务动作恢复 |
+| 点击失败或 settle 超时                 | 先观察动作是否生效；不得自动重试写动作                                                                           |
+| 精简树漏控件                           | 完整 JSON、截图；坐标回退必须基于当前边界并验证后置状态                                                          |
+| 快照显示目标 App，但截图是其他 App     | 以真实前台截图为准，按任务需要返回目标 App                                                                       |
+| 回放身份不匹配                         | 留存错误、重读结构或重新录制；不删除元数据强行通过                                                               |
+
+0.21.3 的本地实测曾出现精简树遗漏、卡片中心误触链接、动作发生后 XCTest 报错、录制祖先层级不匹配。它们是需要识别的失败模式，不是每次启动都必须执行的检查清单，也不能据此自动修改产品代码。
+
+## Runweave 共享模拟器
+
+在 Runweave linked worktree 中先通过仓库 `scripts/ios-simulators/cli.mjs` 申请设备，两个 App 可使用池中任一台；整个验证过程共用 task-dir 和 lease。初始化前用包内 run 入口构建安装；两台都忙且安全回收失败时等待，不另建设备。stop 只停止自动化，结束任务用 finish 释放占用。异常时查看 status 和本任务证据，再按 `docs/cli/ios-simulators.md` 对明确 lease 恢复；空闲超时只在安全清理成功后回收，不能强行抢锁。技能必须由用户主动安装或更新，不由 Desktop 自动复制。