agent-loft 0.0.0-stage → 0.2.8

package/src/cli/passwd.ts

@@ -0,0 +1,15 @@
+// agent-loft passwd：在终端里重置 Web 登录密码（忘记密码时用）。所有已登录设备会下线。
+import readline from "node:readline/promises";
+import { loadConfig } from "../core/config.js";
+import { setPassword } from "../channels/web/auth.js";
+
+loadConfig();
+const fromArg = process.argv[2];
+let password = fromArg;
+if (!password) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  password = await rl.question("新的 Web 登录密码（至少 8 位）：");
+  rl.close();
+}
+setPassword(password.trim());
+console.log("密码已更新，所有已登录的设备需要重新登录。");

package/src/cli/service.ts

@@ -0,0 +1,137 @@
+// agent-loft service install | uninstall | restart | status
+//
+// Linux 用 systemd 用户服务，macOS 用 launchd。只碰服务定义文件，不碰 ~/.agent-loft 里的配置和会话。
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { home, logsDir } from "../home.js";
+
+const UNIT = "agent-loft";
+const LABEL = "com.agent-loft";
+/** 改名前的服务名。装新服务时顺手卸掉，免得新旧两个进程抢同一个飞书机器人的消息 */
+const LEGACY_UNIT = "im-agent";
+const LEGACY_LABEL = "com.im-agent";
+const entry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/cli.js");
+
+function unitPath(): string {
+  return process.platform === "darwin"
+    ? path.join(os.homedir(), "Library/LaunchAgents", `${LABEL}.plist`)
+    : path.join(os.homedir(), ".config/systemd/user", `${UNIT}.service`);
+}
+
+/** systemd 下 PATH 很短：把 node、claude、codex 所在目录都带上 */
+function servicePath(): string {
+  const dirs = new Set<string>([path.dirname(process.execPath)]);
+  for (const bin of ["claude", "codex"]) {
+    const found = spawnSync("sh", ["-c", `command -v ${bin}`], { encoding: "utf8" }).stdout.trim();
+    if (found) dirs.add(path.dirname(found));
+  }
+  for (const d of (process.env.PATH ?? "").split(":")) if (d) dirs.add(d);
+  return [...dirs].join(":");
+}
+
+function systemdUnit(): string {
+  return `[Unit]
+Description=agent-loft（飞书 / Web ↔ Claude Code / Codex）
+After=network-online.target
+# 默认「10 秒内重启 5 次就永久放弃」，那正是崩溃循环最需要它别放弃的时候
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+ExecStart=${process.execPath} ${entry} start
+WorkingDirectory=${home}
+StandardOutput=append:${path.join(logsDir, "out.log")}
+StandardError=append:${path.join(logsDir, "err.log")}
+Environment=PATH=${servicePath()}
+Environment=AGENT_LOFT_HOME=${home}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function plist(): string {
+  const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array><string>${esc(process.execPath)}</string><string>${esc(entry)}</string><string>start</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>WorkingDirectory</key><string>${esc(home)}</string>
+  <key>StandardOutPath</key><string>${esc(path.join(logsDir, "out.log"))}</string>
+  <key>StandardErrorPath</key><string>${esc(path.join(logsDir, "err.log"))}</string>
+  <key>EnvironmentVariables</key><dict>
+    <key>PATH</key><string>${esc(servicePath())}</string>
+    <key>AGENT_LOFT_HOME</key><string>${esc(home)}</string>
+  </dict>
+</dict></plist>
+`;
+}
+
+function removeLegacyService(): void {
+  if (process.platform === "darwin") {
+    const file = path.join(os.homedir(), "Library/LaunchAgents", `${LEGACY_LABEL}.plist`);
+    if (!fs.existsSync(file)) return;
+    spawnSync("launchctl", ["bootout", `gui/${process.getuid?.() ?? 0}/${LEGACY_LABEL}`]);
+    fs.rmSync(file, { force: true });
+  } else {
+    const file = path.join(os.homedir(), ".config/systemd/user", `${LEGACY_UNIT}.service`);
+    if (!fs.existsSync(file)) return;
+    spawnSync("systemctl", ["--user", "disable", "--now", LEGACY_UNIT], { stdio: "inherit" });
+    fs.rmSync(file, { force: true });
+  }
+  console.log(`已停用并移除旧的 ${LEGACY_UNIT} 服务（配置目录不动）`);
+}
+
+function run(cmd: string, args: string[]): void {
+  execFileSync(cmd, args, { stdio: "inherit" });
+}
+
+const sub = process.argv[2] ?? "status";
+fs.mkdirSync(logsDir, { recursive: true });
+
+if (process.platform === "darwin") {
+  const uid = process.getuid?.() ?? 0;
+  if (sub === "install") {
+    removeLegacyService();
+    fs.mkdirSync(path.dirname(unitPath()), { recursive: true });
+    fs.writeFileSync(unitPath(), plist());
+    spawnSync("launchctl", ["bootout", `gui/${uid}/${LABEL}`]);
+    run("launchctl", ["bootstrap", `gui/${uid}`, unitPath()]);
+    console.log(`已安装并启动。日志：${logsDir}`);
+  } else if (sub === "uninstall") {
+    spawnSync("launchctl", ["bootout", `gui/${uid}/${LABEL}`]);
+    fs.rmSync(unitPath(), { force: true });
+    console.log("已卸载");
+  } else if (sub === "restart") {
+    run("launchctl", ["kickstart", "-k", `gui/${uid}/${LABEL}`]);
+  } else {
+    spawnSync("launchctl", ["print", `gui/${uid}/${LABEL}`], { stdio: "inherit" });
+  }
+} else {
+  if (sub === "install") {
+    removeLegacyService();
+    fs.mkdirSync(path.dirname(unitPath()), { recursive: true });
+    fs.writeFileSync(unitPath(), systemdUnit());
+    run("systemctl", ["--user", "daemon-reload"]);
+    run("systemctl", ["--user", "enable", "--now", UNIT]);
+    console.log(`已安装并启动。日志：${logsDir}`);
+    console.log("想在没登录时也运行：sudo loginctl enable-linger $USER");
+  } else if (sub === "uninstall") {
+    spawnSync("systemctl", ["--user", "disable", "--now", UNIT], { stdio: "inherit" });
+    fs.rmSync(unitPath(), { force: true });
+    run("systemctl", ["--user", "daemon-reload"]);
+    console.log("已卸载");
+  } else if (sub === "restart") {
+    run("systemctl", ["--user", "restart", UNIT]);
+  } else {
+    spawnSync("systemctl", ["--user", "status", UNIT, "--no-pager"], { stdio: "inherit" });
+  }
+}

