@chenglu.she/sandy 1.0.2 → 1.0.4

package/README.md

@@ -31,7 +31,7 @@ mkdir -p ~/treedome && cd ~/treedome
 sandy init
 ```
 
-会交互式询问飞书 / Cursor / Agent 等项，并写入当前目录的 `config.yaml`。也可参考 [config.yaml.example](./config.yaml.example) 手改。
+会交互式询问飞书 / Cursor / Agent 等项，并写入当前目录的 `config.yaml`。人设模板见 [templates/sandy.mdc](./templates/sandy.mdc)，可复制到 `.cursor/rules/`。
 
 必填项：
 
@@ -68,14 +68,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. 启动
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenglu.she/sandy",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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/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

@@ -0,0 +1,137 @@
+import type { FieldGuide } from "./prompt.js";
+
+const FEISHU_APP_HOME: FieldGuide = {
+  title: "飞书开放平台",
+  lines: ["企业自建应用的入口，下面几项都在同一个应用里配置。"],
+  links: [{ label: "打开飞书开发者后台", url: "https://open.feishu.cn/app" }],
+};
+
+export const INIT_FIELD_GUIDES = {
+  feishuAppId: {
+    title: "飞书 App ID",
+    lines: [
+      "在飞书开发者后台创建「企业自建应用」后获取。",
+      "路径：你的应用 → 凭证与基础信息 → App ID",
+      "格式通常以 cli_ 开头。",
+    ],
+    links: [
+      { label: "飞书开发者后台", url: "https://open.feishu.cn/app" },
+      {
+        label: "创建应用说明",
+        url: "https://open.feishu.cn/document/home/introduction-to-custom-app-development/self-built-application-development-process",
+      },
+    ],
+  } satisfies FieldGuide,
+
+  feishuAppSecret: {
+    title: "飞书 App Secret",
+    lines: [
+      "与 App ID 在同一页：凭证与基础信息 → App Secret",
+      "点击「显示」或「重置」后复制；勿泄露或提交到 git。",
+    ],
+    links: [{ label: "飞书开发者后台", url: "https://open.feishu.cn/app" }],
+  } satisfies FieldGuide,
+
+  feishuSetupHint: {
+    title: "飞书后台还需完成（init 不会替你操作）",
+    lines: [
+      "1. 应用能力 → 开通「机器人」",
+      "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" },
+      { label: "机器人能力说明", url: "https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability" },
+    ],
+  } satisfies FieldGuide,
+
+  cursorApiKey: {
+    title: "Cursor API Key",
+    lines: [
+      "在 Cursor 账号设置里创建，用于 @cursor/sdk 调用本地 Agent。",
+      "路径：Cursor Settings → Integrations / API Keys（或 Dashboard 中的 API Keys）",
+      "格式通常以 crsr_ 开头。",
+    ],
+    links: [
+      { label: "Cursor 设置", url: "https://cursor.com/settings" },
+      { label: "Cursor SDK 文档", url: "https://cursor.com/docs/sdk/typescript" },
+    ],
+  } satisfies FieldGuide,
+
+  agentName: {
+    title: "Agent 显示名",
+    lines: [
+      "仅影响日志与 Cursor 侧 Agent 标题，飞书里仍显示机器人在后台设置的名称。",
+      "直接回车使用默认 Sandy 即可。",
+    ],
+  } satisfies FieldGuide,
+
+  agentCwd: {
+    title: "Agent 工作目录",
+    lines: [
+      "Agent 读写代码、加载 .cursor/rules 的根目录。",
+      "建议设为你要放 config.yaml 的目录（例如 ~/treedome）。",
+      "支持 ~ 与绝对路径；相对路径相对于运行 sandy 时的 cwd。",
+    ],
+  } satisfies FieldGuide,
+
+  agentDirs: {
+    title: "额外可访问目录（可选）",
+    lines: [
+      "除工作目录外，Agent 还可以访问哪些路径（多仓库 / 多项目时用）。",
+      "多个目录用英文逗号分隔，例如：~/code/api,~/code/web",
+      "留空表示仅使用上面的工作目录。",
+    ],
+  } satisfies FieldGuide,
+
+  agentDirLinks: {
+    title: "工作目录下的 symlink（可选）",
+    lines: [
+      "若 agent.cwd 里有 symlink（如 api → ~/code/api），填链接名以便一并放行。",
+      "多个名称用英文逗号分隔；留空可跳过。",
+    ],
+  } satisfies FieldGuide,
+
+  agentSandbox: {
+    title: "Cursor 本地沙箱",
+    lines: [
+      "开启后 Agent 的 shell/文件操作走 Cursor 沙箱，默认禁止随意访问网络。",
+      "需要 SSH、git push、deploy 等本机能力时选「否」。",
+      "一般个人机器上建议关闭（默认）。",
+    ],
+    links: [
+      { label: "SDK 沙箱说明", url: "https://cursor.com/docs/sdk/typescript#sandbox-options" },
+    ],
+  } satisfies FieldGuide,
+
+  cursorModel: {
+    title: "Cursor 模型",
+    lines: [
+      "传给 @cursor/sdk 的 model id。",
+      "auto 表示由 Cursor 自动选择；也可填具体模型名。",
+      "直接回车使用 auto。",
+    ],
+    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

@@ -1,5 +1,4 @@
 import fs from "node:fs";
-import path from "node:path";
 import {
   configFilePath,
   expandPath,
@@ -7,6 +6,7 @@ import {
   writeConfigFile,
 } from "./config-io.js";
 import { defaultConfigFile, type SandyConfigFile } from "./config-schema.js";
+import { INIT_FIELD_GUIDES } from "./init-guides.js";
 import { createPrompter } from "./prompt.js";
 
 function parseArgs(argv: string[]): { targetDir: string } {
@@ -43,12 +43,13 @@ export async function runInit(argv: string[] = []): Promise<void> {
   const prompt = createPrompter();
 
   try {
-    console.log("Sandy 初始化 — 逐步生成 config.yaml\n");
+    console.log("Sandy 初始化");
+    console.log("会逐步说明每项如何获取，并写入 config.yaml。\n");
     console.log(`目标目录: ${targetDir}`);
-    console.log(`配置文件: ${outPath}\n`);
+    console.log(`配置文件: ${outPath}`);
 
     if (fs.existsSync(outPath)) {
-      const overwrite = await prompt.askYesNo("已存在 config.yaml，是否覆盖？", false);
+      const overwrite = await prompt.askYesNo("\n已存在 config.yaml，是否覆盖？", false);
       if (!overwrite) {
         console.log("已取消。");
         return;
@@ -57,32 +58,78 @@ export async function runInit(argv: string[] = []): Promise<void> {
 
     const cfg: SandyConfigFile = defaultConfigFile(targetDir);
 
-    console.log("【必填】飞书与 Cursor");
-    cfg.feishu.appId = await prompt.askRequired("飞书 App ID (FEISHU_APP_ID)");
-    cfg.feishu.appSecret = await prompt.askRequired("飞书 App Secret");
-    cfg.cursor.apiKey = await prompt.askRequired("Cursor API Key");
+    prompt.section("一、飞书应用");
+    prompt.guide(INIT_FIELD_GUIDES.feishuAppHome);
 
-    console.log("\n【可选】Agent 与工作区");
-    cfg.agent!.name = await prompt.ask("Agent 显示名", "Sandy");
-    cfg.agent!.cwd = await prompt.ask("Agent 工作目录 (AGENT_CWD)", targetDir);
+    cfg.feishu.appId = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.feishuAppId,
+      "App ID",
+      { required: true },
+    );
+    cfg.feishu.appSecret = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.feishuAppSecret,
+      "App Secret",
+      { required: true },
+    );
+
+    prompt.guide(INIT_FIELD_GUIDES.feishuSetupHint);
+
+    prompt.section("二、Cursor");
+    cfg.cursor.apiKey = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.cursorApiKey,
+      "API Key",
+      { required: true },
+    );
+
+    prompt.section("三、Agent 与工作区（可一路回车用默认）");
+    cfg.agent!.name = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.agentName,
+      "显示名",
+      { defaultValue: "Sandy" },
+    );
+    cfg.agent!.cwd = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.agentCwd,
+      "工作目录",
+      { defaultValue: targetDir },
+    );
 
-    const dirsRaw = await prompt.ask("额外可访问目录，逗号分隔 (AGENT_DIRS，可留空)", "");
+    const dirsRaw = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.agentDirs,
+      "额外目录（逗号分隔，可留空）",
+      { defaultValue: "" },
+    );
     cfg.agent!.dirs = dirsRaw ? splitList(dirsRaw) : [];
 
-    const linksRaw = await prompt.ask(
-      "AGENT_CWD 下要放行的 symlink 名，逗号分隔 (可留空)",
-      "",
+    const linksRaw = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.agentDirLinks,
+      "symlink 名（逗号分隔，可留空）",
+      { defaultValue: "" },
     );
     cfg.agent!.dirLinks = linksRaw ? splitList(linksRaw) : [];
 
-    cfg.agent!.sandbox = await prompt.askYesNo("开启 Cursor 本地沙箱 (AGENT_SANDBOX)?", false);
-    cfg.cursor.model = await prompt.ask("Cursor 模型 id", "auto");
-    cfg.feishuDocsFolder = await prompt.ask("飞书文档默认 folder_token (可留空)", "");
+    cfg.agent!.sandbox = await prompt.askYesNoWithGuide(
+      INIT_FIELD_GUIDES.agentSandbox,
+      "开启本地沙箱？",
+      false,
+    );
+    cfg.cursor.model = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.cursorModel,
+      "模型 id",
+      { defaultValue: "auto" },
+    );
+    cfg.feishuDocsFolder = await prompt.askWithGuide(
+      INIT_FIELD_GUIDES.feishuDocsFolder,
+      "folder_token（可留空）",
+      { defaultValue: "" },
+    );
 
     writeConfigFile(outPath, cfg);
 
-    console.log(`\n已写入 ${outPath}`);
-    console.log(`下一步: cd ${targetDir} && sandy`);
+    console.log("\n✓ 已写入 " + outPath);
+    console.log("\n下一步:");
+    console.log(`  cd ${targetDir}`);
+    console.log("  sandy");
+    console.log("\n飞书后台若尚未配置长连接与权限，请按上文「飞书后台还需完成」逐项检查。");
   } finally {
     prompt.close();
   }

package/src/prompt.ts

@@ -1,9 +1,24 @@
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 
+export type GuideLink = {
+  label: string;
+  url: string;
+};
+
+export type FieldGuide = {
+  title: string;
+  lines: string[];
+  links?: GuideLink[];
+};
+
 export type Prompter = {
+  section: (title: string) => void;
+  guide: (guide: FieldGuide) => void;
   ask: (label: string, defaultValue?: string) => Promise<string>;
   askRequired: (label: string) => Promise<string>;
+  askWithGuide: (guide: FieldGuide, label: string, options?: { required?: boolean; defaultValue?: string }) => Promise<string>;
+  askYesNoWithGuide: (guide: FieldGuide, label: string, defaultValue?: boolean) => Promise<boolean>;
   askYesNo: (label: string, defaultValue?: boolean) => Promise<boolean>;
   close: () => void;
 };
@@ -11,10 +26,27 @@ export type Prompter = {
 export function createPrompter(): Prompter {
   const rl = readline.createInterface({ input, output });
 
+  function section(title: string): void {
+    console.log(`\n${title}`);
+    console.log("─".repeat(Math.min(title.length + 4, 60)));
+  }
+
+  function guide(g: FieldGuide): void {
+    console.log(`\n▸ ${g.title}`);
+    for (const line of g.lines) {
+      console.log(`  ${line}`);
+    }
+    if (g.links?.length) {
+      for (const link of g.links) {
+        console.log(`  → ${link.label}: ${link.url}`);
+      }
+    }
+  }
+
   async function ask(label: string, defaultValue?: string): Promise<string> {
     const hint =
       defaultValue !== undefined && defaultValue !== ""
-        ? ` (${defaultValue})`
+        ? ` [默认: ${defaultValue}]`
         : "";
     const answer = (await rl.question(`${label}${hint}: `)).trim();
     if (!answer && defaultValue !== undefined) return defaultValue;
@@ -25,8 +57,20 @@ export function createPrompter(): Prompter {
     while (true) {
       const answer = (await rl.question(`${label}: `)).trim();
       if (answer) return answer;
-      console.log("此项必填，请重新输入。");
+      console.log("  此项必填，请重新输入。");
+    }
+  }
+
+  async function askWithGuide(
+    g: FieldGuide,
+    label: string,
+    options?: { required?: boolean; defaultValue?: string },
+  ): Promise<string> {
+    guide(g);
+    if (options?.required) {
+      return askRequired(label);
     }
+    return ask(label, options?.defaultValue);
   }
 
   async function askYesNo(label: string, defaultValue = false): Promise<boolean> {
@@ -35,13 +79,26 @@ export function createPrompter(): Prompter {
     if (!answer) return defaultValue;
     if (["y", "yes", "是", "1", "true"].includes(answer)) return true;
     if (["n", "no", "否", "0", "false"].includes(answer)) return false;
-    console.log("请输入 y 或 n。");
+    console.log("  请输入 y 或 n。");
+    return askYesNo(label, defaultValue);
+  }
+
+  async function askYesNoWithGuide(
+    g: FieldGuide,
+    label: string,
+    defaultValue = false,
+  ): Promise<boolean> {
+    guide(g);
     return askYesNo(label, defaultValue);
   }
 
   return {
+    section,
+    guide,
     ask,
     askRequired,
+    askWithGuide,
+    askYesNoWithGuide,
     askYesNo,
     close: () => rl.close(),
   };

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 里，按需维护