@chenglu.she/sandy 1.0.0

package/src/cursor-agent.ts

@@ -0,0 +1,191 @@
+import { Agent, CursorAgentError, type SDKCustomTool } from "@cursor/sdk";
+import {
+  isAskQuestionToolName,
+  parseAskQuestionArgs,
+  type ParsedAskQuestion,
+} from "./ask-question.js";
+import { config, localAgentOptions } from "./config.js";
+import type { SessionStore } from "./session-store.js";
+
+export type AgentFinished = {
+  type: "finished";
+  text: string;
+  agentId: string;
+  runId?: string;
+  status: string;
+};
+
+export type AgentNeedsInput = {
+  type: "needs_input";
+  agentId: string;
+  runId?: string;
+  ask: ParsedAskQuestion;
+  partialText?: string;
+};
+
+export type AgentOutcome = AgentFinished | AgentNeedsInput;
+
+export type RunCursorAgentOptions = {
+  /** Per-turn Feishu tools (reply target changes each message). */
+  customTools?: Record<string, SDKCustomTool>;
+};
+
+const RESET_COMMANDS = new Set(["/new", "/reset", "重置", "新对话"]);
+
+export function isResetCommand(text: string): boolean {
+  return RESET_COMMANDS.has(text.trim().toLowerCase()) || RESET_COMMANDS.has(text.trim());
+}
+
+export async function runCursorAgent(
+  sessionStore: SessionStore,
+  sessionKey: string,
+  prompt: string,
+  options?: RunCursorAgentOptions,
+): Promise<AgentOutcome> {
+  const existing = sessionStore.get(sessionKey);
+  let agent;
+  const customTools = options?.customTools;
+
+  try {
+    if (existing?.agentId) {
+      agent = await Agent.resume(existing.agentId, {
+        apiKey: config.cursorApiKey,
+        model: { id: config.cursorModel },
+        name: config.agentName,
+        local: {
+          ...localAgentOptions(),
+          ...(customTools ? { customTools } : {}),
+        },
+      });
+      console.log(`[cursor] resumed agent=${existing.agentId} session=${sessionKey}`);
+    } else {
+      agent = await Agent.create({
+        apiKey: config.cursorApiKey,
+        model: { id: config.cursorModel },
+        name: config.agentName,
+        local: {
+          ...localAgentOptions(),
+          ...(customTools ? { customTools } : {}),
+        },
+      });
+      sessionStore.set(sessionKey, agent.agentId);
+      console.log(`[cursor] created agent=${agent.agentId} session=${sessionKey}`);
+    }
+
+    const run = await agent.send(
+      prompt,
+      customTools ? { local: { customTools } } : undefined,
+    );
+    console.log(`[cursor] run=${run.id} agent=${agent.agentId}`);
+
+    let partialText = "";
+    let pendingAsk: ParsedAskQuestion | undefined;
+    let sawAskQuestion = false;
+
+    for await (const event of run.stream()) {
+      if (event.type === "assistant") {
+        for (const block of event.message.content) {
+          if (block.type === "text" && block.text) {
+            partialText += block.text;
+          }
+          if (block.type === "tool_use" && isAskQuestionToolName(block.name)) {
+            const parsed = parseAskQuestionArgs(block.input);
+            if (parsed) {
+              pendingAsk = parsed;
+              sawAskQuestion = true;
+              console.log(
+                `[cursor] askQuestion via tool_use questions=${parsed.questions.length}`,
+              );
+            }
+          }
+        }
+      }
+
+      if (event.type === "tool_call" && isAskQuestionToolName(event.name)) {
+        const parsed = parseAskQuestionArgs(event.args);
+        if (parsed) {
+          pendingAsk = parsed;
+          sawAskQuestion = true;
+          console.log(
+            `[cursor] askQuestion tool_call status=${event.status} questions=${parsed.questions.length}`,
+          );
+        } else {
+          console.warn(
+            "[cursor] askQuestion tool_call with unparsable args:",
+            JSON.stringify(event.args)?.slice(0, 500),
+          );
+        }
+
+        // Plan A: stop this run and wait for Feishu selection as the next turn.
+        if (event.status === "running" && pendingAsk) {
+          if (run.supports("cancel")) {
+            await run.cancel();
+          }
+          break;
+        }
+      }
+
+      if (event.type === "request") {
+        console.log(`[cursor] request event request_id=${event.request_id}`);
+        // If we already parsed askQuestion args, cancel & hand off to Feishu.
+        if (pendingAsk && run.supports("cancel")) {
+          await run.cancel();
+          break;
+        }
+      }
+    }
+
+    if (sawAskQuestion && pendingAsk) {
+      // Ensure run settles if cancel didn't already.
+      try {
+        await run.wait();
+      } catch {
+        // cancelled runs may reject; ignore
+      }
+
+      return {
+        type: "needs_input",
+        agentId: agent.agentId,
+        runId: run.id,
+        ask: pendingAsk,
+        partialText: partialText.trim() || undefined,
+      };
+    }
+
+    const result = await run.wait();
+    const text =
+      typeof result.result === "string" && result.result.trim()
+        ? result.result.trim()
+        : partialText.trim()
+          ? partialText.trim()
+          : result.status === "finished"
+            ? "(agent 已完成，但没有返回文本)"
+            : `agent 运行状态: ${result.status}`;
+
+    return {
+      type: "finished",
+      text,
+      agentId: agent.agentId,
+      runId: run.id,
+      status: result.status,
+    };
+  } catch (err) {
+    if (err instanceof CursorAgentError) {
+      if (existing?.agentId) {
+        sessionStore.delete(sessionKey);
+      }
+      throw new Error(
+        `Cursor agent 启动失败: ${err.message} (retryable=${err.isRetryable})`,
+      );
+    }
+    throw err;
+  } finally {
+    if (agent) {
+      await agent[Symbol.asyncDispose]();
+    }
+  }
+}
+
+export function resetSession(sessionStore: SessionStore, sessionKey: string): void {
+  sessionStore.delete(sessionKey);
+}

