Webchat Extension

SKILL.md

---
name: webchat-extension
description: 部署「网页划线对话」浏览器扩展（Chrome MV3 / 兼容 Chrome·Edge·千问·夸克 等 Chromium 内核浏览器）。在任意网页选中文字，点工具栏图标唤起可拖动对话浮层，带着网页上下文用 CodeBuddy AI 流式问答。包含本地 Express + SSE 后端（CodeBuddy Agent SDK）与前端扩展。当用户要「做一个网页划词对话插件 / 给浏览器装个网页对话工具 / 选中文字问 AI / 部署小虾网页对话扩展 / web highlight chat extension / 把网页内容丢给 AI 聊」时使用本技能。
---

# 网页划线对话 · 小虾 🦐

一个浏览器扩展 + 本地 AI 后端：用户在任意网页**选中文字**或**复制文字**，点工具栏图标弹出对话浮层，带着网页上下文直接和 AI 流式对话。后端基于 **CodeBuddy Agent SDK**（官方 `@tencent-ai/codebuddy-code` CLI 做 transport）。

## 什么时候用
- 用户想要「在网页上选中一段文字，直接问 AI 这是什么 / 帮我总结 / 翻译 / 解释」。
- 用户想把某个网页内容作为上下文和 AI 聊。
- 用户要部署/打包一个浏览器划词对话工具。

## 架构
```
浏览器扩展 (Chrome MV3)                本地后端 (Express + SSE)
┌──────────────────────────┐          ┌────────────────────────────┐
│ 点工具栏图标 → 浮层(iframe) │──fetch──▶│  /api/chat  (SSE 流式)      │
│ content.js 注入网页          │          │  query() → codebuddy CLI    │
│ background.js service worker│          │  (CodeBuddy Agent SDK)      │
│ 选区经 executeScript 跨 iframe│         │  buildSystemPrompt 注入网页上下文│
└──────────────────────────┘          └────────────────────────────┘
```
- 前端只请求 `http://localhost:3000`，**API Key 只在后端**。
- 面板状态（开关/位置/上下文/对话）用 `chrome.storage` 持久化，刷新不丢。

## 文件布局（本 skill 内）
```
webchat-extension/
├── SKILL.md
├── scripts/deploy.mjs        # 脚手架：复制源码 + npm install（+ Windows 自动注册协议）
├── assets/
│   ├── extension/            # 浏览器扩展（manifest/background/content/panel.*/icons）
│   ├── backend/              # server.js / launcher.mjs / patch-sdk.mjs / package.json / .env.example（launcher.vbs 由部署脚本生成，不随包分发）
│   └── root/                 # 部署到目标根目录的文档：README.md（.gitignore / 协议模板不随包分发）
└── references/deploy-guide.md  # 详细排错表
```

## 部署步骤（agent 照做）
1. **脚手架**：运行 `node <skill_dir>/scripts/deploy.mjs <targetDir>`（不加 `[targetDir]` 默认 `./webchat-extension` 或 `~/webchat-extension`）。脚本会把 `assets/` 里的扩展、后端、根文档复制到目标目录并 `npm install`。**在 Windows 上还会自动注册 `webchat://start` 协议**，并在 `backend/` 自动生成 `launcher.vbs`，使面板「🚀 启动后端」按钮免终端生效。加 `--no-install` 可只复制不装依赖；加 `--no-protocol` 可跳过协议注册。非 Windows 或需手动注册时，按 README「四、一键启动后端」用面板「📋 复制启动命令」手动 `npm start`，或参考 README/references 手动 `reg add` 注册协议。
2. **配置后端**：在 `<target>/backend/` 复制 `.env.example` 为 `.env`，按需填 `CODEBUDDY_API_KEY`（**不填也能跑，进演示模式**验收交互）。确认 `CODEBUDDY_MODEL=hy3`（该账户不支持 `claude-sonnet-4`）。
3. **启动后端（后台运行）**：`cd <target>/backend && npm start`。监听 `http://localhost:3000`。改代码后重启才生效。也可用面板「🚀 启动后端」按钮（需协议已注册）。
4. **加载扩展**：浏览器（Chrome / Edge / 千问 / 夸克 等 Chromium 内核）进入**开发者模式 → 加载已解压的扩展程序**，目录选 `<target>/extension/`。（`deploy` 已自动生成 `extension/icons` 四张图标；若手动加载项目根 `extension/`，请先跑 `node gen-icons.mjs`）改了扩展代码要回扩展管理页点「重新加载」。
5. **验证**：访问 `http://localhost:3000/api/health` 应返回 `{"status":"ok",...}`；打开任意网页 → 点工具栏「🦐 小虾」图标 → 弹出面板 → 选中网页文字点「➕ 添加选中文本」→ 提问 → 流式回答。

