@chenglu.she/sandy 1.0.1 → 1.0.2

package/README.md

@@ -8,7 +8,7 @@
 
 <p align="center"><b>Sandy</b> — 飞书长连接机器人。</p>
 
-通用脚手架：在任意项目目录放一份 `.env` +（可选）`.cursor/rules`，装好依赖后启动即可。
+通用脚手架：在工作目录放一份 `config.yaml` +（可选）`.cursor/rules`，装好依赖后启动即可。
 
 ## 需要什么
 
@@ -22,38 +22,40 @@
 
 `npm install -g @chenglu.she/sandy`
 
-### 2. 在「工作目录」准备 `.env`
+### 2. 初始化配置
 
-CLI **读取你启动时的 cwd** 下的 `.env`（不是包安装目录）。例如：
+在你要运行 bot 的目录执行（例如 `~/treedome`）：
 
 ```bash
 mkdir -p ~/treedome && cd ~/treedome
-cp "$(npm root -g)/@chenglu.she/sandy/.env.example" .env
+sandy init
 ```
 
-必填：
+会交互式询问飞书 / Cursor / Agent 等项，并写入当前目录的 `config.yaml`。也可参考 [config.yaml.example](./config.yaml.example) 手改。
 
-| 变量 | 说明 |
+必填项：
+
+| 配置项 | 说明 |
 |------|------|
-| `FEISHU_APP_ID` | 飞书应用 App ID |
-| `FEISHU_APP_SECRET` | 飞书应用 Secret |
-| `CURSOR_API_KEY` | Cursor API Key |
+| `feishu.appId` | 飞书应用 App ID |
+| `feishu.appSecret` | 飞书应用 Secret |
+| `cursor.apiKey` | 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` |
+| `agent.name` | `Sandy` | Agent 显示名 |
+| `agent.cwd` | 工作目录 | Agent 工作区（会加载这里的 `.cursor/rules`） |
+| `agent.dirs` | `[]` | 额外可访问目录 |
+| `agent.dirLinks` | `[]` | `agent.cwd` 下要一并放行的 symlink 名 |
+| `agent.sandbox` | `false` | `true` 时开 Cursor 本地沙箱 |
+| `cursor.model` | `auto` | 模型 id |
+| `feishuDocsFolder` | （空） | 创建飞书文档时的默认 Drive `folder_token` |
 
 ### 3. （推荐）放项目规则
 
-在 `AGENT_CWD`（默认就是 cwd）下：
+在 `agent.cwd`（默认就是运行目录）下：
 
 ```text
 .cursor/rules/your-persona.mdc
@@ -68,7 +70,7 @@ Agent 通过 `settingSources: ["project"]` 加载这些规则。人设、业务
 2. **权限**（开通后**发布新版本**才生效），至少：
    - 消息：获取与发送单聊/群消息、上传图片、上传文件、下载文件（如 `im:message`、`im:resource`）
    - 文档：读正文、创建文档、编辑文档（如 `docx:document:readonly`、`docx:document` / write）
-   - 若要把新建文档放到指定文件夹：Drive 文件夹相关权限，并填 `FEISHU_DOCS_FOLDER`
+   - 若要把新建文档放到指定文件夹：Drive 文件夹相关权限，并填 `feishuDocsFolder`
 3. **版本管理**：发布；可用范围包含你自己
 4. **事件与回调** → 订阅方式选 **长连接**（先让 bot 进程在线再保存）
 5. 事件：`im.message.receive_v1`
@@ -114,7 +116,7 @@ bash scripts/sandy-ctl.sh logs
 
 ```bash
 npm run dev        # tsx watch
-npm start          # 等同 feishu-cursor-bot（仍读 cwd .env）
+npm start          # 等同 sandy（读 cwd config.yaml）
 npm run typecheck
 ```
 

