hob-bot 1.3.0 → 1.4.0

package/README.md

@@ -1,48 +1,56 @@
 # 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
 
 > The interface is currently Chinese-only. Hob is a single-user app you run on your own machine or server.
 
-![Hob: chat with the main assistant, a running job and its live transcript](docs/screenshots/chat.png)
+![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.*
+
+## 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
+
+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.
+
+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)
 
-**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.
+### Skills
 
-**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.
+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.
 
-**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.
+### Rules
 
-**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.
+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.
 
-**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.
+### Pages and knowledge
 
-**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.
+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.
 
-**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.
+### Cloud desktop and tools
 
-**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.
+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.
 
-**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.
+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.
 
-**Tools that come with it:**
+### Usage and cost
 
-- **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.
+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.
 
-**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.
+### Light and dark
 
-![Hob on a phone: assistant list, a delegation card and assistant settings](docs/screenshots/mobile.png)
+Hob has light and dark themes and can follow the system setting.
 
 ## Quick start
 
@@ -155,7 +163,7 @@ npm test             # vitest
 npm run typecheck
 ```
 
-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.
+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>`.
 
 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

@@ -1,48 +1,56 @@
 # Hob
 
-**一个自己部署、真正动手干活的私人助手。** 你只跟主助手 Hob 说话：它把要做的事交给后台任务执行，有风险的操作先问你；同一类活反复出现时，它会提议分出一个专门的助手。
+Hob 是一个自己部署、真正动手处理事务的私人助手。你只和 Hob 说话：小事它当场处理，大活交给后台任务。
 
 [English](README.md) · [架构说明](docs/architecture.md) · MIT 许可证
 
 > 目前界面只有中文。Hob 是单用户应用，运行在你自己的电脑或服务器上。
 
-![Hob：与主助手的对话、正在运行的任务和实时执行过程](docs/screenshots/chat.png)
+![与 Hob 的对话，展示任务、页面、文件、确认等卡片及浮层](docs/screenshots/chat.jpg)
 
-## 能做什么
+*示意图：浮层卡片由单独截图合成。*
 
-**一条对话，真实干活。** 用平常的话提要求，Hob 会派出任务在后台执行，任务有自己的命令行、文件和工具。任务卡上能看到进度和用时，点开可以实时看每一步，中途补充要求，或者直接停止。
+## 怎么运作
 
-**从习惯里长出来的助手。** 同类要求反复出现时，Hob 会提议创建专门的助手，比如「写作」「服务器」「记账」。每个助手有自己的对话、职责、执行前确认规则、定时任务和工作日志，都在同一个面板里设置。
+你只和助手说话，不直接和任务交互。助手小事当场处理，大活交给任务；任务只向助手交 Markdown 结果和文件，有问题也只问助手。助手决定给你看什么、什么时候问你；全局规则和每个助手自己的规则决定哪些事情要先征求你的确认。
 
-**看得见的委派。** Hob 把事交给合适的助手后，在自己的对话里留一张委派卡，上面有状态、关联任务和待确认的问题，问题可以直接在卡上回答。派活会带上你的原话；在接收助手的对话中说话可以接手转交，在对话中回复也能结束待答提问。
+## 功能
 
-**可以接着做。** 助手可以读取文件，查看任务状态、过程和结果，无需打断任务；已结束的任务可以续做，每轮分别保留卡片和报告。助手会估计任务用时，超时后收到提醒；结束通知会写明实际用时和预计用时。
+### 助手、任务和定时
 
-**自己定规则。** 在设置中管理所有助手和任务的全局规则，分为「执行前确认」和「一律照做」。每个助手也有自己的规则；选一次「一直允许」就会记成规则。
+每个助手有自己的对话、职责、规则、技能、定时任务和工作日志。同类工作反复出现时，Hob 会提议创建专门的助手；向其他助手转交时，对话中的转交卡会跟踪状态、带上你的原话，你也可以在接收助手的对话中接手。
 
