minimal-agent 0.10.0 → 0.12.0

package/plugins/computer_use/src/manuals.ts

@@ -0,0 +1,159 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/manuals.ts —— 应用说明书的清单与详情
+ * ------------------------------------------------------------
+ *  说明书文件住在本插件的 `app/`，但**解析与匹配**用内核的
+ *  `vision/appGuide.ts` —— 内核工具在每次观测时也用同一份逻辑，两边必须
+ *  是同一套判断，否则 `/computeruse apps` 说"命中了"而模型那边没命中。
+ * ============================================================
+ */
+
+import {
+  computerUseDiagnostics,
+  describeMatch,
+  EMPTY_MANUAL,
+  loadAllAppManuals,
+  matchGuide,
+  validateManual,
+  type LoadedManuals,
+} from '../../../src/plugin-sdk.js';
+
+/** 全部说明书 + 冲突报告。与内核工具用**同一个**加载器，不另写一份。 */
+export async function loadAllManuals(): Promise<LoadedManuals> {
+  return loadAllAppManuals();
+}
+
+/** 当前前台应用身份。拿不到就返回 undefined —— 不猜。 */
+async function foregroundIdentity(
+  signal?: AbortSignal,
+): Promise<{ id?: string; name?: string } | undefined> {
+  if (!computerUseDiagnostics.platformSupported()) return undefined;
+  const response = await computerUseDiagnostics.observe(signal).catch(() => null);
+  if (!response?.ok || !response.state?.activeApp) return undefined;
+  return { id: response.state.activeApp.id, name: response.state.activeApp.name };
+}
+
+export async function runApps(signal?: AbortSignal): Promise<string> {
+  const { guides, conflicts, rejected } = await loadAllManuals();
+  const lines = ['# 应用说明书', ''];
+  if (guides.length === 0 && rejected.length === 0) {
+    lines.push(
+      '（一份都没有。工作区说明书放 `app-manuals/<app>.md`；',
+      '插件提供的要在 plugin.json 里声明 `"appManuals": "app"`。）',
+    );
+    return lines.join('\n');
+  }
+
+  for (const guide of guides) {
+    const identifiers = [...guide.bundleIds, ...guide.processNames, ...guide.displayNames];
+    lines.push(
+      `- **${guide.name}** — 匹配标识 ${identifiers.length} 个 · 不可逆声明 ${guide.irreversible.length} 条`,
+    );
+  }
+
+  // 被隔离的说明书必须可见，而且要说得出错在哪 —— 它们的失败方式全是静默的：
+  // match 写错就永远匹配不上、precondition 写错就永远不生效。不报出来，用户
+  // 会以为自己没写过这份说明书。
+  if (rejected.length > 0) {
+    lines.push('', '## ⛔ 已隔离（写错了，不会进入模型上下文）');
+    for (const item of rejected) {
+      lines.push(`- **${item.guide.name}** — ${item.guide.path}`);
+      for (const message of item.errors) lines.push(`  - ${message}`);
+    }
+  }
+
+  // 冲突必须可见：靠目录顺序决定「哪份知识生效」而没人知道，是最难查的那类问题。
+  if (conflicts.length > 0) {
+    lines.push('', '## ⚠️ 冲突');
+    for (const conflict of conflicts) {
+      lines.push(conflict.kind === 'same-name'
+        ? `- 同名说明书 \`${conflict.key}\`：生效 ${conflict.winner}，被遮蔽 ${conflict.shadowed}`
+        : `- 标识 \`${conflict.key}\` 被两份说明书同时认领：生效 ${conflict.winner}，被遮蔽 ${conflict.shadowed}`);
+    }
+  }
+
+  const identity = await foregroundIdentity(signal);
+  lines.push('', '## 当前前台应用');
+  if (!identity) {
+    lines.push('拿不到前台应用（平台不支持、权限未授予或守护进程不可用）。');
+  } else {
+    lines.push(`${identity.name ?? '未知'}（${identity.id ?? '无标识'}）`, '');
+    lines.push(describeMatch(matchGuide(guides, identity), guides, identity));
+  }
+  return lines.join('\n');
+}
+
+export async function runApp(name: string): Promise<string> {
+  const trimmed = name.trim();
+  if (!trimmed) return '用法：`/computeruse app <name>`（名字见 `/computeruse apps`）';
+
+  const { guides, rejected } = await loadAllManuals();
+  // 被隔离的那些也要能查 —— 用户最需要看详情的恰恰是写坏的那一份。
+  const blocked = rejected.find((item) => item.guide.name === trimmed);
+  const guide = guides.find((candidate) => candidate.name === trimmed) ?? blocked?.guide;
+  if (!guide) {
+    return [
+      `没有名为「${trimmed}」的说明书。`,
+      `已有：${guides.map((g) => g.name).join('、') || '（无）'}`,
+    ].join('\n');
+  }
+
+  const checkable = guide.irreversible.filter(
+    (entry) => entry.startsWith('key:') || entry.startsWith('region:'),
+  );
+  const manual = guide.manual ?? EMPTY_MANUAL;
+  const issues = validateManual({
+    manual,
+    irreversible: guide.irreversible,
+    identifiers: guide.bundleIds.length + guide.processNames.length + guide.displayNames.length,
+  });
+  const unverified = [
+    ...manual.layout.filter((r) => !r.verified).map((r) => `分区 ${r.id}`),
+    ...manual.controls.filter((c) => !c.verified).map((c) => `控件 ${c.id}`),
+    ...manual.flows.filter((f) => !f.verified).map((f) => `流程 ${f.id}`),
+  ];
+
+  return [
+    `# 说明书 ${guide.name}`,
+    '',
+    // 隔离状态放最前面：其它信息都建立在「它到底生不生效」之上。
+    ...(blocked
+      ? ['⛔ **已隔离**：这份说明书写错了，不会进入模型上下文。修完下面的 ❌ 才会生效。', '']
+      : []),
+    `文件：${guide.path}`,
+    `schema v${manual.schemaVersion}`,
+    `bundleId：${guide.bundleIds.join('、') || '（无）'}`,
+    `进程名：${guide.processNames.join('、') || '（无）'}`,
+    `显示名：${guide.displayNames.join('、') || '（无）'}`,
+    '',
+    '## 不可逆声明',
+    ...(guide.irreversible.length > 0
+      ? guide.irreversible.map((entry) => `- ${entry}`)
+      : ['（无）']),
+    '',
+    checkable.length > 0
+      ? `其中 ${checkable.length} 条是**引擎可独立验证**的（key/region）。`
+      : '⚠️ 全部是 `intent:` 形式 —— 只能靠模型自报，模型漏报就拦不住。'
+        + '等实机验证出稳定的按键或区域，改成 key:/region: 才是真拦截。',
+    '',
+    '## 结构化内容',
+    `分区 ${manual.layout.length} · 控件 ${manual.controls.length} · 流程 ${manual.flows.length}`,
+    ...manual.flows.map((flow) => {
+      const guarded = flow.steps.filter((s) => s.precondition).length;
+      return `- ${flow.id}：${flow.steps.length} 步`
+        + (guarded > 0 ? `，其中 ${guarded} 步有机器可检查的前置条件` : '，无前置条件');
+    }),
+    '',
+    '## 校验',
+    ...(issues.length > 0
+      ? issues.map((issue) => `${issue.level === 'error' ? '❌' : '⚠️'} ${issue.message}`)
+      : ['✅ 无问题']),
+    '',
+    '## 未验证条目',
+    // 未验证不是缺陷，是**状态**。说清楚才能知道哪些还得实机跑一遍；
+    // 不说，就等于把猜测当事实用。
+    unverified.length > 0
+      ? `${unverified.length} 项：${unverified.join('、')}`
+      : '（无 —— 所有结构化条目都已标记 verified）',
+  ].join('\n');
+}

