hob-bot 1.3.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # Hob
 
-**A self-hosted personal assistant that actually does the work.** You talk to one main assistant, Hob. It runs real work as background jobs, asks before anything risky, and when a kind of work keeps coming back, it proposes a dedicated assistant for it.
+Hob is a self-hosted personal assistant that gets work done: talk to Hob, and it handles small requests itself and delegates larger jobs.
 
 [中文说明](README.zh-CN.md) · [Architecture](docs/architecture.md) · MIT License
 
@@ -8,41 +8,47 @@
 
 ![Hob: chat with the main assistant, a running job and its live transcript](docs/screenshots/chat.png)
 
+## How it works
+
+You talk to assistants, not jobs. An assistant handles small requests directly and delegates larger work to a job. Jobs return Markdown results and files only to their assistant, and ask the assistant when they need an answer; the assistant decides what to show you and when to ask you. Global rules and each assistant's own rules determine what needs your confirmation.
+
 ## What you get
 
-**One conversation, real work.** Ask in plain language; Hob turns it into a job that runs in the background with its own shell, files and tools. A job card shows progress and elapsed time. Open it to follow every step live, add instructions mid-way, or stop it.
+### Assistants, jobs and schedules
 
-**Assistants that grow out of your habits.** When the same kind of request repeats, Hob suggests a dedicated assistant ("写作", "服务器", "记账" …). Each one keeps its own conversation, duties, approval rules, schedules and work log, and you configure all of it in one panel.
+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.
 
-**Delegation you can see.** Hob hands work to the right assistant and keeps a delegation card in its own chat: status, linked jobs, and any pending question, which you can answer right on the card. Your original words travel with the work; reply in the receiving assistant's chat to take over, or reply in chat to close a pending question.
+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.
 
-**Work that can continue.** Assistants can read files, inspect job status, activity and results without interrupting the work, and resume a finished job with separate cards and reports for each round. They estimate job duration and receive reminders when work runs over; completion notices include actual and expected time.
+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.
 
-**Rules you control.** Set global rules for every assistant and job in Settings, with separate lists for actions that need confirmation and instructions to follow. Each assistant can also have its own rules; pick "always allow" once to save an exception.
+![Hob on a phone: assistant list, a delegation card and assistant settings](docs/screenshots/mobile.png)
 
-**Schedules.** Daily briefs, weekly reports, month-end checks: routines run on cron-style schedules and post job cards and results into the assistant's conversation. A routine can also use a saved assistant skill.
+### Skills
 
-**Knowledge bases.** Organize, search and preview files, bind collections to assistants, and follow citations to source passages. An optional embedding model enables hybrid search; PDF text can also be indexed.
+An assistant decides which of its skills each job gets; a schedule can be bound to one. When a job finishes something worth repeating, the assistant has that job write the skill up in its own session, running the commands and scripts again first. Skills covering the same kind of work are merged into one and the older copy archived; when a job finds a step outdated, the skill gets corrected.
 
-**Cloud desktop.** An optional separate container gives each assistant its own screen and browser, with a shared screen for selected assistants. Assistants can browse directly, share login state with their jobs and send screenshots in chat. Watch or take control, sync the clipboard, use your local input method and keyboard shortcuts.
+### Rules
 
-**A clearer workspace.** The right panel brings assistant details, jobs and files together; its two lists load more as you scroll, and nested pages retain their address on refresh. Completed unread work is marked on the assistant's avatar. Archive an assistant when no longer needed while keeping its conversations and job history.
+Global rules apply to every assistant and job; each assistant can also have its own. Rules distinguish actions that require confirmation from instructions to follow automatically; confirmation choices can save an exception for next time.
 
-**Pages instead of walls of text.** For processes, comparisons or research, an assistant can answer with a single-page visual document. It opens in the side panel and renders live while the model is still writing.
+### Pages and knowledge
 
-**Tools that come with it:**
+Assistants can present comparisons and research as pages in the side panel. Organize, search and preview files in knowledge bases, bind them to assistants and follow citations; optional embeddings enable hybrid search, including indexed PDF text.
 
