@chenglu.she/sandy 1.0.5 → 1.0.6

package/README.md

@@ -115,7 +115,7 @@ bash scripts/sandy-ctl.sh logs
 | 同会话 | `Agent.resume` 多轮；映射在 cwd 的 `.data/sessions.json` |
 | `/new` `/reset` `重置` `新对话` | 清空会话，下次新建 Agent |
 | 连续消息 | 按会话排队；排队 `OneSecond`，处理中 `OnIt` |
-| `askQuestion` | 飞书交互卡片；点选或回编号后续跑 |
+| `askQuestion` | 走 `feishu_ask_question`：飞书先发题目正文，再发可点选卡片；点选或回编号后续跑 |
 | 用户发文件/图 | 下载到 `AGENT_CWD/.data/feishu-inbox/…`，路径写入 prompt |
 | Agent 发回文件 | 工具 `feishu_send_file`（本地路径 → 飞书回复） |
 | 飞书文档 | `feishu_doc_read` / `feishu_doc_create` / `feishu_doc_append` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenglu.she/sandy",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "license": "MIT",
   "type": "module",
   "description": "Feishu long-connection bot that drives Cursor agents via @cursor/sdk",

package/src/ask-question.ts

@@ -23,28 +23,41 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 }
 
 function parseOptions(raw: unknown): AskOption[] {
-  if (!Array.isArray(raw)) return [];
-  return raw
-    .map((item, index) => {
-      const obj = asRecord(item);
-      if (!obj) return undefined;
-      const id =
-        typeof obj.id === "string"
-          ? obj.id
-          : typeof obj.value === "string"
-            ? obj.value
-            : `opt_${index + 1}`;
-      const label =
-        typeof obj.label === "string"
-          ? obj.label
-          : typeof obj.text === "string"
-            ? obj.text
-            : typeof obj.title === "string"
-              ? obj.title
-              : String(id);
-      return { id, label };
-    })
-    .filter((x): x is AskOption => Boolean(x));
+  if (Array.isArray(raw)) {
+    return raw
+      .map((item, index) => {
+        if (typeof item === "string" && item.trim()) {
+          return { id: `opt_${index + 1}`, label: item.trim() };
+        }
+        const obj = asRecord(item);
+        if (!obj) return undefined;
+        const id =
+          typeof obj.id === "string"
+            ? obj.id
+            : typeof obj.value === "string"
+              ? obj.value
+              : `opt_${index + 1}`;
+        const label =
+          typeof obj.label === "string"
+            ? obj.label
+            : typeof obj.text === "string"
+              ? obj.text
+              : typeof obj.title === "string"
+                ? obj.title
+                : typeof obj.description === "string"
+                  ? obj.description
+                  : String(id);
+        return { id, label };
+      })
+      .filter((x): x is AskOption => Boolean(x));
+  }
+
+  const obj = asRecord(raw);
+  if (!obj) return [];
+  return Object.entries(obj).map(([id, label], index) => ({
+    id: id || `opt_${index + 1}`,
+    label: typeof label === "string" && label.trim() ? label : String(id),
+  }));
 }
 
 function parseQuestions(raw: unknown): AskQuestion[] {
@@ -66,9 +79,10 @@ function parseQuestions(raw: unknown): AskQuestion[] {
             ? obj.question
             : typeof obj.text === "string"
               ? obj.text
-              : `问题 ${index + 1}`;
+              : typeof obj.header === "string"
+                ? obj.header
+                : `问题 ${index + 1}`;
       const options = parseOptions(obj.options ?? obj.choices);
-      if (options.length === 0) return undefined;
       return {
         id,
         prompt,
@@ -81,7 +95,7 @@ function parseQuestions(raw: unknown): AskQuestion[] {
 
 /** Defensive parse of askQuestion tool args / tool_use input. */
 export function parseAskQuestionArgs(args: unknown): ParsedAskQuestion | undefined {
-  const root = asRecord(args);
+  const root = asRecord(coerceJson(args));
   if (!root) return undefined;
 
   const nested =
@@ -91,22 +105,22 @@ export function parseAskQuestionArgs(args: unknown): ParsedAskQuestion | undefin
     root;
 
   const questions = parseQuestions(
-    nested.questions ?? nested.question_list ?? nested.items,
+    coerceJson(nested.questions ?? nested.question_list ?? nested.items),
   );
   if (questions.length === 0) {
-    // Single-question flattened shape
     const options = parseOptions(nested.options ?? nested.choices);
-    if (options.length > 0) {
+    const prompt =
+      typeof nested.prompt === "string"
+        ? nested.prompt
+        : typeof nested.question === "string"
+          ? nested.question
+          : typeof nested.title === "string"
+            ? nested.title
+            : "";
+    if (options.length > 0 || prompt) {
       questions.push({
         id: typeof nested.id === "string" ? nested.id : "q1",
-        prompt:
-          typeof nested.prompt === "string"
-            ? nested.prompt
-            : typeof nested.question === "string"
-              ? nested.question
-              : typeof nested.title === "string"
-                ? nested.title
-                : "请选择",
+        prompt: prompt || "请选择",
         options,
         allowMultiple: Boolean(nested.allowMultiple ?? nested.allow_multiple),
       });
@@ -121,10 +135,49 @@ export function parseAskQuestionArgs(args: unknown): ParsedAskQuestion | undefin
   };
 }
 
-export function isAskQuestionToolName(name: string | undefined): boolean {
+function coerceJson(raw: unknown): unknown {
+  if (typeof raw !== "string") return raw;
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return raw;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return raw;
+  }
+}
+
+/** Built-in Cursor AskQuestion only — not our Feishu custom tool. */
+export function isBuiltinAskQuestionToolName(name: string | undefined): boolean {
   if (!name) return false;
   const n = name.replace(/[_-]/g, "").toLowerCase();
-  return n === "askquestion" || n.endsWith("askquestion");
+  return n === "askquestion";
+}
+
+export function isAskQuestionToolName(name: string | undefined): boolean {
+  return isBuiltinAskQuestionToolName(name);
+}
+
+/** Last-resort ask payload when the tool fired but args did not parse. */
+export function fallbackAskFromRaw(args: unknown): ParsedAskQuestion {
+  const parsed = parseAskQuestionArgs(args);
+  if (parsed) return parsed;
+  const dump =
+    typeof args === "string"
+      ? args
+      : args == null
+        ? ""
+        : JSON.stringify(args, null, 2);
+  return {
+    title: "需要你的回复",
+    questions: [
+      {
+        id: "q1",
+        prompt: dump.trim() || "Agent 发起了询问，但题目解析失败。请直接回复你的选择或补充说明。",
+        options: [],
+        allowMultiple: false,
+      },
+    ],
+  };
 }
 
 /** Format selected answers as a follow-up user message for Agent.send. */

package/src/ask-waiters.ts

@@ -0,0 +1,44 @@
+export type AskAnswer = {
+  questionId: string;
+  selectedOptionIds: string[];
+  freeformText?: string;
+};
+
+type Waiter = {
+  resolve: (answers: AskAnswer[]) => void;
+  reject: (err: Error) => void;
+};
+
+const waiters = new Map<string, Waiter>();
+
+export function hasAskWaiter(sessionKey: string): boolean {
+  return waiters.has(sessionKey);
+}
+
+export function waitForAskAnswers(sessionKey: string): Promise<AskAnswer[]> {
+  const existing = waiters.get(sessionKey);
+  if (existing) {
+    existing.reject(new Error("replaced by a new question round"));
+    waiters.delete(sessionKey);
+  }
+
+  return new Promise((resolve, reject) => {
+    waiters.set(sessionKey, { resolve, reject });
+  });
+}
+
+export function resolveAskWaiter(sessionKey: string, answers: AskAnswer[]): boolean {
+  const waiter = waiters.get(sessionKey);
+  if (!waiter) return false;
+  waiters.delete(sessionKey);
+  waiter.resolve(answers);
+  return true;
+}
+
+export function cancelAskWaiter(sessionKey: string, reason: string): boolean {
+  const waiter = waiters.get(sessionKey);
+  if (!waiter) return false;
+  waiters.delete(sessionKey);
+  waiter.reject(new Error(reason));
+  return true;
+}

package/src/cursor-agent.ts

@@ -1,6 +1,7 @@
 import { Agent, CursorAgentError, type SDKCustomTool } from "@cursor/sdk";
 import {
-  isAskQuestionToolName,
+  fallbackAskFromRaw,
+  isBuiltinAskQuestionToolName,
   parseAskQuestionArgs,
   type ParsedAskQuestion,
 } from "./ask-question.js";
@@ -45,29 +46,24 @@ export async function runCursorAgent(
   const existing = sessionStore.get(sessionKey);
   let agent;
   const customTools = options?.customTools;
+  const agentOptions = {
+    apiKey: config.cursorApiKey,
+    model: { id: config.cursorModel },
+    name: config.agentName,
+    // Built-in AskQuestion is auto-declined in the SDK and never reaches Feishu.
+    disallowedTools: ["askQuestion"],
+    local: {
+      ...localAgentOptions(),
+      ...(customTools ? { 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 } : {}),
-        },
-      });
+      agent = await Agent.resume(existing.agentId, agentOptions);
       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 } : {}),
-        },
-      });
+      agent = await Agent.create(agentOptions);
       sessionStore.set(sessionKey, agent.agentId);
       console.log(`[cursor] created agent=${agent.agentId} session=${sessionKey}`);
     }