## 关键坑（务必先读，否则部署必踩）
- **端口冲突导致一直转圈**：官方 CLI 启动会起 prewarm 本地 server，端口由 `SERVER__PORT` 控制。若该端口被本机其他程序（**WorkBuddy 桌面应用**）占用，CLI 会 `EADDRINUSE` 卡死。解决：`.env` 设 `SERVER__PORT=40123`（空闲端口）并重启。**面板「🚀 启动后端」按钮路径**下，`launcher.mjs` 会自动从 `.env` 读取 `SERVER__PORT` 并**显式注入**子进程环境，覆盖本机可能存在的系统级 `SERVER__PORT`（dotenv 不覆盖已存在变量，故必须靠 launcher 注入）；未设置时则不注入、由 `server.js` 自动分配空闲端口。若走 `npm start` 手动启动且系统变量残留旧值，用 `SERVER__PORT=40123 npm start` 显式覆盖。
- **模型名 400**：本账户不支持 `claude-sonnet-4`。用 `hy3` 或 `auto`。
- **CLI 路径**：`server.js` 通过 `resolveCli()` 自动定位官方 CLI（优先级：显式 `CODEBUDDY_CLI_PATH` → PATH 上的 `codebuddy` → 受管 node 目录固定路径）。不要用 WorkBuddy 自带的那份 cli（协议不匹配会 initialize 超时）。
- **演示 vs 真实**：没填 `CODEBUDDY_API_KEY` 时后端返回模拟回复，用来验收交互闭环；填了才是真实 AI。
- **扩展不注入系统页**：`chrome://`、`edge://` 等页面扩展无法注入，点图标无反应属正常。
- **图标由 agent 部署时生成（分享包不含任何 *.png）**：`manifest.json` 声明了 `icons/icon{16,32,48,128}.png`，加载扩展前这 4 张必须存在，否则报 `Could not load icon` 加载失败。`deploy.mjs` 复制 extension 后会**自动生成**珊瑚橙 PNG（不依赖源图标）；手动从项目根加载（不跑 deploy）时，请先跑 `node gen-icons.mjs` 生成。想换正式品牌图标，部署后替换这 4 张 png 即可。
- **微信读书等 iframe 阅读器**：选区由 `background.js` 用 `chrome.scripting.executeScript({allFrames:true})` 直插每一帧读取，能抓到；若阅读器是 sandboxed iframe（无 allow-scripts）且屏蔽 copy，则只能手动粘贴/输入到输入框再发送（发送会自动收进上下文）。

## 使用方式（交付给用户）
- 任意网页 → 点工具栏「🦐 小虾」图标 → 右侧弹出对话面板（高约视口 2/3，可拖动，双击标题栏复位，位置自动记住）。
- 喂上下文：选网页文字点「➕ 添加选中文本」（同时读选区 + 系统剪切板，含输入法复制）；或直接发送（自动收剪贴板/提问文本）。
- 上下文只显示 10~20 字摘要 + …，不可编辑；多段累加，✕ 删除。
- 输入框回车发送，AI 逐字流式回答，多轮保持上下文。

## 验证清单
- [ ] `http://localhost:3000/api/health` 返回 ok
- [ ] 扩展已加载、未被禁用
- [ ] 点图标弹出面板、可拖动不抖、不跳左上角
- [ ] 选中文字 → 添加上下文 → 提问有流式回答
- [ ] 刷新网页后面板自动重开、上下文/对话不丢
- [ ] 真实 AI 模式（填了 Key）回答正常；演示模式也能跑通闭环

## 参考
- 详细排错表见 `references/deploy-guide.md`。
- 来源项目：本地 `webchat-extension/`（本 skill 由其封装，扩展版本 1.5.5；路径随各人工作区不同，无硬编码）。