Skip to content

gstack-root.md

Latest commit

 

History

History
825 lines (670 loc) · 35.8 KB

gstack-root.md

File metadata and controls

825 lines (670 loc) · 35.8 KB
Raw

根级 SKILL.md（gstack 主入口）逐段中英对照注解

对应源文件：SKILL.md（872 行，自动从 SKILL.md.tmpl 生成） 本文逐段保留英文原文关键片段，加入中文翻译和设计原理解读。

一、Frontmatter（元数据区）

---
name: gstack
preamble-tier: 1
version: 1.1.0
description: |
  Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with
  elements, verify state, diff before/after, take annotated screenshots, test responsive
  layouts, forms, uploads, dialogs, and capture bug evidence. (gstack)
allowed-tools:
  - Bash
  - Read
  - AskUserQuestion
---

中文解读：

字段 值 含义
name gstack 技能名称，也是所有技能的生态命名空间
preamble-tier 1 最低级别（1-4），包含最精简的环境初始化
version 1.1.0 技能版本，与 VERSION 文件同步
allowed-tools Bash, Read, AskUserQuestion 刻意限制：只允许运行命令、读文件、提问

设计原理：为什么 preamble-tier 是 1？ 根 SKILL.md 是最基础的入口，负责浏览器 QA 测试。它不需要 tier 3/4 的完整 repo 模式检测、 Search Before Building 等重型上下文。Tier 1 让每次调用更快、更轻量。 而 /ship、/qa 等复杂技能用 tier 4，包含全量上下文。

为什么没有 Edit、Write、Glob、Grep？ 根 SKILL.md 的核心能力是浏览器 QA——导航、截图、断言。它不需要修改代码， 也不需要搜索代码库。只有 Bash（运行 $B 命令）、Read（读取截图结果）、 AskUserQuestion（交互确认）就够了。

二、Preamble 区（运行时初始化）

源文件第 19-93 行是一大段 Bash 脚本，在每次技能调用时首先运行。

2.1 更新检查与 Session 追踪

原文（第 22-26 行）：

_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || ...)
[ -n "$_UPD" ] && echo "$_UPD" || true
mkdir -p ~/.gstack/sessions
touch ~/.gstack/sessions/"$PPID"
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f | wc -l)

中文：

  • gstack-update-check：检查是否有新版本，若有则输出 UPGRADE_AVAILABLE <old> <new>
  • touch ~/.gstack/sessions/"$PPID"：以父进程 PID 为 key，记录本 session 存在
  • _SESSIONS：统计过去 2 小时内的活跃 session 数量（了解并发使用情况）

2.2 配置读取

原文（第 28-35 行）：

_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
_SKILL_PREFIX=$(~/.claude/skills/gstack/bin/gstack-config get skill_prefix 2>/dev/null || echo "false")
echo "PROACTIVE: $_PROACTIVE"
echo "SKILL_PREFIX: $_SKILL_PREFIX"

中文：

  • PROACTIVE：是否主动建议技能（默认 true）。用户可关闭，关闭后 AI 不主动触发技能
  • SKILL_PREFIX：是否为技能添加 gstack- 前缀（如 /gstack-qa 代替 /qa）
  • 所有配置存在 ~/.gstack/config.yaml，通过 gstack-config 读写

2.3 Repo 模式检测

原文（第 36-38 行）：

source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true
REPO_MODE=${REPO_MODE:-unknown}
echo "REPO_MODE: $REPO_MODE"

中文：gstack-repo-mode 脚本检测当前目录的类型，可能的值：

  • git：标准 git 仓库
  • monorepo：检测到 packages/ 或 apps/ 等 monorepo 结构
  • unknown：非 git 目录

2.4 Telemetry（遥测）

原文（第 41-60 行）：

_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true)
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
if [ "$_TEL" != "off" ]; then
  echo '{"skill":"gstack","ts":"...","repo":"..."}' >> ~/.gstack/analytics/skill-usage.jsonl
fi

