# gstack

**Repository Path**: iron-beast_2/gstack

## Basic Information

- **Project Name**: gstack
- **Description**: ai快速应用开发
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gstack 中文使用指南

## 项目简介

gstack 是一个 AI 工程工作流工具集，将 Claude Code 转变为虚拟工程团队。包含 23 个专业技能和 8 个强大工具，全部通过斜杠命令调用。

**作者**: Garry Tan (Y Combinator 总裁兼 CEO)  
**许可证**: MIT (永久免费)  
**版本**: 0.16.2.0

---

## 上游仓库同步指南

### 1. 添加上游仓库（首次配置）

```bash
# 进入项目目录
cd /Users/mowei/claude-code-m/gstack-main

# 添加官方上游仓库
git remote add upstream https://github.com/mowei-git/gstack.git

# 验证远程仓库配置
git remote -v
```

**预期输出**:
```
origin    https://gitee.com/iron-beast_2/gstack.git (fetch)
origin    https://gitee.com/iron-beast_2/gstack.git (push)
upstream  https://github.com/mowei-git/gstack.git (fetch)
upstream  https://github.com/mowei-git/gstack.git (push)
```

### 2. 从上游拉取最新代码

```bash
# 拉取上游仓库的所有分支
git fetch upstream

# 查看上游分支
git branch -r
```

### 3. 合并上游更新到本地

```bash
# 确保在 main 分支
git checkout main

# 合并上游的 main 分支到本地
git merge upstream/main

# 如果有冲突，解决冲突后执行
git add .
git commit -m "解决合并冲突"
```

### 4. 推送到自己的 Gitee 仓库

```bash
# 推送到 Gitee
git push origin main
```

### 5. 完整同步流程（一键脚本）

创建一个同步脚本方便日常使用：

```bash
#!/bin/bash
# 文件名: sync-upstream.sh

echo "🔄 开始同步上游仓库..."

# 1. 拉取上游更新
echo "📥 拉取上游更新..."
git fetch upstream

# 2. 切换到 main 分支
echo "🔀 切换到 main 分支..."
git checkout main

# 3. 合并上游更新
echo "🔗 合并上游更新..."
git merge upstream/main

# 4. 推送到 Gitee
echo "📤 推送到 Gitee..."
git push origin main

echo "✅ 同步完成！"
```

**使用方法**:
```bash
# 赋予执行权限
chmod +x sync-upstream.sh

# 运行同步
./sync-upstream.sh
```

---

## 项目安装与启动

### 系统要求

