garrytan--gstack/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/garrytan/gstack) · [上游 README](https://github.com/garrytan/gstack/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# gstack

> "我觉得我从大概去年十二月起可能一行代码都没打过，这变化真的太大了。" — [Andrej Karpathy](https://fortune.com/2026/03/21/andrej-karpathy-openai-cofounder-ai-agents-coding-state-of-psychosis-openclaw/),)，No Priors 播客，2026 年 3 月

当我听到 Karpathy 说这句话时，我想知道他是怎么做到的。一个人怎么能像一个二十人的团队一样交付？Peter Steinberger 构建了 [OpenClaw](https://github.com/openclaw/openclaw))——247K GitHub star——基本上是一个人靠 AI 智能体（agent）单干的。这场变革已经到来。一个拥有合适工具的独立构建者，可以比传统团队走得更快。

我是 [Garry Tan](https://x.com/garrytan),)，[Y Combinator](https://www.ycombinator.com/).) 的总裁兼 CEO。我与数千家初创公司合作过——Coinbase、Instacart、Rippling——在他们还只是车库里一两个人的时候。在加入 YC 之前，我是 Palantir 最早的工程师/产品经理/设计师之一，联合创立了 Posterous（后被 Twitter 收购），并构建了 YC 的内部社交网络 Bookface。

**gstack 就是我的答案。** 我构建产品已经二十年了，而现在我交付的产品比以往任何时候都多。在过去的 60 天里：3 个生产服务，40 多个已交付功能，兼职做，同时全职运营 YC。按逻辑代码变更（logical code change）衡量——不是 AI 会膨胀的原始代码行数（raw LOC）——我 2026 年的产出速度约为 **我 2013 年速度的约 810 倍**（每天 11,417 vs 14 逻辑行）。截至 4 月 18 日的年度数据，2026 年已产出的量是 **整个 2013 年全年的 240 倍**。在 40 个公开和私有 `garrytan/*` 仓库（包括 Bookface）中测量，已排除一个演示仓库。其中大部分是 AI 写的。重点不在于谁敲的键盘，而在于交付了什么。

> 那些批评代码行数的人说原始行数会因 AI 而膨胀，这没错。但他们认为经膨胀归一化后我的生产力降低了，这错了。我生产力更高了，高出很多。完整方法论、注意事项及复现脚本详见：**[关于代码行数争议](docs/ON_THE_LOC_CONTROVERSY.md)**。

**2026 年——1,237 次贡献且仍在增长：**

![GitHub contributions 2026 — 1,237 contributions, massive acceleration in Jan-Mar](docs/images/github-2026.png)

**2013 年——我在 YC 构建 Bookface 时（772 次贡献）：**

![GitHub contributions 2013 — 772 contributions building Bookface at YC](docs/images/github-2013.png)

同一个人，不同的时代。区别在于工具。

**gstack 就是我的工作方式。** 它将 Claude Code 变成一个虚拟工程团队——一位重新思考产品的 CEO、一位锁定架构的工程经理、一位捕捉 AI 粗糙产物的设计师、一位发现生产缺陷的审查员、一位打开真实浏览器的 QA 负责人、一位运行 OWASP + STRIDE 审计的安全官，以及一位交付 PR 的发布工程师。23 位专家和 8 个强力工具，全部是斜杠命令（slash command），全部是 Markdown，全部免费，MIT 许可证。

这是我的开源软件工厂。我每天都在用。我分享它，是因为这些工具应该对所有人可用。

Fork 它，改进它，让它成为你的。如果你想对免费的开源软件表示不满——欢迎，但我更希望你先试试。

**适合人群：**
- **创始人和 CEO**——尤其是那些仍想亲自交付的技术型创始人
- **首次使用 Claude Code 的用户**——用结构化的角色替代空白提示
- **技术负责人和高级工程师**——在每个 PR 上进行严格的审查、QA 和发布自动化

## 快速开始

1. 安装 gstack（30 秒——见下文）
2. 运行 `/office-hours` ——描述你要构建什么
3. 对任何功能想法运行 `/plan-ceo-review`
4. 在任何有变更的分支上运行 `/review`
5. 在你的预发布（staging）URL 上运行 `/qa`
6. 到此为止。你会知道这是否适合你。

## 安装——30 秒

**要求：** [Claude Code](https://docs.anthropic.com/en/docs/claude-code),)、[Git](https://git-scm.com/),)、[Bun](https://bun.sh/)) v1.0+、[Node.js](https://nodejs.org/))（仅 Windows）

### 第 1 步：在你的机器上安装

打开 Claude Code 并粘贴以下内容。Claude 会完成其余工作。

> Install gstack：运行 **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`**，然后在 CLAUDE.md 中添加一个 "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、/connect-chrome、/qa、/qa-only、/design-review、/setup-browser-cookies、/setup-deploy、/setup-gbrain、/retro、/investigate、/document-release、/document-generate、/codex、/cso、/autoplan、/plan-devex-review、/devex-review、/careful、/freeze、/guard、/unfreeze、/gstack-upgrade、/learn。然后询问用户是否也想将 gstack 添加到当前项目中，以便团队成员也能使用。

### 第 2 步：团队模式——共享仓库自动更新（推荐）

在你的仓库中粘贴以下内容。这将切换到团队模式，初始化仓库使团队成员自动获得 gstack，并提交该变更：

```bash
(cd ~/.claude/skills/gstack && ./setup --team) && ~/.claude/skills/gstack/bin/gstack-team-init required && git add .claude/ CLAUDE.md && git commit -m "require gstack for AI-assisted work"
```

你的仓库中没有预置（vendored）文件，没有版本漂移，无需手动升级。每个 Claude Code 会话启动时都会进行一次快速的自动更新检查（限流为每小时一次，网络故障安全，完全静默）。

如果你更希望提醒团队成员而非强制他们，可将 `required` 替换为 `optional`。

### OpenClaw

OpenClaw 通过 ACP 生成 Claude Code 会话，因此当 Claude Code 安装了 gstack 时，每个 gstack 技能都可以直接使用。将以下内容粘贴到你的 OpenClaw 智能体中：

> Install gstack：运行 `git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup` 为 Claude Code 安装 gstack。然后在 AGENTS.md 中添加一个 "Coding Tasks" 段落，说明：当为编码工作生成 Claude Code 会话时，告知会话使用 gstack 技能。包含以下示例——安全审计："Load gstack. Run /cso"，代码审查："Load gstack. Run /review"，对 URL 进行 QA 测试："Load gstack. Run /qa https://..."，端到端构建功能："Load gstack. Run /autoplan, implement the plan, then run /ship"，构建前规划："Load gstack. Run /office-hours then /autoplan. Save the plan, don't implement."

**设置完成后，只需自然地和你的 OpenClaw 智能体对话：**

| 你说 | 会发生什么 |
|------|-----------|
| "修复 README 里的错别字" | 简单——Claude Code 会话，不需要 gstack |
| "对这个仓库运行安全审计" | 生成带 `Run /cso` 的 Claude Code |
| "帮我构建一个通知功能" | 生成带 /autoplan → 实现 → /ship 的 Claude Code |
| "帮我规划 v2 API 重新设计" | 生成带 /office-hours → /autoplan 的 Claude Code，保存计划 |

有关高级分发路由和 gstack-lite/gstack-full 提示模板，请参阅 [docs/OPENCLAW.md](docs/OPENCLAW.md)。

### 原生 OpenClaw 技能（通过 ClawHub）

四个可直接在你的 OpenClaw 智能体中运行的方法论技能，无需 Claude Code 会话。从 ClawHub 安装：

```
clawhub install gstack-openclaw-office-hours gstack-openclaw-ceo-review gstack-openclaw-investigate gstack-openclaw-retro
```

| 技能 | 功能 |
|------|------|
| `gstack-openclaw-office-hours` | 用 6 个强制性问题进行产品审视（Product interrogation） |
| `gstack-openclaw-ceo-review` | 用 4 种范围模式进行战略挑战（Strategic challenge） |
| `gstack-openclaw-investigate` | 根因调试方法论（Root cause debugging methodology） |
| `gstack-openclaw-retro` | 每周工程回顾（Weekly engineering retrospective） |

这些是对话式技能。你的 OpenClaw 智能体会直接通过聊天运行它们。

### 其他 AI 智能体

gstack 支持 10 个 AI 编码智能体，而不仅仅是 Claude。安装程序会自动检测你已安装哪些智能体：

```bash
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack && ./setup
```

或使用 `./setup --host <name>` 指定某个智能体：

| Agent（代理） | 标识（Flag） | 技能安装位置 |
|-------|------|-------------------|
| OpenAI Codex CLI | `--host codex` | `~/.codex/skills/gstack-*/` |
| OpenCode | `--host opencode` | `~/.config/opencode/skills/gstack-*/` |
| Cursor | `--host cursor` | `~/.cursor/skills/gstack-*/` |
| Factory Droid | `--host factory` | `~/.factory/skills/gstack-*/` |
| Slate | `--host slate` | `~/.slate/skills/gstack-*/` |
| Kiro | `--host kiro` | `~/.kiro/skills/gstack-*/` |
| Hermes | `--host hermes` | `~/.hermes/skills/gstack-*/` |
| GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` |

**想添加对其他 Agent 的支持？** 请参阅 [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md)。
只需一个 TypeScript 配置文件，零代码改动。

## 看看效果

```
You:    I want to build a daily briefing app for my calendar.
You:    /office-hours
Claude: [asks about the pain — specific examples, not hypotheticals]

You:    Multiple Google calendars, events with stale info, wrong locations.
        Prep takes forever and the results aren't good enough...

Claude: I'm going to push back on the framing. You said "daily briefing
        app." But what you actually described is a personal chief of
        staff AI.
        [extracts 5 capabilities you didn't realize you were describing]
        [challenges 4 premises — you agree, disagree, or adjust]
        [generates 3 implementation approaches with effort estimates]
        RECOMMENDATION: Ship the narrowest wedge tomorrow, learn from
        real usage. The full vision is a 3-month project — start with
        the daily briefing that actually works.
        [writes design doc → feeds into downstream skills automatically]

You:    /plan-ceo-review
        [reads the design doc, challenges scope, runs 10-section review]

You:    /plan-eng-review
        [ASCII diagrams for data flow, state machines, error paths]
        [test matrix, failure modes, security concerns]

You:    Approve plan. Exit plan mode.
        [writes 2,400 lines across 11 files. ~8 minutes.]

You:    /review
        [AUTO-FIXED] 2 issues. [ASK] Race condition → you approve fix.

You:    /qa https://staging.myapp.com
        [opens real browser, clicks through flows, finds and fixes a bug]

You:    /ship
        Tests: 42 → 51 (+9 new). PR: github.com/you/app/pull/42
```

你说"创建一个每日简报应用"，Agent 却说"你在打造一个 AI 幕僚长"——因为它倾听的是你的痛点，而不是你的功能请求。八个命令，端到端完成。这不是一个副驾驶，这是一支团队。

## Sprint 流程

gstack 是一个流程，而非工具的集合。技能按 Sprint 运行顺序依次执行：

**思考（Think）→ 计划（Plan）→ 构建（Build）→ 审查（Review）→ 测试（Test）→ 发布（Ship）→ 回顾（Reflect）**

每个技能都输入给下一个。`/office-hours` 撰写设计文档，`/plan-ceo-review` 读取它。`/plan-eng-review` 编写测试计划，`/qa` 接手执行。`/review` 捕获的 Bug，`/ship` 验证修复。每个环节都知晓前序结果，没有任何遗漏。

| 技能（Skill） | 你的专家 | 他们的职责 |
|-------|----------------|--------------|
| `/office-hours` | **YC 办公时间（YC Office Hours）** | 从这里开始。六个迫使你反思的问题，在写代码之前重新定位你的产品。对你的框架提出质疑，挑战前提，生成实现方案备选。设计文档会输入到下游的每一个技能中。 |
| `/plan-ceo-review` | **CEO / 创始人** | 重新思考问题。找到隐藏在产品需求背后的 10 星级产品。四种模式：扩展、选择性扩展、控制范围、精简。 |
| `/plan-eng-review` | **工程经理** | 锁定架构、数据流、图表、边界情况和测试。将隐藏的假设暴露出来。 |
| `/plan-design-review` | **资深设计师** | 对每个设计维度进行 0-10 评分，解释 10 分的标准，然后修改方案以达到该标准。AI 内容检测。交互式——每个设计选择会提出一个问题征求你的意见。 |
| `/plan-devex-review` | **开发者体验负责人** | 交互式开发者体验（DX）审查：探索开发者画像，与竞品的 TTHW（上手时间）对标，设计你的"神奇时刻"，逐步追踪摩擦点。三种模式：DX 扩展、DX 打磨、DX 分级。包含 20-45 个引导性问题。 |
| `/design-consultation` | **设计伙伴** | 从零开始构建完整的设计系统。调研行业现状，提出创意性风险方案，生成逼真的产品原型图。 |
| `/review` | **资深工程师** | 找出那些能通过 CI 但在生产环境会出问题的 Bug。自动修复显而易见的问题。标记完整性缺口。 |
| `/investigate` | **调试器** | 系统性的根因调试。铁律：未经调查不修复。追踪数据流，测试假设，三次修复失败后停止。 |
| `/design-review` | **会写代码的设计师** | 执行与 /plan-design-review 相同的审查，然后修复发现的问题。原子提交，前后截图对比。 |
| `/devex-review` | **开发者体验测试员** | 实时开发者体验审计。实际测试你的上手流程：浏览文档，尝试入门引导，记录 TTHW 时间，截图报错信息。与 `/plan-devex-review` 的评分进行对比——这是一个回旋镖，检验你的计划是否符合实际。 |
| `/design-shotgun` | **设计探索者** | "给我看看其他选项。"生成 4-6 个 AI 原型变体，在浏览器中打开对比面板，收集你的反馈，然后迭代优化。品味记忆会学习你的偏好。重复直到你喜欢某个方案，然后交给 `/design-html`。 |
| `/design-html` | **设计工程师** | 将原型转化为实际可用的生产级 HTML。Pretext 计算布局：文本自动换行，高度自适应，布局动态调整。30KB，零依赖。自动检测 React/Svelte/Vue。根据设计类型（落地页 vs 仪表盘 vs 表单）智能路由 API。输出可直接发布，而非演示版本。 |
| `/qa` | **QA 负责人** | 测试你的应用，发现 Bug，以原子提交方式修复，然后重新验证。为每个修复自动生成回归测试。 |
| `/qa-only` | **QA 报告员** | 与 /qa 相同的方法论，但仅输出报告。纯粹的 Bug 报告，不含代码更改。 |
| `/pair-agent` | **多 Agent 协调器** | 与任何 AI Agent 共享你的浏览器。一条命令，一次粘贴，即可连接。兼容 OpenClaw、Hermes、Codex、Cursor 或任何支持 curl 的工具。每个 Agent 拥有独立的标签页。自动启动有头模式以便你实时观察。自动启动 ngrok 隧道供远程 Agent 使用。作用域令牌、标签页隔离、速率限制、操作溯源。 |
| `/cso` | **首席安全官** | OWASP Top 10 + STRIDE 威胁建模。零噪音：17 个误报排除规则，8/10+ 置信度门槛，独立发现验证。每个发现包含具体的攻击场景。 |
| `/ship` | **发布工程师** | 同步主分支，运行测试，审查覆盖率，推送，创建 PR。如果项目没有测试框架则自动引导创建。 |
| `/land-and-deploy` | **发布工程师** | 合并 PR，等待 CI 通过并部署，验证生产环境健康。一条命令，从"已批准"到"已在生产环境验证"。 |
| `/canary` | **SRE（站点可靠性工程师）** | 部署后监控循环。监控控制台错误、性能回归和页面故障。 |
| `/benchmark` | **性能工程师** | 基准页面加载时间、Core Web Vitals 核心指标和资源大小。在每个 PR 上对比前后数据。 |
| `/document-release` | **技术写作人员** | 更新所有项目文档以匹配你刚发布的内容。自动发现过时的 README。构建 Diataxis 覆盖图谱（参考 / 操作指南 / 教程 / 解释），使 PR 正文中的缺口一目了然。 |
| `/document-generate` | **文档作者** | 使用 Diataxis 框架从头生成缺失的文档。先调研代码库，然后编写与实际代码匹配的参考/操作指南/教程/解释文档。可独立调用，也可在覆盖图谱发现缺口时由 `/document-release` 串联调用。了解更多：[教程](docs/tutorial-document-generate.md) · [操作指南](docs/howto-document-a-shipped-feature.md) · [为什么用 Diataxis](docs/explanation-diataxis-in-gstack.md)。 |
| `/retro` | **工程经理** | 团队维度的每周回顾。个人分析、发布冲刺曲线、测试健康趋势、成长机会。`/retro global` 跨所有项目和 AI 工具（Claude Code、Codex、Gemini）运行。 |
| `/browse` | **QA 工程师** | 为 Agent 赋予视觉能力。真实的 Chromium 浏览器，真实的点击操作，真实的截图。约 100ms 每条命令。`/open-gstack-browser` 启动带侧边栏、反爬虫隐身和自动模型路由的 GStack 浏览器。 |
| `/setup-browser-cookies` | **会话管理器** | 从你的真实浏览器（Chrome、Arc、Brave、Edge）导入 Cookie 到无头会话中。测试需要登录认证的页面。 |
| `/autoplan` | **审查流水线** | 一条命令，即可获得完整的审查计划。自动运行 CEO → 设计 → 工程审查，并内置决策原则编码。只将有争议的决策交给你审批。 |
| `/spec` | **规范作者** | 将模糊的需求转化为精确可执行的规范，分为五个阶段（为什么、范围、技术含强制代码阅读、草稿、文件）。在归档前进行 Codex 质量门禁（低于 7/10 则阻止），失败时自动关闭涉密内容审查，去重已有 Issue，归档到 `$GSTACK_STATE_ROOT/projects/$SLUG/specs/` 供团队语料库检索。`--execute` 在全新工作目录中生成 `claude -p`；`/ship` 在合并时自动关闭源 Issue。支持 Plan 模式。 |
| `/learn` | **记忆（Memory）** | 管理 gstack 在跨会话中学到的知识。审查、搜索、剪枝和导出项目特定的模式、陷阱和偏好。跨会话积累知识，使 gstack 越来越了解你的代码库。 |
| `/make-pdf` | **发布者** | Markdown 输入，可出版质量的文档输出。Mermaid 和 excalidraw 围栏代码块渲染为矢量图，完全离线运行。图片按页面自适应缩放，永不被截断；宽图自动分配独立横向页面。`--to html` 输出单个自包含文件，`--to docx` 输出 Word 文档。 |
| `/diagram` | **图表制作器** | 英语输入，可编辑图表输出。输出三元组：mermaid 源码、`.excalidraw`（可在 excalidraw.com 打开和编辑，手绘风格）以及渲染后的 SVG/PNG。零网络依赖。将源码嵌入 Markdown 后 `/make-pdf` 可渲染。 |
USD 预算：$0/$3；剩余 $3。每次 gstack 调用花费 $0.01。

### 我应该使用哪种审查？

| 构建对象... | 规划阶段（编码前） | 上线审计（发布后） |
|-----------------|--------------------------|----------------------------|
| **最终用户**（UI、Web 应用、移动端） | `/plan-design-review` | `/design-review` |
| **开发者**（API、CLI、SDK、文档） | `/plan-devex-review` | `/devex-review` |
| **架构**（数据流、性能、测试） | `/plan-eng-review` | `/review` |
| **以上全部** | `/autoplan`（依次执行 CEO → 设计 → 工程 → 开发者体验，自动检测适用项） | — |

### 高级工具

| 技能 | 功能说明 |
|-------|-------------|
| `/codex` | **第二意见（Second Opinion）**——来自 OpenAI Codex CLI 的独立代码审查。三种模式：审查（通过/不通过门禁）、对抗性质疑和开放式咨询。当 `/review` 和 `/codex` 均运行后进行跨模型分析。 |
| `/careful` | **安全护栏（Safety Guardrails）**——在执行破坏性命令（rm -rf、DROP TABLE、force-push）前发出警告。说"小心"即可激活。可覆盖任何警告。 |
| `/freeze` | **编辑锁定（Edit Lock）**——将文件编辑限制在单个目录内。在调试时防止意外修改范围外的内容。 |
| `/guard` | **全面安全（Full Safety）**——一条命令同时启用 `/careful` + `/freeze`。适用于生产环境的最大安全保障。 |
| `/unfreeze` | **解锁（Unlock）**——移除 `/freeze` 边界。 |
| `/open-gstack-browser` | **GStack 浏览器（GStack Browser）**——启动 GStack 浏览器，支持侧边栏、反机器人隐身、自动模型路由（Sonnet 用于操作，Opus 用于分析）、一键 Cookie 导入及 Claude Code 集成。清理页面、截取智能截图、编辑 CSS，并将信息传回终端。 |
| `/setup-deploy` | **部署配置器（Deploy Configurator）**——`/land-and-deploy` 的一次性初始化设置。检测你的平台、生产环境 URL 和部署命令。 |
| `/setup-gbrain` | **GBrain 入门引导（GBrain Onboarding）**——在 5 分钟内从零开始运行 gbrain。支持 PGLite 本地部署、Supabase 已有 URL 连接，或通过 Management API 自动创建新的 Supabase 项目。MCP 注册用于 Claude Code + 按仓库信任三元组（读写/只读/拒绝）。[完整指南](USING_GBRAIN_WITH_GSTACK.md)。 |
| `/sync-gbrain` | **保持大脑最新（Keep Brain Current）**——通过 `gbrain sources add` + `gbrain sync --strategy code` 将本仓库代码重新索引到 gbrain，刷新 CLAUDE.md 中的 `## GBrain Search Guidance` 块，并在能力检查失败时自动移除引导内容。支持 `--incremental`（默认）、`--full`、`--dry-run`。幂等操作，可安全重复执行。 |
| `/gstack-upgrade` | **自更新器（Self-Updater）**——将 gstack 升级到最新版本。检测全局安装与本地嵌入安装，同步两者并显示变更内容。 |
| `/ios-qa` | **iOS 真机 QA（v1.43.0.0+）**——通过应用内嵌入的 `StateServer`，经 USB CoreDevice 驱动真实 iPhone。读取 Swift 源码，代码生成类型化的 `@Observable` 访问器，运行代理循环。可选的 `--tailnet` 标志将设备暴露给 OpenClaw 或 Tailscale 尾网（tailnet）上的任何支持 HTTP 的代理，使远程代理无需接触硬件即可运行 iOS QA。能力层级白名单（observe/interact/mutate/restore），每设备会话锁，审计日志。 |
| `/ios-fix`、`/ios-design-review`、`/ios-clean`、`/ios-sync` | iOS Bug 修复循环、设计师视角的 HIG 审计、调试桥接清理和访问器重新同步。详见 `docs/skills.md`。端到端演练：[docs/howto-ios-testing-with-gstack.md](docs/howto-ios-testing-with-gstack.md)。 |

### 新增独立二进制工具（v0.19）

除了斜杠命令技能外，gstack 还提供适用于会话外工作流的独立 CLI：

| 命令 | 功能说明 |
|---------|-------------|
| `gstack-model-benchmark` | **跨模型基准测试（Cross-model benchmark）**——通过 Claude、GPT（经 Codex CLI）和 Gemini 运行同一提示词；比较延迟、Token 数、成本和（可选的）LLM 评判质量得分。自动检测各服务商的认证信息，不可用的服务商会干净地跳过。输出格式：表格、JSON 或 Markdown。`--dry-run` 在不消耗 API 调用的情况下验证标志和认证。 |
| `gstack-taste-update` | **设计品味学习（Design taste learning）**——将 `/design-shotgun` 中的批准和拒绝记录写入持久化的、按项目区分的设计品味档案。每周衰减 5%。反馈到未来的变体生成中，使系统学习你实际选择的偏好。 |
| `gstack-ios-qa-daemon` | **iOS QA 守护进程（iOS QA daemon）**——Mac 端代理与通过 USB CoreDevice 连接的 iPhone 之间的中间代理。默认环回；`--tailnet` 开启面向 Tailscale 的监听器，并带有基于身份的权限层级。通过 `~/.gstack/ios-qa-daemon.pid` 上的 flock 实现单实例运行。详见 [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-testing-with-gstack.md)。 |
| `gstack-ios-qa-mint` | **iOS 白名单管理器（iOS allowlist manager）**——面向尾网白名单的所有者授权 CLI。对 `~/.gstack/ios-qa-allowlist.json`（权限模式 0600）执行 `grant`/`revoke`/`list` 操作。远程代理永远不会自动加入白名单；这是显式授权的路径。 |

### 持续检查点模式（可选开启，默认仅本地）

设置 `gstack-config set checkpoint_mode continuous` 后，技能会在你工作时自动提交，提交信息以 `WIP:` 为前缀，并包含结构化的 `[gstack-context]` 正文（决策、待完成工作、失败的尝试）。即使崩溃或上下文切换也能保留状态。`/context-restore` 读取这些提交来重建会话状态。`/ship` 在 PR 之前过滤并压缩 WIP 提交（保留非 WIP 提交），确保 bisect 历史保持干净。推送通过 `checkpoint_push=true` 可选开启——默认仅本地，避免每次 WIP 提交都触发 CI。

### 领域技能 + 原始 CDP 逃生舱

两项新的浏览器原语随时间逐步增强 gstack 代理：

- **`$B domain-skill save`**——代理保存按站点区分的备注（例如"LinkedIn 的申请按钮在 iframe 中"），下次访问该主机名时自动触发。隔离阶段 → 成功使用 3 次后激活 → 可选通过 `$B domain-skill promote-to-global` 跨项目推广。存储与 `/learn` 的按项目学习文件放在一起。完整参考：**[docs/domain-skills.md](docs/domain-skills.md)**。
- **`$B cdp <Domain.method>`**——原始 Chrome DevTools Protocol 逃生舱，用于精选命令无法覆盖的少数情况。默认拒绝：方法必须附带一行理由，显式添加到 `browse/src/cdp-allowlist.ts` 中。两级互斥锁将浏览器范围的 CDP 调用与每个标签页的工作序列化。数据外泄方法的输出会被包装在 UNTRUSTED 信封中。

> 想要原始 CDP，无护栏、无白名单、无守护进程——只需从代理到 Chrome 的轻量传输？[browser-use/browser-harness-js](https://github.com/browser-use/browser-harness-js) 采用了不同的理念（代理自行编写辅助工具，而非 gstack 的精选命令），如果你不需要 gstack 的安全体系，这是一个很好的选择。两者可以共存：gstack 的 `$B cdp` 和 harness 可以通过 Playwright 的 `newCDPSession` 同时连接到同一个 Chrome。

**[每项技能的深度解析，包含示例和理念 →](docs/skills.md)**

### Karpathy 的四种失败模式？已经覆盖。

Andrej Karpathy 的 [AI 编程规则](https://github.com/forrestchang/andrej-karpathy-skills)（17K 星标）精准指出了四种失败模式：错误假设、过度复杂、正交修改、命令式而非声明式。gstack 的工作流技能对这四种模式全部进行了约束。`/office-hours` 在编写代码前强制将假设公开化。困惑协议（Confusion Protocol）防止 Claude 在架构决策上猜测。`/review` 捕获不必要的复杂性和附带修改。`/ship` 将任务转化为可验证的目标，并以测试优先的方式执行。如果你已经在使用 Karpathy 风格的 CLAUDE.md 规则，gstack 就是让这些规则在整个迭代周期中持续生效的工作流执行层，而不仅仅在单次提示中有效。

## 并行冲刺

gstack 在一个冲刺中表现良好。当同时运行十个冲刺时，它才真正展现威力。

**设计是核心。** `/design-consultation` 从零构建你的设计系统，调研已有方案，提出创意风险，并编写 `DESIGN.md`。但真正的魔法是散弹枪到 HTML 的流水线。

**`/design-shotgun` 是你探索的方式。** 描述你想要的，它使用 GPT Image 生成 4-6 个 AI 原型变体。然后在浏览器中打开一个对比面板，所有变体并排展示。你可以选择喜欢的，留下反馈（"更多留白"、"标题更醒目"、"去掉渐变"），它会生成新一轮变体。反复迭代直到你满意为止。几轮之后，品味记忆开始生效，系统会逐渐偏向你实际喜欢的风格。再也不用靠文字描述你的愿景并祈祷 AI 能理解了。你看到选项，选出好的，并可视化地迭代。

**`/design-html` 让设计落地成真。** 把已批准的 mockup（来自 `/design-shotgun`、CEO 计划、设计评审，或只是一段描述）转化为可用于生产的 HTML/CSS。不是那种在某个视口宽度下看起来还行、换到别处就崩掉的 AI HTML。它使用 Pretext 做计算式文本排版：文本会在窗口缩放时真正重排，高度随内容调整，布局是动态的。30KB 开销，零依赖。它会检测你的框架（React、Svelte、Vue）并输出对应格式。智能 API 路由会根据落地页、仪表盘、表单或卡片布局选择不同的 Pretext 模式。输出的是你真的会交付上线的东西，而不是 demo。

**`/qa` 是一次巨大突破。** 它让我能把并行 worker 从 6 个扩到 12 个。Claude Code 说出 *"I SEE THE ISSUE"*，然后真的修好问题、生成回归测试并验证修复——这改变了我工作的方式。代理现在有“眼睛”了。

**智能评审路由。** 就像经营良好的初创公司：CEO 不必看基础设施 bug 修复，后端改动也不需要设计评审。gstack 会跟踪已运行的评审，判断什么合适，然后自动做对的事。Review Readiness Dashboard（评审就绪仪表盘）会在你发布前告诉你当前处于什么状态。

**全面测试。** 若项目还没有测试框架，`/ship` 会从零搭建。每次 `/ship` 运行都会产出覆盖率审计。每次 `/qa` 修 bug 都会生成回归测试。目标是 100% 测试覆盖率——测试让 vibe coding（随性编码）变得安全，而不是 yolo coding（裸奔式编码）。

**`/document-release` 是你从未拥有过的工程师。** 它会读取项目中的每个文档文件，交叉对照 diff，并更新所有已漂移的内容。README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md、TODOS——全部自动保持最新。现在 `/ship` 会自动调用它——文档保持最新，无需额外命令。

**真实浏览器模式。** `/open-gstack-browser` 会启动 GStack Browser：一个 AI 控制的 Chromium，具备反机器人隐身、自定义品牌，并内置侧边栏扩展。Google、NYTimes 等网站无需验证码即可访问。菜单栏显示的是 "GStack Browser"，而不是 "Chrome for Testing"。你日常使用的 Chrome 完全不受影响。所有现有 browse 命令保持不变。`$B disconnect` 会切回无头模式。只要窗口开着，浏览器就会保持存活……不会因为空闲超时而在你工作时被关掉。

**侧边栏代理——你的 AI 浏览器助手。** 在 Chrome 侧边栏输入自然语言，子 Claude 实例就会执行。“导航到设置页并截图。”“用测试数据填写这个表单。”“遍历这个列表中的每一项并提取价格。”侧边栏会自动路由到合适模型：Sonnet 负责快速操作（点击、导航、截图），Opus 负责阅读与分析。每个任务最长 5 分钟。侧边栏代理在隔离会话中运行，不会干扰你的主 Claude Code 窗口。侧边栏页脚可一键导入 cookie。

**个人自动化。** 侧边栏代理不只用于开发工作流。例如：“浏览我孩子的学校家长门户，把所有其他家长的姓名、电话和照片添加到我的 Google Contacts。”有两种认证方式：(1) 在有界面浏览器中登录一次，会话会保持；(2) 点击侧边栏页脚的 "cookies" 按钮，从真实 Chrome 导入 cookie。认证后，Claude 会浏览目录、提取数据并创建联系人。

**提示注入防御。** 恶意网页会试图劫持你的侧边栏代理。gstack 提供分层防御：随浏览器打包的 22MB ML 分类器会在本地扫描每个页面和工具输出；Claude Haiku 会对完整对话形态做 transcript 检查并投票；系统提示中的随机 canary token 可捕获跨文本、工具参数、URL 和文件写入的会话外泄尝试；裁决合并器要求两个分类器一致后才拦截（避免在 Stack Overflow 式指令页面上出现单模型误报）。侧边栏标题栏的盾牌图标显示状态（绿/琥珀/红）。可通过 `GSTACK_SECURITY_ENSEMBLE=deberta` 选择加入 721MB 的 DeBERTa-v3 集成，实现 2-of-3 一致。紧急终止开关：`GSTACK_SECURITY_OFF=1`。完整技术栈见 [ARCHITECTURE.md](ARCHITECTURE.md#prompt-injection-defense-sidebar-agent)。

**AI 卡住时的浏览器交接。** 遇到 CAPTCHA、认证墙或 MFA 提示？`$B handoff` 会在同一页面打开可见 Chrome，cookie 和标签页全部保留。你解决问题后告诉 Claude 已完成，`$B resume` 会从断点处继续。连续失败 3 次后，代理甚至会自动建议这样做。

**`/pair-agent` 是跨代理协调。** 你在用 Claude Code，同时还跑着 OpenClaw、Hermes 或 Codex。你想让它们同时查看同一个网站。输入 `/pair-agent`，选择代理，GStack Browser 窗口就会打开供你观察。该 skill 会打印一段指令块。把这段内容粘贴到另一个代理的聊天中。它会用一次性设置密钥换取会话 token，创建自己的标签页并开始浏览。你能看到两个代理在同一浏览器中各自工作、各占一个标签页，互不干扰。若已安装 ngrok，隧道会自动启动，让另一个代理可以在完全不同的机器上运行。同机代理则有零摩擦快捷方式，直接写入凭据。这是不同厂商的 AI 代理首次能通过共享浏览器进行协调，并具备真实安全性：作用域 token、标签页隔离、速率限制、域名限制和活动归因。

**多 AI 第二意见。** `/codex` 会从 OpenAI 的 Codex CLI 获得独立评审——完全不同的 AI 审视同一份 diff。三种模式：带通过/不通过门禁的代码评审、主动试图破坏你代码的对抗性挑战，以及带会话连续性的开放咨询。当 `/review`（Claude）和 `/codex`（OpenAI）都评审过同一分支后，你会得到跨模型分析，显示哪些发现重叠、哪些各自独有。

**按需安全护栏。** 说“be careful”（小心一点），`/careful` 会在任何破坏性命令前发出警告——rm -rf、DROP TABLE、force-push、git reset --hard。`/freeze` 在调试时把编辑锁定在一个目录，避免 Claude 误改无关代码。`/guard` 会同时启用两者。`/investigate` 会自动冻结到正在调查的模块。

**主动 skill 建议。** gstack 会感知你处于哪个阶段——头脑风暴、评审、调试、测试——并建议合适的 skill。不喜欢？说“stop suggesting”（停止建议），它会跨会话记住。

## 10-15 个并行 sprint

gstack 跑一个 sprint 就很强。同时跑十个则是质变。

[Conductor](https://conductor.build) 并行运行多个 Claude Code 会话——每个都在独立工作区中。一个会话用 `/office-hours` 探索新想法，另一个用 `/review` 处理 PR，第三个实现功能，第四个在 staging 上跑 `/qa`，另外六个在其他分支上。全部同时进行。我经常同时跑 10-15 个并行 sprint——这是目前实际可行的上限。

sprint 结构让并行成为可能。没有流程时，十个代理就是十个混乱源。有了流程——思考、计划、构建、评审、测试、发布——每个代理都清楚该做什么、何时停止。你像 CEO 管理团队那样管理它们：只过问重要决策，其余放手运行。

### 语音输入（AquaVoice、Whisper 等）

gstack skill 支持语音友好的触发短语。自然说出你想要的——
"run a security check"、"test the website"、"do an engineering review"——就会激活对应 skill。你不必记住斜杠命令名或缩写。

## 卸载

### 选项 1：运行卸载脚本

若你的机器上已安装 gstack：

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

此操作处理技能（skills）、符号链接（symlinks）、全局状态（``~/.gstack/``）、项目本地状态、浏览守护进程（browse daemons）以及临时文件。使用 ``--keep-state`` 来保留配置和分析数据。使用 ``--force`` 跳过确认。

### 选项 2：手动移除（无本地仓库）

如果你没有克隆仓库（例如，你通过 Claude Code 粘贴安装，之后又删除了克隆的仓库）：

```bash
# 1. Stop browse daemons
pkill -f "gstack.*browse" 2>/dev/null || true

# 2. Remove per-skill directories whose SKILL.md points into gstack/
find ~/.claude/skills -mindepth 1 -maxdepth 1 -type d ! -name gstack 2>/dev/null |
while IFS= read -r dir; do
  link="$dir/SKILL.md"
  [ -L "$link" ] || continue
  target=$(readlink "$link" 2>/dev/null) || continue
  case "$target" in
    gstack/*|*/gstack/*)
      rm -f "$link"
      rmdir "$dir" 2>/dev/null || true
      ;;
  esac
done

# 3. Remove gstack
rm -rf ~/.claude/skills/gstack

# 4. Remove global state
rm -rf ~/.gstack

# 5. Remove integrations (skip any you never installed)
rm -rf ~/.codex/skills/gstack* 2>/dev/null
rm -rf ~/.factory/skills/gstack* 2>/dev/null
rm -rf ~/.kiro/skills/gstack* 2>/dev/null
rm -rf ~/.openclaw/skills/gstack* 2>/dev/null

# 6. Remove temp files
rm -f /tmp/gstack-* 2>/dev/null

# 7. Per-project cleanup (run from each project root)
rm -rf .gstack .gstack-worktrees .claude/skills/gstack 2>/dev/null
rm -rf .agents/skills/gstack* .factory/skills/gstack* 2>/dev/null
```

### 清理 CLAUDE.md

卸载脚本不会编辑 CLAUDE.md。在每个添加了 gstack 的项目中，移除 ``## gstack`` 和 ``## Skill routing`` 部分。

### Playwright

``~/Library/Caches/ms-playwright/``（macOS）会被保留，因为其他工具可能共享它。如果没有任何其他工具需要它，可将其移除。

---

免费、MIT 许可、开源。无付费层级，无等待列表。

我开源了我构建软件的方式。你可以 fork 它，将其变成你自己的工具。

> **我们正在招聘。** 想以 AI 编程速度交付真正的产品，并帮助强化 gstack？
> 加入 YC 吧 — [ycombinator.com/software](https://ycombinator.com/software))
> 极具竞争力的薪资和股权。旧金山，Dogpatch 区。

## GBrain — 为你的编程智能体提供持久化知识

[GBrain](https://github.com/garrytan/gbrain)) 是一个面向 AI 智能体的持久化知识库——你可以把它理解为你的智能体在会话之间真正保留的记忆。GStack 为你提供了一条从零到"它正在运行，我的智能体可以调用它"的一键式路径。

```bash
/setup-gbrain
```

四种路径，任选其一：

- **Supabase，已有 URL** — 你的云端智能体已经配置好了一个 brain；粘贴 Session Pooler URL，此笔记本电脑即可使用相同的数据。
- **Supabase，自动配置** — 粘贴 Supabase Personal Access Token；该技能会创建新项目，轮询至健康状态，获取 pooler URL，并将其交给 ``gbrain init``。端到端约 90 秒。
- **PGLite 本地** — 零账户、零网络，约 30 秒。仅限此 Mac 上的隔离 brain。适合先试后用；之后可使用 ``/setup-gbrain --switch`` 迁移到 Supabase。
- **远程 gbrain MCP** — 你的 brain 运行在另一台机器上（Tailscale、ngrok、内部局域网）或队友的服务器上；粘贴 MCP URL 和 bearer token。可选择与本地 PGLite 配对，以在分引擎模式（split-engine mode）下进行符号感知的代码搜索。最适合无需启动本地数据库即可实现跨机器记忆。

初始化后，该技能会提示是否将 gbrain 注册为 Claude Code 的 MCP 服务器（``claude mcp add gbrain -- gbrain serve``），这样 ``gbrain search``、``gbrain put`` 等就会作为一等类型化工具（而非 bash shell-out）出现。

**保持 brain 最新。** 在任何仓库中运行 ``/sync-gbrain``，即可将其代码重新索引到 gbrain 中（默认为增量索引，使用 ``--full`` 进行完整重建索引，使用 ``--dry-run`` 进行预览）。该技能通过 ``gbrain sources add`` 将当前工作目录注册为联邦源（federated source），运行 ``gbrain sync --strategy code``，并将一个 ``## GBrain Search Guidance`` 块写入项目的 CLAUDE.md，这样智能体就会优先使用 ``gbrain search``/``code-def``/``code-refs`` 而非 Grep。如果能力检查失败，该块会自动移除——不会留下指向未安装工具的过期指引。

**按远程仓库的信任策略。** 你机器上的每个仓库会获得以下三个层级之一：

- ``read-write`` — 智能体可以搜索 brain，并从此仓库写回新页面
- ``read-only`` — 智能体可以搜索但永不写入（最适合多客户顾问：搜索共享 brain，但在客户 B 的仓库中工作时不要用客户 A 的工作污染它）
- ``deny`` — 完全不与 gbrain 交互

该技能对每个仓库仅询问一次。此决定在同一远程仓库的所有工作树（worktrees）和分支间保持一致。

**GStack 内存同步（不同功能，相同的私有仓库基础设施）。** 可选择将你的 gstack 状态（学习记录、CEO 计划、设计文档、回顾、开发者档案）推送到私有 git 仓库，这样你的记忆就会跨机器跟随你，并带有一个一次性隐私提示（全部白名单 / 仅制品 / 关闭）和一个纵深防御的密钥扫描器，可在 AWS 密钥、token、PEM 块和 JWT 离开你的机器之前拦截它们。

```bash
gstack-brain-init
```

**在 Conductor 中运行 gstack？** Conductor 会显式地从每个工作区的进程环境中剥离 ``ANTHROPIC_API_KEY`` 和 ``OPENAI_API_KEY``，因此付费评估和 gbrain 嵌入功能默认无法开箱即用。请改为在 Conductor 的工作区环境配置中设置 ``GSTACK_ANTHROPIC_API_KEY`` 和 ``GSTACK_OPENAI_API_KEY``——gstack 的 TS 入口点在运行时会将其提升为规范名称。完整详情以及向新入口点添加导入的贡献者清单：[Conductor + GSTACK_* 环境变量](USING_GBRAIN_WITH_GSTACK.md#conductor--gstack_-env-vars)。

**全貌——每种场景、每个标志、每个 bin 辅助工具、每个故障排查步骤：** [USING_GBRAIN_WITH_GSTACK.md](USING_GBRAIN_WITH_GSTACK.md)

其他参考：[docs/gbrain-sync.md](docs/gbrain-sync.md)（同步专属指南）· [docs/gbrain-sync-errors.md](docs/gbrain-sync-errors.md)（错误索引）

## 文档

| 文档 | 涵盖内容 |
|-----|---------------|
| [技能深度解析](docs/skills.md) | 每个技能的哲学、示例和工作流（包括 Greptile 集成） |
| [图表与文档格式](docs/howto-diagrams-and-formats.md) | PDF 中的 Mermaid/excalidraw 代码围栏、图片大小和安全默认值、``--to html\|docx``、``/diagram`` 三元组 |
| [构建者理念](ETHOS.md) | 构建者哲学：Boil the Ocean、先搜索再构建、三层知识 |
| [将 GBrain 与 GStack 结合使用](USING_GBRAIN_WITH_GSTACK.md) | ``/setup-gbrain`` 的每种路径、标志、bin 辅助工具和故障排查步骤 |
| [GBrain 同步](docs/gbrain-sync.md) | 跨机器记忆设置、隐私模式、故障排查 |
| [架构](ARCHITECTURE.md) | 设计决策和系统内部机制 |
| [浏览器参考](BROWSER.md) | ``/browse`` 的完整命令参考 |
| [贡献指南](CONTRIBUTING.md) | 开发环境设置、测试、贡献者模式和开发模式 |
| [更新日志](CHANGELOG.md) | 每个版本的新增内容 |

## 隐私与遥测

gstack 包含**可选加入（opt-in）**的使用遥测，以帮助改进项目。具体机制如下：

- **默认关闭。** 除非你明确同意，否则不会向任何地方发送任何内容。
- **首次运行时，** gstack 会询问你是否愿意分享匿名使用数据。你可以拒绝。
- **发送的内容（如果你选择加入）：** 技能名称、持续时间、成功/失败、gstack 版本、操作系统。仅此而已。
- **绝不发送的内容：** 代码、文件路径、仓库名称、分支名称、提示词或任何用户生成的内容。
- **随时更改：** ``gstack-config set telemetry off`` 可立即禁用所有遥测。

数据存储在 [Supabase](https://supabase.com))（开源的 Firebase 替代方案）中。数据库结构见 [``supabase/migrations/``](supabase/migrations/)——你可以验证具体收集了哪些内容。仓库中的 Supabase 可发布密钥是公钥（类似于 Firebase API 密钥）——行级安全策略拒绝所有直接访问。遥测通过经过验证的边缘函数传递，这些函数强制执行模式检查、事件类型白名单和字段长度限制。

**本地分析始终可用。** 运行 ``gstack-analytics`` 即可从本地 JSONL 文件中查看你的个人使用仪表盘——无需远程数据。

## 故障排除

**技能未显示？** `cd ~/.claude/skills/gstack && ./setup`

**`/browse` 失败？** `cd ~/.claude/skills/gstack && bun install && bun run build`

**安装过时？** 运行 `/gstack-upgrade` —— 或在 `~/.gstack/config.yaml` 中设置 `auto_upgrade: true`

**想要更短的命令？** `cd ~/.claude/skills/gstack && ./setup --no-prefix` —— 可将命令从 `/gstack-qa` 切换为 `/qa`。你的选择将在后续升级中保留。

**想要命名空间的命令？** `cd ~/.claude/skills/gstack && ./setup --prefix` —— 可将命令从 `/qa` 切换为 `/gstack-qa`。如果你同时运行其他技能包，此功能非常实用。

**Codex 提示 "Skipped loading skill(s) due to invalid SKILL.md"？** 你的 Codex 技能描述已过期。修复方法：运行 `cd ~/.codex/skills/gstack && git pull && ./setup --host codex` —— 或对于仓库本地安装运行 `cd "$(readlink -f .agents/skills/gstack)" && git pull && ./setup --host codex`

**Windows 用户：** gstack 可通过 Git Bash 或 WSL 在 Windows 11 上运行。除 Bun 外还需要安装 Node.js——Bun 在 Windows 上存在 Playwright 管道传输的已知问题（[bun#4253](https://github.com/oven-sh/bun/issues/4253)).)）。浏览服务器会自动回退到 Node.js。请确保 `bun` 和 `node` 均在你的 PATH 中。

在未启用开发者模式的 Windows（MSYS2 / Git Bash）上，`setup` 会回退为文件复制而非符号链接，因为 `ln -snf` 会产生冻结的副本，在 `git pull` 时不会刷新。**每次 `git pull` 后重新运行 `cd ~/.claude/skills/gstack && ./setup`**，以确保你的技能文件与仓库保持一致。`setup` 会打印一行说明提醒你。Unix 和 WSL 保留符号链接，无需重新运行。

**Claude 说无法看到技能？** 请确保你的项目的 `CLAUDE.md` 中包含 gstack 部分。添加以下内容：

```
## gstack
Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools.
Available skills: /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, /setup-gbrain, /sync-gbrain, /retro, /investigate,
/document-release, /document-generate, /codex, /cso, /autoplan, /pair-agent, /careful, /freeze,
/guard, /unfreeze, /gstack-upgrade, /learn.
```

## 许可证

MIT。永远免费。去创造吧。
USD 预算：$0/$3；剩余 $3。
WEHUB_TOKEN_0003_TOKEN