# gstack 项目详细文档

> **注意：这不是一个实施计划，而是用户要求的项目分析文档。**

---

## 一、项目概述

**gstack** 是由 Y Combinator 总裁兼 CEO Garry Tan 开源的 **AI 工程工作流系统**，构建在 Claude Code 之上。它将 Claude Code 从一个通用 AI 编程助手，转变为一个拥有 **15 个专业角色**的虚拟工程团队——CEO、工程经理、设计师、QA 主管、发布工程师等，全部通过斜杠命令（slash commands）调用。

**核心理念：** 用结构化的角色分工取代泛化的 AI 对话。每个 skill 都是一套完整的方法论，有明确的输入、输出和流程。

**关键数据：**
- MIT 开源协议，完全免费
- 作者声称使用 gstack 每天可产出 10,000-20,000 行可用代码
- 60 天内产出 600,000+ 行代码（35% 为测试代码）
- 效率压缩比：模板代码 ~100x、测试 ~50x、功能开发 ~30x、Bug 修复 ~20x
- 当前版本 v0.6.4（2026 年 3 月）

---

## 二、核心架构

### 2.1 整体架构图

```
用户 → Claude Code → /skill 命令 → SKILL.md prompt → AI Agent 执行
                         ↓
                    browse 二进制 → HTTP 请求 → Bun 服务器 → Chromium 浏览器（持久守护进程）
```

gstack 由两大核心组件构成：

1. **Skill 系统**：15 个 Markdown 格式的 prompt 模板，每个代表一个专业角色
2. **Browse 浏览器引擎**：基于 Playwright 的无头浏览器守护进程，提供 ~50 个命令

### 2.2 Browse 浏览器守护进程

这是 gstack 的"秘密武器"。与每次调用都启动新浏览器不同，gstack 维护一个**持久运行的 Chromium 守护进程**：

- **首次调用 ~3 秒**启动，后续调用 **~100-200ms**
- Cookie、登录态、localStorage **跨命令持久保存**
- 30 分钟空闲自动关闭，节省资源
- 本地 HTTP 服务器 + Bearer Token 认证，安全隔离

**技术栈：**
- Bun 运行时，编译为 ~58MB 独立二进制
- Playwright 控制 Chromium
- 随机端口（10000-60000），支持多工作区并行

### 2.3 Ref 引用系统（非 CSS 选择器）

gstack 不使用脆弱的 CSS 选择器操作页面元素，而是基于**无障碍树（Accessibility Tree）**建立引用：

```
snapshot 命令输出：
  @e1 [heading] "Welcome" [level=1]
  @e2 [textbox] "Email"
  @e3 [button] "Submit"

后续操作：
  click @e3    → 点击 Submit 按钮
  fill @e2 "test@example.com"  → 填写邮箱
```

- `@e1`, `@e2` 等是基于 Playwright Locator 的稳定引用，不需要修改 DOM
- 不会触发 CSP（Content Security Policy）问题
- 支持 SPA 过期检测

### 2.4 模板生成系统

SKILL.md 文件不是手写的，而是由 `.tmpl` 模板 + `gen-skill-docs.ts` 脚本**自动生成**的：

```
SKILL.md.tmpl （手工编写的模板）
    ↓  gen-skill-docs.ts 读取源码元数据
SKILL.md （自动生成，提交到 Git）
```

10 个模板变量从源码中提取真实数据：
- `{{COMMAND_REFERENCE}}` → 从 `commands.ts` 生成命令表
- `{{SNAPSHOT_FLAGS}}` → 从 `snapshot.ts` 生成快照标志
- `{{PREAMBLE}}` → 通用前置段（升级检查、会话追踪）
- `{{QA_METHODOLOGY}}` → 共享的 QA 测试方法论
- `{{DESIGN_METHODOLOGY}}` → 共享的设计审查方法论
- 等等...

这确保了**文档永远与代码同步**。

---

## 三、15 个 AI 专业技能（Skills）

### 3.1 规划阶段（Plan Review）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/plan-ceo-review` | CEO/创始人 | 重新审视问题本质，寻找 10 倍产品机会。4 种模式：扩展、选择性扩展、保持范围、缩减范围 |
| `/plan-eng-review` | 工程经理 | 锁定架构、数据流、测试计划。每次只抛出一个问题，交互式审查 |
| `/plan-design-review` | 高级设计师 | 交互式设计审查（每个维度 0-10 评分），逐项修复至满分 |
| `/design-consultation` | 设计合伙人 | 从零构建完整设计系统，输出 DESIGN.md 和 HTML 预览页 |

