常见问题

安装与连接

侧边栏显示 Gateway 未连接？

确认本地 Gateway 已启动且端口为 19836：

AGENT_EXECUTION_MODE=cli pnpm start:gateway
curl http://127.0.0.1:19836/health   # 应返回 executionMode:"cli"

若改了端口，请在扩展中同步 Gateway 配置（chrome.storage.local 的 gatewayHost / gatewayPort）。

扩展加载后没有侧边栏？

需要 Chrome ≥ 116，并在扩展详情里允许其使用 Side Panel。

CLI 相关

提示 CLI 未安装 / 未登录？

打开 Setup 向导：未安装会提供「安装」按钮，未登录会提供「登录」按钮。手动验证：

curl -XPOST http://127.0.0.1:19836/setup/detect -d '{"providers":["dingtalk"]}'

OAuth 授权超时？

重新在向导里发起登录；授权 URL 会重新流式回传，点击后尽快在浏览器完成授权。

执行失败、看到一段 CLI 报错？

官方 CLI 的错误会原样透传到「执行结果」区。按报错信息处理（多为未登录、权限不足或参数不符），必要时在终端直接运行对应命令复现。

选区相关

提示「按内容定位，可能不精确」？

说明当前目标拿不到稳定 id，回退到了内容匹配。尽量选择结构清晰的段落 / 单元格；执行前核对选区卡片里的内容摘要。

不支持的页面？

仅在受支持的文档域名（钉钉 / 飞书 / Notion，见 manifest 的 content_scripts 匹配）内可拾取。

模式相关

Direct 里输入了自然语言？

UI 会提示改用 Agent 模式——需要推理的任务应交给 Agent。区别见 Direct / Agent 模式。

想回退到旧的 MCP 链路？

设置 AGENT_EXECUTION_MODE=mcp 并让扩展 EXECUTION_MODE='mcp'。见 执行模式 与 MCP 模式（旧）。