hob-bot 1.4.0 → 1.5.0

package/README.md

@@ -6,9 +6,7 @@ Hob is a self-hosted personal assistant that gets work done: talk to Hob, and it
 
 > The interface is currently Chinese-only. Hob is a single-user app you run on your own machine or server.
 
-![A Hob conversation with job, page, file and confirmation cards, plus other card styles overlaid](docs/screenshots/chat.jpg)
-
-*Illustration: the floating cards are composed from separate screenshots.*
+![Hob: chat with the main assistant, a running job and its live transcript](docs/screenshots/chat.png)
 
 ## How it works
 
@@ -20,11 +18,11 @@ You talk to assistants, not jobs. An assistant handles small requests directly a
 
 Each assistant has a conversation, duties, rules, skills, schedules and a work log. When similar requests recur, Hob can propose a dedicated assistant. When it delegates to another assistant, a delegation card tracks the work, carries your original request and lets you take over in the receiving assistant's conversation.
 
-Jobs can be inspected, stopped or resumed, with each round retained; the assistant receives reminders when a job exceeds its expected duration. Routines put their job cards and results in the conversation. The conversation follows new output as the assistant writes, and a screenshot can be pasted straight into the input box.
+Jobs can be inspected, stopped or resumed, with each round retained; the assistant receives reminders when a job exceeds its expected duration. Routines put their job cards and results in the conversation. A routine can run once at a set time, or carry a check script that runs first and wakes the assistant (or just leaves you a note) only when something changed, optionally stopping after the first hit. The conversation follows new output as the assistant writes; screenshots can be pasted and files dropped straight into the window.
 
 On a phone, the assistant list, conversation and profile use a mobile layout; the app supports swipe-to-reply and long-press actions. Push notifications alert you when an assistant needs your decision or a job gets stuck or fails.
 
