zen-gitsync 2.14.2 → 2.14.3

package/src/ui/server/routes/workbench/llmClient.js

@@ -0,0 +1,214 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// OpenAI 兼容 LLM 客户端封装。
+// 拆分自原 routes/workbench.js 454-635 行。
+//
+// 两个核心 API：
+//   - callLlmJson(model, prompt, opts)         非流式，强制 json_object 返回
+//   - callLlmStream(model, input, onDelta, opts)  SSE 流式，回调推送 thinking/content delta
+// 配套：
+//   - callLlmJsonWithRetry  自动重试一次
+//   - cloneMsgContent       深拷贝消息 content（避免外部 mutation 污染请求）
+
+import { stripThinkingBlocks, extractFirstJsonObject } from './jsonParse.js';
+
+// 非流式调用 LLM，要求返回 JSON 对象。
+// 失败时抛错；成功时返回已 parse 的对象。
+//
+// 图片支持：opts.images 是 data URL 数组（如 'data:image/png;base64,...'）。
+// 非多模态模型遇到 image_url 会忽略图片块，相当于退化成纯文本，不会报错。
+export async function callLlmJson(model, prompt, opts = {}) {
+  const { timeoutMs = 60000, images = [] } = opts;
+  const { default: fetch } = await import('node-fetch').catch(() => ({ default: globalThis.fetch }));
+  const url = `${String(model.baseURL || '').replace(/\/$/, '')}/chat/completions`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (model.apiKey) headers['Authorization'] = `Bearer ${model.apiKey}`;
+
+  let userContent;
+  if (Array.isArray(images) && images.length > 0) {
+    userContent = [
+      { type: 'text', text: prompt },
+      ...images.map(img => ({ type: 'image_url', image_url: { url: img } }))
+    ];
+  } else {
+    userContent = prompt;
+  }
+
+  const body = JSON.stringify({
+    model: model.model,
+    messages: [{ role: 'user', content: userContent }],
+    temperature: 0.4,
+    response_format: { type: 'json_object' },
+    stream: false,
+  });
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(url, { method: 'POST', headers, body, signal: controller.signal });
+    const data = await resp.json().catch(() => ({}));
+    if (!resp.ok) throw new Error(data?.error?.message || `HTTP ${resp.status}`);
+    const content = data?.choices?.[0]?.message?.content || '';
+    if (!content.trim()) {
+      throw new Error('LLM 返回内容为空');
+    }
+    try {
+      const cleaned = stripThinkingBlocks(content);
+      return JSON.parse(extractFirstJsonObject(cleaned));
+    } catch (err) {
+      const snippet = content.length > 500 ? content.slice(0, 500) + '…' : content;
+      throw new Error(`LLM 返回非 JSON 或被截断：${err.message}；原始内容片段：${snippet}`);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// 自动重试一次的包装。重试间隔 800ms * (i+1)。
+export async function callLlmJsonWithRetry(model, prompt, opts = {}, retries = 1) {
+  let lastErr;
+  for (let i = 0; i <= retries; i++) {
+    try {
+      return await callLlmJson(model, prompt, opts);
+    } catch (err) {
+      lastErr = err;
+      if (i < retries) {
+        await new Promise(r => setTimeout(r, 800 * (i + 1)));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+// 深拷贝 message content（字符串直接返回，数组浅拷贝每个 part）
+export function cloneMsgContent(c) {
+  if (typeof c === 'string') return c;
+  if (Array.isArray(c)) return c.map(p => ({ ...p }));
+  return c;
+}
+
+/**
+ * 流式调用 OpenAI 兼容 LLM。每收到一个 chunk 调 onDelta 回调。
+ * onDelta 接收 { thinking?: string, content?: string }，二选一。
+ *   - reasoning_content / reasoning：部分模型（如 deepseek）放在 delta.reasoning_content
+ *   - reasoning / reasoning_text：openai o1 风格
+ *   - content：普通输出
+ * 返回 { content: string, aborted: boolean }。
+ *
+ * input 支持两种形态(判别 union):
+ *   - string: 旧模式，拼成单条 user message，支持 opts.images 多模态
+ *   - ChatMsg[]: 新模式(对话拆分)，直接作为 messages 发送；opts.images/systemPrompt 忽略
+ *
+ * 取消支持：opts.signal 是外部 AbortController.signal，触发后 controller.abort()，
+ * 函数返回 { aborted: true }，不抛错——上层决定怎么处理。
+ */
+export async function callLlmStream(model, input, onDelta, opts = {}) {
+  const { maxTokens = 2000, timeoutMs = 600000, signal, images = [], systemPrompt } = opts;
+  const { default: fetch } = await import('node-fetch').catch(() => ({ default: globalThis.fetch }));
+  const url = `${String(model.baseURL || '').replace(/\/$/, '')}/chat/completions`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (model.apiKey) headers['Authorization'] = `Bearer ${model.apiKey}`;
+
+  // 判别 input: string(旧,直接拆分)或 messages 数组(新,对话拆分)
+  let messages;
+  if (Array.isArray(input)) {
+    // messages 模式: 深拷贝避免外部 mutation 污染 LLM 请求
+    messages = input.map(m => ({ role: m.role, content: cloneMsgContent(m.content) }));
+  } else {
+    // 旧模式: string prompt 拼成单条 user message,支持多模态
+    const text = String(input || '');
+    let userContent;
+    if (Array.isArray(images) && images.length > 0) {
+      userContent = [
+        { type: 'text', text },
+        ...images.map(img => ({ type: 'image_url', image_url: { url: img } }))
+      ];
+    } else {
+      userContent = text;
+    }
+    messages = [];
+    if (systemPrompt) messages.push({ role: 'system', content: String(systemPrompt) });
+    messages.push({ role: 'user', content: userContent });
+  }
+
+  const body = JSON.stringify({
+    model: model.model,
+    messages,
+    max_tokens: maxTokens,
+    temperature: 0.4,
+    // 注意：stream: true 模式下不能同时使用 response_format:{type:'json_object'}，
+    // 部分 provider 会在收到两个一起时报错/静默卡住。改在 prompt 里约束 JSON 输出即可。
+    stream: true,
+  });
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const onAbort = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) controller.abort();
+    else signal.addEventListener('abort', onAbort);
+  }
+
+  let fullContent = '';
+  let aborted = false;
+  try {
+    const resp = await fetch(url, { method: 'POST', headers, body, signal: controller.signal });
+    if (!resp.ok || !resp.body) {
+      const errText = await resp.text().catch(() => '');
+      throw new Error(errText || `HTTP ${resp.status}`);
+    }
+
+    // SSE 格式：每行 "data: {...}"，最后 "data: [DONE]"
+    const decoder = new TextDecoder('utf-8');
+    let buf = '';
+    for await (const chunk of resp.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      const lines = buf.split('\n');
+      buf = lines.pop() ?? '';
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith('data:')) continue;
+        const payload = trimmed.slice(5).trim();
+        if (payload === '[DONE]') continue;
+        try {
+          const evt = JSON.parse(payload);
+          const delta = evt.choices?.[0]?.delta || {};
+          // thinking 在不同 provider 字段名不同，全部尝试
+          const thinkingChunk = delta.reasoning_content
+            || delta.reasoning
+            || delta.reasoning_text
+            || '';
+          const contentChunk = delta.content || '';
+          if (thinkingChunk) onDelta({ thinking: thinkingChunk });
+          if (contentChunk) {
+            fullContent += contentChunk;
+            onDelta({ content: contentChunk });
+          }
+        } catch { /* 跳过无法解析的行 */ }
+      }
+    }
+  } catch (err) {
+    if (err?.name === 'AbortError' || controller.signal.aborted) {
+      aborted = true;
+      // 中断不算错误——上层会决定怎么处理
+    } else {
+      throw err;
+    }
+  } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
+  }
+  return { content: fullContent, aborted };
+}

package/src/ui/server/routes/workbench/projectScan.js

@@ -0,0 +1,191 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 子项目识别 / manifest 读取 / 目录树扫描。
+// 拆分自原 routes/workbench.js 313-390 行 + 1000-1079 行。
+//
+// 用途：AI 生成架构说明时把项目结构喂给 LLM。
+// 设计要点：
+//   - 只读 manifest 与 README，不读源码（避免上下文爆炸）
+//   - findSubProjects 递归找 .git / manifest；A 是 B 的祖先时只保留 B
+//   - 大文件用 safeReadFile 截断到 maxBytes
+
+import fsp from 'fs/promises';
+import path from 'path';
+import { SKIP_DIRS, MANIFEST_FILES } from './shared.js';
+
+// 轻量级：仅告诉 LLM 项目的主 manifest 是什么（用于 AI 拆分时让 LLM 知道项目类型）。
+// 不读内容，只 stat 存在性——拆分子任务不需要细节。
+export async function detectProjectManifest(projectPath) {
+  if (!projectPath) return '';
+  for (const f of MANIFEST_FILES) {
+    try {
+      const stat = await fsp.stat(path.join(projectPath, f));
+      if (stat.isFile()) return f;
+    } catch { /* 不存在，继续 */ }
+  }
+  return '';
+}
+
+// 读取项目所有 manifest 内容（限 20KB / 文件），返回 { [filename]: content }
+export async function readProjectManifest(projectPath) {
+  const out = {};
+  for (const f of MANIFEST_FILES) {
+    const p = path.join(projectPath, f);
+    try {
+      const stat = await fsp.stat(p);
+      if (!stat.isFile()) continue;
+      const content = stat.size > 20000
+        ? (await safeReadFile(p, 20000))
+        : (await fsp.readFile(p, 'utf8'));
+      out[f] = content;
+    } catch { /* 不存在就跳过 */ }
+  }
+  return out;
+}
+
+// 安全读文件：超 maxBytes 时只读前 maxBytes 字节，避免巨型文件把上下文打爆
+export async function safeReadFile(filePath, maxBytes = 200000) {
+  try {
+    const stat = await fsp.stat(filePath);
+    if (stat.size > maxBytes) {
+      const buf = Buffer.alloc(maxBytes);
+      const fd = await fsp.open(filePath, 'r');
+      await fd.read(buf, 0, maxBytes, 0);
+      await fd.close();
+      return buf.toString('utf8').slice(0, maxBytes);
+    }
+    return await fsp.readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+// 列出项目目录树（默认 2 层），过滤掉 node_modules / dist / .git 等
+export async function listDirTree(projectPath, maxDepth = 2, maxEntries = 400) {
+  const lines = [];
+  async function walk(dir, depth) {
+    if (depth > maxDepth || lines.length >= maxEntries) return;
+    let entries;
+    try { entries = await fsp.readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    const filtered = entries.filter(e => {
+      if (e.name.startsWith('.')) return false;
+      if (['node_modules', 'dist', 'build', '.next', '.nuxt', '__pycache__', 'target', 'out', 'coverage', 'vendor'].includes(e.name)) return false;
+      return true;
+    });
+    const indent = '  '.repeat(depth);
+    for (const e of filtered) {
+      if (lines.length >= maxEntries) return;
+      if (e.isDirectory()) {
+        lines.push(`${indent}${e.name}/`);
+        await walk(path.join(dir, e.name), depth + 1);
+      } else if (e.isFile()) {
+        lines.push(`${indent}${e.name}`);
+      }
+    }
+  }
+  await walk(projectPath, 0);
+  return lines.join('\n');
+}
+
+/**
+ * 递归识别子项目：找含 .git 目录或 manifest 文件的目录。
+ * A 是 B 的祖先时只保留更深的 B（避免父项目重复包含子项目）。
+ *
+ * @param {string} projectPath 项目根路径
+ * @param {object} [opts]
+ * @param {number} [opts.maxDepth=4] 最大递归深度
+ * @returns {Promise<Array<{root, name, manifests, readme, dirTree}>>}
+ */
+export async function findSubProjects(projectPath, opts = {}) {
+  const { maxDepth = 4 } = opts;
+  const candidates = [];
+
+  async function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = await fsp.readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+
+    let hasManifest = false;
+    let hasGit = false;
+    const subDirs = [];
+    for (const e of entries) {
+      if (!e.isDirectory() && !e.isFile()) continue;
+      if (e.name.startsWith('.')) {
+        if (e.name === '.git' && e.isDirectory()) hasGit = true;
+        continue;
+      }
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        subDirs.push(path.join(dir, e.name));
+      } else if (e.isFile() && MANIFEST_FILES.includes(e.name)) {
+        hasManifest = true;
+      }
+    }
+    if (hasManifest || hasGit) {
+      candidates.push(dir);
+      return; // 子目录里若还有 manifest，会被自己发现；这里不再下钻避免冗余
+    }
+    if (depth >= maxDepth) return;
+    for (const sub of subDirs) {
+      await walk(sub, depth + 1);
+    }
+  }
+
+  await walk(projectPath, 0);
+
+  // 去重：若 candidates 里 A 是 B 的祖先，只保留更深一级的 B
+  candidates.sort((a, b) => a.length - b.length);
+  const kept = [];
+  for (const c of candidates) {
+    let dominated = false;
+    for (const k of kept) {
+      if (c === k || c.startsWith(k + path.sep)) { dominated = true; break; }
+    }
+    if (!dominated) kept.push(c);
+  }
+
+  // 收集每个子项目的关键文件
+  const result = [];
+  for (const root of kept) {
+    const manifests = {};
+    for (const m of MANIFEST_FILES) {
+      const p = path.join(root, m);
+      try {
+        const stat = await fsp.stat(p);
+        if (stat.isFile()) {
+          manifests[m] = stat.size > 20000
+            ? await safeReadFile(p, 20000)
+            : await fsp.readFile(p, 'utf8');
+        }
+      } catch { /* 不存在就跳过 */ }
+    }
+    let readme = '';
+    try {
+      const stat = await fsp.stat(path.join(root, 'README.md'));
+      if (stat.isFile()) readme = await safeReadFile(path.join(root, 'README.md'), 8000);
+    } catch { /* 不存在就跳过 */ }
+    const dirTree = await listDirTree(root, 2, 200);
+    result.push({
+      root,
+      name: path.basename(root) || path.basename(projectPath),
+      manifests,
+      readme,
+      dirTree
+    });
+  }
+  return result;
+}

package/src/ui/server/routes/workbench/sessionStore.js

@@ -0,0 +1,126 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// AI 对话拆分: session 持久化层。
+// 拆分自原 routes/workbench.js 166-260 行。
+//
+// 文件命名: {sessionId}.json
+// 内容: { version, sessionId, title, desc, taskId, promptId, createdAt, updatedAt,
+//         messages: [{role, content}], latestSubtasks, latestRaw, latestParseStage }
+// 写入用临时文件 + rename 原子替换（与 workbench 现有 writeJson 模式一致），
+// 避免半写状态被读到。并发安全: 单进程内同一 session 串行调用，
+// 跨端点并发写同 session 概率极低，丢失只会是最后一次 user/assistant pair，可重发。
+
+import fsp from 'fs/promises';
+import path from 'path';
+import { logger } from './shared.js';
+import { SESSIONS_DIR, MAX_SESSIONS, SESSIONS_KEEP } from './shared.js';
+
+// 16 字符: 时间戳后 8 位 + 随机 8 位 base36，既可读也基本不冲突
+export function genSessionId() {
+  return `${Date.now().toString(36).slice(-8)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+async function readSessionFile(sessionId) {
+  if (!/^[a-z0-9-]{4,32}$/i.test(sessionId)) {
+    const err = new Error('非法 sessionId'); err.statusCode = 400; throw err;
+  }
+  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
+  try {
+    return JSON.parse(await fsp.readFile(file, 'utf-8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const e = new Error('会话不存在'); e.statusCode = 404; throw e;
+    }
+    throw err;
+  }
+}
+
+async function writeSessionFile(sessionId, data) {
+  await fsp.mkdir(SESSIONS_DIR, { recursive: true });
+  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
+  const tmp = `${file}.tmp.${process.pid}.${Date.now()}`;
+  await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf-8');
+  await fsp.rename(tmp, file);
+}
+
+async function deleteSessionFile(sessionId) {
+  if (!/^[a-z0-9-]{4,32}$/i.test(sessionId)) {
+    const err = new Error('非法 sessionId'); err.statusCode = 400; throw err;
+  }
+  const file = path.join(SESSIONS_DIR, `${sessionId}.json`);
+  try {
+    await fsp.unlink(file);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const e = new Error('会话不存在'); e.statusCode = 404; throw e;
+    }
+    throw err;
+  }
+}
+
+// 列表只读 metadata 不读 messages 内容，启动无需预加载
+async function listSessionsMeta() {
+  await fsp.mkdir(SESSIONS_DIR, { recursive: true });
+  const files = await fsp.readdir(SESSIONS_DIR);
+  const list = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const sid = f.slice(0, -5);
+    try {
+      const file = path.join(SESSIONS_DIR, f);
+      const stat = await fsp.stat(file);
+      const data = JSON.parse(await fsp.readFile(file, 'utf-8'));
+      list.push({
+        sessionId: data.sessionId || sid,
+        title: data.title || '(无标题)',
+        taskId: data.taskId || '',
+        createdAt: data.createdAt || '',
+        updatedAt: data.updatedAt || '',
+        messageCount: Array.isArray(data.messages) ? data.messages.length : 0,
+        latestSubtaskCount: Array.isArray(data.latestSubtasks) ? data.latestSubtasks.length : 0,
+        size: stat.size
+      });
+    } catch { /* 跳过坏文件 */ }
+  }
+  list.sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+  return list;
+}
+
+// 容量控制: 超过 MAX_SESSIONS 时按 mtime 删旧的，保留最新 SESSIONS_KEEP 个
+async function enforceSessionsRetention() {
+  const files = await fsp.readdir(SESSIONS_DIR).catch(() => []);
+  const jsonFiles = files.filter(f => f.endsWith('.json'));
+  if (jsonFiles.length < MAX_SESSIONS) return;
+  const stats = await Promise.all(jsonFiles.map(async f => {
+    const full = path.join(SESSIONS_DIR, f);
+    const s = await fsp.stat(full);
+    return { file: full, mtime: s.mtimeMs };
+  }));
+  stats.sort((a, b) => b.mtime - a.mtime);
+  const toDelete = stats.slice(SESSIONS_KEEP);
+  await Promise.all(toDelete.map(s => fsp.unlink(s.file).catch(() => {})));
+  if (toDelete.length > 0) {
+    logger.info(`[workbench] ai-split sessions: cleaned up ${toDelete.length} old files`);
+  }
+}
+
+export const sessionStore = {
+  genSessionId,
+  read: readSessionFile,
+  write: writeSessionFile,
+  delete: deleteSessionFile,
+  listMeta: listSessionsMeta,
+  enforceRetention: enforceSessionsRetention,
+};

package/src/ui/server/routes/workbench/shared.js

@@ -0,0 +1,115 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// workbench 子模块共享：常量 + 通用工具函数。
+// 拆分自原 routes/workbench.js (3539 行) 顶层 1-46 行 + 778-805 行 + 932-944 行。
+//
+// 设计要点：
+//   - 所有 workbench/* 子模块都从这里 import 常量路径与通用工具
+//   - 不依赖任何其他 workbench 子模块（避免循环）
+//   - 持久化函数（readJson / writeJson）保持原子写（tmp + rename）
+
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import logger from '../../utils/logger.js';
+
+// ── 数据目录与持久化文件路径 ─────────────────────────────────
+// 全部存在用户主目录 ~/.zen-gitsync/ 下，跨项目共享
+export const DATA_DIR = path.join(os.homedir(), '.zen-gitsync');
+export const PROMPTS_FILE = path.join(DATA_DIR, 'prompts.json');
+export const TASKS_FILE = path.join(DATA_DIR, 'tasks.json');
+export const IMAGES_DIR = path.join(DATA_DIR, 'workbench-images');
+export const INSTRUCTION_FILE = path.join(DATA_DIR, 'ai-instruction.json');
+export const SUBTASK_INSTRUCTION_FILE = path.join(DATA_DIR, 'ai-subtask-instruction.json');
+// AI 对话拆分会话存档：每个 sessionId 一个文件，重启可恢复多轮上下文
+export const SESSIONS_DIR = path.join(DATA_DIR, 'ai-split-sessions');
+export const MAX_SESSIONS = 100;     // 软上限，触发清理
+export const SESSIONS_KEEP = 50;     // 超过上限时保留最新 N 个
+// 执行日志持久化：jobs.json 是历史档案，jobs-config.json 是保留策略
+export const JOBS_FILE = path.join(DATA_DIR, 'jobs.json');
+export const JOBS_CONFIG_FILE = path.join(DATA_DIR, 'jobs-config.json');
+export const JOBS_SAVE_DEBOUNCE_MS = 1500;
+export const DEFAULT_JOBS_CONFIG = { maxCount: 500, maxSizeMB: 256 };
+
+// 子项目识别 / 文件扫描时需要跳过的目录
+export const SKIP_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.next', '.nuxt', '__pycache__',
+  'target', 'out', 'coverage', 'vendor', '.git', '.svn', '.hg',
+  '.idea', '.vscode', '.gradle', '.terraform', '.cache', '.parcel-cache',
+  '.turbo', '.svelte-kit', 'storybook-static'
+]);
+
+// 解析 manifest 文件名（按优先级）
+export const MANIFEST_FILES = [
+  'package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml',
+  'pom.xml', 'build.gradle', 'build.gradle.kts', 'composer.json',
+  'Gemfile', 'pubspec.yaml'
+];
+
+// 附件大小 / 数量限制
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;        // 单个附件最大 5MB
+export const MAX_ATTACHMENTS_PER_SUBTASK = 9;          // 一个子任务最多挂 9 个附件
+
+// ── 时间 / ID 工具 ─────────────────────────────────────────
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function genId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ── 文件持久化工具 ─────────────────────────────────────────
+// 所有 workbench 数据都用这两个函数读写，确保原子写与 ENOENT 容错
+export async function ensureDataDir() {
+  await fsp.mkdir(DATA_DIR, { recursive: true });
+}
+
+export async function readJson(file, fallback) {
+  try {
+    const buf = await fsp.readFile(file, 'utf-8');
+    return JSON.parse(buf);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return fallback;
+    throw err;
+  }
+}
+
+// 原子写：tmp + rename。避免半写状态被读到（与 sessionStore 一致）
+export async function writeJson(file, data) {
+  await ensureDataDir();
+  const tmp = `${file}.tmp`;
+  await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf-8');
+  await fsp.rename(tmp, file);
+}
+
+// 简单 Mustache 风格变量插值：{{task.title}} / {{task.desc}} / {{repo.path}} / {{branch}}
+// 用于把用户可编辑的 prompt 模板里的占位符替换成实际上下文
+export function interpolate(template, ctx) {
+  if (typeof template !== 'string') return template;
+  return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => {
+    const parts = key.split('.');
+    let cur = ctx;
+    for (const p of parts) {
+      if (cur == null) return '';
+      cur = cur[p];
+    }
+    return cur == null ? '' : String(cur);
+  });
+}
+
+// 让子模块共享 logger，避免到处 import
+export { logger, fs, fsp, path, os };