中文：

  • _TEL_START + _SESSION_ID：用于后续计算技能执行时长
  • 数据写入 ~/.gstack/analytics/skill-usage.jsonl（本地 JSONL 格式）
  • 三种遥测级别：community（带稳定设备 ID）、anonymous（纯计数）、off（关闭）
  • 遥测只记录技能名、时长、结果，从不发送代码、路径、仓库名

2.5 Project Learnings（项目学习记录）

原文（第 62-72 行）：

eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE")
  if [ "$_LEARN_COUNT" -gt 5 ]; then
    ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 3
  fi
fi

中文：

  • gstack-slug：基于 repo 路径生成唯一项目标识符（如 myapp-abc123）
  • learnings.jsonl：存储该项目历史运行中发现的操作学习（如特殊的 build 顺序）
  • 超过 5 条时自动加载最近 3 条，帮助 AI "记住"项目特性

2.6 Routing 检测与 Vendoring 弃用警告

原文（第 76-90 行）：

_HAS_ROUTING="no"
if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md; then
  _HAS_ROUTING="yes"
fi
_VENDORED="no"
if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then
  _VENDORED="yes"
fi

中文：

  • HAS_ROUTING：检测项目的 CLAUDE.md 是否包含技能路由规则
  • VENDORED_GSTACK：检测项目是否有本地 vendored 的 gstack 副本（已弃用模式）

三、Preamble 行为逻辑（条件分支）

Preamble 读取上面的环境变量后，按以下逻辑触发各种一次性初始化流程：

┌─────────────────────────────────────────────────────────────────────┐
│                     Preamble 执行流程（按序判断）                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ① UPGRADE_AVAILABLE?  ──yes──▶ 读取 gstack-upgrade SKILL.md       │
│         │                       触发升级流程（内联 or 问用户）         │
│         no                                                          │
│         ▼                                                           │
│  ② SPAWNED_SESSION?    ──yes──▶ 跳过所有交互提示，专注完成任务       │
│         │                                                          │
│         no                                                          │
│         ▼                                                           │
│  ③ LAKE_INTRO=no?      ──yes──▶ 介绍 Boil the Lake 原则（一次性）   │
│         │                                                          │
│         no                                                          │
│         ▼                                                           │
│  ④ TEL_PROMPTED=no?    ──yes──▶ 询问遥测设置（一次性）              │
│         │                                                          │
│         no                                                          │
│         ▼                                                           │
│  ⑤ PROACTIVE_PROMPTED=no? ─yes─▶ 询问主动模式偏好（一次性）         │
│         │                                                          │
│         no                                                          │
│         ▼                                                           │
│  ⑥ HAS_ROUTING=no AND  ──yes──▶ 建议写入 CLAUDE.md 路由规则（一次性） │
│     ROUTING_DECLINED=false                                          │
│         │                                                          │
│         no                                                          │
│         ▼                                                           │
│  ⑦ VENDORED_GSTACK=yes? ──yes──▶ 警告 vendoring 已弃用，建议迁移   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

设计原理：一次性初始化的标记机制 每个"只运行一次"的流程都有对应的标记文件：

  • ~/.gstack/.completeness-intro-seen（Lake 原则）
  • ~/.gstack/.telemetry-prompted（遥测设置）
  • ~/.gstack/.proactive-prompted（主动模式设置）
  • ~/.gstack/.vendoring-warned-$SLUG（vendoring 警告，per-project）

这种设计避免了每次对话都重复问同样的问题，同时保证了首次使用的完整引导体验。

四、SPAWNED_SESSION（多智能体模式）

原文（第 251-256 行）：

If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an
AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option.
- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro.
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.

中文：当被 AI 编排器（如 OpenClaw）调用时，gstack 进入自动模式：

  • 不发起交互提问，自动选择推荐选项
  • 跳过所有首次初始化流程
  • 以文字报告结果而非交互式对话

这是 gstack 支持 AI 编排 AI 的关键设计——子 agent 可以无人值守地运行。

五、Voice（表达风格规范）

原文（第 260-264 行）：