package/plugins/computer_use/src/verify.js

@@ -0,0 +1,168 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/verify.ts —— 半自动实机验收
+ * ------------------------------------------------------------
+ *  为什么需要它：说明书里的流程目前全部 `verified: false` —— 它们是把面向人的
+ *  帮助文档转写成 agent 视角，**没有一条实机跑过**。而实机验收这件事我单方面
+ *  做不了：它会接管用户的屏幕、需要人在场判断「这一步到底成了没有」。
+ *
+ *  于是把它做成脚手架：逐步提示 → 人拍板 → 每步自动观测并记下**实际看到的** →
+ *  一条流程全过才把 `verified` 翻真。用户什么时候方便就跑一个 app，
+ *  结论可累积、可审计。
+ *
+ *  ★ 三条纪律：
+ *   ① **人说通过才算通过。** 观测只负责记录现场，不替人判断成败 —— 引擎看不出
+ *     「消息真的发给了张三」这种事。
+ *   ② **只翻全过的那条流程。** 任一步失败或跳过，整条保持 false 并记下卡在哪。
+ *     部分通过就翻真，等于把「大概能用」写成「已验证」。
+ *   ③ **写工作区，不动包内文件**（见 diagnostics.ts::saveVerification）。
+ *
+ *  问用户走 `executeTool('AskUserQuestion')` —— 与 workflow-runner 的 pause 同
+ *  一条通道，非交互宿主会自动选推荐项（这里推荐项是「停止」，见下）。
+ * ============================================================
+ */
+import { computerUseDiagnostics, executeTool, } from '../../../src/plugin-sdk.js';
+export async function runVerify(raw, signal) {
+    const name = raw.trim().split(/\s+/)[0] ?? '';
+    if (!name) {
+        return '用法：`/computeruse verify <app>`（名字见 `/computeruse apps`）\n'
+            + '它会逐步提示你操作、每步记录实际观测，全部通过才把该流程标记为已验证。';
+    }
+    if (!computerUseDiagnostics.platformSupported()) {
+        return `⚠️ 当前平台是 ${process.platform}，实机验收只能在 macOS 上做。`;
+    }
+    const source = await computerUseDiagnostics.readManualSource(name);
+    if (typeof source === 'string')
+        return `# 实机验收\n\n${source}`;
+    const flows = source.guide.manual?.flows ?? [];
+    if (flows.length === 0) {
+        return [
+            `# 实机验收：${name}`,
+            '',
+            '这份说明书没有声明任何 `flows:` —— 没有可验收的流程。',
+            '先用 `/computeruse capture` 采一份草稿，把流程补上，再回来验收。',
+        ].join('\n');
+    }
+    const records = [];
+    const verifiedFlows = [];
+    let aborted = false;
+    for (const flow of flows) {
+        if (aborted)
+            break;
+        if (flow.verified)
+            continue; // 已验证过的不重复折腾人
+        const outcome = await verifyFlow(flow, records, signal);
+        if (outcome === 'aborted') {
+            aborted = true;
+            break;
+        }
+        if (outcome === 'passed')
+            verifiedFlows.push(flow.id);
+    }
+    return renderResult({ source, flows, records, verifiedFlows, aborted, signal });
+}
+async function verifyFlow(flow, records, signal) {
+    let allPassed = flow.steps.length > 0;
+    for (const [index, step] of flow.steps.entries()) {
+        const verdict = await askStep(flow, index, step.do, signal);
+        const scene = await observeScene(signal);
+        records.push({ flowId: flow.id, index: index + 1, step: step.do, verdict, scene });
+        if (verdict === 'aborted')
+            return 'aborted';
+        if (verdict !== 'passed') {
+            allPassed = false;
+            // 一步没过，这条流程后面的步骤多半也无从谈起 —— 不再逐个折腾人。
+            break;
+        }
+    }
+    return allPassed ? 'passed' : 'failed';
+}
+async function askStep(flow, index, step, signal) {
+    const result = await executeTool('AskUserQuestion', JSON.stringify({
+        questions: [{
+                header: `验收 ${flow.id}`,
+                question: `【${flow.id} 第 ${index + 1}/${flow.steps.length} 步】${step}\n`
+                    + (flow.goal ? `（这条流程的目标：${flow.goal}）\n` : '')
+                    + '请你在真实应用里做这一步，然后告诉我结果。',
+                options: [
+                    // 首项是非交互宿主的自动兜底 —— 必须是「停止」：无人在场时不该
+                    // 产出一份「全部通过」的验收结论。
+                    { label: '停止验收', description: '结束本次验收，已记录的结果保留。' },
+                    { label: '做到了', description: '这一步按说明书描述完成了。' },
+                    { label: '跳过', description: '这一步这次不测（不算通过）。' },
+                    { label: '失败了', description: '照说明书做不出来 —— 说明书与实际不符。' },
+                ],
+            }],
+    }), signal);
+    if (!result.ok)
+        return 'aborted';
+    const label = String(result.content ?? '');
+    if (label.includes('做到了'))
+        return 'passed';
+    if (label.includes('跳过'))
+        return 'skipped';
+    if (label.includes('失败'))
+        return 'failed';
+    return 'aborted';
+}
+/** 记下这一步执行后**实际看到的**现场。观测失败也如实写，不留空。 */
+async function observeScene(signal) {
+    const response = await computerUseDiagnostics.observe(signal).catch(() => null);
+    if (!response?.ok || !response.state) {
+        return `观测失败（${response?.error?.code ?? 'unknown'}）`;
+    }
+    const state = response.state;
+    const windows = state.windows.map((w) => w.title ?? '(无标题)').slice(0, 3).join(' / ');
+    return [
+        `前台 ${state.activeApp?.name ?? '未知'}（${state.activeApp?.id ?? '无标识'}）`,
+        `窗口 ${windows || '无'}`,
+        `AX ${state.accessibility ? (state.accessibility.truncated ? '不完整' : '可用') : '无'}`,
+    ].join(' · ');
+}
+async function renderResult(input) {
+    const { source, records, verifiedFlows, aborted } = input;
+    const lines = [
+        `# 实机验收：${source.name}`,
+        '',
+        `说明书：${source.path}`,
+        aborted ? '⚠️ 验收被中止，下面只是已经走过的部分。' : '',
+        '',
+        '## 逐步结果',
+        '',
+    ].filter((line) => line !== '' || true);
+    if (records.length === 0) {
+        return [
+            `# 实机验收：${source.name}`,
+            '',
+            '没有可验收的流程 —— 声明的流程可能都已标记为已验证。',
+            '想重验请先把对应流程的 `verified` 改回 false。',
+        ].join('\n');
+    }
+    for (const record of records) {
+        const mark = record.verdict === 'passed' ? '✅'
+            : record.verdict === 'skipped' ? '⏭️'
+                : record.verdict === 'failed' ? '❌' : '⛔';
+        lines.push(`${mark} ${record.flowId} 第 ${record.index} 步：${record.step}`);
+        lines.push(`   实际观测：${record.scene}`);
+    }
+    lines.push('', '## 结论', '', verifiedFlows.length > 0
+        ? `全部通过、可标记为已验证的流程：${verifiedFlows.join('、')}`
+        : '没有任何流程全部通过 —— 保持未验证。');
+    const notes = buildNotes(records, verifiedFlows);
+    const written = await computerUseDiagnostics.saveVerification({ source, verifiedFlows, notes }, input.signal);
+    lines.push('', written.ok ? `✅ 已写入 ${written.path}` : `未写盘：${written.error}`);
+    if (!written.ok) {
+        lines.push('', '实测记录（可自己贴进说明书的 `## 实测记录` 一节）：', '', ...notes);
+    }
+    return lines.join('\n');
+}
+/** 追加进 `## 实测记录` 的行。带日期，因为「上次能用这次不能」本身是信息。 */
+function buildNotes(records, verifiedFlows) {
+    const day = new Date().toISOString().slice(0, 10);
+    const notes = [`- ${day} 实机验收：通过 ${verifiedFlows.join('、') || '（无）'}`];
+    for (const record of records.filter((item) => item.verdict !== 'passed')) {
+        notes.push(`  - ${record.flowId} 第 ${record.index} 步（${record.verdict}）：${record.step}`
+            + ` —— 当时 ${record.scene}`);
+    }
+    return notes;
+}