-![Phone views of the assistant list, an assistant's confirmation question and its profile](docs/screenshots/mobile.jpg)
+![Hob on a phone: assistant list, a delegation card and assistant settings](docs/screenshots/mobile.png)
 
 ### Skills
 
@@ -77,7 +75,7 @@ Open <http://127.0.0.1:30148> and sign in with that password. Then:
 2. Go to **设置 → 模型** (Settings → Models) and pick the models for chat and for jobs.
 3. Send Hob a message. A reply, or a job card for real work, means you are set.
 
-The password is hashed into `~/.hob/config.json` on first start, so later starts don't need `HOB_PASSWORD`. You can change it under **设置 → 通用**.
+The password is hashed into `~/.hob/system/config.json` on first start, so later starts don't need `HOB_PASSWORD`. You can change it under **设置 → 通用**.
 
 ## Configuration
 
@@ -95,7 +93,18 @@ Startup options are environment variables. Everything else, including providers,
 
 `config.json` can also set `host`, `port` and the initial `password`; environment variables take precedence for host and port. Hob isolates its engine and memory directories under `HOB_HOME` and removes inherited model and Lore credentials from its runtime environment.
 
-Conversations, jobs, memory, skills, keys and engine state live in `HOB_HOME`. To reuse providers or a Lore connection you already have on the machine, import them explicitly in settings. Back up `HOB_HOME` to preserve Hob's data.
+Conversations, jobs, memory, skills, keys and engine state live in `HOB_HOME`, grouped by ownership: `system/` (config, keys, engine, Lore, memory), `cache/` (regenerable), `assistants/<id>/` (each assistant's profile, conversation, routines, jobs and files) and `archive/`. To reuse providers or a Lore connection you already have on the machine, import them explicitly in settings. Back up `HOB_HOME` to preserve Hob's data.
+
+**Data layout migration.** Older versions kept everything flat in `HOB_HOME` (`jobs/`, `pages/`, `images/` … plus a few JSON files at the root). On start Hob migrates that layout automatically, before touching the engine: it checks free space, takes a full verified copy in `HOB_HOME/backup-v1-<time>/` (permissions and symlinks preserved), moves files, and only then writes `system/moves.json` (old path → new path) and `layout.json`. If the process dies mid-way, the next start restores from the backup and runs again. Backups are never deleted automatically — remove `backup-v1-*` yourself once you are happy with the new layout (it contains a copy of your keys). Two commands help:
+
+```
+npm run layout -- --dry-run   # print the migration plan, change nothing
+npm run layout -- --restore   # go back to the old layout from the backup
+# installed from npm: hob layout --dry-run / hob layout --restore
+# Docker (stop Hob first): docker compose run --rm hob node bin/hob.mjs layout --restore
+```
+
+Downgrading means restoring the old layout first: older versions do not understand the new one and must not write the same data directory.
 
 **Claude subscription:** For npm or source installs, install Claude Code and sign in locally with `claude auth login`, then enable Claude subscription under **Settings → Providers**, choose Pro or Max and select the models under **Settings → Models**. Usage counts against the same Claude subscription quota as Claude Code. Docker images do not support this feature. Hob does not read, copy, store or forward Claude credentials; the official Claude Code program uses its existing login. Claude Code writes its own session records under `~/.claude/projects/`, outside `HOB_HOME`.
 
@@ -132,6 +141,8 @@ The desktop is not published to the host network. Hob reads the generated token
 
 For an independent deployment, use [`desktop/compose.yaml`](desktop/compose.yaml) or the `docker run` command in [the desktop guide](desktop/README.md), then enter the service URL and token in Hob's settings. When the desktop profile is not running and its shared token file is absent or empty, Hob uses the desktop configured in settings; once the token file appears, the Compose deployment takes precedence. Anyone signed into Hob can view and take over an individual screen; log into websites yourself, not through the assistant. Google currently blocks Google account sign-in in a browser with remote debugging enabled. Browser cookies in the desktop data volume are sensitive. Bearer tokens travel in cleartext over HTTP: use a trusted private network or HTTPS for connections between machines, and do not expose VNC or CDP ports.
 
+`TZ` (IANA zone) and `DESKTOP_LANG` (BCP 47 tag, e.g. `en-US`) set the desktop container's timezone and language; both go in the `.env` file next to `compose.yaml` and default to `UTC` and `zh-CN`. They drive the UI language of every program on the desktop, the browser UI language, and the `Accept-Language` / `navigator.languages` the browser sends to websites; `DESKTOP_RESOLUTION` (default `1280x800`) sets the screen size. Sites compare the IP's location with timezone, language and screen, so change them together when the egress network is not in mainland China. Existing browser profiles follow the deployment setting, so a language chosen in browser settings is overridden.
+
 Measured for desktop v2 on an amd64 host: image disk usage was 2.03 GB; memory was 23.5 MiB without screens, 354.9 MiB with one Chrome screen on example.com, and 1017 MiB with three Chrome screens on new tabs. The page workloads differ, and actual usage depends on the host and pages.
 
 Behind a reverse proxy, the desktop view needs WebSocket upgrades on `/api/desktop/vnc`. With nginx:
@@ -163,7 +174,7 @@ npm test             # vitest
 npm run typecheck
 ```
 
-Add `?mock=1` to the dev URL to run the UI against an in-browser fake backend. The screenshots above use dedicated mock scenarios; after `npx vite build`, set `CHROME_PATH` to your Chrome or Chromium executable and run `CHROME_PATH=/path/to/chrome node scripts/readme-screenshots.mjs`. To export the full set of detailed views separately, add `--all <output-directory>`.
+Add `?mock=1` to the dev URL to run the UI against an in-browser fake backend. No model or server is needed, and the screenshots above were taken that way.
 
 Stack: Node 22 + TypeScript, Hono with SSE, Vite + React with hand-written CSS. The agent engine is the [pi](https://github.com/earendil-works/pi) SDK, used in-process. Read [docs/architecture.md](docs/architecture.md) for the design, data layout and tool list (in Chinese).
 

package/README.zh-CN.md

@@ -6,9 +6,7 @@ Hob 是一个自己部署、真正动手处理事务的私人助手。你只和
 
 > 目前界面只有中文。Hob 是单用户应用，运行在你自己的电脑或服务器上。
 
-![与 Hob 的对话，展示任务、页面、文件、确认等卡片及浮层](docs/screenshots/chat.jpg)
-
-*示意图：浮层卡片由单独截图合成。*
+![Hob：与主助手的对话、正在运行的任务和实时执行过程](docs/screenshots/chat.png)
 
 ## 怎么运作
 
@@ -20,11 +18,11 @@ Hob 是一个自己部署、真正动手处理事务的私人助手。你只和
 
 每个助手有自己的对话、职责、规则、技能、定时任务和工作日志。同类工作反复出现时，Hob 会提议创建专门的助手；向其他助手转交时，对话中的转交卡会跟踪状态、带上你的原话，你也可以在接收助手的对话中接手。
 
-任务可查看过程、停止或续做，每轮记录分别保留；超出预计用时后，助手会收到督办提醒。定时任务把任务卡和结果发到对应的对话里。助手输出时对话会跟着往下滚，输入框里也可以直接粘贴截图。
+任务可查看过程、停止或续做，每轮记录分别保留；超出预计用时后，助手会收到督办提醒。定时任务把任务卡和结果发到对应的对话里。定时任务可以只在某个时间跑一次，也可以带一个检查脚本：到点先跑脚本，有变化才叫起助手或直接给你留一条提醒，还可以设成触发一次就停。助手输出时对话会跟着往下滚，截图可以直接粘贴，文件可以直接拖进窗口。
 
 手机上可查看助手列表、对话和档案，支持滑动回复和长按操作。助手需要你确认，或任务受阻、失败时，可以收到推送通知。
 
-![手机上的助手列表、助手提出的确认问题和助手档案](docs/screenshots/mobile.jpg)
+![手机上的 Hob：助手列表、委派卡、助手设置](docs/screenshots/mobile.png)
 
 ### 技能
 
@@ -77,7 +75,7 @@ docker compose up -d
 2. 到 **设置 → 模型** 选好对话和任务使用的模型。
 3. 给 Hob 发一条消息。收到回复，或者出现一张任务卡，就说明配置好了。
 
-首次启动时密码会转成哈希写进 `~/.hob/config.json`，之后启动不用再带 `HOB_PASSWORD`。改密码在 **设置 → 通用**。
+首次启动时密码会转成哈希写进 `~/.hob/system/config.json`，之后启动不用再带 `HOB_PASSWORD`。改密码在 **设置 → 通用**。
 
 ## 配置
 
@@ -95,7 +93,18 @@ docker compose up -d
 
 `config.json` 也可设置 `host`、`port` 和初始 `password`；host 和 port 以环境变量优先。Hob 将引擎和记忆目录隔离到 `HOB_HOME`，并从运行环境移除继承的模型及 Lore 凭据。
 
-对话、任务、记忆、技能、Key 和引擎数据都在 `HOB_HOME` 里。想沿用本机已有的服务商或 Lore 连接，可以在设置里主动导入。备份 `HOB_HOME` 即可保留 Hob 的数据。
+对话、任务、记忆、技能、Key 和引擎数据都在 `HOB_HOME` 里，按归属放：`system/`（配置、密钥、引擎、Lore、记忆）、`cache/`（删了能重建）、`assistants/<id>/`（每个助手的档案、对话、定时、任务和文件）、`archive/`。想沿用本机已有的服务商或 Lore 连接，可以在设置里主动导入。备份 `HOB_HOME` 即可保留 Hob 的数据。
+
+**数据目录迁移。** 旧版本把东西平铺在 `HOB_HOME` 根上（`jobs/`、`pages/`、`images/` …… 再加几个 json）。新版本启动时会自动迁移，并且发生在动引擎之前：先看空间够不够，把整个目录完整复制到 `HOB_HOME/backup-v1-<时间>/` 并逐个文件核对（保留权限和符号链接），再搬文件，最后才写 `system/moves.json`（旧路径 → 新路径）和 `layout.json`。中途断掉的话，下次启动先从备份恢复再重跑。备份**不会自动删**：确认新布局没问题后自己删 `backup-v1-*`（里面有整份密钥）。两条命令备用：
+
+```
+npm run layout -- --dry-run   # 只打印迁移计划，什么都不动
+npm run layout -- --restore   # 从备份恢复成老布局
+# npm 安装的：hob layout --dry-run / hob layout --restore
+# Docker（先停掉 Hob）：docker compose run --rm hob node bin/hob.mjs layout --restore
+```
+
+降级要先恢复成老布局：旧版本不认识新布局，不能让新旧版本同时写同一份数据。
 
 **Claude 订阅：** npm 或源码安装时，先安装 Claude Code 并在本机执行 `claude auth login`，然后在 **设置 → 服务商** 启用 Claude 订阅、选择 Pro 或 Max，再到 **设置 → 模型** 选择模型。用量计入 Claude 订阅额度，与 Claude Code 共用。Docker 镜像不支持此功能。Hob 不读取、复制、保存或转发 Claude 凭证，由官方 Claude Code 程序使用已有登录。Claude Code 会在 `~/.claude/projects/` 保存自己的会话记录，此目录不属于 `HOB_HOME`。
 
@@ -132,6 +141,8 @@ docker compose --profile desktop up -d
 
 也可用 [`desktop/compose.yaml`](desktop/compose.yaml) 或[桌面部署说明](desktop/README.md)中的 `docker run` 单独部署，再在 Hob 设置中填写地址和令牌。没有启动 desktop profile、共享令牌文件不存在或为空时，Hob 使用设置里填写的云桌面；令牌文件出现后，以 Compose 部署为准。登录 Hob 的人都可以观看和接管单块屏幕，网站登录由人自己完成，不让助手代登。受 Google 限制，开启远程调试的浏览器目前无法登录 Google 账号。桌面数据卷里的浏览器 Cookie 是敏感信息；令牌通过 HTTP 明文传输，跨机器连接请使用可信内网或 HTTPS，不要映射 VNC / CDP 端口。
 
+桌面容器的时区和语言由 `TZ`（IANA 时区名）和 `DESKTOP_LANG`（BCP 47 语言标签，如 `en-US`）决定，写在同一目录的 `.env` 里，默认 `UTC` 和 `zh-CN`。它们管桌面里所有程序的界面语言、浏览器界面语言，以及浏览器发给网站的 `Accept-Language` 和 `navigator.languages`；分辨率用 `DESKTOP_RESOLUTION`（默认 `1280x800`）。网站会对照出口 IP 所在地、时区和语言，出口不在国内时把这几项一起改，不然更容易被风控拦。已有的浏览器 profile 也按部署配置，在浏览器设置里自己改过的语言会被盖掉。
+
 云桌面 v2 在一台 amd64 机器上的实测：镜像占用 2.03 GB；不开屏幕时内存 23.5 MiB，一块 Chrome 屏幕打开 example.com 时 354.9 MiB，三块 Chrome 屏幕打开新标签页时 1017 MiB。页面负载不同，实际占用因机器和页面而异。
 
 前面有反向代理时，桌面画面需要 `/api/desktop/vnc` 支持 WebSocket 升级。nginx 示例：
@@ -163,7 +174,7 @@ npm test             # vitest
 npm run typecheck
 ```
 
-开发地址加上 `?mock=1`，界面会使用浏览器内的模拟后端。上面的截图使用专门的模拟场景；执行 `npx vite build` 后，将 `CHROME_PATH` 设为 Chrome 或 Chromium 可执行文件路径，再运行 `CHROME_PATH=/path/to/chrome node scripts/readme-screenshots.mjs` 重新拍摄。要另行导出完整的详细场景图，可加上 `--all <输出目录>`。
+开发地址加上 `?mock=1`，界面会使用浏览器内的模拟后端，不需要模型和服务端。上面的截图就是这样拍的。
 
 技术栈：Node 22 + TypeScript，Hono + SSE，Vite + React，CSS 全部手写。智能体引擎是进程内运行的 [pi](https://github.com/earendil-works/pi) SDK。设计、数据布局和工具列表见 [docs/architecture.md](docs/architecture.md)。
 

package/bin/hob.mjs

@@ -3,5 +3,11 @@
 import { register } from "tsx/esm/api";
 
 register();
-const { boot } = await import("../server/src/boot.ts");
-boot();
+// `hob layout --dry-run | --restore`：数据目录布局的试跑和恢复，和 `npm run layout` 一样
+if (process.argv[2] === "layout") {
+  process.argv.splice(2, 1);
+  await import("../server/src/layout-cli.ts");
+} else {
+  const { boot } = await import("../server/src/boot.ts");
+  boot();
+}