@chenglu.she/sandy 1.0.2 → 1.0.3

package/package.json

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

package/src/init-guides.ts

@@ -0,0 +1,132 @@
+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. 权限管理 → 开通消息 / 文件 / 文档等权限，并发布新版本",
+      "3. 事件与回调 → 订阅方式选「长连接」",
+      "   事件：im.message.receive_v1；回调：card.action.trigger",
+      "4. 先在本机运行 sandy，看到 ws client ready 后再在后台保存长连接配置",
+    ],
+    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(),
   };