chatccc 0.2.5 → 0.2.7

package/src/cards.ts

@@ -114,10 +114,12 @@ export function buildHelpCard(userText: string): string {
     header: { template: "blue", title: { content: "ChatCCC", tag: "plain_text" } },
     elements: [
       { tag: "div", text: { tag: "lark_md", content: `你发送了: ${userText}` } },
+      { tag: "div", text: { tag: "lark_md", content: "使用 **/new**（默认 Claude Code）或 **/new claude** / **/new cursor** 创建新会话" } },
       buildButtons([
-        { text: "新建会话（/new）", value: JSON.stringify({ cmd: "new" }), type: "primary" },
-        { text: "重启Chat CCC（/restart）", value: JSON.stringify({ cmd: "restart" }), type: "danger" },
-        { text: "查看/切换工作路径（/cd）", value: JSON.stringify({ cmd: "cd" }), type: "default" },
+        { text: "新建 Claude Code 会话（/new claude）", value: JSON.stringify({ cmd: "new" }), type: "primary" },
+        { text: "新建 Cursor 会话（/new cursor）", value: JSON.stringify({ cmd: "new cursor" }), type: "primary" },
+        { text: "重启 ChatCCC（/restart）", value: JSON.stringify({ cmd: "restart" }), type: "danger" },
+        { text: "切换工作路径（/cd）", value: JSON.stringify({ cmd: "cd" }), type: "default" },
       ]),
     ],
   });
@@ -159,37 +161,146 @@ export function buildCdContent(
   return lines.join("\n");
 }
 