package/src/feishu-docs.ts

@@ -0,0 +1,117 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+
+/** Extract docx document_id from a Feishu URL or bare id. */
+export function parseDocumentId(input: string): string {
+  const trimmed = input.trim();
+  const m = trimmed.match(/\/docx\/([A-Za-z0-9]+)/);
+  if (m?.[1]) return m[1];
+  if (/^[A-Za-z0-9_-]{10,}$/.test(trimmed)) return trimmed;
+  throw new Error(
+    `invalid document id/url: ${input} (expect …/docx/<id> or bare document_id)`,
+  );
+}
+
+export async function readDocumentText(
+  client: Lark.Client,
+  documentIdOrUrl: string,
+): Promise<string> {
+  const document_id = parseDocumentId(documentIdOrUrl);
+  const res = await client.docx.v1.document.rawContent({
+    path: { document_id },
+  });
+  if (res.code && res.code !== 0) {
+    throw new Error(`read doc failed: code=${res.code} msg=${res.msg}`);
+  }
+  return res.data?.content ?? "";
+}
+
+export async function createDocument(
+  client: Lark.Client,
+  options: { title: string; folderToken?: string },
+): Promise<{ documentId: string; title: string }> {
+  const res = await client.docx.v1.document.create({
+    data: {
+      title: options.title,
+      ...(options.folderToken ? { folder_token: options.folderToken } : {}),
+    },
+  });
+  if (res.code && res.code !== 0) {
+    throw new Error(`create doc failed: code=${res.code} msg=${res.msg}`);
+  }
+  const documentId = res.data?.document?.document_id;
+  if (!documentId) {
+    throw new Error(`create doc returned no document_id: ${JSON.stringify(res)}`);
+  }
+  return {
+    documentId,
+    title: res.data?.document?.title || options.title,
+  };
+}
+
+/**
+ * Convert markdown and insert as nested blocks under the page root
+ * (block_id === document_id for docx).
+ */
+export async function appendMarkdownToDocument(
+  client: Lark.Client,
+  documentIdOrUrl: string,
+  markdown: string,
+): Promise<{ blockCount: number }> {
+  const document_id = parseDocumentId(documentIdOrUrl);
+  const md = markdown.trim();
+  if (!md) throw new Error("markdown content is empty");
+
+  const converted = await client.docx.v1.document.convert({
+    data: {
+      content_type: "markdown",
+      content: md,
+    },
+  });
+  if (converted.code && converted.code !== 0) {
+    throw new Error(
+      `convert markdown failed: code=${converted.code} msg=${converted.msg}`,
+    );
+  }
+
+  const childrenId = converted.data?.first_level_block_ids ?? [];
+  const descendants = converted.data?.blocks ?? [];
+  if (childrenId.length === 0 || descendants.length === 0) {
+    throw new Error("convert markdown produced no blocks");
+  }
+
+  // Insert in chunks of <= 1000 blocks if needed; convert already returns tree.
+  const res = await client.docx.v1.documentBlockDescendant.create({
+    path: {
+      document_id,
+      block_id: document_id,
+    },
+    data: {
+      children_id: childrenId,
+      // convert() returns a loose block tree; the create payload is generated and huge.
+      descendants: descendants as never,
+    },
+  });
+  if (res.code && res.code !== 0) {
+    throw new Error(
+      `append blocks failed: code=${res.code} msg=${res.msg} — 确认机器人已是文档协作者且有编辑权限`,
+    );
+  }
+
+  return { blockCount: descendants.length };
+}
+
+export async function createDocumentWithMarkdown(
+  client: Lark.Client,
+  options: { title: string; markdown: string; folderToken?: string },
+): Promise<{ documentId: string; title: string; blockCount: number }> {
+  const doc = await createDocument(client, {
+    title: options.title,
+    folderToken: options.folderToken,
+  });
+  const { blockCount } = await appendMarkdownToDocument(
+    client,
+    doc.documentId,
+    options.markdown,
+  );
+  return { ...doc, blockCount };
+}

