minimal-agent 0.10.0 → 0.12.0

package/plugins/computer_use/src/commands.js

@@ -0,0 +1,91 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/commands.ts —— /computeruse 子命令分发
+ * ------------------------------------------------------------
+ *  全部确定性执行，不经过 LLM。命令是给**人**用的诊断与知识管理入口；
+ *  真正操作桌面是模型调 `ComputerUse` 工具的事。
+ *
+ *  这条分界线是本插件的设计前提：说明书的**强制消费点在工具层**，因为模型
+ *  在任意一轮直接调工具，根本不会经过这里（非 `/` 输入直通 runQuery）。
+ *  把强制逻辑写进命令 = 只在用户敲斜杠时才生效的安全机制。
+ * ============================================================
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { computerUseDiagnostics, readComputerUseTelemetryReport, readRecentComputerUseAudit, } from '../../../src/plugin-sdk.js';
+import { runCapture } from './capture.js';
+import { runVerify } from './verify.js';
+import { runDoctor, runObserve, runStatus } from './daemon.js';
+import { runApp, runApps } from './manuals.js';
+export async function handleComputerUseCommand(args, signal) {
+    const parts = args.trim().split(/\s+/).filter(Boolean);
+    const sub = (parts[0] ?? '').toLowerCase();
+    const rest = parts.slice(1).join(' ');
+    switch (sub) {
+        case '':
+            return runStatus(signal);
+        case 'doctor':
+            return runDoctor(signal);
+        case 'apps':
+            return runApps(signal);
+        case 'app':
+            return runApp(rest);
+        case 'observe':
+            return runObserve(signal);
+        case 'verify':
+            return runVerify(rest, signal);
+        case 'capture':
+            return runCapture(rest, signal);
+        case 'report':
+            return readComputerUseTelemetryReport();
+        case 'audit':
+            return renderAudit(rest);
+        default:
+            return [
+                `未知子命令：${sub}`,
+                '',
+                '可用：（空）· doctor · apps · app <name> · capture [name] [--write] · verify <app> · observe · report · audit [n]',
+            ].join('\n');
+    }
+}
+/**
+ * 两份记录**并排显示，不合并**：
+ *   - `audit.jsonl` 由守护进程拥有与写入（动作级流水）
+ *   - `authorizations.jsonl` 由 TS 侧写（不可逆动作的人工批准结局）
+ * 合并会让人以为它们出自同一条链路、有同一套保证。它们没有。
+ */
+async function renderAudit(arg) {
+    const parsed = Number.parseInt(arg, 10);
+    const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 10;
+    const entries = await readRecentComputerUseAudit(limit).catch((error) => {
+        return [`读取审计失败：${error instanceof Error ? error.message : String(error)}`];
+    });
+    return [
+        `# Computer Use 审计（最近 ${limit} 条）`,
+        '',
+        '## 守护进程动作流水（audit.jsonl）',
+        ...(entries.length > 0 ? entries.map((line) => `- ${line}`) : ['（还没有记录）']),
+        '',
+        '## 不可逆动作授权（authorizations.jsonl，TS 侧）',
+        ...(await readAuthorizations(limit)),
+    ].join('\n');
+}
+async function readAuthorizations(limit) {
+    const path = join(computerUseDiagnostics.stateDir(), 'authorizations.jsonl');
+    const raw = await readFile(path, 'utf8').catch(() => '');
+    const lines = raw.split(/\r?\n/).filter(Boolean).slice(-limit);
+    if (lines.length === 0)
+        return ['（还没有记录）'];
+    return lines.map((line) => {
+        try {
+            const record = JSON.parse(line);
+            const time = typeof record.t === 'number'
+                ? new Date(record.t).toLocaleString()
+                : '未知时间';
+            return `- ${time} · ${record.decision} · ${record.appId} · ${record.actionClass} · ${record.surface}`;
+        }
+        catch {
+            return '- 无法解析的授权记录';
+        }
+    });
+}

