zen-gitsync 2.14.2 → 2.15.1

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

@@ -0,0 +1,175 @@
+// 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 指令文本持久化（生成指令 + 拆分子任务指令）。
+// 拆分自原 routes/workbench.js 57-158 行 + 958-998 行。
+//
+// 两个独立的指令文件：
+//   - ai-instruction.json         生成项目架构说明的指令
+//   - ai-subtask-instruction.json 拆分子任务的指令（支持 zh/en 多语言默认）
+
+import fsp from 'fs/promises';
+import {
+  INSTRUCTION_FILE,
+  SUBTASK_INSTRUCTION_FILE,
+  ensureDataDir,
+  nowIso,
+} from './shared.js';
+
+// ── 生成指令（用户首次使用时作为可编辑指令的初始值） ───────────
+export const DEFAULT_INSTRUCTION = `你是一名资深软件架构师。
+
+【探索步骤】
+1. 先识别项目结构：扫描根目录是否包含 .git 目录，以及 package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml / build.gradle{,.kts} / composer.json / Gemfile / pubspec.yaml 这 9 种 manifest。
+2. 如果根目录含 manifest，就把整个根目录视为一个子项目。
+3. 如果根目录不含 manifest、但子目录（含一层 .git 或上述 manifest）形成多个子项目，对每个子项目分别探索。
+4. 对每个子项目，重点读取：
+   - 所有识别到的 manifest（限制单文件 20KB）
+   - README.md（限制 8KB）
+   - 入口文件：package.json 的 main / scripts / workspaces 字段；pyproject.toml 的 [project.scripts]；go.mod 的 module；Cargo.toml 的 [[bin]]；pom.xml 的 <modules>
+   - 2 层目录树（最多 200 行）
+
+【输出要求】
+1. 给出一段中文「项目架构说明」，长度不限，模型自行决定篇幅与详尽程度，能写多详细就多详细。覆盖：项目整体定位、技术栈、模块划分、核心流程、关键设计决策。
+2. 必须引用子项目里实际存在的文件路径、目录名、依赖名，不要编造。
+3. 多个子项目时：先逐个说明，最后输出一段「整体架构」总结它们之间的关系。
+4. 语气专业、具体、面向接手这个项目的开发者。
+5. 只返回 JSON：{ "name": "项目名（建议：项目名+架构说明）", "summary": "架构说明正文" }。`;
+
+// ── 拆分子任务指令：默认系统指令（用户在 GUI 可编辑覆盖） ───────
+// 国际化：根据请求 Accept-Language 在 zh / en 之间选默认。
+// 中英两份都内置——用户保存到 ~/.zen-gitsync/ai-subtask-instruction.json 后覆盖。
+export const DEFAULT_SUBTASK_INSTRUCTION_ZH = `你是一名任务拆分助手。
+
+【绝对禁止】
+- 不要进入任何"plan 模式"、"plan 阶段"或"先写 plan 再执行"。
+- 不要输出"我要进入 plan / 准备 / 探索 / 调研"之类的元叙述。
+- 不要写"Plan 文件已写入 xxx"或"等用户批准后开始"这种"声明意图"的话。
+- 你只做一件事:把用户给的任务拆成可独立执行的子任务清单,直接输出 JSON。中间任何"我要做什么"的描述都属于错误输出。
+- 你的输出会被另一个程序读取,该程序只看最终 JSON,所有非 JSON 文字会被丢弃——所以不要把"执行步骤"写进 analysis 段,只写在 JSON 的 desc 字段里。
+
+【思考过程】
+在给出 JSON 之前，请先在内部仔细思考（如果模型支持，把思考放在 reasoning 中；否则可以先输出一段较长的仔细分析，再输出 JSON）。分析要覆盖足够维度，不要简短一两句话就过：
+- 任务的真实目标是什么？用户提供的描述/图片/上下文里有哪些关键信息和隐藏诉求？
+- 涉及哪些技术栈、模块、文件、约束？是否有易被忽略的边界条件、风险点？
+- 自然的执行顺序是什么？哪些步骤是前置依赖？哪些可以并行？
+- 哪些步骤可能失败、需要单独验证？验证方式是什么？
+- 是否需要先做调研/读现有代码的步骤，再做修改？
+
+【拆分原则】
+1. 单一职责：每个子任务只做一件事，避免"做 A 和 B"。
+2. 粒度适中：单个子任务应当能在一次会话里完成（既不要"实现整个登录功能"这么大，也不要"打印 hello"这么琐碎）。
+3. 顺序合理：子任务按依赖关系和执行顺序排列（先准备、后实现、最后验证）。
+4. 可验证：每个子任务都有明确的完成标志（"输出文件 xxx"、"通过测试 yyy"、"控制台打印 zzz"）。
+5. 数量：不设上限。任务很简单时 1-2 个就够，复杂时按需拆成 10 个、20 个甚至更多子任务都行，直到覆盖所有可独立验证的步骤。
+6. 描述具体：desc 字段要写清楚"要做什么、参考什么、产出什么"，不要只是把 title 改写一遍。
+7. 如果任务里附带了图片，必须基于图片的实际内容拆分（例如指出图片中的哪个区域、哪个元素需要改），而不是泛泛而谈。
+
+【输出要求】
+最后必须输出 JSON，结构：
+{
+  "subtasks": [
+    { "title": "子任务标题", "desc": "子任务的具体描述，包含要做什么、输入是什么、输出/验证标志是什么" }
+  ]
+}
+
+JSON 要用 \`\`\`json ... \`\`\` 代码块包裹，前面可以有分析文字，但 JSON 必须完整、合法、可解析。`;
+
+export const DEFAULT_SUBTASK_INSTRUCTION_EN = `You are a task breakdown assistant.
+
+[ABSOLUTE PROHIBITIONS]
+- Do NOT enter any "plan mode" / "planning phase" / "I'll write a plan first, then execute".
+- Do NOT output meta-narration like "I'm entering plan / preparing / exploring / researching".
+- Do NOT write "Plan file written to xxx" or "waiting for user approval" style intent-declaration text.
+- You only do one thing: split the user's task into an independently executable subtask list and output JSON directly. Any "what I'm going to do" description in the middle is an error.
+- Your output is consumed by another program that only reads the final JSON. All non-JSON text is discarded — so put execution steps in the desc field of JSON, not in the analysis section.
+
+[Thinking process]
+Before producing JSON, think carefully (put your thoughts in reasoning if the model supports it; otherwise output a longer careful analysis first, then JSON). Cover enough dimensions — don't settle for a one-or-two-sentence summary:
+- What is the real goal? What key info and hidden needs are in the description / images / context?
+- Which stack, modules, files, constraints are involved? Any easily missed edge cases or risks?
+- What is the natural execution order? What blocks what? What can run in parallel?
+- Which steps may fail and need separate verification? How will you verify?
+- Should a research / read-existing-code step come before the changes?
+
+[Breakdown principles]
+1. Single responsibility: each subtask does only one thing, avoid bundling "do A and B".
+2. Right granularity: a subtask should finish in one Claude session (not as big as "implement the whole login flow", not as trivial as "print hello").
+3. Sensible order: arrange subtasks by dependency / execution order (prepare first, implement, then verify).
+4. Verifiable: every subtask has a clear completion signal (e.g. "produce file xxx", "pass test yyy", "log zzz to console").
+5. Quantity: no hard limit. Very simple tasks need only 1-2; complex tasks can be split into 10, 20 or more subtasks until every independently verifiable step is covered.
+6. Concrete desc: write what to do, what to reference, what to produce — don't just paraphrase the title.
+7. If the task includes images, the breakdown must reference the actual image content (which region, which element to change), not just generic talk.
+
+[Output requirements]
+End with JSON, structure:
+{
+  "subtasks": [
+    { "title": "subtask title", "desc": "concrete description: what to do, what the input is, what the output / verification signal is" }
+  ]
+}
+
+Wrap JSON in a \`\`\`json ... \`\`\` code block. Preceding analysis text is allowed, but the JSON must be complete, valid, and parseable.`;
+
+// 兼容旧引用：未保存指令文件时回退到 ZH 版本
+export const DEFAULT_SUBTASK_INSTRUCTION = DEFAULT_SUBTASK_INSTRUCTION_ZH;
+
+// 根据请求 Accept-Language 选默认（zh / en）
+export function pickDefaultSubtaskInstruction(req) {
+  const al = String(req?.headers?.['accept-language'] || '').toLowerCase();
+  if (al.startsWith('en')) return DEFAULT_SUBTASK_INSTRUCTION_EN;
+  return DEFAULT_SUBTASK_INSTRUCTION_ZH;
+}
+
+// ── 生成指令持久化（~/.zen-gitsync/ai-instruction.json） ───────
+export async function readInstruction() {
+  try {
+    const buf = await fsp.readFile(INSTRUCTION_FILE, 'utf-8');
+    const obj = JSON.parse(buf);
+    if (obj && typeof obj.instruction === 'string' && obj.instruction.trim()) {
+      return obj.instruction;
+    }
+  } catch { /* 文件不存在或解析失败 */ }
+  return DEFAULT_INSTRUCTION;
+}
+
+export async function writeInstruction(instruction) {
+  await ensureDataDir();
+  const text = String(instruction || '').trim() || DEFAULT_INSTRUCTION;
+  const tmp = `${INSTRUCTION_FILE}.tmp`;
+  await fsp.writeFile(tmp, JSON.stringify({ instruction: text, updatedAt: nowIso() }, null, 2), 'utf-8');
+  await fsp.rename(tmp, INSTRUCTION_FILE);
+}
+
+// ── 拆分子任务指令持久化 ─────────────────────────────────────
+// 支持传入 req：根据 Accept-Language 选默认（zh/en）
+export async function readSubtaskInstruction(req) {
+  try {
+    const buf = await fsp.readFile(SUBTASK_INSTRUCTION_FILE, 'utf-8');
+    const obj = JSON.parse(buf);
+    if (obj && typeof obj.instruction === 'string' && obj.instruction.trim()) {
+      return obj.instruction;
+    }
+  } catch { /* 文件不存在或解析失败 */ }
+  return pickDefaultSubtaskInstruction(req);
+}
+
+export async function writeSubtaskInstruction(instruction) {
+  await ensureDataDir();
+  // 写入时如果与当前 locale 默认一致，不写文件——这样前端"isDefault"判定永远准确
+  const text = String(instruction || '').trim() || DEFAULT_SUBTASK_INSTRUCTION_ZH;
+  const tmp = `${SUBTASK_INSTRUCTION_FILE}.tmp`;
+  await fsp.writeFile(tmp, JSON.stringify({ instruction: text, updatedAt: nowIso() }, null, 2), 'utf-8');
+  await fsp.rename(tmp, SUBTASK_INSTRUCTION_FILE);
+}

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

