android-midscene-automation 0.1.43 → 0.2.2

package/server/analytics.test.ts

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { summarizeTests, type TestRun } from '../src/analytics/summary';
+
+test('analytics includes unrun and historical scripts and excludes stopped/running from pass rate and average duration', () => {
+  const runs: TestRun[] = ['passed', 'failed', 'stopped', 'running'].map((status, i) => ({
+    scriptId: 'a', scriptName: 'old name', status: status as TestRun['status'], startedAt: `2026-09-2${i}T00:00:00Z`, durationMs: 1000 * (i + 1),
+  }));
+  runs.push({ scriptId: 'deleted', scriptName: '历史测试', status: 'passed', startedAt: '2026-09-01T00:00:00Z', durationMs: 10 });
+  const result = summarizeTests([{ id: 'a', name: '新名称' }, { id: 'b', name: '未执行' }], runs);
+  assert.equal(result.scripts, 2);
+  assert.equal(result.runs, 5);
+  assert.equal(result.testedScripts, 1);
+  assert.equal(result.passRate, 2 / 3);
+  const a = result.rows.find(row => row.id === 'a')!;
+  assert.equal(a.name, '新名称');
+  assert.equal(a.averageDurationMs, 1500);
+  assert.equal(a.passRate, 0.5);
+  assert.equal(a.lastStatus, 'running');
+  assert.equal(result.rows.find(row => row.id === 'b')?.passRate, null);
+  assert.equal(result.rows.find(row => row.id === 'deleted')?.archived, true);
+  const recent = summarizeTests([{ id: 'b', name: '未执行' }], runs, Date.parse('2026-09-22T00:00:00Z'));
+  assert.equal(recent.runs, 2);
+  assert.equal(recent.passRate, null);
+  assert.equal(recent.rows.find(row => row.id === 'a')?.averageDurationMs, null);
+});
+
+
+test('daily/monthly charts zero-fill calendar buckets and retain older runs in all-time totals', () => {
+  const now = new Date(2026, 0, 2, 12).getTime();
+  const runs: TestRun[] = [
+    { scriptId: 'a', scriptName: 'a', status: 'passed', startedAt: new Date(2026, 0, 2, 8).toISOString(), durationMs: 10 },
+    { scriptId: 'a', scriptName: 'a', status: 'failed', startedAt: new Date(2024, 0, 1).toISOString(), durationMs: 10 },
+  ];
+  const all = summarizeTests([], runs, 0, now);
+  assert.equal(all.runs, 2);
+  assert.equal(all.daily.length, 30);
+  assert.equal(all.monthly.length, 12);
+  assert.deepEqual(all.monthly.at(-1), { date: '2026-01', runs: 1 });
+  assert.equal(all.daily.reduce((sum, point) => sum + point.runs, 0), 1);
+  const recent = summarizeTests([], runs, new Date(2025, 11, 27).getTime(), now);
+  assert.equal(recent.daily.length, 7);
+  assert.equal(recent.monthly.length, 2);
+  assert.equal(recent.runs, 1);
+  assert.equal(recent.daily.at(-1)?.date, '2026-01-02');
+});

package/server/analytics.ts

@@ -0,0 +1,24 @@
+import { summarizeTests, type AnalysisResponse, type TestStatus } from '../src/analytics/summary';
+import { listScriptRecords } from './script-db';
+import { listAppiumRecordedScripts } from './appium-recorder/repository';
+import { listOperationAnalytics } from './operations/repository';
+import { listRunAnalytics } from './appium-recorder/run-history';
+
+export function getTestAnalytics(days = 0): AnalysisResponse {
+  const generatedAt = new Date().toISOString();
+  const start = new Date(generatedAt);
+  start.setDate(start.getDate() - Math.max(0, days - 1));
+  start.setHours(0, 0, 0, 0);
+  const since = days ? start.getTime() : 0;
+  const status: Record<string, TestStatus> = { succeeded: 'passed', failed: 'failed', cancelled: 'stopped', running: 'running' };
+  return {
+    generatedAt, days,
+    // Midscene's historical records identify scripts by name, not database ID.
+    midscene: summarizeTests(listScriptRecords().map(script => ({ id: script.name, name: script.name })), listOperationAnalytics().map(run => ({
+      scriptId: run.script_name, scriptName: run.script_name, startedAt: run.started_at,
+      durationMs: run.finished_at ? Date.parse(run.finished_at) - Date.parse(run.started_at) : null,
+      status: status[run.status],
+    })), since, Date.parse(generatedAt)),
+    appium: summarizeTests(listAppiumRecordedScripts().map(script => ({ id: script.id, name: script.name })), listRunAnalytics(), since, Date.parse(generatedAt)),
+  };
+}