package/plugins/computer_use/src/commands.ts

@@ -0,0 +1,103 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/commands.ts —— /computeruse 子命令分发
+ * ------------------------------------------------------------
+ *  全部确定性执行，不经过 LLM。命令是给**人**用的诊断与知识管理入口；
+ *  真正操作桌面是模型调 `ComputerUse` 工具的事。
+ *
+ *  这条分界线是本插件的设计前提：说明书的**强制消费点在工具层**，因为模型
+ *  在任意一轮直接调工具，根本不会经过这里（非 `/` 输入直通 runQuery）。
+ *  把强制逻辑写进命令 = 只在用户敲斜杠时才生效的安全机制。
+ * ============================================================
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import {
+  computerUseDiagnostics,
+  readComputerUseTelemetryReport,
+  readRecentComputerUseAudit,
+} from '../../../src/plugin-sdk.js';
+
+import { runCapture } from './capture.js';
+import { runVerify } from './verify.js';
+import { runDoctor, runObserve, runStatus } from './daemon.js';
+import { runApp, runApps } from './manuals.js';
+
+export async function handleComputerUseCommand(
+  args: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  const sub = (parts[0] ?? '').toLowerCase();
+  const rest = parts.slice(1).join(' ');
+
+  switch (sub) {
+    case '':
+      return runStatus(signal);
+    case 'doctor':
+      return runDoctor(signal);
+    case 'apps':
+      return runApps(signal);
+    case 'app':
+      return runApp(rest);
+    case 'observe':
+      return runObserve(signal);
+    case 'verify':
+      return runVerify(rest, signal);
+    case 'capture':
+      return runCapture(rest, signal);
+    case 'report':
+      return readComputerUseTelemetryReport();
+    case 'audit':
+      return renderAudit(rest);
+    default:
+      return [
+        `未知子命令：${sub}`,
+        '',
+        '可用：（空）· doctor · apps · app <name> · capture [name] [--write] · verify <app> · observe · report · audit [n]',
+      ].join('\n');
+  }
+}
+
+/**
+ * 两份记录**并排显示，不合并**：
+ *   - `audit.jsonl` 由守护进程拥有与写入（动作级流水）
+ *   - `authorizations.jsonl` 由 TS 侧写（不可逆动作的人工批准结局）
+ * 合并会让人以为它们出自同一条链路、有同一套保证。它们没有。
+ */
+async function renderAudit(arg: string): Promise<string> {
+  const parsed = Number.parseInt(arg, 10);
+  const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 10;
+  const entries = await readRecentComputerUseAudit(limit).catch((error: unknown) => {
+    return [`读取审计失败：${error instanceof Error ? error.message : String(error)}`];
+  });
+  return [
+    `# Computer Use 审计（最近 ${limit} 条）`,
+    '',
+    '## 守护进程动作流水（audit.jsonl）',
+    ...(entries.length > 0 ? entries.map((line) => `- ${line}`) : ['（还没有记录）']),
+    '',
+    '## 不可逆动作授权（authorizations.jsonl，TS 侧）',
+    ...(await readAuthorizations(limit)),
+  ].join('\n');
+}
+
+async function readAuthorizations(limit: number): Promise<string[]> {
+  const path = join(computerUseDiagnostics.stateDir(), 'authorizations.jsonl');
+  const raw = await readFile(path, 'utf8').catch(() => '');
+  const lines = raw.split(/\r?\n/).filter(Boolean).slice(-limit);
+  if (lines.length === 0) return ['（还没有记录）'];
+  return lines.map((line) => {
+    try {
+      const record = JSON.parse(line) as Record<string, unknown>;
+      const time = typeof record.t === 'number'
+        ? new Date(record.t).toLocaleString()
+        : '未知时间';
+      return `- ${time} · ${record.decision} · ${record.appId} · ${record.actionClass} · ${record.surface}`;
+    } catch {
+      return '- 无法解析的授权记录';
+    }
+  });
+}

