# pilot-harness

> 为 DSH Web 端提供 `/export` 斜杠命令和会话页头按钮，把当前 Session 打成包含子会话与附件的 ZIP 文件下载到本地。

## Metadata

- Author: [@op7418](https://github.com/op7418)
- Repo: <https://github.com/op7418/pilot-harness.git>
- GitHub: [op7418/pilot-harness](https://github.com/op7418/pilot-harness)
- Stars: 240
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `ai-agent`, `codepilot`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `linux`, `macos`, `typescript`, `windows`
- Forks: 13
- Open Issues: 16
- Last push: 2026-08-20T12:42:53.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/session-query/session-log-export
```

## Wiki

## 一句话定位
为 DSH Web 端提供一键下载 Session 日志的能力：在会话页头增加"导出日志"按钮，并在对话中识别 `/export` 斜杠命令，触发浏览器下载一个包含当前 Session、子 Session 和附件的 ZIP 文件。

## 核心能力
- 注册 `/export` 斜杠命令，将用户的下载意图路由到浏览器侧的下载控制器
- 在 Session 页头工具栏渲染一个 111×32 的"导出日志"按钮，与斜杠命令共用同一个下载流程
- 自动执行 HEAD 预检，确认 Host 端 `/api/session.export` 可用后再交由浏览器下载管理器接管，避免下载半途中断
- 通过统一弹窗展示"准备中 / 下载已开始 / 失败"三种状态
- 每个 Session 同时只允许一项下载，重复点击会复用同一笔进行中的下载操作
- 插件卸载（dispose）时会取消所有未完成的预检请求

## 技术实现
- **语言**: TypeScript（含 React 18 浏览器端组件）
- **关键依赖**: `@deepseek-ai/dsh-commands`（注册 `/export` 斜杠命令）、`@deepseek-ai/dsh-client-ui-trajectory`（工具栏槽位）、`@deepseek-ai/dsh-client-runtime`（会话快照存储）、`@deepseek-ai/dsh-client-ui-primitives`（按钮、图标、弹窗）
- **架构模式**: 双面插件——Host 面注册 `/export` 命令并触发 `command/executed` 事件；Browser 面订阅该事件并驱动下载控制器；实际 ZIP 生成由宿主侧的 `dsh-host-apiproxy` 拥有
- **入口文件**: `src/index.ts`（Host 面命令注册）、`src/client/index.ts`（Browser 面下载控制器与槽位注入）

## 适用场景
适合需要把 AI 助手某次完整对话（含子任务、附件、命令历史）打包分享给同事、归档留底，或上传到工单系统的用户。点击导出即可获得一个完整可解包的 ZIP，无需逐条复制对话内容。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.1.0-rc.7 | 仅支持 Web bundle；需同时安装 `dsh-host-apiproxy`（提供 ZIP 端点）、`dsh-commands`、`dsh-client-ui-commands`、`dsh-client-ui-trajectory` |
| Node.js | >=22.19.0 | 沿用宿主根包 `package.json` 中 `engines.node` 的版本要求 |
| 平台 | 跨平台 | 浏览器侧运行，无原生模块，依赖宿主后端的持久化后端 |

## 安装方式
```bash
dsh plugin --profile web add github:op7418/pilot-harness/packages/session-query/session-log-export
```

## 配置项
本插件无需额外配置。安装到 Web profile 后，重启 profile 即可在 Session 页头看到"导出日志"按钮，并在对话中识别 `/export` 命令。

## 常见问题

**Q: 怎么下载某个 Session 的日志？**

A: 在浏览器界面的 Session 页头右侧点击"导出日志"按钮，或在对话中输入 `/export` 并发送，都会触发浏览器下载一个 ZIP 文件。

**Q: ZIP 包里包含哪些内容？**

A: 包含当前 Session、所有子 Session 以及附件。ZIP 的生成、流式读取、错误处理均由后端的 `dsh-host-apiproxy` 完成，本插件只负责发起下载。

**Q: 一个 Session 可以同时下载多次吗？**

A: 不行。每个 Session 同时只允许一项下载，重复点击按钮或重复发送 `/export` 会复用同一笔进行中的下载操作，不会启动新的下载。

**Q: 支持 SQLite 后端的 Session 导出吗？**

A: 当前不支持。下载端点要求持久化后端提供按 Session 的原始工件；随附的 JSONL 后端支持明文和 zstd 工件，SQLite 导出不在本次范围内。

**Q: 下载失败时会怎样？**

A: 下载开始前（HEAD 预检）发现的失败由插件自带弹窗报告并显示错误信息；浏览器已接收下载请求后发生的失败则由浏览器自身的下载管理器提示，不会再弹本插件的弹窗。

**Q: 关闭弹窗会取消正在进行的下载吗？**

A: 不会。关闭弹窗只是关闭 UI，不会取消浏览器正在进行的下载，该操作完成后也不会重新弹出弹窗。

**Q: 怎么卸载？**

A: 运行 `dsh plugin --profile web remove @deepseek-ai/dsh-session-log-export`，然后重启 Web profile 即可。

## 上手难度
入门 — 安装即用，无需任何额外配置；界面增加一个按钮 + 一个斜杠命令，浏览器侧完成所有交互逻辑。

## 已知问题与限制
- 仅 Web bundle 可用，不影响 CLI、ACP 等其他 profile。
- 依赖持久化后端能提供按 Session 的原始工件；SQLite 后端的导出当前未实现。
- 下载目标是浏览器本地，目标路径由浏览器决定，无法指定 Host 端路径或调用原生文件夹选择器。
- HEAD 预检只报告 ZIP 流式开始前的错误；浏览器接收下载后，子 Session 或附件的读取失败由浏览器下载管理器提示，不会通过本插件的弹窗展示。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [pilot-harness](https://deepseek-plugin.org/plugins/op7418/pilot-harness/packages/session-query/session-log-export)
Wiki generated by AI (model: `MiniMax-M3`)