ai-browser-debug

跨项目的 AI 浏览器可见调试工作流（Web / 浏览器插件）。
以 Agent Skill 形式分发，用 skills CLI 安装，和 skills.sh 市场同款体验。

仓库与 Skill 名均为 ai-browser-debug（由 ai-browser-test 更名）。已装旧名的项目必须重新 npx skills add yehuixiang/ai-browser-debug：只改安装目录名不会更新 SKILL.md 或 bundled scripts/，后续 npx skills update ai-browser-debug 也不会对其生效。

安装

# 装到当前项目（推荐，随仓库共享给同事）
npx skills add yehuixiang/ai-browser-debug -a cursor -y

# 或装到本机全局（所有项目可用）
npx skills add yehuixiang/ai-browser-debug -g -a cursor -y

# 本地路径试装（开发本 skill 时；换成你的实际目录）
# 必须带 --skill：本仓工作区里可能还有 gitignore 的其它 agent skills
npx skills add /absolute/path/to/ai-browser-debug --skill ai-browser-debug -a cursor -y --copy

# 升级
npx skills update ai-browser-debug

安装后落在：

Agent	项目级	全局
Cursor	.agents/skills/ai-browser-debug/	~/.cursor/skills/ai-browser-debug/
Claude Code	.claude/skills/ai-browser-debug/	~/.claude/skills/ai-browser-debug/

不会向业务仓库拷脚本或改 package.json。 唯一可能出现在项目根的是 .playwright-cli/ 调试产物（应 gitignore）。project-matrix.md 写在 skill 安装目录旁。

环境准备（使用前）

本 skill 默认这些已经就绪，运行时不再出确认表、不探测项目、不替你起服务：

• 已全局安装 @playwright/cli：npm install -g @playwright/cli
• 日常 Chrome 可用。插件且走 WXT/Plasmo：dev-runner 浏览器已打开、扩展已加载
• 你能提供浏览器里实际打开的地址（直连或 whistle / SwitchHosts 代理域名）

缺 CLI 时 AI 会停并告诉你去装，不会 npm install -g。仅桥接扩展缺失时给出安装 vs 跳过（CDP）。环境已就绪时直接挂已开日常 Chrome，不要新开浏览器。

触发

对 AI 说下面任意一句即可：

• 「测试一下」/「验证一下」/「帮我测一下」/「看看效果」
• test it / verify in browser

排障文档（给 AI 看）

在其它项目测挂了、要让 AI 修工具本身时，把下面文件丢进对话：

• docs/AI-DEBUG-CONTEXT.md — 背景、架构、硬约束、bootstrap 状态契约、已知坑、修 bug 落点

再附上：现象、skill 目录下的 project-matrix.md、node <skill>/scripts/playwright-bootstrap.cjs --json --no-cdp 输出（cwd = 项目根）、相关 .playwright-cli/ 日志。

版本记录见 CHANGELOG.md。发版与自动生成说明：docs/RELEASE.md。

首次运行会发生什么

1. 读 skill 目录下 project-matrix.md。没有打开地址则问一次：完整 URL + 是否经代理，写入 matrix。默认 type: web
2. 立刻 bootstrap 挂已开日常 Chrome。仅桥接扩展缺失时出现安装 vs 跳过。WXT / Plasmo 且 devRunner: true 时挂 runner 自己打开的浏览器
3. 认页：同源已开则选中，否则 tab-new。不要 playwright-cli open。Allow 页只在挂接超时才出现
4. 改代码后刷新当前页 → 基线冒烟 → 当前页优先 → 报告 + 截图（产物在项目 .playwright-cli/）

之后每次说「测试一下」直接进验证环（matrix 已有地址则不再问）。

仓库结构

SKILL.md 不在仓库根。skills CLI 若在根目录发现 SKILL.md，会把整个 Git 仓（含 .github/、发版脚本、docs）拷进安装目录。可分发内容只放在 skills/ai-browser-debug/。

ai-browser-debug/                         ← Git 仓库
├── README.md
├── LICENSE
├── VERSION / CHANGELOG.md / cliff.toml
├── package.json                          ← npm run changelog / release:* / test
├── docs/                                 ← 给排障 AI / 维护者，不随 skill 安装
├── .github/
├── scripts/                              ← 只放发版与回归
│   ├── release.cjs
│   ├── verify-robustness.cjs
│   └── verify-workflow.cjs
└── skills/ai-browser-debug/              ← npx skills add 唯一拷贝的目录
    ├── SKILL.md
    ├── project-matrix.template.md
    ├── profiles/web.md
    ├── profiles/extension.md
    ├── references/frameworks.md          ← 可选资料，happy path 不读
    └── scripts/                          ← 运行时（从 skill 目录执行，不拷到项目）
        ├── playwright-bootstrap.cjs
        └── playwright-env.cjs

设计要点

• 打开地址由用户提供（含代理域名），写入 matrix 后沿用；不探测框架 / 启动命令
• 唯一硬依赖 @playwright/cli（全局）；缺失则停并说明，不写进消费项目 package.json
• 永不静默降级：桥接扩展缺失时先提供安装选择，再允许 CDP
• 环境就绪直连：立刻 bootstrap 挂已开日常 Chrome，再认页；仅扩展缺失走降级。禁止 playwright-cli open
• 改代码一律刷新当前页；验证三层：基线冒烟 + 运行时用户描述 + 重复 ≥2 次提示回写基线

本地开发本仓库

# 在任意前端项目里试装当前目录
npx skills add /absolute/path/to/ai-browser-debug --skill ai-browser-debug -a cursor -y --copy

# 本仓回归
node scripts/verify-robustness.cjs
node scripts/verify-workflow.cjs

# 发版：升版本并自动生成 CHANGELOG（再按提示打 tag）
npm run changelog:notes
npm run release:patch    # 或 release:minor / release:major

# 改完 skills/ai-browser-debug/ 后，在目标项目里
npx skills update ai-browser-debug

License

MIT