-// 所有会话列表卡片
+// 工作路径卡片（/cd 无参数时使用，含最近使用路径按钮）
+//
+// 必须使用 v1 卡片格式（无 schema 字段、elements 放顶层）。原因：
+// 此卡片通过 `/im/v1/messages?msg_type=interactive` 端点直接发出，content
+// 字段就是卡片 JSON。该端点不接受 schema 2.0 的原始 JSON 作为 content
+// （schema 2.0 卡片必须先通过 CardKit /cardkit/v1/cards 创建得到 card_id，
+// 再以 `{type:"card", data:{card_id}}` 包装发出，参见 sendCardKitMessage）。
+// 之前用过 schema 2.0 + body.elements 的结构，飞书会静默拒绝该消息，
+// 导致 /cd 无任何回复——故此处与 buildSessionsCard/buildStatusCard 保持
+// 同一 v1 结构。
+export function buildCdCard(
+  dirPath: string,
+  entries: { name: string; isDir: boolean }[],
+  recentDirs: string[],
+  sessionCwd?: string,
+  maxFiles = 100,
+): string {
+  const display = entries.slice(0, maxFiles);
+  const overflow = entries.length > maxFiles ? `\n...（共 ${entries.length} 个条目，仅显示前 ${maxFiles} 个）` : "";
+  const listing = display.map(e => e.isDir ? `📁 ${e.name}/` : `📄 ${e.name}`).join("\n");
+
+  const elements: object[] = [];
+
+  if (sessionCwd) {
+    elements.push({
+      tag: "div",
+      text: { tag: "lark_md", content: `**当前会话工作路径:** \`${sessionCwd}\`` },
+    });
+  }
+  elements.push({
+    tag: "div",
+    text: { tag: "lark_md", content: `**新会话默认工作路径:** \`${dirPath}\`` },
+  });
+
+  if (recentDirs.length > 0) {
+    elements.push({ tag: "hr" });
+    elements.push({
+      tag: "div",
+      text: { tag: "lark_md", content: "**最近使用过的路径（点击切换）:**" },
+    });
+    elements.push({
+      tag: "action",
+      actions: recentDirs.map(d => {
+        const label = d.length > 36 ? `...${d.slice(-33)}` : d;
+        return {
+          tag: "button",
+          text: { tag: "plain_text", content: label },
+          type: "default",
+          value: { action: "cd", path: d },
+        };
+      }),
+    });
+  }
+
+  elements.push({ tag: "hr" });
+  elements.push({
+    tag: "div",
+    text: {
+      tag: "lark_md",
+      content: [
+        `**目录内容** (最多 ${maxFiles} 个):`,
+        listing,
+        overflow,
+      ].join("\n"),
+    },
+  });
+
+  return JSON.stringify({
+    config: { wide_screen_mode: true },
+    header: {
+      template: "blue",
+      title: { tag: "plain_text", content: "工作路径" },
+    },
+    elements,
+  });
+}
+
+// 所有会话列表卡片（Claude Code 优先，然后 Cursor）
 export function buildSessionsCard(sessions: Array<{
   sessionId: string;
   active: boolean;
   turnCount: number;
   elapsedSeconds: number | null;
   model: string;
+  tool: string;
 }>): string {
-  const text = sessions.length === 0
-    ? "当前没有会话记录。"
-    : [
-        `共 **${sessions.length}** 个会话:`,
-        ``,
-        ...sessions.map((s, i) => {
-          const status = s.active ? "🟢 活跃" : "⚪ 空闲";
-          const shortId = s.sessionId.length > 16 ? s.sessionId.slice(0, 16) + "..." : s.sessionId;
-          let extra = "";
-          if (s.active && s.elapsedSeconds !== null) {
-            const mins = Math.floor(s.elapsedSeconds / 60);
-            const secs = s.elapsedSeconds % 60;
-            extra = ` | 本轮: ${mins}分${secs}秒`;
-          }
-          return `**${i + 1}.** \`${shortId}\` ${status} | 轮数: ${s.turnCount} | ${s.model}${extra}`;
-        }),
-      ].join("\n");
+  // 按 tool 分组排序：Claude Code 在前，Cursor 在后
+  const claudeCodeSessions = sessions.filter(s => s.tool !== "cursor");
+  const cursorSessions = sessions.filter(s => s.tool === "cursor");
+  const hasClaudeCode = claudeCodeSessions.length > 0;
+  const hasCursor = cursorSessions.length > 0;
+
+  if (sessions.length === 0) {
+    return JSON.stringify({
+      config: { wide_screen_mode: true },
+      header: { template: "blue", title: { content: "所有会话", tag: "plain_text" } },
+      elements: [
+        { tag: "div", text: { tag: "lark_md", content: "当前没有会话记录。\n\n使用 **/new**（默认 Claude Code）、**/new claude** 或 **/new cursor** 创建新会话。" } },
+        { tag: "hr" },
+        { tag: "action", actions: [{ tag: "button", text: { tag: "plain_text", content: "收起" }, type: "default", value: { action: "close" } }] },
+      ],
+    });
+  }
+
+  const formatSession = (s: typeof sessions[0], i: number) => {
+    const status = s.active ? "🟢 活跃" : "⚪ 空闲";
+    const shortId = s.sessionId.length > 16 ? s.sessionId.slice(0, 16) + "..." : s.sessionId;
+    let extra = "";
+    if (s.active && s.elapsedSeconds !== null) {
+      const mins = Math.floor(s.elapsedSeconds / 60);
+      const secs = s.elapsedSeconds % 60;
+      extra = ` | 本轮: ${mins}分${secs}秒`;
+    }
+    const toolLabel = s.tool === "cursor" ? "Cursor" : "Claude Code";
+    return `**${i + 1}.** \`${shortId}\` ${status} | 工具: ${toolLabel} | 轮数: ${s.turnCount} | ${s.model}${extra}`;
+  };
+
+  const lines: string[] = [`共 **${sessions.length}** 个会话:`, ""];
+  let idx = 0;
+
+  if (hasClaudeCode) {
+    lines.push("**Claude Code 会话:**", "");
+    for (const s of claudeCodeSessions) {
+      lines.push(formatSession(s, idx++));
+    }
+  }
+
+  if (hasCursor) {
+    if (hasClaudeCode) lines.push("", "**Cursor 会话:**", "");
+    else lines.push("**Cursor 会话:**", "");
+    for (const s of cursorSessions) {
+      lines.push(formatSession(s, idx++));
+    }
+  }
 
   return JSON.stringify({
     config: { wide_screen_mode: true },
     header: { template: "blue", title: { content: "所有会话", tag: "plain_text" } },
     elements: [
-      { tag: "div", text: { tag: "lark_md", content: text } },
+      { tag: "div", text: { tag: "lark_md", content: lines.join("\n") } },
       { tag: "hr" },
       {
         tag: "action",

package/src/config.ts

@@ -62,13 +62,122 @@ export const CLAUDE_MODEL = process.env.CHATCCC_ANTHROPIC_MODEL?.trim() || "defa
 
 export const CLAUDE_EFFORT = process.env.CHATCCC_ANTHROPIC_EFFORT?.trim() || "default";
 
-/** AI 工具选择：claude | cursor | codex（未设置时默认 claude） */
-export const AI_TOOL = process.env.CHATCCC_AI_TOOL?.trim().toLowerCase() || "claude";
+// ---------------------------------------------------------------------------
+// /git 超时配置（CHATCCC_GIT_TIMEOUT_SECONDS）
+// ---------------------------------------------------------------------------
+
+/** /git 命令默认超时秒数（用户未配置时使用） */
+export const DEFAULT_GIT_TIMEOUT_SECONDS = 180;
+/** /git 超时允许的下限/上限（防止 0、负数、过大值导致行为异常） */
+export const MIN_GIT_TIMEOUT_SECONDS = 1;
+export const MAX_GIT_TIMEOUT_SECONDS = 3600; // 1 小时
+
+export interface ParsedGitTimeout {
+  /** 实际使用的超时秒数（无效时回退为 default） */
+  seconds: number;
+  /** 用户提供的原始字符串是否为合法整数秒（true 表示采纳了用户值或未提供） */
+  valid: boolean;
+  /** 用户原始输入；未设置时为 undefined */
+  raw?: string;
+  /** 是否使用了内置默认值（即用户未提供有效值） */
+  usingDefault: boolean;
+}
+
+/**
+ * 解析 CHATCCC_GIT_TIMEOUT_SECONDS 字符串为有效秒数。
+ * - 未设置 / 空 → 使用默认值，valid=true、usingDefault=true
+ * - 有效整数且在 [MIN, MAX] 区间 → 使用用户值，valid=true、usingDefault=false
+ * - 非整数 / 越界 / NaN → 使用默认值，valid=false、usingDefault=true（同时保留原始字符串供报错）
+ */
+export function parseGitTimeoutSeconds(
+  raw: string | undefined,
+  defaultSeconds = DEFAULT_GIT_TIMEOUT_SECONDS,
+): ParsedGitTimeout {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return { seconds: defaultSeconds, valid: true, usingDefault: true };
+  }
+  const n = Number(trimmed);
+  if (
+    !Number.isFinite(n) ||
+    !Number.isInteger(n) ||
+    n < MIN_GIT_TIMEOUT_SECONDS ||
+    n > MAX_GIT_TIMEOUT_SECONDS
+  ) {
+    return { seconds: defaultSeconds, valid: false, raw: trimmed, usingDefault: true };
+  }
+  return { seconds: n, valid: true, raw: trimmed, usingDefault: false };
+}
+
+const gitTimeoutParsed = parseGitTimeoutSeconds(process.env.CHATCCC_GIT_TIMEOUT_SECONDS);
+/** /git 命令实际使用的超时秒数 */
+export const GIT_TIMEOUT_SECONDS = gitTimeoutParsed.seconds;
+/** /git 命令实际使用的超时毫秒数（runGitCommand 直接使用） */
+export const GIT_TIMEOUT_MS = GIT_TIMEOUT_SECONDS * 1000;
+
+/** 探测 cursor-agent 安装路径（优先环境变量，其次 LocalAppData，最后默认 agent） */
+function detectCursorAgent(): string {
+  if (process.env.CHATCCC_CURSOR_COMMAND?.trim()) return process.env.CHATCCC_CURSOR_COMMAND.trim();
+  const localAppData = process.env.LOCALAPPDATA;
+  if (localAppData) {
+    const defaultPath = join(localAppData, "cursor-agent", "agent.cmd");
+    if (existsSync(defaultPath)) return defaultPath;
+  }
+  return "agent";
+}
+export const CURSOR_AGENT_COMMAND = detectCursorAgent();
+
+function resolveCursorAgentArgs(): string[] {
+  const custom = process.env.CHATCCC_CURSOR_ARGS?.trim();
+  if (custom) return custom.split(/\s+/).filter(Boolean);
+
+  let args = "-p --force --output-format stream-json --stream-partial-output";
+  const model = process.env.CHATCCC_CURSOR_MODEL?.trim();
+  if (model && model !== "default") {
+    args += ` --model ${model}`;
+  }
+  return args.split(/\s+/).filter(Boolean);
+}
+
+/** Cursor agent 参数：-p 非交互模式，--force 强制允许命令（yolo），stream-json 流式 JSONL 输出 */
+export const CURSOR_AGENT_ARGS = resolveCursorAgentArgs();
 
 // 新建会话的默认工作路径（/cd 命令设置，持久化到本地文件）
-// 该路径仅影响通过 /new 新建的 Claude 会话，不影响已有会话的 resume。
+// 该路径仅影响通过 /new 新建的会话，不影响已有会话的 resume。
 export const DEFAULT_CWD_FILE = join(PROJECT_ROOT, ".claude", "working_dir.txt");
 
+/** 会话工具类型持久化文件 */
+export const SESSIONS_FILE = join(PROJECT_ROOT, ".claude", "sessions.json");
+
+/** 最近成功新建会话的工作路径记录（最多 10 条） */
+export const RECENT_DIRS_FILE = join(PROJECT_ROOT, ".claude", "recent_dirs.json");
+export const MAX_RECENT_DIRS = 10;
+
+/** 读取最近使用过的工作路径列表（最新的在前） */
+export async function getRecentDirs(): Promise<string[]> {
+  try {
+    const raw = await readFile(RECENT_DIRS_FILE, "utf-8");
+    const arr = JSON.parse(raw);
+    if (Array.isArray(arr)) return arr.filter((d: unknown) => typeof d === "string");
+  } catch { /* file doesn't exist or corrupted */ }
+  return [];
+}
+
+/** 添加一个路径到最近使用列表（去重、限制数量、最新的在前） */
+export async function addRecentDir(dir: string): Promise<void> {
+  const dirs = await getRecentDirs();
+  const filtered = dirs.filter(d => d !== dir);
+  filtered.unshift(dir);
+  const trimmed = filtered.slice(0, MAX_RECENT_DIRS);
+  try {
+    await mkdir(dirname(RECENT_DIRS_FILE), { recursive: true });
+    await writeFile(RECENT_DIRS_FILE, JSON.stringify(trimmed, null, 2), "utf-8");
+  } catch (err) {
+    console.error(`[${ts()}] Failed to save recent_dirs.json: ${(err as Error).message}`);
+    fileLog.flush();
+  }
+}
+
 /** 读取 /cd 设置的默认工作路径。若文件不存在或路径已失效，回退到用户主目录。 */
 export async function getDefaultCwd(): Promise<string> {
   try {
@@ -184,6 +293,30 @@ export function reportEnvironmentVariableReadout(): void {
     );
   }
 
+  const rawGitTimeout = process.env.CHATCCC_GIT_TIMEOUT_SECONDS?.trim();
+  if (!rawGitTimeout) {
+    console.log(`  [默认] [可选] CHATCCC_GIT_TIMEOUT_SECONDS`);
+    console.log(
+      `         /git 命令超时: 未设置 → 使用内置默认 ${DEFAULT_GIT_TIMEOUT_SECONDS}s`
+    );
+  } else if (!gitTimeoutParsed.valid) {
+    row(
+      "/git 命令超时",
+      "CHATCCC_GIT_TIMEOUT_SECONDS",
+      "可选",
+      false,
+      `值无效 "${rawGitTimeout}"，需为 ${MIN_GIT_TIMEOUT_SECONDS}–${MAX_GIT_TIMEOUT_SECONDS} 的整数秒；已回退为默认 ${DEFAULT_GIT_TIMEOUT_SECONDS}s`,
+    );
+  } else {
+    row(
+      "/git 命令超时",
+      "CHATCCC_GIT_TIMEOUT_SECONDS",
+      "可选",
+      true,
+      `已读入 → ${GIT_TIMEOUT_SECONDS}s`,
+    );
+  }
+
   console.log("  ------------------------------------------------------------------");
 }
 
@@ -227,4 +360,19 @@ export function explainMissingFeishuCredentialsAndExit(): never {
   process.exit(1);
 }
 
-export let SESSION_DESC_PREFIX: string = "Claude Session:";
+/** 群描述中用于识别 Claude Code 会话的前缀 */
+export const CLAUDE_SESSION_PREFIX = "Claude Code Session:";
+/** 群描述中用于识别 Cursor 会话的前缀 */
+export const CURSOR_SESSION_PREFIX = "Cursor Session:";
+
+/** 根据 tool 名称返回对应的群描述前缀 */
+export function sessionPrefixForTool(tool: string): string {
+  if (tool === "cursor") return CURSOR_SESSION_PREFIX;
+  return CLAUDE_SESSION_PREFIX;
+}
+
+/** 根据 tool 名称返回用于状态展示的标签 */
+export function toolDisplayName(tool: string): string {
+  if (tool === "cursor") return "Cursor";
+  return "Claude Code";
+}

package/src/feishu-api.ts

@@ -7,7 +7,8 @@ import {
   BASE_URL,
   CHAT_LOGS_DIR,
   PROJECT_ROOT,
-  SESSION_DESC_PREFIX,
+  CLAUDE_SESSION_PREFIX,
+  CURSOR_SESSION_PREFIX,
   ts,
 } from "./config.ts";
 import { buildButtons } from "./cards.ts";
@@ -219,12 +220,24 @@ export async function getChatInfo(
   };
 }
 
+export function extractSessionInfo(description: string): { sessionId: string; tool: string } | null {
+  const PREFIXES: Array<{ prefix: string; tool: string }> = [
+    { prefix: CLAUDE_SESSION_PREFIX, tool: "claude" },
+    { prefix: CURSOR_SESSION_PREFIX, tool: "cursor" },
+  ];
+  for (const { prefix, tool } of PREFIXES) {
+    const idx = description.indexOf(prefix);
+    if (idx === -1) continue;
+    const after = description.slice(idx + prefix.length).trim();
+    const match = after.match(/^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+    if (match) return { sessionId: match[1], tool };
+  }
+  return null;
+}
+
+/** @deprecated 使用 extractSessionInfo 代替 */
 export function extractSessionId(description: string): string | null {
-  const idx = description.indexOf(SESSION_DESC_PREFIX);
-  if (idx === -1) return null;
-  const after = description.slice(idx + SESSION_DESC_PREFIX.length).trim();
-  const match = after.match(/^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
-  return match ? match[1] : null;
+  return extractSessionInfo(description)?.sessionId ?? null;
 }
 
 // ---------------------------------------------------------------------------
@@ -325,11 +338,12 @@ export async function sendRestartCard(token: string): Promise<void> {
       config: { wide_screen_mode: true },
       header: { template: "green", title: { content: "ChatCCC Started", tag: "plain_text" } },
       elements: [
-        { tag: "div", text: { tag: "lark_md", content: "Bot 已启动完成，可以继续使用。\n\n发送 **/new** 创建新会话，或直接在已有会话群中发消息。" } },
+        { tag: "div", text: { tag: "lark_md", content: "Bot 已启动完成，可以继续使用。\n\n使用 **/new**（默认 Claude Code）或 **/new claude** / **/new cursor** 创建新会话" } },
         buildButtons([
-          { text: "新建会话（/new）", value: JSON.stringify({ cmd: "new" }), type: "primary" },
+          { text: "新建 Claude Code 会话（/new claude）", value: JSON.stringify({ cmd: "new" }), type: "primary" },
+          { text: "新建 Cursor 会话（/new cursor）", value: JSON.stringify({ cmd: "new cursor" }), type: "primary" },
           { text: "重启Chat CCC（/restart）", value: JSON.stringify({ cmd: "restart" }), type: "danger" },
-          { text: "查看/切换工作路径（/cd）", value: JSON.stringify({ cmd: "cd" }), type: "default" },
+          { text: "切换工作路径（/cd）", value: JSON.stringify({ cmd: "cd" }), type: "default" },
         ]),
       ],
     });

package/src/git-command.ts

@@ -0,0 +1,202 @@
+// =============================================================================
+// git-command.ts — /git 命令的执行与结果格式化
+// =============================================================================
+// 解析自 /git 后的原始字符串作为 shell 参数，在指定 cwd 下通过 shell 调起
+// `git ...`，收集 stdout/stderr 与退出码。带超时（kill）与逐路输出字节上限
+// （超过即截断），避免长输出撑爆内存或刷屏。
+//
+// 抽成独立模块是为了便于在不依赖飞书 SDK / 网络的前提下跑单元测试。
+// =============================================================================
+
+import { spawn } from "node:child_process";
+
+import { truncateContent } from "./cards.ts";
+
+// ---------------------------------------------------------------------------
+// 类型
+// ---------------------------------------------------------------------------
+
+export interface GitCommandResult {
+  /** 进程退出码；spawn 失败或被 kill 时为 null */
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  /** 任意一路输出超过 maxBytes 上限，已被截断 */
+  truncated: boolean;
+  /** 命令超过 timeoutMs 被强制终止 */
+  timedOut: boolean;
+  /** spawn 自身错误（如 git 不在 PATH）；正常退出（含非 0）时为 undefined */
+  spawnError?: string;
+}
+
+export interface RunGitOptions {
+  /** 命令最大允许执行毫秒数；超过则 SIGKILL，默认 60_000 */
+  timeoutMs?: number;
+  /** stdout 与 stderr 各自最多采集多少字节；默认 64 KiB */
+  maxBytes?: number;
+  /** 注入测试桩用：自定义 spawn 函数；默认使用 node:child_process 的 spawn */
+  spawnImpl?: typeof spawn;
+}
+
+// ---------------------------------------------------------------------------
+// runGitCommand —— 在 cwd 下执行 `git <args>`
+// ---------------------------------------------------------------------------
+
+/**
+ * 在 `cwd` 目录下执行 `git <args>`。
+ * - 通过 shell 执行（`shell: true`），允许用户使用引号、管道等 shell 语法
+ * - stdout/stderr 各自最多采集 `maxBytes` 字节，超过则置 truncated=true 并丢弃后续片段
+ * - 超时则 SIGKILL 并置 timedOut=true，仍返回已收集的部分输出
+ *
+ * 注意：本函数 **不会抛错**——任何失败都通过返回值传递（退出码、spawnError 等），
+ * 调用方需通过 exitCode/spawnError/timedOut/truncated 判断结果。
+ */
+export function runGitCommand(
+  args: string,
+  cwd: string,
+  opts: RunGitOptions = {},
+): Promise<GitCommandResult> {
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const maxBytes = opts.maxBytes ?? 64 * 1024;
+  const spawnImpl = opts.spawnImpl ?? spawn;
+  const startTime = Date.now();
+
+  return new Promise<GitCommandResult>((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawnImpl(`git ${args}`, {
+        cwd,
+        shell: true,
+        windowsHide: true,
+      });
+    } catch (err) {
+      resolve({
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        durationMs: Date.now() - startTime,
+        truncated: false,
+        timedOut: false,
+        spawnError: err instanceof Error ? err.message : String(err),
+      });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let truncated = false;
+    let timedOut = false;
+    let spawnError: string | undefined;
+
+    const collect = (chunk: Buffer, current: { bytes: number; text: string }): void => {
+      const room = maxBytes - current.bytes;
+      if (room <= 0) {
+        truncated = true;
+        return;
+      }
+      const slice = chunk.length <= room ? chunk : chunk.subarray(0, room);
+      current.text += slice.toString("utf-8");
+      current.bytes += slice.length;
+      if (chunk.length > room) truncated = true;
+    };
+
+    const stdoutState = { bytes: 0, text: "" };
+    const stderrState = { bytes: 0, text: "" };
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      collect(chunk, stdoutState);
+      stdout = stdoutState.text;
+      stdoutBytes = stdoutState.bytes;
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      collect(chunk, stderrState);
+      stderr = stderrState.text;
+      stderrBytes = stderrState.bytes;
+    });
+
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // ignore: 进程可能已退出
+      }
+    }, timeoutMs);
+
+    child.on("error", (err: Error) => {
+      spawnError = err.message;
+    });
+
+    child.on("close", (code: number | null) => {
+      clearTimeout(killTimer);
+      // 仅引用未直接使用的字节计数变量以避免编译告警
+      void stdoutBytes; void stderrBytes;
+      resolve({
+        exitCode: code,
+        stdout,
+        stderr,
+        durationMs: Date.now() - startTime,
+        truncated,
+        timedOut,
+        spawnError,
+      });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// formatGitResult —— 把执行结果渲染为飞书卡片用的 markdown
+// ---------------------------------------------------------------------------
+
+/**
+ * 渲染 `/git` 执行结果为发送给用户的 markdown 字符串。
+ * stdout/stderr 单路各最多保留 `maxLines` 行 / `maxChars` 字符（沿用 truncateContent），
+ * 命令本身的截断状态（truncated/timedOut/spawnError）也会在头部说明。
+ */
+export function formatGitResult(
+  args: string,
+  cwd: string,
+  result: GitCommandResult,
+  opts: { maxLines?: number; maxChars?: number } = {},
+): string {
+  const maxLines = opts.maxLines ?? 50;
+  const maxChars = opts.maxChars ?? 6000;
+  const sec = (result.durationMs / 1000).toFixed(2);
+  const lines: string[] = [];
+
+  lines.push(`**\$ git ${args}**`);
+  lines.push(`工作目录: \`${cwd}\``);
+  const exitDisplay = result.exitCode === null ? "(无)" : String(result.exitCode);
+  lines.push(`退出码: \`${exitDisplay}\` | 用时: \`${sec}s\``);
+  if (result.timedOut) lines.push(`⏱️ 命令超时被强制终止`);
+  if (result.truncated) lines.push(`⚠️ 输出超出采集上限，已截断`);
+  if (result.spawnError) lines.push(`❌ 启动失败: ${result.spawnError}`);
+
+  const stdoutTrim = result.stdout.trim();
+  const stderrTrim = result.stderr.trim();
+
+  if (stdoutTrim) {
+    lines.push("", "**stdout:**", "```", truncateContent(stdoutTrim, maxLines, maxChars), "```");
+  }
+  if (stderrTrim) {
+    lines.push("", "**stderr:**", "```", truncateContent(stderrTrim, maxLines, maxChars), "```");
+  }
+  if (!stdoutTrim && !stderrTrim && !result.spawnError) {
+    lines.push("", "_(命令无输出)_");
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// 头部颜色：成功绿色，失败红色，超时黄色
+// ---------------------------------------------------------------------------
+
+export function gitResultHeaderTemplate(result: GitCommandResult): string {
+  if (result.timedOut || result.spawnError) return "yellow";
+  if (result.exitCode === 0) return "green";
+  return "red";
+}