@@ -0,0 +1,225 @@
+// 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.
+//
+// 执行日志持久化 + 进程表（jobs Map）+ 事件总线（bus）。
+// 拆分自原 routes/workbench.js 814-955 行。
+//
+// 设计要点：
+//   - 写盘在流式 chunk 阶段走 1.5s debounce；终态时（finally / cancel）强制 flush
+//   - 永不持久化 child 引用（参考 cancel 路由的浅拷贝模式）
+//   - hydrate 时把 running/pending 降级为 error：原 child 进程已不存在
+//   - enforceRetention 在每次落盘后跑，按 endedAt desc FIFO 裁剪
+//
+// 模块级单例：bus / jobs / cancelledJobs 跨整个进程共享，
+// SSE /api/workbench/events 与 cancel 接口都从这里读
+
+import { EventEmitter } from 'events';
+import fsp from 'fs/promises';
+import {
+  logger,
+  fsp as _fsp,
+  JOBS_FILE,
+  JOBS_CONFIG_FILE,
+  TASKS_FILE,
+  JOBS_SAVE_DEBOUNCE_MS,
+  DEFAULT_JOBS_CONFIG,
+  readJson,
+  writeJson,
+  nowIso,
+} from './shared.js';
+
+// 进程表：记录每个子任务的运行状态
+// jobId -> { id, taskId, subId, status, pid, startedAt, endedAt, exitCode, error, prompt, child, output, thinking, claudeSessionId }
+export const jobs = new Map();
+
+// 事件总线：SSE /api/workbench/events 监听 'event'，路由层用 publish() 推送
+export const bus = new EventEmitter();
+
+// 被用户主动取消的 jobId 集合——runTaskQueue 在 waitProcessExit 之后检查这个集合
+// 来决定把 job 标为 'cancelled' 还是 'done'。
+// 用 Set 而不是 job.cancelled 标志，是为了在 SIGTERM 发出后到 child 真正退出之间
+// 有一个简洁的"待回收"窗口。
+export const cancelledJobs = new Set();
+
+// ── 持久化层 ─────────────────────────────────────────────────
+// jobs.json 是历史档案；jobs Map 只承载当前进程产出的活跃 job
+let jobsSaveTimer = null;
+
+// 序列化 job 落盘：剥离 child 引用（ChildProcess 无法 JSON.stringify），
+// 反范式 taskTitle/subTitle 方便管理页直接读
+export function serializeJob(j, taskMap) {
+  const { child, ...rest } = j;
+  const t = taskMap ? taskMap.get(rest.taskId) : null;
+  const sub = t && Array.isArray(t.subtasks) ? t.subtasks.find(s => s.id === rest.subId) : null;
+  const size = ((rest.prompt || '').length
+    + (rest.output || '').length
+    + (rest.thinking || '').length);
+  return {
+    ...rest,
+    taskTitle: t ? t.title : '',
+    subTitle: sub ? sub.title : '',
+    size
+  };
+}
+
+// 流式 chunk 阶段 debounce 写盘；终态时由 flushJobsSaveNow() 强制立即落盘
+export function scheduleJobsSave() {
+  if (jobsSaveTimer) clearTimeout(jobsSaveTimer);
+  jobsSaveTimer = setTimeout(() => {
+    jobsSaveTimer = null;
+    flushJobsSaveNow().catch(err => logger.warn('[workbench] jobs save failed:', err.message));
+  }, JOBS_SAVE_DEBOUNCE_MS);
+}
+
+// 立即落盘（终态调用）：把 jobs Map 当前快照写到 jobs.json，然后跑 retention
+export async function flushJobsSaveNow() {
+  if (jobsSaveTimer) { clearTimeout(jobsSaveTimer); jobsSaveTimer = null; }
+  // 读 tasks.json 给落盘 job 反范式 taskTitle/subTitle——父任务被删后管理页仍可读
+  const tasksData = await readJson(TASKS_FILE, { tasks: [] });
+  const taskMap = new Map((tasksData.tasks || []).map(t => [t.id, t]));
+  const payload = {
+    version: 1,
+    jobs: Array.from(jobs.values()).map(j => serializeJob(j, taskMap))
+  };
+  await writeJson(JOBS_FILE, payload);
+  await enforceRetention();
+}
+
+// jobs-config.json 读写：maxCount / maxSizeMB 保留策略
+export async function readJobsConfig() {
+  const cfg = await readJson(JOBS_CONFIG_FILE, null);
+  if (!cfg || typeof cfg !== 'object') return { ...DEFAULT_JOBS_CONFIG };
+  return {
+    maxCount: Number.isFinite(cfg.maxCount) ? Math.max(0, Math.floor(cfg.maxCount)) : DEFAULT_JOBS_CONFIG.maxCount,
+    maxSizeMB: Number.isFinite(cfg.maxSizeMB) ? Math.max(0, Math.floor(cfg.maxSizeMB)) : DEFAULT_JOBS_CONFIG.maxSizeMB
+  };
+}
+
+export async function writeJobsConfig(cfg) {
+  // 校验：非负整数；硬上限防误填爆盘
+  const out = {};
+  if (cfg.maxCount !== undefined) {
+    const n = Math.floor(Number(cfg.maxCount));
+    if (!Number.isFinite(n) || n < 0 || n > 10000) throw new Error('maxCount 必须在 0-10000 之间');
+    out.maxCount = n;
+  }
+  if (cfg.maxSizeMB !== undefined) {
+    const n = Math.floor(Number(cfg.maxSizeMB));
+    if (!Number.isFinite(n) || n < 0 || n > 10240) throw new Error('maxSizeMB 必须在 0-10240 之间');
+    out.maxSizeMB = n;
+  }
+  const merged = { ...(await readJobsConfig()), ...out };
+  await writeJson(JOBS_CONFIG_FILE, merged);
+  return merged;
+}
+
+// 进程启动时把磁盘上的历史拉回内存 Map；陈旧的 running/pending 强制降级。
+// 陈旧 job 的 child 进程已退出，标记为 error 方便用户识别。
+export async function hydrateJobs() {
+  let data;
+  try {
+    data = await readJson(JOBS_FILE, null);
+  } catch (err) {
+    // 损坏文件：改名备份避免下次 flush 静默覆盖用户数据
+    logger.warn('[workbench] jobs.json 解析失败，备份原文件后重置:', err.message);
+    try { await _fsp.rename(JOBS_FILE, `${JOBS_FILE}.bak-${Date.now()}`); } catch { /* 文件可能已不在 */ }
+    return;
+  }
+  if (!data || !Array.isArray(data.jobs)) return;
+  for (const j of data.jobs) {
+    if (j.status === 'running' || j.status === 'pending') {
+      j.status = 'error';
+      j.error = (j.error || '') + ' [重启后回收：原进程已退出]';
+      j.endedAt = j.endedAt || nowIso();
+      j.exitCode = typeof j.exitCode === 'number' ? j.exitCode : 1;
+    }
+    // 旧版本可能没 size 字段；补齐以兼容历史文件
+    if (typeof j.size !== 'number') {
+      j.size = ((j.prompt || '').length + (j.output || '').length + (j.thinking || '').length);
+    }
+    jobs.set(j.id, j);
+  }
+  // 启动后也跑一遍保留策略，让历史文件立刻缩到当前配置
+  try { await enforceRetention(); } catch (err) { logger.warn('[workbench] 启动时 enforceRetention 失败:', err.message); }
+}
+
+// 保留策略：按 endedAt desc（fallback startedAt / id）排序，先按 maxCount 截，
+// 再按 maxSizeMB 累计裁，淘汰同步从内存 Map 删除。
+export async function enforceRetention() {
+  const cfg = await readJobsConfig();
+  const data = await readJson(JOBS_FILE, { version: 1, jobs: [] });
+  if (!data || !Array.isArray(data.jobs) || data.jobs.length === 0) return;
+  const sortKey = (j) => j.endedAt || j.startedAt || j.id || '';
+  data.jobs.sort((a, b) => sortKey(b).localeCompare(sortKey(a)));
+  if (cfg.maxCount > 0) data.jobs = data.jobs.slice(0, cfg.maxCount);
+  if (cfg.maxSizeMB > 0) {
+    const cap = cfg.maxSizeMB * 1024 * 1024;
+    let total = data.jobs.reduce((s, j) => s + (j.size || 0), 0);
+    while (total > cap && data.jobs.length > 1) {
+      const dropped = data.jobs.pop();
+      total -= (dropped && dropped.size) || 0;
+    }
+  }
+  await writeJson(JOBS_FILE, data);
+  const keepIds = new Set(data.jobs.map(j => j.id));
+  for (const id of Array.from(jobs.keys())) {
+    if (!keepIds.has(id)) jobs.delete(id);
+  }
+}
+
+// 进程启动时拉回历史 job（陈旧 running/pending 自动降级 error）
+// 模块加载即触发，与原 workbench.js 顶层调用保持一致
+hydrateJobs().catch(err => logger.warn('[workbench] hydrate jobs failed:', err.message));
+
+// ── 事件推送 + 快照 ─────────────────────────────────────────
+// publish 给 SSE 路由用：所有事件都走 bus.emit('event', {event, payload, ts})
+export function publish(event, payload) {
+  bus.emit('event', { event, payload, ts: nowIso() });
+}
+
+// 给 SSE / cancel / continue 路由用：返回当前所有 job 的可序列化快照
+// 剥离 child 引用（不可序列化），只保留前端需要的字段
+export function snapshotJobs() {
+  return Array.from(jobs.values()).map(j => ({
+    id: j.id,
+    taskId: j.taskId,
+    subId: j.subId,
+    title: j.title,
+    status: j.status,
+    prompt: j.prompt || '',
+    output: j.output || '',
+    pid: j.pid || null,
+    startedAt: j.startedAt || null,
+    endedAt: j.endedAt || null,
+    exitCode: typeof j.exitCode === 'number' ? j.exitCode : null,
+    error: j.error || null,
+    // 续接对话用:claude --output-format stream-json 的 system.init 事件捕获到的 session_id
+    claudeSessionId: j.claudeSessionId || null
+  }));
+}
+
+export const jobStore = {
+  jobs,
+  bus,
+  cancelledJobs,
+  serializeJob,
+  scheduleJobsSave,
+  flushJobsSaveNow,
+  readJobsConfig,
+  writeJobsConfig,
+  hydrateJobs,
+  enforceRetention,
+  publish,
+  snapshotJobs,
+};

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

