@chenglu.she/sandy 1.0.3 → 1.0.5

package/README.md

@@ -31,7 +31,13 @@ mkdir -p ~/treedome && cd ~/treedome
 sandy init
 ```
 
-会交互式询问飞书 / Cursor / Agent 等项，并写入当前目录的 `config.yaml`。也可参考 [config.yaml.example](./config.yaml.example) 手改。
+会交互式询问飞书 / Cursor / Agent 等项，写入 `config.yaml`；在 macOS 上接着触发磁盘授权弹窗（桌面 / 文稿 / 下载等）。人设模板见 [templates/sandy.mdc](./templates/sandy.mdc)，可复制到 `.cursor/rules/`。
+
+新机器务必在**电脑屏幕前**跑 init（不要 SSH）：弹出的「node 想访问某某文件夹」全部点「允许」，并把提示里的 Node 路径加到「完全磁盘访问权限」。以后单独补授权：
+
+```bash
+sandy authorize   # 别名：sandy diskauth
+```
 
 必填项：
 
@@ -68,14 +74,16 @@ Agent 通过 `settingSources: ["project"]` 加载这些规则。人设、业务
 
 1. **应用能力** → 开通 **机器人**
 2. **权限**（开通后**发布新版本**才生效），至少：
-   - 消息：获取与发送单聊/群消息、上传图片、上传文件、下载文件（如 `im:message`、`im:resource`）
-   - 文档：读正文、创建文档、编辑文档（如 `docx:document:readonly`、`docx:document` / write）
-   - 若要把新建文档放到指定文件夹：Drive 文件夹相关权限，并填 `feishuDocsFolder`
-3. **版本管理**：发布；可用范围包含你自己
-4. **事件与回调** → 订阅方式选 **长连接**（先让 bot 进程在线再保存）
-5. 事件：`im.message.receive_v1`
-6. 回调：`card.action.trigger`（Agent 选择题卡片用）
-7. **读写已有文档**：在飞书文档里把机器人加为协作者（读/编辑），仅开通 API 权限不够
+   - **单聊**：`im:message.p2p_msg:readonly`（只有群聊 @ 能回、私聊没反应，通常是缺这个）
+   - **群聊 @**：`im:message.group_at_msg:readonly`
+   - **发消息**：`im:message`
+   - 文件：上传/下载（`im:resource` 等）
+   - 文档：读/写 docx（按需）
+3. **版本管理**：发布；**可用范围**包含你自己
+4. **事件与回调** → 长连接（先 `sandy` 在线再保存）
+5. 事件 `im.message.receive_v1`：点进去确认 **单聊消息**、**群聊 @ 机器人** 子开关都已开通
+6. 回调：`card.action.trigger`
+7. **读写已有文档**：把机器人加为文档协作者
 
 ### 5. 启动
 
@@ -84,7 +92,7 @@ cd ~/treedome
 sandy
 ```
 
-看到 `ws client ready` 后，飞书里私聊机器人即可。
+看到 `ws client ready` 后，飞书里私聊机器人即可。远程任务卡住、回家才看到 node 访问目录的授权框，再跑一次 `sandy authorize`。
 
 #### macOS 常驻（可选）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenglu.she/sandy",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "license": "MIT",
   "type": "module",
   "description": "Feishu long-connection bot that drives Cursor agents via @cursor/sdk",
@@ -26,7 +26,8 @@
     "assets",
     "README.md",
     "LICENSE",
