gstack 原理与入门使用指南-程序员充电站

gstack 原理与入门使用指南

一、gstack 是什么

gstack 是一个面向 AI 辅助开发的工程化工作流框架。它将 Claude Code 等 AI 编码助手的能力从"对话式编程"提升到"结构化工程实践"，通过一套模块化 Skill 系统和自动化浏览器测试能力，覆盖从需求分析、架构设计、编码实现到 QA 验证、安全审计、部署上线的完整软件交付链路。

二、核心架构原理

2.1 Skill 路由系统

gstack 采用"意图识别 → Skill 路由 → 专业工作流"的三层架构：

用户请求 → 意图模式匹配 → 路由到对应 Skill → 执行专业工作流

每个 Skill 是独立的工作流模块，包含完整的步骤定义、检查清单和质量门禁。例如：

/office-hours— 产品创意评审与可行性分析
/plan-ceo-review— 战略范围与目标对齐
/plan-eng-review— 架构方案与技术选型评审
/review— 代码变更审查
/qa— 端到端功能验证
/investigate— Bug 根因分析
/ship— PR 创建与部署

这种设计的关键优势在于关注点分离：每个 Skill 只解决一类问题，拥有专用的检查清单和退出条件，避免了通用 AI 助手的"上下文漂移"问题。

2.2 CDP 浏览器自动化 (browse)

browse是 gstack 的持久化浏览器自动化组件，基于 Chrome DevTools Protocol (CDP) 实现。其核心设计原则如下：

持久化会话模型

与传统的 Selenium/Playwright 脚本不同，browse 维护一个长驻的 Chromium 实例：

首次调用：启动 headless Chromium（约 3 秒）
后续调用：通过 loopback HTTP 与已有实例通信（100-200ms/次）
状态保持：Cookie、localStorage、登录态在调用间持久化
自动回收：30 分钟空闲后自动关闭

这意味着你可以像操作本地变量一样操作浏览器状态：

# 导航一次，多次查询$Bgoto https://app.example.com/login$Bsnapshot-i# 查看交互元素$Bfill @e3"user"# 填充表单$Bclick @e5# 点击提交$Bsnapshot-D# 差异对比，验证跳转结果

快照系统 (Snapshot System)

快照是 browse 的核心交互原语。它将页面的无障碍树 (Accessibility Tree) 转换为带引用的文本表示：

@e1 [heading] "Welcome" [level=1] @e2 [textbox] "Email" @e3 [button] "Submit"

每个交互元素被分配一个@eN引用，后续命令可直接使用引用操作元素，无需手写 CSS 选择器。这解决了传统 UI 测试中"选择器脆弱"的根本问题——引用由浏览器引擎动态分配，与 DOM 结构解耦。

常用快照模式：

标志	作用
`-i`	仅交互元素（按钮、链接、输入框）
`-D`	与前次快照的差异对比（统一 diff 格式）
`-a -o path`	标注截图（红框 + 引用标签覆盖）
`-C`	捕获光标交互元素（带`cursor:pointer`的 div）

CDP 安全模型

browse 对 CDP 方法访问实施了严格的白名单机制：

白名单过滤：仅cdp-allowlist.ts中声明的方法可调用
作用域隔离：方法按 tab 级或 browser 级分类
输出标记：数据外泄类方法（如Network.getResponseBody）的输出被标记为不可信

这确保了 AI 代理在执行自动化操作时不会意外调用危险 CDP 方法。

2.3 配置与遥测

gstack-config 提供统一的配置管理：

gstack-configsetproactivetrue# 主动 Skill 建议gstack-configsetcheckpoint_mode continuous# 持续检查点自动提交gstack-configsetexplain_level terse# 精简输出模式gstack-configsettelemetry community# 遥测开关

三、入门使用

3.1 环境准备

gstack 以 Skill 形式集成到 Claude Code 中，安装后即可使用：

