@chenglu.she/sandy 1.0.1 → 1.0.3

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.3",
   "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-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

@@ -0,0 +1,136 @@
+import fs from "node:fs";
+import {
+  configFilePath,
+  expandPath,
+  workDir,
+  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 } {
+  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 初始化");
+    console.log("会逐步说明每项如何获取，并写入 config.yaml。\n");
+    console.log(`目标目录: ${targetDir}`);
+    console.log(`配置文件: ${outPath}`);
+
+    if (fs.existsSync(outPath)) {
+      const overwrite = await prompt.askYesNo("\n已存在 config.yaml，是否覆盖？", false);
+      if (!overwrite) {
+        console.log("已取消。");
+        return;
+      }
+    }
+
+    const cfg: SandyConfigFile = defaultConfigFile(targetDir);
+
+    prompt.section("一、飞书应用");
+    prompt.guide(INIT_FIELD_GUIDES.feishuAppHome);
+
+    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.askWithGuide(
+      INIT_FIELD_GUIDES.agentDirs,
+      "额外目录（逗号分隔，可留空）",
+      { defaultValue: "" },
+    );
+    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,
+      "开启本地沙箱？",
+      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("\n下一步:");
+    console.log(`  cd ${targetDir}`);
+    console.log("  sandy");
+    console.log("\n飞书后台若尚未配置长连接与权限，请按上文「飞书后台还需完成」逐项检查。");
+  } finally {
+    prompt.close();
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,105 @@
+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;
+};
+
+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}]`
+        : "";
+    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 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> {
+    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);
+  }
+
+  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/.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=