OpenSpec + Playwright E2E 验证

English version

OpenSpec 项目获得与代码同住的 AI 驱动 E2E 验证。 一条 /opsx:e2e <change> 命令（支持七款编辑器）按 spec 规划、生成、执行并自愈 Playwright 测试，附每 change 报告，无需手搭脚手架。

为什么有这个工具：spec 驱动的开发没有测试自动化是半截闭环。本工具把它补完——写 change spec，跑一条命令，拿到可追溯到 spec 锚的测试，外加一份说明什么通过、什么自愈、什么留待人工的报告。

目录

• 安装
• 前置条件
• 初始化
• 支持的 AI 编码助手
• 使用
• 工作原理
• CLI 命令
• 初始化时选择编辑器
• 官方 Playwright Agents
• openspec-pw init 做了什么
• 首次配置清单
• openspec-pw doctor 检查清单
• 认证配置
• 自定义
• 架构
• 许可

安装

npm install -g openspec-playwright@latest

仅支持通过 npm 安装。openspec-pw update 通过 npm install -g 自更新——用 pnpm/bun/yarn 全局安装会装出第二份冲突副本，不受支持。

前置条件

必需：

1. Node.js >= 20
2. Claude Code（带 .claude/ 目录）和/或 OpenCode（带 .opencode/ 目录）和/或 Cline（带 .cline/ 或 .clinerules/ 目录）和/或 Cursor（带 .cursor/ 目录）和/或 Pi（项目 .pi/ 或全局 ~/.pi/agent/）和/或 Oh My Pi（项目 .omp/ 或全局 ~/.omp/agent/）和/或 CodeBuddy CLI（带 .codebuddy/ 目录）
3. OpenSpec 已初始化：npm install -g @fission-ai/openspec@latest && openspec init
4. Playwright MCP（用于测试执行 + Healer）— openspec-pw init 会在检测到前端信号时按编辑器自动安装（纯 API 项目跳过——API 测试用 request fixture），全部项目级（写入项目内文件；Claude Code 用 --scope project 写项目根 .mcp.json，不碰全局 ~/.claude.json）。安装单个 server，与 Playwright 官方 playwright init-agents 布局一致：
   • playwright-test — 官方 test-runner server（npx playwright run-test-mcp-server，playwright 包自带）。是 @playwright/mcp 的超集：一个条目同时暴露 browser_* 浏览器工具（探索 + Healer 页面检查）和结构化的 test_run / test_debug / test_list 工作流工具（Healer 闭环）。
   • Claude Code：claude mcp add --scope project playwright-test npx playwright run-test-mcp-server（写入项目根 .mcp.json；受管 .gitignore 块默认忽略以保护凭据——自加 server 常含 API key，团队确需共享须显式 git add -f .mcp.json）
   • OpenCode：合并到 opencode.jsonc 的 mcp["playwright-test"] = { type: "local", command: ["npx", "playwright", "run-test-mcp-server"] }
   • Cline：合并到 .cline/mcp.json 的 mcpServers["playwright-test"] = { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }
   • Cursor：合并到 .cursor/mcp.json 的 mcpServers["playwright-test"] = { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }
   • Oh My Pi：合并到 .omp/mcp.json 的 mcpServers["playwright-test"] = { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }
   • CodeBuddy CLI：合并到项目根 .mcp.json 的 mcpServers["playwright-test"] = { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }（直接文件读写，不经 codebuddy mcp CLI——CLI 会与运行中的会话抢端口）
   • Pi：无 MCP 客户端，跳过安装 — 浏览器探索改用 openspec-pw explore

旧版本迁移：早期版本把 Claude Code 的 Playwright MCP 装到全局 user 域（~/.claude.json）。若你用旧版 openspec-pw 初始化过，全局残留仍会对所有项目生效，清理一次即可：claude mcp remove playwright（user 域）。注意：项目级 server 首次交互使用时 Claude Code 会弹出批准提示（claude mcp reset-project-choices 可重置选择）。

server 名 playwright-test 的来历：这是 Playwright 官方 playwright init-agents CLI 的产物名——同名、同 transport（npx playwright run-test-mcp-server，playwright 包内置子命令）。它不是 @playwright/mcp（独立 npm 包，注册名 playwright，约 67 个 browser_* 工具）；test-runner 是它的超集（约 80 个工具：完整 browser_* 集 + Healer 闭环用的结构化 test_run / test_debug / test_list 工作流工具）。两个 server 名字不同、可共存；搜「Playwright MCP」通常先看到的是 @playwright/mcp 的文档。

