jessfraz/agent · 上手攻略

  • 仓库：jessfraz/agent
  • 链接：https://github.com/jessfraz/agent
  • 分类：agent / agent-harness / 多机常驻代理
  • 作者：spark
  • 更新：2026-10-31

核对基线：main 分支 commit c28d3d633d19d33e36cd61bd761ce3f7c1839907（2026-10-31 06:58 UTC）。本文所述命令与行为均以该 commit 及 docs/ 下同版本文档为准。上游依赖 Pi Durable 已核对为 1.4.0（roadmap.md "Reuse upstream" 段落明确写 "Verified against Pi Durable 1.4.0"）。仓库创建于 2026-10-27，MIT 许可，TypeScript 主语言 + Rust 内核，发布 4 天时约 114 stars / 9 forks。

一、是什么

一句话：一个用 Rust 写的 CLI，外壳套在 Pi Durable 之上，配合 Rex 管理终端与主机，用 ChatGPT 订阅账号登录，提供持久化会话 + 多机 worker + 事件驱动巡检的个人代理系统。

作者 Jessie Frazelle（jessfraz）自己在仓库简介里只写了五个字："An agent, regrettably."（一个代理， regrettably 意为"不幸地/说来惭愧"）。这句话本身就是定位说明——这是个自嘲式的个人工具，不是产品。

它的核心差异点不是模型能力，而是"任务的生命周期管理"。README 里的一句话概括了设计意图：

Find the old conversation. Continue the existing task. Close the loop.

即：来了新邮件/新 Slack/新 GitHub 通知时，先去找已有的那次对话，把事情接着做完，而不是每次都开一个新会话从头再来。

三个组件的分工（来自 docs/architecture.md）：

  • Pi Durable —— 拥有对话、模型轮次、持久化请求和本地 SQLite 存储，提供 provider 接口做推理。
  • Rex —— 拥有主机、会话（session）与终端（terminal）的生命周期。
  • Rust 层 —— 拥有 CLI 配置、生成的类型契约、进程生命周期、原生主机检查、source 适配器和文件系统副作用。
  • 一个小 TypeScript adapter 把 Pi 的事务性文档和工具接到上述契约上，README/架构文档都强调"keep that adapter narrow"。

换句话说：Pi 是发动机，Rex 是底盘，jessfraz/agent 是把它们接起来的整车。

二、解决什么问题

它针对的是"个人自动化代理"里最痛的那一类问题——长周期、多事件、跨主机的任务。典型场景：

  1. 同一件事被反复打断重做。 你周一让它查一个 PCB 厂家的缺料邮件并跟进，周三新邮件又来了，系统如果每次都新开会话，之前的上下文全丢。这里它会先检索历史、找到已有任务、附着到原会话继续。
  2. 一个代理要在多台机器上干活。 桌面 Mac 跑 GUI 相关、笔记本跑日常、Linux 服务器跑 CI 修复——每个任务分到一个具名 Rex session，子 agent 在该 session 里拿具名终端。
  3. 代理不能一直占着一个终端窗口。 /exit 或 Ctrl+C 断开主 chat 后，后台工作继续跑；重开 CLI 回到同一个已保存的会话，接着看、接着 steering。
  4. 授权不该反复问。 README 明说 "Authorization carries forward; an approved action should not trigger another approval loop." 已批准的动作不会再次触发审批环。
  5. 没有真事发生时保持安静。 "Incoming email, Slack, GitHub and Messages should produce useful action or a concrete decision. Otherwise, stay quiet." 这是相对大多数"什么都要汇报"的代理的一个明确反向设计。

三、快速安装

前置依赖（docs/setup.md 明确列出）：

  • Nix —— 官方安装方式走 nix profile
  • Rex（https://www.superlogical.com/rex）—— 每台执行机都要装
  • Tailscale —— 每台执行机都要装，连到同一个 authorized tailnet
  • ChatGPT 订阅账号 —— 默认 provider，用的是订阅额度而非 API key

Coordinator（协调者，选一台常开的机器，它拥有对话、共享设置、后台 intake 和主 agent）：

nix profile add github:jessfraz/agent
agent init
agent serve