@@ -88,31 +84,26 @@ export async function runCursorAgent(
           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 (block.type === "tool_use" && isBuiltinAskQuestionToolName(block.name)) {
+            pendingAsk = parseAskQuestionArgs(block.input) ?? fallbackAskFromRaw(block.input);
+            sawAskQuestion = true;
+            console.log(
+              `[cursor] askQuestion via tool_use questions=${pendingAsk.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 {
+      if (event.type === "tool_call" && isBuiltinAskQuestionToolName(event.name)) {
+        pendingAsk = parseAskQuestionArgs(event.args) ?? fallbackAskFromRaw(event.args);
+        sawAskQuestion = true;
+        console.log(
+          `[cursor] askQuestion tool_call status=${event.status} questions=${pendingAsk.questions.length}`,
+        );
+        if (!parseAskQuestionArgs(event.args)) {
           console.warn(
-            "[cursor] askQuestion tool_call with unparsable args:",
-            JSON.stringify(event.args)?.slice(0, 500),
+            "[cursor] askQuestion args used fallback:",
+            JSON.stringify(event.args)?.slice(0, 800),
           );
         }
 

package/src/feishu-tools.ts

@@ -3,6 +3,12 @@ import path from "node:path";
 import type * as Lark from "@larksuiteoapi/node-sdk";
 import type { SDKCustomTool, SDKJsonValue } from "@cursor/sdk";
 import { config } from "./config.js";
+import {
+  fallbackAskFromRaw,
+  parseAskQuestionArgs,
+  type ParsedAskQuestion,
+} from "./ask-question.js";
+import type { AskAnswer } from "./ask-waiters.js";
 import {
   appendMarkdownToDocument,
   createDocument,
@@ -35,6 +41,7 @@ export type FeishuToolContext = {
   client: Lark.Client;
   replyToMessageId: string;
   chatId: string;
+  onAskQuestion?: (ask: ParsedAskQuestion) => Promise<AskAnswer[]>;
 };
 
 /** In-process tools exposed to the Cursor agent as custom-user-tools. */
@@ -42,6 +49,71 @@ export function buildFeishuCustomTools(
   ctx: FeishuToolContext,
 ): Record<string, SDKCustomTool> {
   return {
+    feishu_ask_question: {
+      description:
+        "Ask the Feishu user one or more questions and wait until they reply. " +
+        "Always use this when you need a decision (auth, image, plan, env, etc.). " +
+        "The user cannot see Cursor's AskQuestion UI — never write “等你回上面的题” " +
+        "without calling this tool. Include the full prompt and options on every question.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Optional card title" },
+          questions: {
+            type: "array",
+            description: "Questions to show in Feishu",
+            items: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+                prompt: { type: "string", description: "Question text shown to the user" },
+                options: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      id: { type: "string" },
+                      label: { type: "string" },
+                    },
+                  },
+                },
+                allowMultiple: { type: "boolean" },
+              },
+              required: ["prompt"],
+            },
+          },
+        },
+        required: ["questions"],
+      },
+      async execute(args) {
+        try {
+          if (!ctx.onAskQuestion) {
+            throw new Error("onAskQuestion is not configured");
+          }
+          const parsed =
+            parseAskQuestionArgs(args) ?? fallbackAskFromRaw(args);
+          const answers = await ctx.onAskQuestion(parsed);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({ ok: true, answers }),
+              },
+            ],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `feishu_ask_question cancelled: ${err instanceof Error ? err.message : String(err)}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      },
+    },
     feishu_send_file: {
       description:
         "Send a local file or image to the current Feishu chat as a reply. " +

package/src/feishu.ts

@@ -287,7 +287,7 @@ export function buildAskQuestionCard(
           } satisfies CardActionValue,
         })),
       });