Tone: direct, concrete, sharp, never corporate, never academic. Sound like a builder,
not a consultant. Name the file, the function, the command.
No em dashes. No AI vocabulary (delve, crucial, robust, comprehensive, nuanced...).
Short paragraphs. End with what to do.

中文：gstack 的表达风格要求：

  • 直接：说文件名、函数名、命令，不说"您可能需要考虑..."
  • 具体：不用破折号（em dash），不用 AI 套话（"深入探讨"、"全面分析"等）
  • 简短：短段落，以"下一步做什么"结尾

这是整个 gstack 生态系统的统一语气规范，所有技能都继承这个 Voice。

六、Completion Status Protocol（完成状态协议）

原文（第 268-289 行）：

- DONE — All steps completed successfully. Evidence provided for each claim.
- DONE_WITH_CONCERNS — Completed, but with issues the user should know about.
- BLOCKED — Cannot proceed. State what is blocking and what was tried.
- NEEDS_CONTEXT — Missing information required to continue.

中文：任何技能工作流结束时，必须以四种状态之一报告结果：

状态 含义 何时使用
DONE 所有步骤完成，有证据支撑 正常完成
DONE_WITH_CONCERNS 完成但有问题需关注 有警告但未阻断
BLOCKED 无法继续，说明原因 遇到阻碍无法绕过
NEEDS_CONTEXT 缺少必要信息 信息不足无法判断

3次尝试升级规则：尝试同一任务 3 次失败后，必须 STOP 并上报。 坏的结果比没有结果更糟——这是 gstack 的工程哲学。

七、Operational Self-Improvement（操作学习记录）

原文（第 291-307 行）：

Before completing, reflect on this session:
- Did any commands fail unexpectedly?
- Did you discover a project-specific quirk (build order, env vars, auth)?
- Did something take longer than expected?

If yes, log: gstack-learnings-log '{"skill":"...","type":"operational","key":"...","insight":"..."}'

中文：每次技能运行结束前，AI 需要反思本次运行：

  • 发现的项目特有规律（如特殊的环境变量、构建顺序）
  • 预期之外的失败
  • 导致超时的缺失配置

判断标准："知道这个能在未来省 5 分钟吗？" 能则记录，否则跳过。

这些 learnings 以 JSONL 格式存储在 ~/.gstack/projects/$SLUG/learnings.jsonl， 并在下次运行时被 Preamble 加载（见 2.5 节）。形成自我进化的工作循环。

八、Telemetry 收尾（运行最后）

原文（第 323-343 行）：

_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - _TEL_START ))
~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"SKILL_NAME","event":"completed",...}'
echo '{"skill":"SKILL_NAME","duration_s":"...","outcome":"...","browse":"..."}' >> ~/.gstack/analytics/skill-usage.jsonl

中文：每次技能完成后（无论成功/失败/中断）需要记录：

  • 技能名称（SKILL_NAME，替换为实际值）
  • 运行时长（秒）
  • 结果（success/error/abort/unknown）
  • 是否使用了 $B（browse 守护进程）

本地 JSONL 总是写入，远程上报仅当 telemetry 不是 off 且二进制存在时。

九、Plan Mode 安全操作

原文（第 347-359 行）：

When in plan mode, these operations are always allowed:
- $B commands (browse: screenshots, page inspection, navigation, snapshots)
- $D commands (design: mockups, variants, comparison boards)
- codex exec / codex review
- Writing to ~/.gstack/ (config, analytics, learnings)

中文：Plan Mode（计划模式）下，以下操作仍然允许：

  • 所有 $B（browse）命令——检查网站不修改代码
  • 设计相关的 $D 命令——生成视觉 mockup
  • 写入 ~/.gstack/——存储配置和分析数据，不影响项目代码

设计原理：Plan Mode 的本质是"只读于代码库"，但 gstack 认为"读取线上站点状态" 和"记录配置"属于计划工作的一部分，因此单独豁免。

十、Proactive Routing（主动路由）

