@fieldwangai/agentflow 0.1.25

package/bin/lib/composer-flow-instances.mjs

@@ -0,0 +1,68 @@
+/**
+ * 从 flow.yaml 解析实例的 role / model，供 Composer 多步规划与路由使用。
+ */
+import yaml from "js-yaml";
+import { translateRole, normalizeRoleToKey } from "./i18n.mjs";
+
+const VALID_ROLES = ["requirement", "planning", "code", "test", "normal"];
+
+/**
+ * @param {string} [flowYaml]
+ * @returns {Record<string, { role: string, model?: string, label: string, definitionId?: string, hasScript?: boolean }>}
+ */
+export function parseInstanceRoleModelMap(flowYaml) {
+  const map = {};
+  if (!flowYaml || typeof flowYaml !== "string" || !flowYaml.trim()) return map;
+  try {
+    const raw = yaml.load(flowYaml);
+    const instances = raw?.instances && typeof raw.instances === "object" ? raw.instances : {};
+    for (const [id, inst] of Object.entries(instances)) {
+      if (!inst || typeof inst !== "object") continue;
+      const rawRole = inst.role != null ? String(inst.role).trim() : "";
+      const normalizedRole = normalizeRoleToKey(rawRole);
+      const role = VALID_ROLES.includes(normalizedRole) ? normalizedRole : "normal";
+      let model = inst.model != null ? String(inst.model).trim() : "";
+      if (model === "default") model = "";
+      const label = inst.label != null ? String(inst.label) : id;
+      const definitionId = inst.definitionId != null ? String(inst.definitionId).trim() : undefined;
+      const hasScript = definitionId === "tool_nodejs" && inst.script != null && String(inst.script).trim() !== "";
+      map[id] = { role, model: model || undefined, label, definitionId, hasScript };
+    }
+  } catch {
+    /* ignore */
+  }
+  return map;
+}
+
+/**
+ * 供规划器 user 消息附加：明确实例上的角色、模型与节点类型，便于输出带 instanceId / nodeRole 的步骤。
+ * @param {string} [flowYaml]
+ * @returns {string}
+ */
+export function formatInstancePlannerHint(flowYaml) {
+  const map = parseInstanceRoleModelMap(flowYaml);
+  const entries = Object.entries(map);
+  if (entries.length === 0) return "";
+
+  const nodejsMissing = [];
+  const lines = entries.map(([id, v]) => {
+    const m = v.model ? ` · 模型 \`${v.model}\`` : "";
+    const defHint = v.definitionId ? ` · \`${v.definitionId}\`` : "";
+    const scriptHint = v.definitionId === "tool_nodejs" && !v.hasScript ? " ⚠️ **缺 script**" : "";
+    if (v.definitionId === "tool_nodejs" && !v.hasScript) nodejsMissing.push(id);
+    return `- \`${id}\`（${v.label}）：角色 **${translateRole(v.role)}**${defHint}${m}${scriptHint}`;
+  });
+
+  let warn = "";
+  if (nodejsMissing.length > 0) {
+    warn = `\n\n⚠️ **以下 tool_nodejs 节点缺少 script 字段**（无 script 则节点无法执行）：${nodejsMissing.map(id => `\`${id}\``).join("、")}。` +
+      "必须为它们写入可执行的 `script`（shell/node 命令），或改用 `agent_subAgent`。`body` 不会被执行。";
+  }
+
+  return (
+    "\n## 画布实例（类型 / 角色 / 模型）\n" +
+    "agent 步骤请尽量填写 `instanceId`（本步主要操作的实例），`nodeRole` 应与该实例的 role 一致；可选用 `executorModel` 覆盖执行模型（否则使用该实例在 YAML 中的 model，再否则用用户全局模型）。\n" +
+    lines.join("\n") +
+    warn
+  );
+}

package/bin/lib/composer-flow-skeleton.mjs

@@ -0,0 +1,334 @@
+/**
+ * Composer 阶段一 skeleton 生成器：在 AI 真正执行前，由脚本写入：
+ *   1. flow.yaml — 含 control_start + control_end + 一条主链 edge + nodePositions
+ *   2. composer-node-spec.md — 含三段 section 模板（整体框架/节点职责/计划数据槽）
+ *
+ * 设计原则：
+ *   - **幂等**：只有当目标文件不存在 / 完全空 / instances 为空时才写入。
+ *     如已有内容，**不动**（避免覆盖用户工作）。
+ *   - **最小骨架**：让 AI 只做"插入节点 + 调整边"而非"从零写 YAML"。
+ *   - **正确 YAML**：start/end 槽位结构、type、name 严格对齐 schema。
+ */
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+
+/**
+ * 写入 flow.yaml skeleton（如已有非空 instances 则跳过）。
+ * @param {string} flowYamlAbs flow.yaml 绝对路径
+ * @returns {{ created: boolean, reason: string }}
+ */
+export function ensureFlowSkeleton(flowYamlAbs) {
+  if (!flowYamlAbs) return { created: false, reason: "missing flowYamlAbs" };
+
+  const exists = fs.existsSync(flowYamlAbs);
+  if (exists) {
+    try {
+      const raw = fs.readFileSync(flowYamlAbs, "utf-8");
+      const data = yaml.load(raw);
+      const instCount = data && data.instances && typeof data.instances === "object"
+        ? Object.keys(data.instances).length
+        : 0;
+      if (instCount > 0) {
+        return { created: false, reason: `flow.yaml already has ${instCount} instances` };
+      }
+    } catch {
+      /* 解析失败也覆盖（视为坏文件） */
+    }
+  }
+
+  fs.mkdirSync(path.dirname(flowYamlAbs), { recursive: true });
+
+  const skeleton = {
+    instances: {
+      control_start: {
+        definitionId: "control_start",
+        label: "Start",
+        input: [],
+        output: [
+          { type: "node", name: "next", value: "" },
+        ],
+        body: "流程入口",
+      },
+      control_end: {
+        definitionId: "control_end",
+        label: "End",
+        input: [
+          { type: "node", name: "prev", value: "" },
+        ],
+        output: [],
+        body: "流程出口",
+      },
+    },
+    edges: [
+      {
+        source: "control_start",
+        target: "control_end",
+        sourceHandle: "output-0",
+        targetHandle: "input-0",
+      },
+    ],
+    ui: {
+      nodePositions: {
+        control_start: { x: 100, y: 300 },
+        control_end: { x: 380, y: 300 },
+      },
+    },
+  };
+
+  const text = yaml.dump(skeleton, { lineWidth: -1, noRefs: true });
+  fs.writeFileSync(flowYamlAbs, text, "utf-8");
+  return { created: true, reason: "wrote start+end skeleton" };
+}
+
+/**
+ * 写入 composer-node-spec.md 模板（如已存在则跳过）。
+ * @param {string} specMdAbs
+ * @param {{ flowId?: string, userRequest?: string }} [meta]
+ * @returns {{ created: boolean, reason: string }}
+ */
+export function ensureNodeSpecSkeleton(specMdAbs, meta = {}) {
+  if (!specMdAbs) return { created: false, reason: "missing specMdAbs" };
+
+  if (fs.existsSync(specMdAbs)) {
+    try {
+      const raw = fs.readFileSync(specMdAbs, "utf-8").trim();
+      if (raw.length > 0) {
+        return { created: false, reason: "spec.md already exists" };
+      }
+    } catch { /* fallthrough */ }
+  }
+
+  fs.mkdirSync(path.dirname(specMdAbs), { recursive: true });
+
+  const flowId = meta.flowId || "(unknown)";
+  const userRequest = (meta.userRequest || "").trim() || "(未提供)";
+  const ts = new Date().toISOString();
+
+  const tmpl = `# composer-node-spec — ${flowId}
+
+> 生成时间：${ts}
+> 用户原始需求：
+${userRequest.split("\n").map((l) => "> " + l).join("\n")}
+
+## 整体框架
+
+<!--
+  AI 在此填写整体设计意图：
+  - 主链节点序列（Start → ... → End）
+  - 分支结构（control_if 的真假分支去向）
+  - 循环结构（control_anyOne + control_toBool + control_if 的环路）
+  - 并行结构（如有）
+  - 全局数据（SaveKey / LoadKey 跨节点共享的 key）
+-->
+
+## 节点职责
+
+<!--
+  按 instanceId 分小节，**每节点必须写齐 4 项**：
+    **职责**：一句话说该节点做什么
+    **输入**：列出每个 input 槽 → 语义 + 来源（上游 instanceId.slot）
+    **输出**：列出每个 output 槽 → 语义 + 去向（下游 instanceId.slot）
+    **实现要点**：tool_nodejs 写脚本路径（scripts/xxx.mjs）、agent_subAgent 写 body 关键点、control_* 写判定/汇合规则、provide_* 写固定值
+  说明：
+  - **输入/输出**就是阶段三连线的依据——把每个槽位的「上游来源」和「下游去向」写清，连边 sourceHandle/targetHandle 就一目了然
+  - 控制流槽（prev/next）也要写，标「控制流：来自 <upstream>.next」即可
+  - 业务数据槽（text/file）必须写清语义，让阶段二节点补充时知道 body/script 该用什么 \${slot} 占位符
+  - tool_nodejs 的可执行代码留到阶段二写，本阶段只需脚本路径与 I/O 语义
+-->
+
+### control_start
+**职责**：流程入口
+**输入**：—
+**输出**：next:node → 给 <下一个节点>.prev（控制流，启动主链）
+
+### control_end
+**职责**：流程出口
+**输入**：prev:node ← 来自 <最后一个节点>.next（控制流）
+**输出**：—
+
+<!-- 在此后追加每个新节点的小节 -->
+
+## 计划数据槽（仅 ★ 可扩展节点需追加的业务槽）
+
+<!--
+  本 section 是**完整业务数据槽设计**——是 spec.md 的权威记录与阶段二/三对账依据。
+  仅对 ★ 可扩展节点（agent_subAgent / tool_nodejs / tool_user_check）列出需要在 input/output 数组**末尾追加**的业务数据槽。
+  固定槽位节点（control_*、provide_*、tool_load_key、tool_save_key、tool_get_env、tool_print、tool_user_ask）槽位结构由 schema 锁死，**不在此列出**。
+
+  **重要：阶段一 AI 应该同时把这些槽落到 flow.yaml**（鼓励一次写到位）。
+  - 已落到 yaml → 阶段二按 name 去重跳过，不影响幂等
+  - 未落到 yaml → 阶段二脚本/agent 据此 section 补齐
+
+  格式（机器可解析）：
+    <instanceId>:
+      input += [<name>:<text|file>, ...]
+      output += [<name>:<text|file>, ...]
+  type 仅可用 \`text\`（短串/路径/JSON）或 \`file\`（大块产物路径），**禁止 node**。
+  命名建议与上下游语义对齐（如下游 \`fromapp\` 的入参，上游就用同名 output）便于连线。
+  示例：
+    agent_analyze:
+      input += [fromapp:text, page_name:text]
+      output += [analysis:file]
+    agent_convert:
+      input += [analysis:file, toapp:text]
+      output += [converted_code:file]
+    agent_check_compile:
+      input += [converted_code:file]
+      output += [compile_result:text]
+-->
+`;
+
+  fs.writeFileSync(specMdAbs, tmpl, "utf-8");
+  return { created: true, reason: "wrote spec.md template" };
+}
+
+/**
+ * 阶段一前置：同时确保 flow.yaml + spec.md 两份骨架。
+ * @param {{ flowYamlAbs: string, composerSpecAbs?: string, flowId?: string, userRequest?: string }} opts
+ * @returns {{ flow: ReturnType<typeof ensureFlowSkeleton>, spec: ReturnType<typeof ensureNodeSpecSkeleton> }}
+ */
+export function ensurePhase1Skeletons(opts) {
+  const flow = ensureFlowSkeleton(opts.flowYamlAbs);
+  const spec = opts.composerSpecAbs
+    ? ensureNodeSpecSkeleton(opts.composerSpecAbs, { flowId: opts.flowId, userRequest: opts.userRequest })
+    : { created: false, reason: "missing composerSpecAbs" };
+  return { flow, spec };
+}
+
+// ─── 解析 spec.md「计划数据槽」+ 合并到 flow.yaml ──────────────────────────
+
+const VALID_BUSINESS_TYPES = new Set(["text", "file"]);
+
+/**
+ * 从 spec.md 文本中解析「计划数据槽」section。
+ * 期望格式：
+ *   ## 计划数据槽（...）
+ *   <instanceId>:
+ *     input += [<name>:<type>, <name>:<type>]
+ *     output += [<name>:<type>]
+ * @param {string} specText
+ * @returns {Record<string, { input: Array<{name,type}>, output: Array<{name,type}> }>}
+ */
+export function parsePlannedSlotsFromSpec(specText) {
+  if (!specText || typeof specText !== "string") return {};
+  const idx = specText.search(/^##\s+计划数据槽/m);
+  if (idx < 0) return {};
+  const section = specText.slice(idx);
+  // 截到下一个 ## 或 EOF
+  const nextH = section.slice(2).search(/^##\s/m);
+  const body = nextH >= 0 ? section.slice(0, nextH + 2) : section;
+
+  const result = {};
+  // 按 instanceId 块分割：行首非缩进的 "<id>:" 起一个块
+  const lines = body.split("\n");
+  let currentId = null;
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, "");
+    // 跳过 HTML 注释、标题、空行
+    if (/^\s*$/.test(line)) continue;
+    if (/^<!--|-->\s*$|^##\s/.test(line)) continue;
+
+    const idMatch = /^\s{0,2}([A-Za-z][A-Za-z0-9_]*)\s*:\s*$/.exec(line);
+    if (idMatch) {
+      currentId = idMatch[1];
+      if (!result[currentId]) result[currentId] = { input: [], output: [] };
+      continue;
+    }
+    // input += [...] / output += [...]
+    const slotMatch = /^\s*(input|output)\s*\+?=\s*\[([^\]]*)\]\s*$/.exec(line);
+    if (slotMatch && currentId) {
+      const kind = slotMatch[1];
+      const items = slotMatch[2].split(",").map((s) => s.trim()).filter(Boolean);
+      for (const item of items) {
+        const m = /^([A-Za-z][A-Za-z0-9_]*)\s*:\s*([a-z]+)$/.exec(item);
+        if (!m) continue;
+        const name = m[1];
+        const type = m[2];
+        if (!VALID_BUSINESS_TYPES.has(type)) continue;
+        result[currentId][kind].push({ name, type });
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * 把 spec.md 解析出的业务槽合并到 flow.yaml（幂等：同 name 跳过）。
+ * 仅对 ★ 可扩展节点（agent_subAgent / tool_nodejs / tool_user_check）操作；
+ * 其它 definitionId 上的 planned 数据**忽略**（属于 spec.md 误写，不要破坏固定槽位）。
+ *
+ * @param {string} flowYamlAbs
+ * @param {string} specMdAbs
+ * @returns {{ ok: boolean, applied: Array<{instanceId, addedInputs: string[], addedOutputs: string[]}>, skipped: Array<{instanceId, reason: string}>, error?: string }}
+ */
+export function applyPlannedSlotsFromSpec(flowYamlAbs, specMdAbs) {
+  if (!flowYamlAbs || !fs.existsSync(flowYamlAbs)) return { ok: false, applied: [], skipped: [], error: "flow.yaml not found" };
+  if (!specMdAbs || !fs.existsSync(specMdAbs)) return { ok: false, applied: [], skipped: [], error: "spec.md not found" };
+
+  const EXTENSIBLE = new Set(["agent_subAgent", "tool_nodejs", "tool_user_check"]);
+  const applied = [];
+  const skipped = [];
+
+  let flow;
+  try {
+    flow = yaml.load(fs.readFileSync(flowYamlAbs, "utf-8"));
+  } catch (e) {
+    return { ok: false, applied: [], skipped: [], error: `failed to parse flow.yaml: ${e.message}` };
+  }
+  if (!flow || typeof flow !== "object" || !flow.instances) {
+    return { ok: false, applied: [], skipped: [], error: "flow.yaml has no instances" };
+  }
+
+  let planned;
+  try {
+    const specText = fs.readFileSync(specMdAbs, "utf-8");
+    planned = parsePlannedSlotsFromSpec(specText);
+  } catch (e) {
+    return { ok: false, applied: [], skipped: [], error: `failed to parse spec.md: ${e.message}` };
+  }
+
+  let mutated = false;
+  for (const [instanceId, plan] of Object.entries(planned)) {
+    const inst = flow.instances[instanceId];
+    if (!inst || typeof inst !== "object") {
+      skipped.push({ instanceId, reason: "instance not in flow.yaml" });
+      continue;
+    }
+    if (!EXTENSIBLE.has(inst.definitionId)) {
+      skipped.push({ instanceId, reason: `non-extensible definitionId: ${inst.definitionId}` });
+      continue;
+    }
+    if (!Array.isArray(inst.input)) inst.input = [];
+    if (!Array.isArray(inst.output)) inst.output = [];
+
+    const existingInputNames = new Set(inst.input.map((s) => s && s.name).filter(Boolean));
+    const existingOutputNames = new Set(inst.output.map((s) => s && s.name).filter(Boolean));
+    const addedInputs = [];
+    const addedOutputs = [];
+
+    for (const { name, type } of plan.input) {
+      if (existingInputNames.has(name)) continue;
+      inst.input.push({ type, name, value: "" });
+      existingInputNames.add(name);
+      addedInputs.push(`${name}:${type}`);
+      mutated = true;
+    }
+    for (const { name, type } of plan.output) {
+      if (existingOutputNames.has(name)) continue;
+      inst.output.push({ type, name, value: "" });
+      existingOutputNames.add(name);
+      addedOutputs.push(`${name}:${type}`);
+      mutated = true;
+    }
+
+    if (addedInputs.length > 0 || addedOutputs.length > 0) {
+      applied.push({ instanceId, addedInputs, addedOutputs });
+    }
+  }
+
+  if (mutated) {
+    fs.writeFileSync(flowYamlAbs, yaml.dump(flow, { lineWidth: -1, noRefs: true }), "utf-8");
+  }
+  return { ok: true, applied, skipped };
+}

package/bin/lib/composer-flow-validate.mjs

@@ -0,0 +1,47 @@
+/**
+ * Web UI Composer：对当前 flow.yaml 调用与 CLI 一致的 validate-flow 逻辑。
+ * agent 有时会把 flow.yaml 写到 workspace 路径而非 user 路径（或反之），
+ * 当原路径找不到时，尝试在 workspace 下的 .workspace/agentflow/pipelines/ 和
+ * agentflow/pipelines/ 中查找同名目录。
+ */
+import fs from "fs";
+import path from "path";
+import { runValidateFlow } from "../pipeline/validate-flow.mjs";
+
+/**
+ * @param {string} flowYamlAbs
+ * @param {string} workspaceRoot
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateComposerFlowYaml(flowYamlAbs, workspaceRoot) {
+  let flowDir = path.dirname(path.resolve(flowYamlAbs));
+  const root = path.resolve(workspaceRoot);
+
+  if (!fs.existsSync(path.join(flowDir, "flow.yaml"))) {
+    const flowId = path.basename(flowDir);
+    const candidates = [
+      path.join(root, ".workspace", "agentflow", "pipelines", flowId),
+      path.join(root, "agentflow", "pipelines", flowId),
+      path.join(root, ".cursor", "agentflow", "pipelines", flowId),
+    ];
+    for (const c of candidates) {
+      if (fs.existsSync(path.join(c, "flow.yaml"))) {
+        flowDir = c;
+        break;
+      }
+    }
+  }
+
+  return runValidateFlow(flowDir, root);
+}
+
+/**
+ * @param {{ ok?: boolean, errors?: string[] }} result
+ * @returns {string}
+ */
+export function formatValidationErrorsBlock(result) {
+  if (!result) return "（校验无返回）";
+  const errs = Array.isArray(result.errors) ? result.errors : [];
+  if (errs.length === 0) return "（无 errors 字段，请检查 flow.yaml 结构）";
+  return errs.map((e, i) => `${i + 1}. ${e}`).join("\n");
+}

package/bin/lib/composer-log.mjs

@@ -0,0 +1,197 @@
+/**
+ * Composer AI 对话日志记录模块。
+ * 
+ * 将 UI 上 AI 对话生成 flow 的过程持久化到磁盘，便于调试。
+ * 
+ * 日志位置：<workspaceRoot>/.workspace/agentflow/composer-logs/<YYYY-MM>/<YYYY-MM-DD_HHMMSS_<short-uuid>.log>
+ * 格式：[ISO8601] [tag] JSON event or message
+ */
+
+import fs from "fs";
+import path from "path";
+
+const COMPOSER_LOGS_DIR = "composer-logs";
+
+function getComposerLogsRoot(workspaceRoot) {
+  const root = workspaceRoot && String(workspaceRoot).trim() !== ""
+    ? path.resolve(String(workspaceRoot))
+    : process.cwd();
+  return path.join(root, ".workspace/agentflow", COMPOSER_LOGS_DIR);
+}
+
+function generateShortUuid() {
+  return Math.random().toString(36).slice(2, 8);
+}
+
+function formatTimestampForFilename() {
+  const now = new Date();
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  const hh = String(now.getHours()).padStart(2, "0");
+  const min = String(now.getMinutes()).padStart(2, "0");
+  const ss = String(now.getSeconds()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}_${hh}${min}${ss}`;
+}
+
+function getMonthDir() {
+  const now = new Date();
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  return `${yyyy}-${mm}`;
+}
+
+/**
+ * 创建新的 Composer 对话日志会话。
+ * @param {string} workspaceRoot 工作区根目录
+ * @returns {{ sessionId: string, logPath: string, monthDir: string }}
+ */
+export function createComposerSession(workspaceRoot) {
+  const logsRoot = getComposerLogsRoot(workspaceRoot);
+  const monthDir = getMonthDir();
+  const monthPath = path.join(logsRoot, monthDir);
+  
+  fs.mkdirSync(monthPath, { recursive: true });
+  
+  const ts = formatTimestampForFilename();
+  const shortUuid = generateShortUuid();
+  const sessionId = `${ts}_${shortUuid}`;
+  const logPath = path.join(monthPath, `${sessionId}.log`);
+  
+  return { sessionId, logPath, monthDir };
+}
+
+/**
+ * 向 Composer 日志文件追加一行事件。
+ * @param {string} logPath 日志文件绝对路径
+ * @param {string} tag 事件标签：composer-start | classify | plan | step-start | step-progress | step-done | validation | phase-plan | phase-complete | phase-auto-continue | natural | error | composer-done
+ * @param {object|string} payload 事件内容（对象会 JSON.stringify）
+ */
+export function logComposerEvent(logPath, tag, payload) {
+  if (!logPath) return;
+  try {
+    const ts = new Date().toISOString();
+    const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const line = `[${ts}] [${tag}] ${text}\n`;
+    fs.appendFileSync(logPath, line, "utf-8");
+  } catch (e) {
+    process.stderr.write(`[composer-log] 写入失败: ${e.message}\n`);
+  }
+}
+
+/**
+ * 截断文本以便日志记录（避免日志文件过大）。
+ * @param {string} text 原始文本
+ * @param {number} maxLen 最大长度（默认 2000）
+ * @returns {string}
+ */
+export function truncateForLog(text, maxLen = 2000) {
+  if (!text || typeof text !== "string") return "";
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen) + "…(截断)";
+}
+
+/**
+ * 获取 Composer 日志目录路径（供外部查询）。
+ * @param {string} workspaceRoot 工作区根目录
+ * @returns {string}
+ */
+export function getComposerLogsDir(workspaceRoot) {
+  return getComposerLogsRoot(workspaceRoot);
+}
+
+/**
+ * 列出最近的 Composer 日志会话。
+ * @param {string} workspaceRoot 工作区根目录
+ * @param {number} limit 最大数量（默认 20）
+ * @returns {Array<{ sessionId: string, logPath: string, monthDir: string, size: number, mtime: Date }>}
+ */
+export function listRecentComposerSessions(workspaceRoot, limit = 20) {
+  const logsRoot = getComposerLogsRoot(workspaceRoot);
+  if (!fs.existsSync(logsRoot)) return [];
+  
+  const sessions = [];
+  const monthDirs = fs.readdirSync(logsRoot).filter((d) => /^\d{4}-\d{2}$/.test(d));
+  
+  for (const monthDir of monthDirs) {
+    const monthPath = path.join(logsRoot, monthDir);
+    if (!fs.statSync(monthPath).isDirectory()) continue;
+    
+    const files = fs.readdirSync(monthPath).filter((f) => f.endsWith(".log"));
+    for (const file of files) {
+      const logPath = path.join(monthPath, file);
+      const stat = fs.statSync(logPath);
+      sessions.push({
+        sessionId: file.replace(".log", ""),
+        logPath,
+        monthDir,
+        size: stat.size,
+        mtime: stat.mtime,
+      });
+    }
+  }
+  
+  sessions.sort((a, b) => b.mtime - a.mtime);
+  return sessions.slice(0, limit);
+}
+
+/**
+ * 解析日志文件为事件数组。每行格式：[ISO8601] [tag] {json} 或 string。
+ * 多行字段（含换行的 prompt/response）通过 JSON 序列化保留为 \n，所以每行始终是单条事件。
+ * @param {string} logPath
+ * @returns {Array<{ ts: string, tag: string, payload: any }>}
+ */
+export function parseComposerLogFile(logPath) {
+  if (!logPath || !fs.existsSync(logPath)) return [];
+  const raw = fs.readFileSync(logPath, "utf-8");
+  const events = [];
+  const lines = raw.split("\n");
+  for (const line of lines) {
+    if (!line) continue;
+    const m = line.match(/^\[([^\]]+)\]\s+\[([^\]]+)\]\s+(.*)$/);
+    if (!m) continue;
+    const ts = m[1];
+    const tag = m[2];
+    const rest = m[3];
+    let payload;
+    try {
+      payload = JSON.parse(rest);
+    } catch {
+      payload = rest;
+    }
+    events.push({ ts, tag, payload });
+  }
+  return events;
+}
+
+/**
+ * 从日志文件首行尝试提取 composer-start 中的元数据（flowId, model, prompt 等）。
+ * @param {string} logPath
+ * @returns {{ flowId: string|null, flowSource: string|null, model: string|null, prompt: string|null, sessionId: string|null }}
+ */
+export function readComposerSessionMeta(logPath) {
+  const empty = { flowId: null, flowSource: null, model: null, prompt: null, sessionId: null };
+  try {
+    if (!fs.existsSync(logPath)) return empty;
+    const raw = fs.readFileSync(logPath, "utf-8");
+    const lines = raw.split("\n");
+    for (const line of lines) {
+      const m = line.match(/^\[([^\]]+)\]\s+\[composer-start\]\s+(.*)$/);
+      if (m) {
+        try {
+          const obj = JSON.parse(m[2]);
+          return {
+            flowId: obj.flowId || null,
+            flowSource: obj.flowSource || null,
+            model: obj.model || null,
+            prompt: obj.prompt || null,
+            sessionId: obj.sessionId || null,
+          };
+        } catch {
+          return empty;
+        }
+      }
+    }
+  } catch { /* ignore */ }
+  return empty;
+}