From 1445774a3bf11c09f37ba3b65129dde7026bf833 Mon Sep 17 00:00:00 2001 From: ethernet Date: Wed, 9 Sep 2026 20:32:13 -0400 Subject: [PATCH] docs: describe runtime and backup contracts Electron consumes launch paths from its baked stamp, not a fixed Python-version directory. Backups preserve data and declarations, not runtime downloads or browser profiles. State both contracts in the build and migration guides. Keep the backup exclusions and quick/full distinction aligned across English and Chinese, with stable comparison anchors. The bilingual site build, website typecheck, pinned diagram linter and added-prose checks passed. All six affected routes and new backup links were checked in rendered output. Unrelated locale-link warnings remain. No native package acceptance is implied. --- apps/desktop/BUILDING.md | 24 ++++++++++--------- website/docs/getting-started/updating.md | 16 ++++++++++--- website/docs/reference/faq.md | 24 ++++++++++++++++--- website/docs/user-guide/desktop.md | 15 +++++------- .../current/getting-started/updating.md | 10 ++++++-- .../current/reference/faq.md | 23 +++++++++++++++--- 6 files changed, 81 insertions(+), 31 deletions(-) diff --git a/apps/desktop/BUILDING.md b/apps/desktop/BUILDING.md index bc24862828..d990bf7eab 100644 --- a/apps/desktop/BUILDING.md +++ b/apps/desktop/BUILDING.md @@ -36,9 +36,9 @@ This is broader than the source installer's extra named `all`. The backend runs from app resources. Launchers execute the store interpreter with the source and dependency paths; they do not boot through a relocated -venv executable. First boot verifies payload facts without changing signed files. -It can create user-state records and CLI links. Provider calls, model downloads, -and optional integration setup can still use the network. +venv executable. Startup can create user-state records and CLI links. +Provider calls, model downloads, and optional integration setup can still use +the network. Git is a platform exception: Windows stages Git for Windows with Bash. POSIX targets use system Git. A Mac without Command Line Tools can therefore @@ -48,15 +48,17 @@ User data remains outside the package. Optional additions use writable PM storage and complete Python environment generations, not writes into the app. See [Package management](../../website/docs/reference/package-management.md). -## Current Python migration blocker +## Python runtime contract -The staging pin now selects Python 3.14, but -`electron/payload-backend.ts` still defaults POSIX dependency discovery to -`venv/lib/python3.11/site-packages`. No build path supplies its `PYTHON_VER` -override. This mismatch prevents normal bundled macOS/Linux backend resolution. -The native resolver must use the payload's actual Python version before a -3.14 bundle can satisfy startup and update acceptance. A successful staging -step does not resolve this blocker. +The PM bundle builder records interpreter and dependency paths in the payload +manifest. `scripts/write-build-stamp.mjs` copies that runtime contract into the +desktop stamp. The desktop build embeds the stamp in Electron. +`electron/payload-backend.ts` reads `runtime.sitePackages` from this stamp. +It does not select a Python version or search for dependency directories. + +Staging does not prove native startup or package replacement. Those checks +use the [bundled-update acceptance suite](../../tests/install/BUNDLED_UPDATES.md). +Acceptance requires a native run with the actual signed release artifacts. ## Complete native build diff --git a/website/docs/getting-started/updating.md b/website/docs/getting-started/updating.md index 363f921c99..015d855b5b 100644 --- a/website/docs/getting-started/updating.md +++ b/website/docs/getting-started/updating.md @@ -93,7 +93,7 @@ This suppresses both cached update notices and passive update-check network requ For an admitted source checkout, `hermes update` runs these phases: -1. **Pre-update snapshot** — a lightweight state snapshot is saved by default (covers pairing data, cron jobs, `config.yaml`, `.env`, `auth.json`, and other state files that get modified at runtime; individual files over 1 GiB are skipped so a large sessions DB never slows the update down). Because the code swap and gateway restarts touch every profile, the same snapshot is taken for **every profile** on the install — each into its own `state-snapshots/` directory — and the post-update cron-jobs safety net checks each profile against its own snapshot. Controlled by `updates.pre_update_backup` (`quick` by default, `full` for a zip of all of `HERMES_HOME`, `off` to disable). Recoverable via the snapshot restore flow described under [Snapshots and rollback](../user-guide/checkpoints-and-rollback.md). Quick snapshots are file-loss recovery, not code-rollback insurance — for a coherent point-in-time rollback use `--backup` (full mode). +1. **Pre-update snapshot** — Hermes saves selected state files for every profile in that profile's `state-snapshots/` directory. These include pairing data, cron jobs, `config.yaml`, `.env`, and `auth.json`. Automatic quick snapshots skip individual files larger than 1 GiB. `updates.pre_update_backup` selects `quick`, `full`, or `off`. Full archives use the [backup exclusions](/reference/faq#hermes-backup-vs-hermes-profile-export). Recovery uses [Snapshots and rollback](../user-guide/checkpoints-and-rollback.md). Quick snapshots recover state files, not application code. 2. **Code update** — applies the configured source branch or stable release tag and updates submodules. 3. **Post-pull syntax validation + auto-rollback** — after the pull, Hermes compiles the nine critical files every `hermes` invocation imports at startup. If any fails to parse (e.g. an orphan merge-conflict marker, an accidentally truncated file), Hermes runs `git reset --hard ` to roll the install back so your shell stays bootable. Re-run `hermes update` once the upstream fix lands. 4. **Dependency preparation** — PM provisions required tools and prepares a complete Python environment from the new lock, existing extras, and enabled plugin requirements. It validates that environment before publishing its selection. @@ -203,7 +203,13 @@ updates: pre_update_backup: full ``` -`updates.pre_update_backup` is a single knob with three modes: `quick` (default — the lightweight state snapshot described above), `full` (the quick snapshot plus a complete `HERMES_HOME` zip; can add minutes on large homes), and `off` (no pre-update backup at all — `--no-backup` does the same for a single run). Legacy boolean values still work: `true` means `full`, `false` means `off`. +`updates.pre_update_backup` has three modes: + +- `quick` saves the selected state files described above. This is the default. +- `full` adds a zip archive with the [backup exclusions](/reference/faq#hermes-backup-vs-hermes-profile-export). Large data directories can take several minutes. +- `off` disables pre-update backups. `--no-backup` selects this mode for one run. + +Legacy boolean values remain supported: `true` means `full`, and `false` means `off`. :::tip Moving to a new machine instead? Update backups protect an in-place update. If you're migrating your whole setup to different hardware, use `hermes backup` + `hermes import` instead — see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine) and [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export). @@ -336,7 +342,11 @@ same manager that installed them. Their package files are not removed by the source uninstaller. Data deletion is separate from package removal. :::tip Moving to a new machine rather than leaving? -Take your setup with you before removing anything: `hermes backup` captures the entire `~/.hermes` directory including credentials, while `hermes profile export` packs a single profile with credentials excluded by design (so an export alone is not a full backup). See [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export). +Run `hermes backup` before you remove the installation. The full archive includes +credentials but excludes downloaded runtimes, dependency environments, caches, +and browser profiles. Review its skipped-file report before you delete source data. +`hermes profile export` packs one profile without credentials. +See [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export). ::: ### Manual Uninstall diff --git a/website/docs/reference/faq.md b/website/docs/reference/faq.md index dace4e3432..2cd6225f2c 100644 --- a/website/docs/reference/faq.md +++ b/website/docs/reference/faq.md @@ -766,7 +766,9 @@ Skills with very long descriptions are truncated to 40 characters in the Telegra ```bash hermes backup ``` - This creates a zip of your entire `~/.hermes/` directory — config, API keys, memories, skills, sessions, and profiles — saved to your home directory as `~/hermes-backup-.zip`. + This saves a zip archive at `~/hermes-backup-.zip`. + The full backup covers configuration, credentials, memories, skills, sessions, + and profiles under the Hermes data root. It is not an application or runtime image. 3. Copy the zip to the new machine and import it: ```bash @@ -793,16 +795,32 @@ hermes profile import ./work-backup.tar.gz work The imported profile will have all config, memories, sessions, and skills from the export. You may need to update paths or re-authenticate with providers if the new machine has a different setup. -### `hermes backup` vs `hermes profile export` +### `hermes backup` vs `hermes profile export` {#hermes-backup-vs-hermes-profile-export} | Feature | `hermes backup` | `hermes profile export` | | :--- | :--- | :--- | | **Use Case** | **Full machine migration** | **Porting/sharing a specific profile** | -| **Scope** | Global (entire `~/.hermes` directory) | Local (single profile directory) | +| **Scope** | Hermes data root, with the exclusions listed below | Single profile directory | | **Includes** | All profiles, global config, API keys, sessions | Single profile: SOUL.md, memories, sessions, skills | | **Credentials** | **Included** (`.env` and `auth.json`) | **Excluded** (stripped for safe sharing) | | **Format** | `.zip` | `.tar.gz` | +The full backup excludes: + +- The source checkout, dependency environments, and downloaded tools, models, and runtimes. +- Build caches, checkpoints, previous backups, and quick snapshots. +- Browser profiles, including copies of real-browser credentials. +- Bytecode, SQLite sidecars, `gateway.pid`, `cron.pid`, and `.backup.lock`. + +`hermes backup --quick` saves selected state files instead of a full archive. +It is not a replacement for the full backup before a machine migration. + +Full backups report files that fail to copy. An archive can therefore exist +with missing data. Review the skipped-file report before you remove the source installation. +Restored package declarations let PM download dependencies again. Bytecode and +SQLite sidecars regenerate locally. The exclusions do not remove `.env` or +`auth.json` from the full backup. + **Manual fallback (rsync):** If you prefer to copy files directly, exclude the code repo: ```bash rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/ diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md index 01f26b51af..09360b5046 100644 --- a/website/docs/user-guide/desktop.md +++ b/website/docs/user-guide/desktop.md @@ -32,13 +32,9 @@ hermes desktop That uses the selected installation's configuration and data home. -:::warning Current source-branch package limit -The Python 3.14 migration still needs a POSIX payload-resolver correction: -Electron currently defaults to a Python 3.11 dependency path. Do not treat -new macOS/Linux bundles from this branch as accepted until that correction -and native startup/update checks pass. This does not describe the status of -an older published package. -::: +The bundled app uses the interpreter and dependency paths embedded in its +build stamp. It does not use a fixed Python-version directory. +Successful payload staging does not prove native installation, startup, or updates. ### Package variants and CLI commands @@ -53,8 +49,9 @@ release matrix leg. execution aliases expose `hermes`, `hermes-agent`, and `hermes-acp`. - **macOS:** copy the app from its DMG into Applications before opening it. Bundled startup attempts to link those CLI commands into `~/.local/bin`. - Add that directory to your shell's PATH. Existing entries, including stale - symlinks, are left untouched; inspect them if the wrong command runs. + Add that directory to your shell's PATH. Startup repairs broken links that + name the same command in an old bundled payload. It preserves regular files, + live links, and links to unrelated commands. - **Linux:** source development and AppImage build support exist, but the bundled desktop release legs are disabled. Do not assume a published Linux package from the local build target alone. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/updating.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/updating.md index 689cb770dc..6e73ceee4a 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/updating.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/updating.md @@ -24,7 +24,7 @@ hermes update 运行 `hermes update` 时，将依次执行以下步骤： -1. **更新前快照** — 默认保存一份轻量级状态快照（涵盖配对数据、cron 任务、`config.yaml`、`.env`、`auth.json` 及其他运行时修改的状态文件；单个超过 1 GiB 的文件会被跳过，因此大型会话数据库不会拖慢更新）。由 `updates.pre_update_backup` 控制（默认 `quick`，`full` 为整个 `HERMES_HOME` 的 zip 备份，`off` 为禁用）。可通过 [快照与回滚](../user-guide/checkpoints-and-rollback.md) 中描述的快照恢复流程进行恢复。 +1. **更新前快照** — Hermes 在每个 profile 的 `state-snapshots/` 目录中保存指定的状态文件，包括配对数据、cron 任务、`config.yaml`、`.env` 和 `auth.json`。自动快速快照会跳过单个大于 1 GiB 的文件。`updates.pre_update_backup` 可选择 `quick`、`full` 或 `off`。完整归档遵循[备份排除规则](/reference/faq#hermes-backup-vs-hermes-profile-export)。恢复方法见[快照与回滚](../user-guide/checkpoints-and-rollback.md)。快速快照恢复的是状态文件，不是应用程序代码。 2. **Git pull** — 从 `main` 分支拉取最新代码并更新子模块 3. **依赖安装** — 运行 `uv pip install -e ".[all]"` 以获取新增或变更的依赖项 4. **配置迁移** — 检测自当前版本以来新增的配置选项并提示设置 @@ -50,7 +50,13 @@ updates: pre_update_backup: full ``` -`updates.pre_update_backup` 是单一开关，有三种模式：`quick`（默认 — 上述轻量级状态快照）、`full`（快速快照加上完整的 `HERMES_HOME` zip 备份；在大型 home 目录上可能增加数分钟）、`off`（完全不做更新前备份 — `--no-backup` 对单次运行有相同效果）。旧版布尔值仍然有效：`true` 等同于 `full`，`false` 等同于 `off`。 +`updates.pre_update_backup` 有三种模式： + +- `quick` 保存上述指定的状态文件。这是默认模式。 +- `full` 另加一份遵循[备份排除规则](/reference/faq#hermes-backup-vs-hermes-profile-export)的 zip 归档。大型数据目录可能需要几分钟。 +- `off` 禁用更新前备份。`--no-backup` 为单次运行选择此模式。 + +旧版布尔值仍然有效：`true` 等同于 `full`，`false` 等同于 `off`。 ### Windows：另一个 `hermes.exe` 正在运行 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md index d52ac0cd13..0750500380 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/faq.md @@ -739,7 +739,9 @@ skills: ```bash hermes backup ``` - 这会将您整个 `~/.hermes/` 目录（配置、API key、记忆、技能、会话和 profiles）打包为 zip 文件，保存到主目录 `~/hermes-backup-.zip`。 + 归档保存到 `~/hermes-backup-.zip`。 + 完整备份涵盖 Hermes 数据根目录中的配置、凭据、记忆、技能、会话和 profiles。 + 它不是应用程序或运行时的完整镜像。 3. 将 zip 文件复制到新机器并导入： ```bash @@ -766,16 +768,31 @@ hermes profile import ./work-backup.tar.gz work 导入的 profile 将包含导出时的所有配置、记忆、会话和技能。如果新机器的设置不同，您可能需要更新路径或重新向提供商进行身份验证。 -### `hermes backup` 与 `hermes profile export` 的对比 +### `hermes backup` 与 `hermes profile export` 的对比 {#hermes-backup-vs-hermes-profile-export} | 功能 | `hermes backup` | `hermes profile export` | | :--- | :--- | :--- | | **使用场景** | **整机迁移** | **移植/共享特定 profile** | -| **范围** | 全局（整个 `~/.hermes` 目录） | 局部（单个 profile 目录） | +| **范围** | Hermes 数据根目录，下列排除项除外 | 单个 profile 目录 | | **包含内容** | 所有 profiles、全局配置、API key、会话 | 单个 profile：SOUL.md、记忆、会话、技能 | | **凭据** | **包含**（`.env` 和 `auth.json`） | **排除**（为安全共享而剥离） | | **格式** | `.zip` | `.tar.gz` | +完整备份不包含以下内容： + +- 源代码仓库、依赖环境，以及下载的工具、模型和运行时。 +- 构建缓存、checkpoints、旧备份和快速快照。 +- 浏览器配置目录，包括真实浏览器凭据的副本。 +- 字节码、SQLite 辅助文件，以及 `gateway.pid`、`cron.pid` 和 `.backup.lock`。 + +`hermes backup --quick` 只保存指定的状态文件，不生成完整归档。 +迁移机器前，它不能替代完整备份。 + +完整备份会报告复制失败的文件。因此，即使归档已生成，也可能缺少部分数据。 +删除源安装前，请检查跳过文件的报告。 +还原后的软件包声明可让 PM 再次下载依赖项。字节码和 SQLite 辅助文件在本地重新生成。 +上述排除项不会把 `.env` 和 `auth.json` 排除在完整备份之外。 + **手动备选方案（rsync）：** 如果您倾向于直接复制文件，请排除代码仓库： ```bash rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/