agent-loft 0.2.19 → 0.2.21

package/README.md

@@ -2,7 +2,11 @@
 
 # agent-loft
 
-**多个 agent 的工作台。** 把本机的 **Claude Code**、**Codex**（以后还有更多）放到同一张台面上统一管理，用飞书（以后还有 Telegram 等）和 Web 页面随时随地驱动它们。
+**多个 agent 的工作台。** 把本机的 **Claude Code**、**Codex**（以后还有更多）放到同一张台面上统一管理，在网页、飞书和 Mac 桌面端随时驱动它们，进展推送到飞书、iPhone 和 Mac。
+
+![Web 工作台](docs/images/web-chat.png)
+
+> 📖 完整的产品介绍和使用指南见 **[docs/产品介绍.md](docs/产品介绍.md)**：六大核心亮点、快速上手、使用指南、命令速查、常见问题和故障排查。
 
 由 `feishu-claude-bridge` 和 `feishu-codex-bridge` 合并而来：一个进程、一份配置，飞书和网页共用同一套会话、审批和模型切换。
 
@@ -10,56 +14,71 @@
 
 这里的 Loft 不是阁楼，是**工作台**：agent 是干活的人，agent-loft 是它们共用的那张台面。
 
-- **多 agent，一张台面**：Claude Code、Codex 各有所长，不该各开一个窗口、各记一套会话。它们在这里共用工作目录、会话列表、审批和模型切换，同一条对话里随时换人接手，各自的上下文都还在。
+- **多 agent，一张台面**：Claude Code、Codex 各有所长，不该各开一个窗口、各记一套会话。它们在这里共用工作目录、会话列表、审批和模型切换，同一条会话里随时换人接手，各自的上下文都保留着。
 - **统一管理，而不是再造一个 agent**：agent-loft 不自己做模型、不改 agent 的行为，只负责把官方的 agent 接进来、管起来。新的 agent 接一个驱动就能上台。
 - **人在哪，台面就在哪**：电脑上用网页，手机上用 PWA 或飞书。同一个会话、同一个授权请求，在哪个渠道处理都行，其他地方自动同步。
 - **跑在你自己的机器上**：代码、凭据和会话都留在本机，agent-loft 只是一层安全的遥控。
 
 Logo 就是这个意思：一大两小几颗星（多个 agent）站在同一张台面上。
 
+## 六大核心亮点
+
+| | 亮点 | 说明 |
+|---|---|---|
+| 🤖 | **同时管理多个 agent** | Claude Code（官方 Claude Agent SDK）和 Codex（官方 `codex app-server`）共用会话列表、工作目录和授权。同一条会话里用 `/claude`、`/codex`、`/agent` 切换，每个 agent 保留自己的上下文 |
+| 🔀 | **飞书机器人灵活绑定 agent** | 机器人数量不限，每个机器人可以只对应一个 agent，也可以对应多个（在会话里切换）。网页上扫码就能创建，改完立即生效；由服务端主动连向飞书，家里没有公网 IP 也能在外面用 |
+| 🔗 | **飞书续接 Web 任务** | 飞书里发 `/web` 接上一条 Web 会话，或者在网页侧栏右键会话选「在飞书继续…」。之后回复、授权、提问都发到飞书，发 `/detach` 回来 |
+| 🖥️ | **完整的 Web 工作台** | 流式回复、附件、语音输入、模型和思考程度切换、上下文占用、从任意回复分叉、按项目分组的侧栏、全部设置，电脑和手机（PWA）都能用 |
+| 🔔 | **飞书 + 苹果系统推送** | 除了飞书消息，Web 会话还能推送到 iPhone、iPad 锁屏和 Mac 通知中心（标准 Web Push，不需要开发者账号），图标上显示未读数 |
+| 🗂️ | **桌面端同时接入多台设备** | macOS 桌面端同时连多台服务器，菜单栏一眼看完各台的额度、待处理和运行中的会话 |
+
 ## 能做什么
 
