agent-loft 0.2.13 → 0.2.15

package/README.md

@@ -49,6 +49,20 @@ agent-loft service install        # 注册为开机自启服务（systemd / laun
 
 打开 `http://<机器 IP>:8800`：第一次需要输入日志里的设置码，然后设一个登录密码。
 
+设置 → 通用 里能看到服务端版本，有新版本时点「升级」即可（`npm install -g agent-loft@latest`，以系统服务运行时会自动重启）；设置 → Agent 里能检查 Claude Code、Codex 装好、登录了没有，Codex 可以一键装到服务端上。
+
+### macOS 桌面端
+
+到 [Releases](https://github.com/qijieinnet/agent-loft/releases) 下载 `desktop-v*` 里对应芯片的 DMG（Apple 芯片选 arm64，Intel 选 x64），拖进「应用程序」。还没有 Apple 开发者签名，第一次打开如果提示无法验证，到 系统设置 → 隐私与安全性 里点「仍要打开」。
+
+- 同时连多台服务器，左边一栏切换；每台各自登录，切走了也在后台连着，回复完成、需要授权时弹系统通知。
+- 菜单栏图标：悬停看各服务器的 Claude / Codex 额度、待处理和运行中的会话。
+- 支持前面挡着 Cloudflare Access 的服务器：验证页直接在窗口里完成，过期会提醒；也可以配 Service Token 免验证。
+- 首次打开可以选「这台 Mac 也作为服务端」：一键在终端里安装 agent-loft（没有 Node.js 会先用 Homebrew 装）并开机自启，装好自动连上。
+- 服务端有新版本时在服务器列表里点「升级服务端」；桌面端自己的更新在 设置 → 更新 里点「更新并重启」。
+
+桌面端只是个壳（代码在 `desktop/`），服务端照常用 npm 安装和升级。
+
 ### 从旧桥接器迁移
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-loft",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "type": "module",
   "description": "多个 agent 的工作台：把本机 Claude Code / Codex 放到一处统一管理，用飞书和 Web 页面随时驱动——会话、审批、模型切换都共用",
   "keywords": [

package/src/agents/health.ts

@@ -0,0 +1,169 @@
+// Agent 环境体检：装没装、登没登录、怎么修。给 Web 设置页和桌面端的「Agent 环境」用。
+//
+// 修复办法只给命令（给人看、给人复制），这里不替人执行：安装要联网、登录要在浏览器里点，
+// 都得在用户眼皮底下的终端里做。
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { agentEnvironment } from "../core/agent-env.js";
+import { config } from "../core/config.js";
+import { withProbe } from "./claude/probe.js";
+
+const require = createRequire(import.meta.url);
+
+export type AgentFix = {
+  action: "install" | "login";
+  title: string;
+  /** 每一条是一种做法，任选其一（比如 Homebrew 和 npm 两种装法） */
+  commands: string[];
+  note?: string;
+};
+
+export type AgentHealth = {
+  id: "claude" | "codex";
+  label: string;
+  enabled: boolean;
+  installed: boolean;
+  version?: string;
+  /** null：判断不了（探测出错、超时） */
+  loggedIn: boolean | null;
+  account?: string;
+  problem?: string;
+  fix?: AgentFix;
+};
+
+function run(cmd: string, args: string[], timeoutMs: number, env?: NodeJS.ProcessEnv): Promise<{ code: number; out: string }> {
+  return new Promise((resolve) => {
+    let out = "";
+    let child;
+    try {
+      child = spawn(cmd, args, { env: agentEnvironment(env ?? process.env), stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      resolve({ code: -1, out: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (out += d));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: -1, out: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? -1, out: out.trim() });
+    });
+  });
+}
+
+function timeout<T>(ms: number, what: string): Promise<T> {
+  return new Promise((_, reject) => setTimeout(() => reject(new Error(`${what}超时`)), ms).unref());
+}
+
+function quote(p: string): string {
+  return /^[\w./-]+$/.test(p) ? p : `"${p.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+
+/** 登录用哪个 claude：系统里装了 Claude Code 就用它，否则用 SDK 自带的那份（同一个程序） */
+export function claudeBinary(): string {
+  if (spawnSync("sh", ["-c", "command -v claude"], { encoding: "utf8" }).stdout.trim()) return "claude";
+  try {
+    const pkg = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}/package.json`;
+    return path.join(path.dirname(require.resolve(pkg)), "claude");
+  } catch {
+    return "claude";
+  }
+}
+
+async function claudeHealth(): Promise<AgentHealth> {
+  const base = { id: "claude" as const, label: "Claude Code", enabled: config().agents.claude.enabled, installed: true };
+  const loginFix: AgentFix = {
+    action: "login",
+    title: "登录 Claude",
+    commands: [quote(claudeBinary())],
+    note: "打开后输入 /login，按提示在浏览器里登录，完成后输入 /exit。用 API Key 的话，把 ANTHROPIC_API_KEY 写进服务端的环境变量也行。",
+  };
+  try {
+    const info = await Promise.race([withProbe((q) => q.accountInfo()), timeout<never>(25_000, "读取 Claude 账号")]);
+    const thirdParty = info.apiProvider && info.apiProvider !== "firstParty";
+    const loggedIn = !!(info.email || info.apiKeySource || thirdParty || (info.tokenSource && info.tokenSource !== "none"));
+    const account = info.email
+      ? `${info.email}${info.subscriptionType ? `（${info.subscriptionType}）` : ""}`
+      : info.apiKeySource
+        ? `API Key（${info.apiKeySource}）`
+        : thirdParty
+          ? String(info.apiProvider)
+          : undefined;
+    return { ...base, loggedIn, ...(account ? { account } : {}), ...(loggedIn ? {} : { fix: loginFix }) };
+  } catch (err) {
+    return { ...base, loggedIn: null, problem: err instanceof Error ? err.message : String(err), fix: loginFix };
+  }
+}
+
+async function codexHealth(): Promise<AgentHealth> {
+  const cfg = config().agents.codex;
+  const base = { id: "codex" as const, label: "Codex", enabled: cfg.enabled };
+  const env = { ...process.env, ...(cfg.home ? { CODEX_HOME: cfg.home } : {}) };
+  const ver = await run(cfg.path, ["--version"], 10_000, env);
+  if (ver.code !== 0) {
+    return {
+      ...base,
+      installed: false,
+      loggedIn: null,
+      problem: `找不到 ${cfg.path}`,
+      fix: {
+        action: "install",
+        title: "安装 Codex",
+        commands: ["brew install --cask codex", "npm install -g @openai/codex"],
+        note: "有 Homebrew 用第一条，否则用第二条（需要 Node.js）。agent-loft 以系统服务运行时 PATH 很短，装好后在下面把「codex 可执行文件」填成绝对路径（终端里 command -v codex 可以查到）。",
+      },
+    };
+  }
+  const version = ver.out.split("\n")[0]?.trim();
+  const st = await run(cfg.path, ["login", "status"], 10_000, env);
+  const loggedIn = st.code === 0 && !/not logged in/i.test(st.out);
+  return {
+    ...base,
+    installed: true,
+    ...(version ? { version } : {}),
+    loggedIn,
+    ...(loggedIn ? { account: st.out.split("\n")[0]?.trim() } : {}),
+    ...(loggedIn ? {} : { fix: { action: "login" as const, title: "登录 Codex", commands: [`${quote(cfg.path)} login`], note: "会打开浏览器，用 ChatGPT 账号登录；也可以 codex login --with-api-key 用 API Key。" } }),
+  };
+}
+
+let cache: { at: number; value: AgentHealth[] } | null = null;
+
+/**
+ * 不等体检、立刻给出的「这个 agent 能不能用」：用最近一次体检的结果（多旧都算），
+ * 结果超过 5 分钟就顺手在后台再查一次。还没查过返回 null（当作能用，不挡人）。
+ * 新对话里只列出能用的 agent，没装、没登录的不出现。
+ */
+export function agentAvailability(id: AgentHealth["id"]): { available: boolean; reason?: string } | null {
+  if (!cache || Date.now() - cache.at > 5 * 60_000) void agentHealth().catch(() => {});
+  const h = cache?.value.find((a) => a.id === id);
+  if (!h) return null;
+  if (!h.installed) return { available: false, reason: "未安装" };
+  if (h.loggedIn === false) return { available: false, reason: "未登录" };
+  return { available: true };
+}
+
+/** 装了 / 登录了什么之后，下次体检不用缓存 */
+export function invalidateHealth(): void {
+  cache = null;
+}
+let inflight: Promise<AgentHealth[]> | null = null;
+
+/** 两个 agent 一起查，结果缓存一分钟；refresh 跳过缓存（点了「重新检查」） */
+export function agentHealth(refresh = false): Promise<AgentHealth[]> {
+  if (!refresh && cache && Date.now() - cache.at < 60_000) return Promise.resolve(cache.value);
+  inflight ??= Promise.all([claudeHealth(), codexHealth()])
+    .then((value) => {
+      cache = { at: Date.now(), value };
+      return value;
+    })
+    .finally(() => {
+      inflight = null;
+    });
+  return inflight;
+}

package/src/channels/web/api.ts

@@ -12,6 +12,8 @@ import { getConversation, updateConversation } from "../../core/store.js";
 import { resolveUploadFile, saveBuffer, sniff } from "../../core/uploads.js";
 import type { SavedAttachment } from "../../core/types.js";
 import { listAllowlist, setAllowlist } from "../../agents/claude/permissions.js";
+import { agentAvailability, agentHealth, invalidateHealth } from "../../agents/health.js";
+import { installCodex, upgrade, useInstalledCodex, versionInfo } from "../../core/upgrade.js";
 import { feishuBots } from "../feishu/index.js";
 import { beginRegistration, initRegistration, pollRegistration, qrSvg } from "../feishu/register.js";
 import { FeishuClient } from "../feishu/client.js";
@@ -315,6 +317,8 @@ export async function handleApi(req: IncomingMessage, res: ServerResponse, url:
           capabilities: d?.capabilities ?? {},
           // 输入框模型列表里显示哪些，空 = 全部
           models: config().agents[id].models.filter((m) => typeof m === "string"),
+          // 没装 / 没登录：新对话里不出现（null = 还没查过，当作能用）
+          ...(agentAvailability(id) ?? {}),
         };
       }),
       bots: config().feishu.bots.map((b) => ({ id: b.id, name: b.name, agents: b.agents, enabled: b.enabled })),
