paper-plane-x-dsh

Readme

# Paper Plane X × DeepSeek Harness 插件

将 Paper Plane X（ppx）的研究上下文接入 DeepSeek Harness Web 控制台：

1. **上下文面板（`/ppx-context`）**：通过 `ppx` CLI 查看/管理当前 context（`base_url`、`project_id`，读写同一份 CLI context 文件），并提供跳转到 ppx 前端项目页（`/projects/{projectId}`）的新标签页链接。
2. **论文检索（`/ppx-paper`）**：输入 `/ppx-paper` 在输入框上方打开检索面板，面板内输入关键词（支持空格）或 paper_id 复用 ppx Librarian 搜索（`simple_query` / `paper_id`）选择并引用。选中后仅把 `paper_id` 写入输入框（不注入冗余提醒，避免污染上下文）。

这是一个 DeepSeek Harness **bundle** 插件（`dsh.bundle` + `dsh.client`），浏览器半走 `exports["./client"]`，React 实现。

![Context](./docs/assets/screenshots/context.png)

![Paper](./docs/assets/screenshots/paper.png)

## 安装与运行

要求：Node 22+、pnpm、以及一个可运行的 DeepSeek Harness 环境（`dsh` CLI）。

### 1. 构建插件

```bash
cd paper_plane_x_dsh
pnpm install && pnpm build   # 产出 lib/index.js 与 lib/client.js
```

### 2. 装入 Web profile

DSH 的 Web 界面由内置 **`web` profile**（`@deepseek-ai/dsh-base` + `@deepseek-ai/dsh-web-app`）承载，插件必须装进它才会随 Web 一起加载：

```bash
# 本地路径安装（首次会自动初始化 web profile）
dsh plugin --profile web add /path/to/paper_plane_x_dsh

# 或从 Git 安装（SSH / HTTPS 二选一；prepare 会自构建；
# pnpm ≥10 需在 profile 的 pnpm-workspace.yaml 里 allowBuilds）
dsh plugin --profile web add github:WindLX/paper_plane_x_dsh                          # SSH
dsh plugin --profile web add git+https://github.com/WindLX/paper_plane_x_dsh.git      # HTTPS
```

### 3. 启动 Web

```bash
dsh web            # 等价于 dsh --profile web
```

打开 `http://127.0.0.1:3080`。可先 `dsh --profile web --dump-config` 确认 `paper-plane-x-dsh`（行 id 为 `ppx`）已进入 composition。

> `@deepseek-ai/dsh-client-*` 与 `react` **不随插件安装**：它们由 DSH Web shell 的模块表在运行时提供（client bundle 已将其 external）。`pnpm install` 只装构建工具与类型，因此可在插件目录内独立 `pnpm install && pnpm build && pnpm test`。

### 配置存储位置

- **DSH profile 配置**：`~/.dsh/profiles/<name>/`（`package.json` 的 `dsh.profile.bundles` + `cordis.patch.yml`）；根目录可用 `$DSH_HOME` 覆盖。
- **ppx context**：由 `ppx` CLI 统一管理（`ppx context show` / `ppx context set`），插件通过宿主侧的 `/ppx/*` 接口读写同一份 context 文件，保证与 CLI 一致。全局在 `~/.config/paper-plane-x/context.json`，本地在 `./.paper-plane-x/context.json`（相对 DSH 进程 cwd），环境变量 `PPX_BASE_URL` / `PPX_PROJECT_ID` 优先。

## 卸载

```bash
# 从 web profile 移除插件（pnpm 卸载依赖，并自动从 dsh.profile.bundles 层移除）
dsh plugin --profile web remove paper-plane-x-dsh
```

如需连整个 profile 一起删除（连同自动初始化的 `dsh-base`/`dsh-web-app` 清单）：

```bash
rm -rf ~/.dsh/profiles/web
```

> `dsh web` 每次启动都会重读 profile，所以卸载后**重启 `dsh web`** 即不再加载插件。

## 配置（ppx context）

context 由 `ppx` CLI 统一管理，插件不自己存配置。面板打开时读 `ppx context show` 的 resolved 结果，保存时调 `ppx context set`（可勾选写入全局）。

| 字段        | 说明                                                               |
| ----------- | ------------------------------------------------------------------ |
| `baseUrl`   | ppx 后端 API 地址（默认 `http://127.0.0.1:8000/api/v1`）           |
| `projectId` | 当前项目 ID（可选，留空清除）                                      |
| 项目页链接  | 由 `baseUrl` 去掉 `/api/v1` 推导前端地址 + `/projects/{projectId}` |

> 前置条件：用户需已安装 `paper-plane-x-cli`（`ppx` 在 PATH 中）；否则面板会提示未找到 CLI。

## 使用

在 DSH Web 输入框里：

| 命令           | 作用                                                                   |
| -------------- | ---------------------------------------------------------------------- |
| `/ppx-context` | 在输入框上方打开上下文面板（查看/修改 baseUrl、projectId，跳转项目页） |
| `/ppx-paper`   | 在输入框上方打开论文检索面板，面板内输入关键词（支持空格）检索并引用   |

两个命令都会在输入 `/` 时出现在命令菜单里（前缀匹配）；选中后命令 token 从草稿移除，面板浮在输入框上方。检索在面板自己的输入框里进行，因此多词查询（含空格）正常。

## 开发命令

```bash
just setup      # pnpm install
just build      # pnpm build（tsdown 产出 lib/）
just test       # pnpm test（vitest）
just pre-commit # test + build
```

## 结构

```
src/index.ts                # node 半：/ppx/* 路由（ppx CLI + 后端检索）
src/shared/types.ts         # /ppx/* 接口的共享类型
src/client/index.ts         # 浏览器半：注册 /ppx-paper、/ppx-context + 面板 + locale
src/client/ppx-paper-source.ts # /ppx-paper 命令源（打开检索面板）
src/client/ppx-context-source.ts # /ppx-context 命令源（打开上下文面板）
src/client/ppx-panel.tsx    # 组合面板（上下文表单 + 论文检索，ui-primitives + DSH token）
src/client/panel-store.ts   # 面板开/关 + 模式状态
src/client/locales.ts       # ppx 命名空间 zh/en 字典
src/client/ppx/api.ts       # /ppx/* 的浏览器 fetch 封装
tsdown.config.ts            # 复刻 DSH client bundle 契约（__ModuleLoader__ 工厂）
cordis.patch.yml            # bundle patch：insert 插件行
```

## License

AGPL-3.0-or-later，与 Paper Plane X 主仓库一致。