package/server/api-safety-analytics.test.ts

@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { AnalysisResponse } from '../src/analytics/summary';
+
+test('API rejects malformed requests safely and analytics reads all stored executions without a 100-record cap', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'console-api-'));
+  const oldRoot = process.env.ANDROID_MIDSCENE_DATA_ROOT;
+  process.env.ANDROID_MIDSCENE_DATA_ROOT = root;
+  const { createApiMiddleware } = await import('./http-api');
+  const handler = createApiMiddleware();
+  const server = createServer((req, res) => handler(req, res, () => { res.statusCode = 404; res.end(); }));
+  try {
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    const base = `http://127.0.0.1:${address.port}`;
+    for (const path of ['/api/config', '/api/config/appium', '/api/test-model', '/api/appium-recorder/scripts', '/api/generate']) {
+      assert.equal((await fetch(base + path, { method: 'POST', body: '{' })).status, 400, path);
+    }
+    assert.equal((await fetch(base + '/api/config', { headers: { Origin: 'https://foreign.example' } })).status, 403);
+    assert.equal((await fetch(base + '/api/config')).status, 200);
+    const { upsertScriptRecord } = await import('./script-db');
+    upsertScriptRecord({ name: 'Midscene 测试', promptTitle: '', sourcePrompt: '', code: 'private-code', filePath: '', steps: [] });
+    upsertScriptRecord({ name: '未执行', promptTitle: '', sourcePrompt: '', code: '', filePath: '', steps: [] });
+    const { initOperationRepository } = await import('./operations/repository');
+    const { runSql, sqlString } = await import('./storage/sqlite');
+    initOperationRepository();
+    const started = new Date(Date.now() - 10_000).toISOString();
+    const finished = new Date().toISOString();
+    runSql(Array.from({ length: 105 }, (_, i) => `INSERT INTO operations (id, kind, status, script_name, device_id, session_id, created_at, started_at, finished_at) VALUES ('op-${i}', 'script_run', '${i === 0 ? 'failed' : 'succeeded'}', 'Midscene 测试', '', '', ${sqlString(started)}, ${sqlString(started)}, ${sqlString(finished)});`).join('\n'));
+    const { saveAppiumRecordedScript } = await import('./appium-recorder/repository');
+    const script = saveAppiumRecordedScript({ name: 'Appium 测试', appPackage: 'example.test', steps: [] });
+    const { saveRunHistory } = await import('./appium-recorder/run-history');
+    saveRunHistory({ scriptId: script.id, scriptName: script.name, appPackage: 'example.test', appVersion: '1', deviceId: '', startedAt: started, durationMs: 4000, status: 'passed', nodes: [], output: 'private-output', frames: [] });
+    const response = await fetch(base + '/api/analytics');
+    const body = await response.text();
+    const summary = JSON.parse(body) as AnalysisResponse;
+    assert.equal(response.status, 200);
+    assert.equal(summary.midscene.runs, 105);
+    assert.equal(summary.midscene.scripts, 2);
+    assert.equal(summary.midscene.failed, 1);
+    assert.equal(summary.midscene.rows.find(row => row.name === '未执行')?.runs, 0);
+    assert.equal(summary.appium.runs, 1);
+    assert.equal(summary.appium.passRate, 1);
+    assert.equal(body.includes('private-'), false);
+    assert.equal((await fetch(base + '/api/analytics?days=invalid')).status, 400);
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>(resolve => server.close(() => resolve()));
+    if (oldRoot === undefined) delete process.env.ANDROID_MIDSCENE_DATA_ROOT; else process.env.ANDROID_MIDSCENE_DATA_ROOT = oldRoot;
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/server/appium-auto-save.test.ts

@@ -52,7 +52,13 @@ test('loads quietly, serializes rapid edits, validates colors and surfaces save
     await delay(400);
     assert.equal(errors.length, 1);
     assert.match(auto.status.value, /失败/);
+    assert.equal(auto.failed.value, true);
+    assert.equal(auto.dirty.value, true);
     fail = false;
+    await auto.retry();
+    assert.equal(auto.failed.value, false);
+    assert.equal(auto.dirty.value, false);
+    assert.equal(submissions.at(-1)?.screenshotReport, true);
     form.appium.flowBackgroundColor = '#abcdef';
     await delay(400);
     assert.equal(auto.status.value, '已自动保存');

package/server/appium-recorder/ai-recognition.test.ts

@@ -0,0 +1,27 @@
+// Run: npx tsx --test server/appium-recorder/ai-recognition.test.ts
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  AiInvalidResultError,
+  parseAiRecognitionResult,
+  resolveAiInvalidResultFallback,
+} from './ai-recognition';
+
+test('valid AI boolean results keep their original branch', () => {
+  assert.deepEqual(parseAiRecognitionResult('{"result":true,"reason":"已出图"}'), { result: true, reason: '已出图' });
+  assert.deepEqual(parseAiRecognitionResult('{"result":false,"reason":"仍是黑屏"}'), { result: false, reason: '仍是黑屏' });
+});
+
+test('empty, invalid and indeterminate AI answers are classified as invalid results', () => {
+  for (const content of ['', 'not json', '{"result":"true"}', '{"result":null,"reason":"画面模糊"}']) {
+    assert.throws(() => parseAiRecognitionResult(content), AiInvalidResultError);
+  }
+});
+
+test('configured fallback applies only to invalid AI results', () => {
+  const invalid = new AiInvalidResultError('没有 true/false');
+  assert.equal(resolveAiInvalidResultFallback(invalid, 'yes'), true);
+  assert.equal(resolveAiInvalidResultFallback(invalid, 'no'), false);
+  assert.equal(resolveAiInvalidResultFallback(invalid), null);
+  assert.equal(resolveAiInvalidResultFallback(new Error('network failed'), 'yes'), null);
+});

package/server/appium-recorder/ai-recognition.ts

@@ -17,16 +17,28 @@ export function aiAnswerText(content: string | null | undefined) {
   return (content || '').replace(/<think>[\s\S]*?<\/think>/gi, '').trim().replace(/^```(?:json)?\s*([\s\S]*?)\s*```$/i, '$1').trim();
 }
 
+export class AiInvalidResultError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AiInvalidResultError';
+  }
+}
+
+export function resolveAiInvalidResultFallback(error: unknown, branch?: 'yes' | 'no'): boolean | null {
+  if (!(error instanceof AiInvalidResultError) || (branch !== 'yes' && branch !== 'no')) return null;
+  return branch === 'yes';
+}
+
 export function parseAiRecognitionResult(content: string | null | undefined): { result: boolean; reason: string } {
   // 只接受 JSON 布尔值；字符串 "false"、不确定或格式错误不能误走 false 分支。
   const text = aiAnswerText(content);
   let value: unknown;
-  try { value = JSON.parse(text); } catch { throw new Error('AI 识别未返回有效 JSON 结果'); }
+  try { value = JSON.parse(text); } catch { throw new AiInvalidResultError('AI 识别未返回有效 JSON 结果'); }
   if (!value || typeof value !== 'object' || !('result' in value) || typeof value.result !== 'boolean') {
     if (value && typeof value === 'object' && 'result' in value && value.result === null) {
-      throw new Error(`AI 无法判断，无法进入分支：${'reason' in value && typeof value.reason === 'string' ? value.reason.slice(0, 2000) : '未返回确定的判断结果'}`);
+      throw new AiInvalidResultError(`AI 无法判断：${'reason' in value && typeof value.reason === 'string' ? value.reason.slice(0, 2000) : '未返回确定的判断结果'}`);
     }
-    throw new Error('AI 识别结果必须包含布尔值 result（true/false）');
+    throw new AiInvalidResultError('AI 识别结果必须包含布尔值 result（true/false）');
   }
   const reason = 'reason' in value && typeof value.reason === 'string' ? value.reason.trim() : '';
   return { result: value.result, reason: reason.slice(0, 2000) };
@@ -96,7 +108,7 @@ export async function recognizeDeviceScreen(input: {
       // 先记录正文再解析，格式错误或被截断的回答也可排查；不记录请求与鉴权信息。
       const content = (choice?.message.content || '').split(model.apiKey).join('[REDACTED]');
       input.onModelOutput?.(content || '（空响应）');
-      if (choice?.finish_reason !== 'stop') throw new Error('AI 识别响应未完整返回');
+      if (choice?.finish_reason !== 'stop') throw new AiInvalidResultError('AI 识别响应未完整返回');
       if (input.aiBranchEnabled === false && observationConfig?.mode !== 'untilMatch') {
         const reason = aiAnswerText(content);
         if (!reason) throw new Error('AI 识别未返回回答内容');

package/server/appium-recorder/appium-runner.ts

@@ -10,7 +10,7 @@ import { adbScreenshotBase64 } from './screenshot';
 import { loadConfig } from '../config';
 import { timestampReplayLog } from './replay-log';
 import { checkImage } from './image-check';
-import { recognizeDeviceScreen } from './ai-recognition';
+import { recognizeDeviceScreen, resolveAiInvalidResultFallback } from './ai-recognition';
 import { IMAGE_CHECK_MODES, type ImageCheckResult } from '../../src/appium-recorder/image-check';
 import { formatStageLog } from '../../src/appium-recorder/stage-log';
 import { openGalleryOnDevice } from './open-gallery';
@@ -1347,6 +1347,16 @@ async function replayFlowSteps(
           await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'stopped', '已终止');
           throw new ReplayStoppedError();
         }
+        const invalidResultFallback = step.type === 'aiRecognition'
+          ? resolveAiInvalidResultFallback(error, step.aiInvalidResultBranch)
+          : null;
+        if (invalidResultFallback !== null) {
+          const status = `AI 未返回有效 true/false，按兜底配置进入 ${invalidResultFallback ? 'true' : 'false'} 分支`;
+          lines.push(`[节点 ${index + 1}] ${status}；${errorDetail(error)}`);
+          await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', status);
+          index = traversal.branch(step, invalidResultFallback);
+          continue;
+        }
         if (error instanceof ConditionTimeoutError && (step.timeoutBranch === 'yes' || step.timeoutBranch === 'no')) {
           const branch = step.timeoutBranch;
           const status = `判断超时，按配置进入${branch === 'yes' ? '左' : '右'}侧分支（${flowBranchLabel(step, branch)}）`;

package/server/appium-recorder/appium-version.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { getAppiumVersion } from './managed-appium';
+
+test('Appium version uses the configured runtime and reports unavailable versions without a guessed fallback', async () => {
+  const original = { execFile: childProcess.execFile, fetch: globalThis.fetch };
+  const env = { executable: process.env.APPIUM_EXECUTABLE, url: process.env.APPIUM_SERVER_URL };
+  let output = '3.5.0-beta.1\n';
+  let commandError: Error | null = null;
+  let executions = 0;
+  try {
+    delete process.env.APPIUM_SERVER_URL;
+    process.env.APPIUM_EXECUTABLE = '/custom/appium';
+    childProcess.execFile = ((command, args, options, callback) => {
+      executions++;
+      assert.equal(command, '/custom/appium');
+      assert.deepEqual(args, ['--version']);
+      assert.equal(options.timeout, 5000);
+      queueMicrotask(() => callback(commandError, output, ''));
+      return {};
+    }) as typeof childProcess.execFile;
+    syncBuiltinESMExports();
+    assert.equal((await getAppiumVersion()).version, '3.5.0-beta.1');
+    output = 'Warning: Node 24.19.0 is unsupported';
+    assert.equal((await getAppiumVersion()).version, null, 'do not mistake diagnostic output for the Appium version');
+    commandError = Object.assign(new Error('missing'), { code: 'ENOENT' });
+    assert.match((await getAppiumVersion()).message, /未检测到/);
+    commandError = new Error('timeout');
+    assert.match((await getAppiumVersion()).message, /读取.*失败/);
+
+    process.env.APPIUM_SERVER_URL = 'http://appium.example/wd/hub/';
+    const localExecutions = executions;
+    globalThis.fetch = async (url, options) => {
+      assert.equal(url, 'http://appium.example/wd/hub/status');
+      assert.ok(options?.signal);
+      return Response.json({ value: { ready: true, build: { version: '2.19.0' } } });
+    };
+    assert.deepEqual(await getAppiumVersion(), { version: '2.19.0', source: 'server', message: '当前配置的 Appium 服务' });
+    globalThis.fetch = async () => Response.json({ value: {} });
+    assert.equal((await getAppiumVersion()).version, null);
+    globalThis.fetch = async () => new Response('unavailable', { status: 503 });
+    assert.match((await getAppiumVersion()).message, /无法连接/);
+    globalThis.fetch = async () => { throw new Error('offline'); };
+    assert.equal((await getAppiumVersion()).version, null);
+    assert.equal(executions, localExecutions, 'external service failures must not show an unrelated local version');
+  } finally {
+    childProcess.execFile = original.execFile;
+    globalThis.fetch = original.fetch;
+    syncBuiltinESMExports();
+    if (env.executable === undefined) delete process.env.APPIUM_EXECUTABLE; else process.env.APPIUM_EXECUTABLE = env.executable;
+    if (env.url === undefined) delete process.env.APPIUM_SERVER_URL; else process.env.APPIUM_SERVER_URL = env.url;
+  }
+});

package/server/appium-recorder/managed-appium.ts

@@ -1,5 +1,41 @@
 import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { createServer } from 'node:net';
+import type { AppiumVersionInfo } from '../../src/types';
+
+function appiumExecutable() {
+  return process.env.APPIUM_EXECUTABLE?.trim() || (process.platform === 'win32' ? 'appium.cmd' : 'appium');
+}
+
+export async function getAppiumVersion(): Promise<AppiumVersionInfo> {
+  const source = usesManagedAppiumServer() ? 'local' : 'server';
+  try {
+    let output: unknown;
+    if (source === 'server') {
+      const url = process.env.APPIUM_SERVER_URL!.trim().replace(/\/+$/, '');
+      const response = await fetch(`${url}/status`, { signal: AbortSignal.timeout(3000) });
+      if (!response.ok) throw new Error('Appium status request failed');
+      const payload = await response.json() as { value?: { build?: { version?: unknown } } } | null;
+      output = payload?.value?.build?.version;
+    } else {
+      output = await new Promise<string>((resolve, reject) => {
+        execFile(appiumExecutable(), ['--version'], {
+          timeout: 5000, maxBuffer: 64 * 1024, windowsHide: true, shell: process.platform === 'win32',
+        }, (error, stdout) => error ? reject(error) : resolve(stdout));
+      });
+    }
+    const version = typeof output === 'string'
+      ? output.match(/^\s*v?(\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?)\s*$/m)?.[1]
+      : undefined;
+    return { version: version ?? null, source, message: version
+      ? (source === 'local' ? '本机已安装 · Android 自动化引擎' : '当前配置的 Appium 服务')
+      : '未返回有效版本号，请检查 Appium 安装或服务状态' };
+  } catch (error) {
+    const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+    return { version: null, source, message: source === 'server'
+      ? '暂时无法连接 Appium 服务，请检查服务后刷新'
+      : missing ? '未检测到 Appium，请安装或检查可执行文件路径' : '读取 Appium 版本失败，请检查安装后刷新' };
+  }
+}
 
 type ManagedAppiumServer = {
   serverUrl: string;
@@ -110,7 +146,7 @@ export async function startManagedAppiumServer(
 ): Promise<ManagedAppiumServer> {
   const port = await reserveLocalPort();
   const serverUrl = `http://127.0.0.1:${port}`;
-  const executable = process.env.APPIUM_EXECUTABLE?.trim() || (process.platform === 'win32' ? 'appium.cmd' : 'appium');
+  const executable = appiumExecutable();
   const args = [
     '--address',
     '127.0.0.1',

package/server/appium-recorder/repository.ts

@@ -1,4 +1,4 @@
-import { validateAiObservation, type AiObservationConfig } from '../../src/appium-recorder/ai-recognition';
+import { validateAiInvalidResultBranch, validateAiObservation, type AiInvalidResultBranch, type AiObservationConfig } from '../../src/appium-recorder/ai-recognition';
 import {
   createId,
   querySql,
@@ -103,6 +103,7 @@ export type AppiumRecordedStepRecord = {
   timeoutMs?: number;
   aiTimeoutEnabled?: boolean;
   aiBranchEnabled?: boolean;
+  aiInvalidResultBranch?: AiInvalidResultBranch;
   aiObservation?: AiObservationConfig;
   timeoutBranch?: 'stop' | 'yes' | 'no';
   longPressMode?: 'element' | 'coordinates';
@@ -382,7 +383,10 @@ export function saveAppiumRecordedScript(input: {
   if (input.variables !== undefined) validateVariables(input.variables);
   for (const step of steps) {
     // 读取旧脚本必须容错，让用户能打开并修正无效配置；仅在写入时校验。
-    if (step.type === 'aiRecognition') validateAiObservation(step.aiObservation);
+    if (step.type === 'aiRecognition') {
+      validateAiObservation(step.aiObservation);
+      validateAiInvalidResultBranch(step.aiInvalidResultBranch);
+    }
     if (step.type === 'imageCheck') validateImageCheck(step.imageCheck);
     if (step.type === 'extractVariable') validateExtraction(step.extractVariable);
     if (step.type === 'runScript') { validateVariables(step.parameters); validateReturns(step.returns); }

package/server/appium-recorder/routes.ts

@@ -1,3 +1,4 @@
+import { readBody, requestErrorStatus } from '../request-body';
 import type { AiObservationConfig } from '../../src/appium-recorder/ai-recognition';
 import { execFile } from 'node:child_process';
 import { sendReplayVideo } from './video-response';
@@ -43,17 +44,6 @@ function sendStreamEvent(res: ServerResponse, payload: unknown) {
   res.write(`${JSON.stringify(payload)}\n`);
 }
 
-async function readBody<T>(req: IncomingMessage) {
-  let body = '';
-  req.on('data', (chunk) => {
-    body += chunk;
-  });
-  return await new Promise<T>((resolve) => {
-    req.on('end', () => {
-      resolve(JSON.parse(body || '{}') as T);
-    });
-  });
-}
 
 function execFileText(command: string, args: string[] = []) {
   return new Promise<string>((resolve, reject) => {
@@ -504,7 +494,7 @@ export async function handleAppiumRecorderRequest(
       sendStreamEvent(res, { type: 'error', message });
       res.end();
     } else {
-      sendJson(res, { message }, 500);
+      sendJson(res, { message }, requestErrorStatus(error));
     }
     return true;
   }

package/server/appium-recorder/run-history.ts

@@ -40,3 +40,14 @@ export function deleteRunHistory(scriptId: string, id: string) {
   }
   runSql(`PRAGMA secure_delete=ON; DELETE FROM appium_run_history WHERE script_id=${sqlString(scriptId)} AND id=${sqlString(id)};`);
 }
+
+export function listRunAnalytics() {
+  ensureTable();
+  return querySql<{ scriptId: string; scriptName: string; startedAt: string; durationMs: number; status: RunSummary['status'] }>(`
+    SELECT script_id AS scriptId, started_at AS startedAt,
+      json_extract(summary, '$.scriptName') AS scriptName,
+      json_extract(summary, '$.durationMs') AS durationMs,
+      json_extract(summary, '$.status') AS status
+    FROM appium_run_history;
+  `);
+}

package/server/config-access.test.ts

@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import type { IncomingMessage } from 'node:http';
+import { canManageConfig, publicConfig, resolveSavedModelKey } from './config-access';
+import { SAVED_API_KEY } from '../src/config/credentials';
+import type { AppConfig } from './config';
+
+test('configuration access requires a loopback client and matching browser origin', () => {
+  const request = (address: string, origin?: string) => ({ socket: { remoteAddress: address }, headers: { host: 'localhost:5173', origin } }) as IncomingMessage;
+  assert.equal(canManageConfig(request('192.0.2.10')), false);
+  assert.equal(canManageConfig(request('127.0.0.1', 'https://foreign.example')), false);
+  assert.equal(canManageConfig(request('::1', 'http://localhost:5173')), true);
+  assert.equal(canManageConfig(request('::ffff:127.0.0.1')), true);
+});
+
+test('public config masks every key and server env without modifying stored values; masked keys cannot move to another endpoint', () => {
+  const model = { baseUrl: 'https://model.example/v1', apiKey: 'private-secret', name: 'model' };
+  const stored = { runtime: { androidSdkPath: '', reportOutputPath: '' }, midscene: { model: { ...model, provider: 'custom', family: 'gpt-5' }, env: { SECRET: 'secret-env' } }, scriptOptimizer: { model }, appium: { model, promptOptimizer: { model } } } as AppConfig;
+  const output = publicConfig(stored);
+  assert.equal(JSON.stringify(output).includes('private-secret'), false);
+  assert.deepEqual(output.midscene.env, {});
+  assert.equal(stored.midscene.model.apiKey, 'private-secret');
+  assert.equal(resolveSavedModelKey({ ...model, apiKey: SAVED_API_KEY }, model), 'private-secret');
+  assert.throws(() => resolveSavedModelKey({ ...model, baseUrl: 'https://other.example', apiKey: SAVED_API_KEY }, model), /重新输入/);
+  assert.throws(() => resolveSavedModelKey({ ...model, provider: 'codex', apiKey: SAVED_API_KEY }, model), /重新输入/);
+  assert.equal(resolveSavedModelKey({ ...model, apiKey: 'replacement' }, model), 'replacement');
+});

package/server/config-access.ts

@@ -0,0 +1,27 @@
+import type { IncomingMessage } from 'node:http';
+import type { AppConfig } from './config';
+import { SAVED_API_KEY } from '../src/config/credentials';
+
+export function canManageConfig(req: IncomingMessage) {
+  if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress || '')) return false;
+  if (!req.headers.origin) return true;
+  try { return new URL(req.headers.origin).host === req.headers.host; } catch { return false; }
+}
+
+export function publicConfig(config: AppConfig): AppConfig {
+  const result = structuredClone(config);
+  for (const model of [result.midscene.model, result.scriptOptimizer.model, result.appium.model, result.appium.promptOptimizer?.model]) {
+    if (model?.apiKey) model.apiKey = SAVED_API_KEY;
+  }
+  // Runtime environment overrides are only consumed by the server.
+  result.midscene.env = {};
+  return result;
+}
+
+export function resolveSavedModelKey(model: { apiKey?: string; baseUrl?: string; provider?: string }, stored?: { apiKey: string; baseUrl: string; provider?: string }) {
+  if (model.apiKey !== SAVED_API_KEY) return model.apiKey || '';
+  if (!stored || model.baseUrl?.trim().replace(/\/+$/, '') !== stored.baseUrl.trim().replace(/\/+$/, '') || model.provider !== stored.provider) {
+    throw new Error('模型连接地址或提供方已改变，请重新输入 API Key');
+  }
+  return stored.apiKey;
+}