# 检查 browse 是否就绪_ROOT=$(gitrev-parse --show-toplevel2>/dev/null||echo"")B=""[-n"$_ROOT"]&&[-x"$_ROOT/.claude/skills/gstack/browse/dist/browse"]&&B="$_ROOT/.claude/skills/gstack/browse/dist/browse"[-z"$B"]&&B="$HOME/.claude/skills/gstack/browse/dist/browse"[-x"$B"]&&echo"READY"||echo"NEEDS_SETUP"

如需首次构建，在 skill 目录下执行./setup（约 10 秒）。

3.2 第一个浏览自动化脚本

# 设置 browse 路径exportB="$HOME/.claude/skills/gstack/browse/dist/browse"# 1. 打开目标页面$Bgoto https://example.com# 2. 查看页面文本内容$Btext# 3. 检查是否有 JavaScript 错误$Bconsole# 4. 检查网络请求$Bnetwork# 5. 截图留存$Bscreenshot /tmp/example.png

3.3 表单自动化示例

以下是一个完整的登录流程测试：

exportB="$HOME/.claude/skills/gstack/browse/dist/browse"# 导航到登录页$Bgoto https://app.example.com/login# 查看交互元素$Bsnapshot-i# 输出示例:# @e1 [textbox] "Email"# @e2 [textbox] "Password"# @e3 [button] "Sign In"# 填写表单$Bfill @e1"test@example.com"$Bfill @e2"password123"# 提交$Bclick @e3# 验证结果——使用 diff 快照$Bsnapshot-D# 断言仪表盘元素出现$Bis visible".dashboard"# 截图证据$Bscreenshot /tmp/login-success.png

3.4 快照差异验证

snapshot -D是 gstack QA 工作流中最有用的工具之一。它自动维护一个基准快照，并在每次调用时输出统一 diff：

# 第一次调用：存储基准$Bsnapshot-D# → 返回完整快照树# 执行操作$Bclick @e5# 第二次调用：输出差异$Bsnapshot-D# + @e12 [div] "Success" ← 新增元素# - @e8 [spinner] "Loading" ← 移除元素

这使得"操作前后页面发生了什么变化"一目了然，无需人工比对截图。

3.5 响应式测试

exportB="$HOME/.claude/skills/gstack/browse/dist/browse"$Bgoto https://your-app.com# 一键生成三个视口截图$Bresponsive /tmp/layout# → layout-mobile.png (375x812)# → layout-tablet.png (768x1024)# → layout-desktop.png (1280x720)# 或手动指定视口$Bviewport 375x812$Bscreenshot /tmp/iphone.png

3.6 Headed 模式（可视化调试）

当需要人工观察浏览器行为时，切换到 headed 模式：

exportB="$HOME/.claude/skills/gstack/browse/dist/browse"$Bconnect# 启动带扩展的可见 Chromium# 执行操作...$Bdisconnect# 返回 headless 模式

在 headed 模式下，你还可以：

使用$B handoff将控制权临时交还给用户
使用$B resume在用户操作完成后恢复自动化
使用$B focus将浏览器窗口置顶（macOS）

四、最佳实践

4.1 导航一次，查询多次

goto是相对昂贵的操作（加载页面、执行 JS、等待网络）。导航后，text、js、snapshot、screenshot等命令都是毫秒级的内存操作：

$Bgoto https://app.com# ~2s$Bsnapshot-i# ~100ms$Bconsole# ~100ms$Bnetwork# ~100ms

4.2 使用引用而非 CSS 选择器

虽然 browse 支持 CSS 选择器，但@eN引用更可靠：

# 不推荐——选择器可能因 UI 更新而失效$Bfill"input[name='email']""test@example.com"# 推荐——引用由引擎动态分配$Bsnapshot-i$Bfill @e2"test@example.com"

4.3 敏感数据使用环境变量

不要在命令中硬编码凭据：

# 不推荐$Bfill @e2"MyP@ssw0rd!"# 推荐exportTEST_PASSWORD="..."$Bfill @e2"$TEST_PASSWORD"

4.4 使用 chain 执行长流程

对于多步骤操作，chain命令比逐条执行更高效：

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

单次chain调用避免了每步的进程启动开销，整个流程在同一个浏览器会话中完成。