package/plugins/computer_use/src/daemon.js

@@ -0,0 +1,134 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/daemon.ts —— 与守护进程打交道的确定性命令
+ * ------------------------------------------------------------
+ *  全部经内核的 `computerUseDiagnostics` 只读门面。插件**拿不到**动作派发能力
+ *  ——不是靠这里自觉不调用，而是门面根本没有那个方法（见 diagnostics.ts 头注）。
+ * ============================================================
+ */
+import { computerUseDiagnostics, describeCapabilities, } from '../../../src/plugin-sdk.js';
+/** 平台不支持时统一的一段话。分开写是因为它不是「出错」，是「本来就没有」。 */
+function unsupportedNote() {
+    return [
+        `⚠️ 当前平台是 ${process.platform}，Computer Use 只支持 macOS。`,
+        'Windows 侧只有协议桩，没有 UI Automation 驱动 —— 不是「装一下就能用」。',
+    ].join('\n');
+}
+function describeError(response) {
+    return `❌ ${response.error?.code ?? 'failed'}: ${response.error?.message ?? '未知错误'}`
+        + (response.error?.hint ? `\n   ${response.error.hint}` : '');
+}
+export async function runStatus(signal) {
+    const lines = ['# Computer Use 状态', ''];
+    if (!computerUseDiagnostics.platformSupported()) {
+        lines.push(unsupportedNote());
+        return lines.join('\n');
+    }
+    const helper = computerUseDiagnostics.helperPath();
+    lines.push(`守护进程二进制：${helper ?? '未找到（vendor/computer-use 缺失）'}`);
+    lines.push(`状态目录：${computerUseDiagnostics.stateDir()}`);
+    lines.push(`说明书写入目录：${computerUseDiagnostics.manualDir()}`);
+    if (!helper) {
+        lines.push('', '没有 helper 就没有一切。请确认 `vendor/computer-use/<平台>/cu-helperd` 存在。');
+        return lines.join('\n');
+    }
+    const hello = await computerUseDiagnostics.status(signal);
+    if (!hello.ok) {
+        lines.push('', describeError(hello));
+        return lines.join('\n');
+    }
+    const data = (hello.data ?? {});
+    lines.push(`服务版本：${data.serviceVersion ?? '未知'} · ${data.platform ?? '?'} / ${data.implementation ?? '?'}`, '', renderCapabilities(data.capabilities ?? []));
+    return lines.join('\n');
+}
+/**
+ * 能力清单按三态分组呈现。映射来自内核的 `capabilityLabels.ts`，与 Desktop
+ * 面板**共用同一份** —— 两边各自解析字符串前缀是上一版的漂移来源。
+ */
+function renderCapabilities(ids) {
+    if (ids.length === 0)
+        return '## 能力\n\n驱动没有报告任何能力。';
+    const labels = describeCapabilities(ids);
+    const group = (state) => labels.filter((label) => label.state === state)
+        .map((label) => `- ${label.label}${label.reason ? ` —— ${label.reason}` : ''}`);
+    const supported = group('supported');
+    const disabled = group('deliberately-disabled');
+    const missing = group('not-implemented');
+    return [
+        '## 能力',
+        '',
+        '### 已支持',
+        ...(supported.length > 0 ? supported : ['- （无）']),
+        ...(disabled.length > 0 ? ['', '### 有意禁用（不是缺口，是决定）', ...disabled] : []),
+        ...(missing.length > 0 ? ['', '### 尚未实现', ...missing] : []),
+    ].join('\n');
+}
+const PERMISSION_LABEL = {
+    screenCapture: '屏幕录制',
+    accessibility: '辅助功能',
+    inputControl: '输入控制',
+    ocr: 'OCR',
+};
+/**
+ * 权限体检。每一项都给出**能照着做的**下一步，而不是只报一个状态词 ——
+ * 「denied」对用户来说不是信息，「去哪个开关里把它打开」才是。
+ */
+export async function runDoctor(signal) {
+    if (!computerUseDiagnostics.platformSupported())
+        return unsupportedNote();
+    const response = await computerUseDiagnostics.permissions(signal);
+    if (!response.ok) {
+        return ['# Computer Use 权限体检', '', describeError(response)].join('\n');
+    }
+    const snapshot = (response.data ?? {});
+    const lines = ['# Computer Use 权限体检', ''];
+    let blocked = 0;
+    for (const [key, label] of Object.entries(PERMISSION_LABEL)) {
+        const state = snapshot[key] ?? 'unknown';
+        const ok = state === 'granted';
+        if (!ok && key !== 'ocr')
+            blocked += 1;
+        lines.push(`${ok ? '✅' : state === 'unsupported' ? '➖' : '❌'} ${label}：${state}`);
+        if (!ok && key === 'screenCapture') {
+            lines.push('   系统设置 → 隐私与安全性 → 屏幕录制，勾选本应用后**需要重启应用**。');
+        }
+        if (!ok && key === 'accessibility') {
+            lines.push('   系统设置 → 隐私与安全性 → 辅助功能。没有它就拿不到控件树，只能看像素。');
+        }
+        if (!ok && key === 'inputControl') {
+            lines.push('   输入控制随辅助功能一起授予；仍为 denied 时把本应用从列表里删掉再重新添加。');
+        }
+        if (key === 'ocr' && state !== 'granted') {
+            lines.push('   OCR 是**有意不实现**的（见 SPEC），这里不是故障。');
+        }
+    }
+    lines.push('', blocked === 0
+        ? '权限齐全。'
+        : `有 ${blocked} 项关键权限未就绪，Computer Use 会退化或直接失败。`);
+    return lines.join('\n');
+}
+/** 跑一次观测并把结果**给人看**（不进模型上下文，所以不组装图）。 */
+export async function runObserve(signal) {
+    if (!computerUseDiagnostics.platformSupported())
+        return unsupportedNote();
+    const response = await computerUseDiagnostics.observe(signal);
+    if (!response.ok || !response.state) {
+        return ['# 一次观测', '', describeError(response)].join('\n');
+    }
+    const state = response.state;
+    const lines = [
+        '# 一次观测',
+        '',
+        `前台应用：${state.activeApp?.name ?? '未知'}（${state.activeApp?.id ?? '无标识'}）`,
+        `显示器：${state.displays.length} 台 · 窗口：${state.windows.length} 个`,
+        `无障碍树：${state.accessibility ? (state.accessibility.truncated ? '不完整（权限不足或元素过多）' : '可用') : '无'}`,
+        `revision ${state.revision} · epoch ${state.epoch} · backend ${state.backend}`,
+    ];
+    if (state.windows.length > 0) {
+        lines.push('', '## 窗口');
+        for (const window of state.windows.slice(0, 10)) {
+            lines.push(`- ${window.title ?? '(无标题)'} — ${window.appId}`);
+        }
+    }
+    return lines.join('\n');
+}