package/bin/feishu-cursor-bot.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * CLI entry: run from any directory; loads `.env` from cwd (see src/config.ts).
+ * CLI entry: run from any directory; loads `config.yaml` from cwd (see src/config-io.ts).
  *
  *   npx feishu-cursor-bot
  *   npm i -g . && feishu-cursor-bot
@@ -11,7 +11,7 @@ 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 entry = path.join(packageRoot, "src", "cli.ts");
 const require = createRequire(import.meta.url);
 
 let tsxCli;

package/config.yaml.example

@@ -0,0 +1,13 @@
+feishu:
+  appId: "cli_xxx"
+  appSecret: "xxx"
+cursor:
+  apiKey: "crsr_xxx"
+  model: "auto"
+agent:
+  name: "Sandy"
+  cwd: "."
+  dirs: []
+  dirLinks: []
+  sandbox: false
+feishuDocsFolder: ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenglu.she/sandy",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT",
   "type": "module",
   "description": "Feishu long-connection bot that drives Cursor agents via @cursor/sdk",
@@ -26,11 +26,11 @@
     "assets",
     "README.md",
     "LICENSE",
-    ".env.example"
+    "config.yaml.example"
   ],
   "scripts": {
-    "dev": "tsx watch src/index.ts",
-    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/cli.ts",
+    "start": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit"
   },
   "engines": {
@@ -39,8 +39,8 @@
   "dependencies": {
     "@cursor/sdk": "^1.0.0",
     "@larksuiteoapi/node-sdk": "^1.55.0",
-    "dotenv": "^16.6.1",
-    "tsx": "^4.20.3"
+    "tsx": "^4.20.3",
+    "yaml": "^2.8.1"
   },
   "devDependencies": {
     "@types/node": "^22.17.0",

package/src/cli.ts

@@ -0,0 +1,12 @@
+const subcommand = process.argv[2];
+
+if (subcommand === "init") {
+  const { runInit } = await import("./init.js");
+  await runInit(process.argv.slice(3));
+} 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`);
+} else {
+  await import("./index.js");
+}

package/src/config-io.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { SandyConfigFile } from "./config-schema.js";
+
+export const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+/** Workspace that owns `config.yaml` — usually where you run the CLI. */
+export const workDir = (() => {
+  const override = process.env.SANDY_CWD?.trim() || process.env.FEISHU_CURSOR_CWD?.trim();
+  if (!override) return process.cwd();
+  return expandPath(override, process.cwd());
+})();
+
+export function configFilePath(base = workDir): string {
+  const override = process.env.SANDY_CONFIG?.trim();
+  if (override) return expandPath(override, base);
+  return path.join(base, "config.yaml");
+}
+
+export 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);
+}
+
+export function readConfigFile(filePath: string): SandyConfigFile {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(
+      `Config not found: ${filePath}\nRun \`sandy init\` in ${workDir} to create config.yaml.`,
+    );
+  }
+  const raw = fs.readFileSync(filePath, "utf8");
+  const parsed = parseYaml(raw) as SandyConfigFile | null;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Invalid config.yaml: ${filePath}`);
+  }
+  return parsed;
+}
+
+export function writeConfigFile(filePath: string, data: SandyConfigFile): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const body = stringifyYaml(data, {
+    lineWidth: 0,
+    defaultStringType: "QUOTE_DOUBLE",
+  });
+  fs.writeFileSync(filePath, body.endsWith("\n") ? body : `${body}\n`, "utf8");
+}
+
+export function parseBool(raw: unknown, defaultValue: boolean): boolean {
+  if (raw === undefined || raw === null || raw === "") return defaultValue;
+  if (typeof raw === "boolean") return raw;
+  const v = String(raw).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(v)) return true;
+  if (["0", "false", "no", "off"].includes(v)) return false;
+  return defaultValue;
+}
+
+function requiredField(label: string, value: string | undefined, filePath: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    throw new Error(
+      `Missing required config: ${label} (set it in ${filePath}, or run \`sandy init\`)`,
+    );
+  }
+  return trimmed;
+}
+
+export function loadRuntimeConfig() {
+  const filePath = configFilePath();
+  const fileConfig = readConfigFile(filePath);
+  const agentSection = fileConfig.agent ?? {};
+  const agentCwdRaw = agentSection.cwd?.trim() || workDir;
+  const agentDirs = Array.isArray(agentSection.dirs)
+    ? [...new Set(agentSection.dirs.map((p) => expandPath(String(p), workDir)).filter(Boolean))]
+    : [];
+  const agentDirLinks = Array.isArray(agentSection.dirLinks)
+    ? [...new Set(agentSection.dirLinks.map((s) => String(s).trim()).filter(Boolean))]
+    : [];
+
+  return {
+    packageRoot,
+    workDir,
+    configPath: filePath,
+    feishuAppId: requiredField("feishu.appId", fileConfig.feishu?.appId, filePath),
+    feishuAppSecret: requiredField("feishu.appSecret", fileConfig.feishu?.appSecret, filePath),
+    cursorApiKey: requiredField("cursor.apiKey", fileConfig.cursor?.apiKey, filePath),
+    cursorModel: fileConfig.cursor?.model?.trim() || "auto",
+    agentName: agentSection.name?.trim() || "Sandy",
+    agentCwd: expandPath(String(agentCwdRaw), workDir),
+    agentDirs,
+    agentDirLinks,
+    agentSandbox: parseBool(agentSection.sandbox, false),
+    sessionStorePath: path.resolve(workDir, ".data", "sessions.json"),
+    pendingStorePath: path.resolve(workDir, ".data", "pending-questions.json"),
+    feishuDocsFolder: fileConfig.feishuDocsFolder?.trim() || "",
+    inboxDir: path.join(expandPath(String(agentCwdRaw), workDir), ".data", "feishu-inbox"),
+  };
+}
+
+export type RuntimeConfig = ReturnType<typeof loadRuntimeConfig>;