浏览器探索能力由 Playwright MCP 和 openspec-pw explore 内置提供，无需额外工具。

初始化

# 在项目目录下
openspec init              # 初始化 OpenSpec
openspec-pw init          # 安装 Playwright E2E 集成（--tools 选编辑器，--agents 加装官方 agents）

注意：运行 openspec-pw init 后，手动安装 Playwright 浏览器：npx playwright install --with-deps

支持的 AI 编码助手

| 编辑器 | 命令 | Playwright MCP | AGENTS.md 加载方式 | |---|---|---|---| | Claude Code（Anthropic） | /opsx:e2e | 是（项目 .mcp.json） | 经 CLAUDE.md → @AGENTS.md | | OpenCode（SST） | /opsx-e2e | 是（opencode.jsonc） | instructions 字段 | | Cline | /opsx-e2e | 是（.cline/mcp.json） | 原生 | | Cursor | /opsx-e2e | 是（.cursor/mcp.json） | 原生 | | Pi（earendil-works） | /opsx-e2e | 否 — 改用 openspec-pw explore + npx playwright test | 原生 | | Oh My Pi（omp） | /opsx-e2e | 是（.omp/mcp.json） | 原生 | | CodeBuddy CLI（腾讯） | /opsx:e2e | 是（项目根 .mcp.json） | 经 CODEBUDDY.md → @AGENTS.md |

各编辑器命令体完全相同（安装时 /opsx: → /opsx- 改写）。具体安装路径、检测信号、auth/MCP 细节见下方 使用 与 前置条件 两节。

使用

选匹配你项目的编辑器，发同一命令。七款编辑器共用同一工作流——/opsx: 在安装时改写为 /opsx-，正文完全一致，只有命令工件的落盘位置不同。

| 编辑器 | 命令 | 安装位置 | |---|---|---| | Claude Code | /opsx:e2e <change-name> | .claude/commands/opsx/e2e.md | | OpenCode | /opsx-e2e <change-name> | .opencode/commands/opsx-e2e.md | | Cline | /opsx-e2e <change-name> | .cline/skills/opsx-e2e/SKILL.md | | Cursor | /opsx-e2e <change-name> | .cursor/commands/opsx-e2e.md + .cursor/skills/opsx-e2e/SKILL.md | | Pi | /opsx-e2e <change-name> | .pi/prompts/opsx-e2e.md（文件名即命令名） | | Oh My Pi | /opsx-e2e <change-name> | .omp/commands/opsx-e2e.md | | CodeBuddy CLI | /opsx:e2e <change-name> | .codebuddy/commands/opsx/e2e.md |

• Cursor：skill 设置 disable-model-invocation: true（仅在显式调用时加载）。若要用 Cursor 但还没有 .cursor/：mkdir -p .cursor。
• Pi：没有 MCP 客户端——浏览器探索改用 openspec-pw explore，测试执行用 shell 跑 npx playwright test（无 Healer 步骤）。
• Oh My Pi：若 .claude/ / .cursor/ / opencode.jsonc 已存在并配置了 MCP，omp 会一并继承。
• CodeBuddy CLI：冒号命名（同 Claude Code，/opsx:e2e）——命令正文保留 /opsx: 引用不做改写。

初始化时选择编辑器

openspec-pw init 默认自动检测项目中的编辑器并全部配置。如需只装一部分（或不装），用 --tools —— 语义与 openspec init --tools 一致：

openspec-pw init --tools claude,cursor   # 只配置 Claude Code 与 Cursor
openspec-pw init --tools all             # 配置所有受支持编辑器
openspec-pw init --tools none            # 不配置编辑器，只生成脚手架

受支持 id：claude、opencode、cline、cursor、pi、omp、codebuddy（oh-my-pi 是 omp 的别名）。id 大小写不敏感、重复自动去重、all/none 不能与具体 id 混用。被 --tools 指定的编辑器即使未被检测到也会配置（会自动创建其配置目录）。

