@ai-setting/roy-agent-core 1.7.49 → 1.7.50

package/dist/shared/@ai-setting/roy-agent-core-zd077w51.js

@@ -0,0 +1,1037 @@
+import {
+  TracedAs,
+  init_decorator
+} from "./roy-agent-core-dsevjbck.js";
+import {
+  createLogger,
+  init_logger
+} from "./roy-agent-core-8seq65bp.js";
+import {
+  __legacyDecorateClassTS
+} from "./roy-agent-core-fs0mn2jk.js";
+
+// src/env/task/plugins/lark-card-patch-notifier.ts
+init_logger();
+init_decorator();
+import { spawn } from "node:child_process";
+var logger = createLogger("lark-cli:card-patch-notifier");
+var HEADER_TEMPLATE = {
+  running: "blue",
+  completed: "green",
+  failed: "red",
+  stopped: "grey"
+};
+var STATUS_PHRASE = {
+  running: "实时同步中",
+  completed: "\uD83C\uDF89 全部完成！",
+  failed: "\uD83D\uDEA8 任务失败",
+  stopped: "⏹️ 已停止"
+};
+var SPINNER_EMOJIS = ["⏳", "\uD83D\uDD04", "\uD83D\uDD03", "⌛", "⏰", "\uD83D\uDD01"];
+var PROGRESS_BAR_CELLS = 20;
+function formatTimestampForDisplay(iso) {
+  if (!iso)
+    return "";
+  const d = new Date(iso);
+  if (isNaN(d.getTime())) {
+    return iso;
+  }
+  return new Intl.DateTimeFormat("en-GB", {
+    timeZone: "Asia/Shanghai",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  }).format(d);
+}
+function sanitizeInlineText(text, maxLen = 300) {
+  if (!text)
+    return "";
+  const flat = text.replace(/\r\n?/g, `
+`).replace(/^#{1,6}\s+/gm, "").replace(/^\s*[-*+]\s+/gm, "· ").replace(/^\s*\d+\.\s+/gm, "· ").replace(/\*\*/g, "").replace(/`/g, "").replace(/\n+/g, " · ").replace(/\s{2,}/g, " ").replace(/(?:\s*·\s*){2,}/g, " · ").replace(/^(\s*·\s*)+/, "").replace(/(\s*·\s*)+$/, "").trim();
+  return flat.length <= maxLen ? flat : `${flat.slice(0, maxLen)}…`;
+}
+function formatDateTimeForDisplay(value) {
+  const d = new Date(value);
+  if (isNaN(d.getTime()))
+    return value;
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Asia/Shanghai",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false
+  }).formatToParts(d);
+  const get = (t) => parts.find((p) => p.type === t)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")} ${get("hour")}:${get("minute")}`;
+}
+function looksLikeIsoDateTime(v) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(v);
+}
+function renderProgressBar(progress) {
+  const clamped = Math.max(0, Math.min(100, progress));
+  const filled = Math.round(clamped / 100 * PROGRESS_BAR_CELLS);
+  const bar = "▓".repeat(filled) + "░".repeat(PROGRESS_BAR_CELLS - filled);
+  return `${bar} ${Math.round(clamped)}%`;
+}
+function humanizeValue(value, maxLen = 200) {
+  const truncate = (t) => t.length <= maxLen ? t : `${t.slice(0, maxLen)}…`;
+  if (value === null || value === undefined)
+    return "";
+  if (typeof value === "string") {
+    if (looksLikeIsoDateTime(value))
+      return formatDateTimeForDisplay(value);
+    return truncate(sanitizeInlineText(value, maxLen));
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return truncate(value.map((v) => humanizeValue(v, 80)).filter((t) => t.length > 0).join("、"));
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value).map(([k, v]) => {
+      const rendered = humanizeValue(v, 80);
+      return rendered ? `${k}: ${rendered}` : "";
+    }).filter((t) => t.length > 0);
+    return truncate(entries.join(" · "));
+  }
+  return "";
+}
+var CONTEXT_LABELS = {
+  worktree_path: "\uD83C\uDF3F Worktree",
+  branch: "\uD83C\uDF3F 分支",
+  created_at: "\uD83D\uDD50 创建时间",
+  prior_context: "\uD83D\uDCDC 背景",
+  project_path: "\uD83D\uDCC2 项目",
+  type: "\uD83C\uDFF7️ 类型",
+  feature: "\uD83C\uDFF7️ 特性",
+  goal: "\uD83C\uDFAF 目标",
+  feishu_chat_id: "\uD83D\uDCAC 飞书群",
+  trigger_message_id: "✉️ 触发消息",
+  trigger_sender_id: "\uD83D\uDC64 触发人",
+  related_task: "\uD83D\uDD17 关联任务",
+  repo: "\uD83D\uDCE6 仓库",
+  commit: "\uD83D\uDD16 Commit",
+  session_id: "\uD83E\uDDF5 Session",
+  worktree: "\uD83C\uDF3F Worktree",
+  larkPerTaskChatId: "\uD83D\uDDC2️ 任务群聊",
+  larkPerTaskChatProfile: "\uD83D\uDDC2️ 群聊 Profile"
+};
+var CONTEXT_SKIP_KEYS = new Set([
+  "larkPerTaskChatTaskId",
+  "larkPerTaskChatCreatedAt"
+]);
+function renderTaskInfoLines(meta) {
+  const lines = [];
+  if (meta.id !== undefined)
+    lines.push(`- **\uD83C\uDD94 任务 ID**：#${meta.id}`);
+  if (meta.title) {
+    lines.push(`- **\uD83D\uDCCC 标题**：${sanitizeInlineText(meta.title, 120)}`);
+  }
+  if (meta.description) {
+    lines.push(`- **\uD83D\uDCDD 描述**：${sanitizeInlineText(meta.description, 300)}`);
+  }
+  if (meta.goals) {
+    lines.push(`- **\uD83C\uDFAF 目标**：${sanitizeInlineText(meta.goals, 300)}`);
+  }
+  if (meta.parentTaskId)
+    lines.push(`- **\uD83D\uDD17 父任务**：#${meta.parentTaskId}`);
+  if (meta.priority || meta.type) {
+    lines.push(`- **⚡ 优先级 / 类型**：${meta.priority ?? "—"} / ${meta.type ?? "—"}`);
+  }
+  if (meta.currentStatus) {
+    lines.push(`- **\uD83D\uDCF6 当前状态**：${sanitizeInlineText(meta.currentStatus, 200)}`);
+  }
+  const project = realValue(meta.projectPath);
+  if (project)
+    lines.push(`- **\uD83D\uDCC2 项目**：\`${sanitizeInlineText(project, 160)}\``);
+  const contextLines = renderContextAsLines(meta.context);
+  lines.push(...contextLines);
+  return lines;
+}
+function realValue(v) {
+  if (!v)
+    return;
+  const t = v.trim();
+  if (t.length === 0 || t === "unknown" || t === "undefined" || t === "null") {
+    return;
+  }
+  return t;
+}
+function renderContextAsLines(context) {
+  const raw = realValue(context);
+  if (!raw)
+    return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    return [];
+  const obj = parsed;
+  const lines = [];
+  const knownKeys = Object.keys(obj).filter((k) => CONTEXT_LABELS[k] && !CONTEXT_SKIP_KEYS.has(k));
+  const otherKeys = Object.keys(obj).filter((k) => !CONTEXT_LABELS[k] && !CONTEXT_SKIP_KEYS.has(k));
+  for (const k of knownKeys) {
+    const rendered = humanizeValue(obj[k], 160);
+    if (rendered)
+      lines.push(`- **${CONTEXT_LABELS[k]}**：${rendered}`);
+  }
+  for (const k of otherKeys) {
+    const rendered = humanizeValue(obj[k], 160);
+    if (rendered)
+      lines.push(`- **${k}**：${rendered}`);
+  }
+  return lines;
+}
+function renderMilestones(milestones) {
+  if (milestones.length === 0) {
+    return "_（暂无里程碑）_";
+  }
+  return milestones.map((m) => {
+    const ts = formatTimestampForDisplay(m.timestamp) || "—";
+    const head = `- **${ts}** ${sanitizeInlineText(m.title, 120)}`;
+    return m.description ? `${head}
+  - ${sanitizeInlineText(m.description, 300)}` : head;
+  }).join(`
+`);
+}
+function renderProcessSteps(steps) {
+  if (steps.length === 0) {
+    return "_（暂无过程记录）_";
+  }
+  return steps.map((s) => {
+    const startTime = formatTimestampForDisplay(s.timestamp);
+    const endTime = formatTimestampForDisplay(s.endTimestamp) || "现在";
+    const range = startTime ? `${startTime} → ${endTime}` : endTime;
+    const title = s.category ? `${s.title}（${s.category}）` : s.title;
+    const head = `- **${range}** ${sanitizeInlineText(title, 120)}`;
+    return s.description ? `${head}
+  - ${sanitizeInlineText(s.description, 300)}` : head;
+  }).join(`
+`);
+}
+function milestoneKey(m) {
+  return `${m.title}|${m.timestamp ?? ""}|${m.description ?? ""}`;
+}
+function processStepKey(s) {
+  return `${s.title}|${s.timestamp ?? ""}|${s.endTimestamp ?? ""}|${s.description ?? ""}`;
+}
+function buildTaskCard(opts) {
+  const status = opts.status ?? "running";
+  const milestones = opts.milestones ?? [];
+  const processSteps = opts.processSteps ?? [];
+  const updateCount = opts.updateCount ?? 0;
+  const spinner = opts.spinner ?? "";
+  const elements = [];
+  const infoLines = renderTaskInfoLines(opts.meta);
+  if (infoLines.length > 0) {
+    elements.push({ tag: "markdown", content: infoLines.join(`
+`) });
+    elements.push({ tag: "hr" });
+  }
+  elements.push({ tag: "markdown", content: `## \uD83C\uDFAF 里程碑序列` });
+  elements.push({ tag: "markdown", content: renderMilestones(milestones) });
+  elements.push({ tag: "hr" });
+  elements.push({ tag: "markdown", content: `## \uD83D\uDD27 过程信息` });
+  elements.push({ tag: "markdown", content: renderProcessSteps(processSteps) });
+  elements.push({ tag: "hr" });
+  const effectiveProgress = status === "completed" ? 100 : opts.progress;
+  elements.push({
+    tag: "markdown",
+    content: effectiveProgress !== undefined ? `**\uD83D\uDCCA 进度**：${renderProgressBar(effectiveProgress)}` : `**\uD83D\uDCCA 进度**：进行中（第 ${updateCount} 次更新，尚未上报百分比）`
+  });
+  const taskLabel = opts.meta.id !== undefined ? `#${opts.meta.id}` : "任务";
+  return {
+    schema: "2.0",
+    header: {
+      title: { tag: "plain_text", content: `\uD83D\uDCCA Task 实时更新（${taskLabel}）` },
+      subtitle: {
+        tag: "plain_text",
+        content: `spinner: '${spinner}' · 第 ${updateCount} 次更新 | ` + STATUS_PHRASE[status]
+      },
+      template: HEADER_TEMPLATE[status]
+    },
+    body: { elements }
+  };
+}
+function buildChatAppLink(chatId, base = DEFAULT_APP_LINK_BASE) {
+  return `${base}/client/chat/open?openChatId=${chatId}`;
+}
+var DEFAULT_APP_LINK_BASE = "https://applink.feishu.cn";
+function buildRedirectCard(opts) {
+  const taskLabel = opts.taskId !== undefined ? `#${opts.taskId}` : "本任务";
+  const title = opts.taskTitle ? ` ${sanitizeInlineText(opts.taskTitle, 120)}` : "";
+  const link = buildChatAppLink(opts.targetChatId);
+  const groupName = opts.targetChatName ? sanitizeInlineText(opts.targetChatName, 60) : "专属群";
+  return {
+    schema: "2.0",
+    header: {
+      title: { tag: "plain_text", content: "\uD83D\uDCC2 任务卡片已改投专属群" },
+      subtitle: { tag: "plain_text", content: "这里不是本任务的群，进展请看专属群" },
+      template: "grey"
+    },
+    body: {
+      elements: [
+        {
+          tag: "markdown",
+          content: [
+            `- **任务**：${taskLabel}${title}`,
+            `- **专属群**：[${groupName}](${link})`,
+            `- **群 ID**：\`${opts.targetChatId}\`（搜群名也能进）`,
+            opts.reason ? `- **原因**：${sanitizeInlineText(opts.reason, 280)}` : ""
+          ].filter(Boolean).join(`
+`)
+        }
+      ]
+    }
+  };
+}
+var WORKFLOW_STATUS_LABEL = {
+  running: "\uD83D\uDD04 运行中",
+  completed: "✅ 已完成",
+  failed: "\uD83D\uDEA8 已失败",
+  stopped: "⏹️ 已停止"
+};
+var WORKFLOW_STATUS_PHRASE = {
+  running: "实时同步中",
+  completed: "\uD83C\uDF89 流程跑完！",
+  failed: "\uD83D\uDEA8 流程失败",
+  stopped: "⏹️ 流程已停止"
+};
+function formatDurationMs(ms) {
+  if (ms === undefined || ms === null || Number.isNaN(ms))
+    return "";
+  if (ms < 1000)
+    return `${Math.round(ms)}ms`;
+  if (ms < 60000) {
+    const s = ms / 1000;
+    return Number.isInteger(s) ? `${s}s` : `${s.toFixed(1)}s`;
+  }
+  const m = ms / 60000;
+  return Number.isInteger(m) ? `${m}m` : `${m.toFixed(1)}m`;
+}
+function deriveProgress(opts) {
+  if (opts.progress !== undefined)
+    return opts.progress;
+  if (typeof opts.completedNodes === "number" && typeof opts.totalNodes === "number" && opts.totalNodes > 0) {
+    return opts.completedNodes / opts.totalNodes * 100;
+  }
+  return;
+}
+function renderWorkflowInfoLines(meta, extra) {
+  const lines = [];
+  if (meta.workflowName) {
+    lines.push(`- **\uD83D\uDD04 工作流**：${sanitizeInlineText(meta.workflowName, 120)}`);
+  }
+  if (meta.runId) {
+    lines.push(`- **\uD83C\uDD94 Run ID**：\`${sanitizeInlineText(meta.runId, 120)}\``);
+  }
+  if (meta.workflowId) {
+    lines.push(`- **\uD83C\uDFF7️ Workflow ID**：\`${sanitizeInlineText(meta.workflowId, 120)}\``);
+  }
+  lines.push(`- **\uD83D\uDCF6 状态**：${WORKFLOW_STATUS_LABEL[extra.status]}`);
+  if (typeof extra.totalNodes === "number" && extra.totalNodes > 0) {
+    const done = typeof extra.completedNodes === "number" ? extra.completedNodes : 0;
+    lines.push(`- **\uD83E\uDDE9 节点进度**：${done}/${extra.totalNodes}`);
+  }
+  if (extra.currentNode) {
+    const type = extra.currentNodeType ? `（${extra.currentNodeType}）` : "";
+    lines.push(`- **\uD83E\uDDED 当前节点**：${sanitizeInlineText(extra.currentNode, 80)}${type}`);
+  }
+  const duration = formatDurationMs(extra.durationMs);
+  if (duration) {
+    lines.push(`- **⚡ 耗时**：${duration}`);
+  }
+  if (extra.error) {
+    const label = extra.status === "stopped" ? "⏹️ 停止原因" : "\uD83D\uDEA8 失败原因";
+    lines.push(`- **${label}**：${sanitizeInlineText(extra.error, 300)}`);
+  }
+  if (meta.input !== undefined && meta.input !== null) {
+    const rendered = humanizeValue(meta.input, 200);
+    if (rendered) {
+      lines.push(`- **\uD83D\uDCE5 触发输入**：${rendered}`);
+    }
+  }
+  return lines;
+}
+function buildWorkflowCard(opts) {
+  const status = opts.status ?? "running";
+  const milestones = opts.milestones ?? [];
+  const processSteps = opts.processSteps ?? [];
+  const updateCount = opts.updateCount ?? 0;
+  const spinner = opts.spinner ?? "";
+  const elements = [];
+  const infoLines = renderWorkflowInfoLines(opts.meta, {
+    status,
+    totalNodes: opts.totalNodes,
+    completedNodes: opts.completedNodes,
+    currentNode: opts.currentNode,
+    currentNodeType: opts.currentNodeType,
+    durationMs: opts.durationMs,
+    error: opts.error
+  });
+  if (infoLines.length > 0) {
+    elements.push({ tag: "markdown", content: infoLines.join(`
+`) });
+    elements.push({ tag: "hr" });
+  }
+  elements.push({ tag: "markdown", content: `## \uD83C\uDFAF 里程碑序列` });
+  elements.push({ tag: "markdown", content: renderMilestones(milestones) });
+  elements.push({ tag: "hr" });
+  elements.push({ tag: "markdown", content: `## \uD83D\uDD27 过程信息` });
+  elements.push({ tag: "markdown", content: renderProcessSteps(processSteps) });
+  const effectiveProgress = status === "completed" ? 100 : deriveProgress({
+    completedNodes: opts.completedNodes,
+    totalNodes: opts.totalNodes,
+    progress: opts.progress
+  });
+  elements.push({ tag: "hr" });
+  elements.push({
+    tag: "markdown",
+    content: effectiveProgress !== undefined ? `**\uD83D\uDCCA 进度**：${renderProgressBar(effectiveProgress)}` : `**\uD83D\uDCCA 进度**：进行中（第 ${updateCount} 次更新，尚未上报百分比）`
+  });
+  const title = opts.meta.workflowName || opts.meta.runId || "workflow";
+  return {
+    schema: "2.0",
+    header: {
+      title: { tag: "plain_text", content: `\uD83D\uDD04 Workflow 实时更新（${sanitizeInlineText(title, 80)}）` },
+      subtitle: {
+        tag: "plain_text",
+        content: `spinner: '${spinner}' · 第 ${updateCount} 次更新 | ` + WORKFLOW_STATUS_PHRASE[status]
+      },
+      template: HEADER_TEMPLATE[status]
+    },
+    body: { elements }
+  };
+}
+
+class MutexImpl {
+  chain = Promise.resolve();
+  async run(fn) {
+    const prev = this.chain;
+    const next = prev.then(() => fn());
+    this.chain = next.catch(() => {});
+    return next;
+  }
+}
+
+class LarkCardPatchNotifier {
+  options;
+  mutexes = new Map;
+  states = new Map;
+  workflowStates = new Map;
+  redirectsSent = new Set;
+  constructor(options = {}) {
+    this.options = {
+      pinOnStart: true,
+      unpinOnFinish: true,
+      ...options
+    };
+  }
+  mutexFor(messageId) {
+    let m = this.mutexes.get(messageId);
+    if (!m) {
+      m = new MutexImpl;
+      this.mutexes.set(messageId, m);
+    }
+    return m;
+  }
+  async startTask(opts) {
+    const now = new Date().toISOString();
+    const spinner = SPINNER_EMOJIS[0];
+    const milestones = opts.milestones?.length ? opts.milestones : [{ title: "Task 创建", timestamp: now }];
+    const card = buildTaskCard({
+      status: "running",
+      meta: opts.meta,
+      milestones,
+      processSteps: [],
+      updateCount: 1,
+      spinner
+    });
+    const stdout = await this.runLarkCli(this.buildSendCardArgs({ chatId: opts.chatId, profile: opts.profile, card }), "send");
+    const messageId = this.extractMessageId(stdout);
+    if (!messageId) {
+      throw new Error(`lark-cli +messages-send did not return message_id: ${stdout.slice(0, 500)}`);
+    }
+    this.states.set(messageId, {
+      chatId: opts.chatId,
+      profile: opts.profile,
+      meta: opts.meta,
+      startedAt: now,
+      updateCount: 1,
+      spinnerIndex: 0,
+      milestones,
+      processSteps: []
+    });
+    let pinned = false;
+    let pinError;
+    if (this.options.pinOnStart) {
+      try {
+        await this.runLarkCli(this.buildPinArgs({ messageId, profile: opts.profile }), "pin");
+        pinned = true;
+      } catch (pinErr) {
+        pinError = pinErr.message;
+        logger.warn(`Pin failed (non-fatal) for message ${messageId}: ${pinError}`);
+      }
+    }
+    return { messageId, pinned, pinError };
+  }
+  async sendRedirectNotice(opts) {
+    const redirectKey = opts.taskId !== undefined ? `${opts.taskId}:${opts.targetChatId}` : undefined;
+    if (redirectKey) {
+      if (this.redirectsSent.has(redirectKey)) {
+        logger.debug(`sendRedirectNotice: 已发过改投卡片（${redirectKey}）→ 跳过重复发送`);
+        return false;
+      }
+      this.redirectsSent.add(redirectKey);
+    }
+    const card = buildRedirectCard({
+      taskId: opts.taskId,
+      taskTitle: opts.taskTitle,
+      targetChatId: opts.targetChatId,
+      targetChatName: opts.targetChatName,
+      reason: opts.reason
+    });
+    try {
+      await this.runLarkCli(this.buildSendCardArgs({
+        chatId: opts.chatId,
+        profile: opts.profile,
+        card
+      }), "send-redirect");
+      return true;
+    } catch (err) {
+      if (redirectKey)
+        this.redirectsSent.delete(redirectKey);
+      logger.warn(`sendRedirectNotice failed (non-fatal) for chat ${opts.chatId}: ${err.message}`);
+      return false;
+    }
+  }
+  async updateTask(opts) {
+    await this.mutexFor(opts.messageId).run(async () => {
+      const state = this.states.get(opts.messageId) ?? {
+        chatId: opts.chatId ?? "",
+        profile: opts.profile,
+        meta: opts.meta ?? { title: "任务" },
+        startedAt: new Date().toISOString(),
+        updateCount: 0,
+        spinnerIndex: 0,
+        milestones: [],
+        processSteps: []
+      };
+      const mergedMilestones = mergeUnique(state.milestones, opts.milestones ?? [], milestoneKey);
+      const mergedSteps = mergeUnique(state.processSteps, opts.processSteps ?? [], processStepKey);
+      const updateCount = state.updateCount + 1;
+      const spinner = SPINNER_EMOJIS[updateCount % SPINNER_EMOJIS.length];
+      const card = buildTaskCard({
+        status: opts.status,
+        meta: mergeTaskMeta(state.meta, opts.meta),
+        progress: opts.progress ?? state.progress,
+        milestones: mergedMilestones,
+        processSteps: mergedSteps,
+        updateCount,
+        spinner
+      });
+      await this.runLarkCli(this.buildPatchCardArgs({
+        messageId: opts.messageId,
+        profile: opts.profile ?? state.profile,
+        card
+      }), "patch");
+      this.states.set(opts.messageId, {
+        ...state,
+        chatId: opts.chatId ?? state.chatId,
+        profile: opts.profile ?? state.profile,
+        meta: mergeTaskMeta(state.meta, opts.meta),
+        updateCount,
+        spinnerIndex: spinnerIndexFor(updateCount),
+        milestones: mergedMilestones,
+        processSteps: mergedSteps,
+        progress: opts.progress ?? state.progress
+      });
+    });
+  }
+  async finishTask(opts) {
+    await this.mutexFor(opts.messageId).run(async () => {
+      const state = this.states.get(opts.messageId);
+      const now = new Date().toISOString();
+      const updateCount = (state?.updateCount ?? 0) + 1;
+      const spinner = SPINNER_EMOJIS[updateCount % SPINNER_EMOJIS.length];
+      const finalMilestone = {
+        title: opts.status === "completed" ? "Task 完成" : "Task 失败",
+        timestamp: now,
+        description: opts.finalStep
+      };
+      const card = buildTaskCard({
+        status: opts.status,
+        meta: mergeTaskMeta(state?.meta, opts.meta),
+        progress: opts.status === "completed" ? 100 : opts.progress ?? state?.progress,
+        milestones: mergeUnique(state?.milestones ?? [], [finalMilestone], milestoneKey),
+        processSteps: state?.processSteps ?? [],
+        updateCount,
+        spinner
+      });
+      await this.runLarkCli(this.buildPatchCardArgs({
+        messageId: opts.messageId,
+        profile: opts.profile ?? state?.profile,
+        card
+      }), "patch");
+    });
+    if (this.options.unpinOnFinish) {
+      const state = this.states.get(opts.messageId);
+      try {
+        await this.runLarkCli(this.buildUnpinArgs({
+          messageId: opts.messageId,
+          profile: opts.profile ?? state?.profile
+        }), "unpin");
+      } catch (unpinErr) {
+        logger.warn(`Unpin failed (non-fatal) for ${opts.messageId}: ${unpinErr.message}`);
+      }
+    }
+    this.states.delete(opts.messageId);
+    this.mutexes.delete(opts.messageId);
+  }
+  trackedCardCount() {
+    return this.states.size;
+  }
+  trackedWorkflowCardCount() {
+    return this.workflowStates.size;
+  }
+  async startWorkflow(opts) {
+    const now = new Date().toISOString();
+    const spinner = SPINNER_EMOJIS[0];
+    const milestones = opts.milestones?.length ? opts.milestones : [{ title: "Workflow 启动", timestamp: now }];
+    const processSteps = opts.processSteps ?? [];
+    const card = buildWorkflowCard({
+      status: "running",
+      meta: opts.meta,
+      milestones,
+      processSteps,
+      totalNodes: opts.totalNodes,
+      completedNodes: opts.completedNodes ?? 0,
+      updateCount: 1,
+      spinner
+    });
+    const stdout = await this.runLarkCli(this.buildSendCardArgs({ chatId: opts.chatId, profile: opts.profile, card }), "send");
+    const messageId = this.extractMessageId(stdout);
+    if (!messageId) {
+      throw new Error(`lark-cli +messages-send did not return message_id: ${stdout.slice(0, 500)}`);
+    }
+    this.workflowStates.set(messageId, {
+      chatId: opts.chatId,
+      profile: opts.profile,
+      meta: opts.meta,
+      startedAt: now,
+      updateCount: 1,
+      spinnerIndex: 0,
+      milestones,
+      processSteps,
+      completedNodes: opts.completedNodes ?? 0,
+      totalNodes: opts.totalNodes,
+      status: "running"
+    });
+    let pinned = false;
+    let pinError;
+    if (this.options.pinOnStart) {
+      try {
+        await this.runLarkCli(this.buildPinArgs({ messageId, profile: opts.profile }), "pin");
+        pinned = true;
+      } catch (pinErr) {
+        pinError = pinErr.message;
+        logger.warn(`Pin failed (non-fatal) for workflow message ${messageId}: ${pinError}`);
+      }
+    }
+    return { messageId, pinned, pinError };
+  }
+  async updateWorkflow(opts) {
+    await this.mutexFor(opts.messageId).run(async () => {
+      const state = this.workflowStates.get(opts.messageId) ?? {
+        chatId: opts.chatId ?? "",
+        profile: opts.profile,
+        meta: opts.meta ?? { runId: opts.messageId },
+        startedAt: new Date().toISOString(),
+        updateCount: 0,
+        spinnerIndex: 0,
+        milestones: [],
+        processSteps: [],
+        status: "running"
+      };
+      const mergedMilestones = mergeUnique(state.milestones, opts.milestones ?? [], milestoneKey);
+      const mergedSteps = mergeUnique(state.processSteps, opts.processSteps ?? [], processStepKey);
+      const updateCount = state.updateCount + 1;
+      const spinner = SPINNER_EMOJIS[updateCount % SPINNER_EMOJIS.length];
+      const status = opts.status ?? state.status ?? "running";
+      const completedNodes = opts.completedNodes ?? state.completedNodes;
+      const totalNodes = opts.totalNodes ?? state.totalNodes;
+      const card = buildWorkflowCard({
+        status,
+        meta: mergeWorkflowMeta(state.meta, opts.meta),
+        progress: opts.progress ?? state.progress,
+        completedNodes,
+        totalNodes,
+        currentNode: opts.currentNode,
+        currentNodeType: opts.currentNodeType,
+        durationMs: opts.durationMs ?? state.durationMs,
+        error: opts.error ?? state.error,
+        milestones: mergedMilestones,
+        processSteps: mergedSteps,
+        updateCount,
+        spinner
+      });
+      await this.runLarkCli(this.buildPatchCardArgs({
+        messageId: opts.messageId,
+        profile: opts.profile ?? state.profile,
+        card
+      }), "patch");
+      this.workflowStates.set(opts.messageId, {
+        ...state,
+        chatId: opts.chatId ?? state.chatId,
+        profile: opts.profile ?? state.profile,
+        meta: mergeWorkflowMeta(state.meta, opts.meta),
+        updateCount,
+        spinnerIndex: spinnerIndexFor(updateCount),
+        milestones: mergedMilestones,
+        processSteps: mergedSteps,
+        progress: opts.progress ?? state.progress,
+        completedNodes,
+        totalNodes,
+        durationMs: opts.durationMs ?? state.durationMs,
+        error: opts.error ?? state.error,
+        status
+      });
+    });
+  }
+  async finishWorkflow(opts) {
+    await this.mutexFor(opts.messageId).run(async () => {
+      const state = this.workflowStates.get(opts.messageId);
+      const now = new Date().toISOString();
+      const updateCount = (state?.updateCount ?? 0) + 1;
+      const spinner = SPINNER_EMOJIS[updateCount % SPINNER_EMOJIS.length];
+      const titleByStatus = {
+        completed: "Workflow 完成",
+        failed: "Workflow 失败",
+        stopped: "Workflow 停止"
+      };
+      const finalMilestone = {
+        title: titleByStatus[opts.status],
+        timestamp: now,
+        description: opts.finalStep
+      };
+      const completedNodes = opts.completedNodes ?? state?.completedNodes;
+      const totalNodes = opts.totalNodes ?? state?.totalNodes;
+      const card = buildWorkflowCard({
+        status: opts.status,
+        meta: mergeWorkflowMeta(state?.meta, opts.meta),
+        progress: opts.status === "completed" ? 100 : opts.progress ?? state?.progress,
+        completedNodes,
+        totalNodes,
+        durationMs: opts.durationMs ?? state?.durationMs,
+        error: opts.error ?? state?.error,
+        milestones: mergeUnique(state?.milestones ?? [], [finalMilestone], milestoneKey),
+        processSteps: state?.processSteps ?? [],
+        updateCount,
+        spinner
+      });
+      await this.runLarkCli(this.buildPatchCardArgs({
+        messageId: opts.messageId,
+        profile: opts.profile ?? state?.profile,
+        card
+      }), "patch");
+    });
+    if (this.options.unpinOnFinish) {
+      const state = this.workflowStates.get(opts.messageId);
+      try {
+        await this.runLarkCli(this.buildUnpinArgs({
+          messageId: opts.messageId,
+          profile: opts.profile ?? state?.profile
+        }), "unpin");
+      } catch (unpinErr) {
+        logger.warn(`Unpin failed (non-fatal) for workflow ${opts.messageId}: ${unpinErr.message}`);
+      }
+    }
+    this.workflowStates.delete(opts.messageId);
+    this.mutexes.delete(opts.messageId);
+  }
+  buildSendCardArgs(opts) {
+    const args = [
+      "im",
+      "+messages-send",
+      "--chat-id",
+      opts.chatId,
+      "--msg-type",
+      "interactive",
+      "--content",
+      JSON.stringify(opts.card),
+      "--as",
+      "bot"
+    ];
+    if (opts.profile) {
+      args.unshift("--profile", opts.profile);
+    }
+    return args;
+  }
+  buildPatchCardArgs(opts) {
+    const data = JSON.stringify({ content: JSON.stringify(opts.card) });
+    const args = [
+      "im",
+      "messages",
+      "patch",
+      "--message-id",
+      opts.messageId,
+      "--data",
+      data,
+      "--as",
+      "bot"
+    ];
+    if (opts.profile) {
+      args.unshift("--profile", opts.profile);
+    }
+    return args;
+  }
+  buildPinArgs(opts) {
+    const args = [
+      "im",
+      "pins",
+      "create",
+      "--data",
+      JSON.stringify({ message_id: opts.messageId }),
+      "--as",
+      "bot"
+    ];
+    if (opts.profile) {
+      args.unshift("--profile", opts.profile);
+    }
+    return args;
+  }
+  buildUnpinArgs(opts) {
+    const args = [
+      "im",
+      "pins",
+      "delete",
+      "--message-id",
+      opts.messageId,
+      "--yes",
+      "--as",
+      "bot"
+    ];
+    if (opts.profile) {
+      args.unshift("--profile", opts.profile);
+    }
+    return args;
+  }
+  runLarkCli(argv, op) {
+    return new Promise((resolve, reject) => {
+      if (process.env.ROY_HOOK_DEBUG === "1") {
+        console.error(`[DEBUG LarkCardPatchNotifier.runLarkCli] op=${op} args=${JSON.stringify(argv).slice(0, 300)}`);
+      }
+      const proc = spawn("lark-cli", argv, {
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      let stdout = "";
+      let stderr = "";
+      proc.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+      proc.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+      proc.on("close", (code) => {
+        if (process.env.ROY_HOOK_DEBUG === "1") {
+          console.error(`[DEBUG LarkCardPatchNotifier.runLarkCli] op=${op} CLOSE code=${code} stdoutLen=${stdout.length} stderrLen=${stderr.length}`);
+        }
+        if (code === 0) {
+          resolve(stdout);
+        } else {
+          reject(new Error(`lark-cli ${op} exited with code ${code}: ${sanitize(stderr || stdout)}`));
+        }
+      });
+      proc.on("error", (error) => {
+        reject(error);
+      });
+    });
+  }
+  extractMessageId(stdout) {
+    try {
+      const obj = JSON.parse(stdout);
+      const data = obj?.data ?? obj;
+      const id = data?.message_id ?? data?.messageId ?? obj?.message_id ?? obj?.messageId;
+      return typeof id === "string" ? id : undefined;
+    } catch {
+      return;
+    }
+  }
+}
+__legacyDecorateClassTS([
+  TracedAs("lark-card.startTask", {
+    recordParams: true,
+    recordResult: true,
+    flattenParamFilter: true,
+    paramFilter: (args) => ({
+      chatId: args[0]?.chatId,
+      profile: args[0]?.profile,
+      taskId: args[0]?.taskId
+    }),
+    resultFilter: (r) => ({
+      messageId: r?.messageId,
+      pinned: r?.pinned
+    })
+  })
+], LarkCardPatchNotifier.prototype, "startTask", null);
+__legacyDecorateClassTS([
+  TracedAs("lark-card.updateTask", {
+    recordParams: true,
+    recordResult: false,
+    flattenParamFilter: true,
+    paramFilter: (args) => ({
+      messageId: args[0]?.messageId,
+      profile: args[0]?.profile,
+      status: args[0]?.status,
+      taskId: args[0]?.taskId,
+      progress: args[0]?.progress,
+      newMilestones: args[0]?.milestones?.length ?? 0,
+      newProcessSteps: args[0]?.processSteps?.length ?? 0
+    })
+  })
+], LarkCardPatchNotifier.prototype, "updateTask", null);
+__legacyDecorateClassTS([
+  TracedAs("lark-card.finishTask", {
+    recordParams: true,
+    recordResult: false,
+    flattenParamFilter: true,
+    paramFilter: (args) => ({
+      messageId: args[0]?.messageId,
+      profile: args[0]?.profile,
+      status: args[0]?.status,
+      taskId: args[0]?.taskId
+    })
+  })
+], LarkCardPatchNotifier.prototype, "finishTask", null);
+__legacyDecorateClassTS([
+  TracedAs("lark-card.startWorkflow", {
+    recordParams: true,
+    recordResult: true,
+    flattenParamFilter: true,
+    paramFilter: (args) => ({
+      chatId: args[0]?.chatId,
+      profile: args[0]?.profile,
+      runId: args[0]?.meta?.runId,
+      totalNodes: args[0]?.totalNodes
+    }),
+    resultFilter: (r) => ({
+      messageId: r?.messageId,
+      pinned: r?.pinned
+    })
+  })
+], LarkCardPatchNotifier.prototype, "startWorkflow", null);
+__legacyDecorateClassTS([
+  TracedAs("lark-card.updateWorkflow", {
+    recordParams: true,
+    recordResult: false,
+    flattenParamFilter: true,
+    paramFilter: (args) => ({
+      messageId: args[0]?.messageId,
+      profile: args[0]?.profile,
+      status: args[0]?.status,
+      currentNode: args[0]?.currentNode,
+      completedNodes: args[0]?.completedNodes,
+      totalNodes: args[0]?.totalNodes,
+      newMilestones: args[0]?.milestones?.length ?? 0,
+      newProcessSteps: args[0]?.processSteps?.length ?? 0
+    })
+  })
+], LarkCardPatchNotifier.prototype, "updateWorkflow", null);
+__legacyDecorateClassTS([
+  TracedAs("lark-card.finishWorkflow", {
+    recordParams: true,
+    recordResult: false,
+    flattenParamFilter: true,
+    paramFilter: (args) => ({
+      messageId: args[0]?.messageId,
+      profile: args[0]?.profile,
+      status: args[0]?.status,
+      runId: args[0]?.meta?.runId
+    })
+  })
+], LarkCardPatchNotifier.prototype, "finishWorkflow", null);
+__legacyDecorateClassTS([
+  TracedAs("lark-card.runLarkCli", {
+    recordParams: true,
+    recordResult: true,
+    flattenParamFilter: true,
+    paramFilter: (args) => {
+      const argv = args[0] ?? [];
+      const op = args[1] ?? "unknown";
+      return {
+        op,
+        argv: argv.join(" ").slice(0, 300),
+        hasProfile: argv.includes("--profile"),
+        msgType: valueAfter(argv, "--msg-type"),
+        contentLength: (valueAfter(argv, "--content") ?? "").length,
+        dataLength: (valueAfter(argv, "--data") ?? "").length
+      };
+    },
+    resultFilter: (r) => ({
+      stdoutLength: (r ?? "").length
+    })
+  })
+], LarkCardPatchNotifier.prototype, "runLarkCli", null);
+function mergeTaskMeta(base, incoming) {
+  const merged = { ...base ?? {} };
+  if (!incoming)
+    return merged;
+  for (const [k, v] of Object.entries(incoming)) {
+    if (v === undefined || v === null || v === "")
+      continue;
+    merged[k] = v;
+  }
+  return merged;
+}
+function mergeWorkflowMeta(base, incoming) {
+  const merged = { runId: base?.runId ?? incoming?.runId ?? "" };
+  const assign = (src) => {
+    if (!src)
+      return;
+    for (const [k, v] of Object.entries(src)) {
+      if (v === undefined || v === null || v === "")
+        continue;
+      merged[k] = v;
+    }
+  };
+  assign(base);
+  assign(incoming);
+  return merged;
+}
+function mergeUnique(base, incoming, keyOf) {
+  const seen = new Set(base.map(keyOf));
+  const merged = [...base];
+  for (const item of incoming) {
+    const k = keyOf(item);
+    if (seen.has(k))
+      continue;
+    seen.add(k);
+    merged.push(item);
+  }
+  return merged;
+}
+function spinnerIndexFor(updateCount) {
+  return updateCount % SPINNER_EMOJIS.length;
+}
+function valueAfter(argv, flag) {
+  const idx = argv.indexOf(flag);
+  if (idx < 0 || idx + 1 >= argv.length)
+    return;
+  return argv[idx + 1];
+}
+function sanitize(text) {
+  const trimmed = text.trim();
+  if (trimmed.length <= 500)
+    return trimmed;
+  return `${trimmed.slice(0, 500)}…`;
+}
+
+export { humanizeValue, formatDurationMs, LarkCardPatchNotifier };