From aa59aceaee2a80bc9e8ad34c283691edc6efcb7d Mon Sep 17 00:00:00 2001 From: winewill Date: Tue, 20 Oct 2026 18:12:39 +0800 Subject: [PATCH] docs(desktop): replace manual diagnostic scripts with test guidance --- .../scripts/prepare-diagnostic-fixtures.mjs | 104 ------------------ .../scripts/qualify-operation-diagnostics.mjs | 101 ----------------- .../qualify-operation-report-worker.mjs | 53 --------- apps/desktop/tests/README.i18n.yaml | 25 +++-- apps/desktop/tests/README.md | 15 ++- apps/desktop/tests/README.zh.md | 15 ++- .../tests/fixtures/operation-read-stall.mjs | 24 ---- 7 files changed, 42 insertions(+), 295 deletions(-) delete mode 100644 apps/desktop/scripts/prepare-diagnostic-fixtures.mjs delete mode 100644 apps/desktop/scripts/qualify-operation-diagnostics.mjs delete mode 100644 apps/desktop/scripts/qualify-operation-report-worker.mjs delete mode 100644 apps/desktop/tests/fixtures/operation-read-stall.mjs diff --git a/apps/desktop/scripts/prepare-diagnostic-fixtures.mjs b/apps/desktop/scripts/prepare-diagnostic-fixtures.mjs deleted file mode 100644 index d21cd4d489..0000000000 --- a/apps/desktop/scripts/prepare-diagnostic-fixtures.mjs +++ /dev/null @@ -1,104 +0,0 @@ -/** - * Prepare local-only fault bundles for installed Desktop qualification; never publish these packages. - * Run `node apps/desktop/scripts/prepare-diagnostic-fixtures.mjs ` with tar on PATH. - * Each invocation creates a new directory containing six archives, their sources, and a test checklist. - */ -import { execFileSync } from 'node:child_process' -import { mkdir, mkdtemp, writeFile } from 'node:fs/promises' -import { join, resolve } from 'node:path' - -const destination = process.argv[2] -if (destination === undefined) throw new Error('Provide an output directory for local diagnostic test bundles') -await mkdir(resolve(destination), { recursive: true }) -const root = await mkdtemp(join(resolve(destination), 'diagnostic-fixtures-')) -const disabledBundle = 'dsh-test-diagnostic-disabled-services' -const delayMs = 10_000 -const delayed = action => `export const inject = ['appReady']; -export function apply(ctx) { - ctx.effect(() => { - let timer; - const dispose = ctx.appReady.onReady(() => { - timer = setTimeout(() => { ${action} }, ${delayMs}); - }); - return () => { clearTimeout(timer); dispose(); }; - }); -} -` -const fixtures = [ - { - name: disabledBundle, - description: 'Disables four core providers; startup must fail until this test bundle is disabled.', - patch: ['agent', 'session', 'llm', 'tools'].map(id => `- id: ${id}\n disabled: true`).join('\n') + '\n', - }, - { - name: 'dsh-test-diagnostic-import', - description: 'Imports a failing module while agent-loop requires its unavailable fixture service.', - patch: '- insert:\n - id: diagnostic-import\n name: ./fault.mjs\n- id: agent-loop\n inject: [diagnosticFixtureReady]\n', - source: 'throw new Error("DIAGNOSTIC_FIXTURE_IMPORT", { cause: new Error("DIAGNOSTIC_FIXTURE_IMPORT_CAUSE") });\n', - }, - { - name: 'dsh-test-diagnostic-initialize', - description: 'Initializes a failing plugin while agent-loop requires its unavailable fixture service.', - patch: '- insert:\n - id: diagnostic-initialize\n name: ./fault.mjs\n- id: agent-loop\n inject: [diagnosticFixtureReady]\n', - source: 'export function apply() { throw new Error("DIAGNOSTIC_FIXTURE_INITIALIZE", { cause: new Error("DIAGNOSTIC_FIXTURE_INITIALIZE_CAUSE") }); }\n', - }, - { - name: 'dsh-test-diagnostic-async', - description: 'Throws asynchronously ten seconds after appReady; does not call a model provider.', - patch: '- insert:\n - id: diagnostic-async\n name: ./fault.mjs\n', - source: delayed('throw new Error("DIAGNOSTIC_FIXTURE_ASYNC", { cause: new Error("DIAGNOSTIC_FIXTURE_ASYNC_CAUSE") });'), - }, - { - name: 'dsh-test-diagnostic-exit', - description: 'Exits the Host with code 23 ten seconds after appReady, without normal teardown.', - patch: '- insert:\n - id: diagnostic-exit\n name: ./fault.mjs\n', - source: delayed('process.stderr.write("DIAGNOSTIC_FIXTURE_EXIT\\n", () => process.exit(23));'), - }, - { - name: 'dsh-test-diagnostic-restart', - description: 'Requires the disabled-services test package installed but unselected; enables it through pluginManager and then fails asynchronously.', - patch: '- insert:\n - id: diagnostic-restart\n name: ./fault.mjs\n', - source: delayed(`void ctx.pluginManager.setBundleEnabled('${disabledBundle}', true).then(result => { - if (!['applied', 'restart-required'].includes(result.application)) throw new Error('DIAGNOSTIC_FIXTURE_UNEXPECTED_RESULT_' + result.application); - throw new Error('DIAGNOSTIC_FIXTURE_RESTART_AFTER_CHANGE'); - });`).replace("['appReady']", "['appReady', 'pluginManager']"), - }, -] -const packages = [] -for (const fixture of fixtures) { - const directory = join(root, fixture.name) - const contents = join(directory, 'package') - await mkdir(contents, { recursive: true }) - await writeFile(join(contents, 'package.json'), JSON.stringify({ - name: fixture.name, version: '1.0.0', private: true, license: 'UNLICENSED', type: 'module', - description: fixture.description, dsh: { bundle: { patch: './cordis.patch.yml' } }, - }, null, 2) + '\n') - await writeFile(join(contents, 'cordis.patch.yml'), fixture.patch) - if (fixture.source !== undefined) await writeFile(join(contents, 'fault.mjs'), fixture.source) - const archive = join(root, fixture.name + '-1.0.0.tgz') - execFileSync('tar', ['-czf', archive, '-C', directory, 'package'], { windowsHide: true }) - packages.push({ name: fixture.name, archive, description: fixture.description }) -} -await writeFile(join(root, 'fixtures.json'), JSON.stringify({ delayMs, packages }, null, 2) + '\n') -await writeFile(join(root, 'README.txt'), `Desktop 故障诊断测试包 - -这些测试插件会故意触发启动失败、运行异常或 Host 退出,用于检查故障报告和恢复操作。 -仅在独立测试配置或虚拟机中安装,不要安装到日常使用的配置,也不要发布这些包。 -每个 .tgz 都是一个独立 bundle;源码位于同名目录的 package 子目录。 -fixtures.json 记录包名、文件路径和故障类型。生成成功不代表客户端验收通过。 - -预期故障: -- disabled-services:禁用 agent、session、llm、tools 四个核心提供者,启动失败。 -- import:模块导入抛错,并让 agent-loop 等待测试服务;核对原始错误和缺失服务。 -- initialize:插件初始化抛错,并让 agent-loop 等待测试服务;核对 cause。 -- async:appReady 后 10 秒抛出异步异常;核对原始错误和 cause。 -- exit:appReady 后 10 秒将 Host 以退出码 23 结束;核对退出码和 stderr 标记。 -- restart:要求 disabled-services 已安装但未启用;通过 pluginManager 启用它,接受即时应用或要求重启的成功结果后抛错,再次启动应出现核心提供者缺失。 - -每个独立场景从干净测试配置开始。restart 场景保留同一配置和日志跨两次启动。 -appReady 不代表窗口已经显示;运行时场景必须另行观察实际就绪状态。 -记录安装包版本和源码提交、插件操作结果、报告路径、hostRunId、操作记录、附加收集完成标记及耗时。 -通过弹窗获取报告,确认文件可读。恢复操作后核对测试 bundle 已禁用,再验证客户端可启动。 -原始插件输出只在需要时单独取用;提交工单前检查内容,不自动上传。 -`) -console.log(JSON.stringify({ root, packages }, null, 2)) diff --git a/apps/desktop/scripts/qualify-operation-diagnostics.mjs b/apps/desktop/scripts/qualify-operation-diagnostics.mjs deleted file mode 100644 index acdf903962..0000000000 --- a/apps/desktop/scripts/qualify-operation-diagnostics.mjs +++ /dev/null @@ -1,101 +0,0 @@ -/** Manual built-code qualification: fresh processes, bounded work, and retained report output. */ -import assert from 'node:assert/strict' -import { spawnSync } from 'node:child_process' -import { mkdir, mkdtemp, open, readFile, rm, writeFile } from 'node:fs/promises' -import { tmpdir } from 'node:os' -import { dirname, join, resolve } from 'node:path' -import { fileURLToPath } from 'node:url' -import { performance } from 'node:perf_hooks' -import { readOperationHistory } from '../lib/types/operation-history.js' -import { appendOperationReport } from '../lib/types/operation-report.js' -import { writeCrashReport } from '../lib/types/crash-report.js' - -const limits = { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 } -const record = index => ({ - runId: 'c254ab28-97c9-4382-95e6-2db9c66f98c8', transportDropped: 0, - operation: { id: `c254ab28-97c9-4382-95e6-${index.toString(16).padStart(12, '0')}`, - time: '2026-10-19T00:00:00.000Z', reason: 'bundle', phase: 'settled', target: `synthetic-plugin-${index % 50}`, - stage: 'enable', application: 'restart-required', changed: true, version: '1.0.0' }, -}) - -if (process.argv[2] === '--sample') { - const directory = process.argv[3] - global.gc?.() - const baseline = { ...process.memoryUsage(), maxRssKiB: process.resourceUsage().maxRSS } - const start = performance.now() - const report = await writeCrashReport(directory, { - source: 'host', phase: 'startup', error: new Error('synthetic startup failure'), rendererConsole: [], - operationHistoryPlanned: true, time: new Date(), - app: { name: 'qualification', version: 'test', platform: process.platform, arch: process.arch, - electron: 'not-running', node: process.version, locale: 'zh-CN' }, - }) - assert.ok(report) - const basicMs = performance.now() - start - const basic = await readFile(report) - const collectStart = performance.now() - const history = await readOperationHistory(directory, limits, new AbortController().signal) - const collectMs = performance.now() - collectStart - assert.ok(history.filesRead <= 2) - assert.ok(history.bytesRead <= limits.bytes) - assert.ok(history.records.length <= limits.records) - assert.ok(history.records.length >= 50) - const appendStart = performance.now() - assert.equal(await appendOperationReport(report, directory, limits, AbortSignal.timeout(500), null), true) - const appendMs = performance.now() - appendStart - const output = await readFile(report) - assert.equal(output.subarray(0, basic.length).equals(basic), true) - assert.ok(output.length - basic.length <= limits.outputBytes) - global.gc?.() - const retained = process.memoryUsage() - console.log(JSON.stringify({ basicMs, collectMs, appendMs, filesRead: history.filesRead, bytesRead: history.bytesRead, - records: history.records.length, invalidRecords: history.invalidRecords, reportBytes: output.length, - baseline, retained, peakRssKiB: process.resourceUsage().maxRSS, retainedOutputBytes: output.length })) -} else { - const outputPath = process.argv[2] - if (outputPath === undefined) throw new Error('Provide an output JSON path; build Desktop Host TypeScript first') - const root = await mkdtemp(join(tmpdir(), 'dsh-diagnostic-qualification-')) - const samples = [] - try { - for (const scenario of ['ordinary-50', 'two-gib', 'many-unrelated-files', 'dense-and-corrupt']) { - const directory = join(root, scenario) - await mkdir(directory) - const fixtureStart = performance.now() - const tail = Array.from({ length: scenario === 'dense-and-corrupt' ? 2000 : 50 }, (_, i) => JSON.stringify(record(i))).join('\n') + '\n' - if (scenario === 'two-gib') { - await using file = await open(join(directory, 'operations.jsonl'), 'w') - const size = 2 * 1024 ** 3 - await file.truncate(size) - const bytes = Buffer.from('\n' + tail) - await file.write(bytes, 0, bytes.length, size - bytes.length) - } else { - await writeFile(join(directory, 'operations.jsonl'), tail - + (scenario === 'dense-and-corrupt' ? '{broken}\n' + 'x'.repeat(16384) + '\n{"partial":' : '')) - } - if (scenario === 'many-unrelated-files') { - await using raw = await open(join(directory, 'pnpm.log'), 'w') - await raw.truncate(2 * 1024 ** 3) - for (let batch = 0; batch < 100; batch++) { - await Promise.all(Array.from({ length: 50 }, (_, i) => writeFile(join(directory, `rotated-${batch * 50 + i}.log`), 'unrelated'))) - } - } - const fixtureMs = performance.now() - fixtureStart - for (let trial = 0; trial < 3; trial++) { - const child = spawnSync(process.execPath, ['--expose-gc', '--max-old-space-size=64', fileURLToPath(import.meta.url), '--sample', directory], { - encoding: 'utf8', timeout: 15000, windowsHide: true, maxBuffer: 1024 * 1024, - }) - assert.equal(child.error, undefined) - assert.equal(child.signal, null) - assert.equal(child.status, 0, child.stderr) - samples.push({ scenario, trial, fixtureMs, ...JSON.parse(child.stdout) }) - } - } - const evidence = { runtime: process.version, platform: process.platform, arch: process.arch, - scope: 'Built component/report calls in fresh Node processes; not packaged Electron or cold filesystem cache. Fixture setup excluded. Heap capped at 64 MiB; peak RSS includes runtime/imports.', - limits, samples } - await writeFile(outputPath, JSON.stringify(evidence, null, 2) + '\n') - console.log(JSON.stringify(evidence)) - } finally { - assert.equal(dirname(resolve(root)), resolve(tmpdir())) - await rm(root, { recursive: true, force: true }) - } -} diff --git a/apps/desktop/scripts/qualify-operation-report-worker.mjs b/apps/desktop/scripts/qualify-operation-report-worker.mjs deleted file mode 100644 index adc75ded82..0000000000 --- a/apps/desktop/scripts/qualify-operation-report-worker.mjs +++ /dev/null @@ -1,53 +0,0 @@ -/** Built Worker qualification with an injected stalled read; no product fault-injection option. */ -import assert from 'node:assert/strict' -import { spawnSync } from 'node:child_process' -import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' -import { tmpdir } from 'node:os' -import { dirname, join, resolve } from 'node:path' -import { fileURLToPath } from 'node:url' -import { performance } from 'node:perf_hooks' -import { runOperationReportJob } from '../lib/types/operation-report-job.js' - -if (process.argv[2] === '--sample') { - const directory = process.argv[3] - const stalled = process.argv[4] === 'stalled' - const reportPath = join(directory, 'basic.log') - const basic = 'Independent basic crash report\n' - await writeFile(reportPath, basic) - const start = performance.now() - const result = await runOperationReportJob({ reportPath, directory, journal: null, - limits: { bytes: 65536, recordBytes: 4096, records: 100, outputBytes: 65536 } }, stalled ? 2000 : 500) - const elapsedMs = performance.now() - start - const output = await readFile(reportPath, 'utf8') - if (stalled) { - assert.equal(await readFile(join(directory, 'read-entered'), 'utf8'), 'ready') - assert.deepEqual(result, { appended: false, timedOut: true }) - assert.equal(output, basic) - } else { - assert.deepEqual(result, { appended: true, timedOut: false }) - assert.ok(output.startsWith(basic)) - } - console.log(JSON.stringify({ stalled, elapsedMs, result, reportBytes: Buffer.byteLength(output), peakRssKiB: process.resourceUsage().maxRSS })) -} else { - const root = await mkdtemp(join(tmpdir(), 'dsh-worker-qualification-')) - const samples = [] - try { - for (const stalled of [false, true]) { - const child = spawnSync(process.execPath, [ - ...(stalled ? ['--import', new URL('../tests/fixtures/operation-read-stall.mjs', import.meta.url).href] : []), - fileURLToPath(import.meta.url), '--sample', root, stalled ? 'stalled' : 'normal', - ], { windowsHide: true, timeout: 15000, encoding: 'utf8', maxBuffer: 1024 * 1024 }) - assert.equal(child.error, undefined) - assert.equal(child.signal, null) - assert.equal(child.status, 0, child.stderr) - samples.push(JSON.parse(child.stdout)) - } - const evidence = { runtime: process.version, platform: process.platform, - scope: 'Real built Worker exit after normal collection and injected pending asynchronous read; not a kernel-hung filesystem or Electron measurement.', samples } - if (process.argv[2] !== undefined) await writeFile(process.argv[2], JSON.stringify(evidence, null, 2) + '\n') - console.log(JSON.stringify(evidence)) - } finally { - assert.equal(dirname(resolve(root)), resolve(tmpdir())) - await rm(root, { recursive: true, force: true }) - } -} diff --git a/apps/desktop/tests/README.i18n.yaml b/apps/desktop/tests/README.i18n.yaml index 601ce4b9f7..a2281ab239 100644 --- a/apps/desktop/tests/README.i18n.yaml +++ b/apps/desktop/tests/README.i18n.yaml @@ -2,24 +2,27 @@ # section, a hash of its English and Chinese blocks outside code blocks and generated regions. # After editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write apps/desktop/tests/README.md -/desktop-local-update-verification: - en: 194f1f0f1ca90743 - zh: 773ca28e04c8911f -/desktop-local-update-verification/summary: +/desktop-local-verification: + en: 5056a9b4d24c1880 + zh: 4d0c9d8e5f69d153 +/desktop-local-verification/summary: en: 94559f431b0b2151 zh: 1a22166a2bc59686 -/desktop-local-update-verification/table-of-contents: - en: a5edee063916cd27 - zh: 7a5286350ff09e58 -/desktop-local-update-verification/native-overlay-visibility: +/desktop-local-verification/table-of-contents: + en: 599998574ba163f1 + zh: 559999736e735a7f +/desktop-local-verification/fault-report-verification: + en: 7a3a8896370f2b75 + zh: 0ad17fee73fc47ec +/desktop-local-verification/native-overlay-visibility: en: cff2c259a195bb57 zh: fa03ff3fdc32a346 -/desktop-local-update-verification/manual-walkthrough: +/desktop-local-verification/manual-walkthrough: en: c4b4ee8763d8464a zh: ee2159bc08966592 -/desktop-local-update-verification/evidence: +/desktop-local-verification/evidence: en: 331a6709d0f7d03f zh: 98499192ef9d3a81 -/desktop-local-update-verification/open-verification: +/desktop-local-verification/open-verification: en: 20e9ea47acb1ff50 zh: acce24b56d57e12c diff --git a/apps/desktop/tests/README.md b/apps/desktop/tests/README.md index c4f628d596..686620cdef 100644 --- a/apps/desktop/tests/README.md +++ b/apps/desktop/tests/README.md @@ -1,4 +1,4 @@ -# Desktop local update verification +# Desktop local verification English | [中文](README.zh.md) @@ -10,11 +10,24 @@ Installed qualification can opt into `DSH_DESKTOP_UPDATE_JOURNAL_DIR`, an absolu ## Table of Contents +- [Fault-report verification](#verification-diagnostics) - [Native overlay visibility](#verification-overlay) - [Evidence](#verification-evidence) - [Manual walkthrough](#verification-interactive) - [Open verification](#verification-open) + + +## Fault-report verification + +Use a disposable profile and separate Electron `userData` with the actual packaged client. Construct a minimal local bundle with `package.json`, `dsh.bundle.patch` pointing to `cordis.patch.yml`, and an optional plugin module; archive it as a local `.tgz`. These packages deliberately break the application and must not be published or installed in a daily profile. + +Exercise import and plugin-initialization exceptions, an asynchronous exception after `appReady`, and a nonzero Host exit. A patch disabling the `agent`, `session`, `llm`, and `tools` providers exercises missing-service diagnostics. To check cross-restart history, select that bundle through `pluginManager`, then restart the same profile. Runtime scenarios require observing actual client readiness; `appReady` alone does not establish that the window is visible. + +Check the original error and cause or exit code, operation and Host run IDs across restart, report-collection completion and omissions, file retrieval from the native dialog, and startup after plugin recovery. Record the package version and source commit; successful package generation or a management result alone does not establish client functionality. Restore protocol associations and stop test processes afterward. + +For resource checks, use large sparse history files, unrelated files, dense records, and malformed or unfinished lines. Measure setup separately from collection in fresh processes, recording actual bytes read, output size, time, and peak memory. To check Worker cancellation, a test-only module hook can hold an asynchronous file open after writing an entry marker. Confirm that marker, observe Worker exit after the deadline, and compare the basic report bytes. This does not reproduce a kernel-hung system call or establish packaged-client behavior. + ## Native overlay visibility diff --git a/apps/desktop/tests/README.zh.md b/apps/desktop/tests/README.zh.md index 863b297b59..f06666cb58 100644 --- a/apps/desktop/tests/README.zh.md +++ b/apps/desktop/tests/README.zh.md @@ -1,4 +1,4 @@ -# Desktop 本地更新验证 +# Desktop 本地验证 [English](README.md) | 中文 @@ -10,11 +10,24 @@ ## 目录 +- [故障报告验证](#verification-diagnostics) - [原生浮层可见性](#verification-overlay) - [验证证据](#verification-evidence) - [手动演练](#verification-interactive) - [待验证事项](#verification-open) + + +## 故障报告验证 + +使用可丢弃的 profile、独立的 Electron `userData` 和实际打包客户端。构造最小本地组合包:`package.json` 的 `dsh.bundle.patch` 指向 `cordis.patch.yml`,需要执行代码时再加入插件模块,然后打成可本地安装的 `.tgz`。这些包会故意使应用出错,不得发布或安装到日常 profile。 + +分别构造模块导入异常、插件初始化异常、`appReady` 后的异步异常,以及 Host 非零退出。用 patch 禁用 `agent`、`session`、`llm`、`tools` 提供者,检查服务缺失诊断。跨重启场景通过 `pluginManager` 选入该组合包,再重启同一 profile。运行期场景须实际观察客户端就绪;`appReady` 不代表窗口已经显示。 + +检查原始错误与 cause 或退出码、跨重启的操作 ID 和 Host 运行 ID、报告收集完成标记与遗漏信息、原生弹窗中的文件获取,以及禁用插件恢复后的启动。记录安装包版本和源码提交;生成测试包成功或管理操作返回成功,都不能代替客户端功能验证。测试后恢复协议关联并退出测试进程。 + +资源验证可构造大型稀疏历史文件、大量无关文件、密集记录,以及损坏行和未完成行。在独立新进程中测量,分开记录数据构造与收集开销,并核对实际读取量、输出大小、耗时和峰值内存。验证 Worker 取消时,可用仅测试加载的模块钩子在写入进入标记后挂起异步文件打开操作;先确认标记,再观察期限到达后的 Worker 退出,并逐字节核对基本报告。该方法不模拟内核系统调用卡死,也不代替打包客户端验证。 + ## 原生浮层可见性 diff --git a/apps/desktop/tests/fixtures/operation-read-stall.mjs b/apps/desktop/tests/fixtures/operation-read-stall.mjs deleted file mode 100644 index f3a4d538d6..0000000000 --- a/apps/desktop/tests/fixtures/operation-read-stall.mjs +++ /dev/null @@ -1,24 +0,0 @@ -/** Qualification-only hook: hold a real collector at its first asynchronous file open. */ -import { registerHooks } from 'node:module' - -registerHooks({ - resolve(specifier, context, next) { - if (specifier === 'node:fs/promises' && context.parentURL?.endsWith('/operation-history.js')) { - return { url: 'qualification:stalled-read', shortCircuit: true } - } - return next(specifier, context) - }, - load(url, context, next) { - if (url !== 'qualification:stalled-read') return next(url, context) - return { format: 'module', shortCircuit: true, source: ` - import { writeFile } from 'node:fs/promises' - import { join } from 'node:path' - import { workerData } from 'node:worker_threads' - export async function open() { - await writeFile(join(workerData.directory, 'read-entered'), 'ready') - setInterval(() => {}, 1000) - return new Promise(() => {}) - } - ` } - }, -})