package/plugins/computer_use/src/verify.ts

@@ -0,0 +1,219 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/verify.ts —— 半自动实机验收
+ * ------------------------------------------------------------
+ *  为什么需要它：说明书里的流程目前全部 `verified: false` —— 它们是把面向人的
+ *  帮助文档转写成 agent 视角，**没有一条实机跑过**。而实机验收这件事我单方面
+ *  做不了：它会接管用户的屏幕、需要人在场判断「这一步到底成了没有」。
+ *
+ *  于是把它做成脚手架：逐步提示 → 人拍板 → 每步自动观测并记下**实际看到的** →
+ *  一条流程全过才把 `verified` 翻真。用户什么时候方便就跑一个 app，
+ *  结论可累积、可审计。
+ *
+ *  ★ 三条纪律：
+ *   ① **人说通过才算通过。** 观测只负责记录现场，不替人判断成败 —— 引擎看不出
+ *     「消息真的发给了张三」这种事。
+ *   ② **只翻全过的那条流程。** 任一步失败或跳过，整条保持 false 并记下卡在哪。
+ *     部分通过就翻真，等于把「大概能用」写成「已验证」。
+ *   ③ **写工作区，不动包内文件**（见 diagnostics.ts::saveVerification）。
+ *
+ *  问用户走 `executeTool('AskUserQuestion')` —— 与 workflow-runner 的 pause 同
+ *  一条通道，非交互宿主会自动选推荐项（这里推荐项是「停止」，见下）。
+ * ============================================================
+ */
+
+import {
+  computerUseDiagnostics,
+  executeTool,
+  type ManualFlow,
+  type ManualSource,
+} from '../../../src/plugin-sdk.js';
+
+/** 每步三选一。「跳过」与「失败」都不算通过 —— 只是记下来的理由不同。 */
+type StepVerdict = 'passed' | 'skipped' | 'failed' | 'aborted';
+
+interface StepRecord {
+  flowId: string;
+  index: number;
+  step: string;
+  verdict: StepVerdict;
+  /** 这一步执行时**实际看到的**现场。 */
+  scene: string;
+}
+
+export async function runVerify(raw: string, signal?: AbortSignal): Promise<string> {
+  const name = raw.trim().split(/\s+/)[0] ?? '';
+  if (!name) {
+    return '用法：`/computeruse verify <app>`（名字见 `/computeruse apps`）\n'
+      + '它会逐步提示你操作、每步记录实际观测，全部通过才把该流程标记为已验证。';
+  }
+  if (!computerUseDiagnostics.platformSupported()) {
+    return `⚠️ 当前平台是 ${process.platform}，实机验收只能在 macOS 上做。`;
+  }
+
+  const source = await computerUseDiagnostics.readManualSource(name);
+  if (typeof source === 'string') return `# 实机验收\n\n${source}`;
+
+  const flows = source.guide.manual?.flows ?? [];
+  if (flows.length === 0) {
+    return [
+      `# 实机验收：${name}`,
+      '',
+      '这份说明书没有声明任何 `flows:` —— 没有可验收的流程。',
+      '先用 `/computeruse capture` 采一份草稿，把流程补上，再回来验收。',
+    ].join('\n');
+  }
+
+  const records: StepRecord[] = [];
+  const verifiedFlows: string[] = [];
+  let aborted = false;
+
+  for (const flow of flows) {
+    if (aborted) break;
+    if (flow.verified) continue; // 已验证过的不重复折腾人
+    const outcome = await verifyFlow(flow, records, signal);
+    if (outcome === 'aborted') { aborted = true; break; }
+    if (outcome === 'passed') verifiedFlows.push(flow.id);
+  }
+
+  return renderResult({ source, flows, records, verifiedFlows, aborted, signal });
+}
+
+async function verifyFlow(
+  flow: ManualFlow,
+  records: StepRecord[],
+  signal?: AbortSignal,
+): Promise<'passed' | 'failed' | 'aborted'> {
+  let allPassed = flow.steps.length > 0;
+  for (const [index, step] of flow.steps.entries()) {
+    const verdict = await askStep(flow, index, step.do, signal);
+    const scene = await observeScene(signal);
+    records.push({ flowId: flow.id, index: index + 1, step: step.do, verdict, scene });
+    if (verdict === 'aborted') return 'aborted';
+    if (verdict !== 'passed') {
+      allPassed = false;
+      // 一步没过，这条流程后面的步骤多半也无从谈起 —— 不再逐个折腾人。
+      break;
+    }
+  }
+  return allPassed ? 'passed' : 'failed';
+}
+
+async function askStep(
+  flow: ManualFlow,
+  index: number,
+  step: string,
+  signal?: AbortSignal,
+): Promise<StepVerdict> {
+  const result = await executeTool(
+    'AskUserQuestion',
+    JSON.stringify({
+      questions: [{
+        header: `验收 ${flow.id}`,
+        question: `【${flow.id} 第 ${index + 1}/${flow.steps.length} 步】${step}\n`
+          + (flow.goal ? `（这条流程的目标：${flow.goal}）\n` : '')
+          + '请你在真实应用里做这一步，然后告诉我结果。',
+        options: [
+          // 首项是非交互宿主的自动兜底 —— 必须是「停止」：无人在场时不该
+          // 产出一份「全部通过」的验收结论。
+          { label: '停止验收', description: '结束本次验收，已记录的结果保留。' },
+          { label: '做到了', description: '这一步按说明书描述完成了。' },
+          { label: '跳过', description: '这一步这次不测（不算通过）。' },
+          { label: '失败了', description: '照说明书做不出来 —— 说明书与实际不符。' },
+        ],
+      }],
+    }),
+    signal,
+  );
+  if (!result.ok) return 'aborted';
+  const label = String(result.content ?? '');
+  if (label.includes('做到了')) return 'passed';
+  if (label.includes('跳过')) return 'skipped';
+  if (label.includes('失败')) return 'failed';
+  return 'aborted';
+}
+
+/** 记下这一步执行后**实际看到的**现场。观测失败也如实写，不留空。 */
+async function observeScene(signal?: AbortSignal): Promise<string> {
+  const response = await computerUseDiagnostics.observe(signal).catch(() => null);
+  if (!response?.ok || !response.state) {
+    return `观测失败（${response?.error?.code ?? 'unknown'}）`;
+  }
+  const state = response.state;
+  const windows = state.windows.map((w) => w.title ?? '(无标题)').slice(0, 3).join(' / ');
+  return [
+    `前台 ${state.activeApp?.name ?? '未知'}（${state.activeApp?.id ?? '无标识'}）`,
+    `窗口 ${windows || '无'}`,
+    `AX ${state.accessibility ? (state.accessibility.truncated ? '不完整' : '可用') : '无'}`,
+  ].join(' · ');
+}
+
+async function renderResult(input: {
+  source: ManualSource;
+  flows: ManualFlow[];
+  records: StepRecord[];
+  verifiedFlows: string[];
+  aborted: boolean;
+  signal?: AbortSignal;
+}): Promise<string> {
+  const { source, records, verifiedFlows, aborted } = input;
+  const lines = [
+    `# 实机验收：${source.name}`,
+    '',
+    `说明书：${source.path}`,
+    aborted ? '⚠️ 验收被中止，下面只是已经走过的部分。' : '',
+    '',
+    '## 逐步结果',
+    '',
+  ].filter((line) => line !== '' || true);
+
+  if (records.length === 0) {
+    return [
+      `# 实机验收：${source.name}`,
+      '',
+      '没有可验收的流程 —— 声明的流程可能都已标记为已验证。',
+      '想重验请先把对应流程的 `verified` 改回 false。',
+    ].join('\n');
+  }
+
+  for (const record of records) {
+    const mark = record.verdict === 'passed' ? '✅'
+      : record.verdict === 'skipped' ? '⏭️'
+        : record.verdict === 'failed' ? '❌' : '⛔';
+    lines.push(`${mark} ${record.flowId} 第 ${record.index} 步：${record.step}`);
+    lines.push(`   实际观测：${record.scene}`);
+  }
+
+  lines.push(
+    '',
+    '## 结论',
+    '',
+    verifiedFlows.length > 0
+      ? `全部通过、可标记为已验证的流程：${verifiedFlows.join('、')}`
+      : '没有任何流程全部通过 —— 保持未验证。',
+  );
+
+  const notes = buildNotes(records, verifiedFlows);
+  const written = await computerUseDiagnostics.saveVerification(
+    { source, verifiedFlows, notes },
+    input.signal,
+  );
+  lines.push('', written.ok ? `✅ 已写入 ${written.path}` : `未写盘：${written.error}`);
+  if (!written.ok) {
+    lines.push('', '实测记录（可自己贴进说明书的 `## 实测记录` 一节）：', '', ...notes);
+  }
+  return lines.join('\n');
+}
+
+/** 追加进 `## 实测记录` 的行。带日期，因为「上次能用这次不能」本身是信息。 */
+function buildNotes(records: StepRecord[], verifiedFlows: string[]): string[] {
+  const day = new Date().toISOString().slice(0, 10);
+  const notes = [`- ${day} 实机验收：通过 ${verifiedFlows.join('、') || '（无）'}`];
+  for (const record of records.filter((item) => item.verdict !== 'passed')) {
+    notes.push(
+      `  - ${record.flowId} 第 ${record.index} 步（${record.verdict}）：${record.step}`
+      + ` —— 当时 ${record.scene}`,
+    );
+  }
+  return notes;
+}

