# 桌面版 DSH（DSH NEXT.app）接入说明与排障

> 适用：直接在 macOS 桌面应用里使用 `dsh-qq-farm`。
> 与命令行 `npx @deepseek-ai/dsh web` 是**两套并行的宿主**，profile、端口、环境变量都不同。

---

## 0. 三个最容易踩的坑（都实测踩过）

| # | 现象 | 根因 | 修法 |
|---|---|---|---|
| 1 | 插件装了但"完全没效果" | 桌面版用 **`desktop` profile**，命令行走 **`web` profile**，装错地方等于没装 | 装到 `desktop`：`dsh plugin --profile desktop add link:<包路径>` |
| 2 | 界面有胶囊但一直「离线」，日志刷 `ModuleNotFoundError: No module named 'PIL'` | 桌面版宿主的 `PATH` 只有 `/usr/bin:/bin:/usr/sbin:/sbin`，`python3` = `/usr/bin/python3`，**没有任何第三方包** | Agent 侧**不依赖 Pillow**：转码改用系统自带 `/usr/bin/sips` |
| 3 | 日志报 `TypeError: inject is not a function` + `slot entry crashed in 'shell.overlay'` | `slots.register({...})` 的 `inject` 必须是**工厂函数**，传对象会在渲染时炸 | `inject: function () { return api }` |

第 4 个（额外的）：**两个宿主同时跑会抢 Agent 端口**（4571），后启动的那个会
`OSError: [Errno 48] Address already in use` 并陷入重启循环。同一时间只应该有一个 DSH 宿主。

---

## 1. profile 怎么确认

```bash
# 桌面版运行时的 profile 名会出现在宿主进程参数里
ps -o command= -p $(pgrep -f "app.asar/lib" | head -1) | tr ' ' '\n' | grep profiles

ls ~/.dsh/profiles/            # 常见：desktop / web
cat ~/.dsh/profiles/desktop/package.json    # dsh.profile.bundles 里应有 dsh-qq-farm
```

插件官方安装方式（两种 profile 通用）：

```bash
dsh plugin --profile desktop add link:/path/to/dsh-qq-farm
# 桌面版没有 PATH 里的 dsh 时：
npx @deepseek-ai/dsh plugin --profile desktop add link:/path/to/dsh-qq-farm
```

## 2. 为什么 `curl /plugins/...` 返回 403

桌面版对普通浏览器请求做了硬拦截：

```js
function decideDesktopBrowserAccess(access, request) {
  if (sameToken(exactHeaderValue(request.headers), access.rendererHeader.value)) return "renderer";
  if (!access.ordinaryBrowserEnabled || desktopBrowserUrlHasRendererDomarkers(request.url)) return "denied";
  return "browser";
}
```

- **渲染器**（App 自己的 WebView）带一个私有 header → 放行；
- **普通浏览器/curl** → `ordinaryBrowserEnabled` 为 false 时一律 403 `Browser access is disabled`。

所以：**在桌面版里不能用 curl 验证插件路由**。要验证就直接看界面，或者直连 Agent：

```bash
curl -s http://127.0.0.1:4571/v1/health      # Agent 端口不受这个栅栏影响
```

## 3. 日志在哪看

```bash
tail -f ~/.dsh/logs/desktop-next.log | grep -iE "qq-farm|renderer"
```

关键行含义：

| 日志 | 含义 |
|---|---|
| `routes mounted at /plugins/dsh-qq-farm/*` | 宿主半加载成功 |
| `supervisor: spawn python3 ... macagent.py` | 正在拉起 Agent |
| `[agent/out] ... FAP v1 listening on http://127.0.0.1:4571/` | Agent 就绪 ✅ |
| `[agent/err] ModuleNotFoundError` | Agent 环境缺依赖（见坑 2） |
| `OSError: [Errno 48] Address already in use` | 端口被另一个宿主占用（见坑 4） |
| `[renderer] TypeError: inject is not a function` | 客户端注册写法错（见坑 3） |
| `[renderer] slot entry crashed in 'shell.overlay'` | 面板组件崩溃，界面不会出现胶囊 |

## 4. 改了代码什么时候生效

| 改的是 | 生效方式 |
|---|---|
| `lib/client.js`（浏览器半） | **自动 HMR**：宿主会轮询 bundle 哈希，几秒后热重载，无需重启 |
| `lib/*.js` 其余（宿主半） | 需要重启 DSH 桌面版 |
| `agent/mac/*.py` | 下次 Agent 重启时生效（supervisor 崩溃/重连会自动拉起，也可在面板里「修复」） |

## 5. 验证清单（桌面版）

1. `~/.dsh/profiles/desktop/package.json` 的 `bundles` 里有 `dsh-qq-farm`
2. 日志出现 `routes mounted` + `FAP v1 listening`
3. 界面右下角出现 `🌾 农场 0/1` 胶囊
4. 点开胶囊：能看到游戏实时画面 + 24 格地块 + 控制按钮
5. 游戏在**主页**（有底部 仓库/商店/宠物/图鉴/装扮/好友）时，点「开始」才会真的动作