原文（第 427-453 行）：

Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:
- User describes a new idea → invoke /office-hours
- User reports a bug → invoke /investigate
- User asks to test the site → invoke /qa
- User asks to ship, deploy → invoke /ship
...
Do NOT answer the user's question directly when a matching skill exists.

中文：当 PROACTIVE=true 时，AI 在识别到以下意图时必须直接调用对应技能：

用户意图                        → 调用技能
────────────────────────────────────────────────────
"有个新想法，值不值得做？"       → /office-hours
"策略评审，想更大"              → /plan-ceo-review
"审架构，锁定执行方案"          → /plan-eng-review
"设计系统，品牌规范"            → /design-consultation
"视觉审查，设计方案 review"     → /plan-design-review
"全部 review 自动完成"          → /autoplan
"有 bug，为什么坏了"            → /investigate
"测试网站，找 bug"              → /qa
"code review，检查 diff"        → /review
"视觉 polish，设计审计"         → /design-review
"ship，deploy，推代码"          → /ship
"更新文档"                      → /document-release
"周回顾"                        → /retro
"第二意见，codex review"        → /codex
"安全模式"                      → /careful 或 /guard
"升级 gstack"                   → /gstack-upgrade

关键规则：不要直接回答，当有匹配技能时必须调用技能。 技能提供结构化的多步工作流，质量远高于即兴回答。

十一、browse 守护进程（$B）完整参考

11.1 架构概述

┌──────────────────────────────────────────────────────────────────┐
│                      $B 架构                                      │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Claude (Bash tool)                                              │
│       │                                                         │
│       ▼  $B goto/snapshot/click...                              │
│  browse binary (~/.claude/skills/gstack/browse/dist/browse)     │
│       │  首次调用自动启动（~3s），后续 ~100-200ms                  │
│       ▼                                                         │
│  browse server (headless Chromium via Playwright)               │
│       │  状态持久（cookies、tabs、session）                       │
│       │  30分钟无操作后自动关闭                                   │
│       ▼                                                         │
│  Chromium Browser                                               │
│       └── Page 1（当前活跃 tab）                                 │
│       └── Page 2...                                              │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

11.2 启动前检查（SETUP）

