网页划线对话 · 小虾 🦐
一个浏览器扩展 + 本地 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
├── pack.mjs # 发布工具：在 deploy 产物(双形态目录)下 node pack.mjs → 生成干净分享包 zip
├── gen-icons.mjs # 独立图标生成（零依赖）：node gen-icons.mjs [dir]
├── scripts/
│ ├── deploy.mjs # 脚手架：复制 assets 源码 + npm install + 生成 icons/（Windows 部署时生成 launcher.vbs + 注册协议）
│ ├── gen-vbs.mjs # 唯一 source of truth：写出 backend/launcher.vbs（agent 部署时调用，不随包分发）
│ └── register-protocol.cjs # 一键注册/修复 webchat:// 协议（协议丢失或被识别成 Store 应用时用）
├── assets/
│ ├── extension/ # 浏览器扩展（manifest/background/content/panel.*/icons）
│ ├── backend/ # server.js / launcher.mjs / patch-sdk.mjs / package.json / .env.example（launcher.vbs 由 agent 在部署时用 scripts/gen-vbs.mjs 生成，不随包分发）
│ └── root/ # 部署到目标根目录的文档：README.md（.gitignore / 协议模板不随包分发）
└── references/deploy-guide.md # 详细排错表
> 统一原则：本 skill 是唯一 source of truth。运行环境一律由 deploy.mjs 生成（assets → 目标目录），不要在别处手维护一份带 extension/ backend/ 的"双形态"目录，以免与 skill 不同步产生歧义。deploy 产物（目标目录）本身就是双形态目录（含 extension/ backend/ SKILL.md pack.mjs gen-icons.mjs），可直接加载运行，也可 node pack.mjs 生成分享包。
部署步骤（agent 照做）
- 脚手架：运行
node <skill_dir>/scripts/deploy.mjs <targetDir>（不加[targetDir]默认./webchat-extension或~/webchat-extension）。脚本把assets/里的扩展、后端、根文档复制到目标目录并npm install；在 Windows 上，agent 会自动用scripts/gen-vbs.mjs生成backend/launcher.vbs（即使带--no-protocol也会生成），并自动注册webchat://start协议，使面板「🚀 启动后端」按钮免终端生效。launcher.vbs是部署期产物，绝不随分享包分发/上传——若目标目录缺失它，可随时补：node <skill_dir>/scripts/gen-vbs.mjs <target>/backend。加--no-install只复制不装依赖；加--no-protocol跳过协议注册（但 vbs 仍会生成）。非 Windows 或需手动注册时，按 README「四、一键启动后端」用面板「📋 复制启动命令」手动npm start，或参考 README/references 手动reg add注册协议。 - 配置后端：在
<target>/backend/复制.env.example为.env，按需填CODEBUDDY_API_KEY（不填也能跑：复用本机codebuddyCLI 已登录凭据走登录模式真实 AI；只有显式设WEBCHAT_DEMO=1才进演示模式）。确认CODEBUDDY_MODEL=hy3（该账户不支持claude-sonnet-4）。 - 启动后端（后台运行）：
cd <target>/backend && npm start。监听http://localhost:3000。改代码后重启才生效。也可用面板「🚀 启动后端」按钮（需协议已注册）。 - 加载扩展：浏览器（Chrome / Edge / 千问 / 夸克 等 Chromium 内核）进入开发者模式 → 加载已解压的扩展程序，目录选
<target>/extension/。（deploy已自动生成extension/icons四张图标；若手动加载项目根extension/，请先跑node gen-icons.mjs）改了扩展代码要回扩展管理页点「重新加载」。 - 验证：访问
http://localhost:3000/api/health应返回{"status":"ok",...}；打开任意网页 → 点工具栏「🦐 小虾」图标 → 弹出面板 → 选中网页文字点「➕ 添加选中文本」→ 提问 → 流式回答。
发布分享包（可选，给其他人用）
deploy 产物（目标目录）即为双形态目录，内含 pack.mjs。在其中运行：
cd <target> # 例如 ~/webchat-extension
node pack.mjs # 在父目录生成 webchat-extension-share-YYYYMMDD.zip
pack.mjs 自动按 .gitignore + 硬性黑名单排除：node_modules/、.env、私钥 *.pem、extension.crx、协议注册表模板、所有 *.png（图标由收件人部署时生成）。生成的 zip 即干净分享包，可直接发给他人或推送到仓库。
CodeBuddy 认证（登录 / API Key 二选一，零配置优先）
后端 server.js 通过 CodeBuddy Agent SDK 调真实模型，认证方式参考 dingtalk-auto-reply 的「Key / CLI 已登录」范式：
- 登录模式（默认，零配置）：未配置 CODEBUDDY_API_KEY 时，SDK 自动复用本机 codebuddy CLI 已登录凭据（与你在终端 / WorkBuddy 登录的是同一套 ~/.codebuddy/local_storage），无需任何 Key 即可走真实 AI。首次启动前请确保 codebuddy 已登录（终端跑一次 codebuddy 完成登录）。
- Key 模式（推荐无人值守）：在 backend/.env 填 CODEBUDDY_API_KEY=<你的key>（申请：https://copilot.tencent.com 控制台）→ 用 Key 直连，不依赖交互登录。
- 演示模式：仅当显式设 WEBCHAT_DEMO=1 时强制进入（返回模拟回复验收交互）；否则无 Key 也走「登录模式」真实模型，不再降级为 demo。
- CODEBUDDY_INTERNET_ENVIRONMENT：中国版自动设为 internal（已在 server.js 兜底），无需手动配。
- 自检：/api/health 返回 mode（key｜login）、demo；/api/auth 用一次极短 query 实测登录态（15s 超时兜底，不卡死），失败回退到凭据目录存在性判断并给出明确修复提示。后端绝不代填 / 存储登录凭据——认证动作由你本人在终端完成。
> ⚠️ 进程清理绝不误杀：后端退出（/api/stop、空闲超时、托管心跳断、全局退出）时只清理「自己 spawn 出来的 codebuddy CLI 子进程」——按进程树（本进程后代）+ CLI 路径精确匹配，绝不按端口 netstat 乱扫（端口子串匹配会把 45012 误中 450123，且易误杀带看门狗、会被自动重拉的进程，如 dingtalk 监控）。即使某进程有看门狗会自愈，我们也连误杀都不做；另有「监听端口 + CLI 路径二次确认」兜底，确保外来进程永不被误杀。
关键坑（务必先读，否则部署必踩）
- 端口冲突导致一直转圈：官方 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时后端走「登录模式」复用 codebuddy CLI 已登录凭据，是真实 AI（不是模拟回复）；只有显式设WEBCHAT_DEMO=1才进演示模式（模拟回复用来验收交互闭环）。填了 Key 则走 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 即可。 - launcher.vbs 由 agent 部署时生成（绝不随包分发/上传）：
backend/launcher.vbs是 Windows 隐藏启动器，用于「🚀 启动后端」按钮免终端拉起launcher.mjs。它不进分享包、不进 git（被pack.mjs与.gitignore排除），由 agent 在部署时经scripts/gen-vbs.mjs现生成。若某次部署后按钮失效 / 报「找不到 launcher.vbs」，直接重跑node scripts/gen-vbs.mjs <target>/backend（或重新deploy.mjs）即可，无需手动编辑 vbs 内容。 - 微信读书等 iframe 阅读器：选区由
background.js用chrome.scripting.executeScript({allFrames:true})直插每一帧读取，能抓到；若阅读器是 sandboxed iframe（无 allow-scripts）且屏蔽 copy，则只能手动粘贴/输入到输入框再发送（发送会自动收进上下文）。 - webchat:// 协议被识别成 Microsoft Store 应用（弹"获取打开此链接的应用"）：这是
HKCU\Software\Classes\webchat注册表项丢失/损坏导致，Windows 找不到处理程序就去 Store 找 UWP 应用了。修复：运行node scripts/register-protocol.cjs（自动探测launcher.vbs位置并重新注册协议，支持--check仅检查、--force强制重写）。注册指向的launcher.vbs由 agent 在部署时用scripts/gen-vbs.mjs在目标目录生成，若你迁移过项目目录，用WEBCHAT_DIR=新目录 node scripts/register-protocol.cjs --force重新指向（缺失则先node scripts/gen-vbs.mjs <新目录>/backend生成）。
使用方式（交付给用户）
- 任意网页 → 点工具栏「🦐 小虾」图标 → 右侧弹出对话面板（高约视口 2/3，可拖动，双击标题栏复位，位置自动记住）。
- 喂上下文：选网页文字点「➕ 添加选中文本」（同时读选区 + 系统剪切板，含输入法复制）；或直接发送（自动收剪贴板/提问文本）。
- 上下文只显示 10~20 字摘要 + …，不可编辑；多段累加，✕ 删除。
- 输入框回车发送，AI 逐字流式回答，多轮保持上下文。
验证清单
- [ ]
http://localhost:3000/api/health返回 ok - [ ] 扩展已加载、未被禁用
- [ ] 点图标弹出面板、可拖动不抖、不跳左上角
- [ ] 选中文字 → 添加上下文 → 提问有流式回答
- [ ] 刷新网页后面板自动重开、上下文/对话不丢
- [ ] 真实 AI 模式（登录模式默认零配置 / 或填 Key）回答正常；
WEBCHAT_DEMO=1演示模式也能跑通闭环
参考
- 详细排错表见
references/deploy-guide.md。 - 来源项目：本地
webchat-extension/（本 skill 由其封装，扩展版本 1.5.5；路径随各人工作区不同，无硬编码）。
