# zncm Web Clipper

这是给 zncm 使用的 Chrome 插件，安装后默认连接 `config.js` 中配置好的服务地址。

默认地址配置在 `browser-extension/deer-web-clipper/config.js`：

```js
globalThis.ZNCM_WEB_CLIPPER_CONFIG = Object.freeze({
  defaultWebBaseUrl: "http://47.94.209.59:2026",
  defaultApiBaseUrl: "http://47.94.209.59:2026",
});
```

如果部署地址变化，只需要修改 `config.js` 里的这两个字段，然后重新加载插件。

正常情况下不需要手动配置 URL，也不需要手动复制 token。

## 能做什么

1. 把当前浏览器标签页发送到 zncm，作为 Markdown 附件进入聊天。
2. 接收 zncm 聊天中由 `browser_fetch_page` 工具创建的网页抓取任务。
3. 插件在 Chrome 中打开目标网页，读取可见文本和表格，再把结果回传给 zncm。
4. 在普通网页右下角显示“zncm 页面问答”浮窗，直接把当前页面内容交给 zncm 问答。
5. 接收 zncm 的 `browser_act` 交互式操作任务：在 Chrome 中打开页面并按 zncm 的指令**操作页面**——点击、输入、滚动、等待、页内跳转，每一步把页面上的可交互元素清单和正文回传给 zncm，由 zncm 决定下一步（observe→act 循环）。

## 页面操作（browser_act）

除了只读抓取，zncm 还能驱动插件**实际操作网页**，完成登录、填表、翻页找数据等多步任务：

1. zncm 调用 `browser_act` 工具，先 `navigate` 打开页面。
2. 插件打开标签页（同一会话会复用这个标签页），扫描页面上的可交互元素，给每个元素编号后连同正文回传给 zncm。
3. zncm 根据元素编号决定下一步（点第 3 个按钮、在第 1 个输入框填字……），再次调用 `browser_act`。
4. 插件执行动作、重新扫描页面、回传新状态，如此循环，直到任务完成。
5. 任务结束时 zncm 用 `action="close"` 关闭该会话标签页。

支持的动作：`navigate`（打开/跳转 URL）、`click`（点击元素）、`type`（输入文字，可选回车提交）、`scroll`（滚动到元素或下翻一屏）、`wait`（等待某 CSS 选择器出现）、`extract`（重新读取正文）、`observe`（仅重新扫描）、`close`（关闭会话标签页）。

> 提示：页面操作能力较强（可点击任意按钮、提交表单），可在后端 `config.yaml` 用 `browser_context.actions_enabled: false` 关闭，只保留只读抓取。

## 后端启用

在 `offline-backend-20260512/backend/config.yaml` 中保持：

```yaml
browser_context:
  enabled: true          # 只读抓取 + 页面问答
  actions_enabled: true  # 交互式页面操作 browser_act（不需要可设为 false）
```

修改配置后需要重启后端。

## 安装插件

1. 打开 Chrome 的 `chrome://extensions`。
2. 开启右上角的“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择目录：`browser-extension/deer-web-clipper`。
5. 安装后插件名会显示为 `zncm Web Clipper`。

## 安装即用

插件默认已经开启：

- 自动识别已打开 zncm 页面的服务地址。
- 自动同步已登录 zncm 的 token。
- 自动轮询 zncm 聊天触发的浏览器抓取任务。
- 页面问答框默认开启。

如果你打开的是 `config.js` 里配置的默认服务器，通常无需进入设置页。

如果部署地址变了，保持一个已登录的 zncm 页面打开，然后在插件设置里点击：

- `重新识别服务地址`
- `同步 token`

## 自动同步 Token

插件会自动从两个位置获取登录 token：

1. zncm API 域名下的 `access_token` Cookie，包括 HttpOnly Cookie。
2. 已登录 zncm 前端页面里的浏览器本地登录态。

切换登录账号后，插件后台每次轮询任务前都会重新同步 token；点击插件里的“同步 token”也可以立即刷新。

如果当前浏览器已经登出 zncm，且打开的 zncm 页面里没有 token，插件会清空旧 token，避免继续用上一个账号请求。

## 页面问答框

安装插件后，普通 `http` / `https` 页面右下角会出现 `AI` 按钮。点击后可以在当前网页上直接提问，例如：

```text
总结这页的核心结论
提取页面里的价格和时间
这张表里哪个指标最高？
```

插件会读取当前页面可见文本和表格，发送到 zncm，并把 zncm 的回答显示回浮窗里。多轮追问会复用同一个 zncm 会话；如果页面 URL 变化，会自动重新开始当前页会话。

是否显示问答框可以自己控制：

- 插件弹窗里勾选或取消“启用页面问答框”。
- 插件设置页里勾选或取消“启用页面问答框”。

关闭问答框只会隐藏页面浮窗，不会影响“发送当前页”和 zncm 聊天中的 `browser_fetch_page` 抓取任务。

## 手动发送当前网页

点击插件图标，选择“发送当前页”。

插件会读取当前页面的可见文本和表格，发送到 zncm，并打开一个新的 zncm 聊天页面。zncm 会把网页内容作为上传文件注入到首条问题里。

## 在 zncm 聊天中触发浏览器抓取

在 zncm 中输入带有明确 URL 的问题，例如：

```text
使用 browser_fetch_page 打开 https://example.com/report，提取页面里的关键表格数据并总结。
```

执行流程：

1. zncm 调用 `browser_fetch_page` 工具创建浏览器任务。
2. 插件后台轮询到任务。
3. 插件在 Chrome 中打开目标网页。
4. 插件提取页面文本和表格。
5. 插件把结果回传给 zncm。
6. zncm 基于回传内容回答你的问题。

这个方式适合读取需要浏览器登录态、内网权限或当前 Chrome 环境才能访问的页面。

## 注意事项

- 目标 URL 必须是明确的 `http` 或 `https` 地址。
- 插件不能读取 `chrome://` 等浏览器内部页面。
- 如果目标网站阻止扩展脚本注入，抓取可能失败。
- 后台任务默认会打开新标签页；是否抓取完成后关闭标签页，可在插件设置里配置。