asmgr 0.2.0 → 0.4.0

package/README.md

@@ -5,11 +5,11 @@
 ![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 会话与公开 ChatGPT 分享导出成 Markdown 或单文件 HTML。** `asmgr`（Agent Session ManaGeR）读取 GitHub Copilot CLI、Claude Code、OpenAI Codex CLI 写在本地的会话历史，也可捕获公开 ChatGPT `/share/` 页面，再把选定的会话导出成自包含报告；来源无法完整保留的内容会显式标记。它是**一个**无 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`。传本地 session id 或 `--file` 时，`list` / `search` / `show` / `html` / `md` 都严格本地。只有显式导入或直接读取 ChatGPT 分享 URL，以及按配置访问 restic 仓库的 `backup` 命令会联网。
+它对 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)。
 
@@ -37,15 +37,33 @@ HTML 产物高度复刻 Copilot CLI 内置 `/share html` 的排版（Primer 主
 - **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` / `*.chatgpt-share.json` 文件——或一个会被遍历出这些文件的目录——而不是 live agent 主目录。每个文件的 agent 格式自动探测（用 `--agent` 覆盖）。未知 JSON 会明确报错，不再静默显示成空会话。
+每个读命令（`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` 的原始追加消息筛选。v4 存档复用官方 `dsh-session-format-v3-to-v4` 所依赖的 released v2 物理帧解码，再按 v4 词汇表（一等 tool-role 结果、`compact-checkpoint` 等生产者自有 source kind）投影；不升级已锁定的官方依赖。迁移在内存中进行，不依赖本机 DSH 安装、不启动插件、不改写源日志。主干包含直接用户输入、助手正文，以及原生或 PTC 调用中 `ask_user_question` 的题目、全部选项与匹配的回答；普通工具的参数和结果完全不显示。回答按官方格式记录，不额外推断回答者身份。
+
+范围保持有限：不解释未知插件事件、注入上下文、失败模型尝试或任意 `meta`；不把压缩 replacement 当成新对话，不重复拼接 fork 的父会话。只显示官方 compact checkpoint 对应的摘要。图片/文件只显示占位符并提示损失；完整工具仍在 text/HTML/Markdown 中保留。HTML/Markdown 暂无独立的主干导出开关。
+
+压缩日志需要运行时提供 Zstandard API（Node.js ≥ 22.15）；运行时缺少帧解码能力时明确报错，不把未读取内容当空会话。未知版本（含比已支持最高代 v4 更新的存档）、官方迁移器拒绝的旧日志、损坏或未写完的文件会报出路径与原因，不尝试自定义补救，也不会自动回退到旧一代文件。已知官方边界包括 v0 中的 `subagent/descriptor.version: 2`：最新迁移器明确拒绝它；不能仅把该字段改成 3 来冒充兼容。
 
 ## <a id="install"></a>安装
 
-`asmgr` 已发布为单一、无 scope 的公开 npm 包：
+`asmgr` 已发布为单一、无 scope 的公开 npm 包。以下是安装已发布版本的方法；维护者推送代码前请先看[版本与发布](#release)，**普通推送 `main` 可能自动发版**。
 
 ### npm
 
@@ -215,7 +233,7 @@ 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`
 
@@ -451,6 +469,96 @@ Stars 只反映当时状态，不作为持续更新的排名。
 
 </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>
 
@@ -474,4 +582,4 @@ git grep -nE 'PRIVATE|SECRET|TOKEN|PASSWORD|AKIA|/(h[o]me|Users)/|10\\.|192\\.16
 - **忠实恢复 / 迁移**：把会话恢复到"另一台机器能 `--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。