原文（第 463-474 行）：

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/..."
[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
if [ -x "$B" ]; then echo "READY: $B"
else echo "NEEDS_SETUP"
fi

中文：$B 二进制的查找顺序：

  1. 项目本地 .claude/skills/gstack/browse/dist/browse（vendored 安装）
  2. 全局 ~/.claude/skills/gstack/browse/dist/browse（global 安装）

若输出 NEEDS_SETUP，需要先运行 ./setup（约 10 秒，一次性构建）。

11.3 导航命令（Navigation）

命令 说明 示例
$B goto <url> 跳转到 URL，等待页面加载 $B goto https://app.example.com
$B back 浏览器历史后退 $B back
$B forward 浏览器历史前进 $B forward
$B reload 刷新当前页面 $B reload
$B url 打印当前页面 URL $B url

使用时机：每次导航后需重新运行 snapshot 获取新的 @ref 引用。

11.4 Snapshot 系统（核心工具）

Snapshot 是理解页面结构和获取交互引用的主要工具。

原文（第 711-748 行）：

Syntax: $B snapshot [flags]
-i  --interactive      Interactive elements only (buttons, links, inputs) with @e refs
-c  --compact          Compact (no empty structural nodes)
-d <N>  --depth        Limit tree depth
-s <sel>  --selector   Scope to CSS selector
-D  --diff             Unified diff against previous snapshot
-a  --annotate         Annotated screenshot with red overlay boxes
-o <path>  --output    Output path for annotated screenshot
-C  --cursor-interactive  cursor-interactive elements (@c refs)

完整 Flag 对照表：

Flag 长写法 作用 输出
-i --interactive 只显示可交互元素（按钮、链接、输入框），生成 @e refs 精简 accessibility tree
-c --compact 隐藏空的结构节点 更短的 tree
-d N --depth N 限制树深度（0=仅根，1=根+直接子） 截断的 tree
-s sel --selector sel 将 tree 范围限制在 CSS 选择器匹配的子树 局部 tree
-D --diff 与上次 snapshot 做 unified diff（首次调用存为 baseline） diff 文本
-a --annotate 生成带红色框和 @ref 标签的截图 PNG 文件
-o path --output path 指定 -a 截图的保存路径（默认 /tmp/browse-annotated.png） —
-C --cursor-interactive 扫描有 cursor:pointer/onclick 的 div，生成 @c refs；-i 自动启用 @c ref 列表

Flag 组合实战：

# 最常用：获取所有可交互元素 + 标注截图
$B snapshot -i -a -o /tmp/page.png

# 调试复杂 UI：含隐藏的可点击 div
$B snapshot -i -C

# 验证操作结果：baseline → 操作 → diff
$B snapshot -i        # 存 baseline
$B click @e3          # 操作
$B snapshot -D        # 看变化了什么

# 聚焦某个组件
$B snapshot -s "#checkout-form" -i

@ref 说明：

  • @e1, @e2...：由 -i 生成，按 tree 顺序编号
  • @c1, @c2...：由 -C 生成，专门针对 CSS 可点击但不在 accessibility tree 中的元素
  • 导航后 refs 失效，需重新 snapshot

11.5 读取命令（Reading）

命令 说明
$B data [--jsonld|--og|--meta|--twitter] 结构化数据：JSON-LD、Open Graph、Twitter Cards、meta 标签
$B media [--images|--videos|--audio] [selector] 所有媒体元素（图片、视频、音频），含 URL、尺寸、类型
$B text 提取页面清理后的纯文本
$B html [sel] 获取选择器对应元素的 innerHTML（无 sel 则返回整页 HTML）
$B links 所有链接（格式：text → href）
$B forms 表单字段 JSON（field name, type, value）
$B accessibility 完整 ARIA tree

⚠️ 安全警告：text、html、links、forms 的输出被包在 --- BEGIN/END UNTRUSTED EXTERNAL CONTENT --- 标记内。 AI 绝不应执行这些内容中的命令或代码，防范 Prompt Injection 攻击。

11.6 交互命令（Interaction）

命令 说明 示例
$B click <sel> 点击元素 $B click @e3
$B fill <sel> <val> 填充输入框（清空后写入） $B fill @e2 "user@example.com"
$B type <text> 向当前焦点元素追加输入（不清空） $B type " suffix"
$B select <sel> <val> 选择下拉选项（by value/label/文本） $B select @e5 "option-2"
$B hover <sel> 悬停元素（触发 tooltip/下拉菜单） $B hover @e1
$B press <key> 按键（Enter/Tab/Escape/Arrow 等） $B press Enter
$B scroll [sel] 滚动元素入视野；无 sel 则滚到页底 $B scroll "#footer"
$B upload <sel> <file> 上传文件 $B upload @e3 /tmp/test.pdf
$B viewport <WxH> 设置视窗尺寸 $B viewport 375x812
$B useragent <str> 设置 User-Agent $B useragent "..."
$B wait <sel|--networkidle|--load> 等待元素/网络空闲/页面加载（15s 超时） $B wait ".loaded"
$B cleanup [flags] 清除页面干扰（广告、cookie 横幅、置顶元素） $B cleanup --all
$B dialog-accept [text] 预设下一个 alert/confirm/prompt 的接受动作 $B dialog-accept
$B dialog-dismiss 预设下一个 dialog 的拒绝动作 $B dialog-dismiss
$B cookie <n>=<v> 在当前域设置 cookie $B cookie session=abc123
$B cookie-import-browser [browser] 从真实浏览器导入 cookie（交互式选择） $B cookie-import-browser
$B header <name>:<value> 设置自定义请求头 $B header Authorization:Bearer xxx
$B style <sel> <prop> <val> 修改 CSS 属性（支持撤销） $B style ".nav" display none

fill vs type 的区别：

  • fill：清空输入框后写入新值，适合表单填写
  • type：向当前焦点处追加文本，适合触发 input 事件的场景

11.7 检查命令（Inspection）

命令 说明
$B console [--errors] 控制台消息（--errors 只看错误/警告）
$B network [--clear] 网络请求列表（检查失败的请求）
$B is <prop> <sel> 元素状态断言（见下表）
$B js <expr> 执行 JS 表达式，返回字符串结果
$B eval <file> 从文件运行 JS（路径须在 /tmp 或 cwd）
$B attrs <sel> 元素所有 HTML 属性（JSON 格式）
$B css <sel> <prop> 计算后的 CSS 属性值
$B cookies 所有 cookies（JSON 格式）
$B storage [set k v] 读/写 localStorage + sessionStorage
$B dialog [--clear] 查看 dialog 消息历史
$B inspect [sel] 深度 CSS 检查（完整规则级联、盒模型，via CDP）
$B perf 页面加载性能指标（TTFB、DOMContentLoaded、Load 等）

is 命令支持的属性：

属性 含义
visible 元素可见（非 hidden/opacity:0）
hidden 元素不可见
enabled 元素未被禁用
disabled 元素被禁用（disabled 属性）
checked checkbox/radio 已选中
editable 输入框可编辑（非 readonly）
focused 元素当前拥有焦点

11.7.5 提取命令（Extraction）

原文：

### Extraction
| Command | Description |
|---------|-------------|
| `archive [path]` | Save complete page as MHTML via CDP |
| `download <url|@ref> [path] [--base64]` | Download URL or media element to disk using browser cookies |
| `scrape <images|videos|media> [--selector sel] [--dir path] [--limit N]` | Bulk download all media from page. Writes manifest.json |

中文：

命令 说明
$B archive [path] 用 CDP 将完整页面（HTML + 资源）保存为 MHTML 单文件
$B download <url|@ref> [path] [--base64] 使用浏览器 cookies 下载 URL 或媒体元素到磁盘
$B scrape <images|videos|media> [--selector sel] [--dir path] [--limit N] 批量下载页面全部媒体文件，完成后写入 manifest.json

设计解读：Extraction 命令是真正将页面内容写入磁盘的命令，与 data/media（只返回文本数据）形成对比。

  • archive：MHTML 格式将整个页面（含内联资源）打包为单文件，使用 Chrome DevTools Protocol 捕获，保真度高于 wget 镜像。
  • download：复用浏览器当前的 session cookies，解决需要认证才能访问的资源的下载问题；--base64 选项支持内嵌 data: URI 的输出。
  • scrape：批量下载场景，--limit 防止无限下载，manifest.json 记录原始 URL → 本地路径的映射，便于后续处理。
# 典型用法
$B archive /tmp/page.mhtml                      # 存档整页
$B download @e5 /tmp/video.mp4                  # 下载 @ref 引用的视频
$B download https://cdn.example.com/img.png /tmp/ # 带 cookie 下载受保护图片
$B scrape images --dir /tmp/imgs --limit 50     # 批量下载前 50 张图片
$B scrape media --selector ".gallery"           # 只抓 .gallery 内所有媒体

11.8 视觉命令（Visual）

命令 说明 示例
$B screenshot [opts] [path] 保存截图（支持元素裁剪、区域裁剪、仅视窗） $B screenshot /tmp/page.png
$B responsive [prefix] 三端截图（375x812/768x1024/1280x720） $B responsive /tmp/layout
$B diff <url1> <url2> 两个页面的文本 diff $B diff https://staging.app.com https://prod.app.com
$B pdf [path] 保存为 PDF $B pdf /tmp/report.pdf
$B prettyscreenshot [opts] 清洁截图（自动清除干扰元素） $B prettyscreenshot /tmp/clean.png

screenshot 完整选项：

$B screenshot /tmp/page.png              # 整页截图（含滚动区域）
$B screenshot --viewport /tmp/page.png   # 仅视窗（不含滚动）
$B screenshot --clip 0,0,800,600 /tmp/p  # 裁剪区域（x,y,w,h）
$B screenshot "#hero-banner" /tmp/hero   # 元素截图（CSS 选择器）
$B screenshot @e3 /tmp/btn.png           # 元素截图（@ref）

11.9 Meta 命令（元操作）

命令 说明
$B chain 从 stdin 读取 JSON 数组批量执行命令（减少 CLI 开销）
$B frame <sel|@ref|--name|--url|main> 切换到 iframe 上下文（main 返回主框架）
$B inbox [--clear] 查看 sidebar scout 的收件箱消息
$B watch [stop] 被动观察模式——周期性截图，用户浏览时监控

chain 命令示例（长流程最高效的方式）：

echo '[
  ["goto","https://app.example.com"],
  ["snapshot","-i"],
  ["fill","@e3","user@test.com"],
  ["fill","@e4","password123"],
  ["click","@e5"],
  ["snapshot","-D"],
  ["screenshot","/tmp/result.png"]
]' | $B chain