@@ -539,6 +543,27 @@ export async function handleApi(req: IncomingMessage, res: ServerResponse, url:
     return;
   }
   // 侧栏的账号额度：各 agent 自己缓存（60 秒），这里并发问一遍，单个失败 / 超时不影响别的
+  if (p === "/api/server/version" && method === "GET") {
+    sendJson(res, 200, await versionInfo(url.searchParams.get("refresh") === "1"));
+    return;
+  }
+  if (p === "/api/server/upgrade" && method === "POST") {
+    sendJson(res, 200, await upgrade().catch((err) => {
+      throw new HttpError(400, err instanceof Error ? err.message : String(err));
+    }));
+    return;
+  }
+  if (p === "/api/agents/codex/install" && method === "POST") {
+    const result = await installCodex();
+    if (result.ok) useInstalledCodex();
+    invalidateHealth();
+    sendJson(res, 200, result);
+    return;
+  }
+  if (p === "/api/agents/health" && method === "GET") {
+    sendJson(res, 200, { agents: await agentHealth(url.searchParams.get("refresh") === "1") });
+    return;
+  }
   if (p === "/api/quota" && method === "GET") {
     const results = await Promise.all(
       hub.enabledAgents().map(async (d) => {

package/src/channels/web/server.ts

@@ -180,31 +180,45 @@ function convName(key: string): string {
   return conv.title?.trim() || hub.label(conv.agent);
 }
 
-/** 只推 Web 自己的会话：飞书会话的动静飞书已经会提醒 */
-function notifiable(key: string): boolean {
-  return getConversation(key)?.channel === "web" && hasSubscriptions() && !watching(key);
+/** 只提醒 Web 自己的会话：飞书会话的动静飞书已经会提醒 */
+function isWebConv(key: string): boolean {
+  return getConversation(key)?.channel === "web";
+}
+
+type Notice = { title: string; body: string; tag: string };
+
+/**
+ * 一条要提醒的动静，走两条路：
+ *   - 广播给所有连着的页面（t: "notice"）：桌面端据此弹系统通知，要不要弹由它自己判断
+ *     （它知道自己是不是正看着这条会话）。普通网页忽略。
+ *   - Web Push：只在没有页面正看着这条会话时推。
+ */
+function notify(key: string, notice: Notice): void {
+  if (!isWebConv(key)) return;
+  for (const client of clients) send(client, { t: "notice", key, ...notice });
+  if (hasSubscriptions() && !watching(key)) void pushToAll({ ...notice, url: `/#${encodeURIComponent(key)}` });
 }
 
 function pushEvent(env: EventEnvelope): void {
   const ev = env.ev;
   if (ev.type !== "result" && ev.type !== "error") return;
-  if (!notifiable(env.key)) return;
+  if (!isWebConv(env.key)) return;
   const name = convName(env.key);
   const payload =
     ev.type === "result"
       ? { title: `${name} · 回复完成`, body: plainPreview(ev.text) || "（没有文字回复）" }
       : { title: `${name} · 出错了`, body: plainPreview(ev.message) };
-  void pushToAll({ ...payload, tag: `reply:${env.key}`, url: `/#${encodeURIComponent(env.key)}` });
+  notify(env.key, { ...payload, tag: `reply:${env.key}` });
 }
 
 function pushInteraction(i: Interaction): void {
-  if (!notifiable(i.convKey)) return;
+  if (!isWebConv(i.convKey)) return;
   const name = convName(i.convKey);
   const payload =
     i.spec.kind === "approval"
       ? { title: `${name} · 需要授权`, body: plainPreview(i.spec.title) }
       : { title: `${name} · 有问题要你回答`, body: plainPreview(i.spec.questions[0]?.question ?? i.spec.title) };
-  void pushToAll({ ...payload, tag: `ix:${i.id}`, url: `/#${encodeURIComponent(i.convKey)}` });
+  notify(i.convKey, { ...payload, tag: `ix:${i.id}` });
 }
 
 const BY = "已在 Web 处理";

package/src/core/upgrade.ts

@@ -0,0 +1,200 @@
+// 服务端自升级：查 npm 上的最新版本，npm install -g 升级，跑在系统服务下就自动重启。
+//
+// 只支持 npm 全局安装（npm install -g agent-loft）：从源码跑的（git clone）该用 git pull，
+// 别的装法不知道怎么升级，都不碰。
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config, saveConfig } from "./config.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+function readPackage(): { name: string; version: string } {
+  return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+}
+
+/** 当前进程跑的版本（升级后磁盘上的文件变了，进程里的还是旧的，直到重启） */
+export const RUNNING_VERSION = readPackage().version;
+const NAME = readPackage().name;
+
+/** npm 和 node 放在一起（官方安装包、Homebrew、fnm、nvm 都是），用同一套，装到同一个地方 */
+function npmBin(): string {
+  const beside = path.join(path.dirname(process.execPath), process.platform === "win32" ? "npm.cmd" : "npm");
+  return fs.existsSync(beside) ? beside : "npm";
+}
+
+function npmEnv(): NodeJS.ProcessEnv {
+  // 系统服务下 PATH 很短：npm 是个 node 脚本，得让它找得到 node
+  return { ...process.env, PATH: `${path.dirname(process.execPath)}${path.delimiter}${process.env.PATH ?? ""}` };
+}
+
+function run(cmd: string, args: string[], timeoutMs: number): Promise<{ code: number; out: string }> {
+  return new Promise((resolve) => {
+    let out = "";
+    const child = spawn(cmd, args, { env: npmEnv(), stdio: ["ignore", "pipe", "pipe"] });
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (out += d));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: -1, out: err.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? -1, out: out.trim() });
+    });
+  });
+}
+
+/** 由谁托管：launchd 会把标签放进 XPC_SERVICE_NAME，systemd 会设 INVOCATION_ID */
+export function serviceManager(): "launchd" | "systemd" | null {
+  const xpc = process.env.XPC_SERVICE_NAME ?? "";
+  if (/^com\.(agent-loft|im-agent)/.test(xpc)) return "launchd";
+  if (process.env.INVOCATION_ID) return "systemd";
+  return null;
+}
+
+/**
+ * npm 全局安装的目录结构：<prefix>/lib/node_modules/agent-loft，命令链接在 <prefix>/bin/agent-loft
+ * （Windows 上是 <prefix>/node_modules/agent-loft 和 <prefix>/agent-loft.cmd）。
+ * 按结构认，不去问 npm root -g：npm 会把输出里像密钥的串（比如路径里的 UUID）打成 ***。
+ */
+function globalPrefix(): string | null {
+  const real = (p: string) => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return null;
+    }
+  };
+  const self = real(root);
+  if (!self || path.basename(path.dirname(self)) !== "node_modules") return null;
+  if (process.platform === "win32") {
+    const prefix = path.dirname(path.dirname(self));
+    return fs.existsSync(path.join(prefix, `${NAME}.cmd`)) ? prefix : null;
+  }
+  if (path.basename(path.dirname(path.dirname(self))) !== "lib") return null;
+  const prefix = path.dirname(path.dirname(path.dirname(self)));
+  const link = real(path.join(prefix, "bin", NAME));
+  return link && link === real(path.join(self, "bin/cli.js")) ? prefix : null;
+}
+
+/** 怎么装的：npm 全局安装才能在线升级 */
+async function installKind(): Promise<"npm-global" | "source" | "unknown"> {
+  if (fs.existsSync(path.join(root, ".git"))) return "source";
+  return globalPrefix() ? "npm-global" : "unknown";
+}
+
+let latestCache: { at: number; version: string | null; error?: string } | null = null;
+
+/** npm 上的最新版。用 npm view 而不是直接请求 registry.npmjs.org：用户配的镜像源（npmmirror 等）照样生效 */
+async function latestVersion(refresh: boolean): Promise<{ version: string | null; error?: string }> {
+  if (!refresh && latestCache && Date.now() - latestCache.at < 30 * 60_000) return latestCache;
+  const r = await run(npmBin(), ["view", NAME, "version"], 30_000);
+  const version = r.code === 0 ? r.out.split("\n").find((l) => /^\d+\.\d+\.\d+/.test(l.trim()))?.trim() : undefined;
+  latestCache = version ? { at: Date.now(), version } : { at: Date.now(), version: null, error: r.out.slice(-300) || "查询失败" };
+  return latestCache;
+}
+
+/** "0.2.10" > "0.2.9" */
+export function newer(a: string, b: string): boolean {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
+  }
+  return false;
+}
+
+export type VersionInfo = {
+  version: string;
+  latest: string | null;
+  latestError?: string;
+  updateAvailable: boolean;
+  installKind: "npm-global" | "source" | "unknown";
+  service: "launchd" | "systemd" | null;
+  canUpgrade: boolean;
+  /** 不能在线升级时说明原因和手动办法 */
+  reason?: string;
+  upgrading: boolean;
+};
+
+let upgrading = false;
+
+export async function versionInfo(refresh = false): Promise<VersionInfo> {
+  const [kind, latest] = await Promise.all([installKind(), latestVersion(refresh)]);
+  const updateAvailable = !!latest.version && newer(latest.version, RUNNING_VERSION);
+  const reason =
+    kind === "source"
+      ? "从源码运行的，用 git pull 更新后重启"
+      : kind === "unknown"
+        ? "不是用 npm install -g 装的，没法在线升级"
+        : undefined;
+  return {
+    version: RUNNING_VERSION,
+    latest: latest.version,
+    ...(latest.error ? { latestError: latest.error } : {}),
+    updateAvailable,
+    installKind: kind,
+    service: serviceManager(),
+    canUpgrade: kind === "npm-global",
+    ...(reason ? { reason } : {}),
+    upgrading,
+  };
+}
+
+/**
+ * 升级到最新版。跑在 launchd / systemd 下的，回完话就退出，由它们拉起新版本；
+ * 前台手动跑的（agent-loft start）没人拉起，只能请用户自己重启。
+ */
+export async function upgrade(): Promise<{ from: string; to: string; restarting: boolean; output: string }> {
+  if (upgrading) throw new Error("正在升级，稍等");
+  const info = await versionInfo(true);
+  if (!info.canUpgrade) throw new Error(info.reason ?? "没法在线升级");
+  if (!info.latest) throw new Error(`查不到最新版本：${info.latestError ?? ""}`);
+  if (!info.updateAvailable) throw new Error(`已经是最新版本 ${RUNNING_VERSION}`);
+  upgrading = true;
+  try {
+    // 明确指定 prefix：装回原来那个位置，不受当前 npm 配置影响
+    const prefix = globalPrefix()!;
+    const r = await run(npmBin(), ["install", "-g", "--prefix", prefix, `${NAME}@${info.latest}`, "--no-audit", "--no-fund"], 10 * 60_000);
+    const installed = readPackage().version;
+    if (r.code !== 0 || installed !== info.latest) {
+      throw new Error(`npm install 失败：${r.out.slice(-600) || `退出码 ${r.code}`}`);
+    }
+    const restarting = !!info.service;
+    if (restarting) {
+      console.log(`[升级] 已装好 ${installed}，退出进程，由 ${info.service} 拉起新版本`);
+      setTimeout(() => process.exit(0), 1500).unref();
+    }
+    return { from: RUNNING_VERSION, to: installed, restarting, output: r.out.slice(-2000) };
+  } finally {
+    upgrading = false;
+  }
+}
+
+/** 在服务端这台机器上安装 Codex：有 Homebrew 用它，否则用 npm。登录要在浏览器里点，这里不管。 */
+export async function installCodex(): Promise<{ ok: boolean; via: string; output: string }> {
+  const brew = ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"].find((p) => fs.existsSync(p));
+  const r =
+    process.platform === "darwin" && brew
+      ? await run(brew, ["install", "--cask", "codex"], 10 * 60_000)
+      : await run(npmBin(), ["install", "-g", "@openai/codex", "--no-audit", "--no-fund"], 10 * 60_000);
+  return { ok: r.code === 0, via: process.platform === "darwin" && brew ? "Homebrew" : "npm", output: r.out.slice(-2000) };
+}
+
+/**
+ * 装好 Codex 之后：配置里的 codex（默认就是 "codex"）在服务的 PATH 里找不到的话，
+ * 换成刚装好的那个的绝对路径。改配置会让 codex app-server 按新路径重拉。
+ */
+export function useInstalledCodex(): void {
+  const cfg = config();
+  if (spawnSync(cfg.agents.codex.path, ["--version"], { env: npmEnv(), timeout: 10_000 }).status === 0) return;
+  const found = [path.join(path.dirname(process.execPath), "codex"), "/opt/homebrew/bin/codex", "/usr/local/bin/codex"].find((p) => fs.existsSync(p));
+  if (!found) return;
+  const next = structuredClone(cfg);
+  next.agents.codex.path = found;
+  saveConfig(next);
+  console.log(`[codex] 已装好，路径改成 ${found}`);
+}