-- **多个 agent**：Claude Code（官方 Claude Agent SDK）、Codex（官方 `codex app-server`）。在同一条会话里 `/agent` 切换，各 agent 的上下文各自保留。
-- **多个飞书机器人**：一个机器人对应一个 agent，或者一个机器人能切换多个 agent，都在设置页里勾选。机器人能在 Web 上扫码创建，改完配置立即生效，不用重启。
-- **Web 聊天页**：电脑和手机都能用，界面参照 ChatGPT。
-  - 回复逐字显示，markdown 和代码高亮，思考过程和工具调用可以折叠。
+- **多个 agent**：Claude Code、Codex。两个 agent 共用工作目录，能看到对方改过的文件，但聊天记录各自独立。
+- **多个飞书机器人**：一个机器人对应一个 agent，或者一个机器人能切换多个 agent，都在设置页里勾选。机器人能在 Web 上扫码创建（Lark 国际版用「手动添加」），改完配置立即生效，不用重启。
+  - 群聊里要 @ 机器人；不同话题是各自独立的会话；支持文字、富文本、图片、文件、语音和视频。
+  - 思考和工具调用显示在实时刷新的过程卡片里，最终回复是普通消息。
+  - 陌生人发消息会拿到配对码，在设置页批准后才能使用；每个机器人单独授权。
+- **Web 工作台**：电脑和手机都能用，界面参照 ChatGPT。
+  - 回复逐字显示，markdown 和代码高亮，思考过程和工具调用可以折叠；每条回复下方显示用时、费用和完成时间，可以复制，也可以「从这里分叉」成一条新会话（原会话不动）。
   - 授权卡、提问卡直接在页面上点。
