dsh-archive-manager

dsh-archive-manager

---

📑 目录

• 📸 界面预览
• ✨ 功能特性
• 🚀 快速开始
• 📖 使用说明
• 🔧 工作原理
• ⚠️ 技术说明与限制
• ⚙️ 配置说明
• 🤝 贡献
• 📄 许可证

---

📸 界面预览

工作区分组列表 + 筛选/排序工具条

---

✨ 功能特性

---

🚀 快速开始

前提条件

• 已安装 DSH CLI 与 pnpm（dsh plugin 内部转发到 pnpm）

安装

# 方式一：从本地源码安装（开发）
dsh plugin --profile web add dsh-archive-manager@link:<absolute-path-to-plugin>

# 方式二：从 GitHub 安装
dsh plugin --profile web add github:Ycet/dsh-archive-manager

包声明了 dsh.bundle 补丁层，dsh plugin 会自动把加载项合入 profile 的 bundle 层，无需手动编辑 cordis.patch.yml。

启动

1. 重启网页应用：dsh web
2. 打开 http://127.0.0.1:3080 并刷新页面
3. 点击左侧边栏底部的设置，选择归档页面

[!NOTE] 安装为 file: 快照（拷贝）时，修改源码后需重新执行安装命令同步 profile 内的快照，再重启 DSH web 生效（bundle 层变更必须重启 DSH，不热加载）。

---

📖 使用说明

1. 点击左侧边栏底部的 设置；
2. 在设置窗口左侧选择 归档 页面；
3. 页面上方工具条：
   • 筛选下拉：默认「全部工作区」，可选某个具体工作区或「未分组」；菜单只列出至少有一个已归档会话的工作区（某工作区没有任何归档会话时不出现在菜单中），仅当存在未分组归档会话时才出现「未分组」选项；
   • 排序下拉：按名称或创建时间升/降序；
   • 删除全部按钮：删除当前筛选下全部已归档会话（需二次确认）；
4. 会话按工作区分组展示，每组含会话标题与创建时间：
   • 取消归档：会话恢复到左侧边栏对应工作区分组，可点击打开；
   • 删除：二次确认后彻底删除该会话。

---

🔧 工作原理

归档在 DSH 中的底层存储

DSH 的会话归档状态持久化在 ~/.dsh/storages/workspace.json（workspace 领域）：

{
  "global": {
    "initialized": true,
    "workspaceIds": ["..."],
    "archivedSessionIds": ["session-xxx", "..."],
  },
  "tables": {
    "workspaces": {
      "<workspaceId>": {
        "path": "/abs/path",
        "title": "工作区名",
        "sessionIds": ["..."],
        "createdAt": "...",
        "updatedAt": "..."
      }
    }
  }
}

archivedSessionIds 是全局归档集合。归档只把会话从各分区视图隐藏，不删除日志、不改变工作区记账，因此取消归档后可恢复到原工作区位置。

数据流

flowchart LR
    subgraph Browser
        A["设置 → 归档页 settings.section"] -->|"fetch 同源 JSON"| R
        A -->|"React UI: 分组/筛选/排序/确认弹窗"| A
        R["Host webServer 路由"] --> A
    end

    subgraph Host
        R -->|"/api/archive-manager/list"| H1["读 workspace 领域 + 会话 header/标题"]
        R -->|"/api/archive-manager/unarchive"| H2["从 archivedSessionIds 移除"]
        R -->|"/api/archive-manager/delete"| H3["移除归档+记账, 删日志目录"]
        R -->|"/api/archive-manager/delete-all"| H4["逐个删除全部归档"]
    end

    H1 --> WS["storageDomain.get('workspace')"]
    H1 --> SP["sessionPersistence / sessionQuery"]
    H2 --> WS
    H3 --> WS
    H3 --> FL["等待 sessionPersistence.flush 排空持久化"]
    FL --> FS["fs.rm 删除会话日志目录"]
    H4 --> H3

主机端写入 workspace 领域 global 后，DSH 启动时会校验领域状态（fail-loud）。写入严格保持 workspace.json 的 schema 结构不变（数组整体替换后写回），不会破坏 DSH 启动。

---

⚠️ 技术说明与限制