- **Node.js**: v16+ (推荐 v18+)
- **Bun**: v1.0+ ([安装指南](https://bun.sh/))
- **Git**: 2.0+
- **Claude Code**: 必需

### 安装步骤

#### 1. 安装依赖

```bash
# 进入项目目录
cd /Users/mowei/claude-code-m/gstack-main

# 安装依赖
bun install
```

#### 2. 构建项目

```bash
# 编译二进制文件和生成文档
bun run build
```

**构建内容**:
- 浏览器自动化工具 (`browse/dist/browse`)
- 设计工具 (`design/dist/design`)
- 全局发现工具 (`bin/gstack-global-discover`)
- 技能文档 (所有 SKILL.md 文件)

#### 3. 运行测试（可选）

```bash
# 运行快速测试（不包含 E2E 测试）
bun test

# 运行完整测试套件
bun run test:evals
```

### 配置 Claude Code

#### 方法一：全局安装（推荐）

```bash
# 克隆到 Claude 技能目录
git clone https://github.com/mowei-git/gstack.git ~/.claude/skills/gstack

# 进入目录并运行安装脚本
cd ~/.claude/skills/gstack
./setup
```

#### 方法二：项目本地安装

```bash
# 在项目根目录创建软链接
cd /Users/mowei/claude-code-m/gstack-main
ln -s $(pwd) ~/.claude/skills/gstack

# 运行安装
./setup
```

#### 配置 CLAUDE.md

在项目根目录的 `CLAUDE.md` 中添加：

```markdown
## gstack

使用 gstack 的 /browse 进行所有网页浏览。禁止使用 mcp__claude-in-chrome__* 工具。

可用技能: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
/design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy,
/canary, /benchmark, /browse, /open-gstack-browser, /qa, /qa-only, /design-review,
/setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex,
/cso, /autoplan, /pair-agent, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn.
```

---

## 核心功能使用

### 快速开始工作流

```bash
# 1. 产品构思阶段
/office-hours
# 描述你要构建的产品，AI 会通过 6 个关键问题帮你重新定义产品

# 2. CEO 级别审查
/plan-ceo-review
# 从战略层面审查产品想法，找到隐藏的 10 星产品

# 3. 工程审查
/plan-eng-review
# 锁定架构、数据流、边缘情况和测试计划

# 4. 代码审查
/review
# 在任何有改动的分支上运行，找出会在生产环境爆炸的 bug

# 5. QA 测试
/qa https://your-staging-url.com
# 打开真实浏览器，点击测试，发现并修复 bug

# 6. 发布
/ship
# 运行测试、审查覆盖率、推送代码、创建 PR
```

### 主要技能说明

| 技能 | 角色 | 功能 |
|------|------|------|
| `/office-hours` | **YC 办公时间** | 从这里开始。6 个关键问题重新定义产品 |
| `/plan-ceo-review` | **CEO/创始人** | 战略级审查，发现隐藏的 10 星产品 |
| `/plan-eng-review` | **工程经理** | 锁定架构、数据流、边缘情况、测试 |
| `/review` | **高级工程师** | 发现通过 CI 但会在生产环境崩溃的 bug |
| `/qa` | **QA 主管** | 测试应用、发现 bug、修复并重新验证 |
| `/ship` | **发布工程师** | 同步主分支、运行测试、推送、创建 PR |
| `/browse` | **QA 工程师** | 真实 Chromium 浏览器，真实点击，真实截图 |
| `/design-review` | **设计师** | 设计审查，原子化提交，前后对比截图 |
| `/investigate` | **调试专家** | 系统化根因调试，不调查不修复 |
| `/retro` | **工程经理** | 团队感知的周回顾，包含个人分解 |

### 浏览器自动化

```bash
# 启动 GStack 浏览器
/open-gstack-browser

# 基础浏览命令
$B goto https://example.com
$B screenshot
$B click "登录按钮"
$B type "用户名" "myuser"

# 导入真实浏览器的 cookies（用于测试需要登录的页面）
/setup-browser-cookies
```

### 安全与保护

```bash
# 在执行破坏性命令前警告
/careful

# 锁定编辑到特定目录
/freeze /path/to/directory

# 同时启用 careful 和 freeze
/guard

# 解除目录锁定
/unfreeze
```

---

## 开发命令参考

### 常用脚本

```bash
# 安装依赖
bun install

# 构建项目
bun run build

# 运行测试（快速，<5秒）
bun test

# 生成技能文档
bun run gen:skill-docs

# 技能健康检查
bun run skill:check

# 启动浏览器服务器
bun run server

# 开发模式（浏览器工具）
bun run dev

# 开发模式（设计工具）
bun run dev:design

# 查看本地分析数据
bun run analytics
```

### 测试命令

```bash
# 快速测试（不含 E2E）
bun test

# 完整评估测试
bun run test:evals

# 仅 E2E 测试
bun run test:e2e

# 门禁测试（CI 用）
bun run test:gate

# 定期测试（完整）
bun run test:periodic
```

---

## 项目结构

```
gstack-main/
├── .agents/              # 代理配置
├── agents/               # 技能代理
├── bin/                  # 可执行文件
├── browse/               # 浏览器自动化工具
│   ├── src/             # 源代码
│   └── dist/            # 编译后的二进制
├── design/               # 设计工具
├── docs/                 # 文档
├── scripts/              # 构建和工具脚本
├── test/                 # 测试文件
├── *-review/            # 各种审查技能
├── qa/                   # QA 技能
├── ship/                 # 发布技能
├── package.json          # 项目配置
├── README.md             # 英文文档
└── README_CN.md          # 中文文档（本文件）
```

---

## 常见问题

### 1. 技能没有显示？

```bash
cd ~/.claude/skills/gstack
./setup
```

### 2. `/browse` 失败？

```bash
cd ~/.claude/skills/gstack
bun install
bun run build
```

### 3. 安装过期？

```bash
# 在 Claude Code 中运行
/gstack-upgrade

# 或手动更新
cd ~/.claude/skills/gstack
git pull
./setup
```

### 4. 想要更短的命令？

```bash
# 从 /gstack-qa 切换到 /qa
cd ~/.claude/skills/gstack
./setup --no-prefix
```

### 5. 想要命名空间命令？

```bash
# 从 /qa 切换到 /gstack-qa
cd ~/.claude/skills/gstack
./setup --prefix
```

### 6. Windows 用户

gstack 在 Windows 11 上通过 Git Bash 或 WSL 工作。需要同时安装 Node.js 和 Bun。

---

## 隐私与遥测

- **默认关闭**: 除非明确同意，否则不发送任何数据
- **首次运行**: 会询问是否分享匿名使用数据
- **发送内容**（如果同意）: 技能名称、持续时间、成功/失败、版本、操作系统
- **永不发送**: 代码、文件路径、仓库名、分支名、提示词或任何用户生成内容
- **随时更改**: `gstack-config set telemetry off`

本地分析始终可用: `gstack-analytics`

---

## 升级指南

### 自动升级（推荐）

```bash
# 在 Claude Code 中运行
/gstack-upgrade
```

### 手动升级

```bash
cd ~/.claude/skills/gstack
git pull
./setup
```

### 启用自动升级

编辑 `~/.gstack/config.yaml`:
```yaml
auto_upgrade: true
```

---

## 卸载

### 使用卸载脚本

```bash
~/.claude/skills/gstack/bin/gstack-uninstall
```

### 手动卸载

```bash
# 停止浏览器守护进程
pkill -f "gstack.*browse" 2>/dev/null || true

# 删除技能符号链接
find ~/.claude/skills -maxdepth 1 -type l 2>/dev/null | while read -r link; do
  case "$(readlink "$link" 2>/dev/null)" in gstack/*|*/gstack/*) rm -f "$link" ;; esac
done

# 删除 gstack
rm -rf ~/.claude/skills/gstack

# 删除全局状态
rm -rf ~/.gstack

# 删除临时文件
rm -f /tmp/gstack-* 2>/dev/null

# 项目级清理（在每个项目根目录运行）
rm -rf .gstack .gstack-worktrees .claude/skills/gstack 2>/dev/null
```

---

## 贡献指南

详见 [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 相关文档

| 文档 | 内容 |
|------|------|
| [技能深度解析](docs/skills.md) | 每个技能的理念、示例和工作流 |
| [构建者理念](ETHOS.md) | 构建哲学和知识层次 |
| [架构设计](ARCHITECTURE.md) | 设计决策和系统内部结构 |
| [浏览器参考](BROWSER.md) | `/browse` 完整命令参考 |
| [贡献指南](CONTRIBUTING.md) | 开发设置、测试、贡献者模式 |
| [更新日志](CHANGELOG.md) | 每个版本的新功能 |

---

## 许可证

MIT 许可证。永久免费。去构建些东西吧。

---

## 联系方式

- **GitHub**: https://github.com/mowei-git/gstack
- **Gitee**: https://gitee.com/iron-beast_2/gstack
- **原作者**: Garry Tan ([@garrytan](https://x.com/garrytan))
- **官方仓库**: https://github.com/garrytan/gstack

---

**最后更新**: 2026-04-14