未提供 --tools 时：TTY 终端弹出交互式多选。预选读取 openspec-pw 配置清单，而非目录存在性：实际拥有 openspec-pw 产物（命令文件、MCP 条目、claude legacy 技能目录）的编辑器被预勾选并标注 (configured)。项目完全没有任何 openspec-pw 状态时（首次运行）预选仅看项目自身信号——marker 目录加根目录意图文件（根 CLAUDE.md → claude、根 .cursorrules → cursor、根 opencode.json(c) → opencode、根 CODEBUDDY.md → codebuddy）；机器上装有但项目未用的编辑器（如经全局 ~/.pi/agent/、~/.omp/agent/ 检测到的 Pi / Oh My Pi）列出但不勾选，并有一行灰字提示。一旦配置过任何编辑器，撑着目录存在性的外部文件（官方 openspec CLI 自己的 opsx-* 文件、你自己的配置、全局目录）就不再影响预选。--tools 与 --no-mcp 正交：前者选择哪些编辑器，后者决定是否为它们安装 Playwright MCP。

init 打印两种输出信号：预选提示行（仅未传 --tools 时出现）——有 openspec-pw 状态的项目是 Configured (pre-select):，首次运行回退则是 Detected (pre-select):——不是实际安装集；Selected editors: 行（总是打印，位于任何编辑器配置之前）才是实际安装集。判断装了什么，看 Selected editors。

取消勾选 = 移除。交互式多选里，已被探测但你取消勾选的编辑器的 openspec-pw 产物会被移除——命令/技能文件、该编辑器的 openspec-pw MCP 条目（含 claude 的 wrapper 块与 legacy 技能目录，以及归本工具所有的 vendored agents），前置一次列出全部待移除项的确认（拒绝则保持旧行为：本次仅跳过写入）。只动 openspec-pw 自有领土——同一文件中你自有的配置条目不受影响；你手改过的 vendored agent 文件会被保留并报告，绝不删除。共享规则：AGENTS.md 的 openspec-pw 块仅在没有任何编辑器保留时移除；symlink 的 CLAUDE.md 永不穿透写入。--tools 与非 TTY 运行不做任何移除（--tools 是显式授权清单）。移除直接反哺预选：被移除的编辑器下次 init 不再预勾选（预选读 openspec-pw 清单——保留的 mcp.json、你自己的文件、全局目录都不再重要）；全部取消并确认的项目下次 init 重置回首-运行预选语义。

编辑器领土：update 只维护项目内已有 openspec-pw 命令工件的编辑器——不会新增编辑器（全局配置目录或手建的 .cursor/ 不构成写入授权）。给已初始化项目新增编辑器请重跑 openspec-pw init --tools <id>（幂等）。

官方 Playwright Agents

openspec-pw init --tools claude --agents   # 额外安装官方三个 agent 定义

--agents（默认关）把 Playwright 官方 playwright init-agents（claude loop）生成的三个 agent 定义逐字快照装进 .claude/agents/：

• playwright-test-planner.md — 探索应用、产出测试计划
• playwright-test-generator.md — 生成测试代码
• playwright-test-healer.md — 调试并修复失败测试

它们的 tools: frontmatter 引用的正是 playwright-test MCP server——本工具装好的那一条目，MCP 前提天然满足。交互式 init 会在编辑器确认后追加一个默认 No 的确认项；纯 API 项目与 MCP 一起跳过（该相位跟随同一前端信号门控——agent 的工具全是 MCP 工具）。归属按内容判定：与内置快照一致的文件（上游基线见 templates/agents/SOURCE.md）归本工具所有——update 在快照升级时刷新、移除路径一并删除；你手改过的（或用新版官方 init-agents 刷过的）文件永不覆盖、永不删除，仅提示。doctor 报告其存在、归属状态，并在 playwright-test MCP 条目缺失时给出非阻断 ⚠。

与 /opsx:e2e 的分工：命令模板是 OpenSpec 锚定的完整管道（计划 → 生成 → 带 App Bug Registry 的治疗闭环 → Phase 3 人工升级）；vendored agents 是无 change 在飞时可单独召唤的子 agent。工作流内部，Planner 与 Generator 两个阶段在子 agent 已安装时可委托执行（规则随委托提示词传递，产物由主 agent 核验）；Healer 阶段永不委托——管道护栏取代官方 healer 的自主改断言行为。项目 AGENTS.md §6 约束一切来源的 agent。

官方 healer 与本工具护栏的差异：官方 healer 被指示「不要问用户、可通过修改断言和期望值修复失败测试」；本工具的 Healer 管道禁止未授权放宽断言——更新断言或 spec 是 Phase 3 的人工决策。单独召唤官方 healer 快速修测试是你的选择，但不要把它的输出混入 /opsx:e2e 交付流。