• 无官方 unarchive / 删除会话 API：DSH 主机端 workspaceRegistry 只暴露 archiveSession，没有 unarchiveSession，也没「删除会话」接口。本插件直接读写 storageDomain.get('workspace') 领域存储（~/.dsh/storages/workspace.json），严格保持其 schema。
• 删除为彻底删除：删除会话会删掉 ~/.dsh/sessions/<项目目录>/<sessionId>/ 下的日志文件，不可恢复。DSH 的 SQLite 搜索索引会在下一次 reconciliation 自动清理该会话。
• 删除先删文件、后清记录：删除时先定位会话日志目录，确认日志文件删除成功后才移除归档标记与工作区记账；若日志删除失败（无法定位、仍存在、IO 错误），返回错误且不改动归档状态——会话保持隐藏，不会「复活」到侧边栏。
• 持久化快照兼容与删除复核：DSH 0.1.5-rc.1 的 sessionPersistence.list() 返回 { header, revision }，不是裸 header。此前直接读取条目的 id / cwd，导致找不到真实会话；路径兜底也失败时，误判日志不存在并清除归档标记，使仍在磁盘的会话重新显示。现在统一解包快照（兼容旧版裸 header），优先用实际 header 调用 locate()，支持自定义存储根目录与合法的 _no-cwd 路径；删除后通过可用的 stat(id) 复核。列表读取失败、格式不兼容、仍能查到会话或无法定位已列出的会话时，均保留归档标记并报错。
• live 持久化排空防护：保留摘除空闲 live 会话后 await sessionPersistence.flush() 的防护；缺少该能力或调用失败时拒绝清除归档标记。该屏障排空当前活跃的 write handles，但上一轮将异步写回认定为本问题根因的结论未经真实后端复现；本轮实际复现并修复的是快照结构解析错误。
• 运行中即时生效：写入 global 会触发 domain/changed，DSH 会向浏览器推送 host/archived-sessions-changed，侧边栏与归档页即时刷新。
• 内存缓存一致性（已修复）：DSH 的 WorkspaceRegistry 是单一写入者，其 archivedSessionIds getter 直接读内存 state。本插件改写存储时会同步更新 registry.state.archivedSessionIds，并用官方 WorkspaceEntity.detachSession 移除工作区记账（同时更新 entity.record 缓存）；因此取消归档后再归档、硬刷新重建基线都不会出现会话消失/不显示的问题。
• 仅支持归档会话：删除/取消归档前会校验该会话确实存在于 archivedSessionIds，对未归档会话不会操作。
• live 会话处理（已修复）：agent 结束后的会话仍会作为 live Session 留在 DSH 内存（ctx.sessions），仅删文件不会让前端移除它（session.list 的 live 部分仍返回，侧边栏显示「复活」）。删除时若会话是 live：仅当 agent 真正运行中（agent.status === "running"）才拒绝删除；空闲 live（agent idle 或没有 agent）→ 先调用 sessions.detachEntered 将其从内存移除（触发 session/disposed → DSH 推送 api-session/removed → 前端侧边栏立即移除，agent-loop 也会自动清理关联的 idle agent），再等待持久化排空屏障，之后才删文件与清记录（避免 DSH 的异步最终 drain 把日志写回磁盘）。
  • 注意：前端收到 api-session/removed 时，若该行 origin === "subagent" 或被 address 保留，DSH 会把「删除行」降级为「running=false」而不移除该行；此类会话请以硬刷新后的结果为准。

[!WARNING] 「删除」与「删除全部」均为彻底删除：会话日志文件、归档标记与工作区记账会被一并移除，不可恢复。

---

⚙️ 配置说明

本插件无需任何环境变量或配置文件，开箱即用。它不新增 DSH 公共 RPC、不挂载新 Service，仅注册 4 条包内同源 HTTP 路由：

---

🤝 贡献

欢迎提交 Issue 与 Pull Request：发现问题请携带 DSH 版本、插件版本、复现步骤与日志到 Issues 反馈；改进请按 Fork → 分支 → PR 流程提交（主机端修改 index.js，浏览器端修改 client.js）。

---

📄 许可证

本项目使用 MIT 许可证。