11.10 Tabs 命令（多标签）

命令 说明
$B tabs 列出所有打开的 tab（id + url）
$B tab <id> 切换到指定 tab
$B newtab [url] 打开新 tab（可选直接导航到 url）
$B closetab [id] 关闭 tab（无 id 则关闭当前）

11.11 Server 命令（服务器管理）

命令 说明
$B status 健康检查
$B restart 重启 browse server
$B stop 关闭 server
$B connect 启动有头 Chromium + Chrome 扩展
$B disconnect 断开有头浏览器，返回无头模式
$B focus [@ref] 将有头浏览器窗口提到前台（macOS）
$B handoff [message] 在当前页面打开可见 Chrome，交给用户接管
$B resume 用户接管后重新获取控制权
$B state save|load <name> 保存/加载浏览器状态（cookies + URL）

十二、QA 标准食谱（Standard Recipes）

12.1 测试用户登录流程

# 1. 导航到登录页
$B goto https://app.example.com/login

# 2. 获取表单结构和可交互元素
$B snapshot -i

# 3. 用环境变量填写凭证（安全实践）
$B fill @e3 "$TEST_EMAIL"
$B fill @e4 "$TEST_PASSWORD"
$B click @e5

# 4. 验证登录结果
$B snapshot -D              # diff 显示登录后页面变化
$B is visible ".dashboard"  # 断言 dashboard 出现
$B screenshot /tmp/after-login.png