如果你坚持自己跑 npx playwright init-agents：它是清场重写型——整文件重写 .mcp.json（你自装的 MCP 条目会被销毁，fixture 已实证）、已有 opencode.jsonc 时另立 opencode.json、且要求随 Playwright 升级重跑。必须跑的话请在 openspec-pw init 之前，跑完 git diff .mcp.json 检查其他条目幸存。用 --agents 则不需要跑它——官方新版快照由 update 同步。

CLI 命令

openspec-pw init          # 初始化集成（--tools all|none|ids… 可选编辑器；--agents 加装官方 agents）
openspec-pw update        # 更新 CLI 和命令到最新版本
openspec-pw doctor        # 检查前置条件 (Node, Playwright, OpenSpec, 配置, 测试) + 应用服务器诊断
openspec-pw audit         # 检查测试文件是否有孤儿文件和配置问题
openspec-pw coverage      # 分析 spec 与测试之间的覆盖率
openspec-pw flake         # 检测测试文件中的静态不稳定模式
openspec-pw migrate       # 迁移旧测试文件到新目录结构
openspec-pw explore       # 探索应用路由
openspec-pw uninstall     # 移除项目中的集成

工作原理

Spec 锚与过时测试审计

Generator 生成的每条测试上方带一行 spec 锚 注释：

// spec: coupon#优惠券七天后过期
test('coupon expires after 7 days', async ({ page }) => { ... });

锚的 <capability>#<requirement> 直接使用 delta spec 中 requirement 的标题原文（不做 slug 转换），openspec-pw audit 因此能用纯文本匹配对主 spec 核验。审计报告五态：

| 状态 | 信号 | 含义 | |---|---|---| | 锚指向的 requirement 已不在主 spec | ⚠ issue，引证删除它的归档 change | 测试是候删项——删除 / test.fixme 附理由 / 行为仍存活则保留 | | 锚的 capability 段写成了 change/提案名 | ⚠ issue，精确诊断 | 生成端笔误——修锚即可，测试本身无需 review | | 锚指向的 capability 目录缺失（且非 change 名） | ⚠ issue（单独类别） | 大概率是 capability 改名——先核验再处置 | | 某 change 目录下有测试无锚 | ℹ 每目录一行 info | 锚机制之前的存量或漏写——仅可见性提示，不计入 issue 数 | | test.fixme 的测试 | 跳过 | fixme 即「已知过时、故意保留」的声明，报告它是噪音 |

audit 只报告、绝不删除——测试退役永远是人工决策。存量无锚测试不迁移，随新测试自然带锚而逐步退役。MCP 录制流（generator_write_test）产物按操作步骤切、天然无锚，模板 review 清单含补锚步骤。

# 由 /opsx:e2e <change-name>（Claude Code / CodeBuddy CLI）或 /opsx-e2e <change-name>（OpenCode/Cline/Cursor/Pi/Oh My Pi）触发
/opsx:e2e <change-name>
  │
  ├── 1. 选择 change → 读取 openspec/changes/<name>/specs/
  │
  ├── 2. 检测 auth → 从 specs 识别登录/认证标记
  │
  ├── 3. 验证环境 → 运行 seed.spec.ts
  │
  ├── 4. 探索应用 → 浏览器探索（Playwright MCP / `openspec-pw explore`）
  │       ├─ 读取 app-knowledge.md（项目级知识）
  │       ├─ 从 specs 提取路由
  │       ├─ 遍历每个路由 → snapshot → screenshot
  │       └─ 写入 app-exploration.md（change 级发现）
  │           └─ 提取模式 → 更新 app-knowledge.md
  │
  ├── 5. Planner → 生成 test-plan.md
  │
  ├── 6. Generator → 创建 tests/playwright/changes/<name>/<name>.spec.ts
  │       └─ 写测试前先在真实浏览器验证选择器
  │
  ├── 7. 配置 auth → auth.setup.ts（如需要）
  │
  ├── 8. 配置 playwright → playwright.config.ts
  │
  ├── 9. 执行测试 → npx playwright test
  │
  ├── 10. Healer（如需要）→ 通过 MCP 自动修复失败
  │
  └── 11. 报告 → openspec/reports/playwright-e2e-<name>-<timestamp>.md

openspec-pw init 做了什么