package/src/feishu-files.ts

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import path from "node:path";
+import type * as Lark from "@larksuiteoapi/node-sdk";
+
+export type FeishuUploadFileType =
+  | "opus"
+  | "mp4"
+  | "pdf"
+  | "doc"
+  | "xls"
+  | "ppt"
+  | "stream";
+
+const EXT_TO_TYPE: Record<string, FeishuUploadFileType> = {
+  ".opus": "opus",
+  ".mp4": "mp4",
+  ".pdf": "pdf",
+  ".doc": "doc",
+  ".docx": "doc",
+  ".xls": "xls",
+  ".xlsx": "xls",
+  ".ppt": "ppt",
+  ".pptx": "ppt",
+};
+
+export function guessFileType(fileName: string): FeishuUploadFileType {
+  return EXT_TO_TYPE[path.extname(fileName).toLowerCase()] ?? "stream";
+}
+
+/** Upload a local file; returns file_key for sending as a message. */
+export async function uploadFile(
+  client: Lark.Client,
+  filePath: string,
+  options?: { fileName?: string; fileType?: FeishuUploadFileType },
+): Promise<{ fileKey: string; fileName: string }> {
+  const fileName = options?.fileName || path.basename(filePath);
+  const fileType = options?.fileType || guessFileType(fileName);
+  const buf = fs.readFileSync(filePath);
+  if (buf.length === 0) throw new Error(`empty file: ${filePath}`);
+  if (buf.length > 30 * 1024 * 1024) {
+    throw new Error(`file too large (>30MB): ${filePath}`);
+  }
+
+  const res = await client.im.v1.file.create({
+    data: {
+      file_type: fileType,
+      file_name: fileName,
+      file: buf,
+    },
+  });
+
+  const fileKey = res?.file_key;
+  if (!fileKey) {
+    throw new Error(`upload file failed: ${JSON.stringify(res)}`);
+  }
+  return { fileKey, fileName };
+}
+
+/** Upload a local image; returns image_key. */
+export async function uploadImage(
+  client: Lark.Client,
+  filePath: string,
+): Promise<string> {
+  const buf = fs.readFileSync(filePath);
+  if (buf.length === 0) throw new Error(`empty image: ${filePath}`);
+  if (buf.length > 10 * 1024 * 1024) {
+    throw new Error(`image too large (>10MB): ${filePath}`);
+  }
+
+  const res = await client.im.v1.image.create({
+    data: {
+      image_type: "message",
+      image: buf,
+    },
+  });
+
+  const imageKey = res?.image_key;
+  if (!imageKey) {
+    throw new Error(`upload image failed: ${JSON.stringify(res)}`);
+  }
+  return imageKey;
+}
+
+/** Reply with a file message. */
+export async function replyFile(
+  client: Lark.Client,
+  messageId: string,
+  filePath: string,
+): Promise<void> {
+  const { fileKey } = await uploadFile(client, filePath);
+  await client.im.v1.message.reply({
+    path: { message_id: messageId },
+    data: {
+      msg_type: "file",
+      content: JSON.stringify({ file_key: fileKey }),
+    },
+  });
+}
+
+/** Reply with an image message. */
+export async function replyImage(
+  client: Lark.Client,
+  messageId: string,
+  filePath: string,
+): Promise<void> {
+  const imageKey = await uploadImage(client, filePath);
+  await client.im.v1.message.reply({
+    path: { message_id: messageId },
+    data: {
+      msg_type: "image",
+      content: JSON.stringify({ image_key: imageKey }),
+    },
+  });
+}
+
+const IMAGE_EXTS = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+]);
+
+export function isImagePath(filePath: string): boolean {
+  return IMAGE_EXTS.has(path.extname(filePath).toLowerCase());
+}
+
+export async function replyLocalPath(
+  client: Lark.Client,
+  messageId: string,
+  filePath: string,
+): Promise<{ kind: "file" | "image"; fileName: string }> {
+  const fileName = path.basename(filePath);
+  if (isImagePath(filePath)) {
+    await replyImage(client, messageId, filePath);
+    return { kind: "image", fileName };
+  }
+  await replyFile(client, messageId, filePath);
+  return { kind: "file", fileName };
+}
+
+/** Download a resource attached to an incoming Feishu message. */
+export async function downloadMessageResource(
+  client: Lark.Client,
+  messageId: string,
+  fileKey: string,
+  type: "file" | "image" | "media",
+  destPath: string,
+): Promise<string> {
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  const resp = await client.im.v1.messageResource.get({
+    path: { message_id: messageId, file_key: fileKey },
+    params: { type },
+  });
+  await resp.writeFile(destPath);
+  return destPath;
+}
+
+export function parseIncomingFileContent(content: string): {
+  fileKey?: string;
+  imageKey?: string;
+  fileName?: string;
+} {
+  try {
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    return {
+      fileKey: typeof parsed.file_key === "string" ? parsed.file_key : undefined,
+      imageKey:
+        typeof parsed.image_key === "string" ? parsed.image_key : undefined,
+      fileName:
+        typeof parsed.file_name === "string"
+          ? parsed.file_name
+          : typeof parsed.name === "string"
+            ? parsed.name
+            : undefined,
+    };
+  } catch {
+    return {};
+  }
+}