-  - 支持上传附件（粘贴、拖拽，手机上可以拍照）。
-  - 可以「添加到主屏幕」当 App 用。手机切到后台再回来会自动重连，并补上错过的内容。
-  - 系统通知：回复完成、出错、需要授权或提问时推送到手机 / 电脑（设置 → 通知 里按设备开启）。标准 Web Push，不用注册任何开发者账号；需要 HTTPS 访问，iPhone 需 iOS 16.4+ 且从主屏幕图标打开。
-  - 收到推送时，主屏 / 桌面 PWA 图标上显示未读角标（iOS 16.4+、桌面 Chrome / Edge），打开页面自动清零。
-  - 切换工作目录可以在目录树里一层层点选；新对话发第一条消息前也能先选好目录。
-  - 语音输入：输入框旁的麦克风按钮，用浏览器自带的语音识别（Chrome / Edge / Safari，需要 HTTPS）。
-  - 新对话页：大标题里点目录名切换工作目录；输入框上方的条里选目录和 agent，右下角直接选模型和思考程度（弹出菜单，不用开弹窗）。会话中 agent 不切换（命令 `/agent` 仍可切），模型和思考程度随时可换。
-  - 输入框里显示上下文窗口占用（小圆环，悬停看已用 / 剩余 token）。
-  - 输入框的模型按钮直接显示实际的模型和思考程度（如「Opus 5.5 high」），和选项里的名字一致；列表里显示哪些模型在 设置 → Agent 里勾选。
-  - 每条回复下方显示用时、费用和完成时间，最后一条常驻，前面的悬停才出现；可以复制，也可以「从这里分叉」成一条新对话（只保留到这条回复，原对话不动）。
-  - 侧栏分「最近」和「项目」两组：Web 会话按工作目录归类，飞书机器人各占一行并带飞书图标；分叉出来的对话挂在主对话下面，用虚线连起来；分组可折叠，宽度可拖动，双击会话重命名，名字太长时悬停滚动显示。
-  - 侧栏底部显示 Claude / Codex 的订阅额度（5 小时 / 7 天窗口，悬停看重置时间）；空闲时按设置的间隔自动刷新（默认 10 分钟），跑完一轮后也会刷新。
-- **跨渠道同步**：飞书里的会话在 Web 上也能打开，接着聊。同一个授权请求同时出现在飞书卡片和网页上，哪边先点算哪边，另一边自动变成「已处理」。
-- **设置都在网页上**：工作目录、各 agent 的默认模型和思考程度、Codex 沙箱、飞书机器人、配对批准、Claude 的「总是允许」名单、登录设备管理。
+  - 附件：粘贴、拖拽，手机上可以拍照；可以预览和下载。附件存在服务端的专用上传目录里，开新会话或切换目录时清理。
+  - 语音输入：用浏览器自带的语音识别（Chrome / Edge / Safari，需要 HTTPS）。
+  - 新对话页：点大标题里的目录名，在目录树里逐层选工作目录；输入框上方选 agent，右下角选模型和思考程度。会话进行中用 `/agent` 切换 agent，模型和思考程度随时可换。
+  - 输入框里的小圆环显示上下文窗口占用；模型按钮显示实际的模型和思考程度（如「Opus 5.5 high」）。
+  - 侧栏分「最近」和「项目」两组：Web 会话按工作目录归类，飞书机器人各占一行（右键看历史会话）；分叉出来的会话用虚线挂在原会话下面；会话标题由 agent 自动生成，双击重命名。
+  - 侧栏底部显示 Claude / Codex 的订阅额度（5 小时 / 7 天窗口，以及多久后重置）。
+  - 「添加到主屏幕」后当 App 用；切到后台再回来会自动重连，补上错过的内容。
+- **系统通知**：Web 会话回复完成、出错、需要授权或提问时推送到手机 / 电脑（设置 → 通知 → 「在此设备开启通知」，可以发测试通知）。飞书会话由飞书提醒，正在前台看着的会话不推。需要 HTTPS 访问，iPhone 需 iOS 16.4+ 且从主屏幕图标打开。
+- **跨渠道同步**：飞书里的会话在 Web 上也能打开接着聊。同一个授权请求同时出现在飞书卡片和网页上，哪边先点算哪边，另一边自动变成「已处理」。
+- **授权**：允许一次 / 本会话全部允许 / 总是允许（按钮上写明放行范围）/ 拒绝。`/autoedit on` 让 Claude Code 在这条会话里改工作目录内的文件不再询问（Bash 仍询问）。超时一律按拒绝处理。
+- **设置都在网页上**：工作目录、会话闲置过期时间、局域网访问和端口、各 agent 的默认模型和思考程度、可选模型、Codex 沙箱、飞书机器人、配对批准、Claude 的「总是允许」名单、通知设备、登录设备管理、服务端升级。
 
 ## 安装
 
+需要 Linux 或 macOS，Node.js 22 及以上。
+
 ```bash
 npm install -g agent-loft         # 或者在仓库里 npm install 后用 node bin/cli.js
 agent-loft start                  # 前台运行，日志里会打印首次登录用的设置码
-agent-loft service install        # 注册为开机自启服务（systemd / launchd）
+agent-loft service install        # 注册为开机自启服务（systemd / launchd），日志在 ~/.agent-loft/logs/
 ```
 
-打开 `http://<机器 IP>:8800`：第一次需要输入日志里的设置码，然后设一个登录密码。
+打开 `http://<机器 IP>:8800`（本机用 `http://localhost:8800`）：第一次需要输入日志里的设置码，然后设一个登录密码。设置码找不到的话，直接运行 `agent-loft passwd` 设密码。
+
+到 设置 → Agent 检查 Claude Code、Codex 装好、登录了没有：Claude Code 随 agent-loft 一起安装，只需在服务端终端里登录；Codex 可以点「直接在服务器上安装」。设置 → 通用 里能看到服务端版本，有新版本时点「升级」即可（`npm install -g agent-loft@latest`，以系统服务运行时会自动重启，打开的页面会自动刷新）。
 
