内容
align="center">
# 技能写作
**向浏览器展示一个任务一次。获取任何代理都可以运行的技能 — 永久。**
[](https://github.com/gericke98/skillwright/actions/workflows/ci.yml)
[](LICENSE)
[](CHANGELOG.mdBuilt with TDD](https://img.shields.io/badge/built%20with-TDD-brightgreenCONTRIBUTING.md)
</div>
---
`skillwright` 观察您在浏览器中执行一个一次**，语义化地理解它，并将其编译成一个可移植的 [代理技能](https://agentskills.io) —— 一个标准技能目录，任何代理都可以针对您的 **真实、已认证** Chrome 会话，作为确定性脚本 *或* 作为指令进行推理。
```bash
skillwright record # 在您自己的 Chrome 中执行任务一次
skillwright distill recording.json # → 一个类型化、带有影响标签的代理技能
skillwright run approve-invoice --input invoice=INV-1042
```
当网站发生变化，选择器断裂时，`skillwright` **自动修复步骤** 并继续执行 — 然后在修复在多个运行中得到验证后，将其纳入技能中。
<div align="center">
<sub>提炼的技能针对实时应用重放 — 记录的选择器已过时，因此 skillwright 从实时页面修复步骤并完成删除。重现它：<code>pnpm demo</code>。</sub>
</div>
## 您获得的是 — 便携、易读的技能
`distill` 生成一个标准的 [代理技能](https://agentskills.io) 目录。`SKILL.md` 是人类可读的、类型化的，并带有影响标签 — 代理可以将其作为脚本运行 *或* 作为指令遵循：
```markdown
---
name: approve-invoice
description: 通过发票号码批准待处理的发票。适用于需要批准、释放或签署发票的情况。
compatibility: 需要 Node 20+、Chrome CDP 端点（skillwright 代理）和该浏览器中的已认证会话。
metadata:
version: "1.0"
skillwright-inputs: '[{"name":"invoice_number","type":"string","required":true}]'
---
# 批准发票
## 输入
- `{invoice_number}`（字符串，必填）
## 步骤
1. [只读] 打开发票列表。
2. [可变] 在“搜索发票”字段中输入 {invoice_number}。
3. [破坏性] 点击“批准发票 {invoice_number}”以释放它。
```
```
approve-invoice/
├── SKILL.md # 上述内容 — 指令 + 类型化输入 + 影响标签
├── scripts/replay.ts # 确定性 Playwright-over-CDP 重放
├── references/walkthrough.md # 完整步骤叙述 + 选择器堆栈
└── assets/recording.json # 不变、已编辑的证据
```
## 为什么不直接录制和重放？
经典的录制工具（Selenium IDE、Playwright codegen、RPA 工具）会将您的点击冻结为针对 XPath 的脆弱脚本。skillwright 在实际重要的轴上有所不同：
| | 录制-重放 / RPA | 纯 LLM 浏览器代理 | **skillwright** |
|---|---|---|---|
| 可靠性 | 脆弱（在任何 UI 更改时都会中断） | 每次运行都不确定 | **确定性脚本 + 自我修复备用** |
| 理解意图 | 否 | 是（但每次都重新派生） | **一次，然后冻结为可重用的技能** |
| 在您的真实会话上运行 | 通常是全新的自动化配置文件 | 取决于 | **您的认证 Chrome，通过 CDP 代理** |
| 对破坏性操作的安全性 | 没有相关概念 | 希望最好 | **来自 HTTP 方法 + 标签的效果；确认后再删除/支付/发送** |
| 跨代理可移植性 | 否 | 绑定到一个框架 | **标准代理技能 — 在 Claude Code、Codex、… 中运行** |
| 机密信息 | 原样捕获 | 在上下文中 | **在它们接触磁盘之前进行编辑** |
## 它是如何工作的
```
record distill (LLM) run
┌─────────┐ ┌──────────────────┐ ┌──────────────────────────┐
│ Chrome │ ───► │ 意图 │ ──► │ 1 级 确 │
│ │ │ 参数 │ 2 级 选择器 │
│ │ │ │ │ 3 级 代理修复 ─── 隔离 │
│ 代理 │ 影响标签 🛡 │ │ （安全性保证） ► 提升─────────┘ └──────────────────┘ └──────────────────────────┘ 验证后
```
- **捕获网络真相，而不仅仅是点击。** 被动 观察器记录后的实际 HTTP 调用。方法（`GET`/`POST`/`DELETE`）是一种 **非 LLM** 安全信号 — `DELETE` 发射是步骤具有破坏性的硬证据 — 请求 URL/正文证实哪些值是真实参数。DOM 手势给出意图；网络给出基本事实。
- **确定性阶梯。** 重放尝试快速、无 LLM，首先下降选择器堆栈，仅在页面真正更改时升级到 LLM 以完成步骤。
- **自我修复赢得信任。** 成功修复被 **隔离** 并用于当前仅在重复干净验证后才提升为规范技能 — 因此看似合理临时修复无法破坏共享技能。
-至关重要。** 每个步骤都标readonly` / `mutating` / `destructive`（LLM 判断发式底线融合，只能 **提高** 严重性）。破坏性步骤需要确认；可能部分执行的步骤永远不会重试。参见 [SECURITY.md](SECURITY.md)。
## 安装
**CLI** — 来自 npm：
```bash
npm i -g skillwright # 或：npx skillwright <command>
```
（也可在每个 [Release](../../releases) 中作为 `skillwrighttgz` 资产提供，用于隔离安装：`npm i -g ./skillwright-*.tgz`。）
**扩展**（v1 以 unpacked 开发者模式发布）：
1. 从最新的 [Release](../../releases) 下载 `skillwright-extension.zip`。
2. 解压它，打开 `chrome://extensions`，启用 **开发者模式**，点击 **加载 unpacked**，然后选择文件夹。
> **已知的 v1 限制。** unpacked 扩展显示启动提示，并且可以在托管/企业配置文件中禁用。对于 v1 的受众（开发者模式用户）来说，这是的；计划进行快速跟进的 Chrome 应用商店提交。
## 快速入门
两种方式进入。**如果您只需要技能，请选择面板**；如果您想将其连接到代理、在 CI 中重放或自我修复，请选择 CLI。
### A. 直接从浏览器（无 CLI）
打开侧边栏，面板会自行运行整个管道：
**记录 → 提炼 → 参数化 → 生成脚本 → 导出 → 验证**
您批准它提出的 **参数**（机密始终是参数，无法取消勾选），然后 **保存到技能文件夹** 会将 `skillwright/<slug>/{SKILL.md, scripts/replay.ts, assets/recording.json}` 直接写入您选择的文件夹 — 一个完整、可移植的代理技能。**验证** 在选项卡放它，以便您在信任它之前看到它起作用（除非您要求，否则不会跳过破坏性步骤）。
**无需 API 密钥 — 使用您已经拥有的 CLI。** 运行：
```bash
skillwright serve # 为面板提供此机器的 LLM；打印端口 + 令牌
```
在 *LLM 设置* 中选择 **本地 skillwright CLI**，粘贴端口和令牌，面板会通过您现有的 `claude` / `codex` / `gemini` 身份验证编译技能。浏览器中没有密钥，创建时也没有密钥，代理 CLI 已经发送的任何内容都不会发送到此处。
**或带上您自己的密钥 — skillwright 不运行网关。** 在 *LLM 设置* 中选择 Anthropic 或 Open您自己的密钥，或 **自定义** 以指向任何 OpenAI 兼容端点：您的网关（OpenRouter、LiteLLM、Azure、公司代理）或本地模型，如 **Ollama**，它也不需要密钥。密钥存储在 `chrome.storage.local` 中，仅发送到您命名的端点。
**完全没有密钥仍然有效。** 管道永远不会终止：您会失去 LLM 编写的描述和名称，但技能仍然编译，**安全底线仍然生效** — 编辑后的密码仍然被强制输入到必需的、无值的参数中，因为该代码，而不是提示。
### B CLI
```bash
# 0.环境是否准备就绪（LLM 后端、Chromium、可写库）：
skillwright doctor
# 1. 通过侧边栏在 Chrome 中记录 — 它保存 recording.json。提炼它：
skillwright distill recording.json --semantic
# 2. 通过代理重放针对您的真实 Chrome：
skillwright relay # 托管端点；在侧边栏中配skillwright run <skill> --confirm-destructive
skillwright run <skill> --cdp <url> --timeout 15 # 提高慢速应用的每时间
# 使其对您的代理（Claude Code + Code）可见：
skillwright install <skill> --project . # → .claude/skills/ 和 .agents/skills/
skillwright list # 库 + 安装位置 promote <skill> # 提升已修复为规范
```
记录您自己的日常任务？参见 **实际录制指南** ([docs/recording-real-world-tasks.md](docs/recording-real-world-tasks.md)) — 什么能干净地捕获，如何处理慢速应用、文件上传、代理与 `--cdp`、安全性以及故障排除。
提炼后端是可插拔的：**agent-cli** 默认（自动检测 `claude` / `codex` / `gemini`），或通过 `SKILLWRIGHT_API_KEY` 使用 **Anthropic API**。
## 从任何代理使用技能
- **脚本模式** — 代理运行 `skillwright run <skill>`（确定性，除非需要修复，否则无需 LLM）。
- **语义模式** — 具有自己浏览器工具的代理读取 `SKILL.md` 并遵循步骤；遍历的选择器堆栈使其可靠。
- **MCP 模式** — `skillwright mcp` 运行一个模型上下文协议服务器，将每个已安装的技能作为可调用的 **工具** 公开，以便使用代理（OpenAI、、Cursor、Claude、...）可以列出和运行您的技能：
```jsonc
// 在任何 MCP 客户端的配置中
{ "mcpServers": { "skillwright": { "command": "skillwright", "args": ["mcp"] } ```
通过 `.claude/skills`agents/skills` 进行发现涵盖 Claude Code、Codex 和 Cursor；MCP 服务器涵盖其他所有情况。同样的技能，适用于任何代理。
## 状态和路线图
Pre-1.0。整个管道 — 捕获 → 语义提炼 → 自我修复重放 → 安装 — 已构建并正常运行（每个里程碑都针对实际的内容进行检查：实时 LLM、真实 Chromium 和真实的非 Anthropic 代理）。到 1.0 的诚实差距：
- [ ] 发布到 npm + Chrome 应用商店提交
- [x] **扩展内管道** — 记录 → 提炼 → 参数化 → 脚本 → 导出 → 验证，完全在侧边栏中。CLI 现在是可选的。
- [x] 实时网络真相捕获（被动 CDP 观察器）+ API 重放模式
- [x] 通过中继传输的 3 级修复（扩展 ARIA 快照通道）
- [x] 通过中继的文件上传（`DOM.setFileInputFiles`）— 两种路径现在都支持
- [x] 键盘快捷键保真度 — 修饰符在捕获 → 重放中得以保留
- [x] 现实世界强化 — 使用公共网站测试修复了 4 个错误（选择器优先级、嵌套 URL 机密泄露、表单字段锚点、选择器唯一性）
- [x] **影子 DOM** — 通过 `composedPath()` 捕获穿透边界（真实的内部元素，而不是重新定位的主机）；两种重放路径都穿透开放的影子根（Playwright 原生，代理解析器递归影子根）。
- [x] **框架** — 捕获在每个框架中运行（`all_frames`）；重放适用于 Playwright/cdp 路径上的（包括跨源 — Playwright 不受同源策略限制）和同一源在代理路径上。
- [ ] **通过代理跨源 iframe 重放 页面解析器无法访问跨源框架（浏览器安全边界）；使用 cdp 路径。
- [ ] Windows / 复制模式下安装分歧处理 / 限制文件系统
- [ ] 扩大评估基准库以适应现实世界的网站
## 开发
pnpm monorepo。`pnpm test` · `pnpm typecheck` · 夹具应用：`pnpm --filter @skillwright/fixture-app serve`。评估套件按需运行（令牌成本）：`pnpm eval`。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 `docs/s