-- **Web search** across 10 providers (SearXNG, Exa, Tavily, Brave, Serper, Jina, Firecrawl, Perplexity, You.com, Ollama), used in order with automatic fallback.
-- **Skills** from Hob's own skill folder, the shared `~/.agents/skills`, and Lore. Import existing skills or let assistants save reusable ones, edit their instructions with version history, and choose a skill for a job.
-- **MCP servers** (stdio or streamable HTTP) that jobs can call, with per-server and per-tool switches; import what you already have from Claude Code, Cursor and pi.
-- **Long-term memory**, kept locally or in [Lore](https://github.com/FFatTiger/lore).
-- **Image generation** in chat through an OpenAI-compatible image API, with a progress card while it runs.
-- **Claude subscription** via an existing local Claude Code login on npm or source installs.
-- **Push notifications** when an assistant needs your decision or a job gets stuck or fails.
+### Cloud desktop and tools
 
-**Made for the phone too.** Hob is an installable web app with a mobile layout and Telegram-style gestures: swipe a message to reply, long-press for actions. Light and dark themes follow your system.
+An optional cloud desktop gives each assistant a browser and screen shared with its jobs; selected assistants can also use a public screen. Assistants can operate the browser and send screenshots in chat; you can watch or take control.
 
-![Hob on a phone: assistant list, a delegation card and assistant settings](docs/screenshots/mobile.png)
+Assistants and jobs can use web search across SearXNG, Exa, Tavily, Brave, Serper, Jina, Firecrawl, Perplexity, You.com and Ollama. Jobs can call configured MCP services, including configurations imported from Claude Code, Cursor and pi. Memory can be local or use [Lore](https://github.com/FFatTiger/lore); image generation uses an OpenAI-compatible API. npm and source installations can also use an existing Claude Code subscription login.
+
+### Usage and cost
+
+Settings → Usage counts the conversations and jobs you already have and shows requests, tokens and estimated cost for the last day, 7 days, 30 days or all time, with a heatmap for the past year and breakdowns by model and by assistant. Prices come from models.dev by default and can be edited per model.
+
+### Light and dark
+
+Hob has light and dark themes and can follow the system setting.
 
 ## Quick start
 
@@ -69,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
 
@@ -87,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`.
 
@@ -124,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:

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # Hob
 
-**一个自己部署、真正动手干活的私人助手。** 你只跟主助手 Hob 说话：它把要做的事交给后台任务执行，有风险的操作先问你；同一类活反复出现时，它会提议分出一个专门的助手。
+Hob 是一个自己部署、真正动手处理事务的私人助手。你只和 Hob 说话：小事它当场处理，大活交给后台任务。
 
 [English](README.md) · [架构说明](docs/architecture.md) · MIT 许可证
 
@@ -8,41 +8,47 @@
 
 ![Hob：与主助手的对话、正在运行的任务和实时执行过程](docs/screenshots/chat.png)
 
-## 能做什么
+## 怎么运作
 
-**一条对话，真实干活。** 用平常的话提要求，Hob 会派出任务在后台执行，任务有自己的命令行、文件和工具。任务卡上能看到进度和用时，点开可以实时看每一步，中途补充要求，或者直接停止。
+你只和助手说话，不直接和任务交互。助手小事当场处理，大活交给任务；任务只向助手交 Markdown 结果和文件，有问题也只问助手。助手决定给你看什么、什么时候问你；全局规则和每个助手自己的规则决定哪些事情要先征求你的确认。
 
-**从习惯里长出来的助手。** 同类要求反复出现时，Hob 会提议创建专门的助手，比如「写作」「服务器」「记账」。每个助手有自己的对话、职责、执行前确认规则、定时任务和工作日志，都在同一个面板里设置。
+## 功能
 
-**看得见的委派。** Hob 把事交给合适的助手后，在自己的对话里留一张委派卡，上面有状态、关联任务和待确认的问题，问题可以直接在卡上回答。派活会带上你的原话；在接收助手的对话中说话可以接手转交，在对话中回复也能结束待答提问。
+### 助手、任务和定时
 
-**可以接着做。** 助手可以读取文件，查看任务状态、过程和结果，无需打断任务；已结束的任务可以续做，每轮分别保留卡片和报告。助手会估计任务用时，超时后收到提醒；结束通知会写明实际用时和预计用时。
+每个助手有自己的对话、职责、规则、技能、定时任务和工作日志。同类工作反复出现时，Hob 会提议创建专门的助手；向其他助手转交时，对话中的转交卡会跟踪状态、带上你的原话，你也可以在接收助手的对话中接手。
 
-**自己定规则。** 在设置中管理所有助手和任务的全局规则，分为「执行前确认」和「一律照做」。每个助手也有自己的规则；选一次「一直允许」就会记成规则。
+任务可查看过程、停止或续做，每轮记录分别保留；超出预计用时后，助手会收到督办提醒。定时任务把任务卡和结果发到对应的对话里。定时任务可以只在某个时间跑一次，也可以带一个检查脚本：到点先跑脚本，有变化才叫起助手或直接给你留一条提醒，还可以设成触发一次就停。助手输出时对话会跟着往下滚，截图可以直接粘贴，文件可以直接拖进窗口。
 
-**定时任务。** 每日简报、周报、月底对账，按 cron 式的时间表运行，任务卡和结果发到对应助手的对话里。定时任务也可以绑定已保存的助手技能。
+手机上可查看助手列表、对话和档案，支持滑动回复和长按操作。助手需要你确认，或任务受阻、失败时，可以收到推送通知。
 
-**知识库。** 整理、搜索和预览文件，将知识库绑定给助手，并从出处跳转到原文段落。配置向量模型后可混合检索，也支持为 PDF 文字建立索引。
+![手机上的 Hob：助手列表、委派卡、助手设置](docs/screenshots/mobile.png)
 
-**云桌面。** 可选的独立容器为每个助手提供屏幕和浏览器，也可允许指定助手使用公共屏幕。助手可以直接操作浏览器，和任务共用登录状态，并在对话中发送截图。你可以观看或接管，使用剪贴板同步、本机输入法和键盘快捷键。
+### 技能
 
-**更清晰的工作区。** 右栏集中展示助手信息、任务和文件，两个列表滚动到底自动加载更多，二级页面刷新后仍可通过地址恢复。助手头像会标出完成未读的工作。不再需要的助手可以归档，对话和历史任务仍会保留。
+技能归助手管：派活时由助手决定给任务哪几份，定时任务可以绑定一份。任务做完、结果值得留下时，助手让做这件事的原任务在自己的会话里把它写成技能，写之前把命令和脚本真跑一遍。管同一类事的技能会合成一份，旧的归档；任务照着技能做时发现哪一步过时，助手会让它改对。
 
-**用页面代替大段文字。** 讲流程、做对比、写调研时，助手可以交一页图文页面。页面在侧栏打开，模型边写边显示。
+### 规则
 
-**自带的能力：**
+全局规则对所有助手和任务生效，每个助手也可以有自己的规则。规则分为执行前确认和一律照做；确认时可以选择以后允许同类操作，保存为规则。
 
-- **联网搜索**：支持 10 个服务商（SearXNG、Exa、Tavily、Brave、Serper、Jina、Firecrawl、Perplexity、You.com、Ollama），按顺序使用，失败时自动换下一个。
-- **技能**：读取 Hob 自己的技能目录、通用的 `~/.agents/skills` 和 Lore。可以导入已有技能；助手可以沉淀技能、修改正文并保留旧版，派任务时可指定技能。
-- **MCP 服务**：任务可以调用本地命令（stdio）或远程地址（streamable HTTP）的 MCP 服务，可按服务、按工具单独开关；可以从 Claude Code、Cursor、pi 导入已有配置。
-- **长期记忆**：保存在本地，或接入 [Lore](https://github.com/FFatTiger/lore)。
-- **图像生成**：接 OpenAI 兼容的图像接口，在对话里生图，并通过生成中卡片查看进度。
-- **Claude 订阅**：npm 或源码安装时，可使用本机已有的 Claude Code 登录。
-- **推送通知**：助手需要你确认，或任务受阻、失败时通知你。
+### 页面和知识库
 
-**手机上也好用。** Hob 可以安装成网页应用，手机上是专门的布局，交互照 Telegram：向左滑动消息即可回复，长按弹出菜单。支持亮色和暗色主题。
+助手可以把方案比较、调研等内容做成页面，在侧栏打开。知识库支持整理、搜索和预览文件，绑定到助手并从引用跳到原文；配置向量模型后可混合检索，也支持为 PDF 文字建立索引。
 
-![手机上的 Hob：助手列表、委派卡、助手设置](docs/screenshots/mobile.png)
+### 云桌面和工具
+
+可选的云桌面为每个助手提供与任务共用的屏幕和浏览器，也可允许指定助手使用公共屏幕。助手可以自己操作浏览器并在对话中发送截图，你可以观看或接管。
+
+助手和任务可以使用 SearXNG、Exa、Tavily、Brave、Serper、Jina、Firecrawl、Perplexity、You.com、Ollama 的联网搜索。任务可以调用配置好的 MCP 服务，也可以从 Claude Code、Cursor 和 pi 导入已有配置。记忆可保存在本地或接入 [Lore](https://github.com/FFatTiger/lore)；图像生成使用 OpenAI 兼容接口。npm 或源码安装也可以使用本机已有的 Claude Code 订阅登录。
+
+### 消耗
+
+设置 → 消耗 把已有的对话和任务统计起来，显示今天、近 7 天、近 30 天和全部的请求数、token 和估算花费，附最近一年的热力图，以及按模型、按助手的明细。单价默认取自 models.dev，也可以按模型自己改。
+
+### 浅色和深色
+
+Hob 支持浅色、深色，以及跟随系统设置。
 
 ## 快速开始
 
@@ -69,7 +75,7 @@ docker compose up -d
 2. 到 **设置 → 模型** 选好对话和任务使用的模型。
 3. 给 Hob 发一条消息。收到回复，或者出现一张任务卡，就说明配置好了。
 
-首次启动时密码会转成哈希写进 `~/.hob/config.json`，之后启动不用再带 `HOB_PASSWORD`。改密码在 **设置 → 通用**。
+首次启动时密码会转成哈希写进 `~/.hob/system/config.json`，之后启动不用再带 `HOB_PASSWORD`。改密码在 **设置 → 通用**。
 
 ## 配置
 
@@ -87,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`。
 
@@ -124,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 示例：

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();
+}