package/plugins/computer_use/test/commands.test.ts

@@ -0,0 +1,73 @@
+/**
+ * plugins/computer_use/test/commands.test.ts
+ *
+ * 守两件事：
+ *  ① `/computeruse` 与 `/cu` 都能路由到同一个 runCommand（别名不是摆设）
+ *  ② 命令面**只读**：不平台依赖的子命令在任何机器上都给出可读输出，
+ *     且不会因为拿不到守护进程就抛异常
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { initWorkingDir } from '../../../src/bootstrap/workingDir.js';
+
+initWorkingDir();
+
+const { handleComputerUseCommand } = await import('../src/commands.js');
+
+describe('computer-use 命令面', () => {
+  test('两个命令文件都存在 —— /cu 是声明出来的别名，不是隐式行为', () => {
+    const commands = readdirSync(join(import.meta.dir, '..', 'commands')).sort();
+    expect(commands).toEqual(['computeruse.md', 'cu.md']);
+  });
+
+  test('plugin.ts 对两个命令名都接管', async () => {
+    const api = (await import('../plugin.js')).default;
+    for (const name of ['computeruse', 'cu']) {
+      const events: unknown[] = [];
+      for await (const event of api.runCommand!(name, 'apps', {
+        provider: { baseURL: '', apiKey: '', model: '' } as never,
+        history: [],
+      })) {
+        events.push(event);
+      }
+      // 有实际输出，且以 turn_done 收尾（否则 UI 会一直等）
+      expect(events.length).toBeGreaterThan(1);
+      expect((events.at(-1) as { type: string }).type).toBe('turn_done');
+    }
+  });
+
+  test('未知子命令给出可用列表，而不是静默或抛错', async () => {
+    const out = await handleComputerUseCommand('nonsense');
+    expect(out).toContain('未知子命令');
+    expect(out).toContain('doctor');
+  });
+
+  test('apps 列出真实说明书，并如实报告拿不到前台应用', async () => {
+    const out = await handleComputerUseCommand('apps');
+    expect(out).toContain('wechat');
+    expect(out).toContain('当前前台应用');
+  });
+
+  test('app <name> 报告不可逆声明的可检查性 —— 不把 intent 说成拦截', async () => {
+    const out = await handleComputerUseCommand('app wechat');
+    // 显示的是**引擎实际用来匹配**的形式（loadGuides 统一小写化），
+    // 不是文件里的原始大小写 —— 诊断要照着引擎的眼睛看。
+    expect(out).toContain('com.tencent.xinwechat');
+    // 现状：微信的声明全是 intent 形式，必须如实说"拦不住"
+    expect(out).toContain('模型漏报就拦不住');
+  });
+
+  test('app 名字不存在时列出已有的，不静默', async () => {
+    const out = await handleComputerUseCommand('app 不存在的应用');
+    expect(out).toContain('已有：');
+    expect(out).toContain('finder');
+  });
+
+  test('report / audit 在没有任何记录时也不抛异常', async () => {
+    expect(typeof await handleComputerUseCommand('report')).toBe('string');
+    expect(await handleComputerUseCommand('audit 3')).toContain('最近 3 条');
+  });
+});

package/plugins/cron-runner/plugin.ts

@@ -0,0 +1,38 @@
+import type { PluginApi, PluginRuntimeContext } from '../../src/plugin-sdk.js';
+import { handleCronCommand } from './src/commands.js';
+import { Scheduler } from './src/scheduler.js';
+import { migrateCronTasks } from './src/store.js';
+
+let scheduler: Scheduler | null = null;
+let schedulerStop: Promise<void> | null = null;
+
+export function getCronScheduler(): Scheduler | null {
+  return scheduler;
+}
+
+const api: PluginApi = {
+  async activate(ctx: PluginRuntimeContext) {
+    await migrateCronTasks();
+    await scheduler?.stop();
+    await schedulerStop;
+    const instance = new Scheduler(ctx);
+    scheduler = instance;
+    instance.start();
+    return () => {
+      if (scheduler === instance) scheduler = null;
+      let tracked: Promise<void>;
+      tracked = instance.stop().finally(() => {
+        if (schedulerStop === tracked) schedulerStop = null;
+      });
+      schedulerStop = tracked;
+    };
+  },
+
+  async *runCommand(commandName, args) {
+    const text = await handleCronCommand(commandName, args, scheduler);
+    yield { type: 'text', delta: text };
+    yield { type: 'turn_done' };
+  },
+};
+
+export default api;