package/src/main.ts

@@ -5,6 +5,7 @@ import { flushStore, getConversation, isExpired } from "./core/store.js";
 import { sweepUploads } from "./core/uploads.js";
 import { ClaudeDriver } from "./agents/claude/driver.js";
 import { CodexDriver } from "./agents/codex/driver.js";
+import { agentHealth } from "./agents/health.js";
 import { startFeishu, stopFeishu } from "./channels/feishu/index.js";
 import { startWeb, stopWeb } from "./channels/web/server.js";
 import { home } from "./home.js";
@@ -40,6 +41,8 @@ async function main(): Promise<void> {
 
   startFeishu();
   if (config().web.enabled) await startWeb();
+  // 先查一遍 agent 装没装、登没登录，网页打开时新对话里就只列出能用的
+  void agentHealth().catch(() => {});
 
   console.log(`[启动] workspace=${config().workspaceRoot}`);
   if (config().workspaceRoot === process.cwd()) {

package/web/app.js

@@ -260,6 +260,14 @@ const S = {
 
 const ui = {};
 
+/**
+ * 运行在 macOS 桌面端（agent-loft-desktop）里时，由它的 preload 注入。
+ * 桌面端收不到 Web Push，系统通知、Dock 角标、菜单栏的待处理数都交给它。
+ */
+const desktop = window.agentLoftDesktop ?? null;
+// 桌面端里：顶栏、侧栏顶部可以按住拖动窗口（样式见 style.css 的 .in-desktop）
+if (desktop) document.documentElement.classList.add("in-desktop");
+
 // ---------- WebSocket ----------
 
 const WS = {
@@ -445,6 +453,12 @@ function onWsMessage(msg) {
     case "ix":
       upsertInteraction(msg.interaction);
       return;
+    case "notice":
+      // 正看着这条会话就不打扰；普通网页靠 Web Push，这里只给桌面端
+      if (!desktop) return;
+      if (document.visibilityState === "visible" && document.hasFocus() && msg.key === S.current) return;
+      desktop.notify({ key: msg.key, title: msg.title, body: msg.body, tag: msg.tag });
+      return;
   }
 }
 
@@ -516,9 +530,10 @@ async function boot() {
   S.quotaRefreshMin = data.quotaRefreshMin ?? 10;
   S.convs = new Map(data.conversations.map((c) => [c.key, c]));
   S.pending = new Map(data.pending.map((i) => [i.id, i]));
-  const enabled = S.agents.filter((a) => a.enabled).map((a) => a.id);
+  const enabled = usableAgents().map((a) => a.id);
   if (!S.draftAgent || !enabled.includes(S.draftAgent)) S.draftAgent = enabled[0] ?? null;
   renderLayout();
+  reportDesktop();
   WS.connect();
   void loadQuota();
   const fromHash = decodeURIComponent(location.hash.slice(1));
@@ -527,6 +542,10 @@ async function boot() {
   if (fromHash && S.convs.has(fromHash)) await openConversation(fromHash);
   else if (latest) await openConversation(latest.key);
   else newDraft();
+  // 点了桌面端的系统通知 / 菜单栏里的待处理项：跳到对应会话
+  desktop?.onOpen((key) => {
+    if (key && S.convs.has(key) && key !== S.current) void openConversation(key);
+  });
   if ("serviceWorker" in navigator) {
     navigator.serviceWorker.register("/sw.js").catch(() => {});
     clearAppBadge();
@@ -660,6 +679,7 @@ async function loadQuota() {
     const data = await api("/api/quota");
     quotaState.data = data.quotas;
     quotaState.at = Date.now();
+    desktop?.setQuota(data.quotas);
   } catch {
     // 保留旧数据
   } finally {
@@ -829,6 +849,7 @@ function scheduleSidebar() {
   requestAnimationFrame(() => {
     sidebarScheduled = false;
     renderSidebar();
+    reportDesktop();
   });
 }
 
@@ -923,6 +944,16 @@ let autoOpenedFor = null;
 const RECENT_LIMIT = 10;
 const PROJECT_LIMIT = 5;
 
+/** 待处理的授权 / 提问和正在跑的会话，报给桌面端显示在菜单栏里 */
+function reportDesktop() {
+  if (!desktop) return;
+  const pending = [...S.pending.values()]
+    .filter((i) => !i.settled)
+    .map((i) => ({ id: i.id, key: i.convKey, title: i.spec.title, conv: convTitle(S.convs.get(i.convKey)) }));
+  const busy = [...S.convs.values()].filter((c) => c.busy).length;
+  desktop.setState({ pending, busy });
+}
+
 function renderSidebar() {
   if (!ui.convList) return;
   const askKeys = new Set([...S.pending.values()].filter((i) => !i.settled).map((i) => i.convKey));
@@ -1084,8 +1115,18 @@ function currentCwd() {
   return c ? c.cwd : (S.draftCwd ?? S.workspaceRoot ?? "");
 }
 
+/**
+ * 新对话能选的 agent：启用了、并且服务端查过是装好登录了的（available 为 false 的不出现）。
+ * 一个能用的都没有时退回到全部启用的，至少能看到报错，而不是什么都选不了。
+ */
+function usableAgents() {
+  const enabled = S.agents.filter((a) => a.enabled);
+  const usable = enabled.filter((a) => a.available !== false);
+  return usable.length ? usable : enabled;
+}
+
 function pickAgentMenu(anchor) {
-  const allowed = S.agents.filter((a) => a.enabled).map((a) => a.id);
+  const allowed = usableAgents().map((a) => a.id);
   if (allowed.length < 2) return;
   if (ui.menu?.dataset.for === "agent") return closeMenu();
   const pop = showPopover(anchor, { align: "left" });
@@ -1176,7 +1217,7 @@ function renderContext() {
   if (!ui.ctxBar) return;
   const c = S.current ? S.convs.get(S.current) : null;
   const cwd = currentCwd();
-  const multi = S.agents.filter((a) => a.enabled).length > 1;
+  const multi = usableAgents().length > 1;
   // 会话里不能换 agent（两个 agent 的会话互不相通），只显示；新对话里可以选
   const agentId = c ? c.agent : S.draftAgent;
   const agentEl = c || !multi
@@ -1408,7 +1449,7 @@ function newDraft() {
 }
 
 function renderEmpty() {
-  const enabled = S.agents.filter((a) => a.enabled);
+  const enabled = usableAgents();
   const cwd = S.draftCwd ?? S.workspaceRoot ?? "";
   fill(ui.msgInner,
     h(
@@ -1838,7 +1879,8 @@ function upsertInteraction(ix) {
 }
 
 function notifyIfHidden(ix) {
-  if (document.visibilityState === "visible" || !("Notification" in window)) return;
+  // 桌面端由服务端的 notice 统一弹，这里再弹就重复了
+  if (desktop || document.visibilityState === "visible" || !("Notification" in window)) return;
   if (Notification.permission === "granted") {
     try {
       new Notification("Agent Loft 需要你处理", { body: ix.spec.title, tag: ix.id });
@@ -2352,7 +2394,7 @@ function oneLine(text, max = 80) {
 
 function currentAgentId() {
   const c = S.current ? S.convs.get(S.current) : null;
-  return c?.agent ?? S.draftAgent ?? S.agents.find((a) => a.enabled)?.id ?? "claude";
+  return c?.agent ?? S.draftAgent ?? usableAgents()[0]?.id ?? "claude";
 }
 
 async function loadCommands(agent) {
@@ -2563,14 +2605,14 @@ async function switchAgent(id) {
   await doAction("agent", id);
 }
 
-function modal({ title, body, foot, wide }) {
+function modal({ title, body, foot, wide, tall }) {
   const close = () => overlay.remove();
   const overlay = h(
     "div",
     { class: "overlay", onclick: (e) => e.target === overlay && close() },
     h(
       "div",
-      { class: `modal${wide ? " wide" : ""}` },
+      { class: `modal${wide ? " wide" : ""}${tall ? " tall" : ""}` },
       h("div", { class: "modal-head" }, h("h3", {}, title), h("button", { class: "icon-btn", onclick: close }, icon("x"))),
       body,
       foot ?? null,
@@ -3015,7 +3057,8 @@ async function deleteConv(key = S.current) {
 async function openSettings() {
   const nav = h("div", { class: "settings-nav" });
   const panel = h("div", { class: "settings-body" });
-  const close = modal({ title: "设置", wide: true, body: h("div", { class: "settings" }, nav, panel) });
+  // 设置弹窗高度固定，切标签页时不跟着内容一伸一缩
+  const close = modal({ title: "设置", wide: true, tall: true, body: h("div", { class: "settings" }, nav, panel) });
   let cfg;
   try {
     cfg = await api("/api/config");
@@ -3047,6 +3090,7 @@ async function openSettings() {
 function pushSupport() {
   const ios = /iPhone|iPad|iPod/.test(navigator.userAgent);
   const standalone = window.matchMedia("(display-mode: standalone)").matches || navigator.standalone === true;
+  if (desktop) return { ok: false, why: "桌面端会直接弹出 macOS 系统通知，不需要在这里开启。" };
   if (!window.isSecureContext) return { ok: false, why: "通知需要 HTTPS 访问（localhost 除外）。请通过 HTTPS 的反向代理地址打开。" };
   if (ios && !standalone) {
     return { ok: false, why: "iPhone / iPad 上要先在 Safari 里点「分享 → 添加到主屏幕」，再从桌面图标打开，才能开启通知（需 iOS 16.4+）。" };
@@ -3197,7 +3241,61 @@ function field(label, input, hint) {
   return h("label", { class: "field" }, h("span", {}, label), input, hint ? h("small", {}, hint) : null);
 }
 
+/** 服务端版本：有新版就能一键升级（npm install -g，系统服务下自动重启） */
+function serverVersionSection() {
+  const box = h("div", { class: "section" });
+  const load = async (refresh) => {
+    fill(box, h("h4", {}, "服务端版本", h("span", { class: "grow" }), h("span", { class: "spinner" })));
+    let v;
+    try {
+      v = await api(`/api/server/version${refresh ? "?refresh=1" : ""}`);
+    } catch (err) {
+      fill(box, h("h4", {}, "服务端版本"), h("div", { class: "error-text" }, err.message));
+      return;
+    }
+    const recheck = h("button", { class: "btn small", onclick: () => load(true) }, "检查更新");
+    const status = v.updateAvailable
+      ? `有新版本 ${v.latest}`
+      : v.latest
+        ? "已是最新版本"
+        : `查不到最新版本${v.latestError ? `：${v.latestError}` : ""}`;
+    const upgradeBtn =
+      v.updateAvailable && v.canUpgrade
+        ? h(
+            "button",
+            {
+              class: "btn small primary",
+              onclick: async () => {
+                upgradeBtn.disabled = true;
+                upgradeBtn.textContent = "正在升级…";
+                try {
+                  const r = await api("/api/server/upgrade", { method: "POST" });
+                  toast(r.restarting ? `已升级到 ${r.to}，服务正在重启，页面会自动重连` : `已升级到 ${r.to}，重启 agent-loft 后生效`, 6000);
+                  void load(false);
+                } catch (err) {
+                  toast(`升级失败：${err.message}`, 6000);
+                  upgradeBtn.disabled = false;
+                  upgradeBtn.textContent = "升级";
+                }
+              },
+            },
+            "升级",
+          )
+        : null;
+    fill(
+      box,
+      h("h4", {}, "服务端版本", h("span", { class: "grow" }), upgradeBtn, recheck),
+      h("div", { class: "health-meta" }, `当前 ${v.version} · ${status}`),
+      v.updateAvailable && !v.canUpgrade && v.reason ? h("div", { class: "health-meta" }, v.reason) : null,
+      v.updateAvailable && v.canUpgrade && !v.service ? h("div", { class: "health-meta" }, "agent-loft 是在前台手动运行的，升级后要自己重启一下。") : null,
+    );
+  };
+  void load(false);
+  return box;
+}
+
 function generalTab(cfg, panel) {
+  panel.append(serverVersionSection());
   const root = h("input", { value: cfg.workspaceRoot });
   const approval = h("input", { type: "number", min: 1, value: Math.round(cfg.approvalTimeoutMs / 60000) });
   const ttl = h("input", { type: "number", min: 0, value: Math.round(cfg.sessionTtlMs / 3600000) });
@@ -3678,7 +3776,93 @@ function modelChecklist(agent, selected) {
   };
 }
 
+/** Agent 运行环境：装没装、登没登录；没好的给出在终端里执行的命令 */
+function agentHealthSection() {
+  const box = h("div", { class: "section" });
+  const load = async (refresh) => {
+    const recheck = h("button", { class: "btn small", onclick: () => load(true) }, "重新检查");
+    fill(box, h("h4", {}, "运行环境", h("span", { class: "grow" }), h("span", { class: "spinner" })));
+    let data;
+    try {
+      data = await api(`/api/agents/health${refresh ? "?refresh=1" : ""}`);
+    } catch (err) {
+      fill(box, h("h4", {}, "运行环境", h("span", { class: "grow" }), recheck), h("div", { class: "error-text" }, err.message));
+      return;
+    }
+    // 体检结果顺手同步到新对话的 agent 列表：刚装好 / 登录好的立刻能选，不行的立刻消失
+    for (const a of data.agents) {
+      const known = S.agents.find((x) => x.id === a.id);
+      if (known) known.available = a.installed && a.loggedIn !== false;
+    }
+    if (!usableAgents().some((a) => a.id === S.draftAgent)) S.draftAgent = usableAgents()[0]?.id ?? null;
+    if (!S.current) renderEmpty();
+    fill(
+      box,
+      h("h4", {}, "运行环境", h("span", { class: "grow" }), recheck),
+      ...data.agents.map((a) => {
+        const ok = a.installed && a.loggedIn === true;
+        const state = !a.installed ? "未安装" : a.loggedIn === false ? "未登录" : a.loggedIn === null ? "无法确认" : "正常";
+        return h(
+          "div",
+          { class: "health-row" },
+          h(
+            "div",
+            { class: "health-head" },
+            h("span", { class: `health-dot ${ok ? "ok" : "bad"}` }),
+            h("b", {}, a.label),
+            h("span", { class: "health-state" }, state),
+            a.enabled ? null : h("span", { class: "health-off" }, "（未启用）"),
+          ),
+          a.account || a.version ? h("div", { class: "health-meta" }, [a.account, a.version].filter(Boolean).join(" · ")) : null,
+          a.problem ? h("div", { class: "health-meta" }, a.problem) : null,
+          a.fix
+            ? h(
+                "div",
+                { class: "health-fix" },
+                h("div", {}, `${a.fix.title}：在运行 agent-loft 的机器上打开终端执行${a.fix.commands.length > 1 ? "（任选一条）" : ""}`),
+                a.fix.commands.map((cmd) => {
+                  const copy = h("button", { class: "btn small", onclick: () => copyText(cmd, copy) }, "复制");
+                  return h("div", { class: "health-cmd" }, h("code", {}, cmd), copy);
+                }),
+                a.fix.note ? h("small", {}, a.fix.note) : null,
+                a.id === "codex" && a.fix.action === "install" ? installCodexButton(() => load(true)) : null,
+              )
+            : null,
+        );
+      }),
+    );
+  };
+  void load(false);
+  return box;
+}
+
+/** 直接在服务端那台机器上装 Codex（Homebrew 或 npm），装完重新检查 */
+function installCodexButton(after) {
+  const btn = h(
+    "button",
+    {
+      class: "btn small primary",
+      onclick: async () => {
+        btn.disabled = true;
+        btn.textContent = "正在安装，可能要几分钟…";
+        try {
+          const r = await api("/api/agents/codex/install", { method: "POST" });
+          toast(r.ok ? `已用 ${r.via} 装好 Codex` : `安装失败：${r.output.slice(-200)}`, 6000);
+          after();
+        } catch (err) {
+          toast(`安装失败：${err.message}`, 6000);
+          btn.disabled = false;
+          btn.textContent = "直接在服务器上安装";
+        }
+      },
+    },
+    "直接在服务器上安装",
+  );
+  return h("div", {}, btn);
+}
+
 function agentsTab(cfg, panel) {
+  panel.append(agentHealthSection());
   const a = structuredClone(cfg.agents);
   const claudeOn = h("input", { type: "checkbox", checked: a.claude.enabled });
   const claudePick = modelPicker("claude", a.claude.defaultModel, a.claude.defaultEffort, "跟随 Claude Code 默认");

package/web/style.css

@@ -2300,6 +2300,11 @@ button.ctx-item:hover {
   max-width: 860px;
 }
 
+/* 设置弹窗：固定高度 */
+.modal.tall {
+  height: 86vh;
+}
+
 .modal-head {
   display: flex;
   align-items: center;
@@ -2747,6 +2752,10 @@ button.list-item:hover {
     align-items: center;
   }
 
+  .modal.tall {
+    height: 92vh;
+  }
+
   .modal,
   .modal.wide {
     max-width: none;
@@ -3152,3 +3161,75 @@ button.list-item:hover {
 .lightbox-dl:hover {
   background: rgba(255, 255, 255, 0.26);
 }
+
+/* 设置 → Agent → 运行环境 */
+.health-row {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.health-row + .health-row {
+  border-top: 1px solid var(--border);
+  padding-top: 12px;
+}
+.health-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.health-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--danger);
+  flex: none;
+}
+.health-dot.ok {
+  background: var(--ok);
+}
+.health-state {
+  color: var(--fg-soft);
+}
+.health-off,
+.health-meta {
+  color: var(--fg-faint);
+  font-size: 12px;
+}
+.health-fix {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 10px 12px;
+  border-radius: 10px;
+  background: var(--warn-bg);
+  border: 1px solid var(--warn-border);
+  font-size: 13px;
+}
+.health-fix small {
+  color: var(--fg-soft);
+}
+.health-cmd {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.health-cmd code {
+  flex: 1;
+  min-width: 0;
+  overflow-x: auto;
+  white-space: nowrap;
+  padding: 5px 8px;
+  border-radius: 6px;
+  background: var(--code-bg);
+  font-size: 12px;
+}
+
+/* 桌面端（Agent Loft for macOS）里：顶栏和侧栏顶部按住能拖动窗口，里面的按钮照常能点 */
+.in-desktop .topbar,
+.in-desktop .side-top {
+  -webkit-app-region: drag;
+}
+.in-desktop .topbar :is(button, a, input, select, textarea, label, .conv-name),
+.in-desktop .side-top :is(button, a, input, select, textarea, label) {
+  -webkit-app-region: no-drag;
+}