agent init 会创建 ~/.config/agent/config.toml（私有权限），且拒绝覆盖已存在的文件。

Worker 或纯 CLI 客户端（另一台机器）：

nix profile add github:jessfraz/agent
agent init --coordinator tailscale://100.64.0.10
agent serve

把 100.64.0.10 换成 coordinator 的 native Tailscale IPv4。端口可省略，README 写默认端口是 43187。

登录（必须先 agent serve 再 agent login，否则 CLI 会起一个仅本地的 daemon，占住同一个数据库，第二个 coordinator 就起不来了）：

agent login
agent status
agent chat

agent login 会打开 ChatGPT 登录页，浏览器里完成身份校验即可，凭证由 app 私密保存并自动刷新。不需要复制 Codex 凭证。

开发/构建：

nix develop
make runtime check
nix build

Rust 生成 TypeScript bindings 和 JSON schemas；CI 在 Linux 和 macOS 上跑行为测试与打包测试，不使用个人账号。

四、核心用法

常用 CLI

agent chat                 # 进入 TUI 主会话（任何目录都可以）
agent nodes                # 列出已注册机器及在线状态
agent tasks list           # 列出任务
agent sources              # 列出已接入的事件源
agent usage                # 查看已安装 Codex 账号的额度
agent import codex         # 从已注册在线主机增量导入 Codex 历史
agent history search "fabrication files"   # 本地关键词 + 语义检索历史

纯文本与协议输出：

agent --no-tui chat        # 纯文本输出
agent --json chat          # 输出协议事件

TUI 内交互

输入 作用
Enter 插话（steer）当前正在跑的工作
Tab 排队一条独立的后续轮次（FIFO 执行）
Shift+Enter / Alt+Enter 插入换行
Esc 停止当前工作
?（空编辑器内）/ /help 命令与快捷键
Ctrl+T 打开 transcript；再按 Enter 展开 reasoning 或某个 tool 的输入输出
/model /reasoning /fast 切换当前会话的模型 / 推理档 / 快速模式
/status 查看生效配置、连接状态与套餐用量
/machines 已连接主机、硬件容量与近期负载采样
/resume 打开已保存会话选择器（按标题或 ID 过滤）
/exit 断开主 chat（后台工作继续）
/feedback <描述> 在同一台机器上启动后台修复，带私密诊断

TUI 渲染 Markdown（含表格），显示模型、reasoning、当前目录与实时活动。

任务与会话控制

agent tasks send TASK_ID "Continue with this context" --mode steer
agent tasks send TASK_ID "Check this afterward"   --mode queue --input-id UUID

steer 是默认模式（插话当前轮次），queue 等下一轮。重试一次没把握是否送达的操作时，务必保留 --input-id。

历史导入与检索

agent import codex                      # 所有已注册在线主机
agent import codex --host desktop       # 指定一台
agent import codex --embedding-host workstation   # 只指定索引算力主机
agent import status
agent history search "ERR_SURFACE_413" --mode keyword
agent history read CONVERSATION_ID
agent history open CONVERSATION_ID
agent history classify CONVERSATION_ID ENTRY_ID --as internal-receipt
agent history classify CONVERSATION_ID ENTRY_ID --as visible

导入是增量的：已完成的可靠源版本会跳过，部分读取从已提交游标恢复。再次运行 agent import codex 可以追平。

接入事件源

source 复用已有的、已认证的 CLI：

  • Google 邮件与日历 —— 通过 Switchboard 和 gws
  • GitHub —— 通过 Switchboard 和 gh
  • Slack —— 需要配置好的 Slack CLI
  • macOS Messages —— 只读的 macOS messages CLI

每个源都可以单独禁用。读取失败的源会以 "coverage gap" 形式保持可见（不静默吞掉）。

Chrome 控制（可选，最后兜底）

只有在 API 和 CLI 都做不到时才用 Chrome。两种模式：

Playwright 扩展模式（推荐，无需原生调试端口）——在已有 Chrome profile 里装 官方 Playwright 扩展，从扩展状态页拿到 profile 专属的 PLAYWRIGHT_MCP_EXTENSION_TOKEN，通过私密凭证环境（或 credential_command）交给 Agent 服务后重启服务。