package/src/config-schema.ts

@@ -0,0 +1,34 @@
+/** On-disk config.yaml shape. */
+export type SandyConfigFile = {
+  feishu: {
+    appId: string;
+    appSecret: string;
+  };
+  cursor: {
+    apiKey: string;
+    model?: string;
+  };
+  agent?: {
+    name?: string;
+    cwd?: string;
+    dirs?: string[];
+    dirLinks?: string[];
+    sandbox?: boolean;
+  };
+  feishuDocsFolder?: string;
+};
+
+export function defaultConfigFile(workDir: string): SandyConfigFile {
+  return {
+    feishu: { appId: "", appSecret: "" },
+    cursor: { apiKey: "", model: "auto" },
+    agent: {
+      name: "Sandy",
+      cwd: workDir,
+      dirs: [],
+      dirLinks: [],
+      sandbox: false,
+    },
+    feishuDocsFolder: "",
+  };
+}

package/src/config.ts

@@ -1,93 +1,16 @@
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import dotenv from "dotenv";
+import type { RuntimeConfig } from "./config-io.js";
+import { loadRuntimeConfig } from "./config-io.js";
 
-const packageRoot = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-);
+export { expandPath, workDir } from "./config-io.js";
+export type { RuntimeConfig };
 
-/** 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 const config: RuntimeConfig = loadRuntimeConfig();
 
 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],
   };
 }

package/src/index.ts

@@ -298,6 +298,7 @@ async function handleCardAction(data: unknown) {
 
 async function main() {
   console.log("[boot] feishu-cursor-bot starting");
+  console.log(`[boot] config=${config.configPath}`);
   console.log(`[boot] agent cwd=${config.agentCwd}`);
   console.log(`[boot] agent dirs=${config.agentDirs.join(", ") || "(none)"}`);
   console.log(`[boot] sandbox=${config.agentSandbox}`);

package/src/init.ts

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  configFilePath,
+  expandPath,
+  workDir,
+  writeConfigFile,
+} from "./config-io.js";
+import { defaultConfigFile, type SandyConfigFile } from "./config-schema.js";
+import { createPrompter } from "./prompt.js";
+
+function parseArgs(argv: string[]): { targetDir: string } {
+  let targetDir = workDir;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--dir" || arg === "-C") {
+      const next = argv[i + 1];
+      if (!next) throw new Error(`${arg} requires a directory path`);
+      targetDir = expandPath(next, process.cwd());
+      i++;
+    } else if (arg === "--help" || arg === "-h") {
+      console.log(`Usage: sandy init [--dir <path>]
+
+Create config.yaml interactively in the target directory (default: current cwd).`);
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { targetDir };
+}
+
+function splitList(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export async function runInit(argv: string[] = []): Promise<void> {
+  const { targetDir } = parseArgs(argv);
+  const outPath = configFilePath(targetDir);
+  const prompt = createPrompter();
+
+  try {
+    console.log("Sandy 初始化 — 逐步生成 config.yaml\n");
+    console.log(`目标目录: ${targetDir}`);
+    console.log(`配置文件: ${outPath}\n`);
+
+    if (fs.existsSync(outPath)) {
+      const overwrite = await prompt.askYesNo("已存在 config.yaml，是否覆盖？", false);
+      if (!overwrite) {
+        console.log("已取消。");
+        return;
+      }
+    }
+
+    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");
+
+    console.log("\n【可选】Agent 与工作区");
+    cfg.agent!.name = await prompt.ask("Agent 显示名", "Sandy");
+    cfg.agent!.cwd = await prompt.ask("Agent 工作目录 (AGENT_CWD)", targetDir);
+
+    const dirsRaw = await prompt.ask("额外可访问目录，逗号分隔 (AGENT_DIRS，可留空)", "");
+    cfg.agent!.dirs = dirsRaw ? splitList(dirsRaw) : [];
+
+    const linksRaw = await prompt.ask(
+      "AGENT_CWD 下要放行的 symlink 名，逗号分隔 (可留空)",
+      "",
+    );
+    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 (可留空)", "");
+
+    writeConfigFile(outPath, cfg);
+
+    console.log(`\n已写入 ${outPath}`);
+    console.log(`下一步: cd ${targetDir} && sandy`);
+  } finally {
+    prompt.close();
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,48 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export type Prompter = {
+  ask: (label: string, defaultValue?: string) => Promise<string>;
+  askRequired: (label: string) => Promise<string>;
+  askYesNo: (label: string, defaultValue?: boolean) => Promise<boolean>;
+  close: () => void;
+};
+
+export function createPrompter(): Prompter {
+  const rl = readline.createInterface({ input, output });
+
+  async function ask(label: string, defaultValue?: string): Promise<string> {
+    const hint =
+      defaultValue !== undefined && defaultValue !== ""
+        ? ` (${defaultValue})`
+        : "";
+    const answer = (await rl.question(`${label}${hint}: `)).trim();
+    if (!answer && defaultValue !== undefined) return defaultValue;
+    return answer;
+  }
+
+  async function askRequired(label: string): Promise<string> {
+    while (true) {
+      const answer = (await rl.question(`${label}: `)).trim();
+      if (answer) return answer;
+      console.log("此项必填，请重新输入。");
+    }
+  }
+
+  async function askYesNo(label: string, defaultValue = false): Promise<boolean> {
+    const hint = defaultValue ? "Y/n" : "y/N";
+    const answer = (await rl.question(`${label} [${hint}]: `)).trim().toLowerCase();
+    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。");
+    return askYesNo(label, defaultValue);
+  }
+
+  return {
+    ask,
+    askRequired,
+    askYesNo,
+    close: () => rl.close(),
+  };
+}

package/.env.example

@@ -1,24 +0,0 @@
-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=