@coda-console/testbed 0.0.0 → 1.2.0

package/.coda/capabilities/run-on-device.bpmn

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 在测试机上执行（README.md）：会话的 host-sim 为测试机交来的命令。测试机只借不排：它借的是
+     use-testbed 交给这个会话的任务所占的组 device:<设备名>，会话没在做那台设备的任务就立刻拒绝。借到后在会话的目录里、带会话的环境执行；
+     任务答复、出错或被取消时，还在执行的命令随之停下，测试机等它停完才切黑屏。命令的退出码作为输出 exit_code，交给 host-sim。
+     能力：只被调用，结果交给调用者。 -->
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:coda="https://coda.pub/schema/bpmn/1.0" id="run-on-device-definitions" targetNamespace="https://coda.pub/plugins/testbed">
+  <process id="run-on-device" name="在测试机上执行" isExecutable="true" coda:title="{{inputs.device}}：{{inputs.label}}">
+    <extensionElements>
+      <coda:input name="spec" required="true" description="host-sim 写下的命令说明（JSON 文件的绝对路径：命令、目录、环境）" />
+      <coda:input name="device" required="true" description="设备名，如 iphone-testbed" />
+      <coda:input name="label" default="在测试机上执行" description="运行的标题：这条命令" />
+    </extensionElements>
+    <startEvent id="start" />
+    <sequenceFlow id="to-borrow" sourceRef="start" targetRef="borrow" />
+    <serviceTask id="borrow" name="借测试机" coda:action="hold-group" coda:status="借测试机 {{inputs.device}}">
+      <extensionElements>
+        <coda:param name="group" value="device:{{inputs.device}}" />
+        <coda:param name="capacity" value="1" />
+        <coda:param name="borrow" value="only" />
+      </extensionElements>
+    </serviceTask>
+    <sequenceFlow id="to-run" sourceRef="borrow" targetRef="command" />
+    <!-- exec：取消时整组收到 TERM，执行器等这个进程退出；它等命令结束再退出。 -->
+    <scriptTask id="command" name="执行" coda:checkout="false" coda:timeout="600" coda:status="在 {{inputs.device}} 上执行：{{inputs.label}}" scriptFormat="bash">
+      <extensionElements>
+        <coda:env name="SPEC" value="=inputs.spec" />
+        <coda:output name="exit_code" />
+      </extensionElements>
+      <script>exec node "$CODA_PLUGIN_PATH/scripts/run-on-device.mjs"</script>
+    </scriptTask>
+    <sequenceFlow id="ran" sourceRef="command" targetRef="end" />
+    <endEvent id="end" />
+  </process>
+</definitions>

package/.coda/capabilities/use-testbed.bpmn