⚠️ 凭证安全：永远用环境变量 $TEST_EMAIL、$TEST_PASSWORD， 不要在命令行硬编码密码。

12.2 验证生产部署

$B goto https://yourapp.com
$B text                          # 页面是否正常加载？
$B console                       # 有无 JS 错误？
$B network                       # 有无请求失败？
$B js "document.title"           # 标题是否正确？
$B is visible ".hero-section"    # 关键元素是否存在？
$B screenshot /tmp/prod-check.png

12.3 端到端功能 Dogfood

# 导航到新功能
$B goto https://app.example.com/new-feature

# 获取标注截图（bug report 用）
$B snapshot -i -a -o /tmp/feature-annotated.png

# 找所有可点击的 div（复杂 UI 必备）
$B snapshot -C

# 交互 + Diff 验证
$B snapshot -i               # 存 baseline
$B click @e3                 # 触发操作
$B snapshot -D               # 看变化

# 检查状态
$B is visible ".success-toast"
$B is enabled "#next-step-btn"

# 检查 JS 错误
$B console

12.4 响应式布局测试

$B goto https://yourapp.com
$B responsive /tmp/layout    # 自动生成 mobile/tablet/desktop 三张截图
# 输出：/tmp/layout-mobile.png, layout-tablet.png, layout-desktop.png

12.5 表单验证测试

# 1. 空提交，检查验证错误
$B goto https://app.example.com/form
$B snapshot -i
$B click @e10                # 提交按钮
$B snapshot -D               # 错误信息出现了吗？
$B is visible ".error-message"