**CEO 审查的 4 种模式**特别值得关注：
- **EXPANSION（扩展）**：放大思考，寻找 10 倍机会，需要用户明确同意
- **SELECTIVE EXPANSION（选择性扩展）**：保持范围，逐项提议扩展供用户选择
- **HOLD SCOPE（保持范围）**：最大严谨度，加固现有计划
- **SCOPE REDUCTION（缩减范围）**：无情削减到最小可行产品

### 3.2 测试与修复阶段（QA & Fix）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/qa` | QA 主管 + 修复者 | 系统化测试应用并修复发现的 Bug，生成回归测试 |
| `/qa-only` | QA 报告员 | 仅测试和报告，**绝不修改代码** |
| `/design-review` | 设计师 + 编码者 | 对线上网站做设计审查，然后逐项修复 CSS/HTML |
| `/browse` | QA 工程师 | 底层浏览器操作，~50 个命令 |

`/qa` 的工作流程：
1. 分析 git diff 确定测试范围
2. 系统化浏览每个页面并截图
3. 交互测试（表单填写、按钮点击、边界测试）
4. 发现 Bug → 修复 → 原子化提交（`test(qa): ...`）
5. 自动生成回归测试
6. 输出详细报告，含前后对比截图

### 3.3 发布阶段（Ship & Post-Ship）

| 命令 | 角色 | 功能 |
|------|------|------|
| `/review` | Staff 工程师 | PR 代码审查：SQL 安全、竞态条件、LLM 信任边界、枚举完整性 |
| `/ship` | 发布工程师 | 全自动发布流程：测试→覆盖率→审查→版本号→CHANGELOG→提交→推送→创建 PR |
| `/document-release` | 技术写手 | 发布后文档更新：README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md |
| `/retro` | 工程经理 | 周回顾：提交统计、测试健康度、工作模式分析 |

**`/ship` 是最复杂的 skill（165KB 模板），实现完全自动化发布：**
1. Pre-flight 检查（分支状态、未提交变更）
2. 合并基础分支（自动解决简单冲突）
3. 运行测试（Rails + Vitest 并行）
4. **测试覆盖率审计**（ASCII 图表展示代码路径覆盖）
5. **Pre-landing 代码审查**（调用 `/review` 工作流）
6. 版本号自动递增
7. CHANGELOG 自动生成
8. TODOS.md 自动更新
9. Bisect 提交（每个提交一个逻辑变更）
10. 推送并创建 PR（包含完整的审查报告）

### 3.4 辅助工具

| 命令 | 功能 |
|------|------|
| `/setup-browser-cookies` | 从 Chrome/Arc/Brave/Edge 导入 Cookie 到无头浏览器 |
| `/gstack-upgrade` | 检查和安装 gstack 更新 |

---

## 四、AI 能力深度解析

### 4.1 AI 作为虚拟团队

gstack 的核心创新在于**将不同的 AI prompt 策略映射为不同的专业角色**。每个角色内嵌了该领域大师的思维框架：

**CEO 模式内嵌的思维框架：**
- Bezos（单向门决策、Day 1 思维）
- Andy Grove（偏执危机感）
- Charlie Munger（逆向思维）
- Ben Horowitz（战时 CEO 意识）
- Chesky/Graham（创始人模式）
- Sam Altman（杠杆偏执）

**工程经理模式：**
- Will Larson（团队状态诊断）
- Tanya Reilly（boring by default）
- Fred Brooks（本质 vs 偶然复杂性）
- Kent Beck（让变更变得容易）

**设计师模式：**
- Dieter Rams（减法优先）
- Don Norman（设计的三个层次）
- Julie Zhuo（有原则的品味）
- Jony Ive（关怀是可见的）

这不是简单的 checklist——它通过"潜在空间激活"让 LLM 内化这些框架，使每次审查都成为一次真正的视角转换。

### 4.2 AI 驱动的浏览器自动化

gstack 让 AI Agent 能够**直接操作真实浏览器**，这远超传统的代码分析能力：

