# 常见问题

[← 全部文档](../README.md)

按你会遇到的顺序排列：安装、首次绑定、然后是该到却没到的卡片。英文版为 [../troubleshooting.md](../troubleshooting.md)。

**从 GitHub 首次安装停在 `ERR_PNPM_IGNORED_BUILDS`。**
git 依赖会从 registry 解析它自己的依赖，于是 pnpm ≥11 会撞上 `protobufjs` 的 postinstall，
在你允许或拒绝该脚本之前拒绝完成安装。pnpm 追加的那条占位项**不是决定**——
把它设为 `false` 再重新执行即可。从 npm 安装不会走到这一步，因为通道是内置的。

**pnpm 往 profile 里写了 `minimumReleaseAgeExclude`，或者装到的还是上一个版本。**
两者都是 pnpm 对"刚发布不久的版本"的供应链策略，不是本插件要求的：它会把太新的版本压住、
把不带版本的写法解析到上一个，并把实际放行的那个记进排除项。想立刻拿到新版本就**显式指定版本**——
`dsh plugin --profile web add dsh-pocket-console@0.7.6`——之后想自动跟随发布，再改回不带版本的写法。
另外 pnpm 会缓存 registry 元数据，几分钟前刚发布的版本可能在那份缓存刷新前一直看不见。

**从 `github:` 安装等于什么都没激活，启动会打 `pocket-console (dsh-pocket-console): failed to import`。**
pnpm 不去解析 git 依赖的 `bundleDependencies`：`dsh plugin --profile web add
github:picsky/dsh-pocket-console` 装下来的仓库**一个 `node_modules` 都没有**，而飞书通道正是
发布 tarball 内置的那几个包之一。在 0.9.5 + DSH 0.1.7-rc.2 上实测：该条目根本不在组合树里，
失败的那个 specifier 是 `qrcode`，而在同一个 profile 里补上通道之后，同一次安装就正常激活了。
两条出路：装发布包（`dsh plugin --profile web add dsh-pocket-console`）或本地打包的 tarball——
两者都自带通道；或者保留 git 安装、把通道补给 profile：`dsh plugin --profile web add
@larksuiteoapi/node-sdk qrcode`，再把 profile 的 `pnpm-workspace.yaml` 里 `allowBuilds` 下的
`protobufjs` 设为 `false`（上一条就是原因），重新执行一次 `dsh plugin --profile web install`。
之后重启 `dsh web`。

**任何一次启动都可能打出那句警告，而它不带任何细节。**
`failed to import` 是宿主自己的标签：某个已配置条目始终没拿到 fiber。宿主不会附上任何细节——
在本插件自己的副本里故意制造一个断掉的 import，打出来的就是这两行、上面什么都没有，
终端里问不出更多。要查的是条目本身，而不是那句警告：`dsh --profile web --dump-config` 应列出
`# == dsh-pocket-console` 层，卡片要用的接口应该存在——`http://127.0.0.1:3080/__pocket/state`
回 `401` 表示插件在跑，回干净的 `404` 表示它根本没被加载。安装完整的树每次重启都会正常激活，
所以包管理器改过 profile 之后请重启 `dsh web`；若警告仍在，请把 profile 的 `package.json`
和 `dsh plugin --profile web install` 的输出一起报出来。

**页面停在「Failed to load plugins」，整个界面都打不开。**
这一页是 Web shell 拒绝启动，不是"某张卡片出错"：它要求自己加载的每个插件都进入 active 状态，
而所需 Cordis 服务缺失的条目会永远等待——括号里写的就是缺哪个服务。DSH 0.1.7 上本插件正是那一条：
它把卡片绑定的浏览器端设置服务改了名（`settingsScope` → `configForms`），宿主侧的可编辑字段也从
`settings.installSection` 挪到条目自己的 volatile `Config` 上；0.9.2 及更早版本要求旧名字，
于是一个改了名的服务把整个界面一起拖垮。修复后按能力向 Host 索取设置通道并**等它出现**：
宿主不提供的服务最多让卡片不显示，不会影响页面。注意 0.9.3 只修好了启动、
仍然一张卡片都没注册——它只读了一次，而 0.1.7 的设置提供方那时还没 apply；真正能看到卡片的是 0.9.4。
若你用的是受影响的版本，先卸掉插件
（`dsh plugin --profile web remove dsh-pocket-console`）再升级。

