chatccc 0.2.5 → 0.2.7

package/src/adapters/cursor-adapter.ts

@@ -0,0 +1,402 @@
+// =============================================================================
+// cursor-adapter.ts — Cursor Agent CLI 适配器
+// =============================================================================
+// 通过 agent -p --output-format stream-json 与 Cursor agent 交互。
+// 命令行可通过 CHATCCC_CURSOR_COMMAND / CHATCCC_CURSOR_ARGS 环境变量自定义。
+// =============================================================================
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+
+import type {
+  ToolAdapter,
+  UnifiedBlock,
+  UnifiedStreamMessage,
+  CreateSessionResult,
+  SessionInfo,
+} from "./adapter-interface.ts";
+import { CURSOR_AGENT_COMMAND, CURSOR_AGENT_ARGS } from "../config.ts";
+import {
+  defaultCursorSessionMetaStore,
+  type CursorSessionMetaStore,
+} from "./cursor-session-meta-store.ts";
+
+// ---------------------------------------------------------------------------
+// 类型：Cursor JSONL 消息行
+// ---------------------------------------------------------------------------
+
+interface CursorMessageLine {
+  type?: string;
+  subtype?: string;
+  session_id?: string;
+  cwd?: string;
+  model?: string;
+  message?: {
+    role?: string;
+    content?: CursorContentBlock[];
+  };
+  result?: string;
+  duration_ms?: number;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+  };
+  /**
+   * 三类 assistant 事件的判定字段之一。详见 normalizeCursorMessage。
+   * 官方文档：cursor.com/docs/cli/reference/output-format
+   */
+  timestamp_ms?: number;
+  /**
+   * 三类 assistant 事件的判定字段之一：
+   *   - has timestamp_ms, no model_call_id  → Streaming delta（真增量）
+   *   - has timestamp_ms, has model_call_id → Buffered flush before tool call（重复快照）
+   *   - no  timestamp_ms                    → Final flush at end of turn（重复快照）
+   */
+  model_call_id?: string;
+  /** thinking delta 消息的文本内容 */
+  text?: string;
+  /** tool_call 消息的 call_id */
+  call_id?: string;
+  /** tool_call 消息的 tool_call 载荷 */
+  tool_call?: Record<string, unknown>;
+}
+
+interface CursorContentBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  input?: unknown;
+  tool_use_id?: string;
+  content?: unknown;
+  is_error?: boolean;
+  query?: string;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// normalizeCursorMessage — Cursor 消息 → UnifiedStreamMessage | null
+// ---------------------------------------------------------------------------
+
+/** Cursor tool_call 内部 key → 统一工具名 */
+function mapToolCallKey(key: string): string {
+  const KEY_MAP: Record<string, string> = {
+    globToolCall: "Glob",
+    shellToolCall: "Bash",
+    readToolCall: "Read",
+    writeToolCall: "Write",
+    editToolCall: "Edit",
+    grepToolCall: "Grep",
+    webSearchToolCall: "WebSearch",
+    webFetchToolCall: "WebFetch",
+    taskToolCall: "Agent",
+    notebookEditToolCall: "NotebookEdit",
+  };
+  return KEY_MAP[key] ?? key;
+}
+
+export function normalizeCursorMessage(
+  msg: CursorMessageLine,
+): UnifiedStreamMessage | null {
+  if (msg.type === "assistant" && msg.message?.content) {
+    // 按 cursor 官方 stream-json 规范区分三类 assistant 事件，避免 text 重复累加：
+    //   ┌────────────────┬───────────────┬─────────────────┐
+    //   │ 种类            │ timestamp_ms  │ model_call_id   │
+    //   ├────────────────┼───────────────┼─────────────────┤
+    //   │ Streaming delta│ 有             │ 无               │ → 唯一带新文本（text）
+    //   │ Buffered flush │ 有             │ 有               │ → 工具调用前完整快照（text_final）
+    //   │ Final flush    │ 无             │ 无               │ → 回合末完整快照（text_final）
+    //   └────────────────┴───────────────┴─────────────────┘
+    // 文档：cursor.com/docs/cli/reference/output-format
+    const isStreamingDelta =
+      msg.timestamp_ms !== undefined && msg.model_call_id === undefined;
+    const blocks: UnifiedBlock[] = [];
+    for (const block of msg.message.content) {
+      if (block.type === "thinking" && block.thinking) {
+        blocks.push({ type: "thinking", thinking: block.thinking });
+      } else if (block.type === "tool_use") {
+        blocks.push({
+          type: "tool_use",
+          name: block.name ?? "unknown",
+          input: block.input,
+        });
+      } else if (block.type === "tool_result") {
+        blocks.push({
+          type: "tool_result",
+          tool_use_id: block.tool_use_id ?? "",
+          content: block.content,
+          is_error: block.is_error,
+        });
+      } else if (block.type === "redacted_thinking") {
+        blocks.push({ type: "redacted_thinking" });
+      } else if (block.type === "search_result") {
+        blocks.push({
+          type: "search_result",
+          query: block.query ?? "",
+        });
+      } else if (block.type === "text" && block.text) {
+        blocks.push(
+          isStreamingDelta
+            ? { type: "text", text: block.text }
+            : { type: "text_final", text: block.text },
+        );
+      }
+    }
+    return { type: "assistant", blocks };
+  }
+
+  // Cursor agent 发出的独立 thinking delta 消息
+  if (msg.type === "thinking" && msg.subtype === "delta" && msg.text) {
+    return {
+      type: "assistant",
+      blocks: [{ type: "thinking", thinking: msg.text }],
+    };
+  }
+
+  // Cursor agent 发出的独立 tool_call 消息（tool_call.started / tool_call.completed）
+  if (msg.type === "tool_call" && msg.call_id && msg.tool_call) {
+    const toolKey = Object.keys(msg.tool_call)[0];
+    if (!toolKey) return null;
+    const toolData = msg.tool_call[toolKey] as {
+      args?: Record<string, unknown>;
+      result?: Record<string, unknown>;
+      description?: string;
+    } | undefined;
+    if (!toolData) return null;
+
+    if (msg.subtype === "started") {
+      return {
+        type: "assistant",
+        blocks: [
+          {
+            type: "tool_use",
+            name: mapToolCallKey(toolKey),
+            input: toolData.args ?? {},
+          },
+        ],
+      };
+    }
+
+    if (msg.subtype === "completed") {
+      const resultRaw = toolData.result as Record<string, unknown> | undefined;
+      const hasSuccess = resultRaw && "success" in resultRaw;
+      const hasError = resultRaw && "error" in resultRaw;
+      return {
+        type: "assistant",
+        blocks: [
+          {
+            type: "tool_result",
+            tool_use_id: msg.call_id,
+            content: hasSuccess
+              ? (resultRaw!.success as Record<string, unknown>)?.stdout ??
+                resultRaw!.success
+              : hasError
+                ? resultRaw!.error
+                : resultRaw ?? {},
+            is_error: hasError || undefined,
+          },
+        ],
+      };
+    }
+
+    return null;
+  }
+
+  if (msg.type === "user" && msg.message?.content) {
+    // Cursor resume 模式会先 echo 一条用户输入消息（text 块就是用户原始输入），
+    // 不应混入 assistant 输出累加。这里只保留 tool_result（工具调用反馈）。
+    const blocks: UnifiedBlock[] = [];
+    for (const block of msg.message.content) {
+      if (block.type === "tool_result") {
+        blocks.push({
+          type: "tool_result",
+          tool_use_id: block.tool_use_id ?? "",
+          content: block.content,
+          is_error: block.is_error,
+        });
+      }
+    }
+    return { type: "user", blocks };
+  }
+
+  // result 消息：cursor 官方推荐的"权威最终文本"来源（流末发出，含完整一段文字）。
+  // 提取为 assistant 的 text_final 块，由 session.ts 累积到 finalCompleteText。
+  if (msg.type === "result" && typeof msg.result === "string" && msg.result.length > 0) {
+    return {
+      type: "assistant",
+      blocks: [{ type: "text_final", text: msg.result }],
+    };
+  }
+
+  if (msg.type === "system" && msg.subtype === "compact_boundary") {
+    const meta = (msg as Record<string, unknown>).compact_metadata as
+      | { trigger?: "manual" | "auto"; pre_tokens?: number; post_tokens?: number }
+      | undefined;
+    if (!meta) return null;
+    return {
+      type: "system",
+      blocks: [
+        {
+          type: "compact_boundary",
+          trigger: meta.trigger ?? "auto",
+          pre_tokens: meta.pre_tokens ?? 0,
+          post_tokens: meta.post_tokens,
+        },
+      ],
+    };
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// 子进程辅助函数
+// ---------------------------------------------------------------------------
+
+function spawnAgent(
+  extraArgs: string[],
+  cwd?: string,
+  stdinText?: string,
+): ChildProcess {
+  const allArgs = [...CURSOR_AGENT_ARGS, ...extraArgs];
+  const proc = spawn(CURSOR_AGENT_COMMAND, allArgs, {
+    cwd,
+    stdio: [stdinText !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+    windowsHide: true,
+    shell: true,
+  });
+
+  // 收集 stderr，子进程异常退出时输出到日志，方便排查静默失败
+  let stderr = "";
+  proc.stderr!.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
+  proc.on("close", (code) => {
+    if (code !== 0 && stderr.trim()) {
+      console.error(`[Cursor stderr] exit=${code}: ${stderr.trim().slice(0, 2000)}`);
+    }
+  });
+
+  if (stdinText !== undefined) {
+    proc.stdin!.write(stdinText);
+    proc.stdin!.end();
+  }
+  return proc;
+}
+
+async function* readJsonLines(
+  proc: ChildProcess,
+  signal?: AbortSignal,
+): AsyncGenerator<CursorMessageLine> {
+  const rl = createInterface({ input: proc.stdout!, crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (signal?.aborted) break;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      yield JSON.parse(trimmed) as CursorMessageLine;
+    } catch { /* 非 JSON 行静默跳过 */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 适配器实现
+// ---------------------------------------------------------------------------
+
+class CursorAdapter implements ToolAdapter {
+  readonly displayName = "Cursor";
+  readonly sessionDescPrefix = "Cursor Session:";
+  private activeProcs = new Set<ChildProcess>();
+  private metaStore: CursorSessionMetaStore;
+
+  constructor(metaStore: CursorSessionMetaStore) {
+    this.metaStore = metaStore;
+  }
+
+  async createSession(cwd: string): Promise<CreateSessionResult> {
+    const proc = spawnAgent(["ok"], cwd);
+    this.activeProcs.add(proc);
+
+    for await (const msg of readJsonLines(proc)) {
+      if (msg.type === "system" && msg.subtype === "init" && msg.session_id) {
+        const sessionId = msg.session_id;
+        // 持久化 sessionId → { cwd, model }：getSessionInfo 后续依赖此映射，
+        // 否则 Cursor 会话上的 /git、/status、/sessions 等命令将无法显示
+        // 真实工作目录与真实模型。优先用 init 事件自报字段（cursor-agent
+        // 内部权威），cwd 没有时退回调用方传入的 cwd 兜底。
+        await this.metaStore
+          .set(sessionId, { cwd: msg.cwd ?? cwd, model: msg.model })
+          .catch(() => {});
+        this.activeProcs.delete(proc);
+        proc.kill();
+        return { sessionId };
+      }
+    }
+
+    proc.kill();
+    this.activeProcs.delete(proc);
+    throw new Error("No session ID in Cursor init event");
+  }
+
+  async *prompt(
+    sessionId: string,
+    userText: string,
+    cwd: string,
+    signal?: AbortSignal,
+  ): AsyncIterable<UnifiedStreamMessage> {
+    const proc = spawnAgent(["--resume", sessionId], cwd, userText);
+    this.activeProcs.add(proc);
+
+    try {
+      for await (const raw of readJsonLines(proc, signal)) {
+        if (signal?.aborted) break;
+        // 自动学习：resume 流首条 init 事件若带 cwd / model，更新映射。
+        // 这是为升级前创建的旧会话或映射文件意外丢失的情况兜底——
+        // 用户向旧会话发一次消息后，/git、/status 等即可正常显示。
+        // fire-and-forget：写失败不影响流式输出。
+        if (
+          raw.type === "system" &&
+          raw.subtype === "init" &&
+          raw.session_id &&
+          (raw.cwd || raw.model)
+        ) {
+          this.metaStore
+            .set(raw.session_id, { cwd: raw.cwd, model: raw.model })
+            .catch(() => {});
+        }
+        const normalized = normalizeCursorMessage(raw);
+        if (normalized) yield normalized;
+      }
+    } finally {
+      proc.kill();
+      this.activeProcs.delete(proc);
+    }
+  }
+
+  async getSessionInfo(
+    sessionId: string,
+  ): Promise<SessionInfo | undefined> {
+    const meta = await this.metaStore.get(sessionId);
+    if (!meta) return { sessionId };
+    return meta.model
+      ? { sessionId, cwd: meta.cwd, model: meta.model }
+      : { sessionId, cwd: meta.cwd };
+  }
+
+  async closeSession(_sessionId: string): Promise<void> {
+    // 子进程由 prompt 的 finally 自动 kill
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 工厂函数
+// ---------------------------------------------------------------------------
+
+export interface CreateCursorAdapterOptions {
+  /** 注入自定义 meta 持久化 store（测试用）；未提供时使用全局默认实例。 */
+  metaStore?: CursorSessionMetaStore;
+}
+
+export function createCursorAdapter(
+  options: CreateCursorAdapterOptions = {},
+): ToolAdapter {
+  return new CursorAdapter(options.metaStore ?? defaultCursorSessionMetaStore);
+}

package/src/adapters/cursor-session-meta-store.ts

@@ -0,0 +1,154 @@
+// =============================================================================
+// cursor-session-meta-store.ts — Cursor 会话 sessionId → meta 持久化映射
+// =============================================================================
+// 背景：Claude Adapter 通过 SDK 的 getSessionInfo 能拿到会话的真实 cwd（SDK
+// 内部已持久化）。Cursor CLI 没有等价机制，因此 ChatCCC 必须自己维护一份
+// sessionId → { cwd, model } 映射，否则：
+//   1. /git、/cd 等需要"会话真实工作目录"的命令将在 Cursor 会话上 100% 失败
+//   2. /status、/sessions 显示的"模型"只能硬塞 ChatCCC 的 ANTHROPIC 环境变量，
+//      与 Cursor 实际跑的 Composer 2 Fast 等真实模型无关
+//
+// 存储：
+//   文件 .claude/cursor-session-meta.json，结构：
+//     { "<sessionId>": { "cwd": "...", "model": "..." } }
+//
+// API 设计：
+//   set(sid, partial) → 部分合并写入；只更新非空字段，不会清空其他字段
+//   这样 createSession（拿到 cwd+model）与 prompt（resume 时再次学习）都用同一
+//   接口，但若某次 init 事件少了某字段也不会破坏已记录值。
+//
+// 鲁棒性：文件不存在/损坏/IO 失败一律视为空映射，仅打日志，不阻断主流程。
+// =============================================================================
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { PROJECT_ROOT } from "../config.ts";
+
+/** 持久化文件默认路径（生产）。测试可通过 createCursorSessionMetaStore(filePath) 注入。 */
+export const CURSOR_SESSION_META_FILE = join(
+  PROJECT_ROOT,
+  ".claude",
+  "cursor-session-meta.json",
+);
+
+/**
+ * 单条会话元数据。cwd 为必填（无 cwd 的记录视为不完整，get 返回 undefined）；
+ * model 可选（cursor agent init 事件理论上一定带，留可选是为防御性兜底）。
+ */
+export interface CursorSessionMeta {
+  cwd: string;
+  model?: string;
+}
+
+export interface CursorSessionMetaStore {
+  /** 查询某 sessionId 对应的元数据；未记录或 cwd 缺失返回 undefined。 */
+  get(sessionId: string): Promise<CursorSessionMeta | undefined>;
+  /**
+   * 部分合并写入：仅写入非 undefined / 非空字段；其他字段保持原值。
+   * - 第一次写入若不含 cwd，记录视为不完整，get 仍返回 undefined
+   * - 同 sessionId 重复写入完全相同值时跳过 IO（性能优化）
+   */
+  set(sessionId: string, partial: Partial<CursorSessionMeta>): Promise<void>;
+}
+
+interface RawEntry {
+  cwd?: string;
+  model?: string;
+}
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.length > 0;
+}
+
+/**
+ * 解析持久化文件中的单条记录，兼容历史 schema：
+ *   - 新版：{ cwd: string, model?: string }
+ *   - 历史 v1：纯字符串（直接是 cwd 值）—— 升级前旧数据兼容
+ * 非法形态返回 null。
+ */
+function parseEntry(raw: unknown): RawEntry | null {
+  if (typeof raw === "string" && raw.length > 0) {
+    return { cwd: raw };
+  }
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    const out: RawEntry = {};
+    if (isNonEmptyString(obj.cwd)) out.cwd = obj.cwd;
+    if (isNonEmptyString(obj.model)) out.model = obj.model;
+    return out;
+  }
+  return null;
+}
+
+/**
+ * 创建一个基于 JSON 文件的 store 实例。
+ *
+ * - 首次访问时懒加载文件到内存缓存；后续读全部走缓存
+ * - 写时先合并到缓存再落盘（写失败仅 console.error，不抛异常）
+ * - 同一 sessionId 重复 set 完全相同值时跳过 IO
+ */
+export function createCursorSessionMetaStore(
+  filePath: string = CURSOR_SESSION_META_FILE,
+): CursorSessionMetaStore {
+  let cache: Record<string, RawEntry> | null = null;
+
+  async function load(): Promise<Record<string, RawEntry>> {
+    if (cache) return cache;
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const out: Record<string, RawEntry> = {};
+        for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+          const entry = parseEntry(v);
+          if (entry) out[k] = entry;
+        }
+        cache = out;
+        return out;
+      }
+    } catch {
+      // 文件不存在 / JSON 损坏 / 读权限失败 → 视为空映射，不阻断主流程
+    }
+    cache = {};
+    return cache;
+  }
+
+  return {
+    async get(sessionId: string): Promise<CursorSessionMeta | undefined> {
+      const map = await load();
+      const entry = map[sessionId];
+      if (!entry || !isNonEmptyString(entry.cwd)) return undefined;
+      return entry.model
+        ? { cwd: entry.cwd, model: entry.model }
+        : { cwd: entry.cwd };
+    },
+
+    async set(
+      sessionId: string,
+      partial: Partial<CursorSessionMeta>,
+    ): Promise<void> {
+      const map = await load();
+      const existing = map[sessionId] ?? {};
+      const merged: RawEntry = { ...existing };
+      if (isNonEmptyString(partial.cwd)) merged.cwd = partial.cwd;
+      if (isNonEmptyString(partial.model)) merged.model = partial.model;
+
+      // 与原值完全相同时跳过 IO
+      if (existing.cwd === merged.cwd && existing.model === merged.model) return;
+
+      map[sessionId] = merged;
+      try {
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, JSON.stringify(map, null, 2), "utf-8");
+      } catch (err) {
+        console.error(
+          `[cursor-session-meta] failed to persist ${filePath}: ${(err as Error).message}`,
+        );
+      }
+    },
+  };
+}
+
+/** 生产环境共享的全局默认实例（指向 .claude/cursor-session-meta.json）。 */
+export const defaultCursorSessionMetaStore = createCursorSessionMetaStore();