**~50 个浏览器命令分类：**

| 类别 | 命令示例 | 用途 |
|------|---------|------|
| 导航 | `goto`, `back`, `forward`, `reload` | 页面跳转 |
| 读取 | `text`, `html`, `links`, `forms`, `accessibility`, `console`, `network` | 提取页面信息 |
| 交互 | `click`, `fill`, `select`, `hover`, `type`, `press`, `scroll` | 模拟用户操作 |
| 视觉 | `screenshot`, `responsive`, `diff`, `pdf` | 截图/对比/响应式测试 |
| 检查 | `is`（visible/hidden/enabled/checked）, `cookies`, `storage`, `perf` | 状态断言 |
| 标签页 | `tabs`, `tab`, `newtab`, `closetab` | 多标签管理 |

**关键能力：**
- `snapshot -i` — 仅交互元素的无障碍树快照，让 AI 快速理解页面结构
- `responsive` — 一键在手机/平板/桌面三种视口下截图
- `diff` — 对比两次快照的差异（SPA 状态变化检测）
- `chain` — JSON 格式批量执行命令，减少往返次数
- `cookie-import-browser` — 从本地浏览器导入认证 Cookie，测试登录后页面

### 4.3 三层 AI 评估管道

gstack 拥有一套**用 AI 测试 AI 的完整评估体系**：

#### Tier 1：静态验证（免费，<1 秒）
- 验证 SKILL.md 中所有 `$B` 命令语法正确
- 检查 snapshot 标志合法性
- 确保生成文件与模板同步

#### Tier 2：端到端评估（~$3.85/运行）
- 通过 `claude -p` 子进程**完整运行 AI Agent 工作流**
- 实时流式输出 NDJSON 格式的工具调用
- 使用"植入 Bug"（planted bugs）的方式测试 QA 技能的 Bug 检出率
- 自动记录成本（美元）、token 用量、工具调用次数

#### Tier 3：LLM-as-Judge（~$0.15/运行）
- 使用 claude-sonnet-4-6 模型评估文档质量
- 三个评分维度：**清晰度、完整性、可操作性**（1-5 分）
- 对于 planted-bug 测试，评估：**检出率、误报数、证据质量**

#### 智能差异化测试选择
- 每个测试声明自己依赖的文件（touchfiles）
- 只运行受 `git diff` 影响的测试
- 全局 touchfile 变更（如 session-runner.ts）触发全量测试
- 大幅降低 CI 成本

### 4.4 完整性原则（Completeness Principle）

gstack 的核心哲学之一——贯穿所有 skill：

> 当 AI 辅助编码将实施时间压缩 10-100 倍时，始终推荐完整方案。边际成本几乎为零时，不要走捷径。

体现在：
- 计划审查会标记偷工减料的实现
- 全程展示双时间估算（人工团队时间 vs CC+gstack 时间）
- 测试覆盖率和边界情况默认追求完整
- 被推迟的工作会明确写入 TODOS.md

### 4.5 AI Slop（AI 垃圾风格）检测

设计审查中内置了**AI 生成内容的垃圾风格检测**：
- 紫色渐变背景
- 千篇一律的三栏布局
- 泛化的营销文案
- 过度使用的设计模式

这帮助团队避免 AI 生成的内容看起来像"AI 做的"。

### 4.6 交互式 AI 审查

所有审查 skill 都采用**结构化交互**模式：
- 每次只提出一个问题（绝不批量提问）
- 每个问题都有明确的上下文（项目名、分支名、当前步骤）
- 提供推荐选项并说明原因
- 通常只给 2-3 个选择，避免决策疲劳

---

## 五、安装与使用

### 5.1 安装（约 30 秒）

```bash
# 全局安装
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

# 可选：为项目团队本地安装
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
rm -rf .claude/skills/gstack/.git
cd .claude/skills/gstack && ./setup
```

`setup` 脚本会：
1. 构建 browse 二进制（如需要）
2. 安装 Playwright Chromium
3. 创建 `~/.gstack` 全局状态目录
4. 建立技能符号链接

### 5.2 日常使用示例

一个完整的功能开发流程：

