Nook

给 Pi coding agent 用的轻量 Web 界面：在浏览器或手机上查看会话、发消息、把服务装成开机常驻，并按 cron 挂定时任务。

Nook 只是 Pi 的包装层：模型、密钥等配置全部沿用 Pi 自己的设置（~/.pi），Nook 不保存任何模型或服务配置。

快速开始

先确保本机的 Pi 已经配好可用（在终端能跑 pi）。

npm install -g @vitex/nook   # 或者不安装：npx @vitex/nook start
nook start

然后打开 nook status 打印的地址（默认 http://127.0.0.1:4317），添加一个项目目录就能开始。

CLI

| 命令 | 说明 | | --- | --- | | nook start [--host H] [--port P] | 前台启动 | | nook status | 查看访问地址、运行状态、项目数 | | nook update [--check] | 检查官方仓库并安装最新版 | | nook service install | 安装并启动后台服务 | | nook service start / stop / restart | 启动 / 停止 / 重启后台服务 | | nook service status | 查看服务管理器与状态 | | nook service uninstall | 卸载后台服务 | | nook help | 帮助 |

更新

nook update          # 有新版本就自动安装
nook update --check  # 只检查，不安装

• 检查 npm 上的最新版本，有更新时执行 npm install -g @vitex/nook@latest
• npx 运行：只提示新版本，不落盘安装
• 后台服务正在运行时会自动重启
• 国内网络可指定镜像：nook update --registry https://registry.npmmirror.com

后台服务

macOS 用 launchd，Linux 用 systemd 用户服务（systemd 已存在的发行版均可）。

nook service install            # 服务文件按安装时的路径生成，不依赖仓库位置
nook service restart            # 改完后端代码后重启

• 日志：macOS ~/.nook/logs/stdout.log / stderr.log；Linux journalctl --user -u com.nook.server -f
• Linux 请用当前用户运行，不要加 sudo。若安装时启用 linger 失败，手动执行 sudo loginctl enable-linger "$USER"，服务才能在未登录时运行
• macOS 若项目在 ~/Desktop、~/Documents、~/Downloads，后台服务可能没有读写权限：改用 nook start 前台运行（继承终端权限），或给 Node 可执行文件授权「完全磁盘访问权限」

访问方式

只按传入的 host / port 监听，不依赖任何特定网络服务：

nook start --host 127.0.0.1 --port 4317     # 只本机
nook start --host 0.0.0.0 --port 4317       # 所有网卡
nook start --host 192.168.1.10 --port 4317  # 指定网卡

nook service install 同样接受 --host / --port。

页面没有登录，请只在可信网络里使用。手机访问、以及 PWA 安装都需要 HTTPS（安全上下文），建议在本机加一层 HTTPS 反向代理或内网穿透，或者直接用下面的 Android App。

功能

会话 Nook 直接读写 Pi 的 session 文件（~/.pi/agent/sessions/），不另存格式；Nook 里新建的会话 Pi CLI pi -r 也能看到。项目只是 { name, path } 记录，删除项目不会删除目录或会话。

图片附件 输入框支持图片附件，必须和文字一起发送：最多 6 张，单张 ≤ 1 MB（GIF ≤ 2 MB），单条消息总计 ≤ 4 MB，支持 PNG / JPEG / WebP / GIF。桌面可粘贴或拖拽，手机从相册多选；图片随消息写入 Pi session，Nook 不另存副本。当前模型需要支持图片输入。

模型与思考等级 输入框底部一行、和发送按钮并排：左边是当前模型（带思考等级），点一下向上弹出列表直接切换，选完自动收起。模型列表只列已配置凭据的模型（拿不到时退回完整目录），模型多时可搜索；思考等级按当前模型支持的范围显示（off / low / high / max 等，Pi 自动夹取）。切换只写入当前会话的 model_change / thinking_level_change，不影响 Pi 的全局默认设置。

运行中：默认跟进，可改插话 Agent 运行时输入框仍可用，消息默认进入跟进（本轮结束后处理）队列；排队中的消息可以单独改成插话（当前工具调用结束后插入）、撤回，或一起取回输入框。发送按钮在运行中会变成停止按钮。桌面键盘：Enter 发送，Alt+Enter 直接插话。

定时任务 每个项目可挂多个任务，到点自动新建 Pi 会话执行提示词，像普通会话一样推送进度和完成通知（首页项目卡片的「定时」按钮进入）。

• 标准 5 段 cron（分 时 日 月 周），按运行 Nook 的机器时区执行
• 支持启用/暂停、立即运行测试（不影响下次定时）
• 默认不补跑：停机或休眠期间错过的任务跳过，迟到 5 分钟以内仍执行；上一轮未跑完则跳过本次
• 依赖后端常驻，建议 nook service install

Agent 也能用 schedule_list / create / update / delete / run / preview 工具管理当前项目的定时任务。

其他

• 思考过程、工具调用、重试/压缩状态通过 SSE 实时推送
• 运行结束会推一条轻量的 nook_run_end SSE（/api/notify），供 Android App 做跑完提醒
• 前端带 manifest.webmanifest 与 sw.js，可添加到桌面；Service Worker 只缓存页面壳和静态资源，/api/ 与 SSE 始终走网络

数据

~/.nook/projects.json    项目索引
~/.nook/schedules.json   定时任务
~/.nook/scheduler.lock   调度器单实例锁（同一份 ~/.nook 只有一个调度器在跑）
~/.nook/logs/            macOS 服务日志

环境变量

| 变量 | 说明 | | --- | --- | | NOOK_HOST | 监听地址，默认 127.0.0.1；0.0.0.0 为所有网卡 | | NOOK_PORT | 端口，默认 4317 | | NOOK_HOME | 数据目录，默认 ~/.nook | | NOOK_WEB_DIR | 自定义构建后的前端目录 | | NOOK_ALLOW_PROTECTED | macOS：设为 1 允许后台服务访问桌面/文稿/下载 | | NOOK_BACKEND | 前端 dev server 代理目标，默认 http://127.0.0.1:4317 |

Android App

不想折腾 HTTPS / PWA 的话，android/ 里有一个原生 WebView 壳，直接打包成 APK：

./android/build.sh   # 产物：dist/nook-<版本>.apk，每次打包自动升 patch 版本

安装后添加一次服务地址（如 http://192.168.1.10:4317）即可，支持明文 http，可保存多个地址并切换。细节（含通过 Tailscale 直接把 APK 发给手机的步骤）见 android/README.md。

开发

src/frontend/    Vue 3 + Vite
src/backend/     Node 后端、Pi SDK、CLI、服务管理
bin/nook.js      CLI 入口
scripts/build.js 构建脚本
dist/            构建产物

npm install
npm run dev:backend    # 后端 API，127.0.0.1:4317
npm run dev:frontend   # Vite dev server，/api 代理到后端
npm run build          # 构建前端 + 生成 dist/nook
npm run build:service  # 构建并重启后台服务

后端已占用 4317 时，先 nook service stop，或换端口：

NOOK_PORT=4320 npm run dev:backend
NOOK_BACKEND=http://127.0.0.1:4320 npm run dev:frontend

只跑前端、后端用已有服务时，把 NOOK_BACKEND 指向那台机器即可。