package/plugins/computer_use/src/daemon.ts

@@ -0,0 +1,161 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/daemon.ts —— 与守护进程打交道的确定性命令
+ * ------------------------------------------------------------
+ *  全部经内核的 `computerUseDiagnostics` 只读门面。插件**拿不到**动作派发能力
+ *  ——不是靠这里自觉不调用，而是门面根本没有那个方法（见 diagnostics.ts 头注）。
+ * ============================================================
+ */
+
+import {
+  computerUseDiagnostics,
+  describeCapabilities,
+  type ComputerUseResponse,
+} from '../../../src/plugin-sdk.js';
+
+/** 平台不支持时统一的一段话。分开写是因为它不是「出错」，是「本来就没有」。 */
+function unsupportedNote(): string {
+  return [
+    `⚠️ 当前平台是 ${process.platform}，Computer Use 只支持 macOS。`,
+    'Windows 侧只有协议桩，没有 UI Automation 驱动 —— 不是「装一下就能用」。',
+  ].join('\n');
+}
+
+function describeError(response: ComputerUseResponse): string {
+  return `❌ ${response.error?.code ?? 'failed'}: ${response.error?.message ?? '未知错误'}`
+    + (response.error?.hint ? `\n   ${response.error.hint}` : '');
+}
+
+export async function runStatus(signal?: AbortSignal): Promise<string> {
+  const lines = ['# Computer Use 状态', ''];
+  if (!computerUseDiagnostics.platformSupported()) {
+    lines.push(unsupportedNote());
+    return lines.join('\n');
+  }
+
+  const helper = computerUseDiagnostics.helperPath();
+  lines.push(`守护进程二进制：${helper ?? '未找到（vendor/computer-use 缺失）'}`);
+  lines.push(`状态目录：${computerUseDiagnostics.stateDir()}`);
+  lines.push(`说明书写入目录：${computerUseDiagnostics.manualDir()}`);
+
+  if (!helper) {
+    lines.push('', '没有 helper 就没有一切。请确认 `vendor/computer-use/<平台>/cu-helperd` 存在。');
+    return lines.join('\n');
+  }
+
+  const hello = await computerUseDiagnostics.status(signal);
+  if (!hello.ok) {
+    lines.push('', describeError(hello));
+    return lines.join('\n');
+  }
+  const data = (hello.data ?? {}) as {
+    serviceVersion?: string;
+    platform?: string;
+    implementation?: string;
+    capabilities?: string[];
+  };
+  lines.push(
+    `服务版本：${data.serviceVersion ?? '未知'} · ${data.platform ?? '?'} / ${data.implementation ?? '?'}`,
+    '',
+    renderCapabilities(data.capabilities ?? []),
+  );
+  return lines.join('\n');
+}
+
+/**
+ * 能力清单按三态分组呈现。映射来自内核的 `capabilityLabels.ts`，与 Desktop
+ * 面板**共用同一份** —— 两边各自解析字符串前缀是上一版的漂移来源。
+ */
+function renderCapabilities(ids: string[]): string {
+  if (ids.length === 0) return '## 能力\n\n驱动没有报告任何能力。';
+  const labels = describeCapabilities(ids);
+  const group = (state: string): string[] =>
+    labels.filter((label) => label.state === state)
+      .map((label) => `- ${label.label}${label.reason ? ` —— ${label.reason}` : ''}`);
+
+  const supported = group('supported');
+  const disabled = group('deliberately-disabled');
+  const missing = group('not-implemented');
+
+  return [
+    '## 能力',
+    '',
+    '### 已支持',
+    ...(supported.length > 0 ? supported : ['- （无）']),
+    ...(disabled.length > 0 ? ['', '### 有意禁用（不是缺口，是决定）', ...disabled] : []),
+    ...(missing.length > 0 ? ['', '### 尚未实现', ...missing] : []),
+  ].join('\n');
+}
+
+const PERMISSION_LABEL: Record<string, string> = {
+  screenCapture: '屏幕录制',
+  accessibility: '辅助功能',
+  inputControl: '输入控制',
+  ocr: 'OCR',
+};
+
+/**
+ * 权限体检。每一项都给出**能照着做的**下一步，而不是只报一个状态词 ——
+ * 「denied」对用户来说不是信息，「去哪个开关里把它打开」才是。
+ */
+export async function runDoctor(signal?: AbortSignal): Promise<string> {
+  if (!computerUseDiagnostics.platformSupported()) return unsupportedNote();
+
+  const response = await computerUseDiagnostics.permissions(signal);
+  if (!response.ok) {
+    return ['# Computer Use 权限体检', '', describeError(response)].join('\n');
+  }
+  const snapshot = (response.data ?? {}) as Record<string, string>;
+  const lines = ['# Computer Use 权限体检', ''];
+  let blocked = 0;
+
+  for (const [key, label] of Object.entries(PERMISSION_LABEL)) {
+    const state = snapshot[key] ?? 'unknown';
+    const ok = state === 'granted';
+    if (!ok && key !== 'ocr') blocked += 1;
+    lines.push(`${ok ? '✅' : state === 'unsupported' ? '➖' : '❌'} ${label}：${state}`);
+    if (!ok && key === 'screenCapture') {
+      lines.push('   系统设置 → 隐私与安全性 → 屏幕录制，勾选本应用后**需要重启应用**。');
+    }
+    if (!ok && key === 'accessibility') {
+      lines.push('   系统设置 → 隐私与安全性 → 辅助功能。没有它就拿不到控件树，只能看像素。');
+    }
+    if (!ok && key === 'inputControl') {
+      lines.push('   输入控制随辅助功能一起授予；仍为 denied 时把本应用从列表里删掉再重新添加。');
+    }
+    if (key === 'ocr' && state !== 'granted') {
+      lines.push('   OCR 是**有意不实现**的（见 SPEC），这里不是故障。');
+    }
+  }
+
+  lines.push('', blocked === 0
+    ? '权限齐全。'
+    : `有 ${blocked} 项关键权限未就绪，Computer Use 会退化或直接失败。`);
+  return lines.join('\n');
+}
+
+/** 跑一次观测并把结果**给人看**（不进模型上下文，所以不组装图）。 */
+export async function runObserve(signal?: AbortSignal): Promise<string> {
+  if (!computerUseDiagnostics.platformSupported()) return unsupportedNote();
+
+  const response = await computerUseDiagnostics.observe(signal);
+  if (!response.ok || !response.state) {
+    return ['# 一次观测', '', describeError(response)].join('\n');
+  }
+  const state = response.state;
+  const lines = [
+    '# 一次观测',
+    '',
+    `前台应用：${state.activeApp?.name ?? '未知'}（${state.activeApp?.id ?? '无标识'}）`,
+    `显示器：${state.displays.length} 台 · 窗口：${state.windows.length} 个`,
+    `无障碍树：${state.accessibility ? (state.accessibility.truncated ? '不完整（权限不足或元素过多）' : '可用') : '无'}`,
+    `revision ${state.revision} · epoch ${state.epoch} · backend ${state.backend}`,
+  ];
+  if (state.windows.length > 0) {
+    lines.push('', '## 窗口');
+    for (const window of state.windows.slice(0, 10)) {
+      lines.push(`- ${window.title ?? '(无标题)'} — ${window.appId}`);
+    }
+  }
+  return lines.join('\n');
+}

package/plugins/computer_use/src/manuals.js

@@ -0,0 +1,135 @@
+/**
+ * ============================================================
+ *  plugins/computer_use/src/manuals.ts —— 应用说明书的清单与详情
+ * ------------------------------------------------------------
+ *  说明书文件住在本插件的 `app/`，但**解析与匹配**用内核的
+ *  `vision/appGuide.ts` —— 内核工具在每次观测时也用同一份逻辑，两边必须
+ *  是同一套判断，否则 `/computeruse apps` 说"命中了"而模型那边没命中。
+ * ============================================================
+ */
+import { computerUseDiagnostics, describeMatch, EMPTY_MANUAL, loadAllAppManuals, matchGuide, validateManual, } from '../../../src/plugin-sdk.js';
+/** 全部说明书 + 冲突报告。与内核工具用**同一个**加载器，不另写一份。 */
+export async function loadAllManuals() {
+    return loadAllAppManuals();
+}
+/** 当前前台应用身份。拿不到就返回 undefined —— 不猜。 */
+async function foregroundIdentity(signal) {
+    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) {
+    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) {
+    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');
+}