package/src/feishu-markdown.ts

@@ -0,0 +1,79 @@
+/** Heuristic: does this look like markdown worth rendering? */
+export function looksLikeMarkdown(text: string): boolean {
+  if (!text || text.trim().length < 2) return false;
+
+  const t = text.trim();
+  if (/```[\s\S]*?```/.test(t)) return true;
+  if (/`[^`\n]+`/.test(t)) return true;
+  if (/^#{1,6}\s+/m.test(t)) return true;
+  if (/\*\*[^*\n]+\*\*/.test(t)) return true;
+  if (/(^|\s)\*[^*\n]+\*(\s|$)/.test(t)) return true;
+  if (/^[-*+]\s+/m.test(t)) return true;
+  if (/^\d+\.\s+/m.test(t)) return true;
+  if (/\[[^\]]+\]\([^)]+\)/.test(t)) return true;
+  if (/^\|.+\|/m.test(t)) return true;
+  if (/^>\s+/m.test(t)) return true;
+  if (/~~[^~]+~~/.test(t)) return true;
+
+  // Multi-paragraph agent replies often contain markdown even if subtle
+  if (t.includes("\n") && t.length > 120) return true;
+
+  return false;
+}
+
+/** Agent replies: prefer rendered markdown whenever plausible. */
+export function shouldRenderAgentReply(text: string): boolean {
+  return looksLikeMarkdown(text) || text.includes("\n\n") || text.length > 400;
+}
+
+/** Feishu post message with md tag (CommonMark + GFM). */
+export function buildPostMdContent(text: string): string {
+  return JSON.stringify({
+    zh_cn: {
+      content: [[{ tag: "md", text: optimizeMarkdownForFeishu(text) }]],
+    },
+  });
+}
+
+/** Feishu post renders H1/H2 oversized — demote headings slightly. */
+function optimizeMarkdownForFeishu(text: string): string {
+  if (!/^#{1,3} /m.test(text)) return text;
+  let r = text.replace(/^#{2,6} (.+)$/gm, "##### $1");
+  r = r.replace(/^# (.+)$/gm, "#### $1");
+  return r.replace(/\n{3,}/g, "\n\n");
+}
+
+/** Interactive card 2.0 with markdown element (fallback). */
+export function buildMarkdownCard(text: string): Record<string, unknown> {
+  return {
+    schema: "2.0",
+    config: { wide_screen_mode: true },
+    body: {
+      elements: [
+        {
+          tag: "markdown",
+          content: text,
+          text_align: "left",
+        },
+      ],
+    },
+  };
+}
+
+/** Split long replies; post/card limit ~30KB, keep headroom. */
+export function splitReplyChunks(text: string, markdown: boolean): string[] {
+  const max = markdown ? 28_000 : 3_500;
+  if (text.length <= max) return [text];
+
+  const parts: string[] = [];
+  let rest = text;
+  while (rest.length > max) {
+    let cut = rest.lastIndexOf("\n\n", max);
+    if (cut < max * 0.4) cut = rest.lastIndexOf("\n", max);
+    if (cut < max * 0.4) cut = max;
+    parts.push(rest.slice(0, cut));
+    rest = rest.slice(cut).trimStart();
+  }
+  if (rest) parts.push(rest);
+  return parts;
+}