-设置 → 通用 里能看到服务端版本，有新版本时点「升级」即可（`npm install -g agent-loft@latest`，以系统服务运行时会自动重启）；设置 → Agent 里能检查 Claude Code、Codex 装好、登录了没有，Codex 可以一键装到服务端上。
+在外面只用飞书的话不需要任何网络配置（机器人由服务端主动连向飞书）。在外面用网页、系统推送和语音输入需要 HTTPS，见下面的「安全」和[产品介绍里的「从外网访问」](docs/产品介绍.md#从外网访问)。
 
 ### macOS 桌面端
 
 到 [Releases](https://github.com/qijieinnet/agent-loft/releases) 下载 `desktop-v*` 里对应芯片的 DMG（Apple 芯片选 arm64，Intel 选 x64），拖进「应用程序」。还没有 Apple 开发者签名，第一次打开如果提示无法验证，到 系统设置 → 隐私与安全性 里点「仍要打开」。
 
-- 同时连多台服务器，左边一栏切换；每台各自登录，切走了也在后台连着，回复完成、需要授权时弹系统通知。
-- 菜单栏图标：悬停看各服务器的 Claude / Codex 额度、待处理和运行中的会话。
+- 同时连多台服务器，顶部标签栏切换、拖动排序；每台各自登录，切走了也在后台连着，回复完成、需要授权时弹系统通知，程序坞图标显示未读数。
+- 菜单栏图标：悬停看各服务器的 Claude / Codex 额度、待处理和运行中的会话；双击打开主窗口。同一个账号的额度只查一次。
 - 支持前面挡着 Cloudflare Access 的服务器：验证页直接在窗口里完成，过期会提醒；也可以配 Service Token 免验证。
-- 首次打开可以选「这台 Mac 也作为服务端」：一键在终端里安装 agent-loft（没有 Node.js 会先用 Homebrew 装）并开机自启，装好自动连上。
-- 服务端有新版本时在服务器列表里点「升级服务端」；桌面端自己的更新在 设置 → 更新 里点「更新并重启」。
+- 首次打开可以选「这台 Mac 也作为服务端」：一键在终端里安装 agent-loft（没有 Node.js 会先用 Homebrew 装）并开机自启，装好自动连上。可选开启「本机有会话在跑时不休眠」。
+- 设置（`⌘,`）的服务器列表里展开某台服务器，能看它的 Agent 环境和版本，有新版本时点「升级服务端」；桌面端自己的更新在同一页的「更新」里点「更新并重启」。
 
 桌面端只是个壳（代码在 `desktop/`），服务端照常用 npm 安装和升级。
 
@@ -85,7 +104,9 @@ agent-loft service install
 | `agent-loft service install \| uninstall \| restart \| status` | 开机自启 |
 | `agent-loft doctor` | 体检 |
 
-聊天里的命令（飞书和 Web 通用；Web 输入框打 `/` 会弹出命令补全，飞书里打 `/` 会弹出机器人的指令面板（agent-loft 自动注册，约 5～8 分钟生效；只发一个 `/` 也会回一张可点击的命令卡片），顺序和显示项在 设置 → 命令 里调整）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/agent [名称]`（或者直接发 `/claude`、`/codex`）`/stop` `/cd <目录>` `/pwd` `/status` `/approve <id> allow-once|allow-always|allow-session|deny` `/help`
+`aloft` 是 `agent-loft` 的简写。
+
+聊天里的命令（飞书和 Web 通用；Web 输入框打 `/` 会弹出命令补全，飞书里打 `/` 会弹出机器人的指令面板（agent-loft 自动注册，约 5～8 分钟生效；只发一个 `/` 也会回一张可点击的命令卡片），顺序和显示项在 设置 → 命令 里调整）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/agent [名称]`（或者直接发 `/claude`、`/codex`）`/stop` `/cd <目录>` `/pwd` `/status` `/autoedit [on|off]` `/approve <id> allow-once|allow-always|allow-session|deny` `/help`；只在飞书里有的：`/web` `/detach`
 
 自定义命令：设置 → 命令 → 「添加命令」，填命令名、说明和一段提示词，之后发 `/命令名 参数` 就会把这段提示词发给 agent（提示词里的 `$ARGUMENTS` 换成参数，没写就把参数接在后面）。按 agent 分开存，可以编辑、删除，也会同步到飞书指令面板。
 
@@ -95,7 +116,7 @@ agent-loft service install
 
 - Web 登录密码用 scrypt 哈希保存。首次设置必须用启动日志里的一次性设置码，防止「谁先打开页面谁就成了主人」。
 - 登录态通过 HttpOnly cookie 保存，服务端只存它的哈希。同一 IP 连续输错 5 次锁 15 分钟。所有写请求和 WebSocket 都校验 Origin。页面开启了严格的 CSP。
-- 暴露到公网时，只通过 HTTPS 反向代理（比如 Lucky）访问，并把反代的 IP 加进 `web.trustedProxies`（只有从这些地址来的连接才采信 `X-Forwarded-*`）。不要直接把 8800 端口映射出去。
+- 暴露到公网时，只通过 HTTPS 反向代理（比如 Lucky）或 Cloudflare Tunnel 访问，并把不在本机的反代 IP 加进 `web.trustedProxies`（只有从这些地址来的连接才采信 `X-Forwarded-*`）。不要直接把 8800 端口映射出去。局域网访问可以在 设置 → 通用 → 网络访问 里关掉。
 - 审批超时一律按拒绝处理。Codex 默认沙箱为 `workspace-write`，不会因为 `~/.codex/config.toml` 里配了 `never` 或 `danger-full-access` 就绕过审批。
 - agent 子进程拿不到本服务自己的凭据（`FEISHU_*`、`AGENT_LOFT_*` 等环境变量会被剔除）。
 
@@ -116,6 +137,8 @@ src/
     feishu/        飞书：一个 FeishuBot 对应一个机器人，支持多个
     web/           HTTP + WebSocket + 鉴权
 web/               前端（原生 JS，不需要构建）
+desktop/           macOS 桌面端（Electron 外壳）
+docs/              产品介绍和截图
 ```
 
 ### 接入新的消息渠道（比如 Telegram）

package/package.json

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

package/src/channels/feishu/attach.ts

@@ -0,0 +1,48 @@
+// 飞书聊天「挂到」Web 会话上：挂上之后，这个飞书聊天说的话、发的命令都送进那条 Web 会话，
+// 那条会话的回复、授权、提问也画到这个飞书聊天里。发 /detach 回到聊天自己的会话。
+//
+// 只是一层路由，会话本身（agent 进程、历史、审批）一点不动。按飞书会话键记：
+//   feishu:<机器人id>:<chatId>[:<话题id>] → web:<…>
+// 一条 Web 会话可以同时被好几个飞书聊天挂着。要落盘：重启之后飞书那边还接着它聊。
+import path from "node:path";
+import { dataDir, readJson, writeJsonAtomic } from "../../home.js";
+
+type Shape = Record<string, { target: string; at: number }>;
+
+const storePath = path.join(dataDir, "feishu-attach.json");
+let cache: Shape | null = null;
+
+function load(): Shape {
+  cache ??= readJson<Shape>(storePath, {});
+  return cache;
+}
+
+function save(): void {
+  writeJsonAtomic(storePath, cache ?? {});
+}
+
+/** 这个飞书会话挂着的 Web 会话键 */
+export function attachedTarget(feishuKey: string): string | undefined {
+  return load()[feishuKey]?.target;
+}
+
+export function attach(feishuKey: string, target: string): void {
+  load()[feishuKey] = { target, at: Date.now() };
+  save();
+}
+
+/** 返回原来挂着的目标（没挂着返回 undefined） */
+export function detach(feishuKey: string): string | undefined {
+  const prev = load()[feishuKey]?.target;
+  if (prev === undefined) return undefined;
+  delete load()[feishuKey];
+  save();
+  return prev;
+}
+
+/** 挂在 target 上的所有飞书会话键（可选只要某个前缀的，也就是某个机器人的） */
+export function watchersOf(target: string, prefix = ""): string[] {
+  return Object.entries(load())
+    .filter(([k, v]) => v.target === target && k.startsWith(prefix))
+    .map(([k]) => k);
+}