package/src/core/agent-env.ts

@@ -0,0 +1,11 @@
+/**
+ * 交给 agent 子进程的环境变量。
+ *
+ * agent 可能会跑用户项目里的脚本，那些脚本也可能读 FEISHU_APP_ID 之类的变量 ——
+ * 我们自己的凭据不能漏进去。复制而不是改 process.env：本进程还要用它们。
+ */
+export function agentEnvironment(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return Object.fromEntries(
+    Object.entries(source).filter(([name]) => !/^(FEISHU_|LARK_|BRIDGE_|AGENT_LOFT_|IM_AGENT_|TELEGRAM_)/i.test(name)),
+  );
+}

package/src/core/command-catalog.ts

@@ -0,0 +1,112 @@
+// 命令目录：输入「/」时给用户看的那张表。
+//
+// 两种来源：
+//   - agent-loft 自己的命令（/new /status …），由 hub 拦下来执行，所有 agent 通用；
+//   - agent 原生命令（Claude 的 skills、/compact 之类），agent-loft 不认识，原样转给 agent。
+// 顺序和隐藏按 agent 分开存在配置里（设置 → 命令），用户自己排。
+
+/** agent-loft 内置命令。name 不带斜杠；args 里尖括号是必填、方括号是可选 */
+export type BuiltinSpec = { name: string; args?: string; description: string; multiAgentOnly?: boolean };
+
+export const BUILTIN_COMMANDS: BuiltinSpec[] = [
+  { name: "new", args: "[模型]", description: "开一条新会话" },
+  { name: "status", description: "查看当前会话、模型、目录、剩余额度" },
+  { name: "stop", description: "中断当前执行" },
+  { name: "model", args: "[名称]", description: "切换模型（不带参数弹选择）" },
+  { name: "effort", args: "[程度]", description: "切换思考程度" },
+  { name: "sessions", args: "[all]", description: "列出历史会话，点按钮恢复；加 all 列所有目录" },
+  { name: "resume", args: "<会话ID>", description: "恢复指定会话" },
+  { name: "fork", description: "从当前会话分叉，原会话保留" },
+  { name: "agent", args: "[名称]", description: "查看 / 切换 agent", multiAgentOnly: true },
+  { name: "claude", description: "切换到 Claude Code", multiAgentOnly: true },
+  { name: "codex", description: "切换到 Codex", multiAgentOnly: true },
+  { name: "cd", args: "<相对目录>", description: "切换工作目录（限 workspace 内）" },
+  { name: "pwd", description: "显示当前工作目录" },
+  { name: "autoedit", args: "[on|off]", description: "本对话自动允许改工作目录内的文件（Bash 仍询问）" },
+  { name: "approve", args: "<请求ID> allow-once|allow-always|allow-session|deny", description: "审批兜底（卡片失效时用）" },
+  { name: "help", description: "显示帮助" },
+];
+
+/** agent 自己报上来的命令 */
+export type AgentCommand = { name: string; description: string; args?: string };
+
+export type CommandEntry = {
+  name: string;
+  args?: string;
+  description: string;
+  source: "agent-loft" | "agent";
+  /** 不带参数就能直接执行（飞书卡片上给按钮、Web 里回车直接发） */
+  runnable: boolean;
+  hidden: boolean;
+};
+
+export type CommandPrefs = { order: string[]; hidden: string[] };
+
+/** 参数里有必填项（尖括号）就不能一键执行 */
+function needsArgs(args: string | undefined): boolean {
+  return !!args && args.includes("<");
+}
+
+/**
+ * 合并内置命令和 agent 原生命令，再按用户配置排序。
+ * - 只对接得上的 agent 才列 /claude /codex 这类快捷切换；
+ * - 和内置命令重名的原生命令丢掉：反正会被 agent-loft 先拦下来，列出来只会误导；
+ * - 配置里排过序的在前，按配置的顺序；没排过的（比如新装的 skill）按默认顺序接在后面。
+ */
+export function buildCatalog(params: {
+  allowedAgents: string[];
+  native: AgentCommand[];
+  prefs: CommandPrefs | undefined;
+}): CommandEntry[] {
+  const multi = params.allowedAgents.length > 1;
+  const builtin: CommandEntry[] = BUILTIN_COMMANDS.filter(
+    (c) =>
+      (!c.multiAgentOnly || multi) &&
+      // /claude /codex 只在这个渠道能用对应 agent 时才有意义
+      (!["claude", "codex"].includes(c.name) || params.allowedAgents.includes(c.name)),
+  ).map((c) => ({
+    name: c.name,
+    ...(c.args ? { args: c.args } : {}),
+    description: c.description,
+    source: "agent-loft" as const,
+    runnable: !needsArgs(c.args),
+    hidden: false,
+  }));
+  const taken = new Set(BUILTIN_COMMANDS.map((c) => c.name));
+  const seen = new Set<string>();
+  const native: CommandEntry[] = [];
+  for (const c of params.native) {
+    const name = c.name.replace(/^\//, "");
+    if (!name || taken.has(name) || seen.has(name)) continue;
+    seen.add(name);
+    native.push({
+      name,
+      ...(c.args ? { args: c.args } : {}),
+      description: c.description,
+      source: "agent",
+      runnable: !needsArgs(c.args),
+      hidden: false,
+    });
+  }
+
+  const all = [...builtin, ...native];
+  const order = params.prefs?.order ?? [];
+  const hidden = new Set(params.prefs?.hidden ?? []);
+  const rank = new Map(order.map((name, i) => [name, i]));
+  return all
+    .map((c, i) => ({ c, i }))
+    .sort((a, b) => {
+      const ra = rank.get(a.c.name);
+      const rb = rank.get(b.c.name);
+      if (ra !== undefined && rb !== undefined) return ra - rb;
+      if (ra !== undefined) return -1;
+      if (rb !== undefined) return 1;
+      return a.i - b.i;
+    })
+    .map(({ c }) => ({ ...c, hidden: hidden.has(c.name) }));
+}
+
+/** 「/name args」，给人看的写法 */
+export function usageOf(c: { name: string; args?: string }): string {
+  return `/${c.name}${c.args ? ` ${c.args}` : ""}`;
+}

package/src/core/commands.ts

@@ -0,0 +1,104 @@
+// 斜杠命令解析（各渠道通用）。
+//
+// 只有「整条消息就是一个命令」时才当命令处理，参数对不上就退化成普通聊天 ——
+// 避免把正常对话误当指令执行。
+import { BUILTIN_COMMANDS, usageOf } from "./command-catalog.js";
+import type { ApprovalDecision } from "./types.js";
+
+export type ParsedCommand =
+  | { kind: "new"; model?: string }
+  | { kind: "fork" }
+  | { kind: "resume"; sessionId: string }
+  | { kind: "sessions"; all: boolean }
+  | { kind: "model"; model?: string }
+  | { kind: "effort"; effort?: string }
+  | { kind: "agent"; agent?: string }
+  | { kind: "stop" }
+  | { kind: "cd"; dir: string }
+  | { kind: "status" }
+  | { kind: "pwd" }
+  | { kind: "autoedit"; on?: boolean }
+  | { kind: "help" }
+  /** 只发了一个「/」：列出可用命令 */
+  | { kind: "commands" }
+  | { kind: "approve"; requestId: string; decision: ApprovalDecision }
+  | { kind: "chat"; text: string };
+
+const DECISIONS: ApprovalDecision[] = ["allow-once", "allow-always", "allow-session", "deny"];
+
+export function parseCommand(raw: string): ParsedCommand {
+  const text = raw.trim();
+  // 全角斜杠也认：中文输入法下很容易打成「／」
+  if (text === "/" || text === "／") return { kind: "commands" };
+  if (!text.startsWith("/") || text.includes("\n")) return { kind: "chat", text };
+
+  const [head = "", ...rest] = text.slice(1).split(/\s+/);
+  const arg = rest.join(" ").trim();
+
+  switch (head.toLowerCase()) {
+    case "new":
+      return { kind: "new", ...(arg ? { model: arg } : {}) };
+    case "fork":
+      return { kind: "fork" };
+    case "resume":
+      return arg ? { kind: "resume", sessionId: arg } : { kind: "chat", text };
+    case "sessions":
+      return { kind: "sessions", all: arg === "all" || arg === "-a" };
+    case "model":
+      return { kind: "model", ...(arg ? { model: arg } : {}) };
+    case "effort":
+      return { kind: "effort", ...(arg ? { effort: arg } : {}) };
+    case "agent":
+      return { kind: "agent", ...(arg ? { agent: arg.toLowerCase() } : {}) };
+    // 快捷切换
+    case "claude":
+    case "codex":
+      return arg ? { kind: "chat", text } : { kind: "agent", agent: head.toLowerCase() };
+    case "stop":
+      return { kind: "stop" };
+    case "cd":
+      return arg ? { kind: "cd", dir: arg } : { kind: "chat", text };
+    case "status":
+      return { kind: "status" };
+    case "pwd":
+      return { kind: "pwd" };
+    case "autoedit": {
+      const v = arg.toLowerCase();
+      if (!v) return { kind: "autoedit" };
+      if (["on", "开", "1", "true"].includes(v)) return { kind: "autoedit", on: true };
+      if (["off", "关", "0", "false"].includes(v)) return { kind: "autoedit", on: false };
+      return { kind: "chat", text };
+    }
+    case "help":
+      return { kind: "help" };
+    case "approve": {
+      const [requestId, decision] = rest;
+      if (!requestId || !decision) return { kind: "chat", text };
+      const normalized = decision.toLowerCase() as ApprovalDecision;
+      if (!DECISIONS.includes(normalized)) return { kind: "chat", text };
+      return { kind: "approve", requestId, decision: normalized };
+    }
+    default:
+      // 不认识的命令原样交给 agent：Claude / Codex 自己也有斜杠命令
+      return { kind: "chat", text };
+  }
+}
+
+export function helpText(agents: string[]): string {
+  const multi = agents.length > 1;
+  return [
+    "直接说话即可，会自动接着上次的会话。闲置太久会自动开新会话。",
+    "",
+    "Agent 给选项时会发一张提问卡，点按钮作答；都不合适就直接发消息，那条消息会被当成你的回答。",
+    "",
+    "**命令**（需整条消息只有命令；只发一个 `/` 可以列出全部命令，包括 agent 自己的）",
+    "",
+    ...BUILTIN_COMMANDS.filter((c) => !c.multiAgentOnly || multi)
+      .filter((c) => !["claude", "codex"].includes(c.name))
+      .map((c) =>
+        c.name === "agent"
+          ? `\`${usageOf(c)}\` ${c.description}（可选：${agents.join("、")}），也可以直接发 ${agents.map((a) => `\`/${a}\``).join(" ")}`
+          : `\`${usageOf(c)}\` ${c.description}`,
+      ),
+  ].join("\n");
+}

