@chenglu.she/sandy 1.0.0

package/.env.example

@@ -0,0 +1,24 @@
+FEISHU_APP_ID=cli_xxx
+FEISHU_APP_SECRET=xxx
+CURSOR_API_KEY=crsr_xxx
+
+# Agent display name (shown in Cursor / logs)
+AGENT_NAME=Sandy
+
+# Workspace the agent works in (defaults to current working directory)
+# AGENT_CWD=.
+
+# Extra roots the agent may use, comma-separated
+# AGENT_DIRS=~/code/api,~/code/web
+
+# Symlink names under AGENT_CWD whose targets should also be allowlisted
+# AGENT_DIR_LINKS=api,web
+
+# false ≈ full local shell (SSH / git / deploy). true = Cursor sandbox.
+AGENT_SANDBOX=false
+
+# Model id for @cursor/sdk
+CURSOR_MODEL=auto
+
+# Optional Drive folder_token for feishu_doc_create default placement
+# FEISHU_DOCS_FOLDER=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 louis-she
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# Feishu ↔ Cursor Bot
+
+<p align="center">
+  <img src="assets/sandy.png" alt="Sandy" width="220" height="220" />
+</p>
+
+<p align="center"><b>Sandy</b> — 飞书长连接机器人，背后用 <a href="https://cursor.com/docs/sdk/typescript"><code>@cursor/sdk</code></a> 跑本地 Cursor Agent。</p>
+
+通用脚手架：在任意项目目录放一份 `.env` +（可选）`.cursor/rules`，装好依赖后启动即可。
+
+## 需要什么
+
+- Node.js ≥ 20
+- [飞书企业自建应用](https://open.feishu.cn/)（开通机器人 + 长连接事件）
+- [Cursor API Key](https://cursor.com/settings)
+
+## Setup
+
+### 1. 安装
+
+```bash
+npm install -g @chenglu.she/sandy
+# 命令：feishu-cursor-bot 或 sandy
+```
+
+或从源码：
+
+```bash
+git clone https://github.com/louis-she/sandy.git
+cd sandy
+npm install
+npm link
+```
+
+### 2. 在「工作目录」准备 `.env`
+
+CLI **读取你启动时的 cwd** 下的 `.env`（不是包安装目录）。例如：
+
+```bash
+mkdir -p ~/my-agent-home && cd ~/my-agent-home
+cp /path/to/sandy/.env.example .env
+```
+
+必填：
+
+| 变量 | 说明 |
+|------|------|
+| `FEISHU_APP_ID` | 飞书应用 App ID |
+| `FEISHU_APP_SECRET` | 飞书应用 Secret |
+| `CURSOR_API_KEY` | Cursor API Key |
+
+常用可选：
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `AGENT_NAME` | `Sandy` | Agent 显示名 |
+| `AGENT_CWD` | 当前目录 | Agent 工作区（会加载这里的 `.cursor/rules`） |
+| `AGENT_DIRS` | （空） | 额外可访问目录，逗号分隔 |
+| `AGENT_DIR_LINKS` | （空） | `AGENT_CWD` 下要一并放行的 symlink 名 |
+| `AGENT_SANDBOX` | `false` | `true` 时开 Cursor 本地沙箱 |
+| `CURSOR_MODEL` | `auto` | 模型 id |
+| `FEISHU_DOCS_FOLDER` | （空） | 创建飞书文档时的默认 Drive `folder_token` |
+
+### 3. （推荐）放项目规则
+
+在 `AGENT_CWD`（默认就是 cwd）下：
+
+```text
+.cursor/rules/your-persona.mdc
+.cursor/rules/your-domain.mdc
+```
+
+Agent 通过 `settingSources: ["project"]` 加载这些规则。人设、业务知识都写在这里，**不要写进 bot 源码**。
+
+### 4. 飞书后台
+
+1. **应用能力** → 开通 **机器人**
+2. **权限**（开通后**发布新版本**才生效），至少：
+   - 消息：获取与发送单聊/群消息、上传图片、上传文件、下载文件（如 `im:message`、`im:resource`）
+   - 文档：读正文、创建文档、编辑文档（如 `docx:document:readonly`、`docx:document` / write）
+   - 若要把新建文档放到指定文件夹：Drive 文件夹相关权限，并填 `FEISHU_DOCS_FOLDER`
+3. **版本管理**：发布；可用范围包含你自己
+4. **事件与回调** → 订阅方式选 **长连接**（先让 bot 进程在线再保存）
+5. 事件：`im.message.receive_v1`
+6. 回调：`card.action.trigger`（Agent 选择题卡片用）
+7. **读写已有文档**：在飞书文档里把机器人加为协作者（读/编辑），仅开通 API 权限不够
+
+### 5. 启动
+
+```bash
+cd ~/my-agent-home   # 有 .env 的目录
+feishu-cursor-bot    # 或 sandy
+# 或
+npx @chenglu.she/sandy
+```
+
+看到 `ws client ready` 后，飞书里私聊机器人即可。
+
+#### macOS 常驻（可选）
+
+本仓库带了 launchd 包装，避免挂在 IDE 终端里被杀掉：
+
+```bash
+bash scripts/sandy-ctl.sh install
+bash scripts/sandy-ctl.sh status
+bash scripts/sandy-ctl.sh logs
+```
+
+> plist 里是本机绝对路径，换机器请改 `deploy/cn.sandy.plist` 或自己写一份 LaunchAgent。
+
+## 行为速览
+
+| 场景 | 行为 |
+|------|------|
+| 私聊 | 文本 / 文件 / 图片进 Agent |
+| 群聊 | 仅当 @机器人（文件同理，需 @） |
+| 同会话 | `Agent.resume` 多轮；映射在 cwd 的 `.data/sessions.json` |
+| `/new` `/reset` `重置` `新对话` | 清空会话，下次新建 Agent |
+| 连续消息 | 按会话排队；排队 `OneSecond`，处理中 `OnIt` |
+| `askQuestion` | 飞书交互卡片；点选或回编号后续跑 |
+| 用户发文件/图 | 下载到 `AGENT_CWD/.data/feishu-inbox/…`，路径写入 prompt |
+| Agent 发回文件 | 工具 `feishu_send_file`（本地路径 → 飞书回复） |
+| 飞书文档 | `feishu_doc_read` / `feishu_doc_create` / `feishu_doc_append` |
+
+## 开发
+
+```bash
+npm run dev        # tsx watch
+npm start          # 等同 feishu-cursor-bot（仍读 cwd .env）
+npm run typecheck
+```
+
+## License
+
+[MIT](./LICENSE)

package/bin/feishu-cursor-bot.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * CLI entry: run from any directory; loads `.env` from cwd (see src/config.ts).
+ *
+ *   npx feishu-cursor-bot
+ *   npm i -g . && feishu-cursor-bot
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const entry = path.join(packageRoot, "src", "index.ts");
+const require = createRequire(import.meta.url);
+
+let tsxCli;
+try {
+  tsxCli = require.resolve("tsx/cli");
+} catch {
+  console.error("Missing dependency `tsx`. Run npm install in the package root.");
+  process.exit(1);
+}
+
+const child = spawn(process.execPath, [tsxCli, entry, ...process.argv.slice(2)], {
+  cwd: process.cwd(),
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chenglu.she/sandy",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Feishu long-connection bot that drives Cursor agents via @cursor/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/louis-she/sandy.git"
+  },
+  "homepage": "https://github.com/louis-she/sandy",
+  "bugs": {
+    "url": "https://github.com/louis-she/sandy/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "feishu-cursor-bot": "./bin/feishu-cursor-bot.js",
+    "sandy": "./bin/feishu-cursor-bot.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.0",
+    "@larksuiteoapi/node-sdk": "^1.55.0",
+    "dotenv": "^16.6.1",
+    "tsx": "^4.20.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.17.0",
+    "typescript": "^5.9.2"
+  }
+}

package/src/ask-question.ts

@@ -0,0 +1,228 @@
+export type AskOption = {
+  id: string;
+  label: string;
+};
+
+export type AskQuestion = {
+  id: string;
+  prompt: string;
+  options: AskOption[];
+  allowMultiple: boolean;
+};
+
+export type ParsedAskQuestion = {
+  title?: string;
+  questions: AskQuestion[];
+  callId?: string;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as 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));
+}
+
+function parseQuestions(raw: unknown): AskQuestion[] {
+  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.questionId === "string"
+            ? obj.questionId
+            : `q_${index + 1}`;
+      const prompt =
+        typeof obj.prompt === "string"
+          ? obj.prompt
+          : typeof obj.question === "string"
+            ? obj.question
+            : typeof obj.text === "string"
+              ? obj.text
+              : `问题 ${index + 1}`;
+      const options = parseOptions(obj.options ?? obj.choices);
+      if (options.length === 0) return undefined;
+      return {
+        id,
+        prompt,
+        options,
+        allowMultiple: Boolean(obj.allowMultiple ?? obj.allow_multiple ?? obj.multiSelect),
+      };
+    })
+    .filter((x): x is AskQuestion => Boolean(x));
+}
+
+/** Defensive parse of askQuestion tool args / tool_use input. */
+export function parseAskQuestionArgs(args: unknown): ParsedAskQuestion | undefined {
+  const root = asRecord(args);
+  if (!root) return undefined;
+
+  const nested =
+    asRecord(root.args) ??
+    asRecord(root.input) ??
+    asRecord(root.arguments) ??
+    root;
+
+  const questions = parseQuestions(
+    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) {
+      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
+                : "请选择",
+        options,
+        allowMultiple: Boolean(nested.allowMultiple ?? nested.allow_multiple),
+      });
+    }
+  }
+
+  if (questions.length === 0) return undefined;
+
+  return {
+    title: typeof nested.title === "string" ? nested.title : undefined,
+    questions,
+  };
+}
+
+export function isAskQuestionToolName(name: string | undefined): boolean {
+  if (!name) return false;
+  const n = name.replace(/[_-]/g, "").toLowerCase();
+  return n === "askquestion" || n.endsWith("askquestion");
+}
+
+/** Format selected answers as a follow-up user message for Agent.send. */
+export function formatAnswerPrompt(
+  questions: AskQuestion[],
+  answers: Array<{ questionId: string; selectedOptionIds: string[]; freeformText?: string }>,
+): string {
+  const lines = ["【用户已完成选择题】请根据以下选择继续："];
+  for (const q of questions) {
+    const answer = answers.find((a) => a.questionId === q.id);
+    if (!answer) {
+      lines.push(`- ${q.prompt}: （未选择）`);
+      continue;
+    }
+    if (answer.freeformText?.trim()) {
+      lines.push(`- ${q.prompt}: ${answer.freeformText.trim()}`);
+      continue;
+    }
+    const labels = answer.selectedOptionIds.map((id) => {
+      const opt = q.options.find((o) => o.id === id);
+      return opt ? `${opt.label} (id=${opt.id})` : id;
+    });
+    lines.push(`- ${q.prompt}: ${labels.join("、")}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Parse a free-text reply against pending questions.
+ * Supports: "1", "1,3", "选项原文", or "q1=1; q2=2".
+ */
+export function parseTextAnswer(
+  questions: AskQuestion[],
+  text: string,
+): Array<{ questionId: string; selectedOptionIds: string[]; freeformText?: string }> | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+
+  if (questions.length === 1) {
+    const q = questions[0]!;
+    const byLabel = q.options.find(
+      (o) => o.label === trimmed || o.id === trimmed,
+    );
+    if (byLabel) {
+      return [{ questionId: q.id, selectedOptionIds: [byLabel.id] }];
+    }
+
+    const nums = trimmed
+      .split(/[,，\s]+/)
+      .map((p) => Number.parseInt(p, 10))
+      .filter((n) => Number.isFinite(n) && n >= 1 && n <= q.options.length);
+
+    if (nums.length > 0) {
+      const ids = [...new Set(nums)].map((n) => q.options[n - 1]!.id);
+      if (!q.allowMultiple && ids.length > 1) return undefined;
+      return [{ questionId: q.id, selectedOptionIds: ids }];
+    }
+
+    // Freeform fallback for single question
+    return [{ questionId: q.id, selectedOptionIds: [], freeformText: trimmed }];
+  }
+
+  // Multi-question: expect "1:1; 2:2" or "q1=label"
+  const parts = trimmed.split(/[;；\n]+/).map((p) => p.trim()).filter(Boolean);
+  if (parts.length === 0) return undefined;
+
+  const answers: Array<{ questionId: string; selectedOptionIds: string[]; freeformText?: string }> = [];
+  for (const part of parts) {
+    const m = part.match(/^(?:q\s*)?(\d+|[A-Za-z0-9_-]+)\s*[=:：]\s*(.+)$/);
+    if (!m) return undefined;
+    const key = m[1]!;
+    const value = m[2]!.trim();
+    const q =
+      questions.find((qq) => qq.id === key) ??
+      ( /^\d+$/.test(key) ? questions[Number(key) - 1] : undefined);
+    if (!q) return undefined;
+
+    const idxs = value
+      .split(/[,，\s]+/)
+      .map((p) => Number.parseInt(p, 10))
+      .filter((n) => Number.isFinite(n) && n >= 1 && n <= q.options.length);
+
+    if (idxs.length > 0) {
+      answers.push({
+        questionId: q.id,
+        selectedOptionIds: [...new Set(idxs)].map((n) => q.options[n - 1]!.id),
+      });
+      continue;
+    }
+
+    const opt = q.options.find((o) => o.label === value || o.id === value);
+    if (opt) {
+      answers.push({ questionId: q.id, selectedOptionIds: [opt.id] });
+      continue;
+    }
+
+    answers.push({ questionId: q.id, selectedOptionIds: [], freeformText: value });
+  }
+
+  return answers.length > 0 ? answers : undefined;
+}

package/src/config.ts

@@ -0,0 +1,93 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import dotenv from "dotenv";
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+/** Workspace that owns `.env` / agent cwd — usually where you run the CLI. */
+export const workDir = (() => {
+  const override = process.env.FEISHU_CURSOR_CWD?.trim();
+  if (!override) return process.cwd();
+  return expandPath(override, process.cwd());
+})();
+
+// Prefer cwd `.env`, then package-local `.env` as fallback (no override).
+dotenv.config({ path: path.join(workDir, ".env") });
+dotenv.config({ path: path.join(packageRoot, ".env") });
+
+function required(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(
+      `Missing required env: ${name} (put it in ${path.join(workDir, ".env")})`,
+    );
+  }
+  return value;
+}
+
+function expandPath(raw: string, base: string = process.cwd()): string {
+  const trimmed = raw.trim();
+  if (trimmed === "~") return os.homedir();
+  if (trimmed.startsWith("~/")) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  return path.isAbsolute(trimmed) ? trimmed : path.resolve(base, trimmed);
+}
+
+function parseBool(raw: string | undefined, defaultValue: boolean): boolean {
+  if (raw === undefined || raw.trim() === "") return defaultValue;
+  const v = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(v)) return true;
+  if (["0", "false", "no", "off"].includes(v)) return false;
+  return defaultValue;
+}
+
+const agentCwdRaw = process.env.AGENT_CWD?.trim() || workDir;
+const agentDirsRaw = process.env.AGENT_DIRS?.trim() || "";
+const agentDirs = agentDirsRaw
+  ? [...new Set(agentDirsRaw.split(",").map((p) => expandPath(p)).filter(Boolean))]
+  : [];
+
+/** Optional symlink names under AGENT_CWD to also allow (comma-separated). */
+const agentDirLinksRaw = process.env.AGENT_DIR_LINKS?.trim() || "";
+export const agentDirLinks = agentDirLinksRaw
+  ? [...new Set(agentDirLinksRaw.split(",").map((s) => s.trim()).filter(Boolean))]
+  : [];
+
+export const config = {
+  packageRoot,
+  workDir,
+  feishuAppId: required("FEISHU_APP_ID"),
+  feishuAppSecret: required("FEISHU_APP_SECRET"),
+  cursorApiKey: required("CURSOR_API_KEY"),
+  cursorModel: process.env.CURSOR_MODEL?.trim() || "auto",
+  /** Display name for the Cursor agent / bot persona. */
+  agentName: process.env.AGENT_NAME?.trim() || "Sandy",
+  /** Primary workspace root for the agent. Defaults to cwd. */
+  agentCwd: expandPath(String(agentCwdRaw)),
+  /** Optional extra workspace roots (multi-root). */
+  agentDirs,
+  agentDirLinks,
+  /** Enable Cursor local sandbox (FS + shell + default deny network for shell). */
+  agentSandbox: parseBool(process.env.AGENT_SANDBOX, false),
+  sessionStorePath: path.resolve(workDir, ".data", "sessions.json"),
+  pendingStorePath: path.resolve(workDir, ".data", "pending-questions.json"),
+  /** Optional Drive folder_token for feishu_doc_create default placement. */
+  feishuDocsFolder: process.env.FEISHU_DOCS_FOLDER?.trim() || "",
+  /** Where incoming Feishu files are saved (under AGENT_CWD so the agent can read them). */
+  inboxDir: path.join(expandPath(String(agentCwdRaw)), ".data", "feishu-inbox"),
+};
+
+export function localAgentOptions() {
+  return {
+    cwd: config.agentCwd,
+    ...(config.agentDirs.length > 0 ? { dirs: config.agentDirs } : {}),
+    ...(config.agentSandbox ? { sandboxOptions: { enabled: true as const } } : {}),
+    // Load AGENTS.md / .cursor/rules from AGENT_CWD.
+    settingSources: ["project" as const],
+  };
+}