harness-mix 0.1.0

package/src/main/shared-contracts/capability.js

@@ -0,0 +1,35 @@
+// Capability：UI/Core 判断功能的唯一依据，禁止按 Harness 名称分支。
+// 结构按域分组，默认全部为 false，由 Adapter Manifest 显式声明开启。
+const CAPABILITY_GROUPS = {
+  conversation: ['streaming', 'reasoning', 'plan', 'compaction', 'attachments'],
+  interaction: ['approval', 'question', 'permissionMode'],
+  session: ['resume', 'fork', 'forkFromMessage'],
+  workspace: ['nativeDiff', 'nativePatch'],
+  model: ['selection', 'thinkingLevel'],
+  usage: ['tokens', 'context', 'cost'],
+};
+
+function createCapabilities(overrides = {}) {
+  const caps = {};
+  for (const [group, keys] of Object.entries(CAPABILITY_GROUPS)) {
+    caps[group] = {};
+    for (const key of keys) caps[group][key] = overrides[group]?.[key] === true;
+  }
+  return caps;
+}
+
+function validateCapabilities(caps) {
+  const errors = [];
+  if (!caps || typeof caps !== 'object' || Array.isArray(caps)) return ['capabilities must be an object'];
+  for (const [group, values] of Object.entries(caps)) {
+    if (!CAPABILITY_GROUPS[group]) { errors.push(`capabilities.${group} is not a known group`); continue; }
+    if (!values || typeof values !== 'object' || Array.isArray(values)) { errors.push(`capabilities.${group} must be an object`); continue; }
+    for (const [key, value] of Object.entries(values)) {
+      if (!CAPABILITY_GROUPS[group].includes(key)) errors.push(`capabilities.${group}.${key} is not a known capability`);
+      else if (typeof value !== 'boolean') errors.push(`capabilities.${group}.${key} must be a boolean`);
+    }
+  }
+  return errors;
+}
+
+module.exports = { CAPABILITY_GROUPS, createCapabilities, validateCapabilities };

package/src/main/shared-contracts/event.js

@@ -0,0 +1,55 @@
+const { newEventId } = require('./ids');
+const { createNativeRef, validateNativeRef } = require('./native-ref');
+
+// CoreEvent：所有 Harness 事件的统一出口。Adapter/Normalizer 只产出 CoreEvent，
+// Core 只消费 CoreEvent（Native Event 能力优先于 Host 推测，语义由 source 侧给出）。
+const EVENT_TYPES = [
+  'thread.created',
+  'thread.updated',
+  'thread.rolledBack',
+  'turn.started',
+  'turn.waiting',
+  'turn.resumed',
+  'turn.completed',
+  'turn.cancelled',
+  'turn.failed',
+  'item.started',
+  'item.delta',
+  'item.updated',
+  'item.completed',
+  'usage.updated',
+  'files.updated',
+  'plan.updated',
+];
+
+function createCoreEvent({ eventId, sequence, timestamp, threadId, turnId, itemId, source, nativeRef, type, payload } = {}, now = Date.now()) {
+  return {
+    eventId: eventId ?? newEventId(),
+    sequence: typeof sequence === 'number' ? sequence : null,
+    timestamp: typeof timestamp === 'number' ? timestamp : now,
+    threadId: threadId ?? null,
+    turnId: turnId ?? null,
+    itemId: itemId ?? null,
+    source: source ?? null,
+    nativeRef: createNativeRef(nativeRef),
+    type,
+    payload: payload && typeof payload === 'object' ? payload : {},
+  };
+}
+
+function validateCoreEvent(event) {
+  const errors = [];
+  if (!event || typeof event !== 'object') return ['event must be an object'];
+  if (typeof event.eventId !== 'string' || !event.eventId) errors.push('event.eventId is required');
+  if (event.sequence != null && typeof event.sequence !== 'number') errors.push('event.sequence must be a number or null');
+  if (typeof event.timestamp !== 'number') errors.push('event.timestamp must be a number');
+  if (typeof event.threadId !== 'string' || !event.threadId) errors.push('event.threadId is required');
+  if (event.turnId != null && typeof event.turnId !== 'string') errors.push('event.turnId must be a string or null');
+  if (event.itemId != null && typeof event.itemId !== 'string') errors.push('event.itemId must be a string or null');
+  if (!EVENT_TYPES.includes(event.type)) errors.push(`event.type must be one of ${EVENT_TYPES.join('/')}`);
+  if (event.payload != null && (typeof event.payload !== 'object' || Array.isArray(event.payload))) errors.push('event.payload must be an object');
+  errors.push(...validateNativeRef(event.nativeRef));
+  return errors;
+}
+
+module.exports = { EVENT_TYPES, createCoreEvent, validateCoreEvent };