# 2. 正确填写，验证成功状态
$B fill @e3 "valid input"
$B click @e10
$B snapshot -D               # 错误消失，出现成功状态

十三、gstack 生态技能全览

根级 SKILL.md 是所有 gstack 技能的公共基础层，提供：

  1. Preamble 逻辑（所有技能共用的初始化框架）
  2. $B 命令参考（所有用到浏览器的技能都遵循这套 API）
  3. Voice 规范（所有技能统一的表达风格）
  4. Completion Protocol（所有技能统一的完成状态报告）

在这个基础上运行的技能生态：

gstack 生态
│
├── 代码质量
│   ├── /review          ─── PR 预合并检查（diff 分析）
│   ├── /investigate     ─── 系统性 debug（四阶段方法论）
│   └── /codex           ─── Codex CLI 第二意见
│
├── 测试与 QA（重度使用 $B）
│   ├── /qa              ─── 系统性 QA + 自动修复 bug
│   ├── /qa-only         ─── 纯 QA 报告（不修复）
│   ├── /benchmark       ─── 性能基准测试
│   └── /canary          ─── 部署后金丝雀监控
│
├── 发布流程
│   ├── /ship            ─── 完整 ship 工作流（测试→版本→PR）
│   ├── /land-and-deploy ─── 合并 PR + 等待部署 + canary 验证
│   └── /document-release ── 发布后文档更新
│
├── 方案评审
│   ├── /office-hours    ─── YC 式创业/Builder 想法审查
│   ├── /plan-ceo-review ─── CEO 角色范围策略评审
│   ├── /plan-eng-review ─── 工程经理架构评审
│   ├── /plan-design-review ─ 设计师视角 UI/UX 评审
│   ├── /plan-devex-review ── 开发者体验评审
│   └── /autoplan        ─── 自动运行全套评审
│
├── 设计
│   ├── /design-consultation ─ 创建设计系统 + DESIGN.md
│   ├── /design-review   ─── 视觉 QA（找问题 + 修复）
│   └── /design-html     ─── HTML 页面生成
│
├── 团队协作
│   ├── /retro           ─── 周回顾
│   ├── /health          ─── 代码库健康检查
│   └── /checkpoint      ─── 保存/恢复工作状态
│
└── 工具管理
    ├── /gstack-upgrade  ─── 升级 gstack
    ├── /freeze / /unfreeze ─ 限制/释放编辑范围
    ├── /careful / /guard ─── 危险操作安全护栏
    └── /setup-browser-cookies ─ 导入浏览器 cookies

十四、根 SKILL.md 与 /browse 技能的关系

维度 根 SKILL.md /browse 技能
定位 gstack 主入口 + 完整 API 参考 浏览器使用的快速指南
内容 Preamble 逻辑、所有命令、所有 QA 食谱 场景化使用示例、核心提示
Preamble Tier 1（最轻量） —
谁调用它 用户直接用 /gstack 或其他技能间接引用 用户需要浏览器帮助时
命令文档完整性 完整（所有 flag、所有命令） 精选最常用场景

实践建议：需要查命令语法时看根 SKILL.md；需要了解某个使用场景时看 /browse 技能。 其他技能（/qa、/design-review 等）内部都参考根 SKILL.md 的 $B 命令规范。

十五、关键设计决策总结

决策 原因
根 SKILL.md 用 preamble-tier 1 最轻量的初始化，适合频繁调用的基础技能
$B 是编译后的二进制（非 npm 脚本） 启动后每次调用 ~100ms，比 Node.js 脚本快很多
状态持久（cookies/tabs 跨调用） 测试完整用户流程（登录→操作→验证）不需要每步重新认证
不信任页面内容（UNTRUSTED 标记） 防范 Prompt Injection——页面可能包含恶意指令
Snapshot 系统（@e refs） 比 CSS 选择器更稳定：不依赖具体类名，按可访问性树编号
chain 命令 批量执行减少 Bash tool 调用次数，提升长流程效率
~/.gstack/ 存储所有状态 与项目代码库隔离，升级/卸载不影响项目文件