@zzusp/ccsm 1.0.0 → 1.0.2

package/server/lib/modified-files.test.ts

@@ -0,0 +1,280 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// 用 CCSM_TEST_ROOT 跨进程桥接的写法跟 delete.test.ts 保持一致——vi.mock 的工厂
+// 必须 hoist 安全，闭包里不能引用模块作用域变量。
+vi.mock('./claude-paths.ts', () => {
+  return {
+    get PATHS() {
+      const root = process.env.CCSM_TEST_ROOT!;
+      return {
+        root,
+        projects: path.join(root, 'projects'),
+        fileHistory: path.join(root, 'file-history'),
+        sessionEnv: path.join(root, 'session-env'),
+        sessions: path.join(root, 'sessions'),
+        history: path.join(root, 'history.jsonl'),
+      };
+    },
+    isUnderClaudeRoot(target: string): boolean {
+      const root = process.env.CCSM_TEST_ROOT!;
+      const resolved = path.resolve(target);
+      return resolved === root || resolved.startsWith(root + path.sep);
+    },
+    getCacheDir(): string {
+      return path.join(process.env.CCSM_TEST_ROOT!, '_cache');
+    },
+  };
+});
+
+import { loadModifiedFiles } from './modified-files.ts';
+
+let fakeRoot: string;
+
+beforeEach(() => {
+  fakeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ccsm-modfiles-test-'));
+  process.env.CCSM_TEST_ROOT = fakeRoot;
+  fs.mkdirSync(path.join(fakeRoot, 'projects'), { recursive: true });
+});
+
+afterEach(() => {
+  fs.rmSync(fakeRoot, { recursive: true, force: true });
+  delete process.env.CCSM_TEST_ROOT;
+});
+
+function writeJsonl(projectId: string, sessionId: string, lines: object[]): string {
+  const dir = path.join(fakeRoot, 'projects', projectId);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${sessionId}.jsonl`);
+  fs.writeFileSync(file, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return file;
+}
+
+function userMsg(uuid: string, ts: string, content: unknown): object {
+  return { type: 'user', uuid, timestamp: ts, message: { content } };
+}
+
+function assistantMsg(uuid: string, ts: string, content: unknown): object {
+  return { type: 'assistant', uuid, timestamp: ts, message: { content } };
+}
+
+function toolUse(id: string, name: string, input: unknown): object {
+  return { type: 'tool_use', id, name, input };
+}
+
+function toolResult(toolUseId: string, isError = false): object {
+  return { type: 'tool_result', tool_use_id: toolUseId, content: '', is_error: isError };
+}
+
+describe('loadModifiedFiles', () => {
+  it('returns null when session jsonl missing', async () => {
+    const out = await loadModifiedFiles('proj', 'no-such-sid');
+    expect(out).toBeNull();
+  });
+
+  it('aggregates Edit/Write/MultiEdit/NotebookEdit by filePath and counts per-tool', async () => {
+    writeJsonl('proj-1', 'sid-1', [
+      { type: 'summary', cwd: '/Users/me/repo' },
+      assistantMsg('a1', '2026-06-01T10:00:00.000Z', [
+        toolUse('t1', 'Edit', { file_path: '/Users/me/repo/src/a.ts', old_string: 'x', new_string: 'y' }),
+      ]),
+      userMsg('u1', '2026-06-01T10:00:01.000Z', [toolResult('t1', false)]),
+      assistantMsg('a2', '2026-06-01T10:01:00.000Z', [
+        toolUse('t2', 'Edit', { file_path: '/Users/me/repo/src/a.ts', old_string: 'a', new_string: 'b' }),
+      ]),
+      userMsg('u2', '2026-06-01T10:01:01.000Z', [toolResult('t2', false)]),
+      assistantMsg('a3', '2026-06-01T10:02:00.000Z', [
+        toolUse('t3', 'Write', { file_path: '/Users/me/repo/src/b.ts', content: 'new file' }),
+      ]),
+      userMsg('u3', '2026-06-01T10:02:01.000Z', [toolResult('t3', false)]),
+      assistantMsg('a4', '2026-06-01T10:03:00.000Z', [
+        toolUse('t4', 'MultiEdit', {
+          file_path: '/Users/me/repo/src/b.ts',
+          edits: [{ old_string: 'a', new_string: 'b' }],
+        }),
+      ]),
+      userMsg('u4', '2026-06-01T10:03:01.000Z', [toolResult('t4', false)]),
+      assistantMsg('a5', '2026-06-01T10:04:00.000Z', [
+        toolUse('t5', 'NotebookEdit', {
+          notebook_path: '/Users/me/repo/nb.ipynb',
+          cell_id: 'c1',
+          new_source: 'print(1)',
+        }),
+      ]),
+      userMsg('u5', '2026-06-01T10:04:01.000Z', [toolResult('t5', false)]),
+    ]);
+
+    const out = await loadModifiedFiles('proj-1', 'sid-1');
+    expect(out).not.toBeNull();
+    expect(out!.cwd).toBe('/Users/me/repo');
+    expect(out!.files).toHaveLength(3);
+
+    // 排序 by lastAt desc: nb.ipynb (10:04) → b.ts (10:03) → a.ts (10:01)
+    const nb = out!.files[0]!;
+    const b = out!.files[1]!;
+    const a = out!.files[2]!;
+    expect(nb.filePath).toBe('/Users/me/repo/nb.ipynb');
+    expect(nb.notebookEditCount).toBe(1);
+    expect(nb.relativePath).toBe('nb.ipynb');
+
+    expect(b.filePath).toBe('/Users/me/repo/src/b.ts');
+    expect(b.relativePath).toBe('src/b.ts');
+    expect(b.writeCount).toBe(1);
+    expect(b.multiEditCount).toBe(1);
+    expect(b.totalCount).toBe(2);
+
+    expect(a.filePath).toBe('/Users/me/repo/src/a.ts');
+    expect(a.relativePath).toBe('src/a.ts');
+    expect(a.editCount).toBe(2);
+    expect(a.totalCount).toBe(2);
+    expect(a.errorCount).toBe(0);
+    expect(a.firstAt).toBe('2026-06-01T10:00:00.000Z');
+    expect(a.lastAt).toBe('2026-06-01T10:01:00.000Z');
+    expect(a.operations.map((o) => o.toolUseId)).toEqual(['t1', 't2']);
+    expect(a.operations.every((o) => !o.pending && !o.errored)).toBe(true);
+  });
+
+  it('marks errored when tool_result.is_error=true and pending when no result line found', async () => {
+    writeJsonl('proj', 'sid', [
+      assistantMsg('a1', '2026-06-01T10:00:00.000Z', [
+        toolUse('t-err', 'Edit', { file_path: '/repo/x.ts', old_string: 'a', new_string: 'b' }),
+      ]),
+      userMsg('u1', '2026-06-01T10:00:01.000Z', [toolResult('t-err', true)]),
+      assistantMsg('a2', '2026-06-01T10:01:00.000Z', [
+        toolUse('t-pend', 'Edit', { file_path: '/repo/x.ts', old_string: 'b', new_string: 'c' }),
+      ]),
+      // 没有 t-pend 的 tool_result
+    ]);
+
+    const out = await loadModifiedFiles('proj', 'sid');
+    const x = out!.files[0]!;
+    expect(x.totalCount).toBe(2);
+    expect(x.errorCount).toBe(1);
+    const err = x.operations.find((o) => o.toolUseId === 't-err')!;
+    expect(err.errored).toBe(true);
+    expect(err.pending).toBe(false);
+    const pend = x.operations.find((o) => o.toolUseId === 't-pend')!;
+    expect(pend.errored).toBe(false);
+    expect(pend.pending).toBe(true);
+  });
+
+  it('ignores non-file-mutating tools (Bash/Read/Grep/Task)', async () => {
+    writeJsonl('proj', 'sid', [
+      assistantMsg('a1', '2026-06-01T10:00:00.000Z', [
+        toolUse('t1', 'Bash', { command: 'ls' }),
+        toolUse('t2', 'Read', { file_path: '/repo/x.ts' }),
+        toolUse('t3', 'Grep', { pattern: 'foo' }),
+      ]),
+      userMsg('u1', '2026-06-01T10:00:01.000Z', [
+        toolResult('t1', false),
+        toolResult('t2', false),
+        toolResult('t3', false),
+      ]),
+    ]);
+    const out = await loadModifiedFiles('proj', 'sid');
+    expect(out!.files).toEqual([]);
+  });
+
+  it('relativePath is null when filePath sits outside cwd', async () => {
+    writeJsonl('proj', 'sid', [
+      { type: 'summary', cwd: '/Users/me/repo' },
+      assistantMsg('a1', '2026-06-01T10:00:00.000Z', [
+        toolUse('t1', 'Write', { file_path: '/tmp/elsewhere.txt', content: 'hi' }),
+      ]),
+      userMsg('u1', '2026-06-01T10:00:01.000Z', [toolResult('t1')]),
+    ]);
+    const out = await loadModifiedFiles('proj', 'sid');
+    expect(out!.files[0]!.relativePath).toBeNull();
+  });
+
+  it('operations within a file are ordered by ts asc', async () => {
+    writeJsonl('proj', 'sid', [
+      assistantMsg('a1', '2026-06-01T10:02:00.000Z', [
+        toolUse('t2', 'Edit', { file_path: '/repo/x.ts', old_string: 'a', new_string: 'b' }),
+      ]),
+      userMsg('u1', '2026-06-01T10:02:01.000Z', [toolResult('t2')]),
+      assistantMsg('a2', '2026-06-01T10:01:00.000Z', [
+        toolUse('t1', 'Edit', { file_path: '/repo/x.ts', old_string: 'c', new_string: 'd' }),
+      ]),
+      userMsg('u2', '2026-06-01T10:01:01.000Z', [toolResult('t1')]),
+    ]);
+    const out = await loadModifiedFiles('proj', 'sid');
+    expect(out!.files[0]!.operations.map((o) => o.toolUseId)).toEqual(['t1', 't2']);
+    expect(out!.files[0]!.firstAt).toBe('2026-06-01T10:01:00.000Z');
+    expect(out!.files[0]!.lastAt).toBe('2026-06-01T10:02:00.000Z');
+  });
+
+  it('skips malformed jsonl lines and tool_use entries without id/file_path', async () => {
+    const file = path.join(fakeRoot, 'projects', 'proj', 'sid.jsonl');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(
+      file,
+      [
+        '{not json',
+        JSON.stringify(
+          assistantMsg('a1', '2026-06-01T10:00:00.000Z', [
+            toolUse('', 'Edit', { file_path: '/x.ts', old_string: 'a', new_string: 'b' }), // empty id → skip
+            toolUse('t1', 'Edit', { /* no file_path */ old_string: 'a', new_string: 'b' }), // no path → skip
+            toolUse('t2', 'Write', { file_path: '/ok.ts', content: 'hi' }),
+          ]),
+        ),
+        JSON.stringify(userMsg('u1', '2026-06-01T10:00:01.000Z', [toolResult('t2')])),
+        '',
+      ].join('\n'),
+    );
+    const out = await loadModifiedFiles('proj', 'sid');
+    expect(out!.files).toHaveLength(1);
+    expect(out!.files[0]!.filePath).toBe('/ok.ts');
+  });
+
+  it('attaches structuredPatch from toolUseResult; [] for create, null when absent', async () => {
+    writeJsonl('proj-sp', 'sid-sp', [
+      { type: 'summary', cwd: '/repo' },
+      // Edit whose result line carries a real structuredPatch (accurate file line numbers).
+      assistantMsg('a1', '2026-06-01T10:00:00.000Z', [
+        toolUse('t1', 'Edit', { file_path: '/repo/a.ts', old_string: 'x', new_string: 'y' }),
+      ]),
+      {
+        type: 'user',
+        uuid: 'u1',
+        timestamp: '2026-06-01T10:00:01.000Z',
+        message: { content: [toolResult('t1', false)] },
+        toolUseResult: {
+          type: 'update',
+          filePath: '/repo/a.ts',
+          structuredPatch: [
+            { oldStart: 10, oldLines: 2, newStart: 10, newLines: 2, lines: [' ctx', '-x', '+y'] },
+          ],
+        },
+      },
+      // Write create → structuredPatch is an empty array (render input as all-added).
+      assistantMsg('a2', '2026-06-01T10:01:00.000Z', [
+        toolUse('t2', 'Write', { file_path: '/repo/b.ts', content: 'new' }),
+      ]),
+      {
+        type: 'user',
+        uuid: 'u2',
+        timestamp: '2026-06-01T10:01:01.000Z',
+        message: { content: [toolResult('t2', false)] },
+        toolUseResult: { type: 'create', filePath: '/repo/b.ts', structuredPatch: [] },
+      },
+      // Edit whose result has no toolUseResult sentinel → null (fall back to input diff).
+      assistantMsg('a3', '2026-06-01T10:02:00.000Z', [
+        toolUse('t3', 'Edit', { file_path: '/repo/c.ts', old_string: 'm', new_string: 'n' }),
+      ]),
+      userMsg('u3', '2026-06-01T10:02:01.000Z', [toolResult('t3', false)]),
+    ]);
+
+    const out = await loadModifiedFiles('proj-sp', 'sid-sp');
+    expect(out).not.toBeNull();
+    const byPath = new Map(out!.files.map((f) => [f.filePath, f]));
+
+    expect(byPath.get('/repo/a.ts')!.operations[0]!.structuredPatch).toEqual([
+      { oldStart: 10, oldLines: 2, newStart: 10, newLines: 2, lines: [' ctx', '-x', '+y'] },
+    ]);
+    expect(byPath.get('/repo/b.ts')!.operations[0]!.structuredPatch).toEqual([]);
+    expect(byPath.get('/repo/c.ts')!.operations[0]!.structuredPatch).toBeNull();
+  });
+});

package/server/lib/modified-files.ts

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { PATHS } from './claude-paths.ts';
+import type {
+  DiffHunk,
+  ModifiedFileOperation,
+  ModifiedFileSummary,
+  ModifiedFileToolName,
+  ModifiedFilesResponse,
+} from '../types.ts';
+
+const FILE_MOD_TOOLS = new Set<ModifiedFileToolName>([
+  'Edit',
+  'Write',
+  'MultiEdit',
+  'NotebookEdit',
+]);
+
+interface PendingOp {
+  toolUseId: string;
+  toolName: ModifiedFileToolName;
+  ts: string | null;
+  messageUuid: string | null;
+  filePath: string;
+}
+
+export async function loadModifiedFiles(
+  projectId: string,
+  sessionId: string,
+): Promise<ModifiedFilesResponse | null> {
+  const jsonlPath = path.join(PATHS.projects, projectId, `${sessionId}.jsonl`);
+  if (!fs.existsSync(jsonlPath)) return null;
+
+  const ops: PendingOp[] = [];
+  // tool_use_id → is_error；tool_result 在 jsonl 中通常出现在对应 tool_use 之后，
+  // 但不强依赖顺序——单次扫完再回填。
+  const resultErr = new Map<string, boolean>();
+  // tool_use_id → 该次工具结果的 structuredPatch（带真实行号的 hunk）。
+  // 哨兵记录在 user 消息顶层的 obj.toolUseResult 上，与同一行 content 里的 tool_result 一一对应。
+  const resultPatch = new Map<string, DiffHunk[]>();
+  let cwd: string | null = null;
+
+  const rl = readline.createInterface({
+    input: fs.createReadStream(jsonlPath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const raw of rl) {
+    const line = raw.trim();
+    if (!line) continue;
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    if (typeof obj.cwd === 'string' && !cwd) cwd = obj.cwd;
+
+    if (obj.type !== 'user' && obj.type !== 'assistant') continue;
+    const message = obj.message;
+    if (!message || typeof message !== 'object') continue;
+    const content = (message as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+
+    const ts = typeof obj.timestamp === 'string' ? obj.timestamp : null;
+    const messageUuid = typeof obj.uuid === 'string' ? obj.uuid : null;
+
+    for (const block of content) {
+      if (!block || typeof block !== 'object') continue;
+      const b = block as Record<string, unknown>;
+      if (b.type === 'tool_use') {
+        const name = b.name;
+        if (typeof name !== 'string') continue;
+        if (!FILE_MOD_TOOLS.has(name as ModifiedFileToolName)) continue;
+        const input = b.input;
+        if (!input || typeof input !== 'object') continue;
+        const filePath = extractFilePath(input as Record<string, unknown>);
+        if (!filePath) continue;
+        const id = typeof b.id === 'string' ? b.id : '';
+        if (!id) continue;
+        ops.push({
+          toolUseId: id,
+          toolName: name as ModifiedFileToolName,
+          ts,
+          messageUuid,
+          filePath,
+        });
+      } else if (b.type === 'tool_result') {
+        const id = b.tool_use_id;
+        if (typeof id !== 'string' || !id) continue;
+        // 同一 tool_use_id 理论上只对应一条 result；以首次出现为准。
+        if (!resultErr.has(id)) resultErr.set(id, b.is_error === true);
+        if (!resultPatch.has(id)) {
+          const patch = extractStructuredPatch(obj.toolUseResult);
+          if (patch) resultPatch.set(id, patch);
+        }
+      }
+    }
+  }
+
+  // 按 filePath 聚合
+  const byPath = new Map<string, ModifiedFileSummary>();
+  for (const op of ops) {
+    const errored = resultErr.get(op.toolUseId) === true;
+    const pending = !resultErr.has(op.toolUseId);
+    const operation: ModifiedFileOperation = {
+      toolUseId: op.toolUseId,
+      toolName: op.toolName,
+      ts: op.ts,
+      messageUuid: op.messageUuid,
+      errored,
+      pending,
+      structuredPatch: resultPatch.has(op.toolUseId) ? resultPatch.get(op.toolUseId)! : null,
+    };
+    let summary = byPath.get(op.filePath);
+    if (!summary) {
+      summary = {
+        filePath: op.filePath,
+        relativePath: null,
+        editCount: 0,
+        writeCount: 0,
+        multiEditCount: 0,
+        notebookEditCount: 0,
+        totalCount: 0,
+        errorCount: 0,
+        firstAt: null,
+        lastAt: null,
+        operations: [],
+      };
+      byPath.set(op.filePath, summary);
+    }
+    summary.operations.push(operation);
+    summary.totalCount += 1;
+    if (errored) summary.errorCount += 1;
+    switch (op.toolName) {
+      case 'Edit':
+        summary.editCount += 1;
+        break;
+      case 'Write':
+        summary.writeCount += 1;
+        break;
+      case 'MultiEdit':
+        summary.multiEditCount += 1;
+        break;
+      case 'NotebookEdit':
+        summary.notebookEditCount += 1;
+        break;
+    }
+    if (op.ts) {
+      if (!summary.firstAt || op.ts < summary.firstAt) summary.firstAt = op.ts;
+      if (!summary.lastAt || op.ts > summary.lastAt) summary.lastAt = op.ts;
+    }
+  }
+
+  for (const summary of byPath.values()) {
+    summary.operations.sort(compareByTs);
+    summary.relativePath = relativizeIfUnder(summary.filePath, cwd);
+  }
+
+  const files = Array.from(byPath.values()).sort((a, b) => {
+    // lastAt desc，null 排末尾
+    if (a.lastAt && b.lastAt) return a.lastAt < b.lastAt ? 1 : a.lastAt > b.lastAt ? -1 : 0;
+    if (a.lastAt) return -1;
+    if (b.lastAt) return 1;
+    return a.filePath.localeCompare(b.filePath);
+  });
+
+  return { sessionId, projectId, cwd, files };
+}
+
+/** Pull the structuredPatch hunks out of a `toolUseResult` sentinel. Returns an
+ *  empty array for a brand-new file (Write/NotebookEdit create, where Claude Code
+ *  records `structuredPatch: []`), and null when the field is absent/malformed. */
+function extractStructuredPatch(tur: unknown): DiffHunk[] | null {
+  if (!tur || typeof tur !== 'object') return null;
+  const sp = (tur as Record<string, unknown>).structuredPatch;
+  if (!Array.isArray(sp)) return null;
+  const hunks: DiffHunk[] = [];
+  for (const h of sp) {
+    if (!h || typeof h !== 'object') continue;
+    const r = h as Record<string, unknown>;
+    if (
+      typeof r.oldStart === 'number' &&
+      typeof r.oldLines === 'number' &&
+      typeof r.newStart === 'number' &&
+      typeof r.newLines === 'number' &&
+      Array.isArray(r.lines)
+    ) {
+      hunks.push({
+        oldStart: r.oldStart,
+        oldLines: r.oldLines,
+        newStart: r.newStart,
+        newLines: r.newLines,
+        lines: r.lines.filter((l): l is string => typeof l === 'string'),
+      });
+    }
+  }
+  return hunks;
+}
+
+function extractFilePath(input: Record<string, unknown>): string | null {
+  const fp = input.file_path;
+  if (typeof fp === 'string' && fp) return fp;
+  // NotebookEdit uses notebook_path.
+  const np = input.notebook_path;
+  if (typeof np === 'string' && np) return np;
+  return null;
+}
+
+function relativizeIfUnder(filePath: string, cwd: string | null): string | null {
+  if (!cwd) return null;
+  // 用 posix-style 简单前缀判断即可——session 是在 macOS/Linux/Windows
+  // 各自原生路径下记录的 cwd，不跨平台。
+  const normCwd = cwd.replace(/[\\/]+$/, '');
+  if (filePath === normCwd) return '.';
+  if (filePath.startsWith(normCwd + '/')) return filePath.slice(normCwd.length + 1);
+  if (filePath.startsWith(normCwd + '\\')) return filePath.slice(normCwd.length + 1);
+  return null;
+}
+
+function compareByTs(a: ModifiedFileOperation, b: ModifiedFileOperation): number {
+  if (a.ts && b.ts) return a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0;
+  if (a.ts) return -1;
+  if (b.ts) return 1;
+  return 0;
+}

package/server/lib/open-folder.ts

@@ -1,40 +1,47 @@
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-
-export interface OpenFolderResult {
-  ok: boolean;
-  error?: string;
-}
-
-export function openFolder(folderPath: string): OpenFolderResult {
-  try {
-    const st = fs.statSync(folderPath);
-    if (!st.isDirectory()) return { ok: false, error: 'not a directory' };
-  } catch {
-    return { ok: false, error: 'path not found' };
-  }
-
-  let cmd: string;
-  let args: string[];
-  if (process.platform === 'win32') {
-    cmd = 'explorer.exe';
-    args = [folderPath];
-  } else if (process.platform === 'darwin') {
-    cmd = 'open';
-    args = [folderPath];
-  } else {
-    cmd = 'xdg-open';
-    args = [folderPath];
-  }
-
-  try {
-    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
-    child.on('error', (err) => {
-      console.error(`[open-folder] spawn ${cmd} failed:`, err);
-    });
-    child.unref();
-    return { ok: true };
-  } catch (err) {
-    return { ok: false, error: (err as Error).message };
-  }
-}
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+export interface OpenResult {
+  ok: boolean;
+  error?: string;
+}
+
+export function openFolder(folderPath: string): OpenResult {
+  try {
+    const st = fs.statSync(folderPath);
+    if (!st.isDirectory()) return { ok: false, error: 'not a directory' };
+  } catch {
+    return { ok: false, error: 'path not found' };
+  }
+  return launch(folderPath);
+}
+
+export function openFile(filePath: string): OpenResult {
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile()) return { ok: false, error: 'not a file' };
+  } catch {
+    return { ok: false, error: 'path not found' };
+  }
+  return launch(filePath);
+}
+
+// 交给系统默认程序打开（文件 → 关联应用；文件夹 → 资源管理器），等价于双击。
+// detached + unref，不阻塞、不等子进程；spawn 失败在异步回调里只记日志。
+function launch(target: string): OpenResult {
+  let cmd: string;
+  if (process.platform === 'win32') cmd = 'explorer.exe';
+  else if (process.platform === 'darwin') cmd = 'open';
+  else cmd = 'xdg-open';
+
+  try {
+    const child = spawn(cmd, [target], { detached: true, stdio: 'ignore' });
+    child.on('error', (err) => {
+      console.error(`[open] spawn ${cmd} failed:`, err);
+    });
+    child.unref();
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: (err as Error).message };
+  }
+}