-**定时任务。** 每日简报、周报、月底对账，按 cron 式的时间表运行，任务卡和结果发到对应助手的对话里。定时任务也可以绑定已保存的助手技能。
+任务可查看过程、停止或续做，每轮记录分别保留；超出预计用时后，助手会收到督办提醒。定时任务把任务卡和结果发到对应的对话里。助手输出时对话会跟着往下滚，输入框里也可以直接粘贴截图。
 
-**知识库。** 整理、搜索和预览文件，将知识库绑定给助手，并从出处跳转到原文段落。配置向量模型后可混合检索，也支持为 PDF 文字建立索引。
+手机上可查看助手列表、对话和档案，支持滑动回复和长按操作。助手需要你确认，或任务受阻、失败时，可以收到推送通知。
 
-**云桌面。** 可选的独立容器为每个助手提供屏幕和浏览器，也可允许指定助手使用公共屏幕。助手可以直接操作浏览器，和任务共用登录状态，并在对话中发送截图。你可以观看或接管，使用剪贴板同步、本机输入法和键盘快捷键。
+![手机上的助手列表、助手提出的确认问题和助手档案](docs/screenshots/mobile.jpg)
 
-**更清晰的工作区。** 右栏集中展示助手信息、任务和文件，两个列表滚动到底自动加载更多，二级页面刷新后仍可通过地址恢复。助手头像会标出完成未读的工作。不再需要的助手可以归档，对话和历史任务仍会保留。
+### 技能
 
-**用页面代替大段文字。** 讲流程、做对比、写调研时，助手可以交一页图文页面。页面在侧栏打开，模型边写边显示。
+技能归助手管：派活时由助手决定给任务哪几份，定时任务可以绑定一份。任务做完、结果值得留下时，助手让做这件事的原任务在自己的会话里把它写成技能，写之前把命令和脚本真跑一遍。管同一类事的技能会合成一份，旧的归档；任务照着技能做时发现哪一步过时，助手会让它改对。
 
-**自带的能力：**
+### 规则
 
-- **联网搜索**：支持 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：向左滑动消息即可回复，长按弹出菜单。支持亮色和暗色主题。
+### 页面和知识库
 
-![手机上的 Hob：助手列表、委派卡、助手设置](docs/screenshots/mobile.png)
+助手可以把方案比较、调研等内容做成页面，在侧栏打开。知识库支持整理、搜索和预览文件，绑定到助手并从引用跳到原文；配置向量模型后可混合检索，也支持为 PDF 文字建立索引。
+
+### 云桌面和工具
+
+可选的云桌面为每个助手提供与任务共用的屏幕和浏览器，也可允许指定助手使用公共屏幕。助手可以自己操作浏览器并在对话中发送截图，你可以观看或接管。
+
+助手和任务可以使用 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 支持浅色、深色，以及跟随系统设置。
 
 ## 快速开始
 
@@ -155,7 +163,7 @@ npm test             # vitest
 npm run typecheck
 ```
 
-开发地址加上 `?mock=1`，界面会使用浏览器内的模拟后端，不需要模型和服务端。上面的截图就是这样拍的。
+开发地址加上 `?mock=1`，界面会使用浏览器内的模拟后端。上面的截图使用专门的模拟场景；执行 `npx vite build` 后，将 `CHROME_PATH` 设为 Chrome 或 Chromium 可执行文件路径，再运行 `CHROME_PATH=/path/to/chrome node scripts/readme-screenshots.mjs` 重新拍摄。要另行导出完整的详细场景图，可加上 `--all <输出目录>`。
 
 技术栈：Node 22 + TypeScript，Hono + SSE，Vite + React，CSS 全部手写。智能体引擎是进程内运行的 [pi](https://github.com/earendil-works/pi) SDK。设计、数据布局和工具列表见 [docs/architecture.md](docs/architecture.md)。