package/src/core/config.ts

@@ -0,0 +1,285 @@
+// 配置：一个 JSON 文件，由 Web 设置页读写，也可以手改。
+//
+// 和旧桥接器的 .env 不同，这里的配置在运行中会变（Web 上改完立即生效），
+// 所以对外是「读当前值 + 订阅变化」，而不是一个启动时冻结的常量。
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { configPath, ensureDirs, readJson, writeJsonAtomic } from "../home.js";
+import type { CommandPrefs } from "./command-catalog.js";
+
+
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+
+export type FeishuBotConfig = {
+  /** 内部 id，会话键里会用到，创建后不要改 */
+  id: string;
+  name: string;
+  enabled: boolean;
+  appId: string;
+  appSecret: string;
+  domain: "feishu" | "lark";
+  /** owner 白名单（open_id）。配对批准的人另存在 data/pairing-<id>.json */
+  allowFrom: string[];
+  /** 这个机器人能用哪些 agent。只有一个就是「一个机器人一个 agent」 */
+  agents: string[];
+  /** 新会话默认用哪个 agent，必须在 agents 里 */
+  defaultAgent: string;
+};
+
+export type AppConfig = {
+  /** 所有会话的默认工作目录；/cd 只能在它之内 */
+  workspaceRoot: string;
+  approvalTimeoutMs: number;
+  sessionTtlMs: number;
+  agents: {
+    claude: {
+      enabled: boolean;
+      defaultModel: string;
+      defaultEffort: string;
+      /** 输入框模型列表里显示哪些（模型 id），空 = 全部显示 */
+      models: string[];
+    };
+    codex: {
+      enabled: boolean;
+      /** codex 可执行文件，systemd 下 PATH 很短，最好写绝对路径 */
+      path: string;
+      /** 留空用 ~/.codex */
+      home: string;
+      sandbox: SandboxMode;
+      defaultModel: string;
+      defaultEffort: string;
+      /** 同 claude.models */
+      models: string[];
+    };
+  };
+  web: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    /** scrypt 哈希，空 = 还没设密码（首次访问需要终端里打印的设置码） */
+    passwordHash: string;
+    /**
+     * 可信反向代理的 IP。只有从这些地址来的连接，才采信 X-Forwarded-* 头 ——
+     * 否则直连的人随手伪造一个 X-Forwarded-For 就能绕过登录限流。
+     * 反代（比如 Lucky）不在本机时，把它的 IP 加进来。
+     */
+    trustedProxies: string[];
+    /** 侧栏额度空闲时多久自动刷新一次（分钟），0 = 不自动刷新 */
+    quotaRefreshMin: number;
+  };
+  /** 输入「/」时命令列表的顺序和隐藏项，按 agent 分开（设置 → 命令） */
+  commands: { claude: CommandPrefs; codex: CommandPrefs };
+  feishu: {
+    /** 长连接掉线多久就重建，0 关闭 */
+    watchdogMs: number;
+    bots: FeishuBotConfig[];
+  };
+};
+
+export const AGENT_IDS = ["claude", "codex"] as const;
+
+export function defaultConfig(): AppConfig {
+  return {
+    workspaceRoot: process.env.HOME ? path.join(process.env.HOME, "project") : process.cwd(),
+    approvalTimeoutMs: 30 * 60 * 1000,
+    sessionTtlMs: 12 * 60 * 60 * 1000,
+    agents: {
+      claude: { enabled: true, defaultModel: "", defaultEffort: "", models: [] },
+      codex: {
+        enabled: true,
+        path: "codex",
+        home: "",
+        sandbox: "workspace-write",
+        defaultModel: "",
+        defaultEffort: "",
+        models: [],
+      },
+    },
+    web: { enabled: true, host: "0.0.0.0", port: 8800, passwordHash: "", trustedProxies: ["127.0.0.1", "::1"], quotaRefreshMin: 10 },
+    commands: { claude: { order: [], hidden: [] }, codex: { order: [], hidden: [] } },
+    feishu: { watchdogMs: 10 * 60 * 1000, bots: [] },
+  };
+}
+
+/** 递归补齐缺省字段：老配置文件缺新字段时不至于整个崩掉。 */
+function mergeDefaults<T>(base: T, value: unknown): T {
+  if (Array.isArray(base)) return (Array.isArray(value) ? value : base) as T;
+  if (typeof base !== "object" || base === null) {
+    return (value === undefined || value === null || typeof value !== typeof base ? base : value) as T;
+  }
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  const v = (typeof value === "object" && value !== null ? value : {}) as Record<string, unknown>;
+  for (const key of Object.keys(out)) out[key] = mergeDefaults(out[key], v[key]);
+  return out as T;
+}
+
+function normalizeBot(raw: Partial<FeishuBotConfig>): FeishuBotConfig {
+  const agents = (raw.agents ?? []).filter((a) => (AGENT_IDS as readonly string[]).includes(a));
+  const list = agents.length > 0 ? agents : ["claude"];
+  return {
+    id: raw.id?.trim() || `bot_${crypto.randomBytes(3).toString("hex")}`,
+    name: raw.name?.trim() || "飞书机器人",
+    enabled: raw.enabled !== false,
+    appId: raw.appId?.trim() ?? "",
+    appSecret: raw.appSecret?.trim() ?? "",
+    domain: raw.domain === "lark" ? "lark" : "feishu",
+    allowFrom: (raw.allowFrom ?? [])
+      .map((s) => s.trim().toLowerCase())
+      .filter((s) => s.startsWith("ou_")),
+    agents: list,
+    defaultAgent: raw.defaultAgent && list.includes(raw.defaultAgent) ? raw.defaultAgent : list[0]!,
+  };
+}
+
+let current: AppConfig | null = null;
+const listeners = new Set<(next: AppConfig, prev: AppConfig) => void>();
+
+export function loadConfig(): AppConfig {
+  if (current) return current;
+  ensureDirs();
+  const raw = readJson<unknown>(configPath, null);
+  const merged = mergeDefaults(defaultConfig(), raw);
+  merged.workspaceRoot = path.resolve(merged.workspaceRoot);
+  merged.feishu.bots = merged.feishu.bots.map(normalizeBot);
+  current = merged;
+  if (!raw) writeJsonAtomic(configPath, merged);
+  watchExternalEdits();
+  return current;
+}
+
+/**
+ * 配置文件被别的进程改了（手改、或终端里跑了 agent-loft passwd）：重新读进来。
+ * 自己保存触发的变更内容一致，比较后直接跳过。
+ */
+let watching = false;
+function watchExternalEdits(): void {
+  if (watching) return;
+  watching = true;
+  let timer: NodeJS.Timeout | null = null;
+  try {
+    fs.watch(path.dirname(configPath), { persistent: false }, (_event, file) => {
+      if (file !== path.basename(configPath)) return;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        const raw = readJson<unknown>(configPath, null);
+        if (!raw || !current) return;
+        const next = mergeDefaults(defaultConfig(), raw);
+        next.workspaceRoot = path.resolve(next.workspaceRoot);
+        next.feishu.bots = next.feishu.bots.map(normalizeBot);
+        if (JSON.stringify(next) === JSON.stringify(current)) return;
+        const prev = current;
+        current = next;
+        console.log("[配置] 检测到配置文件被修改，已重新加载");
+        for (const listener of listeners) {
+          try {
+            listener(next, prev);
+          } catch (err) {
+            console.error("[配置] 变更回调出错:", err);
+          }
+        }
+      }, 200);
+    });
+  } catch {
+    // 监听不了就算了，重启后生效
+  }
+}
+
+/** 当前配置。别缓存返回值里的子对象：保存后整个对象会被换掉。 */
+export function config(): AppConfig {
+  return current ?? loadConfig();
+}
+
+export function saveConfig(next: AppConfig): AppConfig {
+  const prev = config();
+  const normalized = mergeDefaults(defaultConfig(), next);
+  normalized.workspaceRoot = path.resolve(normalized.workspaceRoot);
+  normalized.feishu.bots = normalized.feishu.bots.map(normalizeBot);
+  writeJsonAtomic(configPath, normalized);
+  current = normalized;
+  for (const listener of listeners) {
+    try {
+      listener(normalized, prev);
+    } catch (err) {
+      console.error("[配置] 变更回调出错:", err);
+    }
+  }
+  return normalized;
+}
+
+export function onConfigChange(listener: (next: AppConfig, prev: AppConfig) => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function inside(root: string, target: string): boolean {
+  const rel = path.relative(root, target);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/**
+ * 把用户给的目录限制在 workspaceRoot 之内，防止 /cd 跳到任意路径。
+ *
+ * 必须比较真实路径：工作区里一个指向外面的符号链接，字符串上在里面，实际在外面。
+ * 目标还必须存在且是目录 —— 不存在的目录拉不起 agent。
+ */
+export function resolveWorkspacePath(input: string, base?: string): string | null {
+  const root = config().workspaceRoot;
+  const target = path.resolve(base ?? root, input);
+  if (!inside(root, target)) return null;
+  try {
+    const realRoot = fs.realpathSync(root);
+    const realTarget = fs.realpathSync(target);
+    if (!inside(realRoot, realTarget) || !fs.statSync(realTarget).isDirectory()) return null;
+    // 用工作区根目录的写法返回：根目录本身是符号链接时，存下来的路径仍然落在根目录之内
+    return path.join(root, path.relative(realRoot, realTarget));
+  } catch {
+    return null;
+  }
+}
+
+export type WorkspaceDirListing = {
+  root: string;
+  /** 绝对路径（工作区根目录的写法） */
+  path: string;
+  /** 相对工作区根目录，根目录本身是 "" */
+  rel: string;
+  dirs: { name: string; hidden: boolean }[];
+  /** 子目录太多，只列了前一部分 */
+  truncated: boolean;
+};
+
+const MAX_LISTED_DIRS = 500;
+
+/**
+ * 列出工作区内某个目录下的子目录，给 Web 的目录选择器用。只列目录不列文件；
+ * 指向工作区外面（或已经失效）的符号链接不列 —— 列出来也 /cd 不进去。
+ */
+export function listWorkspaceDirs(input: string): WorkspaceDirListing | null {
+  const root = config().workspaceRoot;
+  const resolved = resolveWorkspacePath(input || ".");
+  if (!resolved) return null;
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(resolved, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const dirs: { name: string; hidden: boolean }[] = [];
+  for (const entry of entries) {
+    const ok = entry.isDirectory() || (entry.isSymbolicLink() && resolveWorkspacePath(path.join(resolved, entry.name)) !== null);
+    if (ok) dirs.push({ name: entry.name, hidden: entry.name.startsWith(".") });
+  }
+  dirs.sort((a, b) => Number(a.hidden) - Number(b.hidden) || a.name.localeCompare(b.name));
+  return {
+    root,
+    path: resolved,
+    rel: path.relative(root, resolved),
+    dirs: dirs.slice(0, MAX_LISTED_DIRS),
+    truncated: dirs.length > MAX_LISTED_DIRS,
+  };
+}
+
+export function isInsideWorkspace(dir: string): boolean {
+  return resolveWorkspacePath(dir) === path.resolve(dir);
+}

package/src/core/dedup.ts

@@ -0,0 +1,16 @@
+// 事件去重。IM 平台对消息和回调都可能重投，不挡住就会重复执行：
+// 消息重投 = 同一句话跑两遍；回调重投 = 第一次消费掉待处理项，第二次误报「已失效」。
+export class Dedup {
+  private seen = new Set<string>();
+  constructor(private readonly max = 2000) {}
+
+  isDuplicate(id: string | undefined): boolean {
+    if (!id) return false;
+    if (this.seen.has(id)) return true;
+    this.seen.add(id);
+    if (this.seen.size > this.max) {
+      for (const key of [...this.seen].slice(0, this.max / 2)) this.seen.delete(key);
+    }
+    return false;
+  }
+}