-    } else {
+    } else if (q.options.length > 0) {
       const lines = q.options.map((opt, oi) => `${oi + 1}. ${opt.label}`);
       elements.push({
         tag: "markdown",
@@ -297,12 +297,14 @@ export function buildAskQuestionCard(
   }
 
   if (!useButtons) {
+    const hasOptions = ask.questions.some((q) => q.options.length > 0);
     elements.push({
       tag: "markdown",
-      content:
-        ask.questions.length === 1
+      content: hasOptions
+        ? ask.questions.length === 1
           ? "请直接回复选项编号（多选如 `1,3`），或回复选项原文。"
-          : "请按题号回复，例如：`1:2; 2:1`（题号:选项编号）。",
+          : "请按题号回复，例如：`1:2; 2:1`（题号:选项编号）。也可直接用文字说明。"
+        : "请直接回复本题答案。",
     });
   }
 
@@ -318,19 +320,26 @@ export function buildAskQuestionCard(
 }
 
 export function formatAskQuestionFallbackText(ask: ParsedAskQuestion): string {
-  const lines = [`【需要选择】${ask.title?.trim() || ""}`.trim()];
+  const lines = [`【需要你选择】${ask.title?.trim() || ""}`.trim()];
   for (const [qi, q] of ask.questions.entries()) {
     lines.push("");
     lines.push(`${qi + 1}. ${q.prompt}${q.allowMultiple ? "（可多选）" : ""}`);
+    if (q.options.length === 0) {
+      lines.push("   （请直接回复）");
+      continue;
+    }
     for (const [oi, opt] of q.options.entries()) {
       lines.push(`   ${oi + 1}) ${opt.label}`);
     }
   }
   lines.push("");
+  const hasOptions = ask.questions.some((q) => q.options.length > 0);
   lines.push(
-    ask.questions.length === 1
-      ? "回复编号继续（多选如 1,3），也可点卡片按钮。"
-      : "回复格式如 1:2; 2:1，也可点卡片按钮（单题单选）。",
+    hasOptions
+      ? ask.questions.length === 1
+        ? "回复编号继续（多选如 1,3），也可点卡片按钮。"
+        : "回复格式如 1:2; 2:1，或直接用文字说明。"
+      : "请直接回复答案。",
   );
   return lines.join("\n");
 }
@@ -341,6 +350,13 @@ export async function replyAskQuestionCard(
   sessionKey: string,
   ask: ParsedAskQuestion,
 ): Promise<void> {
+  // Always send readable text first. Cursor's built-in AskQuestion UI never
+  // reaches Feishu; if the interactive card fails, the user still sees the
+  // questions and how to reply.
+  await replyText(client, messageId, formatAskQuestionFallbackText(ask), {
+    preferMarkdown: true,
+  });
+
   const card = buildAskQuestionCard(sessionKey, ask);
   try {
     await client.im.v1.message.reply({
@@ -351,8 +367,7 @@ export async function replyAskQuestionCard(
       },
     });
   } catch (err) {
-    console.warn("[feishu] interactive card failed, falling back to text:", err);
-    await replyText(client, messageId, formatAskQuestionFallbackText(ask));
+    console.warn("[feishu] interactive ask card failed (text already sent):", err);
   }
 }
 

package/src/index.ts

@@ -2,7 +2,15 @@ import path from "node:path";
 import {
   formatAnswerPrompt,
   parseTextAnswer,
+  type AskQuestion,
 } from "./ask-question.js";
+import {
+  cancelAskWaiter,
+  hasAskWaiter,
+  resolveAskWaiter,
+  waitForAskAnswers,
+  type AskAnswer,
+} from "./ask-waiters.js";
 import {
   isResetCommand,
   resetSession,
@@ -138,10 +146,6 @@ async function deliverOutcome(
       createdAt: new Date().toISOString(),
     });
 
-    if (outcome.partialText) {
-      await replyAgentText(client, replyToMessageId, outcome.partialText);
-    }
-
     await replyAskQuestionCard(client, replyToMessageId, sessionKey, outcome.ask);
     console.log(
       `[ask] waiting for selection session=${sessionKey} questions=${outcome.ask.questions.length}`,
@@ -160,12 +164,32 @@ const sessionQueue = createSessionQueueManager(client, async (job: QueueJob) =>
       client,
       replyToMessageId: job.messageId,
       chatId: job.chatId,
+      onAskQuestion: async (ask) => {
+        pendingStore.set(sessionKey, {
+          agentId: sessionStore.get(sessionKey)?.agentId ?? "",
+          chatId: job.chatId,
+          replyToMessageId: job.messageId,
+          title: ask.title,
+          questions: ask.questions,
+          createdAt: new Date().toISOString(),
+        });
+        await replyAskQuestionCard(client, job.messageId, sessionKey, ask);
+        console.log(
+          `[ask] waiting (feishu_ask_question) session=${sessionKey} questions=${ask.questions.length}`,
+        );
+        try {
+          return await waitForAskAnswers(sessionKey);
+        } finally {
+          pendingStore.delete(sessionKey);
+        }
+      },
     });
     const outcome = await runCursorAgent(sessionStore, sessionKey, job.prompt, {
       customTools,
     });
     await deliverOutcome(sessionKey, job.messageId, job.chatId, outcome);
   } catch (err) {
+    cancelAskWaiter(sessionKey, "agent failed");
     const message = err instanceof Error ? err.message : String(err);
     console.error("[handle] agent failed:", err);
     await replyText(client, job.messageId, `处理失败：${message}`);
@@ -185,11 +209,24 @@ function enqueuePrompt(
   });
 }
 
+function freeformAnswers(questions: AskQuestion[], text: string): AskAnswer[] {
+  return questions.map((q) => ({
+    questionId: q.id,
+    selectedOptionIds: [],
+    freeformText: text,
+  }));
+}
+
 async function continueWithAnswers(
   sessionKey: string,
   replyToMessageId: string,
-  answers: Array<{ questionId: string; selectedOptionIds: string[]; freeformText?: string }>,
+  answers: AskAnswer[],
 ): Promise<void> {
+  if (resolveAskWaiter(sessionKey, answers)) {
+    console.log(`[ask] resolved in-run waiter session=${sessionKey}`);
+    return;
+  }
+
   const pending = pendingStore.get(sessionKey);
   if (!pending) {
     await replyText(client, replyToMessageId, "没有待回答的选择题，直接发消息即可。");
@@ -251,6 +288,7 @@ async function handleMessage(raw: Parameters<typeof parseIncomingMessage>[0]) {
   }
 
   if (isResetCommand(text)) {
+    cancelAskWaiter(sessionKey, "user reset");
     resetSession(sessionStore, sessionKey);
     pendingStore.delete(sessionKey);
     await sessionQueue.clear(sessionKey);
@@ -260,12 +298,13 @@ async function handleMessage(raw: Parameters<typeof parseIncomingMessage>[0]) {
 
   const pending = pendingStore.get(sessionKey);
   if (pending && text && !attachmentPrompt) {
-    const answers = parseTextAnswer(pending.questions, text);
+    const answers =
+      parseTextAnswer(pending.questions, text) ??
+      (hasAskWaiter(sessionKey) ? freeformAnswers(pending.questions, text) : undefined);
     if (answers) {
       await continueWithAnswers(sessionKey, msg.messageId, answers);
       return;
     }
-    // Not a valid answer — treat as normal new prompt, drop pending.
     console.log(`[ask] clearing pending; treating as new prompt session=${sessionKey}`);
     pendingStore.delete(sessionKey);
   }
@@ -291,6 +330,7 @@ async function handleCardAction(data: unknown) {
   const q = pending.questions.find((qq) => qq.id === value.qid);
   if (!q || !q.options.some((o) => o.id === value.oid)) {
     await replyText(client, replyTo, "选项无效或已过期，请重新提问。");
+    cancelAskWaiter(sessionKey, "invalid option");
     pendingStore.delete(sessionKey);
     return;
   }

package/templates/sandy.mdc

@@ -10,7 +10,7 @@ alwaysApply: true
 ## 职责
 
 - 协助写代码、排障、运维与部署
-- 在飞书里回答简洁、可执行；需要选择时用选择题
+- 在飞书里回答简洁、可执行；需要对方做选择时，必须调用 `feishu_ask_question`（题目和选项会发到飞书）。不要只写「等你回上面的题」——飞书用户看不到 Cursor 里的询问框。
 - 可在 `AGENT_CWD/.cursor/rules/` 下创建或更新规则，沉淀领域约定与协作习惯
 - 文件修改范围以 `config.yaml` 里的 `agent.cwd` / `agent.dirs` 白名单为准
 - 可使用本机 shell（SSH / git / 项目脚本），除非 `agent.sandbox=true`