@@ -0,0 +1,219 @@
+// 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 拆分子任务 JSON 多级降级解析。
+// 拆分自原 routes/workbench.js 395-776 行。
+//
+// 模型经常会犯几类格式错：在 desc 里用 ASCII 双引号引用术语 / 末尾留尾随逗号 /
+// 输出被 token 上限截断导致代码块未闭合。直接 JSON.parse 一旦失败就会让前端的
+// "确认入库" 按钮永远是 (0)，用户看不到原因。这里按"越简单越优先"的顺序尝试：
+//   ① ```json``` 代码块 / ```any``` 代码块 / 第一个完整 { ... } 范围
+//   ② 把候选片段去掉尾随逗号 + 块/行注释 再 parse
+//   ③ 用括号深度扫描，从开头找一个语法平衡的 { ... } 子串
+//   ④ 启发式转义模型夹在字符串内部的未转义 ASCII 双引号
+// 任一步成功就返回 parsed，全部失败时返回最后一次 JSON.parse 的错误，
+// 用 parseStage 告知前端"模型输出哪一步崩了"，并把原始 raw 一并回传。
+
+// 剥离 LLM 输出的 思考块、```json``` 代码块围栏，以及首尾说明文字。
+// 原贪婪正则 /({[\s\S]*})/ 会把 思考块（内含未配对花括号或字符串）一起吞进 JSON.parse，
+// 在 DeepSeek 等会输出 推理链的模型上偶发 "Unterminated string in JSON"。
+export function stripThinkingBlocks(content) {
+  let s = String(content || '');
+  // 1) 显式 思考块（成对标签）
+  s = s.replace(/<think(?:ing)?>[\s\S]*?<\/think(?:ing)?>/gi, '');
+  // 2) 某些 provider 流式结尾会留下裸 <think>...</think> 之外的残段（无结束标签时被截断）
+  s = s.replace(/<think(?:ing)?>[\s\S]*$/gi, '');
+  // 3) ```json ... ``` 代码块围栏（保留内部 JSON）
+  s = s.replace(/```json\s*/gi, '').replace(/```/g, '');
+  return s;
+}
+
+// 在剥离 思考块 的文本里定位第一个「平衡花括号对象」的起点/终点。
+// 跳过字符串内的 {/}（含转义）以及 Jinja {{ }} 模板占位符；
+// 同时只在「JSON 特征显著」的 { 处起算 —— 即该 { 之后不远处出现 " 字符串。
+// 这能避免把 LLM 思考文本里的裸 { ... }（如 "see { views, stores }"）误当 JSON 起点。
+export function extractFirstJsonObject(content) {
+  const s = String(content || '');
+  let depth = 0;
+  let inStr = false;
+  let escape = false;
+  let start = -1;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (inStr) {
+      if (escape) { escape = false; continue; }
+      if (ch === '\\') { escape = true; continue; }
+      if (ch === '"') { inStr = false; }
+      continue;
+    }
+    if (ch === '"') { inStr = true; continue; }
+    // 跳过 Jinja {{ }} 占位符（提示词模板常用，勿当 JSON）
+    if (ch === '{' && s[i + 1] === '{') { i++; continue; }
+    if (ch === '}' && s[i - 1] === '}') { continue; }
+    if (ch === '{') {
+      if (depth === 0) {
+        // 启发式判断「这看起来像 JSON 起点」：
+        // 1. { 之前紧邻「真正的语义字符」(字母/数字/中文/下划线) → 不是 JSON 起点（散文里的花括号）
+        //    但接受 . , ; : 等句末标点（LLM 经常以「总结：{...}」直接开头 JSON）
+        // 2. { 之后跳过空白第一个字符必须是 " 或 }（空对象）
+        const before = i > 0 ? s[i - 1] : '';
+        if (/[A-Za-z0-9_一-龥]/.test(before)) continue;
+        let j = i + 1;
+        while (j < s.length && /\s/.test(s[j])) j++;
+        const firstNonWs = s[j];
+        if (firstNonWs !== '"' && firstNonWs !== '}') continue;
+        start = i;
+      }
+      depth++;
+    } else if (ch === '}') {
+      if (depth > 0) depth--;
+      if (depth === 0 && start !== -1) {
+        return s.slice(start, i + 1);
+      }
+    }
+  }
+  // 兜底：找不到平衡对象时返回原文（让上层 JSON.parse 报清晰错误）
+  return s;
+}
+
+// 从字符串中提取首个语法平衡的 { ... } 子串。
+// 跟踪字符串字面量（含转义），避免把 desc 里的 } 当成结束。
+export function extractBalancedJson(text) {
+  const s = String(text || '');
+  const start = s.indexOf('{');
+  if (start < 0) return '';
+  let depth = 0;
+  let inStr = false;
+  let strCh = '';
+  let esc = false;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (inStr) {
+      if (esc) { esc = false; continue; }
+      if (c === '\\') { esc = true; continue; }
+      if (c === strCh) { inStr = false; }
+      continue;
+    }
+    if (c === '"' || c === "'") { inStr = true; strCh = c; continue; }
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return s.slice(start, i + 1);
+    }
+  }
+  return '';
+}
+
+// ④ 级降级：把字符串字面量内部出现的、未转义的 ASCII 双引号自动转义。
+// 实战中模型最常见的错误是 "desc": "...用户点击"保存"按钮..." 这种—
+// 中间的 "保存" 把外层字符串截断成两段，后面变成裸文本，JSON.parse 必崩。
+//
+// 启发式判断：扫描时若处于字符串中且遇到 "，往后看第一个非空白字符：
+//   - 是 , } ] : 或文本结尾 → 这是真闭合，正常退出字符串
+//   - 否则 → 是模型乱写的字面量引号，改写为 \" 并继续留在字符串里
+// 不依赖正则、不破坏已经转义的 \"，对嵌套 / 多行字符串都安全。
+export function reescapeUnescapedQuotes(text) {
+  const s = String(text || '');
+  if (!s) return '';
+  const out = [];
+  let inStr = false;
+  let strCh = '';
+  let esc = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (!inStr) {
+      out.push(c);
+      if (c === '"' || c === "'") { inStr = true; strCh = c; }
+      continue;
+    }
+    // 字符串内部
+    if (esc) { out.push(c); esc = false; continue; }
+    if (c === '\\') { out.push(c); esc = true; continue; }
+    if (c !== strCh) { out.push(c); continue; }
+    // 遇到与开闭引号相同的字符——往后看下一个非空白
+    let j = i + 1;
+    while (j < s.length && (s[j] === ' ' || s[j] === '\t')) j++;
+    const next = j < s.length ? s[j] : '';
+    if (next === '' || next === ',' || next === '}' || next === ']'
+        || next === ':' || next === '\n' || next === '\r') {
+      // 真闭合
+      out.push(c);
+      inStr = false;
+      strCh = '';
+    } else {
+      // 字面量裸引号——转义
+      out.push('\\', c);
+    }
+  }
+  return out.join('');
+}
+
+// AI 拆分子任务 JSON 多级降级解析主入口。
+// 返回 { parsed, parseError, parseStage }：
+//   - parsed: 解析成功时的对象，失败时为 null
+//   - parseError: 失败时的错误信息
+//   - parseStage: 'empty' / '' (成功) / 'cleaned' / 'balanced' / 'reescaped' / 'failed'
+export function parseSubtaskJson(content) {
+  let src = String(content || '');
+  if (!src.trim()) {
+    return { parsed: null, parseError: '模型未返回任何内容', parseStage: 'empty' };
+  }
+
+  // 预处理：剥离 deepseek-r1 / QwQ 等模型在 content 前输出的 <think>...</think> 思考块
+  src = src.replace(/<think>[\s\S]*?<\/think>/gi, '').replace(/<think\s*\/>/gi, '').trim();
+
+  const candidates = [];
+  const fenced = src.match(/```json\s*([\s\S]*?)```/i) || src.match(/```\s*([\s\S]*?)```/);
+  if (fenced) candidates.push(fenced[1]);
+  // 平衡花括号扫描：避免贪婪正则把多段 JSON / 散落的 { } 全包进去
+  const balancedFirst = extractBalancedJson(src);
+  if (balancedFirst) candidates.push(balancedFirst);
+  // 兜底：整段当 JSON 试
+  candidates.push(src);
+
+  let lastErr = null;
+  for (const raw of candidates) {
+    const txt = String(raw || '').trim();
+    if (!txt) continue;
+    // ① 直 parse
+    try { return { parsed: JSON.parse(txt), parseError: '', parseStage: '' }; }
+    catch (e) { lastErr = e; }
+    // ② 清洗：去 //…/* */ 注释 + 尾随逗号
+    const cleaned = txt
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:"'\\])\/\/[^\n]*/g, '$1')
+      .replace(/,(\s*[}\]])/g, '$1');
+    try { return { parsed: JSON.parse(cleaned), parseError: '', parseStage: 'cleaned' }; }
+    catch (e) { lastErr = e; }
+    // ③ 平衡花括号扫描
+    const balanced = extractBalancedJson(cleaned);
+    if (balanced && balanced !== cleaned) {
+      try { return { parsed: JSON.parse(balanced), parseError: '', parseStage: 'balanced' }; }
+      catch (e) { lastErr = e; }
+    }
+    // ④ 启发式转义字符串内的未转义双引号
+    const base = balanced || cleaned;
+    const reescaped = reescapeUnescapedQuotes(base);
+    if (reescaped && reescaped !== base) {
+      try { return { parsed: JSON.parse(reescaped), parseError: '', parseStage: 'reescaped' }; }
+      catch (e) { lastErr = e; }
+    }
+  }
+
+  return {
+    parsed: null,
+    parseError: lastErr ? (lastErr.message || String(lastErr)) : '未能从模型输出中提取出 JSON',
+    parseStage: 'failed'
+  };
+}