@@ -0,0 +1,159 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- 使用测试机（README.md）：测试机的唯一入口。先从本机的设备登记查出这台设备，再排进它的组 device:<设备名>，
+     按需装上 App，把任务交给调用的会话；会话做任务期间，它用 host-sim run --kind <设备> 的命令（能力 run-on-device）借用这个组。
+     任务答复、装包或任务出错、运行被取消，都先等借去的命令停完、再切黑屏，然后放开；切不过去就请用户处理，处理之前一直占着。
+     能力：只被调用（workflow_run 或 callActivity），结果交给调用者。 -->
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:coda="https://coda.pub/schema/bpmn/1.0" id="use-testbed-definitions" targetNamespace="https://coda.pub/plugins/testbed">
+  <message id="cancel" name="workflow.cancel" />
+  <process id="use-testbed" name="使用测试机" isExecutable="true" coda:title="{{inputs.device}}：{{inputs.task}}">
+    <extensionElements>
+      <coda:input name="device" required="true" description="设备名：它所在 Mac 的测试机插件登记的 id，如 iphone-testbed" />
+      <coda:input name="instructions" required="true" description="要会话在测试机上做什么、做完怎么答复（写进交给会话的任务）" />
+      <coda:input name="task" default="在测试机上验证" description="交给会话的任务名" />
+      <coda:input name="app" description="先装到测试机的 App（.app 或 .ipa 的绝对路径）；不填就不装" />
+    </extensionElements>
+    <startEvent id="start" />
+    <sequenceFlow id="to-find" sourceRef="start" targetRef="find" />
+    <!-- 这台 Mac 登记了哪台设备叫这个名字：显示名、UDID 与给会话的说明。没有登记就到此为止，不排队。 -->
+    <scriptTask id="find" name="找测试机" coda:checkout="false" coda:timeout="1" coda:status="找测试机 {{inputs.device}}" scriptFormat="bash">
+      <extensionElements>
+        <coda:env name="DEVICE" value="=inputs.device" />
+        <coda:output name="name" />
+        <coda:output name="udid" />
+        <coda:output name="note" />
+      </extensionElements>
+      <script>node "$CODA_PLUGIN_PATH/scripts/device.mjs"</script>
+    </scriptTask>
+    <sequenceFlow id="to-testbed" sourceRef="find" targetRef="testbed" />
+
+    <!-- 占着测试机的这一段：离开它就放开，所以切黑屏在里面。 -->
+    <subProcess id="testbed" name="占用测试机">
+      <startEvent id="testbed-start" />
+      <sequenceFlow id="to-hold" sourceRef="testbed-start" targetRef="hold" />
+      <serviceTask id="hold" name="等测试机" coda:action="hold-group" coda:status="等测试机 {{find.name}}">
+        <extensionElements>
+          <coda:param name="group" value="device:{{inputs.device}}" />
+          <coda:param name="capacity" value="1" />
+          <!-- 每次使用都排队：做着上一次任务的会话再发起一次，也排在它后面，不借它的。 -->
+          <coda:param name="borrow" value="no" />
+        </extensionElements>
+      </serviceTask>
+      <sequenceFlow id="to-has-app" sourceRef="hold" targetRef="has-app" />
+      <exclusiveGateway id="has-app" default="no-app" />
+      <sequenceFlow id="with-app" sourceRef="has-app" targetRef="install">
+        <conditionExpression xsi:type="tFormalExpression">=inputs.app</conditionExpression>
+      </sequenceFlow>
+      <sequenceFlow id="no-app" sourceRef="has-app" targetRef="task" />
+      <scriptTask id="install" name="装 App" coda:checkout="false" coda:timeout="15" coda:status="把 App 装到 {{find.name}}" scriptFormat="bash">
+        <extensionElements>
+          <coda:env name="UDID" value="=find.udid" />
+          <coda:env name="APP" value="=inputs.app" />
+        </extensionElements>
+        <script>xcrun devicectl device install app --device "$UDID" "$APP"</script>
+      </scriptTask>
+      <sequenceFlow id="installed" sourceRef="install" targetRef="task" />
+      <userTask id="task" name="=inputs.task" coda:status="{{find.name}} 交给会话使用">
+        <documentation>{{inputs.instructions}}
+
+测试机 {{find.name}}（设备名 {{inputs.device}}，UDID {{find.udid}}）由这个任务占着，直到答复：本会话（含子 Agent）用 host-sim run --kind {{inputs.device}} -- &lt;命令&gt; 操作它，命令结束不会交出设备。答复之后还在执行的命令随之停下，测试机切黑屏，再交给下一位。
+
+{{find.note}}</documentation>
+      </userTask>
+      <sequenceFlow id="used" sourceRef="task" targetRef="black" />
+
+      <!-- 装包或任务出错、运行被取消：同样先切黑屏，再让运行以原来的原因结束。 -->
+      <boundaryEvent id="install-cancelled" attachedToRef="install"><messageEventDefinition messageRef="cancel" /></boundaryEvent>
+      <boundaryEvent id="install-failed" attachedToRef="install"><errorEventDefinition /></boundaryEvent>
+      <boundaryEvent id="task-cancelled" attachedToRef="task"><messageEventDefinition messageRef="cancel" /></boundaryEvent>
+      <boundaryEvent id="task-failed" attachedToRef="task"><errorEventDefinition /></boundaryEvent>
+      <sequenceFlow id="install-cancelled-black" sourceRef="install-cancelled" targetRef="black-stop" />
+      <sequenceFlow id="install-failed-black" sourceRef="install-failed" targetRef="black-stop" />
+      <sequenceFlow id="task-cancelled-black" sourceRef="task-cancelled" targetRef="black-stop" />
+      <sequenceFlow id="task-failed-black" sourceRef="task-failed" targetRef="black-stop" />
+
+      <scriptTask id="black" name="切黑屏" coda:checkout="false" coda:timeout="2" coda:status="{{find.name}} 切黑屏" scriptFormat="bash">
+        <extensionElements>
+          <coda:env name="DEVICE" value="=inputs.device" />
+          <coda:env name="UDID" value="=find.udid" />
+          <coda:env name="COMMANDS" value="=vars.testbed.blackscreen" />
+        </extensionElements>
+        <script>node "$CODA_PLUGIN_PATH/scripts/blackscreen.mjs"</script>
+      </scriptTask>
+      <sequenceFlow id="blacked" sourceRef="black" targetRef="done" />
+      <!-- 切黑屏时被取消：照样切完；运行随后以「已取消」结束。 -->
+      <boundaryEvent id="black-cancelled" attachedToRef="black" cancelActivity="false"><messageEventDefinition messageRef="cancel" /></boundaryEvent>
+      <sequenceFlow id="black-noted" sourceRef="black-cancelled" targetRef="noted" />
+      <endEvent id="noted" />
+      <boundaryEvent id="black-failed" attachedToRef="black"><errorEventDefinition /></boundaryEvent>
+      <sequenceFlow id="ask-black" sourceRef="black-failed" targetRef="black-trouble" />
+      <userTask id="black-trouble" name="测试机切黑屏失败" coda:assignee="user" coda:handback="false" coda:status="{{find.name}} 切黑屏失败，等你处理">
+        <documentation>测试机 {{find.name}}（{{inputs.device}}）用完后没能切黑屏，原因见运行页「切黑屏」这一步的日志。在你处理之前，它不会交给下一位。
+
+检查设备连接、黑屏 App 或插件设置「切黑屏命令」后选「重试」；已经手动处理好了就选「我处理好了，放锁」。</documentation>
+        <extensionElements>
+          <coda:choice id="retry" name="重试" />
+          <coda:choice id="release" name="我处理好了，放锁" />
+        </extensionElements>
+      </userTask>
+      <sequenceFlow id="black-answered" sourceRef="black-trouble" targetRef="black-again" />
+      <exclusiveGateway id="black-again" default="black-released" />
+      <sequenceFlow id="black-retry" sourceRef="black-again" targetRef="black">
+        <conditionExpression xsi:type="tFormalExpression">=black-trouble.chose.retry</conditionExpression>
+      </sequenceFlow>
+      <sequenceFlow id="black-released" sourceRef="black-again" targetRef="done" />
+      <endEvent id="done">
+        <extensionElements><coda:output name="stopped" value="false" /></extensionElements>
+      </endEvent>
+
+      <scriptTask id="black-stop" name="切黑屏（没有做完）" coda:checkout="false" coda:timeout="2" coda:status="{{find.name}} 切黑屏" scriptFormat="bash">
+        <extensionElements>
+          <coda:env name="DEVICE" value="=inputs.device" />
+          <coda:env name="UDID" value="=find.udid" />
+          <coda:env name="COMMANDS" value="=vars.testbed.blackscreen" />
+        </extensionElements>
+        <script>node "$CODA_PLUGIN_PATH/scripts/blackscreen.mjs"</script>
+      </scriptTask>
+      <sequenceFlow id="stop-blacked" sourceRef="black-stop" targetRef="stopped" />
+      <boundaryEvent id="black-stop-cancelled" attachedToRef="black-stop" cancelActivity="false"><messageEventDefinition messageRef="cancel" /></boundaryEvent>
+      <sequenceFlow id="black-stop-noted" sourceRef="black-stop-cancelled" targetRef="stop-noted" />
+      <endEvent id="stop-noted" />
+      <boundaryEvent id="black-stop-failed" attachedToRef="black-stop"><errorEventDefinition /></boundaryEvent>
+      <sequenceFlow id="ask-black-stop" sourceRef="black-stop-failed" targetRef="black-stop-trouble" />
+      <userTask id="black-stop-trouble" name="测试机切黑屏失败" coda:assignee="user" coda:handback="false" coda:status="{{find.name}} 切黑屏失败，等你处理">
+        <documentation>测试机 {{find.name}}（{{inputs.device}}）没能切黑屏，原因见运行页「切黑屏（没有做完）」这一步的日志。在你处理之前，它不会交给下一位。
+
+检查设备连接、黑屏 App 或插件设置「切黑屏命令」后选「重试」；已经手动处理好了就选「我处理好了，放锁」。</documentation>
+        <extensionElements>
+          <coda:choice id="retry" name="重试" />
+          <coda:choice id="release" name="我处理好了，放锁" />
+        </extensionElements>
+      </userTask>
+      <sequenceFlow id="black-stop-answered" sourceRef="black-stop-trouble" targetRef="black-stop-again" />
+      <exclusiveGateway id="black-stop-again" default="black-stop-released" />
+      <sequenceFlow id="black-stop-retry" sourceRef="black-stop-again" targetRef="black-stop">
+        <conditionExpression xsi:type="tFormalExpression">=black-stop-trouble.chose.retry</conditionExpression>
+      </sequenceFlow>
+      <sequenceFlow id="black-stop-released" sourceRef="black-stop-again" targetRef="stopped" />
+      <endEvent id="stopped">
+        <extensionElements><coda:output name="stopped" value="true" /></extensionElements>
+      </endEvent>
+    </subProcess>
+
+    <!-- 放开之后：做完了把任务的答复交给调用者；没做完（出错、被取消）就以原来的原因结束。 -->
+    <sequenceFlow id="to-how" sourceRef="testbed" targetRef="how" />
+    <exclusiveGateway id="how" default="to-end" />
+    <sequenceFlow id="to-not-done" sourceRef="how" targetRef="not-done">
+      <conditionExpression xsi:type="tFormalExpression">=testbed.stopped</conditionExpression>
+    </sequenceFlow>
+    <sequenceFlow id="to-end" sourceRef="how" targetRef="end" />
+    <endEvent id="end">
+      <extensionElements>
+        <coda:output name="result" value="=task.result" />
+        <coda:output name="note" value="=task.note" />
+        <coda:output name="choice" value="=task.choice" />
+      </extensionElements>
+    </endEvent>
+    <endEvent id="not-done" name="没有做完"><errorEventDefinition /></endEvent>
+  </process>
+</definitions>