package/src/main/shared-contracts/ids.js

@@ -0,0 +1,12 @@
+const { randomUUID } = require('node:crypto');
+
+// 统一 ID 生成：带前缀，便于在日志 / Fixture / NativeRef 中辨识实体类型。
+const newId = (prefix) => `${prefix}_${randomUUID()}`;
+
+module.exports = {
+  newThreadId: () => newId('thread'),
+  newTurnId: () => newId('turn'),
+  newItemId: () => newId('item'),
+  newEventId: () => newId('evt'),
+  newInteractionId: () => newId('int'),
+};

package/src/main/shared-contracts/index.js

@@ -0,0 +1,11 @@
+// Shared Contracts：Core、Adapter、Renderer 共享的数据协议唯一来源。
+module.exports = {
+  ...require('./ids'),
+  ...require('./thread'),
+  ...require('./turn'),
+  ...require('./item'),
+  ...require('./event'),
+  ...require('./native-ref'),
+  ...require('./capability'),
+  ...require('./interaction'),
+};

package/src/main/shared-contracts/interaction.js

@@ -0,0 +1,37 @@
+const { newInteractionId } = require('./ids');
+const { createNativeRef, validateNativeRef } = require('./native-ref');
+
+// Interaction：approval / question / permission / confirmation / input / select
+// 统一建模（PR 8 的 InteractionRouter 以此为协议）。第一阶段仅定义契约。
+const INTERACTION_TYPES = ['approval', 'question', 'permission', 'confirmation', 'input', 'select'];
+const INTERACTION_STATUS = ['pending', 'responded', 'cancelled', 'expired'];
+
+function createInteraction({ id, threadId, turnId, type, title, message, options, allowTextInput, nativeRef, status = 'pending' } = {}, now = Date.now()) {
+  return {
+    id: id ?? newInteractionId(),
+    threadId: threadId ?? null,
+    turnId: turnId ?? null,
+    type,
+    title: title ?? '',
+    message: message ?? '',
+    options: Array.isArray(options) ? options.map((o) => ({ id: String(o?.id ?? o), label: String(o?.label ?? o?.id ?? o) })) : [],
+    allowTextInput: allowTextInput === true,
+    nativeRef: createNativeRef(nativeRef),
+    status,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function validateInteraction(interaction) {
+  const errors = [];
+  if (!interaction || typeof interaction !== 'object') return ['interaction must be an object'];
+  if (typeof interaction.id !== 'string' || !interaction.id) errors.push('interaction.id is required');
+  if (!INTERACTION_TYPES.includes(interaction.type)) errors.push(`interaction.type must be one of ${INTERACTION_TYPES.join('/')}`);
+  if (!INTERACTION_STATUS.includes(interaction.status)) errors.push(`interaction.status must be one of ${INTERACTION_STATUS.join('/')}`);
+  if (!Array.isArray(interaction.options)) errors.push('interaction.options must be an array');
+  errors.push(...validateNativeRef(interaction.nativeRef));
+  return errors;
+}
+
+module.exports = { INTERACTION_TYPES, INTERACTION_STATUS, createInteraction, validateInteraction };

package/src/main/shared-contracts/item.js

@@ -0,0 +1,50 @@
+const { newItemId } = require('./ids');
+const { createNativeRef, validateNativeRef } = require('./native-ref');
+
+// Item：Turn 内的最小呈现单元。第一阶段类型清单（后续只增不改语义）。
+const ITEM_TYPES = [
+  'user_message',
+  'agent_message',
+  'reasoning',
+  'tool_call',
+  'file_change',
+  'approval',
+  'question',
+  'plan',
+  'usage',
+  'notice',
+];
+
+// started：刚建立；streaming：持续接收 delta；completed/cancelled/error：终态。
+const ITEM_STATUS = ['started', 'streaming', 'completed', 'cancelled', 'error'];
+const TERMINAL_ITEM_STATUS = ['completed', 'cancelled', 'error'];
+
+function createItem({ id, threadId, turnId, type, status = 'started', nativeRef, ...rest } = {}, now = Date.now()) {
+  return {
+    id: id ?? newItemId(),
+    threadId: threadId ?? null,
+    turnId: turnId ?? null,
+    type,
+    status,
+    createdAt: now,
+    updatedAt: now,
+    nativeRef: createNativeRef(nativeRef),
+    ...rest,
+  };
+}
+
+function validateItem(item) {
+  const errors = [];
+  if (!item || typeof item !== 'object') return ['item must be an object'];
+  if (typeof item.id !== 'string' || !item.id) errors.push('item.id is required');
+  if (typeof item.threadId !== 'string' || !item.threadId) errors.push('item.threadId is required');
+  if (item.turnId != null && typeof item.turnId !== 'string') errors.push('item.turnId must be a string or null');
+  if (!ITEM_TYPES.includes(item.type)) errors.push(`item.type must be one of ${ITEM_TYPES.join('/')}`);
+  if (!ITEM_STATUS.includes(item.status)) errors.push(`item.status must be one of ${ITEM_STATUS.join('/')}`);
+  if (typeof item.createdAt !== 'number') errors.push('item.createdAt must be a number');
+  if (typeof item.updatedAt !== 'number') errors.push('item.updatedAt must be a number');
+  errors.push(...validateNativeRef(item.nativeRef));
+  return errors;
+}
+
+module.exports = { ITEM_TYPES, ITEM_STATUS, TERMINAL_ITEM_STATUS, createItem, validateItem };

package/src/main/shared-contracts/native-ref.js

@@ -0,0 +1,24 @@
+// NativeRef：Core 实体与 Harness 原生身份之间的桥。
+// 所有字段均可选，但绝不允许丢失已知的原生 ID（执行约束 #8/#9）。
+const NATIVE_REF_FIELDS = ['sessionId', 'turnId', 'itemId', 'toolCallId', 'interactionId', 'checkpointId'];
+
+function createNativeRef(ref = {}) {
+  const out = {};
+  for (const field of NATIVE_REF_FIELDS) {
+    if (typeof ref[field] === 'string' && ref[field]) out[field] = ref[field];
+  }
+  return out;
+}
+
+function validateNativeRef(ref) {
+  const errors = [];
+  if (ref == null) return errors; // 整体可选
+  if (typeof ref !== 'object' || Array.isArray(ref)) return ['nativeRef must be an object'];
+  for (const [key, value] of Object.entries(ref)) {
+    if (!NATIVE_REF_FIELDS.includes(key)) errors.push(`nativeRef.${key} is not a known field`);
+    else if (typeof value !== 'string' || !value) errors.push(`nativeRef.${key} must be a non-empty string`);
+  }
+  return errors;
+}
+
+module.exports = { NATIVE_REF_FIELDS, createNativeRef, validateNativeRef };

package/src/main/shared-contracts/thread.js

@@ -0,0 +1,36 @@
+const { newThreadId } = require('./ids');
+const { createNativeRef, validateNativeRef } = require('./native-ref');
+
+// Thread：一次任务会话的 Core 侧身份。与具体 Harness 无关。
+const THREAD_STATUS = ['idle', 'running', 'waiting', 'error'];
+
+function createThread({ id, workspaceId, harnessId, nativeSessionRef, status = 'idle', metadata } = {}, now = Date.now()) {
+  return {
+    id: id ?? newThreadId(),
+    workspaceId: workspaceId ?? null,
+    harnessId: harnessId ?? null,
+    nativeSessionRef: createNativeRef(nativeSessionRef),
+    status,
+    activeTurnId: null,
+    createdAt: now,
+    updatedAt: now,
+    metadata: metadata && typeof metadata === 'object' ? { ...metadata } : {},
+  };
+}
+
+function validateThread(thread) {
+  const errors = [];
+  if (!thread || typeof thread !== 'object') return ['thread must be an object'];
+  if (typeof thread.id !== 'string' || !thread.id) errors.push('thread.id is required');
+  if (thread.workspaceId != null && typeof thread.workspaceId !== 'string') errors.push('thread.workspaceId must be a string');
+  if (thread.harnessId != null && typeof thread.harnessId !== 'string') errors.push('thread.harnessId must be a string');
+  if (!THREAD_STATUS.includes(thread.status)) errors.push(`thread.status must be one of ${THREAD_STATUS.join('/')}`);
+  if (thread.activeTurnId != null && typeof thread.activeTurnId !== 'string') errors.push('thread.activeTurnId must be a string or null');
+  if (typeof thread.createdAt !== 'number') errors.push('thread.createdAt must be a number');
+  if (typeof thread.updatedAt !== 'number') errors.push('thread.updatedAt must be a number');
+  if (thread.metadata != null && (typeof thread.metadata !== 'object' || Array.isArray(thread.metadata))) errors.push('thread.metadata must be an object');
+  errors.push(...validateNativeRef(thread.nativeSessionRef));
+  return errors;
+}
+
+module.exports = { THREAD_STATUS, createThread, validateThread };

package/src/main/shared-contracts/turn.js

@@ -0,0 +1,54 @@
+const { newTurnId } = require('./ids');
+const { createNativeRef, validateNativeRef } = require('./native-ref');
+
+// Turn：一次独立执行。生命周期只能由 TurnManager 推进（执行约束：状态不得由
+// Renderer / Transcript / Adapter 推断）。
+const TURN_STATUS = ['created', 'starting', 'running', 'waiting_interaction', 'completed', 'cancelled', 'error'];
+const TERMINAL_TURN_STATUS = ['completed', 'cancelled', 'error'];
+
+// 合法状态机。终态不允许再迁移（例如 completed → running 必须拒绝）。
+const TURN_TRANSITIONS = {
+  created: ['starting', 'cancelled', 'error'],
+  starting: ['running', 'waiting_interaction', 'completed', 'cancelled', 'error'],
+  running: ['waiting_interaction', 'completed', 'cancelled', 'error'],
+  waiting_interaction: ['running', 'completed', 'cancelled', 'error'],
+  completed: [],
+  cancelled: [],
+  error: [],
+};
+
+function canTransition(from, to) {
+  return (TURN_TRANSITIONS[from] ?? []).includes(to);
+}
+
+function createTurn({ id, threadId, nativeTurnRef, status = 'created', itemIds, lastSequence, error } = {}, now = Date.now()) {
+  return {
+    id: id ?? newTurnId(),
+    threadId: threadId ?? null,
+    nativeTurnRef: createNativeRef(nativeTurnRef),
+    status,
+    startedAt: null,
+    completedAt: null,
+    itemIds: Array.isArray(itemIds) ? [...itemIds] : [],
+    lastSequence: typeof lastSequence === 'number' ? lastSequence : 0,
+    error: error ?? null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function validateTurn(turn) {
+  const errors = [];
+  if (!turn || typeof turn !== 'object') return ['turn must be an object'];
+  if (typeof turn.id !== 'string' || !turn.id) errors.push('turn.id is required');
+  if (typeof turn.threadId !== 'string' || !turn.threadId) errors.push('turn.threadId is required');
+  if (!TURN_STATUS.includes(turn.status)) errors.push(`turn.status must be one of ${TURN_STATUS.join('/')}`);
+  if (turn.startedAt != null && typeof turn.startedAt !== 'number') errors.push('turn.startedAt must be a number or null');
+  if (turn.completedAt != null && typeof turn.completedAt !== 'number') errors.push('turn.completedAt must be a number or null');
+  if (!Array.isArray(turn.itemIds)) errors.push('turn.itemIds must be an array');
+  if (typeof turn.lastSequence !== 'number') errors.push('turn.lastSequence must be a number');
+  errors.push(...validateNativeRef(turn.nativeTurnRef));
+  return errors;
+}
+
+module.exports = { TURN_STATUS, TERMINAL_TURN_STATUS, TURN_TRANSITIONS, canTransition, createTurn, validateTurn };

package/src/main/workspace/core-review.js

@@ -0,0 +1,53 @@
+const { diff } = require('./diff');
+
+// Snapshot acquisition/undo stay in Workspace. Core stores their presentation.
+async function projectReview(runtime, thread, message, record) {
+  const core = runtime.core;
+  if (!core?.getTurn(message.coreTurnId)) throw new Error('审查记录缺少 Core Turn，请重新加载任务完成历史迁移');
+
+  const hasNativePatch = Boolean(
+    runtime.getCapabilities?.(thread.harnessId)?.conversation?.nativePatch ||
+    runtime.adapters?.get(thread.harnessId)?.manifest?.capabilities?.nativePatch
+  );
+
+  let changes = record.changes;
+  if (hasNativePatch) {
+    // 原生 Codex 协议直通：若该会话有原生 patch 能力，当前轮次文件变更以原生汇报为准，消除同目录并发干扰
+    const nativeItems = core.getItemsForTurn(message.coreTurnId).filter(item => item.type === 'file_change' && item.source === 'native');
+    const nativePaths = new Set(nativeItems.map(item => item.path));
+    changes = changes.filter(change => nativePaths.has(change.path));
+  }
+
+  core.dispatch({ threadId: thread.id, turnId: message.coreTurnId, type: 'files.updated', payload: {
+    source: 'snapshot', replace: true,
+    changes: changes.map(change => ({
+      path: change.path, changeType: !change.before ? 'added' : !change.after ? 'deleted' : 'modified',
+      before: change.before?.text ?? '', after: change.after?.text ?? '',
+      patch: diff(change.before?.text, change.after?.text), complete: true,
+      added: change.added, removed: change.removed, undone: change.undone === true,
+    })),
+  } });
+  message.coreItems = structuredClone(core.getItemsForTurn(message.coreTurnId));
+  const summaryRecord = { ...record, changes };
+  const summary = { ...runtime.reviews.summary(summaryRecord), files: message.coreItems.filter(item => item.type === 'file_change') };
+  message.coreReview = structuredClone(summary);
+  return summary;
+}
+
+async function readReview(runtime, thread, message, file) {
+  const id = message.review?.id ?? message.reviewId;
+  let record;
+  for (let attempt = 0; ; attempt++) {
+    const revision = thread.fileRevision;
+    record = await runtime.reviews.preview(id);
+    if (revision === thread.fileRevision) break;
+    if (attempt === 4) throw new Error('文件仍在变化，请稍后刷新审查');
+  }
+  const summary = await projectReview(runtime, thread, message, record);
+  if (!file) return summary;
+  const item = summary.files.find(item => item.path === file);
+  if (!item) throw new Error('文件不在本轮审查记录中');
+  return { path: item.path, undone: item.undone, ...(item.patch?.rows ? item.patch : diff(item.before, item.after)) };
+}
+
+module.exports = { projectReview, readReview };

package/src/main/workspace/diff.js

@@ -0,0 +1,27 @@
+// Bounded line LCS; large inputs use a content-exact coarse replacement.
+function diff(before = '', after = '') {
+  const lines = s => s ? s.match(/[^\n]*\n|[^\n]+$/g) ?? [] : [];
+  const a = lines(before), b = lines(after), rows = [];
+  let old = 1, next = 1;
+  const add = (kind, text) => rows.push({ kind, text: text.replace(/\r?\n$/, ''), old: kind === 'add' ? null : old++, next: kind === 'remove' ? null : next++ });
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) { add('same', a[start]); start++; }
+  let x = a.length, y = b.length;
+  while (x > start && y > start && a[x - 1] === b[y - 1]) { x--; y--; }
+  const n = x - start, m = y - start, coarse = n * m > 1_000_000;
+  if (coarse) {
+    a.slice(start, x).forEach(s => add('remove', s)); b.slice(start, y).forEach(s => add('add', s));
+  } else {
+    const table = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) table[i][j] = a[start + i] === b[start + j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+    let i = 0, j = 0;
+    while (i < n || j < m) {
+      if (i < n && j < m && a[start + i] === b[start + j]) { add('same', a[start + i++]); j++; }
+      else if (j < m && (i === n || table[i][j + 1] > table[i + 1][j])) add('add', b[start + j++]);
+      else add('remove', a[start + i++]);
+    }
+  }
+  a.slice(x).forEach(s => add('same', s));
+  return { rows, added: rows.filter(r => r.kind === 'add').length, removed: rows.filter(r => r.kind === 'remove').length, coarse };
+}
+module.exports = { diff };

package/src/main/workspace/file-changes.js

@@ -0,0 +1,21 @@
+const path = require('node:path');
+const { diff } = require('./diff');
+
+function canonicalChanges(cwd, changes = [], previous = []) {
+  return changes.map(change => {
+    const absolute = path.resolve(cwd, change.path);
+    const relative = path.relative(cwd, absolute).replace(/\\/g, '/');
+    if (!relative || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative)) throw new Error('FileChange is outside the workspace');
+    const old = previous.find(item => item.path === relative);
+    if (old && typeof old.before === 'string' && typeof old.after === 'string') {
+      if (change.before === old.after) {
+        change = { ...change, before: old.before, changeType: old.changeType === 'added' && change.changeType !== 'deleted' ? 'added' : change.changeType };
+      } else if (change.before !== old.before) {
+        change = { ...change, complete: false };
+      }
+    }
+    const patch = typeof change.before === 'string' && typeof change.after === 'string' ? diff(change.before, change.after) : change.patch;
+    return { ...change, path: relative, ...(patch ? { patch, added: patch.added, removed: patch.removed } : {}) };
+  });
+}
+module.exports = { canonicalChanges };

package/src/main/workspace/files.js

@@ -0,0 +1,65 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const OMIT = /^(node_modules|\.git|\.venv|venv|dist|build|output|__pycache__|\.next|\.idea)$/i;
+const PRIVATE = /(^\.env($|\.)|^\.ssh$|^\.aws$|credentials|secrets?|^auth\.json$|^settings\.json$|^id_rsa|\.(pem|key|pfx|p12)$)/i;
+const hash = data => createHash('sha256').update(data).digest('hex');
+const inside = (root, target) => { const relative = path.relative(root, target); return !relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative); };
+
+async function resolveFile(root, relative = '') {
+  root = await fs.realpath(root);
+  if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.includes(':')) throw Error('仅允许项目内相对路径');
+  const target = path.resolve(root, relative);
+  if (!inside(root, target)) throw Error('路径超出项目范围');
+  let cursor = root;
+  for (const part of path.relative(root, target).split(path.sep).filter(Boolean)) {
+    if (PRIVATE.test(part) || OMIT.test(part)) throw Error('该路径不参与桌面文件预览与快照');
+    cursor = path.join(cursor, part);
+    try { if ((await fs.lstat(cursor)).isSymbolicLink()) throw Error('不跟随符号链接或目录联接'); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+  return target;
+}
+
+async function readText(root, relative) {
+  const target = await resolveFile(root, relative);
+  const stat = await fs.stat(target);
+  if (!stat.isFile() || stat.size > 1024 * 1024) throw Error('仅预览 1 MB 以内文本文件');
+  const buffer = await fs.readFile(target);
+  const text = buffer.toString('utf8');
+  if (buffer.includes(0) || !Buffer.from(text).equals(buffer)) throw Error('二进制或非 UTF-8 文件不参与预览');
+  return { text, hash: hash(buffer), mode: stat.mode };
+}
+
+async function list(root, relative = '') {
+  const entries = await fs.readdir(await resolveFile(root, relative), { withFileTypes: true });
+  return entries.filter(e => !e.isSymbolicLink() && !OMIT.test(e.name) && !PRIVATE.test(e.name))
+    .sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name))
+    .slice(0, 1500).map(e => ({ name: e.name, path: path.join(relative, e.name), directory: e.isDirectory() }));
+}
+
+async function snapshot(root) {
+  const names = [], files = Object.create(null), skipped = [];
+  let bytes = 0, entries = 0;
+  async function walk(relative) {
+    const all = await fs.readdir(await resolveFile(root, relative), { withFileTypes: true });
+    for (const entry of all) {
+      if (++entries > 15000) throw Error('项目超过 15,000 个目录项，未建立完整快照');
+      if (OMIT.test(entry.name) || PRIVATE.test(entry.name) || entry.isSymbolicLink()) continue;
+      const file = path.join(relative, entry.name);
+      if (entry.isDirectory()) await walk(file);
+      else if (entry.isFile()) {
+        names.push(file);
+        try {
+          const value = await readText(root, file);
+          bytes += Buffer.byteLength(value.text);
+          if (bytes > 24 * 1024 * 1024) throw Error('快照超过 24 MB');
+          files[file] = value;
+        } catch (e) { skipped.push(file); }
+      }
+    }
+  }
+  await walk('');
+  return { names, files, skipped };
+}
+module.exports = { resolveFile, readText, list, snapshot, hash };