-    "config.yaml.example"
+    "config.yaml.example",
+    "templates"
   ],
   "scripts": {
     "dev": "tsx watch src/cli.ts",

package/src/authorize.ts

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  configFilePath,
+  expandPath,
+  readConfigFile,
+  workDir,
+} from "./config-io.js";
+
+export type AuthorizeOptions = {
+  extraDirs?: string[];
+  /** Open System Settings → Full Disk Access after probing. Default true. */
+  openSettings?: boolean;
+};
+
+type ProbeResult = {
+  dir: string;
+  status: "ok" | "missing" | "denied";
+  detail?: string;
+};
+
+function nodeBinary(): string {
+  try {
+    return fs.realpathSync(process.execPath);
+  } catch {
+    return process.execPath;
+  }
+}
+
+function isRemoteSession(): boolean {
+  return Boolean(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY);
+}
+
+function extraDirsFromConfig(): string[] {
+  try {
+    const filePath = configFilePath();
+    if (!fs.existsSync(filePath)) return [workDir];
+    const file = readConfigFile(filePath);
+    const cwdRaw = file.agent?.cwd?.trim() || workDir;
+    const dirs = Array.isArray(file.agent?.dirs) ? file.agent.dirs : [];
+    return [
+      expandPath(String(cwdRaw), workDir),
+      ...dirs.map((d) => expandPath(String(d), workDir)),
+    ];
+  } catch {
+    return [workDir];
+  }
+}
+
+function listSubdirs(root: string): string[] {
+  try {
+    return fs
+      .readdirSync(root, { withFileTypes: true })
+      .filter((d) => d.isDirectory() || d.isSymbolicLink())
+      .map((d) => path.resolve(root, d.name));
+  } catch {
+    return [];
+  }
+}
+
+function standardTargets(home: string): string[] {
+  return [
+    home,
+    path.join(home, "Desktop"),
+    path.join(home, "Documents"),
+    path.join(home, "Downloads"),
+    path.join(home, "Pictures"),
+    path.join(home, "Movies"),
+    path.join(home, "Music"),
+    path.join(home, "Library"),
+    path.join(home, "Library", "CloudStorage"),
+    path.join(home, "Library", "Mobile Documents"),
+    path.join(home, "Library", "Mobile Documents", "com~apple~CloudDocs"),
+  ];
+}
+
+function uniqueExistingOrder(dirs: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const raw of dirs) {
+    const resolved = path.resolve(raw);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+function probe(dir: string): ProbeResult {
+  try {
+    fs.accessSync(dir, fs.constants.R_OK);
+    const st = fs.statSync(dir);
+    if (st.isDirectory()) {
+      const dh = fs.opendirSync(dir);
+      dh.closeSync();
+    }
+    return { dir, status: "ok" };
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") return { dir, status: "missing" };
+    return { dir, status: "denied", detail: err.code || err.message };
+  }
+}
+
+function displayPath(dir: string, home: string): string {
+  if (dir === home) return "~";
+  if (dir.startsWith(home + path.sep)) return "~" + dir.slice(home.length);
+  return dir;
+}
+
+function openFullDiskAccessSettings(): void {
+  spawn(
+    "open",
+    [
+      "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles",
+    ],
+    { detached: true, stdio: "ignore" },
+  ).unref();
+}
+
+/**
+ * Touch macOS TCC-protected folders so this Node binary gets Files and Folders
+ * prompts. Must be run at the Mac (GUI session); SSH will hang on unread dialogs.
+ */
+export function runAuthorize(options: AuthorizeOptions = {}): void {
+  if (process.platform !== "darwin") {
+    console.log("非 macOS，无需磁盘授权。");
+    return;
+  }
+
+  const home = os.homedir();
+  const nodePath = nodeBinary();
+  const extra = options.extraDirs?.length ? options.extraDirs : extraDirsFromConfig();
+  const cloudRoot = path.resolve(path.join(home, "Library", "CloudStorage"));
+  const targets = uniqueExistingOrder([...standardTargets(home), ...extra]);
+  const openSettings = options.openSettings !== false;
+
+  console.log("macOS 磁盘授权");
+  console.log("会逐个访问受保护目录；弹出「node 想访问…」请全部点「允许」。");
+  console.log(`当前 Node: ${nodePath}`);
+  if (isRemoteSession()) {
+    console.log("检测到 SSH：弹窗会出现在这台 Mac 的屏幕上，没人点就会卡住。请在电脑前执行。");
+  }
+  console.log("");
+
+  const results: ProbeResult[] = [];
+  const seen = new Set(targets);
+  for (let i = 0; i < targets.length; i++) {
+    const dir = targets[i]!;
+    const label = displayPath(dir, home);
+    process.stdout.write(`  ${label} … `);
+    const result = probe(dir);
+    results.push(result);
+    if (result.status === "ok") console.log("ok");
+    else if (result.status === "missing") console.log("（目录不存在，跳过）");
+    else console.log(`拒绝 (${result.detail})`);
+
+    if (result.status === "ok" && dir === cloudRoot) {
+      for (const child of listSubdirs(dir)) {
+        if (seen.has(child)) continue;
+        seen.add(child);
+        targets.push(child);
+      }
+    }
+  }
+
+  const denied = results.filter((r) => r.status === "denied");
+  const ok = results.filter((r) => r.status === "ok");
+  console.log("");
+  console.log(`完成：允许 ${ok.length}，拒绝 ${denied.length}，其余目录不存在。`);
+  if (denied.length) {
+    console.log("被拒绝的目录远程访问仍会卡住。再跑一次 sandy authorize，或到「文件和文件夹」里打开开关。");
+  }
+
+  console.log("");
+  console.log("建议再把这份 Node 加到「完全磁盘访问权限」（升级 Node 后要重新加）：");
+  console.log(`  ${nodePath}`);
+
+  if (openSettings) {
+    openFullDiskAccessSettings();
+    console.log("已打开系统设置 → 隐私与安全性 → 完全磁盘访问权限。");
+  }
+}

package/src/cli.ts

@@ -3,10 +3,21 @@ const subcommand = process.argv[2];
 if (subcommand === "init") {
   const { runInit } = await import("./init.js");
   await runInit(process.argv.slice(3));
+} else if (subcommand === "authorize" || subcommand === "diskauth") {
+  const { runAuthorize } = await import("./authorize.js");
+  if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(`Usage: sandy authorize
+
+Touch macOS-protected folders so this Node binary gets Files and Folders prompts.
+Run at the Mac (not over SSH). Alias: sandy diskauth`);
+  } else {
+    runAuthorize({ openSettings: true });
+  }
 } else if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
   console.log(`Usage:
-  sandy          Start the Feishu bot (reads ./config.yaml)
-  sandy init     Interactive setup — writes config.yaml`);
+  sandy            Start the Feishu bot (reads ./config.yaml)
+  sandy init       Interactive setup — writes config.yaml, then macOS disk auth
+  sandy authorize  Trigger macOS folder-access prompts (alias: diskauth)`);
 } else {
   await import("./index.js");
 }

package/src/index.ts

@@ -218,9 +218,14 @@ async function handleMessage(raw: Parameters<typeof parseIncomingMessage>[0]) {
   const { text, mentionedBot } = extractText(msg, botOpenId ?? "");
 
   if (!shouldHandleMessage(msg, mentionedBot)) {
+    console.log(
+      `[handle] ignored chat_type=${msg.chatType} message_type=${msg.messageType} mentionedBot=${mentionedBot}`,
+    );
     return;
   }
 
+  console.log(`[handle] chat_type=${msg.chatType} message_id=${msg.messageId}`);
+
   const sessionKey = msg.chatId;
 
   let attachmentPrompt: string | undefined;

package/src/init-guides.ts

@@ -36,10 +36,15 @@ export const INIT_FIELD_GUIDES = {
     title: "飞书后台还需完成（init 不会替你操作）",
     lines: [
       "1. 应用能力 → 开通「机器人」",
-      "2. 权限管理 → 开通消息 / 文件 / 文档等权限，并发布新版本",
-      "3. 事件与回调 → 订阅方式选「长连接」",
-      "   事件：im.message.receive_v1；回调：card.action.trigger",
-      "4. 先在本机运行 sandy，看到 ws client ready 后再在后台保存长连接配置",
+      "2. 权限管理（缺一不可，改完必须发布新版本）：",
+      "   · 读取用户发给机器人的单聊消息 im:message.p2p_msg:readonly",
+      "   · 获取用户在群组中@机器人的消息 im:message.group_at_msg:readonly",
+      "   · 获取与发送单聊、群组消息 im:message",
+      "   · 文件 / 文档权限按需开通",
+      "3. 事件与回调 → 长连接；订阅 im.message.receive_v1",
+      "   点进该事件，确认「单聊消息」「群聊 @ 机器人」等子项均为已开通",
+      "4. 可用范围包含测试账号；先运行 sandy（ws client ready）再保存长连接",
+      "5. 群聊能回、私聊不回 → 几乎总是缺 p2p 权限或事件子开关未开",
     ],
     links: [
       { label: "事件订阅（长连接）", url: "https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/long-connection-mode" },
@@ -86,14 +91,6 @@ export const INIT_FIELD_GUIDES = {
     ],
   } satisfies FieldGuide,
 
-  agentDirLinks: {
-    title: "工作目录下的 symlink（可选）",
-    lines: [
-      "若 agent.cwd 里有 symlink（如 api → ~/code/api），填链接名以便一并放行。",
-      "多个名称用英文逗号分隔；留空可跳过。",
-    ],
-  } satisfies FieldGuide,
-
   agentSandbox: {
     title: "Cursor 本地沙箱",
     lines: [
@@ -116,17 +113,5 @@ export const INIT_FIELD_GUIDES = {
     links: [{ label: "Cursor 模型与 SDK", url: "https://cursor.com/docs/sdk/typescript" }],
   } satisfies FieldGuide,
 
-  feishuDocsFolder: {
-    title: "飞书文档默认文件夹（可选）",
-    lines: [
-      "feishu_doc_create 创建文档时默认放到哪个云空间文件夹。",
-      "在飞书云文档打开目标文件夹，从 URL 或文件夹属性里复制 folder_token。",
-      "不需要自动归档文档可留空。",
-    ],
-    links: [
-      { label: "创建文档 API", url: "https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/create" },
-    ],
-  } satisfies FieldGuide,
-
   feishuAppHome: FEISHU_APP_HOME,
 } as const;

package/src/init.ts

@@ -100,13 +100,6 @@ export async function runInit(argv: string[] = []): Promise<void> {
     );
     cfg.agent!.dirs = dirsRaw ? splitList(dirsRaw) : [];
 
-    const linksRaw = await prompt.askWithGuide(
-      INIT_FIELD_GUIDES.agentDirLinks,
-      "symlink 名（逗号分隔，可留空）",
-      { defaultValue: "" },
-    );
-    cfg.agent!.dirLinks = linksRaw ? splitList(linksRaw) : [];
-
     cfg.agent!.sandbox = await prompt.askYesNoWithGuide(
       INIT_FIELD_GUIDES.agentSandbox,
       "开启本地沙箱？",
@@ -117,15 +110,23 @@ export async function runInit(argv: string[] = []): Promise<void> {
       "模型 id",
       { defaultValue: "auto" },
     );
-    cfg.feishuDocsFolder = await prompt.askWithGuide(
-      INIT_FIELD_GUIDES.feishuDocsFolder,
-      "folder_token（可留空）",
-      { defaultValue: "" },
-    );
 
     writeConfigFile(outPath, cfg);
 
     console.log("\n✓ 已写入 " + outPath);
+
+    if (process.platform === "darwin") {
+      const { runAuthorize } = await import("./authorize.js");
+      prompt.section("四、macOS 磁盘授权");
+      console.log("  弹出「node 想访问…」请全部点「允许」。远程 SSH 时弹窗在本机屏幕上。\n");
+      const extraDirs = [
+        expandPath(cfg.agent!.cwd || targetDir, targetDir),
+        ...(cfg.agent!.dirs ?? []).map((d) => expandPath(d, targetDir)),
+        targetDir,
+      ];
+      runAuthorize({ extraDirs, openSettings: true });
+    }
+
     console.log("\n下一步:");
     console.log(`  cd ${targetDir}`);
     console.log("  sandy");

package/src/write-hook-policy.ts

@@ -29,7 +29,6 @@ export function writeHookPolicy(): string {
   const payload = {
     updatedAt: new Date().toISOString(),
     allowedRoots: [...new Set(roots)],
-    protectedWriteGlobs: [".cursor/rules", ".rules"],
   };
   fs.writeFileSync(policyPath, JSON.stringify(payload, null, 2), "utf8");
   return policyPath;

package/templates/sandy.mdc

@@ -0,0 +1,22 @@
+---
+description: Sandy 松鼠 — 通用飞书 Cursor Agent 人设模板
+alwaysApply: true
+---
+
+# Sandy 松鼠
+
+你是 **Sandy 松鼠**，开发与运维助手。
+
+## 职责
+
+- 协助写代码、排障、运维与部署
+- 在飞书里回答简洁、可执行；需要选择时用选择题
+- 可在 `AGENT_CWD/.cursor/rules/` 下创建或更新规则，沉淀领域约定与协作习惯
+- 文件修改范围以 `config.yaml` 里的 `agent.cwd` / `agent.dirs` 白名单为准
+- 可使用本机 shell（SSH / git / 项目脚本），除非 `agent.sandbox=true`
+
+## 风格
+
+- 自称：Sandy 松鼠
+- 直接、靠谱、少废话；先给结论再展开
+- 领域约定写在同目录其它 rules 里，按需维护