# 安装

目标环境是 DSH Desktop `0.2.0-rc.2`（宿主 tag `dsh-v0.2.0-rc.2`）。插件以预构建产物交付，不需要在你机器上跑 TypeScript 构建链。

下面用 `$DSH_HOME` 表示 DSH 的主目录：Windows 默认 `C:\Users\<你>\.dsh`，macOS/Linux 默认 `~/.dsh`。

## 1. 拿到包

**方式一（推荐）：下载 Release 里的 tarball**

从 [Releases](https://github.com/sumingwang233/dsh-question-bridge/releases) 下载 `dsh-question-bridge.tgz`（资产名不带版本号，方便一直指向最新版），放到 `$DSH_HOME/plugins/packages/`。

**方式二：从源码打包**

仓库里没有 `node_modules`，也不需要装依赖——打包脚本只用 Node 内置模块和系统自带 `tar`：

```powershell
git clone https://github.com/sumingwang233/dsh-question-bridge.git
cd dsh-question-bridge
node scripts/pack.mjs --out "$env:USERPROFILE\.dsh\plugins\packages\dsh-question-bridge.tgz"
```

```bash
git clone https://github.com/sumingwang233/dsh-question-bridge.git
cd dsh-question-bridge
node scripts/pack.mjs --out ~/.dsh/plugins/packages/dsh-question-bridge.tgz
```

（Windows 上 `npm pack` 会因为缓存目录 EPERM 失败，所以脚本绕开 npm，直接按 `package/…` 结构打 tar.gz，和 `npm pack` 的产物同构。）

## 2. 加进 profile

编辑 `$DSH_HOME/profiles/desktop/package.json`，两处。

`dependencies` 里加一条（路径按你的实际情况写，Windows 用正斜杠）：

```json
"dsh-question-bridge": "file:C:/Users/<你>/.dsh/plugins/packages/dsh-question-bridge.tgz"
```

`dsh.profile.bundles` 数组末尾加：

```json
"dsh-question-bridge"
```

`bundles` 是 DSH 装配 profile 的入口列表：每个 bundle 先铺一层，然后才叠加 `cordis.patch.yml`。插件必须同时出现在依赖和 bundles 里——只加依赖不会加载它。

## 3. 安装依赖并重启

```bash
cd "$DSH_HOME/profiles/desktop"
pnpm install
```

然后完全退出 DSH（Windows 托盘图标里也要退出），重新启动。刷新网页不够：宿主端插件只在宿主进程启动时装配。

如果你习惯用 DSH 自带的插件管理入口，等价操作是安装这个本地 tarball，效果相同。

## 4. 验证

1. 打开 DSH，右下角应该出现一个不显眼的"待回答"圆钮（`shell.overlay` 槽位）。没有批次时只有图标和数字 0。
2. 让 Agent 调用 `ask_interactive_question`（比如："问我今晚先做哪个任务，给两个选项"）。工具应该立刻返回 `pending`，对话继续，而不是卡在工具里。
3. 原生问题卡片弹出，或者待答面板里出现这个批次。回答之后，会话里多一条 `kind: "answer_to_question_bridge"` 的用户消息，Agent 接着往下走。
4. 宿主端自检：浏览器开发者工具执行 `fetch('/plugins/question-bridge/state').then(r => r.json())`，应返回 `{schemaVersion: 1, sessions: [...]}`。返回 404 说明插件没进宿主进程，那是装配问题，不是 UI 问题；返回 401 说明插件在，只是当前页面没有通过浏览器鉴权。

## 配置

字段可以写在 profile 的插件配置里，也可以写在 `cordis.patch.yml` 的 id 定向条目里：

```yaml
- id: dsh-question-bridge
  config:
    classifier: model
    maxOpenBatchesPerSession: 3
    notifyOnlyWhenHidden: true
```

完整字段见 README 的配置表。默认 `classifier: "off"`——只跑规则，不花模型额度。

## 禁用 / 卸载

- 临时禁用：配置 `enabled: false`，重启。
- 卸载：从 `dsh.profile.bundles` 删掉那一行，从 `dependencies` 删掉依赖，`pnpm install`，重启。
- 数据：`$DSH_HOME/question-bridge/`。里面只有批次状态和额度计数，没有别的会话内容；确认没有待答问题后整个目录可以删。

## 回滚

改动 profile 前先备份 `package.json` 和 `cordis.patch.yml`。回滚时把备份覆盖回去、`pnpm install`、重启即可：插件没有写 profile 之外的状态。

## 常见问题

| 现象 | 大概原因 |
| --- | --- |
| 面板不出现，`/plugins/question-bridge/state` 404 | 插件没进宿主进程：检查 `dsh.profile.bundles`、`pnpm install` 是否真的装了、是否重启了宿主 |
| 面板出现但一直是 0 | 没有 open 批次；确认 Agent 真的调了工具，而不是用文字描述"我要问你" |
| 工具报 `delegated agent cannot ask` | 子 agent 直接调用了工具，这是刻意拒绝的；问题要由 root agent 发起 |
| 原生卡片没弹，只有面板 | 宿主原生问题卡片可能正被别的交互占用（比如 plan review），插件不会抢；面板里照样能答 |
| 系统通知按钮点了没反应 | 浏览器/Electron 通知权限被拒或被系统策略关掉，面板交互不受影响 |