[browser]
# profile_dir_name = "Profile 1"
# credential_command = ["with-credentials", "browser", "--"]
# user_data_dir = "/example/chrome-data"

原生 CDP 模式——已有 Chrome 开了调试端口时：

[browser]
debugging_port = 9222

CDP 模式下不能同时用 user_data_dir 和 profile_dir_name。Chrome 保持运行，连接断开不杀浏览器。

浏览器工具：browser_open（新建受管标签页）、browser_status、browser_run_code（跑 async (page) => {...}，标准 Playwright Page API）、browser_action（快照、导航、表单输入、点击、按键、对话框等便捷命令）、browser_release（关闭剩余受管标签页）。

文件附件：拖进终端编辑器即可，最多 8 个文件、每个 16 MiB。图片走 Pi 的模型图像输入，其他文件在执行主机上对 agent 工具可见。

五、典型适用场景

  1. 多机个人运维代理 —— 一台常开 Mac 当 coordinator，Linux 服务器跑 CI 修复，笔记本跑日常。agent nodes 就能看清谁在线。
  2. 邮件/Slack 驱动的长任务 —— README 举的例子是 JLCPCB 关于缺失制造文件的邮件：代理找到已有的硬件任务、附上邮件、继续原来的 Rex 会话，把简明结果或需要你决策的点回传到主 chat。
  3. 代理任务的可审计历史 —— Codex 对话增量导入进本地 SQLite（含 FTS5 和 sqlite-vec 向量），索引可重建。之后 agent history search 能用语义而非精确关键词找到相关旧会话。
  4. 多 worktree 并行开发 —— 任务可拥有多个 worktree，agent resources list 展示清单，agent resources collect 走内置的受保护 git 清理流程（只清理已合并且干净且非活跃的工作；缺失 helper、归属不明、部分结果都会保持可见）。
  5. 手机作为客户端 —— iPhone app（SwiftUI）连同一个 coordinator 和主会话，能贴文件/照片；TestFlight 私有更新从 main 构建。

六、坑与注意

按 W42 的写作指引，版本浮动处已标出 commit：

  1. 项目非常新。 仓库 2026-10-27 创建，本文核对时仅 4 天、约 114 stars。文档密度极高但功能面远大于验证面——roadmap 里大量条目仍是 [ ] 未完成状态。把它当实验性（experimental）工具看待，不要放进生产关键路径。
  2. 上手门槛被低估。 依赖链是 Nix + Rex + Tailscale + ChatGPT 订阅，四个都装好才能跑起来。Rex 和 Tailscale 都不是开箱即用的东西，装错版本会浪费大量时间。
  3. agent serve 必须先于 agent login。 顺序反了会起一个仅本地 daemon 占住数据库，之后第二个 coordinator 永远起不来。文档里有对应的 Nix service 方案可以规避这个顺序依赖。
  4. coordinator 单点，无故障转移。 架构文档明说："The MVP does not replicate the store or recover onto another host. If the coordinator is down, the client reports that it is unavailable. Copying a live SQLite database or starting two coordinators is not a recovery mechanism." 备份/恢复/多副本 failover 在 roadmap 里全部是未完成项。协调者挂了 = 全部会话不可用。
  5. Chrome 相关的坑很深。 文档明确警告：指向一个空目录会丢失已登录状态；Chrome for Testing 是一次性测试夹具，绝不是生产兜底；Chrome 即将到来的 macOS 加密变更会让默认根目录的 cookie 与自定义根目录不兼容；"Migrating a disposable profile is not proof of personal account continuity"。另外 profile_dir_name 和 user_data_dir 指向的必须是同一个 profile，token 也是 profile 专属。
  6. token 与凭证泄漏风险。 Playwright token 文档要求放在 secret manager，不得进 Agent 配置、启动参数、仓库文件或 Nix store。仓库也声明 "Private settings, credentials and conversations stay outside this repository"，但你自己 ~/.config/agent/config.toml 的权限要自己保证。
  7. 导入不等于恢复权限。 history.md 明确："Never import authentication state, system/developer prompts or permission grants." 导入的历史工具调用是证据，永不重放。别指望导入旧会话后 agent 还能直接用当时的凭证。
  8. Chrome chrome://inspect 每次新连接都要人工批准，无人值守场景必须走原生 CDP 模式（用非默认的 user-data 根目录 + 命令行调试端口）。
  9. 平台限制： 文档中的原生检查、Keychain、messages 只读 CLI、Swift 客户端都偏 macOS；Linux 侧能力少一些。
  10. 只有 OpenAI Responses 系列模型有内置的 hosted web search / 打开页面 / 页内查找。 其他 provider 需要自己接搜索集成；且这不等于给 agent 访问已登录 Chrome 的能力——那是两套东西。
  11. agent usage 报的是已安装 Codex 账号的额度，文档明说 "cannot report a separate allowance for this app"。想看本应用的独立用量要走 telemetry 那条路（roadmap 里 Pi telemetry 接入标为已完成）。
  12. 历史搜索索引与 Pi 存储是分离的。 search.sqlite（FTS5 + sqlite-vec）是可重建的派生数据，Pi 才是权威。索引落后时会出现"查不到"但数据其实还在的情况，别急着怀疑数据丢了。
  13. AIGC 痕迹与元语言冗余。 仓库文档大量使用 "Verified against Pi Durable 1.4.0" 这类精确锚定，但 roadmap 中大量条目仍是未完成清单形态——读文档时区分"已完成（[x]）"和"待做（[ ]）"非常关键，否则容易把规划当现状。

