# agent-loft 中文文档

规范地址：https://npmcn.com/package/agent-loft/

版本：0\.2\.87
npm 元数据更新时间：2026-11-03T01:26:31.117Z
中文译文更新时间：2026-11-03T02:19:23.864Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/agent-loft
原文对照：https://npmcn.com/package/agent-loft/?lang=original
项目主页：https://github.com/qijieinnet/agent-loft#readme
源码仓库：https://github.com/qijieinnet/agent-loft

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，200 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.13
- 运行依赖：14 个
- 首次发布：2026-10-20T11:40:28.266Z
- 最新版本发布：2026-11-03T01:26:30.772Z
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

多个 agent 的工作台：把本机 Claude Code / Codex 放到一处统一管理，用飞书和 Web 页面随时驱动——会话、审批、模型切换都共用

## 安装

```sh
npm install agent-loft
```

也可以使用：`pnpm add agent-loft`、`yarn add agent-loft`、`bun add agent-loft`

## README

![agent-loft](https://npmcn.com/package/agent-loft/web/icon.svg)

# agent-loft

**多个 agent 的工作台。** 把本机的 **Claude Code**、**Codex**（以后还有更多）放到同一张台面上统一管理，在网页、飞书和桌面端（macOS / Windows / Linux）随时驱动它们，进展推送到飞书、iPhone 和 Mac。

![Web 工作台](https://npmcn.com/package/agent-loft/docs/images/web-chat.png)

> 📖 完整的产品介绍和使用指南见 **[docs/产品介绍.md](https://npmcn.com/package/agent-loft/docs/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D.md)**：六大核心亮点、快速上手、使用指南、命令速查、常见问题和故障排查。

由 `feishu-claude-bridge` 和 `feishu-codex-bridge` 合并而来：一个进程、一份配置，飞书和网页共用同一套会话、审批和模型切换。

## 理念

这里的 Loft 不是阁楼，是**工作台**：agent 是干活的人，agent-loft 是它们共用的那张台面。

-   **多 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 Code / Codex，或者自己配的专家 |
| 🧑‍🏫 | **专家** | 自己配专家：选引擎、写提示词，定它能做什么（只能联网 / 读文件 / 改文件 / 跑命令），挂哪些技能和 MCP，能把活派给哪些子智能体。新对话、定时任务都能选 |
| 🔀 | **飞书机器人灵活绑定 agent** | 机器人数量不限，每个机器人可以直接勾选内置或共享专家，并选择默认专家（可在会话里切换）。网页上扫码就能创建，改完立即生效；由服务端主动连向飞书，家里没有公网 IP 也能在外面用 |
| 🔗 | **飞书续接 Web 任务** | 飞书里发 `/web` 接上一条 Web 会话，或者在网页聊天右上角「更多」或侧栏会话右键菜单里选「在飞书继续」。之后回复、授权、提问都发到飞书，发 `/detach` 回来 |
| 💬 | **微信 ClawBot** | 设置 → 账号里用微信扫码，就能在微信里和 agent 聊天、回数字处理授权和提问，网页上是同一条对话。每个人连自己的微信。微信限制较多，适合发起任务和接收回复，详见下面的说明 |
| 🖥️ | **完整的 Web 工作台** | 流式回复、附件、语音输入、模型和思考程度切换、上下文占用、从任意回复分叉、按项目分组的侧栏、搜索会话、全部设置，电脑和手机（PWA）都能用 |
| 🔔 | **飞书 + 苹果系统推送** | 除了飞书消息，Web 会话还能推送到 iPhone、iPad 锁屏和 Mac 通知中心（标准 Web Push，不需要开发者账号），图标上显示未读数 |
| 🗂️ | **桌面端同时接入多台设备** | 桌面端（macOS / Windows / Linux）同时连多台服务器，菜单栏 / 托盘一眼看完各台的额度、待处理和运行中的会话 |

## 能做什么

-   **多个 agent**：Claude Code、Codex。两个 agent 共用工作目录，能看到对方改过的文件，但聊天记录各自独立。
    
-   **多个飞书机器人**：设置 → 飞书 →「可用专家」直接勾选内置或共享专家，并选择「默认专家」。只勾一个共享专家即可专用，不用再勾选底层 Agent；每个人绑定自己的账号后，直接私聊就是这个专家，使用各自的记忆和工具。机器人能在 Web 上扫码创建（Lark 国际版用「手动添加」），改完配置立即生效，不用重启。
    
    -   群聊里要 @ 机器人；不同话题是各自独立的会话；支持文字、富文本、图片、文件、语音和视频。
    -   思考和工具调用显示在实时刷新的过程卡片里，最终回复是普通消息。
    -   陌生人发消息会拿到配对码，在设置页批准后才能使用；每个机器人单独授权。
-   **Web 工作台**：电脑和手机都能用，界面参照 ChatGPT。
    
    -   回复逐字显示，markdown 和代码高亮，思考过程和工具调用可以折叠；每条回复下方显示用时、费用和完成时间，可以复制，也可以「从这里分叉」成一条新会话（原会话不动）；自己发的消息也能一键复制。
    -   agent 做多步骤的活时列的任务清单显示在输入框上方，看得到做到第几项、正在做哪一项。
    -   授权卡、提问卡直接在页面上点。
    -   附件：点击输入框的「+」直接上传，也可以粘贴、拖拽，手机上可以拍照；可以预览和下载。附件存在服务端的专用上传目录里，发出去的都收进资料库，开新会话、切换目录也不删；删除会话时立即清理。
    -   回复里提到的文件（链接、`路径`、正文里的绝对路径，Claude 和 Codex 都认）点一下就能预览：图片、PDF、音视频、markdown、代码和文本直接看，网页渲染出来看（也能切到源码），其它的下载。Codex 的 visualize 插件画的图表（回复里的 `visualize{"path":…}`）和官方客户端一样直接嵌在回复里。网页和图表放在沙箱里显示，碰不到登录态和本站接口。
    -   **回复里的图**：专家和 agent 在回复里写 ` ```chart `（一段 JSON：折线、面积、柱状、饼图、散点）就画成可悬停的图，可以切到表格看具体数字；写 ` ```mermaid ` 画流程图、时序图等。跟着系统深浅色走，图库用到时才加载；飞书上 chart 换成表格。写法自动附在每个专家（包括内置的 Claude Code、Codex）的提示词里。只认这条对话里 agent 回复写过的路径；私钥、`.ssh`、`.env`、各种凭据和 agent-loft 自己的配置数据一律不给看。
    -   **回复里的相册**：agent 用 ` ```album ` JSON 描述多张本地照片，网页显示缩略图网格，每页 12 张、懒加载；点开大图可左右切换，也支持方向键和 Esc。可附名称、拍摄日期、说明和查询总数，每个相册最多 200 张；飞书显示简短摘要。写法自动附在所有专家的提示词里，图片沿用会话文件权限。
    -   聊天右上角「更多」和侧栏会话右键菜单共用分叉、重命名、在飞书继续、删除操作，按会话类型和可用机器人显示。
    -   语音输入：用浏览器自带的语音识别（Chrome / Edge / Safari，需要 HTTPS）。
    -   新对话页：点大标题里的目录名，在固定高度的目录弹窗里逐层选工作目录，也能新建文件夹；输入框上方选专家，鼠标停在专家上看简介，右下角选模型和思考程度。对话从头到尾一个专家，要换专家就新建对话；模型和思考程度随时可换。
    -   输入框里的小圆环显示上下文窗口占用；模型按钮显示实际的模型和思考程度（如「Opus 5.5 high」）。
    -   滚动和 ChatGPT 一样：发出的问题顶到最上面、下面留白，回复长到屏幕底部才跟着往下滚；回复过程中自己滚动了就不再自动滚，下次发消息再恢复。
    -   定时发送：右上角「更多」→「定时发送」，默认排在 5 小时额度重置后 5 分钟（弹窗里提示 5 小时 / 7 天额度的重置时间），由服务端到点发出，关掉页面也会发。适合额度用完、要等刷新才能接着干活的时候。
    -   侧栏直接显示各个文件夹，Web 会话按工作目录归类（目录可以拖动排序，右键可置顶；排好的顺序跟着账号走、各设备一致，新消息不会打乱），飞书会话按机器人分组，微信的当前与历史会话按账号分组，两者都能展开 / 折叠并记住状态，收起时仍显示运行中和待处理提示，展开即可查看历史会话。渠道分组行右侧始终显示飞书或微信的静态图标，Web 页面不提供这些分组的新建会话入口。项目名、渠道分组名和有分叉的会话后面有个小三角，点一下折叠 / 展开（分叉折叠后显示「N 个嵌套会话」）；分叉出来的会话缩进挂在原会话下面，用一条细线连着；标题放不下时尾巴淡出；Web 和飞书会话都先用首条消息命名，再同步 agent 自动生成的标题，旧飞书会话会从历史记录补名，双击可手动重命名；鼠标移到会话上，行尾显示对应的专家图标；定时任务的时钟图标始终放在最右侧。
    -   **搜索**：侧栏「搜索」弹窗，搜全部会话的标题、目录名和聊天内容（不开记忆也能搜），可以按专家筛；电脑和手机上弹窗都固定高度，结果在内部滚动，手机上从底部展开；↑↓ 选、回车打开。
    -   **侧栏菜单**：项目上方的「更多」支持点击或鼠标悬停展开，设置入口也在这里。「编辑侧边栏」可勾选直接显示的菜单、拖动调整顺序，未勾选的收进「更多」；配置跟着账号走，电脑和手机共用。
    -   会话页顶部标题前是专家的头像，PC 端头像与会话名称字号一致（15px）；鼠标停上去或点一下，看专家的说明、模型、能力、当前工作目录和本会话 Token 用量。
    -   附件可以直接拖到聊天区任意位置上传。
    -   回复过程中接着发的消息排队，标着「排队中」，隐藏底部的复制和回退按钮，上一条回复完自动接着处理；点「撤销并编辑」图标把排队消息放回输入框；点「打断并发送」停掉正在进行的回复、马上处理这条；点停止则连排着的一起取消（标「没有发出」）。
    -   用户消息的复制按钮后有「回退到此处」图标：把这条消息及附件放回输入框，并删除它及之后的聊天内容，重新发送时从之前的上下文继续。
    -   太长的消息先收起，点「展开显示」看全文；对话里有至少 3 条用户消息时，右侧显示快速定位尺，电脑上鼠标移入查看消息开头、点击跳转；手机上手动滚动时显示短轨道，按住拖动可预览问题和位置，松手跳转，停止操作约 1.6 秒后隐藏。
    -   回复底部的 token 数自动按大小显示为 K、M 等单位。
    -   项目右键（触屏长按）可「删除项目…」：二次确认后删除文件夹及全部文件、子目录和关联会话，同时清理附件、资料库文件和定时发送；目录选择器里也可删除空文件夹。工作区根目录、包含其他用户会话的目录不能删除，Agent 自己保存的原始会话记录仍保留。
    -   侧栏按页加载：每个项目目录和飞书机器人分组先显示 5 条，点「展开显示」每次再拉 10 条。
    -   项目、飞书和微信分组可混合拖拽排序，渠道分组可以放在项目前面或项目之间；右键（触屏长按）可置顶、上移、下移或按最近活跃重排。顺序按账号保存，刷新、换设备后保留，新消息不会改变已排好的位置。
    -   侧栏底部显示 Claude / Codex 的订阅额度（5 小时 / 7 天窗口，以及多久后重置）；关了额度查询就整块不显示。
    -   专家信息弹窗底部显示当前会话累计消耗的 Token 分布（输入 / 缓存写入 / 缓存读取 / 输出，Claude 还有按 API 价格估算的费用）。设置入口在侧栏的「更多」里。
    -   设置 → 用量：按日 / 月 / 年（默认按月）统计 token 和金额，有每天（每月）的柱状图，按 agent、模型、用户（管理员才有）分开看；成员只看到自己的。管理员还可查看服务端本机直接使用的 Claude Code、Codex 桌面端和 CLI 用量，和 Agent Loft 的用量分开显示、避免重复计算。金额都是按 API 价格算的参考值：Agent Loft 的 Claude 用它自己报的费用，Codex 和直接用的 Claude Code 按模型单价 × token 估算（OpenAI 单价来自 LiteLLM 公开价格表，内置快照、联网时每天更新）。Agent Loft 的账从 0.2.34 开始记录；本机直接使用的用量可回溯已有会话记录。
    -   「添加到主屏幕」后当 App 用；切到后台再回来会自动重连，补上错过的内容。
    -   前端资源按指纹长缓存：再次打开不用逐个向服务端确认，升级或改了文件后刷新页面自动换新。
    -   手机顶栏采用实色圆形按钮和「专家＋更多」胶囊按钮组；从左边缘右滑展开侧栏，在侧栏或遮罩上左滑收起，短滑会回弹。消息底部操作栏与下一条消息之间留 4px。
-   **网页多服务器切换**：在 设置 → 服务器 添加其他 agent-loft，再点「授权」到对方页面确认，侧栏左上角通过名称和紧随其后的箭头切换，不显示服务器图标，嵌入桌面端时隐藏此入口；各台分别登录，切走后保持连接，列表显示待处理数和运行状态，刷新后保留选择。几台需使用同一主域名下的 HTTPS 地址（例如 `mac.example.com`、`nas.example.com`）。在外层页面开启系统通知后，各台的提醒都能推到同一个主屏幕 App，点通知自动切到对应服务器和对话。见[使用指南](https://npmcn.com/package/agent-loft/docs/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D.md#%E5%9C%A8%E7%BD%91%E9%A1%B5%E5%92%8C%E6%89%8B%E6%9C%BA%E4%B8%8A%E5%88%87%E6%8D%A2%E5%A4%9A%E5%8F%B0%E6%9C%8D%E5%8A%A1%E5%99%A8)。
    
-   **系统通知**：Web 会话回复完成、出错、需要授权或提问时推送到手机 / 电脑（设置 → 系统 → 系统通知 → 「在此设备开启通知」，可以发测试通知）。飞书会话由飞书提醒，正在前台看着的会话不推。需要 HTTPS 访问，iPhone 需 iOS 16.4+ 且从主屏幕图标打开。
    
-   **跨渠道同步**：飞书里的会话在 Web 上也能打开接着聊。同一个授权请求同时出现在飞书卡片和网页上，哪边先点算哪边，另一边自动变成「已处理」。
    
-   **授权**：允许一次 / 本会话全部允许 / 总是允许（按钮上写明放行范围）/ 拒绝。权限级别（输入框左下角或 `/permission`）：逐次询问 / 自动改文件 / 完全允许，定时任务也可以单独设，完全允许只给管理员。`/autoedit on` 让 Claude Code 在这条会话里改工作目录内的文件不再询问（Bash 仍询问）。超时一律按拒绝处理。
    
-   **设置都在网页上**，按用途分组：**我的**（账号、飞书和微信绑定、自己的登录设备、记忆、专家、技能、MCP、用量）；**Agent**（运行环境置顶，各 agent 卡片分别配置默认模型、思考程度、可选模型、个人默认技能和 MCP，Codex 沙箱、额度查询；工作目录、会话闲置过期、授权卡超时和 Claude 的「总是允许」名单；「/」命令）；**连接**（飞书机器人、配对批准、指令面板同步；远程控制；服务器）；**管理**（用户标题旁添加用户，用户的「管理 → 登录设备」查看和下线各自设备；系统页管理服务端版本和升级、重启、局域网访问和端口，网络访问下方是系统通知；成员也可在系统页设置自己的通知）。账号页通过「修改名称」「修改密码」按需展开表单；飞书和微信绑定操作位于卡片右上角。设置、新建 / 编辑专家、重命名等编辑弹窗不会因点击外部或按 Esc 关闭；通过关闭、取消或保存 / 完成按钮退出。改了没保存就切页或关掉设置会先提醒。
    
-   **多用户**（信任型）：管理员在 设置 → 用户 里给别人建账号。每个人只看得到自己的对话、授权和通知；个人设置各自管理，服务器设置由管理员修改，见下面「安全」。
    
-   **专家**：设置 → 专家。专家是一份配置，新建对话、定时任务时选一个，对话从头到尾都是它（中途不能换；飞书里 `/expert 名字`、`/claude`、`/codex` 换专家会开新会话）。**内置专家**：Claude Code、Codex，保留原装提示词和所有工具，默认技能与 MCP 在「设置 → Agent」中按账号、按引擎分别选择。**自定义专家**由创建者管理，可以勾选「共享给所有账号」。共享后，其他人能在网页、绑定账号后的飞书私聊和定时任务中选择它；只有创建者能修改设定。每个人在该专家的「我的工具」里选择自己的技能和 MCP，使用各自的变量、凭据、记忆和聊天记录；创建者沿用原有工具选择，其他人未配置时不加载技能或 MCP。取消共享后，其他人的历史对话保留，后续消息不能继续调用该专家，相关定时任务在下次运行时暂停。可以配：
    
    -   头像（点头像区域的加号上传；未上传时，会话中用引擎的图标）、引擎（Claude / Codex，建好后不能换）、默认模型和思考程度（从模型列表里选）；
    -   提示词：人设、规则、输出格式。agent-loft 在后面自动补上这个专家能做什么、今天的日期、记忆。Claude 专家默认只用这段提示词（一句话约 2 千 token），也可以选「追加在 Claude Code 原装提示词后面」（干活更稳，每轮多约 1.6 万）；Codex 的基础指令改不了，专家的提示词附在第一条消息后面，约束力弱一些；
    -   权限，勾选：联网搜索、读网页，以及文件权限（一级包含一级）：都不勾就是**只能联网**（不碰本机文件、不弹授权，文本附件内容直接放进消息）／**能读文件**／**能改文件**／**能跑命令**（跑命令就等于能改任何文件，需要授权时弹卡）。Claude 按权限给工具；Codex 按权限开 shell、apply\_patch，沙箱只读或 workspace-write；
    -   带不带个人记忆，默认工作目录，新对话页上的欢迎语和快捷提问；
    -   技能：只给选中的（Claude 用技能白名单，没选的调不了；没选技能就不挂 Skill 工具，省 token）；
    -   MCP：从「设置 → MCP」里勾（管理员还能勾机器上配的）；
    -   子智能体（只有 Claude）：别的 Claude 专家，主专家用 Agent 工具把子任务派给它。子智能体的权限不能超过主专家（运行时也封顶在主专家的权限）。
    
    只勾联网搜索、读网页的 Claude 专家就是以前聊天模式的效果。专家改了，用它的对话下一条消息起生效；专家删了，用它的对话还能看、不能再发消息，用它的定时任务暂停。以前的聊天模式取消了：升级后聊天模式的旧对话不再保留，聊天模式的定时任务暂停，选个专家再启用。
    
-   **MCP**：设置 → MCP，每人管自己的：本机进程（命令 + 参数 + 环境变量）或 HTTP 地址（+ 请求头），值可以标成密钥（网页上不回显，只交给 MCP 进程或请求头，不进提示词）。可以设「调用前询问」，不设就直接用。自定义专家加载各自勾选的服务；内置专家在「设置 → Agent → 对应 Agent 卡片 → 默认加载」里选择，支持个人 MCP、管理员可选的机器 MCP，也可全部取消；不指定时管理员沿用机器配置。
    
-   **记忆**：像 ChatGPT 的记忆，设置 → 记忆（默认关）。「关于我」加上一条条记住的事，每次对话都带上；agent 在聊天里遇到长期有用的信息会自己用 `remember` 记一条（回复里会说），记错了用 `forget` 删。**自动整理**：把上次整理之后新说的话交给模型（不留会话记录的一次性调用），补充、更新或删掉过时的记忆，用户自己加的条目它不动。什么时候整理每个人自己定：每天一次（默认凌晨 2 点，把当天的对话合起来一次整理，最省）／每段对话聊完后（停多久可选，改了什么会在对话里说一声）／只在点「现在整理」时／不整理；整理哪些对话也能选：全部／只整理选中专家的对话；用哪个 agent 的哪个模型也能选，默认 Claude Haiku，没有 Claude 就用 Codex 的默认模型、思考程度 low。**参考以前的聊天**：agent 遇到「上次说的那个……」会用 `search_past_chats` 搜你以前的对话（关键词搜索，只有你自己的、没被删掉的对话）。聊天记录索引不开记忆也会记（侧栏的「搜索」也用它），升级后会把已有对话收录进来一次；没开记忆时记进来的不拿去整理。两项都能在设置里单独关。每个用户一份，Claude 和 Codex、Web 和飞书共用。只用在有主人的对话里：你的 Web 对话，以及绑定了飞书账号后和机器人的私聊；飞书群聊不用。别人（包括管理员）看不到你的记忆，管理员只能清空它；删用户时记忆一起删，不转给管理员。
    
-   **定时任务**：像 ChatGPT 的 Tasks，侧栏的「定时任务」。到点把一段提示词交给 agent，结果发回对话：一次 / 每天 / 工作日 / 每周 / 每月 / 每隔几小时 / 自定义 cron，按服务端时区，两次至少隔 15 分钟。**有需要才提醒**（默认）：agent 自己判断这次有没有要告诉你的事（比如「有新版本才告诉我」），没有就在回复第一行写 `[[静默]]`，推送、飞书都不发，对话里折叠成一行；没写暗号一律照常提醒。结果发到**专用对话**（任务自己的一条对话，第一次运行时新建、之后续用，可选专家和目录；可以设成不携带上下文，每次运行都换新会话，之前的结果还留在对话里，只是 agent 看不到），在专用对话右上角的「更多」里可以直接编辑任务、立即运行，或者**原来的对话**。也能直接在对话里说「每天早上 9 点帮我……」：agent 用 `create_task` / `update_task` / `delete_task` / `list_tasks` 工具管理，新建、修改、删除都会先弹授权卡让你确认（只有暂停不用；没有「总是允许」），任务自己运行的那一轮里不能再建、改、删任务。按人隔离：每人只看得到、改得了自己的任务（最多 30 个），删用户时一起删；到点再核对一次对话还是不是他的，对话被删或换了主人就暂停任务。到点对话在忙（正在回复或挂着授权）就等它，最多 30 分钟；服务停着时错过 2 小时以内的启动后补跑一次。工具和记忆一样只给有主人的对话，飞书群聊里没有。
    
-   **技能（skills）**：设置 → 技能。技能就是 Claude Code / Codex 用的那种 SKILL.md（可以带脚本和资料），由 agent-loft 按人管理，两个 agent 都能用。**来源**：在页面上写、上传技能包（`.zip` / `.skill` / 单个 SKILL.md / 整个文件夹），或者在对话里让 agent「把刚才的做法存成技能」（agent 用 `create_skill` / `update_skill`，先弹授权卡）。**共享**：新建、编辑时选择「仅自己可见」「指定用户」或「所有人可见」，也可在自己技能的「更多 → 共享」里调整；默认仅自己可见。其他用户在「共享技能」中查看正文和附带文件、安装；安装后出现在「我的技能」，可停用、卸载或重新安装。安装的是作者的同一份技能，更新自动跟随；作者撤回共享后，范围外用户不再可用。只有作者能编辑，管理员可下架自己看得到的共享技能。共享不包含作者填写的变量和密钥，每人使用自己的配置。**使用**：内置专家默认使用你启用的全部技能，也可以在「设置 → Agent」中分别指定 Claude Code / Codex 加载哪些技能；自定义专家只用它选中的；agent 遇到对得上的事自己用。**变量**：技能可以声明要用的环境变量（接口地址、密钥），每个人填自己的值，只注入自己的会话；密钥再写上「只允许发往」的地址就成了**受保护的密钥**——不进环境变量，agent 看不到值，只能用 `skill_request` 工具让 agent-loft 代发请求（在地址、请求头、请求体里写 `{{变量名}}`），只发往你确认过的地址、不跟随跳转、响应里出现的值会被抹掉；作者后来改了地址，要你再确认一次才放行。**机器上原有的技能**（`~/.claude/skills`、`~/.agents/skills`、插件市场和 claude.ai 同步的）只给管理员：成员的会话里看不到、调不了（Claude 用技能白名单，`/技能名` 也会被拦下；Codex 关掉它自己的技能清单），管理员在「设置 → 技能 → 本机技能」里能看到。
    
-   **资料库**：像 ChatGPT 的资料库，侧栏的「资料库」。对话里发过的附件、agent 回复里给出的、这一轮新写出来的图片 / 文档 / 音视频（复制一份收进来，之后原文件改了删了不影响）都汇总在这里：按图片 / 文档 / 音视频筛、按文件名搜，点开看大图或下载，「在新对话里用」，单个或批量删除（文件从磁盘上删掉）。从资料库拿到对话里的文件硬链接进那条对话的上传目录，不占双份空间，agent 照常能读。按人隔离，规则同对话：自己的；没主人的对话（飞书群聊等）的归管理员。上传了一直没发出去的一天后清掉；删除会话时立即清理该会话的上传文件和资料库记录，删除原件也会清理复用到其他会话的副本。agent 侧的会话记录仍保留，恢复会话不会恢复已删除的文件。
    
-   **远程控制**：侧栏「定时任务」下面的「远程控制」，直接操作这台机器的**桌面**和**终端**，上面一键切换；切回对话时连接留在后台（侧栏入口上亮个小绿点），再进来接着用。这台机器没有图形桌面（服务器、NAS）时只有终端。
    
    -   桌面：走 VNC 协议，网页里用 noVNC 显示，鼠标、键盘、剪贴板都能用，进来时不自动连、点「连接桌面」才连，工具栏上选画质：流畅 / 标准（默认）/ 高清由服务端把画面缩小到长边 1280 / 1920 / 2560、只把变了的地方压成 JPEG 发过来（macOS 屏幕共享只给无损的 ZRLE，5K 屏一整屏 30MB，原样转发隔着公网几秒一帧），原画是原样转发、只适合局域网；远程那边接了几块屏时可以只看其中一块（按系统里的显示器名称选，服务端只截那块再缩，比几块屏拼在一起缩小清楚得多；macOS 的各块屏位置要从屏幕共享发来的画面里学，第一次连上要几秒，原画下不能选）；可以缩放到窗口或按原始大小看、全屏（手机上也能，iPhone 上是铺满页面）、「只看不控制」、发送 Ctrl+Alt+Del 之类的组合键。手机上有两种手势（右上角切换，「?」看说明）：**触控板模式**（默认）屏幕上有个指针，单指滑动移动、轻点单击、双指轻点右键、长按后拖动是按住左键拖、双指滑动滚动；**触摸模式**点哪就点哪。两种模式都能双指捏合在本地放大画面（放大后小按钮也点得准，右下角「还原」），画面下面一排 Esc / Tab / Ctrl / Alt / Win / 方向键，Ctrl、Alt、Win 点一下会粘住，带给下一个按键或点击；键盘按钮弹出软键盘打字，中文输入法也能用。Linux 上 agent-loft 在有人连时用 x11vnc 共享当前的桌面（Xorg 会话；只听 127.0.0.1、随机端口、每次随机密码，需要 `sudo apt install x11vnc`），没人连着 30 分钟后停掉；macOS 上在 设置 → 远程控制 里改用「已有的 VNC 服务」，接系统自带的屏幕共享：填 VNC 密码，或者屏幕共享没开 VNC 密码时填 Mac 的用户名和登录密码（苹果认证，由服务端登录）。
    -   终端：进入或刷新页面时不自动连接，点击「连接终端」后接上后台终端，没有现成的才新建；也可直接点击「新建终端」。新终端开在当前对话的工作目录里，可以开多个标签；`Ctrl+Shift+C` / `Ctrl+Shift+V` 复制粘贴。`` Ctrl+` `` 在对话下面拉出终端面板（高度可拖动），面板和远程控制里的是同一批终端。关掉页面、手机切到后台、断线都不结束 shell，重新打开后手动连接即可接着用、补上错过的输出，别的设备上也能接上；没有页面连着超过 30 分钟（设置里可改）才结束，点标签上的 × 立即结束。依赖可选的原生模块 `node-pty`：Linux 上安装时要现场编译（需要 `make`、`g++`、`python3`），没装好时终端用不了，其他功能照常。手机上单指上下滑翻看历史（在 less、vim 里是翻页），长按选中文字、接着拖动扩大选区，再点「复制」；终端下面多一排 Esc / Tab / Ctrl / Alt / 方向键 / Home / End / PgUp / PgDn / 粘贴。iOS 上软键盘弹出来时这排键会垫到键盘上面。
    -   管理员能用；成员要管理员在 设置 → 用户 里单独「开通远程控制」。终端、桌面在 设置 → 远程控制 里各有总开关。
-   **微信 ClawBot**：设置 → 账号 → 微信 →「扫码连接微信」，用手机微信扫码并确认（要求微信 8.0.70 以上，「设置 → 插件」里有 ClawBot；这个功能腾讯还在逐步放量）。每个人连自己的微信，会话归扫码的人，用他的记忆和工具，只认扫码的这个微信号；发送 `/new` 创建独立会话并保留旧记录，Web 微信分组里可以查看和续聊历史；服务端主动连向腾讯，不需要公网地址。微信里发文字或语音（要微信能转成文字），不发过程，只显示「正在输入」，结束后发结果；授权和提问是一条文字，回复数字处理（`1` 允许一次、`0` 拒绝，含义固定），网页上也能处理。`/new`、`/stop`、`/model`、`/expert` 等命令都能用。连接后可在同一设置页的「微信使用的专家」中选择专家并点击「切换专家」，也能在首次发微信消息前选好；已有聊天内容时，切换会创建独立会话并保留旧记录，和微信里的 `/expert` 共用同一份选择。
    
    微信的限制（官方没公布具体数字，以下来自社区实测，agent-loft 按此处理）：每条入站消息之后约能发 10 条，所以长回复每次发 3 段，回「继续」接着发，额度用完时在网页上说明；约 24 小时没在微信里说话后微信会拒绝发送，定时任务的结果可能发不过去，这时改走网页提示和系统推送。接口受理了但没给 `message_id` 时手机可能没收到（微信可能在静默限制账号），设置页和对话里会提示。Web 上说的话回复留在 Web，不花微信的额度。暂不支持群聊和收发图片、文件。
    
    消息会经过腾讯服务器，腾讯保留限制、拦截和终止服务的权利（《微信 ClawBot 功能使用条款》）。建议先用小号，不要反复重新扫码（有开发者反映会触发风控）。如果走了代理，让 `ilinkai.weixin.qq.com` 和 `*.cdn.weixin.qq.com` 直连。
    
-   **飞书账号绑定**：设置 → 账号 → 飞书账号 →「生成绑定码」，再在飞书私聊机器人发 `/bind 绑定码`（10 分钟内有效，群里发不算）。绑定后这个私聊就是你的个人会话：用你的记忆，`/sessions` 只列你的会话，`/web` 只能接上你自己的 Web 会话，管理员在 Web 上也看不到它。必须本人在两边各操作一次，管理员不能替人绑定（只能解除），否则就能借飞书读到别人的记忆。
    

## 安装

需要 Linux 或 macOS，Node.js 22.13 及以上。

```bash
npm install -g agent-loft         # 或者在仓库里 npm install 后用 node bin/cli.js
agent-loft start                  # 前台运行，日志里会打印首次登录用的设置码
agent-loft service install        # 注册为开机自启服务（systemd / launchd），日志在 ~/.agent-loft/logs/
```

打开 `http://<机器 IP>:8800`（本机用 `http://localhost:8800`）：第一次需要输入日志里的设置码，然后建一个管理员账号（用户名默认 `admin`）。设置码找不到的话，直接运行 `agent-loft passwd` 设密码。

到 设置 → Agent 检查 Claude Code、Codex 装好、登录了没有：Claude Code 随 agent-loft 一起安装，只需在服务端终端里登录；Codex 可以点「直接在服务器上安装」。设置 → 系统 里能看到服务端版本，有新版本时点「升级」即可（`npm install -g agent-loft@latest`，以系统服务运行时会自动重启，打开的页面会自动刷新）。

在外面只用飞书的话不需要任何网络配置（机器人由服务端主动连向飞书）。在外面用网页、系统推送和语音输入需要 HTTPS，见下面的「安全」和[产品介绍里的「从外网访问」](https://npmcn.com/package/agent-loft/docs/%E4%BA%A7%E5%93%81%E4%BB%8B%E7%BB%8D.md#%E4%BB%8E%E5%A4%96%E7%BD%91%E8%AE%BF%E9%97%AE)。

### 桌面端（macOS / Windows / Linux）

到 [Releases](https://github.com/qijieinnet/agent-loft/releases) 下载 `desktop-v*` 里对应的安装包：

-   **macOS**：对应芯片的 DMG（Apple 芯片选 arm64，Intel 选 x64），拖进「应用程序」。还没有 Apple 开发者签名，第一次打开如果提示无法验证，到 系统设置 → 隐私与安全性 里点「仍要打开」。
-   **Windows**：`Agent-Loft-Setup-*-x64.exe`，装在用户目录里，不用管理员权限。没有代码签名，SmartScreen 拦的话点「更多信息 → 仍要运行」。
-   **Linux**：Debian / Ubuntu 用 deb（`sudo apt install ./agent-loft-desktop_*_amd64.deb`），其他发行版用 AppImage（需要 libfuse2）；ARM 选 arm64。App 内一键更新只支持 AppImage。GNOME 要装 AppIndicator 扩展才看得到托盘图标。

下面以 macOS 为例，Windows / Linux 上「菜单栏」是托盘、`⌘` 是 `Ctrl`：

-   同时连多台服务器，顶部标签栏切换、拖动排序；每台各自登录，切走了也在后台连着，回复完成、需要授权时弹系统通知，程序坞图标显示未读数。
-   菜单栏图标：悬停看各服务器的 Claude / Codex 额度、待处理和运行中的会话；双击打开主窗口。同一个账号的额度只查一次。（Windows 上点托盘图标弹出；Linux 上在托盘菜单里点「额度和待处理」。）
-   菜单栏图标可以换成额度条：Claude、Codex 各是一只像素小宠物，看样子就知道是谁，身子是 5 小时额度，下面一条是周额度。桌面端设置 → 额度显示 →「菜单栏显示额度」，选所有服务器合起来（取最高），或者按服务器分别选 Claude / Codex（图标上不写服务器名）；都不选就只显示图标。「额度条显示」选实心表示剩余额度（默认，像电池）还是已用额度。只有 macOS 有，Windows / Linux 的托盘图标太小放不下。
-   支持前面挡着 Cloudflare Access 的服务器：验证页直接在窗口里完成，过期会提醒；也可以配 Service Token 免验证。
-   首次打开可以选「这台 Mac 也作为服务端」：一键在终端里安装 agent-loft（没有 Node.js 会先用 Homebrew 装）并开机自启，装好自动连上；设置里可以改成「只在桌面端运行时运行」（不开机自启，打开桌面端时启动、退出时停止）。Linux 上一样（需要先装好 Node.js 22.13+，开机自启用 systemd 用户服务）；Windows 上服务端还没有开机自启，可以在 WSL 里装，桌面端会自动检测到 `127.0.0.1` 上的它。防休眠：本机有会话在跑时不休眠；另有永不休眠、定时休眠（设休眠时段，时段外不休眠，时段内本机没有会话在跑、屏幕锁上后让 Mac 睡下去）和合盖不休眠（macOS，第一次开关要输管理员密码，之后不用；开着时闲置也不睡，定时休眠到点会临时关掉它让 Mac 睡下去，醒来再打开）。
-   macOS 从系统菜单「显示 → 用量汇总」（`⌘⇧U`）打开汇总页，Windows / Linux 也可点顶栏服务器标签后面的用量按钮（柱状图图标）：从所有已添加服务器拉取 token 和费用，包括各服务器本机直接使用的 Claude Code、Codex 桌面端和 CLI（仅管理员可见）。按日 / 月 / 年统计，和网页设置 → 用量一样有柱状图和按 agent、模型、用户的分项，另外多一栏按服务器来源。采集在各服务端完成：读取运行服务的系统用户下 `~/.claude/projects`、`~/.codex/sessions` 和 `archived_sessions`（支持 `CLAUDE_CONFIG_DIR` / `CODEX_HOME`），按服务器时区记日期，并跳过 Agent Loft 已记账的会话。桌面端不再扫描本机文件；这台电脑的直接用量也需要添加本机服务端才能统计。不在线、没登录或缺少用量接口的服务器不计入，页面上会注明；有旧版用量接口但不支持本机采集的，会提示升级。
-   macOS 从系统菜单「Agent Loft → 设置…」（`⌘,`）打开桌面端设置，Windows / Linux 也可点顶栏设置按钮。在服务器列表里展开某台服务器，能看它的 Agent 环境和版本，有新版本时点「升级服务端」；桌面端自己的更新在同一页的「更新」里点「更新并重启」。

桌面端只是个壳（代码在 `desktop/`），服务端照常用 npm 安装和升级。

桌面端一键安装的服务端放在 `~/.local`，无需管理员权限，也不修改 npm 的全局配置。如果旧版桌面端安装时出现 `EACCES /usr/local/lib/node_modules/agent-loft`，可以先在终端执行：

```bash
npm install -g --prefix "$HOME/.local" agent-loft
PATH="$HOME/.local/bin:$PATH" "$HOME/.local/bin/agent-loft" service install
```

第一条成功后再执行第二条，然后重新打开桌面端，选择连接本机服务端即可。需要 Node.js 22.13 以上。

### 从旧桥接器迁移

```bash
agent-loft import --dry-run       # 先看会导入什么
systemctl --user disable --now feishu-claude-bridge feishu-codex-bridge   # 同一个机器人不能被两个程序同时连
agent-loft import                 # 导入机器人凭据、白名单、配对、会话绑定、总是允许名单
agent-loft service install
```

导入后，飞书群里原来的会话会接着聊。

## 命令

| 命令 | 作用 |
| --- | --- |
| `agent-loft start` | 启动 |
| `agent-loft import [--only claude|codex] [--disabled] [--dry-run]` | 从旧桥接器导入 |
| `agent-loft pair list | approve <码> | revoke <机器人id> <open_id>` | 配对管理（Web 设置页里也能做） |
| `agent-loft passwd [新密码] [--user 用户名]` | 重置 Web 登录密码（默认是最早的管理员），他的设备全部下线 |
| `agent-loft user list | add <用户名> [--admin] | passwd <用户名> | role <用户名> admin|member | disable | enable | remove` | 管理 Web 登录用户（设置 → 用户 里也能做） |
| `agent-loft service install | uninstall | restart | status` | 开机自启 |
| `agent-loft doctor` | 体检 |

`aloft` 是 `agent-loft` 的简写。

聊天里的命令（飞书和 Web 通用；Web 打开页面时会预加载当前专家和目录的命令，输入框打 `/` 会弹出命令补全，飞书里打 `/` 会弹出机器人的指令面板（agent-loft 自动注册，约 5～8 分钟生效；只发一个 `/` 也会回一张可点击的命令卡片），顺序和显示项在 设置 → 命令 里调整）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/stop` `/cd <目录>` `/pwd` `/status` `/permission [ask|edit|full|default]`、`/autoedit [on|off]` `/approve <id> allow-once|allow-always|allow-session|deny` `/help`；只在飞书里有的：`/expert [名称]`（或者直接发 `/claude`、`/codex`，换专家会开新会话）`/web` `/detach` `/bind <绑定码>`

自定义命令：设置 → 命令 → 「添加命令」，填命令名、说明和一段提示词，之后发 `/命令名 参数` 就会把这段提示词发给 agent（提示词里的 `$ARGUMENTS` 换成参数，没写就把参数接在后面）。按 agent 分开存，可以编辑、删除，也会同步到飞书指令面板。

## 安全

这个服务能让 agent 在你的机器上执行命令，等于一个远程 shell。

-   Web 登录密码用 scrypt 哈希保存。首次建管理员必须用启动日志里的一次性设置码，防止「谁先打开页面谁就成了主人」。
-   管理员在 设置 → 用户 添加成员时，或点已有成员的「使用权限」，可以分别设置共享专家、内置 Agent、服务器切换为「全部允许（含以后新增）」或指定列表（可全部取消）；旧账号沿用全部允许。共享专家和内置 Agent 分别授权，成员自己创建的专家仍可使用；收回权限后旧对话可查看，但不能继续调用，相关定时任务会暂停。服务器权限控制本机切换列表，当前服务器保持可用，各台服务器仍各自登录和管理账号。每个用户都可以在 设置 → 账号 修改自己的账号名称（也是登录名），修改不影响原有对话和登录设备。
-   多用户只隔开**界面上**的东西：会话列表、授权 / 提问卡、通知、记忆、`/sessions` 能列出和恢复的 agent 会话；设置、飞书机器人和飞书会话只给管理员（绑定了账号的飞书私聊除外，它归绑定的人）；会落盘、对所有人生效的「总是允许」（Claude 的总是允许名单、Codex 的 execpolicy）只有管理员能点。**它不是安全边界**：所有 agent 都以同一个系统用户运行，任何用户都能让 agent 读到这台机器上的文件（别人的对话记录、配置里的密钥），用的也是同一个 Claude / Codex 订阅。只给信任的人开账号；要真正隔离，就每人用自己的系统用户各跑一份 agent-loft。
-   从老版本升级：原来的登录密码自动变成管理员 `admin`，已登录的设备不用重新登录。
-   登录态通过 HttpOnly cookie 保存，服务端只存它的哈希。同一 IP 连续输错 5 次锁 15 分钟。所有写请求和 WebSocket 都校验 Origin。页面开启了严格的 CSP。
-   暴露到公网时，只通过 HTTPS 反向代理（比如 Lucky）或 Cloudflare Tunnel 访问，并把不在本机的反代 IP 加进 `web.trustedProxies`（只有从这些地址来的连接才采信 `X-Forwarded-*`）。不要直接把 8800 端口映射出去。局域网访问可以在 设置 → 系统 → 网络访问 里关掉。
-   远程控制不经过授权卡：拿到终端就是拿到运行 agent-loft 的那个系统用户的 shell，拿到桌面就是坐在登录桌面的那个人面前。所以默认只给管理员，成员要管理员单独开通（开通时会再提醒一次）；收回权限、停用或删除用户、在设置里关掉终端 / 桌面时，他开着的 shell 立刻结束、桌面立刻断开。终端和桌面的 WebSocket 和其他接口一样校验登录态和 Origin。shell 拿不到本服务自己的凭据（和 agent 子进程一样剔除环境变量）。共享桌面用的 x11vnc 只听本机、密码每次随机生成、经文件传过去（不出现在命令行里）；用「已有的 VNC 服务」时，配置里的 VNC 密码会交给开通了远程控制的人的页面；填了 Mac 用户名走苹果认证时由服务端登录，登录密码不会发到页面（但和 VNC 密码一样明文存在 config.json 里）。
-   审批超时一律按拒绝处理。Codex 默认沙箱为 `workspace-write`，不会因为 `~/.codex/config.toml` 里配了 `never` 或 `danger-full-access` 就绕过审批。
-   agent 子进程拿不到本服务自己的凭据（`FEISHU_*`、`AGENT_LOFT_*` 等环境变量会被剔除）。
-   技能存在 `data/skills/`：技能本体在 `files/<技能 id>/`，每个人装了哪些、变量的值在 `users/<用户 id>.json`（0600）。普通变量注入到会话环境里，agent 能读到；受保护的密钥 agent 看不到值，但和多用户一样不是安全边界——能读文件的专家（包括内置的 Claude Code / Codex）能直接读这些文件。别人分享的技能会在你的会话里照着执行，装之前在技能页点开看一眼它要做什么、要哪些变量。
-   记忆和聊天记录索引都存在 `data/agent-loft.db`（SQLite，会话、脚注、用量也在里面）。记给谁由 agent-loft 在拉起记忆工具时定死（工具参数里没有用户），模型想写别人的记忆也写不了；但和多用户一样不是安全边界：能读文件的专家能读到这个数据库文件。只能联网的专家没有读写本机文件的工具，网页里的提示注入也骗不走本机文件。
-   专家存在 `data/experts.json`，MCP 存在 `data/mcp.json`（0600，含 MCP 的密钥值），内置 Agent 的个人默认选择存在 `data/builtin-agents.json`。和技能一样不是安全边界：能读文件的专家读得到。

## 结构

```
src/
  core/            与渠道、agent 都无关的中枢
    hub.ts         会话调度：事件广播、命令、按专家拉起会话、换模型 / 目录
    interactions.ts 审批与提问：一个请求，多个渠道都能处理
    store.ts       会话持久化（每个 agent 的会话 id 各自保存）
    config.ts      配置（Web 可改，改完热加载）
    users.ts       Web 登录用户和归属规则（谁能看到哪条会话）
    memory.ts      记忆的存储和注入系统提示的那段文字；personal.ts 定记忆用谁的
    chat-history.ts 聊天记录索引（数据库的 history 表）和关键词搜索
    memory-curator.ts 录入聊天、回填已有对话、聊完后自动整理记忆
    feishu-links.ts 飞书账号 ↔ 用户的绑定和绑定码
    experts.ts     专家的存储、校验，开会话时解析成交给 agent 的配置（MCP、技能、子智能体）
    expert-prompt.ts 专家告诉 agent 的话（Claude 换系统提示或追加，Codex 附在消息后面）
    mcp.ts         MCP 的存储（按人）、机器上原有的 MCP
    library.ts     资料库：文件索引（数据库的 files 表）、收录用户发的附件和 agent 生成的文件、启动时收拾上传目录
    db.ts          数据库（data/agent-loft.db）：建表、导入升级前的 JSON
    tasks.ts       定时任务的存储（按人隔离）；task-schedule.ts 频率和 cron；task-prompt.ts 每次运行附给 agent 的说明和静默暗号
    task-runner.ts 定时任务的调度：到点核对主人和对话、送进对话、记下结果
    tasks-bridge.ts 定时任务工具在主进程这头：核对签名、弹授权卡、增删改（tasks-mcp.ts 定怎么拉起）；技能工具也走这条通道
    skills.ts      技能的存储：可见性、安装、停用、变量和受保护密钥确认过的地址；zip.ts 解技能包
    skill-runtime.ts 技能怎么交给 agent：Claude 的插件目录和成员白名单、Codex 的清单、自定义专家只给选中的、机器上原有的技能
    skills-bridge.ts 技能工具在主进程这头：建 / 改技能（弹授权卡）、skill_request 代发带密钥的请求
    terminals.ts   网页终端：用 node-pty 起 shell、留最近的输出给重连补发、没人连着到点结束、权限收回时结束
    desktop.ts     远程桌面：找这台机器的 X 桌面、按需起 x11vnc（或用已有的 VNC 服务）、没人连着到点停掉
    vnc-auth.ts    由服务端登录 VNC（苹果认证、VNC 密码、不用认证），对页面装成不用认证的
    vnc-transcode.ts 远程桌面转码：服务端当 VNC 客户端收全分辨率画面，缩小、只把变了的格子压成 JPEG 按 Tight 发给页面
    pairing.ts uploads.ts commands.ts …
  mcp/
    memory-server.ts 记忆工具（remember / forget / search_past_chats）的 stdio MCP 服务，两个 agent 共用
    tasks-server.ts  定时任务工具的 stdio MCP 服务：只传话，经 unix socket 转给主进程；AGENT_LOFT_TOOLSET=skills 时是技能工具
  agents/
    claude/        Claude Agent SDK 驱动
    codex/         codex app-server 驱动
  channels/
    feishu/        飞书：一个 FeishuBot 对应一个机器人，支持多个
    weixin/        微信 ClawBot（iLink 协议）：一个 WeixinBot 对应一个用户扫码连上的微信
    web/           HTTP + WebSocket + 鉴权；terminal.ts 是终端的接口和 /ws/term，desktop.ts 是桌面的接口和 /ws/desktop（转给 VNC）
web/               前端（原生 JS，不需要构建）
desktop/           桌面端（Electron 外壳，macOS / Windows / Linux）
docs/              产品介绍和截图
```

### 接入新的消息渠道（比如 Telegram）

参照 `channels/feishu/bot.ts`，做三件事：

1.  收到消息 → `hub.ensure()` 建会话 → `parseCommand()`。是命令就调 `hub.command()`，再把 `CommandReply` 画出来；是聊天就调 `hub.send()`。
2.  订阅 `hub.on("event")`，挑出自己的会话（键前缀如 `telegram:<botId>:`），把 step / text / result / error 画出来。
3.  订阅 `interactions` 的 `created / updated / settled`，把授权卡和提问卡画成按钮。用户点击后调 `interactions.decide / select / submit / skip`。

### 接入新的 agent

实现 `core/types.ts` 里的 `AgentDriver`，然后在 `main.ts` 里 `hub.registerDriver()`。`AgentDriver` 包括开会话、发消息、中断、切模型、列历史、读历史，审批通过传入的 `InteractionHost` 发起。以后要接 ACP 协议的 agent（Gemini CLI、OpenCode 等），写一个通用的 ACP 驱动就行。

## 开发

```bash
npm install
npm run dev          # AGENT_LOFT_HOME=./.dev，改代码自动重启
npm test
npm run typecheck
```

## 常见问题

### agent-loft 是什么？

多个 agent 的工作台：把本机 Claude Code / Codex 放到一处统一管理，用飞书和 Web 页面随时驱动——会话、审批、模型切换都共用

### 如何安装 agent-loft？

在项目目录运行 npm install agent-loft，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 aloft、agent-loft，可以用 npx aloft 直接运行。

### agent-loft 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agent-loft 是否存在。

### agent-loft 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### agent-loft 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### agent-loft 可以商用吗？

agent-loft 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### agent-loft 还在维护吗？

最新版本 0\.2\.87 发布于 2026/11/03（今天）；至今共发布 82 个版本，其中过去 12 个月发布了 82 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。