1. 检测项目中的受支持编辑器（Claude Code 和/或 OpenCode 和/或 Cline 和/或 Cursor 和/或 Pi 和/或 Oh My Pi 和/或 CodeBuddy CLI；Pi 与 Oh My Pi 也会通过全局配置目录 ~/.pi/agent/ / ~/.omp/agent/ 检测）
2. 为每个检测到的编辑器安装 E2E 命令（Claude Code / CodeBuddy CLI 用 /opsx:e2e，OpenCode / Cline / Cursor / Pi / Oh My Pi 用 /opsx-e2e；Cursor 另装 Agent Skill）
3. 生成 tests/playwright/seed.spec.ts、auth.setup.ts、credentials.yaml、app-knowledge.md、pages/BasePage.ts
4. 检测前端信号（分层检测：框架配置文件 → 前端框架依赖 → dev 命令关键词，含 monorepo workspace 成员检测——前端在 apps/* 的 pnpm/npm workspace 也能识别）；未检测到时在 Summary 打印引导提示——monorepo 去应用目录运行 openspec-pw init，纯 API 项目用 Playwright request fixture

首次配置清单

首次使用 E2E 工作流，按顺序执行以下步骤：

| 步骤 | 命令 | 失败时快速修复 | |------|------|----------------| | 1. 安装 CLI | npm install -g openspec-playwright@latest | 检查 Node.js 版本 node -v（需 >= 20） | | 2. 安装 OpenSpec | npm install -g @fission-ai/openspec@latest && openspec init | npm cache clean -f && npm install -g @fission-ai/openspec@latest | | 3. 初始化 E2E | openspec-pw init | 运行 openspec-pw doctor 查看具体缺失项 | | 4. 安装 Playwright MCP | claude mcp add --scope project playwright-test npx playwright run-test-mcp-server（Claude，写入项目根 .mcp.json），或将 mcp["playwright-test"] 加入 opencode.jsonc（OpenCode），或将 mcpServers["playwright-test"] 加入 .cline/mcp.json（Cline）/ .cursor/mcp.json（Cursor）/ .omp/mcp.json（Oh My Pi），或合并进项目根 .mcp.json（CodeBuddy CLI，直接文件读写）；Pi 无简单 MCP 配置文件，跳过 | cat .mcp.json（Claude / CodeBuddy CLI，检查 mcpServers["playwright-test"]）/ cat opencode.jsonc（OpenCode）/ cat .cline/mcp.json（Cline）/ cat .cursor/mcp.json（Cursor）/ cat .omp/mcp.json（Oh My Pi）确认安装成功 | | 5. 安装浏览器 | npx playwright install --with-deps | macOS 可能需先运行 xcode-select --install | | 6. 启动开发服务器 | npm run dev（在另一个终端） | 确认端口，配置 BASE_URL | | 7. 验证环境 | npx playwright test tests/playwright/seed.spec.ts | 检查 playwright.config.ts 中的 webServer 配置 | | 8. 配置认证（如需要） | 见下方"认证配置" | npx playwright test --project=setup 调试 | | 9. 运行第一个 E2E | /opsx:e2e <change-name>（Claude / CodeBuddy CLI）或 /opsx-e2e <change-name>（OpenCode/Cline/Cursor/Pi/Oh My Pi） | 查看 openspec/reports/ 中的报告 |

openspec-pw doctor 检查清单

openspec-pw doctor 在 10 个类别中验证前置条件，必需项失败时退出码非零。

| 类别 | 必需检查项 | 可选检查项 | |---|---|---| | Node.js | node 版本 | engines 兼容性（对比 package.json） | | npm | npm 可用性 | — | | Playwright 配置 | 配置文件存在（ts/js/mjs/mts） | — | | OpenSpec | 目录已初始化 | .spec.md 规范文件数量 | | Playwright 浏览器 | CLI 版本、Chromium 二进制已下载 | — | | Playwright 测试框架 | @playwright/test 已安装 | — | | Playwright MCP | 每个已授权（有命令工件）编辑器的 test-runner server 配置；未授权编辑器降为信息行（提示 init --tools 添加，不阻断） | playwright-cli（PATH 上的 @playwright/cli）——可选 ⚠，不阻断 | | Vendored Agents | — | 官方 agents 快照的存在与归属（owned/modified）；依赖的 playwright-test MCP 缺失时 ⚠（不阻断） | | Sync | 已初始化时标准同步（漂移 → openspec-pw update；AGENTS.md 无标记视为未初始化，恒 ok:true） | 未初始化（闸门，不阻断） | | 测试目录 | tests/playwright/ 目录存在 | auth.setup.ts 是否存在 | | 种子测试 | — | seed.spec.ts 是否存在 | | 应用服务器 | — | 开发脚本、基础 URL、可达性 | | CodeGraph | — | CLI 可用性、索引存在、MCP 安装（警告，不阻断） |

加 --json 参数输出机器可读格式。

认证配置

如果你的应用需要登录，配置一次凭证后，所有测试自动以已登录状态运行。

凭据自动忽略：init 和 update 会在 .gitignore 尾部维护一个标记块，忽略 tests/playwright/credentials.yaml、其 .bak 和 tests/playwright/test-results/——以及 auth storageState（playwright/.auth/，已登录会话 cookie）、MCP 配置（.mcp.json——用户自加的 server 常在 env/headers 里放 API key）、工具本地数据（.codegraph/、.playwright-mcp/）、第一层名如 .claude/、.cursor/、.codebuddy/、openspec/、AGENTS.md、CLAUDE.md、CODEBUDDY.md（生成的产物按设计留在本地）。标记块幂等、不碰你自己的规则，uninstall 时自动清理。无法写入时会降级为警告并列出未覆盖路径。注意：ignore 规则对已被 git 追踪的文件无效——若凭据曾提交过，请执行 git rm --cached tests/playwright/credentials.yaml。也可以改用 E2E_USERNAME / E2E_PASSWORD 环境变量。

# 1. 编辑凭证
vim tests/playwright/credentials.yaml

# 2. 设置环境变量
export [email protected]
export E2E_PASSWORD=your-password

# 3. 录制登录（一次性 — 打开浏览器，手动登录一次）
npx playwright test --project=setup

# 4. 后续所有测试自动复用登录状态
/opsx:e2e my-feature

支持 API 登录（推荐）和 UI 登录（备选）。多用户测试（管理员 vs 普通用户）在 credentials.yaml 中添加多个用户，运行 /opsx:e2e（OpenCode/Cline/Cursor/Pi/Oh My Pi 中用 /opsx-e2e；CodeBuddy CLI 用 /opsx:e2e 冒号形式）— 会从 specs 自动检测角色。

自定义

自定义 seed 测试

编辑 tests/playwright/seed.spec.ts 以匹配你的应用：

• 基础 URL
• 常用选择器
• Page Object 方法

认证凭证

编辑 tests/playwright/credentials.yaml：

• 设置登录 API 端点（或留空使用 UI 登录）
• 配置测试用户凭证
• 为角色测试添加多用户

架构

模板（内置于 npm 包，安装到 tests/playwright/）
  └── seed.spec.ts, auth.setup.ts, credentials.yaml, app-knowledge.md, pages/BasePage.ts

CLI (openspec-pw)
  ├── init       → 安装命令和模板
  ├── update     → 从 npm 同步命令和模板
  ├── migrate    → 迁移旧测试文件到新目录结构
  ├── audit      → 检查测试文件是否有孤儿文件和配置问题
  ├── coverage   → 分析 spec 与测试之间的覆盖率
  ├── flake      → 检测测试文件中的静态不稳定模式
  ├── doctor     → 检查前置条件
  ├── explore    → 探索应用路由
  └── uninstall  → 移除项目中的集成

编辑器（由 openspec-pw init 自动检测）
  ├── Claude Code (/opsx:e2e)
  │   ├── .claude/commands/opsx/e2e.md    → 命令文件（从 templates/e2e-command.md 安装）
  │   ├── playwright-test server         → Healer Agent 工具（通过 `claude mcp add --scope project playwright-test …`，写入项目根 `.mcp.json`）
  │   ├── .claude/agents/playwright-test-*.md → 官方 agents 快照（opt-in `--agents`）
  │   └── CLAUDE.md                       → CodeGraph 优先节 + 工作流提示 + 通过 `@AGENTS.md` 引入 AGENTS.md
  ├── OpenCode (/opsx-e2e)
  │   ├── .opencode/commands/opsx-e2e.md  → 命令文件（正文由 /opsx: 改写为 /opsx-）
  │   ├── opencode.jsonc                  → Playwright MCP (mcp["playwright-test"]) + 指令路由
  │   └── AGENTS.md                       → 员工级规范（单一数据源）
  ├── Cline (/opsx-e2e)
  │   ├── .cline/skills/opsx-e2e/SKILL.md → Skill 文件（正文由 /opsx: 改写为 /opsx-）
  │   ├── .cline/mcp.json                 → Playwright MCP (mcpServers["playwright-test"])
  │   └── AGENTS.md                       → 员工级规范（Cline 原生自动识别）
  ├── Cursor (/opsx-e2e)
  │   ├── .cursor/commands/opsx-e2e.md    → 斜杠命令（纯 MD，$1 = change 名）
  │   ├── .cursor/skills/opsx-e2e/SKILL.md → Skill（disable-model-invocation: true）
  │   ├── .cursor/mcp.json                → Playwright MCP (mcpServers["playwright-test"])
  │   └── AGENTS.md                       → 员工级规范（Cursor 原生自动识别）
  ├── Pi (/opsx-e2e)
  │   ├── .pi/prompts/opsx-e2e.md         → 提示词模板（文件名 = 命令名）
  │   └── AGENTS.md                       → 员工级规范（Pi 原生自动识别）
  │       （无 MCP 客户端 — 探索改用 `openspec-pw explore`）
  ├── Oh My Pi (/opsx-e2e)
      ├── .omp/commands/opsx-e2e.md       → 命令文件（name + description frontmatter）
      ├── .omp/mcp.json                   → Playwright MCP (mcpServers["playwright-test"])
      └── AGENTS.md                       → 员工级规范（omp 原生自动识别）
  └── CodeBuddy CLI (/opsx:e2e)
      ├── .codebuddy/commands/opsx/e2e.md → 命令文件（子目录冒号命名，无 `name` frontmatter）
      ├── .mcp.json                       → Playwright MCP (mcpServers["playwright-test"，项目根])
      └── CODEBUDDY.md                    → CodeGraph 优先节 + 工作流提示 + 通过 `@AGENTS.md` 引入 AGENTS.md

员工级规范统一存放在 **AGENTS.md** 中。Claude Code 通过 CLAUDE.md 加载——前置 CodeGraph 优先节与
OpenSpec 工作流提示，后接 `@AGENTS.md` 导入（Claude Code 官方记载的复用 AGENTS.md 机制，默认并不读取 AGENTS.md）。
导入位置无约束（官方原文 "anywhere in your CLAUDE.md"），唯一要求是 `@` 行不能放在反引号或代码块内。
导入行位于 OPENSPEC-PW:START/END 注释之外（注释在注入上下文前被剥离），marker 作为工具领地边界、
导入仍生效；OpenCode 在 `opencode.jsonc` 的 `instructions` 中注册 AGENTS.md；
Cline 与 Cursor 原生自动识别 `AGENTS.md`，无需包装文件。CodeBuddy CLI 加载方式与 Claude Code 相同——
thin CODEBUDDY.md wrapper，同样的 CodeGraph 块与 `@AGENTS.md` 导入（CodeBuddy 双文件并存时优先读 CODEBUDDY.md）。

> **与官方 `@fission-ai/openspec` CLI 共存**：官方 `openspec update` 内置「legacy 清理」，会删除根
> AGENTS.md/CLAUDE.md 中以普通 `OPENSPEC:START/END` 包裹的块（2026-08-28 曾因此误删本工具的规范块）。
> openspec-pw 的块使用专属 `OPENSPEC-PW:` 命名空间，官方匹配器不可见（已对照官方 v1.11.0 实测）。
> 本 change 之前安装的项目会在下次 `openspec-pw update`/`init` 时自动迁移标记；若块已被官方清掉，
> `openspec-pw update` 会黄色警告，跑 `openspec-pw init` 即可恢复。

测试资产 (tests/playwright/)
  ├── seed.spec.ts        → 环境验证
  ├── auth.setup.ts       → 会话录制
  ├── global.teardown.ts  → 测试后清理（可选）
  ├── credentials.yaml    → 测试用户
  ├── app-knowledge.md    → 项目级选择器模式（跨 change 复用）
  └── pages/BasePage.ts   → 共享页面对象基类

探索结果 (openspec/changes/<name>/specs/playwright/)
  ├── app-exploration.md → 本次 change 的路由 + 已验证选择器
  └── test-plan.md       → 本次 change 的测试用例

Healer Agent (playwright-test MCP server)
  └── browser_snapshot, browser_navigate, browser_run_code 等

许可

MIT