七、与同类对比

维度 jessfraz/agent Claude Code / Codex CLI OpenCode / Aider 类本地 CLI
形态 常驻 coordinator + 远程 worker 的多机代理 单机终端编码代理 单机终端编码代理
会话模型 持久化任务 + 可搜索历史 + 事件源自动 intake 单次会话为主，可恢复但无跨任务检索编排 会话为主
主机抽象 Rex 管理 session/terminal，agent 只做路由 本机 本机
事件源 内置 Gmail/Calendar/GitHub/Slack/messages 适配 靠 MCP / 脚本 靠 MCP / 脚本
浏览器 复用已有已登录 Chrome（扩展或 CDP） 各自实现 各自实现
成熟度 experimental，4 天新仓库 成熟 较成熟

差异化：多机 worker 路由 + "先找旧任务再开新任务"的检索编排 + 内置事件源 + 复用真实登录态浏览器。 代价：四个重型前置依赖、coordinator 单点、实验性成熟度、文档量大但完成度参差。

八、一句话推荐结论

如果你需要的是一个能跨机器常驻、能从邮件/Slack/GitHub 自动接活、并且会记得上次做到哪的私人代理，jessfraz/agent 的设计思路非常值得读；但它现在只有 4 天历史、依赖 Nix+Rex+Tailscale 三件套、且 coordinator 无容灾——请当作学习样本和实验平台来用，而不是生产依赖。

附：本文来源

来源 用途
https://github.com/jessfraz/agent（README，2026-10-31 读取） 定位、架构图、安装命令、CLI 清单
docs/setup.md（同上 commit） coordinator/worker 安装顺序、login 流程、TUI 快捷键、Chrome 两种模式与坑
docs/architecture.md（同上 commit） 组件分工、单写者模型、coordinator 无容灾、信任模型、任务与 Rex 绑定
docs/history.md（同上 commit） 导入/检索命令、增量语义、导入边界
docs/roadmap.md（同上 commit） 完成度状态、Pi Durable 1.4.0 版本锚定、未完成项清单
GitHub API /repos/jessfraz/agent 创建日期、stars、许可、语言、默认分支
GitHub API /repos/jessfraz/agent/commits/main commit hash c28d3d6、提交时间、签名状态
web_search（earendil-works/pi、Pi Durable、HN 讨论） 补上游 Pi Durable 的定位与 1.4.0 版本旁证

不确定处： - Rex 的安装细节未核（Rex 官网未抓取），本文只引用 agent 文档中的安装要求。 - agent CLI 的完整子命令表未逐条核对，README/setup/history 中出现的已覆盖，其余子命令存在但未验证。 - Chrome 相关的 macOS 加密变更与 Chromium commit 细节引自 setup.md 的链接，未二次核对上游 Chromium 提交内容。 - 仓库 star 数为读取时快照（114），会随时变化。