asmgr 0.1.0 → 0.3.0

package/README.md

@@ -5,13 +5,13 @@
 ![pnpm](https://img.shields.io/badge/pnpm-10.x-f69220?logo=pnpm&logoColor=white)
 ![Vitest](https://img.shields.io/badge/tests-Vitest-6E9F18?logo=vitest&logoColor=white)
 
-**把编码 agent 的 CLI 会话导出成 Markdown 或单文件 HTML。** `asmgr`（Agent Session ManaGeR）只读地读取 GitHub Copilot CLI、Claude Code、OpenAI Codex CLI 写在本地的会话历史，再把选定的会话导出成一份忠实、自包含的报告。它是**一个**无 scope 的公开 npm 包，命令也叫 `asmgr`；HTML 与 Markdown 是它的导出能力，而非独立发布的产品。
+**把编码 agent 的 CLI 会话与公开 ChatGPT 分享导出成 Markdown 或单文件 HTML。** `asmgr`（Agent Session ManaGeR）读取 GitHub Copilot CLI、Claude Code、OpenAI Codex CLI、DeepSeek Harness（DSH）写在本地的会话历史，也可捕获公开 ChatGPT `/share/` 页面，再把选定的会话导出成自包含报告；来源无法完整保留的内容会显式标记。它是**一个**无 scope 的公开 npm 包，命令也叫 `asmgr`；HTML 与 Markdown 是它的导出能力，而非独立发布的产品。
 
 HTML 产物高度复刻 Copilot CLI 内置 `/share html` 的排版（Primer 主题、sticky header、类型筛选 pill、侧栏目录、上一条/下一条用户消息跳转、搜索），差异见 [ADR 0003](docs/adr/0003-archive-reconstruction-fidelity.md)。Markdown 产物遵循 Copilot CLI `/share file` 的结构与约定（`### 💬/👤/🔧/✅` 标题、`<sub>⏱️</sub>` 耗时戳、`<details>` 折叠、diff 围栏、`[!NOTE]` 头块）。
 
-它对 agent 状态目录**只读**：不写 `.copilot`、`.claude`、`.codex`。读命令（`list` / `search` / `show` / `html` / `md`）都严格本地——从不联系任何云端或会话同步后端、从不通过网络拉取会话历史。（唯一走网络的是 `backup`：它按你配置的 restic 远端做备份 / 恢复。）
+它对 agent 状态目录**只读**：不写 `.copilot`、`.claude`、`.codex`、`.dsh`。传本地 session id 或 `--file` 时，`list` / `search` / `show` / `html` / `md` 都严格本地。只有显式导入或直接读取 ChatGPT 分享 URL，以及按配置访问 restic 仓库的 `backup` 命令会联网。
 
-> **归档 ≠ 恢复。** 导出的报告是有损、只读、给人看的产物，**不能**反推回可 `--resume` 的原生会话。把会话忠实恢复到"另一台机器能续聊"是一条**规划中**的独立能力（来源 = 备份快照 ∪ 另一台机器），与只读归档严格分层——理念见 [ADR 0001](docs/adr/0001-scope-archive-and-restore.md) 与 [ADR 0004](docs/adr/0004-restore-fidelity-and-safety.md)。
+> **归档 ≠ 恢复。** 导出的报告是有损、只读、给人看的产物，**不能**反推回可 `--resume` 的原生会话。把会话忠实恢复到"另一台机器能续聊"是一条**规划中**的独立能力（来源 = 备份快照 ∪ 另一台机器），与只读归档严格分层——理念见 [ADR 0001](docs/adr/0001-scope-archive-and-restore.md)。
 
 ## 功能
 
@@ -22,32 +22,66 @@ HTML 产物高度复刻 Copilot CLI 内置 `/share html` 的排版（Primer 主
 | 在单个会话内搜索 | `asmgr search "关键词" --session <session-id>` |
 | 打印一个会话 | `asmgr show <session-id> --agent claude` |
 | 只看对话主干（跳过工具调用） | `asmgr show <session-id> --format dialogue` |
+| 导入公开 ChatGPT 分享 | `asmgr import 'https://chatgpt.com/share/<id>'` |
+| 直接读取 ChatGPT 分享主干 | `asmgr show 'https://chatgpt.com/share/<id>' --format dialogue` |
 | 导出 Markdown（Copilot `/share file` 风格） | `asmgr md <session-id> -o session.md` |
 | 导出 HTML（高度复刻 `/share html`） | `asmgr html <session-id> -o session.html` |
+| 直接把 ChatGPT 分享导出 HTML | `asmgr html 'https://chatgpt.com/share/<id>' -o session.html` |
 | 读取任意位置的会话文件（scp 来的 / 恢复出来的） | `asmgr html --file /path/to/events.jsonl -o session.html` |
-| 搜索恢复出来的备份缓存目录 | `asmgr search "关键词" --file /path/to/restored-cache` |
-| 运行备份（restic 封装） | `asmgr backup run --dry-run` |
+| 搜索任意位置的会话目录 | `asmgr search "关键词" --file /path/to/sessions` |
+| 运行加密增量备份 | `asmgr backup run --dry-run` |
+| 把备份快照恢复到隔离缓存 | `asmgr backup cache latest --target ~/.cache/asmgr/restic-cache` |
 
 ## 支持的 agent 与数据来源
 
 - **Copilot CLI**：读取 `~/.copilot/session-state/*/events.jsonl`；同时用 `~/.copilot/session-store.db` 列出会话与元信息。events.jsonl 缺失（老会话被 prune、或只迁移了 DB）时回退到 DB 的 `turns` 表（lossy：只有 user/assistant 文本，工具与用户决策不可恢复）。所有读命令可用 `--copilot-db <path>` 覆盖 DB 路径。
 - **Claude Code**：读取 `~/.claude/projects/**/*.jsonl`
 - **Codex CLI**：读取 `~/.codex/sessions/**/*.jsonl`
+- **DeepSeek Harness（DSH）**：读取 `${DSH_HOME:-~/.dsh}/sessions/<project>/<session>/session[.vN].jsonl[.zstd]`；用 `--dsh-root <path>` 覆盖会话根目录。目录发现选择每个会话的最高版本文件；`--file` 指向单个文件时读取指定版本。
+- **ChatGPT 公共分享**：`asmgr import <url>` 从 `/share/<id>` 页面的 React Router 水合数据读取
+  `linear_conversation`。默认托管目录中的快照会自动进入 `list/search/show/html/md`；
+  也可把 URL 直接传给 `show/html/md`，不落盘使用。
 
-每个读命令（`list` / `search` / `show` / `html` / `md`）都接受 `--file <path>`（别名 `--events <path>`），读一个显式的 `*.jsonl` 文件——或一个会被遍历出这些文件的目录——而不是 live agent 主目录。每个文件的 agent 格式自动探测（用 `--agent` 覆盖）。这就是渲染从别的机器拷来的会话、或搜索 restic 恢复出来的备份缓存（无需先放回 `~/.copilot`）的方式。
+每个读命令（`list` / `search` / `show` / `html` / `md`）都接受 `--file <path>`（别名 `--events <path>`），读一个显式的 `*.jsonl` / DSH `*.jsonl.zstd` / `*.chatgpt-share.json` 文件——或一个会被遍历出这些文件的目录——而不是 live agent 主目录。每个文件的 agent 格式自动探测（用 `--agent` 覆盖）。未知 JSON 会明确报错，不再静默显示成空会话。
+
+### DSH 读取与主干
+
+**默认自动使用 DSH home，无需传 `--dsh-root`。** 会话目录优先级为：显式 `--dsh-root` → 环境变量 `DSH_HOME` 下的 `sessions/` → 当前用户的 `~/.dsh/sessions/`。`--dsh-root` 仅用于覆盖会话日志根目录，例如读取备份；它不是 DSH 源码目录，也不是项目工作目录。
+
+```bash
+asmgr list --agent dsh
+asmgr show <session-id> --agent dsh --format dialogue
+asmgr show --file /path/to/session.jsonl.zstd --format dialogue
+asmgr html <session-id> --agent dsh -o dsh-session.html
+```
+
+以官方 [`dsh-v0.1.5-rc.1`](https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.1.5-rc.1) 为基线，直接使用 `dsh-session-format-catalog` 的 v0→v3 解码/迁移及 `dsh-session/surface` 的原始追加消息筛选。迁移在内存中进行，不依赖本机 DSH 安装、不启动插件、不改写源日志。主干包含直接用户输入、助手正文，以及原生或 PTC 调用中 `ask_user_question` 的题目、全部选项与匹配的回答；普通工具的参数和结果完全不显示。回答按官方格式记录，不额外推断回答者身份。
+
+范围保持有限：不解释未知插件事件、注入上下文、失败模型尝试或任意 `meta`；不把压缩 replacement 当成新对话，不重复拼接 fork 的父会话。只显示官方 compact checkpoint 对应的摘要。图片/文件只显示占位符并提示损失；完整工具仍在 text/HTML/Markdown 中保留。HTML/Markdown 暂无独立的主干导出开关。
+
+压缩日志需要运行时提供 Zstandard API（Node.js ≥ 22.15）；运行时缺少帧解码能力时明确报错，不把未读取内容当空会话。未知版本、官方迁移器拒绝的旧日志、损坏或未写完的文件会报出路径与原因，不尝试自定义补救，也不会自动回退到旧一代文件。已知官方边界包括 v0 中的 `subagent/descriptor.version: 2`：最新迁移器明确拒绝它；不能仅把该字段改成 3 来冒充兼容。
 
 ## <a id="install"></a>安装
 
-四种方式，按摩擦从低到高。`asmgr` 是单一、无 scope 的公开 npm 包。
+`asmgr` 已发布为单一、无 scope 的公开 npm 包。以下是安装已发布版本的方法；维护者推送代码前请先看[版本与发布](#release)，**普通推送 `main` 可能自动发版**。
 
-### npm（发布到 registry 后）
+### npm
 
 ```bash
 npm i -g asmgr
 asmgr list --agent all
 ```
 
-> 发布由手动触发的 CI（semantic-release）驱动。registry 上线前，请用下面任一方式。
+各安装方式当前能力如下：
+
+| 安装方式 | 读取、搜索、导入与导出 | `asmgr backup` |
+|---|---|---|
+| npm / `npm i -g github:` | ✅ | ❌ 暂未包含备份运行时 |
+| 原生二进制 | ✅，但不读取 Copilot live SQLite | ❌ 暂未包含备份运行时 |
+| 源码 checkout | ✅ | ✅ |
+
+<details>
+<summary>其他安装方式与运行时差异</summary>
 
 ### 原生二进制（无需 Node）
 
@@ -92,6 +126,8 @@ asmgr list --agent all
 
 开发时直接跑源码：`pnpm dev list --agent all`（经 tsx）。自行编译原生二进制（需要 [Bun](https://bun.sh)）：`pnpm run binaries`，四平台产物落在 `dist/asmgr-*`。
 
+</details>
+
 ## 首次运行
 
 1. 按上面任一方式装好 `asmgr`。
@@ -127,7 +163,7 @@ asmgr list --agent claude --claude-root /path/to/claude/projects
 
 ```bash
 asmgr list --by project     # 按仓库聚类会话
-asmgr list --by agent       # 按 copilot / claude / codex 分组
+asmgr list --by agent       # 按 copilot / claude / codex / chatgpt 分组
 ```
 
 分组模式每组打印一个 `# <组> (<数量>)` 头（组间排序，组内按最后活动时间从新到旧），随后是 `组`、`agent`、`session-id`、`最后活动`、`条目数` 的 tab 分隔行。
@@ -145,6 +181,47 @@ asmgr search "database migration" --session <session-id>   # 只在一个会话
 
 `--session <id>` 把搜索限定到一个会话（先精确匹配 id，否则按前缀匹配）——用来在**当前这个会话**里按关键词找模型回复，不必先用 `--file` 指路径。
 
+### `asmgr import`
+
+导入公开 ChatGPT 分享页：
+
+```bash
+asmgr import 'https://chatgpt.com/share/<conversation-id>'
+```
+
+默认写入 asmgr 托管目录，随后可直接用 session id 执行 `list/search/show/html/md`。
+也可以把分享 URL 直接传给 `show/html/md`，跳过本地保存。
+
+<details>
+<summary>ChatGPT 存储路径、输出方式与保真限制</summary>
+
+托管目录优先使用 `ASMGR_DATA_HOME`，其次使用 `XDG_DATA_HOME`；都未设置时按平台选择：
+
+| 平台 | 默认目录 |
+|---|---|
+| Linux | `~/.local/share/asmgr/imports/chatgpt` |
+| macOS | `~/Library/Application Support/asmgr/imports/chatgpt` |
+| Windows | `%LOCALAPPDATA%\asmgr\imports\chatgpt` |
+
+三种写入方式的后续读取不同：
+
+| 导入方式 | 后续读取 |
+|---|---|
+| 默认目录 | 自动进入 `list/search/show/html/md` |
+| `--chatgpt-root <dir>` | 后续读命令继续传相同的 `--chatgpt-root` |
+| `-o <path>` | 用 `--file <path>` 显式读取；若改为扫描目录，文件名需以 `.chatgpt-share.json` 结尾 |
+
+新快照权限为 `0600`；目标已存在时拒绝覆盖，确认要刷新才加 `--force`。普通 ChatGPT 页面、私有
+`/c/...`、`/g/.../c/...` 地址栏会话及其它网站 URL 都不会发起抓取：检测到地址栏私有
+会话链接时，会用中文明确提示先在 ChatGPT 中点击“分享”，再复制 `/share/` 链接。
+
+捕获不启动浏览器：直接解码页面 HTML 内的 turbo-stream 水合数据。快照保留完整公开
+`linear_conversation`，便于未来适配器改进后重新解析。公开页隐藏的工具结果无法恢复；
+图片或附件若只有资源指针而没有内容，会显示占位符并把来源标记为 lossy。工具调用与结果
+只有在同一用户轮次内存在唯一匹配时才合并，关联不明确时保留独立结果或 pending 状态。
+
+</details>
+
 ### `asmgr show`
 
 以 text、dialogue 或 JSON 打印一个会话：
@@ -153,20 +230,30 @@ asmgr search "database migration" --session <session-id>   # 只在一个会话
 asmgr show <session-id> --agent codex
 asmgr show <session-id> --agent copilot --format dialogue
 asmgr show <session-id> --agent codex --format json
+asmgr show 'https://chatgpt.com/share/<id>' --format dialogue
 ```
 
-`--format dialogue` 只保留**用户消息 / 用户决策（`ask_user` 的回答）/ 压缩摘要 / 助手回复**，跳过工具调用与 reasoning。工具噪音被剔掉后，每条用户 prompt 直接紧跟回答它的助手回复，prompt↔回复的对应关系一目了然——适合会话复盘、交接和收尾盘点等需要通读对话主干的场景。`--format text` 则含完整工具参数+结果、子代理/技能/计划/压缩统计。
+`--format dialogue` 只保留**用户消息 / 交互式提问与选项 / 用户决策或回答 / 压缩摘要 / 助手回复**，跳过普通工具调用的全部内容与 reasoning。DSH 的 `ask_user_question` 保留题目、全部选项、单/多选信息、选中项和自由回答；Copilot 的 `ask_user` 保留题目、全部候选项及回答。工具噪音被剔掉后，每条用户 prompt 直接紧跟回答它的助手回复，prompt↔回复的对应关系一目了然——适合会话复盘、交接和收尾盘点等需要通读对话主干的场景。`--format text` 则含完整工具参数+结果、子代理/技能/计划/压缩统计。
 
 ### `asmgr html`
 
-写出一份自包含 HTML 报告。它高度贴合 Copilot CLI `/share html`（sticky header、筛选 pill、侧栏目录、搜索、展开/折叠、上一条/下一条用户消息跳转、主题切换、紧凑模式、Markdown 表格、KaTeX 数学），但不是逐像素/逐字节一致。有意为之的差异：
+写出一份自包含 HTML 报告，支持搜索、筛选、侧栏目录、主题切换、Markdown 表格与 KaTeX 数学：
+
+```bash
+asmgr html <session-id> --agent copilot -o report.html
+asmgr html <session-id> -s agent-summary.html -o report.html   # 顶部钉一份 HTML 总结
+asmgr html 'https://chatgpt.com/share/<id>' -o report.html
+```
+
+<details>
+<summary>HTML 与 Copilot CLI `/share html` 的差异</summary>
 
 - **用 React 渲染，而非官方 vanilla bundle 资产。** 抽取的上游 CSS/JS 只当逆向参照，不随运行时产物发布。
 - **Shiki 语法高亮**，覆盖 markdown 代码围栏与 diff 风格的工具输出，双 light+dark 主题，页面切主题时代码无需重载即重新着色。
 - **24 小时制时间戳**（会话起点 `YYYY-MM-DD HH:MM:SS`；同日条目 `HH:MM:SS`，跨日 `MM-DD HH:MM:SS`）——en-US 默认的 12 小时制（`PM/AM`）太容易读错。
 - **耗时 pill**，由 `startedAt` → 最后一条条目算出，显示在 header。
 - **agent 总结卡片**，用 `--summary <file.html>` 钉在时间线顶部（原样渲染受信任 HTML；`data-index="summary"`，真实第 1 条仍是第 1 条）。
-- **合并的工具卡片**，五种结果态（success / failure / rejected / denied / pending），配对应的边框色与状态图标。
+- **合并的工具卡片**，六种结果态（success / failure / rejected / denied / pending / redacted），配对应的边框色与状态图标。
 - **`ask_user` 的回答被抽成一等「用户决策」条目**（`user/decision`）：既保留原始工具卡片，又让用户的选择/回答在时间线里单独、显眼地出现——复盘或交接时不会把决策埋没在成百上千次工具调用里。
 - **子代理 / 技能 / 计划条目**，从 `events.jsonl` 解析、各自成卡片 + 筛选 pill。子代理卡片在可得时显示记录到的身份、模型、描述、失败详情。这些超出 Copilot 自身 `/share html` 的筛选集。
 - **数据源回退警告 pill**，当解析器不得不读 `events.jsonl` 之外的东西时显示在 header；回退到 `db.turns` 时进一步说明「交互式用户决策与工具条目在此模式下不可恢复」。
@@ -174,10 +261,7 @@ asmgr show <session-id> --agent codex --format json
 - **单行 info 条目**（模型切换 / 取消）默认展开而非折叠——与官方 bundle 不同，让「Model changed from X to Y」「Operation cancelled by user」这类一行信息一眼可见；多行 info 仍折叠。
 - **只存在于 live 内存的条目离线无法重建**，包括吉祥物启动横幅、临时重试提示、`/share` 成功回执。见 [ADR 0003](docs/adr/0003-archive-reconstruction-fidelity.md) 与下文[「Copilot 时间线与离线映射」](#timeline-ref)。
 
-```bash
-asmgr html <session-id> --agent copilot -o report.html
-asmgr html <session-id> -s agent-summary.html -o report.html   # 顶部钉一份 HTML 总结
-```
+</details>
 
 ### `asmgr md`
 
@@ -187,41 +271,93 @@ asmgr html <session-id> -s agent-summary.html -o report.html   # 顶部钉一份
 asmgr md <session-id> --agent copilot -o report.md
 asmgr md <session-id> --no-reasoning -o report.md             # 去掉 reasoning 条目
 asmgr md <session-id> -s summary.md -o report.md              # 注入一份 markdown 总结
+asmgr md 'https://chatgpt.com/share/<id>' -o report.md
 ```
 
 ### `asmgr backup`
 
-`backup` 是一个命令组：
+`backup` 是正式的 restic 备份命令组：
 
 ```bash
-asmgr backup run --dry-run     # 预览 restic 备份
-asmgr backup run               # 运行 restic 备份封装（backup.sh）
-asmgr backup                   # `backup run` 的向后兼容别名
-asmgr backup cache latest --target ~/.cache/asmgr/restic-cache   # 把一个快照恢复进缓存目录
+asmgr backup run --dry-run
+asmgr backup run
+asmgr backup cache latest --target ~/.cache/asmgr/restic-cache
 ```
 
-`backup cache` 把 agent 历史从 restic 快照恢复进一个**本地缓存目录**（绝不恢复进 live 的 `~/.copilot`、`~/.claude`、`~/.codex`——那会被拒绝），之后读命令可用 `--file` 在其上工作（未来还有 `--source cache`）。加 `--host <h>` 钉某主机的快照，`--dry-run` 只预览、不实际恢复。
+`backup run` 默认备份 `~/.copilot`、`~/.claude`、`~/.codex` 与 asmgr 托管的 ChatGPT
+导入目录，只处理实际存在的路径。运行时会先尽力把 Copilot 的 SQLite WAL 合入主库，
+再执行加密、去重、增量备份；SQLite 热文件、锁文件和 Copilot 进程日志不会进入快照。
+每次快照带 `agent-session-manager` 与当前主机标签，并应用 daily / weekly / monthly
+保留策略。
+
+`backup cache` 把指定快照恢复到独立缓存，明确拒绝 home 目录及 live 的
+`~/.copilot`、`~/.claude`、`~/.codex`，也拒绝 asmgr 托管的 ChatGPT 导入目录。
+缓存用于 `list/search/show/html/md --file`，不等于把会话恢复成原 agent 可以
+`--resume` 的状态。
+
+> 当前备份命令需要从源码 checkout 运行；npm 包和原生二进制尚未包含备份运行时。
+
+<details>
+<summary>备份配置与 systemd 自动运行</summary>
 
-备份是未来检索 / 搜索工作的一个数据源。当前搜索读 live 本地历史；对恢复出来的备份缓存做**持久化**索引单独跟踪（issue #1）。今天要临时用，就恢复一个快照，再用 `--file` 让任意读命令指过去：
+#### 配置
+
+复制配置模板并限制权限：
 
 ```bash
-restic restore latest --target /tmp/cache          # 恢复一个快照
-asmgr search "关键词" --file /tmp/cache           # 搜索恢复出来的缓存
-asmgr html <session-id> --file /tmp/cache -o s.html
+cp secrets.env.example secrets.env
+chmod 600 secrets.env
 ```
 
+必填项是 `RESTIC_REPOSITORY` 与 `RESTIC_PASSWORD`；S3 兼容后端还需要
+`AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`。可用 `RESTIC_BIN` 覆盖 restic
+位置、用 `BACKUP_AGENT_DIRS` 调整数据源、用 `BACKUP_EXCLUDE_REWIND=1` 排除
+Copilot rewind 快照。通过 `--chatgpt-root` 或 `-o` 放到其它位置的 ChatGPT 快照不会
+自动进入备份，需要显式加入 `BACKUP_AGENT_DIRS`。
+
+新仓库先加载配置并初始化，再运行备份：
+
+```bash
+set -a; source secrets.env; set +a
+restic init
+asmgr backup run --dry-run
+asmgr backup run
+```
+
+`RESTIC_PASSWORD` 是读取所有快照的唯一密钥，初始化后必须保存到密码管理器或另一台设备。
+
+#### 自动运行
+
+`systemd/` 提供 user service 与 timer 示例，每天运行一次，并用随机延迟避免整点拥塞；
+`Persistent=true` 会在机器重新启动后补跑错过的任务。复制示例后按源码 checkout 和日志
+位置调整 service，再启用 timer：
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp systemd/agent-session-manager.service.example ~/.config/systemd/user/agent-session-manager.service
+cp systemd/agent-session-manager.timer.example ~/.config/systemd/user/agent-session-manager.timer
+systemctl --user daemon-reload
+systemctl --user enable --now agent-session-manager.timer
+```
+
+同一个 restic 仓库只应由一台机器负责定时运行。需要在登出后继续执行时，为该用户启用
+systemd lingering。
+
+</details>
+
 ## 从 live 目录之外读取会话
 
-`--file <path>`（别名 `--events <path>`）让 `list` / `search` / `show` / `html` / `md` 读一个显式路径，而不是 `~/.copilot`、`~/.claude`、`~/.codex`：
+`--file <path>`（别名 `--events <path>`）让 `list` / `search` / `show` / `html` / `md` 读一个显式路径，而不是 live agent / import 主目录：
 
 ```bash
 # 从别的机器拷来的单个会话文件（agent 自动探测）
 asmgr show --file ~/dl/events.jsonl --format json
 asmgr html --file ~/dl/events.jsonl -o report.html
+asmgr show --file ~/dl/conversation.chatgpt-share.json --format dialogue
 
-# 整个目录（遍历 *.jsonl；每个文件各自探测 agent）
-asmgr list --file /tmp/restored-cache
-asmgr search "migration" --file /tmp/restored-cache
+# 整个目录（遍历 *.jsonl / *.chatgpt-share.json；每个文件各自探测 agent）
+asmgr list --file /tmp/session-archive
+asmgr search "migration" --file /tmp/session-archive
 ```
 
 `--file` 指向单个文件时，`<session-id>` 参数可省。指向的目录若产出多个会话，传一个 `<session-id>` 挑一个（用 `asmgr list --file <dir>` 看 id）。
@@ -229,21 +365,23 @@ asmgr search "migration" --file /tmp/restored-cache
 ## 术语
 
 - **会话（Session）**：agent CLI 持久化的一次对话，可由 UUID、JSONL 路径，或某 agent 本地数据库中的一行标识。
-- **agent 适配器（Adapter）**：知道如何发现并解析某一家 agent 持久化格式的代码。当前适配 GitHub Copilot CLI、Claude Code、OpenAI Codex CLI。
+- **agent 适配器（Adapter）**：知道如何发现并解析某一家 agent 持久化格式的代码。当前适配 GitHub Copilot CLI、Claude Code、OpenAI Codex CLI 与 ChatGPT 公共分享快照。
 - **事件（Event）**：agent 持久化流里的一条原始记录。Copilot 的事件存在 `events.jsonl`，是离线时间线重建的输入，而非 live `/share html` 直接渲染的对象。
 - **时间线条目（Timeline entry）**：时间线里的一个展示单元（用户消息、助手回复、reasoning 块、工具调用等）。Copilot 把 live 条目放内存里；`asmgr` 从持久化事件重建规范化条目，供搜索与渲染共用。
 - **归档（Archive / 只读检索）**：`asmgr` 只读地取回历史会话——搜索、文本显示、JSON 导出、给人看的 HTML/Markdown。归档**从不**把会话恢复回原 agent 的 live 状态。
 - **恢复（Restore）**：忠实重建**可 `--resume` 的原生会话状态**（规划中）。**归档 ≠ 恢复**：报告不可反推回可续聊的原生态。
-- **归档源（Archive source）**：可读取会话文件的地方——包括 live 本地 agent 目录，以及从 restic 恢复出来的备份缓存。
+- **归档源（Archive source）**：可读取会话文件的地方——包括 live 本地 agent 目录，以及通过 `--file` 显式指定的文件或目录。
 
 ## 设计文档（ADR）
 
 重要决策的理念记录在 [`docs/adr/`](docs/adr/)：
 
-- [ADR 0001](docs/adr/0001-scope-archive-and-restore.md) —— 范围、双面能力与"归档 ≠ 恢复"。
-- [ADR 0002](docs/adr/0002-single-package-asmgr-distribution.md) —— 单一 `asmgr` 包、能力而非产品、分发与发布。
-- [ADR 0003](docs/adr/0003-archive-reconstruction-fidelity.md) —— 归档侧：从 `events.jsonl` 离线重建的保真度模型。
-- [ADR 0004](docs/adr/0004-restore-fidelity-and-safety.md) —— 恢复侧：忠实迁移的保真度与破坏性操作安全。
+- [ADR 0001](docs/adr/0001-scope-archive-and-restore.md) —— 产品范围与"归档 ≠ 恢复"。
+- [ADR 0002](docs/adr/0002-single-package-asmgr-distribution.md) —— 单一 `asmgr` 包与统一命令入口。
+- [ADR 0003](docs/adr/0003-archive-reconstruction-fidelity.md) —— 归档数据的规范化与保真度。
+
+<details>
+<summary>实现参考：Copilot 时间线、目录结构与漂移探针</summary>
 
 ## <a id="timeline-ref"></a>Copilot 时间线与离线映射（参考）
 
@@ -266,110 +404,6 @@ asmgr search "migration" --file /tmp/restored-cache
 
 **置信度**：`getTimelineEntries()` 用法、空会话消息、12 类筛选、`reasoningText` 不对称、上列 live-only 条目——置信度高；compaction 时的文件截断机制置信度较低，需对新版本复验。Copilot 升级后重跑[漂移探针](#drift-oracle)并查 unknown 诊断。
 
-## 备份配置
-
-`asmgr backup`（`backup.sh` 的薄封装）用 [restic](https://restic.net) 对 agent 历史做加密、去重、增量备份。部署相关的值（restic 仓库 URL、凭据、到存储后端的确切网络路径）都放在 `secrets.env`（gitignore、`600`）——不进被跟踪的文件，让仓库里没有内网 IP / 主机名（见下文[「公开前的安全检查」](#safety)）。
-
-### 备份什么
-
-`backup.sh` 读 `BACKUP_AGENT_DIRS`（默认 `~/.copilot:~/.claude:~/.codex`），备份其中存在的 agent 主目录。以 Copilot（`~/.copilot`）为例：
-
-| 路径 | 典型大小 | 是什么 | 是否备份 |
-|---|---|---|---|
-| `session-state/<id>/events.jsonl` | 大（合计 GB 级） | 持久化的每会话事件流——resume 时回放、并被 `asmgr` 映射成离线条目 | ✅ 核心 |
-| `session-state/<id>/{checkpoints,files,research}/` | 中小 | 每会话产物（检查点、附件、research 笔记） | ✅ |
-| `session-store.db` | 数十 MB | 全会话的 SQLite 索引（摘要、turns、文件 / 引用索引、FTS） | ✅ —— 先 checkpoint WAL 保证副本自洽 |
-| `session-store.db-wal` / `-shm` | 小 | SQLite WAL / 共享内存（热文件） | ❌ 排除（`exclude.txt`） |
-| `*.lock`（如 `inuse.<pid>.lock`） | 极小 | 运行时锁文件 | ❌ 排除（`exclude.txt`） |
-| `logs/` | 很大（GB 级） | CLI 进程日志 | ❌ 始终排除（`backup.sh` 里）——量大、恢复价值低 |
-| `session-state/<id>/rewind-snapshots/` | 大（GB 级） | 支撑 `/rewind` 撤销功能的快照 | ⚠️ 可选——`BACKUP_EXCLUDE_REWIND=1` 时排除 |
-| `config.json`、`settings.json`、`mcp-config.json`、`servers/` | 极小 | CLI + MCP 配置 | ✅ |
-
-Claude Code（`~/.claude`）与 Codex（`~/.codex`）主目录存在时整体备份。
-
-**`rewind-snapshots/` 为什么可选**：Copilot 的 `/rewind` 靠 `~/.copilot/session-state/<id>/rewind-snapshots/`（一个 `index.json` 加快照数据）撤销本会话的编辑。设 `BACKUP_EXCLUDE_REWIND=1` 把它们排除——省的空间比任何单项排除都多，且**不影响** `/share html`、`--resume`、`asmgr`（后两者从始终备份的 `events.jsonl` 重建）；唯一失去的是对**恢复出来的**会话执行 `/rewind` 的能力。
-
-### 端到端加密与架构
-
-restic 跑在**客户端**，在数据离开主机前做**端到端 AES-256 加密**，再写入 **S3 兼容端点**（`RESTIC_REPOSITORY=s3:<endpoint>/<bucket>`；任何 restic 后端都行——rustfs / MinIO / SeaweedFS / AWS S3 / B2 / R2 / 本地路径 / sftp / rest）。后端只见密文，存储主机被攻破也不暴露你的历史。
-
-反面：`RESTIC_PASSWORD` 是整个仓库**唯一**的钥匙——丢了它，所有快照永久不可读。`restic init` 后立刻把它抄进密码管理器 / 另一台设备。
-
-到端点可能要过若干网络跳转（如 mesh 覆盖网 → 主机端口代理 → WSL2 端口转发 → 容器端口）；这条跳转链是部署相关、含内网地址的，记在 `secrets.env` 头部注释里而**非**本文件——换机重新部署时只改 `secrets.env`，`backup.sh` / `exclude.txt` / 本文都是通用的。
-
-### 配置与运行
-
-复制模板、填入你自己的后端：
-
-```bash
-cp secrets.env.example secrets.env
-chmod 600 secrets.env
-```
-
-必填变量：
-
-| 变量 | 含义 |
-|---|---|
-| `RESTIC_REPOSITORY` | restic 仓库 URL，例如一个 S3 兼容桶 |
-| `RESTIC_PASSWORD` | restic 仓库的加密口令 |
-| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | S3 凭据，仅 S3 兼容后端需要 |
-
-可选变量：
-
-| 变量 | 默认值 |
-|---|---|
-| `RESTIC_BIN` | `$HOME/.local/bin/restic` |
-| `BACKUP_AGENT_DIRS` | `$HOME/.copilot:$HOME/.claude:$HOME/.codex` |
-| `BACKUP_EXCLUDE_REWIND` | 未设置；设为 `1` 跳过 Copilot rewind 快照 |
-
-首次初始化一个新的 restic 仓库：
-
-```bash
-set -a; source secrets.env; set +a
-restic init
-```
-
-然后运行：
-
-```bash
-asmgr backup run --dry-run
-asmgr backup run
-```
-
-把 `RESTIC_PASSWORD` 存进密码管理器或另一台设备。丢了它，加密备份就再也读不出来。
-
-### 保留策略
-
-每次运行给快照打 `agent-session-manager` + `$(hostname)` 标签，然后：
-
-```
-restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune
-```
-
-> 迁移注记：快照标签历经 `session-recall` → `agent-session-exporter` → `agent-session-manager`。若把新 checkout 指向已有仓库，先对齐标签（如 `restic tag --set agent-session-manager --tag agent-session-exporter`，或加匹配的 `--keep-tag`），让 `forget` 按预期血缘 prune、而非遗弃旧快照。
-
-## 用 systemd 自动备份
-
-示例 unit 文件在 `systemd/`：
-
-```bash
-mkdir -p ~/.config/systemd/user
-cp systemd/agent-session-manager.service.example ~/.config/systemd/user/agent-session-manager.service
-cp systemd/agent-session-manager.timer.example ~/.config/systemd/user/agent-session-manager.timer
-```
-
-编辑 `agent-session-manager.service`，把路径指向你的 checkout，然后：
-
-```bash
-systemctl --user daemon-reload
-systemctl --user enable --now agent-session-manager.timer
-systemctl --user list-timers agent-session-manager.timer
-```
-
-若希望登出后 timer 仍运行，请用你的系统管理员账户开启 user lingering。
-
-> 只应有**一台**机器拥有该 timer。若从旧部署迁来（unit 曾指向别的 checkout、或快照打的是旧标签如 `session-recall`），先禁用并删掉旧 unit（`systemctl --user disable --now <old>.timer` 再删文件），以免跑两份备份或把保留血缘劈成两半。
-
 ## 目录结构
 
 `asmgr` 是**一个** npm 包；下面的 `src/*` 是它的内部模块（相对 import 串联），不是各自发布的包。
@@ -383,7 +417,6 @@ systemctl --user list-timers agent-session-manager.timer
 | `scripts` | esbuild 单文件打包、bun 原生二进制、构建期资源内联（gen-assets） |
 | `fixtures` | 脱敏的解析器与 CLI fixtures |
 | [`tools/copilot`](tools/copilot/) | Copilot `/share` bundle 漂移探针（仅逆向研究，非运行时依赖） |
-| `backup.sh` | `asmgr backup` 用的 restic 封装 |
 
 ### <a id="drift-oracle"></a>漂移探针（`tools/copilot`）
 
@@ -395,9 +428,15 @@ node tools/copilot/extract-share-assets.cjs [path/to/@github/copilot/app.js] [ou
 
 **为什么保留**：它是**漂移探针**。Copilot 升级可能改动时间线条目 / 筛选类、Primer 明暗主题规则、按钮 id 等 DOM 钩子。升级后重跑并 diff 上一次输出，把有意义的变化当作"复核离线事件映射与 React 渲染器"的提示，而不是自动搬进产物。维护中的 HTML 渲染器是 `src/html` 的 React 实现，不 import 也不发布这些抽取资产；仓库里目前没有大小 / 哈希基线，可在下次比较时记录探针打印的长度与本地校验和。
 
+</details>
+
+<details>
+<summary>同类项目调研与差异</summary>
+
 ## 同类项目对比
 
-这个问题空间很拥挤——至少 14 个 OSS 项目瞄准相近方向，其中几个 star 数可观，至少一个出自知名开源作者。设计本工具前我们调研过它们，并在本地 `readonly-repos/<name>/` 各留一份只读镜像备查。
+这个问题空间已有多种 CLI、TUI、Web 与桌面实现。下表是 2026-07-24 整理文档时的调研快照；
+Stars 只反映当时状态，不作为持续更新的排名。
 
 | 仓库 | Stars | 语言 | 形态 | 覆盖 agent | 备注 |
 |---|---:|---|---|---|---|
@@ -428,6 +467,101 @@ node tools/copilot/extract-share-assets.cjs [path/to/@github/copilot/app.js] [ou
 
 这些灵感项都作为 GitHub issue 跟踪（每条写明 `Inspired by …`），见 [issues](https://github.com/TMYTiMidlY/agent-session-manager/issues)：项目层级索引页（`claude-code-log`）、Token / 成本分析视图（`token-dashboard`）、实时 tail 模式（`claude-code-trace` / `tail-claude`）、按项目分组侧栏（`agent-session-viewer` / `codex-history-viewer`）、VS Code 扩展封装（`codex-history-viewer`）、Pages 静态导出 tarball（`claude-code-transcripts`）。
 
+</details>
+
+## <a id="release"></a>维护者：版本与发布
+
+> **推送 `main` 不等于“只同步代码”。** 当前使用 **semantic-release** 自动推导并发布版本，
+> 不是维护者先运行 `cz bump` 再推 tag。发布前必须检查上次发布以来的**全部提交**，不能只看本次提交的类型。
+
+操作规则以 [`release.yml`](.github/workflows/release.yml)（触发条件、测试与权限）和
+[`.releaserc.json`](.releaserc.json)（提交分析、版本写回、构建与发布插件）为准。
+
+### 什么操作会启动发布
+
+| 操作 | 当前行为 |
+|---|---|
+| 向 `main` 推送，或合并 PR 使 `main` 更新 | 自动运行 `release` 工作流：安装依赖 → `pnpm test` → `semantic-release`；没有按文件路径过滤，纯文档推送也会启动 |
+| 在 GitHub Actions 手动运行 `release`，选择 `main` | 运行同一条发布流水线；**不是预演**，也不强制一定产生新版本 |
+| 只在本地 commit、推送非 `main` 分支、仅创建 PR，或单独推 tag | 不触发当前发布工作流；semantic-release 的发布分支也仅配置了 `main` |
+
+**启动工作流 ≠ 一定发版。** 测试通过后，semantic-release 分析上个发布 tag 到本次运行提交之间的
+提交记录；没有符合发布规则的提交时，不生成新版本。有可发布变更且验证、构建等步骤成功时，就会实际发布。
+
+### 提交如何决定版本
+
+当前未自定义 `releaseRules` 或解析器，使用默认 Angular 风格的提交解析（如 `fix(parser): ...`）：
+
+| 提交内容 | 版本变化（以上一版 `0.2.0` 为例） |
+|---|---|
+| `fix: ...`、`perf: ...` | patch → `0.2.1` |
+| `feat: ...` | minor → `0.3.0` |
+| 正文或页脚含 `BREAKING CHANGE: ...` | major → `1.0.0`，不会因仍处于 `0.x` 自动降为 minor |
+| 被解析为 revert 的回退提交 | 默认 patch；在分析区间内成功匹配的原提交与回退会被成对过滤 |
+| 普通 `docs:`、`chore:`、`ci:`、`test:`、`refactor:` 等，不含破坏性变更说明 | 自身不要求发布 |
+
+同一分析区间按**最高级别**决定一个版本，而非每条提交各发一版。破坏性变更请使用明确的
+`BREAKING CHANGE:` 正文或页脚，**不要只写 `feat!:` / `fix!:`**：当前默认解析器不凭标题中的 `!` 识别破坏性变更。
+
+“本次只有 `docs:`”**不保证不发版**：如果此前有尚未发布的 `fix:` / `feat:`，本次运行仍会把它们纳入分析。
+发布的是本次运行所检出的完整源码，不是只打包触发版本升级的那几条提交；CHANGELOG 则按提交规则生成摘要。
+
+### 版本、标签和产物由谁生成
+
+日常维护不要用 `cz bump`、`npm version`、手工改 `package.json` 版本或手工打发布 tag 来推动发版。
+semantic-release 以 Git 发布历史为依据，在 CI 中自动完成：
+
+1. 推导下个版本并生成 release notes，更新 `CHANGELOG.md` 与 `package.json` 的版本。
+2. 构建 Node 单文件 bundle、Linux x64 / macOS Intel / macOS Apple Silicon / Windows x64 四平台二进制及 `SHA256SUMS.txt`。
+3. 将 `package.json` 和 `CHANGELOG.md` 以 `chore(release): X.Y.Z [skip ci]` 提交回 `main`，并创建、推送 `vX.Y.Z` tag。
+4. 发布公开 npm 包 [`asmgr`](https://www.npmjs.com/package/asmgr)，创建 [GitHub Release](https://github.com/TMYTiMidlY/agent-session-manager/releases)，附上 notes、二进制、Node bundle 和校验和。
+
+npm 发布走 OIDC Trusted Publishing（`npmjs` environment），GitHub 操作使用工作流的 `GITHUB_TOKEN`。
+它是直接发布，不是先生成等待人工确认的 npm 暂存版本。
+
+### 只推代码：优先使用非 `main` 分支
+
+不准备发布时，将提交保留在工作分支并只推该分支，例如：
+
+```bash
+# 从当前提交创建工作分支；分支名按需替换
+git switch -c work/my-change
+# 在该分支完成提交后，只推当前分支，不更新 main
+git push -u origin HEAD
+```
+
+合并该分支到 `main` 仍可能发版，合并前需要重新确认发布范围。
+
+如果确实要把代码推到 `main`，但只想跳过**这次 push** 的工作流，可在提交消息中加 `[skip ci]`
+（例如 `fix: handle large sessions [skip ci]`）。注意：
+
+- 它跳过匹配的 `push` / `pull_request` 工作流，**测试也会跳过**；不会取消已启动的运行，也不阻止手动 `workflow_dispatch`。
+- 它不是 semantic-release 的“永不发布此提交”标记。该修复仍在上个 tag 之后，下一次未跳过的 `main` 推送或手动发布仍会分析并可能发布它。
+- 因而它只适合临时跳过一次触发，不能作为长期发布闸门，也不能防止其他维护者后续推送带出该变更。
+
+### 明确批准一次发布
+
+1. 维护者先核对目标 `main` 提交 SHA、上个发布 tag 之后的全部变更与预期版本，确认这些内容都允许公开发布。
+2. 明确批准后，再向 `main` 普通推送 / 合并以启动自动发布；若待发布提交已在 `main`（例如此前用了 `[skip ci]`），
+   可在 GitHub Actions → `release` → **Run workflow** 选择 `main`，或执行：
+
+   ```bash
+   # 真正启动发布，不是 dry-run；只在明确批准后执行
+   gh workflow run release.yml --ref main
+   ```
+
+3. 检查运行结果，以及回写的版本 / CHANGELOG、`vX.Y.Z` tag、npm 版本和 GitHub Release 附件。手动运行没有绕过提交分析；无可发布变更时仍不会发新版本。
+
+**“单独提交”只授权本地 commit，不包含 push 或发布；“只推代码”应使用非 `main` 分支。**
+自动化助手执行可能发版的 `main` 推送 / 合并或手动运行前，必须说明发布影响并取得维护者明确同意。
+
+当前工作流没有 `publish=true` 一类的二次确认输入；`environment: npmjs` 本身也**不代表已有人工审批**，
+是否等待审批取决于仓库 Settings → Environments → `npmjs` 的保护规则。若需要每次都强制人工批准，
+应在那里配置 required reviewers（以仓库支持情况为准），或另行修改工作流为仅手动发布；这些都需要单独配置，不能靠 `[skip ci]` 实现。
+
+<details>
+<summary>维护者：公开前安全检查</summary>
+
 ## <a id="safety"></a>公开前的安全检查
 
 把本仓库推到任何公开位置前，只检查被跟踪的文件：
@@ -437,13 +571,15 @@ git ls-files
 git grep -nE 'PRIVATE|SECRET|TOKEN|PASSWORD|AKIA|/(h[o]me|Users)/|10\\.|192\\.168\\.|172\\.|D[E]SKTOP|[Ww]orkstation'
 ```
 
-`secrets.env`、`backup.log`、`node_modules/`、构建产物都被忽略，应保持未跟踪。
+`secrets.env`、`backup.log`、`node_modules/` 与构建产物都被忽略，应保持未跟踪。
+
+</details>
 
 ## <a id="roadmap"></a>路线图
 
 待办与灵感项都在 [GitHub issues](https://github.com/TMYTiMidlY/agent-session-manager/issues) 跟踪。两条值得单独点名的方向：
 
-- **忠实恢复 / 迁移**：把会话恢复到"另一台机器能 `--resume`"的原生状态（来源 = 备份快照 ∪ 另一台机器）——理念见 [ADR 0001](docs/adr/0001-scope-archive-and-restore.md) 与 [ADR 0004](docs/adr/0004-restore-fidelity-and-safety.md)。
-- **本地 Web 界面 `asmgr web`**：本机启动、仅供自己查看、默认只绑 `127.0.0.1` 的会话浏览界面，随同一个包分发——见 [ADR 0002](docs/adr/0002-single-package-asmgr-distribution.md)。
+- **忠实恢复 / 迁移**：把会话恢复到"另一台机器能 `--resume`"的原生状态（来源 = 备份快照 ∪ 另一台机器）——边界见 [ADR 0001](docs/adr/0001-scope-archive-and-restore.md)。
+- **本地 Web 界面 `asmgr web`**：本机启动、仅供自己查看的会话浏览界面。
 
-单文件分发与 npm 发布**已实现**（单一无 scope 包 `asmgr`、四平台原生二进制、semantic-release、`npm i -g github:` 免 registry 安装）——详见[安装](#install)。其余（持久化索引搜索恢复出来的备份、提升适配器保真度、项目层级索引页、Token / 成本视图、实时 tail、VS Code 扩展、Pages 导出 tarball、跨多会话仪表盘）见 issues。
+单文件分发与 npm 发布**已实现**（单一无 scope 包 `asmgr`、四平台原生二进制、semantic-release、`npm i -g github:` 免 registry 安装）——使用方式见[安装](#install)，发布规则见[维护者：版本与发布](#release)。其余（持久化索引外部会话目录、提升适配器保真度、项目层级索引页、Token / 成本视图、实时 tail、VS Code 扩展、Pages 导出 tarball、跨多会话仪表盘）见 issues。