package/src/main/workspace/git.js

@@ -0,0 +1,73 @@
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const path = require('node:path');
+const { createItem } = require('../shared-contracts');
+const run = promisify(execFile);
+
+async function git(cwd, args) {
+  try {
+    return (await run('git', ['--no-pager', '-c', 'core.quotepath=false', ...args], {
+      cwd, windowsHide: true, timeout: 30000, maxBuffer: 8 * 1024 * 1024,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_LITERAL_PATHSPECS: '1' },
+    })).stdout;
+  } catch (e) { throw Error(e.code === 'ENOENT' ? '未找到 Git，请安装 Git for Windows。' : (e.stderr || e.message).trim()); }
+}
+async function repository(cwd) {
+  const root = (await git(cwd, ['rev-parse', '--show-toplevel'])).trim();
+  if (path.resolve(root).toLowerCase() !== path.resolve(cwd).toLowerCase()) throw Error('请将 Git 仓库根目录作为项目打开：' + root);
+  return root;
+}
+function parseStatus(raw) {
+  const entries = raw.split('\0'), files = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]; if (!entry) continue;
+    const x = entry[0], y = entry[1], file = entry.slice(3);
+    const from = /[RC]/.test(x + y) ? entries[++i] : undefined;
+    files.push({ path: file, from, index: x, worktree: y, untracked: x === '?', staged: ![' ', '?', '!'].includes(x), changed: y !== ' ', conflict: x === 'U' || y === 'U' || ['AA', 'DD'].includes(x + y) });
+  }
+  return files;
+}
+async function status(cwd) {
+  await repository(cwd);
+  const [raw, branch, log] = await Promise.all([
+    git(cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=all']),
+    git(cwd, ['symbolic-ref', '--short', '-q', 'HEAD']).catch(() => git(cwd, ['rev-parse', '--short', 'HEAD'])),
+    git(cwd, ['log', '-15', '--format=%h%x00%s%x00%an%x00%ar']).catch(() => ''),
+  ]);
+  return { root: cwd, branch: branch.trim(), files: parseStatus(raw), log: log.trim().split('\n').filter(Boolean).map(row => { const [hash, subject, author, age] = row.split('\0'); return { hash, subject, author, age }; }) };
+}
+async function fileEntry(cwd, file) {
+  if (typeof file !== 'string' || path.isAbsolute(file) || file.includes('\0') || file.includes(':') || file.split(/[\\/]/).includes('..')) throw Error('无效 Git 文件路径');
+  const entry = (await status(cwd)).files.find(f => f.path === file);
+  if (!entry) throw Error('文件状态已改变，请刷新 Git 面板');
+  return entry;
+}
+async function diff(cwd, file, staged) {
+  const entry = await fileEntry(cwd, file);
+  const text = entry.untracked ? '新文件尚未暂存。可在文件面板查看内容，暂存后查看 Git 差异。'
+    : await git(cwd, ['diff', '--no-ext-diff', '--no-textconv', ...(staged ? ['--cached'] : []), '--', ...(entry.from ? [entry.from, file] : [file])]);
+  const item = createItem({ id: `git_${cwd}_${staged ? 'index' : 'worktree'}_${file}`, threadId: `workspace_${cwd}`,
+    type: 'file_change', status: 'completed', source: 'git', path: file, previousPath: entry.from,
+    changeType: entry.untracked || (staged ? entry.index : entry.worktree) === 'A' ? 'added' : (staged ? entry.index : entry.worktree) === 'D' ? 'deleted' : entry.from ? 'renamed' : 'modified',
+    scope: staged ? 'index' : 'worktree', patch: { format: 'unified', text }, complete: !entry.untracked,
+  });
+  return { item };
+}
+async function mutate(cwd, action, input) {
+  if (action === 'init') { await git(cwd, ['init']); return status(cwd); }
+  await repository(cwd);
+  if (action === 'commit') {
+    if (typeof input.message !== 'string' || !input.message.trim()) throw Error('请输入提交说明');
+    await git(cwd, ['commit', '-m', input.message]);
+  } else {
+    const entry = await fileEntry(cwd, input.path);
+    const paths = entry.from ? [entry.path, entry.from] : [entry.path];
+    if (action === 'stage') await git(cwd, ['add', '--', ...paths]);
+    else if (action === 'unstage') {
+      const hasHead = await git(cwd, ['rev-parse', '--verify', 'HEAD']).then(() => true, () => false);
+      await git(cwd, hasHead ? ['reset', '-q', 'HEAD', '--', ...paths] : ['rm', '--cached', '--', ...paths]);
+    } else throw Error('不支持的 Git 操作');
+  }
+  return status(cwd);
+}
+module.exports = { status, diff, mutate, parseStatus };

package/src/main/workspace/ipc.js

@@ -0,0 +1,50 @@
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const files = require('./files');
+const { CommandTerminal } = require('./terminal');
+const git = require('./git');
+
+function registerWorkspace({ ipcMain, runtime, emit, roots }) {
+  const terminal = new CommandTerminal(emit);
+  async function root(input) {
+    const thread = runtime.threads.find(t => t.id === input.threadId);
+    const candidate = thread?.cwd ?? input.cwd;
+    const allowed = [...roots, ...runtime.threads.map(t => t.cwd)];
+    if (typeof candidate !== 'string' || !allowed.some(p => path.resolve(p).toLowerCase() === path.resolve(candidate).toLowerCase())) throw Error('请先选择项目目录');
+    return fs.realpath(candidate);
+  }
+  ipcMain.handle('workspace:list', async (_, input) => files.list(await root(input), input.path));
+  ipcMain.handle('git:status', async (_, input) => git.status(await root(input)));
+  ipcMain.handle('git:diff', async (_, input) => git.diff(await root(input), input.path, input.staged === true));
+  ipcMain.handle('git:mutate', async (_, input) => {
+    const cwd = await root(input);
+    if (runtime.threads.some(t => path.resolve(t.cwd).toLowerCase() === cwd.toLowerCase() && ['working', 'opening'].includes(t.status)) || terminal.list(cwd).some(s => s.running)) throw Error('请等待项目任务和终端命令结束后再修改 Git 状态');
+    return git.mutate(cwd, input.action, input);
+  });
+  ipcMain.handle('workspace:read', async (_, input) => ({ path: input.path, ...(await files.readText(await root(input), input.path)) }));
+  ipcMain.handle('workspace:review', async (_, input) => {
+    const thread = runtime.threads.find(t => t.id === input.threadId);
+    const message = thread?.messages.find(m => m.id === input.messageId);
+    const id = message?.review?.id ?? message?.reviewId;
+    if (!id) throw Error('该轮尚无文件快照');
+    return runtime.readReview(thread, message, input.path);
+  });
+  ipcMain.handle('workspace:undo', async (_, input) => {
+    const cwd = await root(input);
+    if (terminal.list(cwd).some(s => s.running)) throw Error('请先停止该项目的终端命令');
+    return runtime.undoFile(input.threadId, input.messageId, input.path);
+  });
+  ipcMain.handle('terminal:list', async (_, input) => terminal.list(await root(input)));
+  ipcMain.handle('terminal:run', async (_, input) => {
+    const cwd = await root(input);
+    if (runtime.threads.some(t => path.resolve(t.cwd).toLowerCase() === cwd.toLowerCase() && t.status === 'working')) throw Error('请等待项目任务结束后再运行手动命令');
+    return terminal.run(cwd, input.command);
+  });
+  ipcMain.handle('terminal:stop', async (_, input) => {
+    const list = terminal.list(await root(input));
+    if (!list.some(s => s.id === input.id)) throw Error('终端不属于当前项目');
+    await terminal.stop(input.id);
+  });
+  return terminal;
+}
+module.exports = { registerWorkspace };