```
你：    我想给卖家添加照片上传功能。
你：    /plan-ceo-review
Claude: [提出 8 个扩展提议，附带努力/影响评估]

你：    /plan-design-review
Claude: 设计评分: B | AI Slop 评分: C
        [80 项设计审查，逐项修复至满分]

你：    /plan-eng-review
Claude: [架构图、测试矩阵、错误路径分析]

你：    [批准计划] → Claude 在 11 个文件中写入 2,400 行代码

你：    /review
Claude: [自动修复] 2 个问题 | [询问] 1 个竞态条件

你：    /qa https://staging.myapp.com
Claude: [发现并修复预览清除 Bug]
        [自动生成回归测试]

你：    /ship
Claude: 测试: 42 → 51 (+9 新增)
        覆盖率: 14/14 代码路径 (100%)
        PR: github.com/you/app/pull/42
```

**一个功能。七个命令。一整个虚拟团队。**

### 5.3 开发与测试命令

```bash
bun install              # 安装依赖
bun test                 # 免费测试（浏览器 + 快照 + 技能验证）
bun run test:evals       # 付费评估：LLM 判官 + 端到端
bun run test:e2e         # 仅端到端测试
bun run eval:select      # 预览差异化测试会选中哪些测试
bun run dev <cmd>        # 开发模式运行 CLI
bun run build            # 生成文档 + 编译二进制
bun run gen:skill-docs   # 重新生成 SKILL.md
bun run skill:check      # 技能健康仪表盘
```

---

## 六、项目目录结构

```
gstack/
├── browse/              # 无头浏览器 CLI + 服务器
│   ├── src/
│   │   ├── cli.ts       # CLI 入口
│   │   ├── server.ts    # Bun HTTP 服务器
│   │   ├── commands.ts  # 命令注册表（唯一真相源）
│   │   ├── snapshot.ts  # 无障碍树 + Ref 引用系统
│   │   └── browser-manager.ts  # Chromium 生命周期管理
│   ├── test/            # 166+ 集成测试
│   └── dist/browse      # 编译后的二进制
│
├── plan-ceo-review/     # CEO 审查 skill
├── plan-eng-review/     # 工程经理审查 skill
├── plan-design-review/  # 设计审查 skill（计划阶段）
├── design-consultation/ # 设计系统构建 skill
├── design-review/       # 设计审查 + 修复 skill（线上）
├── review/              # 代码审查 skill
├── ship/                # 发布流程 skill（165KB 模板）
├── qa/                  # QA 测试 + 修复 skill
├── qa-only/             # QA 仅报告 skill
├── retro/               # 周回顾 skill
├── document-release/    # 发布后文档更新 skill
├── setup-browser-cookies/ # Cookie 导入 skill
├── gstack-upgrade/      # 升级 skill
│
├── scripts/
│   ├── gen-skill-docs.ts    # 模板 → SKILL.md 生成器
│   ├── skill-check.ts       # 健康仪表盘
│   └── dev-skill.ts         # 开发模式（文件监视）
│
├── test/
│   ├── helpers/
│   │   ├── session-runner.ts  # 端到端子进程编排
│   │   ├── llm-judge.ts       # LLM-as-Judge 评估
│   │   ├── eval-store.ts      # 评估结果持久化 + 对比
│   │   └── touchfiles.ts      # 差异化测试选择
│   ├── skill-validation.test.ts  # Tier 1: 静态验证
│   ├── skill-e2e.test.ts         # Tier 2: 端到端评估
│   └── skill-llm-eval.test.ts    # Tier 3: LLM 判官
│
├── bin/                 # 工具脚本
├── SKILL.md.tmpl        # 根技能模板
├── SKILL.md             # 自动生成（勿直接编辑）
├── CLAUDE.md            # 开发指引
├── CHANGELOG.md         # 版本历史
└── package.json         # Bun 项目配置
```

---

## 七、核心设计理念总结

1. **角色化 AI**：不是一个万能 Agent，而是 15 个专精角色，各有方法论
2. **持久浏览器**：守护进程模式带来亚秒级响应和状态持久
3. **代码即文档**：模板系统保证文档永远与代码一致
4. **AI 测试 AI**：三层评估管道确保 skill 质量
5. **完整性优先**：AI 压缩了实施成本，因此永远选择完整方案
6. **交互式审查**：一次一个问题，减少认知负荷
7. **开箱即用**：30 秒安装，一个命令就能调用整个虚拟团队