package/README.md

@@ -1,3 +1,59 @@
-# @coda-console/testbed
+# 测试机
 
-Bootstrap placeholder. The usable release will be published by coda-console/coda-plugins.
+iPhone、iPad 测试机由这个插件登记归属。每台设备是一个[并发组](https://github.com/coda-console/coda/blob/main/docs/workflows.md#并发组) `device:<设备名>`，容量 1；
+排到、装 App、交给会话、复原都写在它的能力 `use-testbed`（`.coda/capabilities/use-testbed.bpmn`）里，会话借用设备的命令走它的另一个能力 `run-on-device`。
+它依赖[宿主资源](../host/README.md)插件（`extensionDependencies`），接在那边的扩展点 `kinds` 上：会话里 `host-sim --kind <设备名>` 由它的 `scripts/host-sim.mjs` 处理。
+从 Coda 的商店安装（npm 包 `@coda-console/testbed`），装它时一起装上宿主资源；给 Agent 的用法在 Skill `testbed`（`skills/testbed/SKILL.md`）。
+需要会话操作时调用 `use-testbed`。无需会话操作但需要独占设备的流程（如预览版直装、开发流程的设备验收），可自行用 `hold-group device:<id>`（capacity 1）占一段，测试机会话排在它后面；流程负责自己的操作与收尾。
+
+**设备登记**：插件在这个后端的状态目录里的 `devices.json`（[`CODA_PLUGIN_STATE`](https://github.com/coda-console/coda/blob/main/docs/plugins.md#插件进程的环境)：默认实例是 `~/.local/state/coda/data/plugins/testbed/devices.json`，
+另一个[后端实例](https://github.com/coda-console/coda/blob/main/docs/deployment.md#后端实例)是 `P/data/plugins/testbed/devices.json`）。它是一个数组，每项一台归本实例的设备：
+
+```json
+[{ "id": "iphone-testbed", "name": "iPhone13pm", "udid": "…", "note": "…" }]
+```
+
+`id` 是设备名（小写字母开头，字母、数字、连字符），`name` 显示名，`udid` 不重复；`note` 可省，是给拿到任务的会话的说明（这台 Mac 上怎么驱动这台设备、哪些东西不能碰），原样附在任务末尾。
+登记在哪个实例就归哪个实例，`devices.json` 是归属的唯一事实来源。插件启动时声明 `device:<id>`，把 `name`、`udid`、`note` 发布到空间，以 `udid` 为唯一属性；文件变化时重新全量声明。空间里同一设备只能登记一次，同名或相同 UDID 的重复登记会使占用失败并报冲突。
+登记读不了时日志记录错误，保留已有声明；有效的空数组 `[]` 撤销全部声明。设备正被使用时不要改名或换 UDID。
+
+任何实例的会话都能用设备，由引擎在归属实例排队。安装、会话的 `host-sim` 命令和切黑屏在发起的 Mac 上执行；这台 Mac 须与设备配对，跑 XCTest 还须有本机 runner。
+
+**入口**：
+- Agent：`workflow_run`，`workflow: "use-testbed"`，`inputs` 给 `device`（设备名，归属实例登记的 `id`）、
+  `instructions`（要会话在测试机上做什么、怎么答复），可选 `app`（先装上的 `.app` 或 `.ipa` 的绝对路径）、`task`（任务名，默认「在测试机上验证」）。插件的说明告诉每个会话的 Agent 这样调用。
+- 其他流程：`<callActivity calledElement="use-testbed">`，参数用 `coda:param`；项目流程先在自己的步骤构建、签名，把 App 路径传给它。
+
+**过程**：
+1. 「找测试机」：先查本地登记；没有这个 id 就用 `coda-resources group-owner device:<id>` 读取归属实例声明的显示名、UDID 和说明。两边都没有则报「没有这台测试机」，列出本地可用设备，不排队。
+2. 「等测试机」：`hold-group` 为「占用测试机」这一段排进组 `device:<设备名>`（`capacity` 1、`borrow="no"`：每次使用都排队，做着上一次任务的会话再发起一次也排在后面），由引擎到归属实例排队，排到才往下走；之后到这一段结束都占着它。
+3. 有 `app` 就装上（`xcrun devicectl device install app`），再把任务交给调用的会话：要求是 `instructions`，加上设备名、UDID、借用方法和登记里的说明。
+   做任务期间，这个会话（含子 Agent）用 `host-sim run --kind <设备名> -- <命令>` 操作设备：`host-sim` 经 `coda-run` 把命令交给能力 `run-on-device`，
+   它用 `hold-group borrow="only"` 借这个组——只借给正在做这台设备任务的会话，别的情况立刻拒绝、不排队——借到后在会话的目录里、带会话的环境执行，
+   附上 `HOST_SIM_LEASE=coda-run:<设备名>`（命令里再调用 `host-sim run --kind <设备名>` 直接执行，`host-sim check` 通过），退出码交回 `host-sim`。
+   任务答复、撤回或运行被取消时，还在执行的这些命令随之停下（[并发组](https://github.com/coda-console/coda/blob/main/docs/workflows.md#并发组)「借用跟着任务走」），下一步等它们停完才开始。
+4. 「切黑屏」：任务答复、借用的命令停完后，在发起的 Mac 上用 `xcrun devicectl device process launch --terminate-existing` 在设备上打开[黑屏 App](#黑屏-app)，限时 2 分钟；
+   设置「切黑屏命令」（`testbed.blackscreen`）里有这台设备的一行时，改为用 `sh` 执行那一行，设备的 UDID 在环境变量 `UDID` 里。
+   装 App 或任务出错、任务被拒绝、运行被取消（流程等着 [`workflow.cancel`](https://github.com/coda-console/coda/blob/main/docs/workflows.md#执行与恢复)）时，同样先切黑屏；切黑屏时被取消，照样切完。
+5. 切不过去（命令失败或超时，如设备断开、锁屏或没装黑屏 App）：给用户一张卡片「测试机切黑屏失败」，选「重试」或「我处理好了，放锁」；处理之前设备一直占着，不交给下一位。
+   卡片没有主按钮。
+6. 离开「占用测试机」这一段才放开组，排在后面的随即拿到。
+
+**结果**：做完了，`result`、`note`、`choice` 是任务的答复，调用者照常读到；没做完时以原来的原因结束（被拒绝时是拒绝的理由），被取消的记为已取消。
+
+**设置**：`testbed.blackscreen`「切黑屏命令」是表格，默认没有行；某台设备要换掉默认的做法时加一行：左边是设备名，右边是在发起的 Mac 上执行的命令。
+设置在整个空间只有一份，所以各台 Mac 的设备写在同一张表里，设备名在空间里不重复。
+
+**面板**「测试机」（`devices`）：这台 Mac 登记的每台设备一张卡片（显示名、设备名），写谁在用（`use-testbed` 的运行与会话、会话借用的命令）、
+用了多久、谁在排队；没人用写「空闲」。读的是设备登记和 `CODA_GROUPS_STATE` 里的 `device:<设备名>`；本机没有登记设备就不显示。
+
+- 装上后对这台机器的所有项目生效（[安装、停用与卸载](https://github.com/coda-console/coda/blob/main/docs/plugins.md#安装停用与卸载)），可按 Tag 限定或在项目里停用。
+
+## 黑屏 App
+
+插件的 `blackscreen/BlackScreen.swift`：纯黑全屏、隐藏状态栏与主屏幕指示条的 App，iPhone、iPad 通用（OLED 黑色像素不发光；LCD 的 iPad 在它前台时把亮度压到最低，离开时还原）。
+Bundle ID 是 `com.leavan.blackscreen`，切黑屏默认打开的就是它。每台测试机装一次；签名用的开发描述文件到期或换设备时重装：
+
+1. 在本仓库工作树的会话里，用持锁执行（`run-held`）运行 `sh plugins/testbed/blackscreen/build.sh <输出目录> <描述文件名>`，占一个构建名额；
+   编译后用登录钥匙串里的 Apple Development 证书和这份开发描述文件签名（描述文件须是通配 App ID、包含目标设备，Team 取自描述文件），得到 `<输出目录>/BlackScreen.app`。它不碰设备。
+2. 在与设备配对的 Mac 上调用 `use-testbed`，`app` 给这个 `.app`：装上后任务交给会话，答复后的切黑屏打开它，切得过去就是装好了。

package/blackscreen/BlackScreen.swift

@@ -0,0 +1,39 @@
+import UIKit
+
+// 纯黑全屏：测试机用完交出前切到这里（插件「测试机」的切黑屏），空闲时停着；OLED 黑色像素不发光，不烧屏。
+// LCD（iPad）黑色仍有背光：在前台时把亮度压到最低，离开时还原，别的 App 和截图不受影响。
+final class BlackViewController: UIViewController {
+    override func loadView() {
+        view = UIView()
+        view.backgroundColor = .black
+    }
+
+    override var prefersStatusBarHidden: Bool { true }
+    override var prefersHomeIndicatorAutoHidden: Bool { true }
+}
+
+@main
+final class AppDelegate: UIResponder, UIApplicationDelegate {
+    var window: UIWindow?
+    private var savedBrightness: CGFloat?
+
+    func application(_ application: UIApplication,
+                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        window = UIWindow(frame: UIScreen.main.bounds)
+        window?.rootViewController = BlackViewController()
+        window?.makeKeyAndVisible()
+        return true
+    }
+
+    func applicationDidBecomeActive(_ application: UIApplication) {
+        savedBrightness = savedBrightness ?? UIScreen.main.brightness
+        UIScreen.main.brightness = 0
+    }
+
+    func applicationWillResignActive(_ application: UIApplication) {
+        if let saved = savedBrightness {
+            UIScreen.main.brightness = saved
+            savedBrightness = nil
+        }
+    }
+}

package/blackscreen/build.sh

@@ -0,0 +1,67 @@
+#!/bin/sh
+# 编译并签名黑屏 App（iPhone 与 iPad 通用），不装到设备：装经测试机插件的 use-testbed（app 给产物路径），见 README.md。
+# 用法：build.sh <输出目录> <描述文件名>。签名用登录钥匙串里的 Apple Development 证书与这份开发描述文件（须是通配 App ID、包含目标设备），
+# Team 取自描述文件。在 Coda 会话里交给持锁执行（run-held）运行，或在占着组 host 的流程步骤里：它经 host-sim 占构建名额。
+set -eu
+[ $# -eq 2 ] || { echo "用法：$0 <输出目录> <描述文件名>" >&2; exit 2; }
+# 已在构建名额里才直接编译；测试机上执行的命令也带 HOST_SIM_LEASE，但占的不是构建名额，所以问 host-sim。
+if ! host-sim check --kind build 2>/dev/null; then
+  exec host-sim run --kind build -- sh "$(cd "$(dirname "$0")" && pwd)/$(basename "$0")" "$@"
+fi
+# blackscreen.mjs 默认打开的就是这个 Bundle ID。
+BUNDLE_ID=com.leavan.blackscreen
+PROFILE_NAME="$2"
+mkdir -p "$1"
+APP="$(cd "$1" && pwd)/BlackScreen.app"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+rm -rf "$APP"; mkdir -p "$APP"
+
+profile=""
+for candidate in "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles"/*.mobileprovision; do
+  security cms -D -i "$candidate" > "$WORK/profile.plist" 2>/dev/null || continue
+  if [ "$(plutil -extract Name raw -o - "$WORK/profile.plist")" = "$PROFILE_NAME" ]; then profile="$candidate"; break; fi
+done
+[ -n "$profile" ] || { echo "找不到描述文件：$PROFILE_NAME" >&2; exit 1; }
+TEAM="$(plutil -extract TeamIdentifier.0 raw -o - "$WORK/profile.plist")"
+identity=$(security find-identity -v -p codesigning | awk '/Apple Development/ {print $2; exit}')
+[ -n "$identity" ] || { echo "登录钥匙串里没有 Apple Development 证书" >&2; exit 1; }
+
+xcrun -sdk iphoneos swiftc -target arm64-apple-ios17.0 -O -parse-as-library \
+  "$(dirname "$0")/BlackScreen.swift" -o "$APP/BlackScreen"
+
+cat > "$APP/Info.plist" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>CFBundleIdentifier</key><string>$BUNDLE_ID</string>
+  <key>CFBundleExecutable</key><string>BlackScreen</string>
+  <key>CFBundleName</key><string>黑屏</string>
+  <key>CFBundleDisplayName</key><string>黑屏</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleVersion</key><string>1</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>CFBundleSupportedPlatforms</key><array><string>iPhoneOS</string></array>
+  <key>MinimumOSVersion</key><string>17.0</string>
+  <key>UIDeviceFamily</key><array><integer>1</integer><integer>2</integer></array>
+  <key>UIRequiresFullScreen</key><true/>
+  <key>UIRequiredDeviceCapabilities</key><array><string>arm64</string></array>
+  <key>UILaunchScreen</key><dict/>
+  <key>UIUserInterfaceStyle</key><string>Dark</string>
+  <key>UIStatusBarHidden</key><true/>
+</dict></plist>
+PLIST
+cp "$profile" "$APP/embedded.mobileprovision"
+
+cat > "$WORK/entitlements.plist" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>application-identifier</key><string>$TEAM.$BUNDLE_ID</string>
+  <key>com.apple.developer.team-identifier</key><string>$TEAM</string>
+  <key>get-task-allow</key><true/>
+</dict></plist>
+PLIST
+codesign --force --sign "$identity" --entitlements "$WORK/entitlements.plist" --timestamp=none "$APP"
+codesign --verify --strict "$APP"
+echo "$APP"

package/main.mjs

@@ -0,0 +1,30 @@
+import { watchFile, unwatchFile } from 'node:fs';
+import { join } from 'node:path';
+import { devices } from './scripts/registry.mjs';
+
+let stopWatching;
+let pending = Promise.resolve();
+export async function activate(coda) {
+  const file = join(coda.plugin.state, 'devices.json');
+  const publish = () => {
+    pending = pending.then(async () => {
+      const list = devices(file, { missingIsEmpty: false });
+      await coda.resources.declareGroups(list.map(device => ({
+        name: `device:${device.id}`,
+        attributes: { name: device.name ?? device.id, udid: device.udid, note: device.note ?? '' },
+        unique: ['udid'],
+      })));
+    }).catch(error => console.error(`测试机归属声明失败：${error.message}`));
+    return pending;
+  };
+  // Stat-based watching also observes atomic replacements and a deleted/recreated file.
+  watchFile(file, { interval: 500 }, publish);
+  stopWatching = () => unwatchFile(file, publish);
+  await publish();
+}
+
+export async function deactivate() {
+  stopWatching?.();
+  stopWatching = undefined;
+  await pending;
+}

package/package.json

@@ -1,7 +1,52 @@
 {
   "name": "@coda-console/testbed",
-  "version": "0.0.0",
-  "description": "Reserved for the first Coda plugin release.",
+  "id": "testbed",
+  "displayName": "测试机",
+  "description": "iPhone、iPad 测试机登记在哪个实例就归哪个实例，空间里同一设备只登记一次，重复占用报冲突。任何实例的会话都能用，在归属实例排队；安装、操作和切黑屏在发起的 Mac 执行，须与设备配对，XCTest 须有本机 runner。无需会话操作的流程可自行 hold-group device:<id>（capacity 1）独占。",
+  "version": "1.2.0",
+  "categories": [
+    "机器与资源"
+  ],
+  "extensionDependencies": [
+    "host"
+  ],
+  "contributes": {
+    "panels": [
+      {
+        "id": "devices",
+        "title": "测试机",
+        "command": "node \"$CODA_PLUGIN_PATH/scripts/panel.mjs\""
+      }
+    ],
+    "capabilities": [
+      "use-testbed",
+      "run-on-device"
+    ],
+    "extensions": {
+      "host/kinds": {
+        "command": "\"$CODA_NODE\" \"$CODA_PLUGIN_PATH/scripts/host-sim.mjs\""
+      }
+    },
+    "instructions": "要在 iPhone/iPad 测试机上操作或验证：调用 workflow_run，workflow 为 use-testbed，inputs 给 device（设备名，如 iphone-testbed）和 instructions；先装 App 就再给 app（.app 的绝对路径）。拿到任务后用 host-sim run --kind <设备名> 操作，做完用 workflow_task 答复。",
+    "configuration": {
+      "title": "测试机",
+      "properties": {
+        "testbed.blackscreen": {
+          "title": "切黑屏命令",
+          "type": "object",
+          "order": 1,
+          "description": "每台测试机用完、交给下一位之前怎么切黑屏。默认用 devicectl 在设备上打开黑屏 App（com.leavan.blackscreen）；某台要换做法就加一行：左边是设备名（归属实例的测试机插件登记的 id），右边是在发起的 Mac 上执行的命令（sh，设备的 UDID 在 $UDID）。失败时请你处理后再交出设备。",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {}
+        }
+      }
+    },
+    "skills": [
+      "skills/testbed"
+    ]
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,5 +55,16 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "files": [
+    ".coda",
+    "scripts",
+    "blackscreen",
+    "skills",
+    "main.mjs"
+  ],
+  "main": "main.mjs",
+  "activationEvents": [
+    "onStartupFinished"
+  ]
 }

package/scripts/blackscreen.mjs

@@ -0,0 +1,14 @@
+// Puts a test device to its black screen before it is handed on (README.md): the black screen app
+// (blackscreen/, installed on the device) launched over devicectl, or the line the plugin's setting `testbed.blackscreen`
+// gives for the device instead, run by sh with its UDID in `UDID`. Its output is the step's log; its exit, the step's.
+import { spawn } from 'node:child_process';
+
+// As blackscreen/build.sh signs it.
+const APP = 'com.leavan.blackscreen';
+const command = JSON.parse(process.env.COMMANDS || '{}')[process.env.DEVICE]?.trim()
+  || `xcrun devicectl device process launch --terminate-existing --device "$UDID" ${APP}`;
+console.log(`切黑屏：${command}`);
+const child = spawn('/bin/sh', ['-c', command], { stdio: 'inherit' });
+for (const name of ['SIGTERM', 'SIGINT']) process.on(name, () => child.kill(name));
+child.on('error', error => { console.error(error.message); process.exit(1); });
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/scripts/device.mjs

@@ -0,0 +1,13 @@
+// Find a device's name, UDID and note for the step outputs. Registration determines its owning instance,
+// whose declarations are published to the space. An id absent locally is resolved through group-owner;
+// if neither has it, report the missing device and the locally available ids.
+import { appendFileSync } from 'node:fs';
+import { resolveDevice } from './resolve-device.mjs';
+
+const device = process.env.DEVICE ?? '';
+let found;
+try { found = resolveDevice(device); } catch (error) { fail(error.message); }
+console.log(`测试机 ${device}：${found.name ?? device}（${found.udid}）`);
+appendFileSync(process.env.GITHUB_OUTPUT, `name=${String(found.name ?? device).replace(/\n/g, ' ')}\nudid=${found.udid}\nnote<<CODA_NOTE\n${found.note ?? ''}\nCODA_NOTE\n`);
+
+function fail(message) { console.error(message); process.exit(1); }

package/scripts/host-sim.mjs

@@ -0,0 +1,60 @@
+// What this plugin plugs into the host plugin's `host-sim` (its point `kinds`, README.md):
+// `host-sim run|check --kind <设备名> …` for a test device, handed over whole. In a session doing that device's task, a
+// command is handed to the capability 在测试机上执行 and followed with `coda-run`: Coda lends it the device the task holds
+// and runs it in the session's directory, with its environment. Inside that command (`HOST_SIM_LEASE=coda-run:<设备名>`),
+// or in a step whose run holds the device's group (`CODA_GROUPS` names device:<设备名>), it runs at once.
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { constants as system, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2), command = args[0];
+const option = name => { const at = args.indexOf(name); return at >= 0 ? args[at + 1] : undefined; };
+// A step names its session too; what it may run is what its groups (`CODA_GROUPS`) hold, never a device asked for the session.
+const kind = option('--kind'), thread = process.env.CODA_GROUPS === undefined && process.env.CODA_THREAD_ID, group = `device:${kind}`;
+// What Coda gives this command as the plugin's (Coda's docs/plugins.md「插件进程的环境」) is not what the session's commands run with.
+const session = () => Object.fromEntries(Object.entries(process.env).filter(([name]) => !/^CODA_(NODE|ARBITER|PLUGIN_.*)$/.test(name)));
+const lease = process.env.HOST_SIM_LEASE ?? '';
+const stepHeld = (process.env.CODA_GROUPS ?? '').split(' ').includes(group);
+const held = stepHeld || lease === `coda-run:${kind}`;
+
+if (command === 'run' && (held || thread)) {
+  const at = args.indexOf('--'), argv = at >= 0 ? args.slice(at + 1) : [];
+  if (!argv.length) fail('用法：host-sim run --kind <设备名> -- <命令> [参数…]', 2);
+  // Already inside a command on the device (a project script calling itself again): it is this one's.
+  if (held) follow(argv, { ...session(), HOST_SIM_LEASE: lease || `coda-group:${group}` });
+  else {
+    // What to run, where and with what, for 在测试机上执行 to read: kept while the run may still read it. coda-run ending
+    // with any status but 75 (Coda's docs/workflows.md「从命令行调用」) says the run is over or never started — the device
+    // not lent, say —, so it goes then; let go of (75, or a signal), the run goes on and reads it however late that is.
+    const env = session();
+    delete env.HOST_SIM_LEASE; delete env.HOST_SIM_DEVICES;
+    const dir = join(process.env.TMPDIR || tmpdir(), 'coda-host-sim');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const spec = join(dir, `${randomUUID()}.json`);
+    writeFileSync(spec, JSON.stringify({ argv, cwd: process.cwd(), env, kind }), { mode: 0o600 });
+    follow(['coda-run', 'run-on-device', `spec=${spec}`, `device=${kind}`, `label=${argv.join(' ').slice(0, 200)}`], session(),
+      code => { if (code !== null && code !== 75) rmSync(spec, { force: true }); });
+  }
+} else if (command === 'check' && held) {
+  process.stderr.write(`host-sim：在借到的测试机 ${kind} 上\n`);
+} else if (!['run', 'check'].includes(command)) {
+  fail(`用法：host-sim run --kind ${kind} -- <命令>，或在借到的测试机上用 check`, 2);
+} else if (thread) {
+  fail(`不在测试机 ${kind} 里：先用 host-sim run --kind ${kind} -- <命令>`, 1);
+} else if (process.env.CODA_GROUPS !== undefined) {
+  fail(`这一步没有占着组 ${group}：测试机调用能力 use-testbed`, 1);
+} else {
+  fail('只能在 Coda 的会话或流程步骤里用：测试机由 Coda 借出，终端里直接运行不借，也不执行', 1);
+}
+
+// Runs it in the foreground, ending as it ends; a signal to this process goes on to it (coda-run then lets the run go on).
+// `ended` is told its exit code first: 127 when it could not be started, null when a signal ended it.
+function follow([program, ...rest], env, ended = () => {}) {
+  const child = spawn(program, rest, { stdio: 'inherit', env });
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+  child.on('error', error => { ended(127); fail(error.message, 127); });
+  child.on('close', (code, signal) => { ended(code); process.exit(code ?? 128 + (system.signals[signal] ?? 0)); });
+}
+function fail(message, code) { process.stderr.write(`host-sim：${message}\n`); process.exit(code); }

package/scripts/panel.mjs

@@ -0,0 +1,28 @@
+// The test devices plugged into this Mac as a panel (README.md): each one registered here
+// (scripts/registry.mjs), with who has it — its group device:<name>, as Coda says it is now (`CODA_GROUPS_STATE`) — and who
+// waits. No device registered, nothing to show.
+import { devices } from './registry.mjs';
+
+const { now, groups } = JSON.parse(process.env.CODA_GROUPS_STATE || '{"groups":[]}');
+let list;
+try { list = devices(); } catch (error) {
+  console.log(JSON.stringify({ items: [{ type: 'error', text: error.message.slice(0, 200) }] })); process.exit(0);
+}
+
+const clip = (text, n = 80) => text.length > n ? `${text.slice(0, n - 1)}…` : text;
+const minutes = since => { const m = Math.max(0, Math.floor((now - since) / 60_000)); return m < 1 ? '不到 1 分钟' : m < 60 ? `${m} 分钟` : `${Math.floor(m / 60)} 小时 ${m % 60} 分钟`; };
+const who = x => clip(`${x.title || x.workflow}${x.thread ? ` · ${x.thread}` : ''}`);
+
+const items = list.filter(d => d && typeof d.id === 'string').slice(0, 20).map(device => {
+  const group = groups.find(g => g.name === `device:${device.id}`) ?? { holders: [], queue: [] };
+  const rows = [];
+  // The use that holds it first; commands a session borrowed it for after.
+  const holders = [...group.holders].sort((a, b) => a.borrowed - b.borrowed || a.since - b.since);
+  if (!holders.length) rows.push({ type: 'stat', label: '状态', value: '空闲' });
+  for (const h of holders.slice(0, 8))
+    rows.push({ type: 'stat', label: who(h), value: clip(h.leaving ? `正在收尾，${minutes(h.since)}` : h.borrowed ? `会话借用 ${minutes(h.since)}` : `使用中 ${minutes(h.since)}`) });
+  for (const [i, w] of group.queue.slice(0, 8).entries())
+    rows.push({ type: 'stat', label: who(w), value: `排第 ${i + 1} 位，等了 ${minutes(w.since)}` });
+  return { type: 'card', title: clip(device.name || device.id, 40), subtitle: clip(device.id), items: rows };
+});
+console.log(JSON.stringify({ items }));

package/scripts/registry.mjs

@@ -0,0 +1,26 @@
+// Devices belong to the instance whose plugin state contains their devices.json registration.
+// The plugin publishes ownership declarations to the space; callers missing a local id query group-owner.
+// An unreadable registration must not revoke existing declarations; only a valid empty array does.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const file = process.env.CODA_PLUGIN_STATE && join(process.env.CODA_PLUGIN_STATE, 'devices.json');
+export function devices(path = file, { missingIsEmpty = true } = {}) {
+  let list;
+  try { list = JSON.parse(readFileSync(path, 'utf8')); } catch (error) {
+    if (missingIsEmpty && error.code === 'ENOENT') return [];
+    throw new Error(`读不了设备登记 ${path}：${error.message}`);
+  }
+  if (!Array.isArray(list)) throw new Error(`设备登记 ${path} 须为设备数组`);
+  for (const device of list) {
+    if (typeof device?.udid !== 'string' || !device.udid)
+      throw new Error(`设备登记 ${path} 须有非空 udid`);
+  }
+  // A device is held by the group of its name: one device under two names would be held twice, one name twice either device.
+  for (const key of ['id', 'udid']) {
+    const values = list.map(d => d?.[key]).filter(Boolean);
+    const twice = [...new Set(values.filter((value, i) => values.indexOf(value) !== i))];
+    if (twice.length) throw new Error(`设备登记 ${path} 里 ${key} 重复：${twice.join('、')}`);
+  }
+  return list;
+}

package/scripts/resolve-device.mjs

@@ -0,0 +1,12 @@
+// Local registration is authoritative here; otherwise read the owner's published attributes.
+import { execFileSync } from 'node:child_process';
+import { devices } from './registry.mjs';
+
+export function resolveDevice(id) {
+  const list = devices();
+  const local = list.find(device => device.id === id);
+  if (local) return local;
+  const owner = JSON.parse(execFileSync('coda-resources', ['group-owner', `device:${id}`], { encoding: 'utf8' }));
+  if (owner) return { id, ...owner.attributes };
+  throw new Error(`没有这台测试机 ${id}；本地可用：${list.map(device => device.id).join('、') || '无'}`);
+}

package/scripts/run-on-device.mjs

@@ -0,0 +1,23 @@
+// The step of 在测试机上执行 that runs the command a session's host-sim handed over for a test device (scripts/host-sim.mjs),
+// once the device is lent to it: in the session's directory, with the session's environment, as if host-sim had run it
+// there. Its commands see the device as theirs (`HOST_SIM_LEASE`), so that a project script calling host-sim again for
+// it inside runs at once. The command's exit status is the step's output `exit_code`; the step itself succeeds, so that
+// the status reaches host-sim as the command gave it.
+import { spawn } from 'node:child_process';
+import { appendFileSync, readFileSync, rmSync } from 'node:fs';
+import { constants } from 'node:os';
+
+const spec = JSON.parse(readFileSync(process.env.SPEC, 'utf8'));
+rmSync(process.env.SPEC, { force: true });
+const env = { ...spec.env, HOST_SIM_LEASE: `coda-run:${spec.kind}` };
+const child = spawn(spec.argv[0], spec.argv.slice(1), { cwd: spec.cwd, env, stdio: 'inherit' });
+let ending = false;
+// Cancelled (its task over, say): the step's process group is asked to stop, the command with it.
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => { ending = true; });
+child.on('error', error => { process.stderr.write(`执行不了：${error.message}\n`); done(127); });
+child.on('close', (code, signal) => done(code ?? 128 + (constants.signals[signal] ?? 0)));
+
+function done(status) {
+  appendFileSync(process.env.GITHUB_OUTPUT, `exit_code=${status}\n`);
+  process.exit(ending ? 143 : 0);
+}

package/skills/testbed/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: testbed
+description: 测试机插件怎么用：会话或流程里用 use-testbed 排到 iPhone/iPad 测试机、按需装 App、拿到任务后用 host-sim run --kind <设备名> 操作并用 workflow_task 答复；流程里 callActivity 的写法与输出。要在真机上操作、验证或写真机验收流程时读。
+---
+
+# 测试机
+
+测试机（`iphone-testbed`、`ipad-testbed` 这类设备）需要会话操作时经能力 `use-testbed` 使用：它排进设备的并发组 `device:<设备名>`，
+按需装 App，把任务交给发起的会话；答复、出错或运行被取消后，先等会话借设备还在跑的命令停下，再切黑屏、交出设备。
+
+登记在哪个实例就归哪个实例，`devices.json` 是归属的唯一事实来源。空间里同一设备只能登记一次，同名或相同 UDID 的重复登记会使占用失败并报冲突。任何实例的会话都能用，在归属实例排队。
+安装、会话的 host-sim 命令和切黑屏在发起的 Mac 上跑；这台 Mac 须与设备配对，跑 XCTest 还须有本机 runner。
+
+## 会话里
+
+1. 调用 `workflow_run`，`workflow` 为 `use-testbed`，`inputs` 给 `device`（设备名）和 `instructions`（要做什么、怎么答复）；
+   先装 App 就再给 `app`（`.app` 或 `.ipa` 的绝对路径），`task` 是任务名（默认「在测试机上验证」）。
+2. 排到后你会收到任务：用 `host-sim run --kind <设备名> -- <命令>` 操作设备（如 `xcrun devicectl …`）。
+   只有正在做这台设备任务的会话（含子会话）借得到，别的时候立刻拒绝、不排队。
+3. 做完用 `workflow_task` 答复；答复后还在跑的借用命令随之停下。
+
+## 流程里
+
+先在自己的步骤构建、签名，把产物放进 `$CODA_ARTIFACTS`，再调用它：
+
+```xml
+<callActivity id="verify" name="真机验证" calledElement="use-testbed">
+  <extensionElements>
+    <coda:param name="device" value="iphone-testbed" />
+    <coda:param name="app" value="=sign.app" />
+    <coda:param name="instructions" value="打开 App，走一遍登录，截图确认没有报错。" />
+  </extensionElements>
+</callActivity>
+```
+
+任务的答复是这一步的输出：`=verify.result`、`.note`、`.choice`。被拒绝、出错或被取消时这一步抛出 `CALL_FAILED`，用出错边界事件接住做自己的收尾。
+
+无需会话操作但需要独占设备的流程（如预览版直装、开发流程的设备验收），可自行用 `hold-group device:<id>`（capacity 1）占一段，由引擎到归属实例排队，测试机会话排在它后面；流程负责自己的操作与收尾。