**设置卡片没出现。**
卡片按 Host 服务的设置命名空间键控。先确认插件加载了
（`dsh --profile web --dump-config` 应列出 `# == dsh-pocket-console` 层），
然后刷新页面——已服务命名空间列表只在文档提交或重连时重读，不在注册时。
DSH 0.1.7 起设置里已经没有这张卡片：同一个卡片在侧边栏的**插件**页里，
列在该页的**官方**分组下（这一页把每个注册了设置页的插件都渲染在那里，
安装随附的页面同样在这一组；profile 自己持有的组合包在下面的「已安装」组）。
卡片挂上时，页面控制台会打印 `pocket-console: settings card mounted on plugins.item`。
**没有这行**就说明设置服务从未到达插件：0.9.4 之前的版本只读一次、且读得太早，于是什么都没注册。

**点「扫码创建应用」失败，或不出二维码。**
一键创建流程需要能访问 `open.feishu.cn`。如果主机走代理，确认该域名可达。

**点卡片上的操作回 404，或卡片提示"宿主还在运行旧版插件"。**
页面和提供页面的进程是**分开**替换的：`dsh plugin … add` 之后，页面可能已经是新版，
而 `dsh web` 还在跑旧代码，卡片要用的那条接口于是不存在。**重启 `dsh web`**
（只刷新页面不会更新宿主），重启后再刷新页面。

**「无法确认这组凭据」，或原因里点名 App ID / App Secret。**
插件用你填的那两项直接问了平台，平台拒绝了——说明 App ID 或 App Secret 与线上应用对不上。
请去开发者后台「凭证与基础信息」重新复制两项（secret 只显示一次，没存下来就重新生成）；
另外**被拒的那组凭据不会被保留**，这是有意的。若提示的是"平台没有给出明确答复"，
则说明这台机器连不上 `open.feishu.cn`。

**二维码出来了，但扫码后不完成。**
链接 10 分钟内有效且只能用一次。先「解除绑定」，再点「扫码创建应用」拿一个新的。
另外你的飞书账号必须能在所属组织内创建应用；个人版且未加入任何组织时，
先建一个免费组织并把自己拉进去。

**卡片一直停在「正在连接飞书…」。**
握手还在重试。超过 30 秒后卡片会说明这一等异常久。如果一直不完成，
要么这台机器连不上 `open.feishu.cn`，要么凭据不对——「解除绑定」后重新绑定；
如果你手上有确定可用的凭据，用「使用已有的应用」直接填。

**给 bot 发了私聊，但没有绑定成功。**
绑定只会由**私聊**发给**尚未绑定**的部署。群消息永不绑定；
已经绑定了接收人的部署会忽略其他账号——这是有意的，
因为接收人决定了审批卡片发去哪里、谁的点击算数
（见 [ADR 0006](../decisions/0006-binding-is-not-up-for-grabs.md)）。
要改一个已绑定的接收人：用「使用其他应用」，或者先「解除绑定」再发一条新的私聊。

**日志有 `ws client ready`，但点按钮没反应。**
飞书旧版「消息卡片回传交互」**不支持长连接**，只有新版 `card.action.trigger` 可以。
确认应用订阅了 `card.action.trigger`——一键创建流程已经帮你配好。

**点按钮回的是「该请求已处理或过期」。**
这次点击没有对应的存活请求：要么桌面已经先答了那条请求，要么它被取消了——
一旦产生决定就会改写卡片，按钮本应随之消失。0.1.0 之前的版本读错了卡片回调的字段路径，
**每次**点击都会回这个提示；如果 profile 里还是那个版本，升级即可。

**审批永远到不了手机。**
先看卡片报的是什么。**已绑定**且**长连接：已建立**，说明投递链路是通的，问题在别处
（`delaySeconds`，或接收人还没绑定——给 bot 发一条消息即可）。
**长连接：已断开，正在重连…** 说明这段时间只有桌面能答；
此时通道**有意不报告自己可用**，所以请求会留在桌面，而不是等一张回不来的卡片。
**连接失败**后面跟着的就是平台给出的原因。

**能和别的飞书机器人一起跑吗？**
只有在**不同应用**的前提下可以。飞书长连接是集群模式、不广播，
两个工具共用一个应用会互相静默丢回调。请新建一个应用。

**和 Auto review 预设兼容吗？**
审批不兼容。Auto review 下 `approval/policy` 为 `never`，
工具审批不再经过 `approval/request`，没有东西可以升级。提问升级仍然有效。

**会话明明跑完了，为什么什么都没收到？**
结果通知需要 `resultNotify: idle`、安静了 `delaySeconds` 那么久，并且这一轮要么产出了**答案**（一条说了话但没调用工具的消息），要么是**没跑完**的中断（出错或输出到上限）——后者不管结束在什么上都会通知。它在这些情况下不通知：会话还在干活、
距同一会话上一条通知不到 `resultNotifyCooldownSeconds`、子会话、
以及宿主已经把 agent 回收掉的会话。