gstack教程
markdown
2026年7月17日13 min read2,467 words
Updated 2026年7月17日
gstack 完整教程：把 AI 变成虚拟工程团队
目录
- 痛点导入：我们为什么需要虚拟工程团队？
- gstack 是什么？
- 核心理念：YC 创始人的工程哲学
- 技能体系全解
- 快速入门：30 秒安装
- 实战演示：从想法到部署
- 架构深度解析
- 最佳实践与安全指南
- 方法论总结：如何写好工具教程
1. 痛点导入：我们为什么需要虚拟工程团队？
1.1 独立开发者的困境
作为独立开发者或小团队，你是否面临过以下挑战？
| 困境 | 描述 |
|---|---|
| 角色缺失 | 你是 CEO、PM、设计师、工程师、QA、安全审计员——一个人扮演所有人 |
| 上下文切换 | 从产品思考切换到代码编写再到测试，每次切换都消耗精力 |
| 质量瓶颈 | 代码写完没人 review，bug 藏在生产环境 |
| 发布焦虑 | 改一行代码要手动测试、部署、验证，心惊胆战 |
| 知识断层 | 跨会话工作，AI 忘记之前的决策和上下文 |
1.2 现有 AI 工具的局限
| 工具 | 角色 | 局限 |
|---|---|---|
| Copilot | 代码补全 | 只解决"怎么写"，不解决"写什么" |
| ChatGPT | 对话助手 | 无状态、无法与代码库交互 |
| Claude Code | 执行引擎 | 缺少结构化流程，容易"盲飞" |
| Superpowers | 方法论框架 | 偏向流程规范，缺少浏览器交互能力 |
1.3 gstack 的答案
"把 Claude Code 变成一个虚拟工程团队。"
— Garry Tan，Y Combinator 总裁
gstack 不是替代这些工具，而是为 Claude Code 注入完整的工程团队能力：
传统 AI 编程：一个人 + 一个 AI = 单打独斗
gstack 模式： 一个人 + 一支 AI 团队 = 虚拟工程团队
2. gstack 是什么？
2.1 一句话定义
gstack 是一套运行在 Claude Code 上的 AI 软件工厂，通过一系列结构化的 slash commands，让一个人能以二十人团队的速度交付产品。
2.2 项目档案
| 属性 | 内容 |
|---|---|
| GitHub | garrytan/gstack |
| Stars | 118k |
| Fork | 17.6k |
| 主要语言 | TypeScript (79.4%), Go Template (11.2%), Shell (5.8%) |
| 许可证 | MIT |
| 作者 | Garry Tan (Y Combinator 总裁) |
2.3 核心能力矩阵
| 能力维度 | 具体能力 |
|---|---|
| 产品思维 | /office-hours (YC Office Hours)、/plan-ceo-review (CEO 视角) |
| 架构设计 | /plan-eng-review (工程经理)、/plan-design-review (设计师) |
| 代码实现 | 支持 Claude Code、Codex CLI、Cursor、OpenCode 等主流 AI 代理 |
| 代码审查 | /review (Staff Engineer)、/investigate (Debugger) |
| 质量保障 | /qa (QA Lead)、/browse (浏览器测试) |
| 安全审计 | /cso (首席安全官)、OWASP Top 10 + STRIDE 模型 |
| 发布部署 | /ship (Release Engineer)、/land-and-deploy (合并到生产) |
| 知识管理 | /learn (跨会话记忆)、/retro (团队回顾) |
2.4 软件工厂流水线
3. 核心理念：YC 创始人的工程哲学
gstack 的灵魂藏在 ETHOS.md 中，这是 Garry Tan 二十年工程经验的结晶。
3.1 原则一：Boil the Ocean（沸腾海洋）
"当完整实现的边际成本趋近于零时，应始终选择完整方案而非捷径。"
反直觉的时代变迁
| 时代 | 完整实现的成本 | 建议 |
|---|---|---|
| 传统软件 | 昂贵（人力、时间） | "不要沸腾海洋" |
| AI 时代 | 趋近于零（代码增量以秒计） | 选择完整方案是正确选择 |
测试：最便宜的"湖泊"
3.2 原则二：Search Before Building（先搜索后构建）
"千倍工程师的第一本能是：这个问题是否已被解决？"
三层知识结构
第一层：久经考验
├── 标准库、设计模式、最佳实践
├── 需要偶尔质疑前提，但默认正确
└── 示例：关系型数据库 ACID 特性
第二层：新潮流行
├── 当前技术博客、热门框架、Trend
├── 需要批判性审视，验证有效性
└── 示例：某个新晋前端框架
第三层：第一性原理
├── 从具体问题出发的原创推理
├── 最有价值，也最稀缺
└── 示例：为什么这个场景不需要数据库？
搜索的终极价值
最佳结果不是找到完美方案，而是发现"常规方案为何错误"的 Eureka 时刻。
3.3 原则三：User Sovereignty（用户主权）
"AI 提供建议，用户做决定。两模型一致是强信号，非指令。"
正确模式：生成-验证循环
验证的重要性
| 场景 | AI 跳过验证的风险 |
|---|---|
| 代码修改 | 引入隐藏 bug |
| 产品决策 | 偏离用户真实需求 |
| 安全变更 | 暴露攻击面 |
3.4 三原则协同
最坏结果：基于已有解决方案构建完整版本（浪费了搜索，但确保了质量）
最好结果：通过搜索发现他人遗漏的盲点，构建无人想过的完整方案
4. 技能体系全解
gstack 提供 40+ 技能，覆盖产品开发全生命周期。按角色分类：
4.1 产品与战略（Think 阶段）
/office-hours — YC Office Hours
角色定位：YC 合伙人，在投入工程前追问 6 个强制问题
核心问题清单：
1. 你在解决什么问题？痛点是什么？
2. 目前用户是如何解决这个问题的？
3. 你的解决方案有何不同？为什么现在可行？
4. 如何衡量成功？关键指标是什么？
5. 商业模式是什么？如何变现？
6. 竞争对手是谁？为什么你能赢？
输出：经过重构的产品设计文档，供下游 /plan-* 使用
/plan-ceo-review — CEO/Founder 视角
角色定位：公司创始人，从战略层审查产品计划
四种范围模式：
| 模式 | 描述 | 适用场景 |
|---|---|---|
| 10 星产品 | 突破性创新，重新定义品类 | 全新赛道 |
| 选择性扩展 | 保持核心，拓展特定边界 | 已有产品迭代 |
| 保持 | 专注核心竞争力 | 资源有限时 |
| 缩减 | 聚焦最小可行产品 | 验证阶段 |
输出：战略层面的产品范围决策
/autoplan — 一键审查流水线
角色定位：Review Pipeline，一次运行完整审查
执行顺序：
价值：原本需要 3 个独立命令，现在一键完成
4.2 架构与设计（Plan 阶段）
/plan-eng-review — Engineering Manager
角色定位：工程经理，锁定架构和测试计划
审查维度：
1. 架构锁定
├── 技术选型合理性
├── 模块边界清晰度
└── 扩展性预留
2. 数据流图
├── 数据从哪里来
├── 经过哪些处理
└── 最终去向何方
3. 测试矩阵
├── 单元测试覆盖点
├── 集成测试场景
└── E2E 测试路径
4. 边缘用例
├── 异常情况处理
├── 边界条件
└── 错误恢复机制
输出：可执行的测试计划，自动传递给 /qa
/plan-design-review — Senior Designer
角色定位：资深设计师，交互设计审查
评分体系：
评分范围：0-10 分
及格线：7 分（7 轮审计循环）
审查维度：
- 信息架构清晰度
- 交互流程顺畅度
- 视觉层次合理性
- 响应式适配度
- 无障碍访问
/design-shotgun — Design Explorer
角色定位：设计探索者，生成多种方案供选择
输出：
生成 3-6 个 AI 设计变体
↓
用户对比选择
↓
选定方向迭代深化
价值：快速探索设计空间，避免"一条路走到黑"
/design-html — Design Engineer
角色定位：设计工程师，将设计稿转为生产级 HTML
输出标准：
- Preact 原生组件（非 React）
- 自适应布局
- 生产级代码质量
- 可直接提交代码审查
4.3 代码实现（Build 阶段）
/review — Staff Engineer
角色定位：资深工程师，找出 CI 通过但生产爆炸的 bug
自动修复能力：
发现的 Bug 类型：
├── 逻辑错误（空指针、边界溢出）
├── 资源泄漏（未关闭连接、内存泄漏）
├── 安全漏洞（注入、XSS）
└── 性能问题（N+1 查询、阻塞调用）
自动修复：明显问题自动修复，非明显问题报告
Greptile 集成：
review/ship 自动读取 GitHub Greptile 评论
↓
分类处理：
├── 有效问题 → 修复后再发布
├── 已修复问题 → 自动回复确认
└── 误报 → 确认后回复解释，保存到历史
/investigate — Debugger
角色定位：根因调试专家，铁律：无调查不修复
调查原则：
第一步：复现问题
↓ 找到稳定复现步骤
第二步：收集证据
↓ 日志、堆栈、监控数据
第三步：形成假设
↓ 提出可能的根因
第四步：验证假设
↓ 证实或证伪
第五步：修复验证
↓ 确认修复有效
强制规则：未经调查不得修复
/careful — Safety Guardrails
角色定位：安全护栏，危险命令警告
监控命令类型：
# 危险命令
rm -rf / # 系统删除
DROP TABLE # 数据库删除
git push --force # 历史覆写
# 需要谨慎的命令
npm install -g # 全局安装
chmod 777 # 权限过大
curl | sh # 远程脚本执行
/freeze / /guard — Edit Lock
角色定位：编辑边界锁定，防止调试时意外修改
/freeze src/utils # 锁定特定目录
/guard # /careful + /freeze 组合
/unfreeze # 解除锁定
使用场景：
- 调试时锁定核心代码，只在调试目录修改
- 防止 AI "顺手改一下"导致不可预期的影响
4.4 质量保障（Test 阶段）
/qa — QA Lead
角色定位：QA 负责人，四种测试模式
| 模式 | 描述 | 适用场景 |
|---|---|---|
| 发现问题 | 发现并修复 bug | 开发完成后的质量检查 |
| 回归测试 | 确保修复不引入新问题 | Bug 修复后验证 |
| 新功能测试 | 验证新功能符合预期 | 功能完成后 |
| 压力测试 | 边界条件和极端场景 | 发布前验证 |
输出：
- Bug 修复
- 回归测试用例（自动生成）
/browse — 真实浏览器控制
角色定位：QA 工程师，控制真实 Chromium 浏览器
核心能力：
命令示例：
$browse goto https://example.com # 导航
$browse click "Login" # 点击按钮
$browse fill "email" "test@test.com" # 填写表单
$browse screenshot # 截图
$browse console # 控制台日志
技术细节：
- 约 100-200ms 命令延迟
- 持久化状态（登录、Cookie）
- 支持 Playwright 所有定位符
/cso — Chief Security Officer
角色定位：首席安全官，OWASP + STRIDE 审计
审计维度：
OWASP Top 10：
├── A01 失效的访问控制
├── A02 加密失败
├── A03 注入
├── A04 不安全的设计
├── A05 安全配置错误
├── A06 易受攻击的过时组件
├── A07 身份识别与身份验证失败
├── A08 数据完整性失败
├── A09 安全日志和监控失败
└── A10 服务器端请求伪造
STRIDE 模型：
├── Spoofing（欺骗）
├── Tampering（篡改）
├── Repudiation（抵赖）
├── Information Disclosure（信息泄露）
├── Denial of Service（拒绝服务）
└── Elevation of Privilege（权限提升）
4.5 发布与部署（Ship 阶段）
/ship — Release Engineer
角色定位：发布工程师，标准化发布流程
流程步骤：
/land-and-deploy — 合并到生产
角色定位：发布工程师，合并 PR 并验证
执行步骤：
/canary — SRE 金丝雀监控
角色定位：SRE，部署后监控循环
监控指标：
- 错误率
- 延迟（P50/P95/P99）
- Core Web Vitals
- 业务指标异常
触发条件：检测到性能回归或错误率上升，自动告警
4.6 知识与回顾（Reflect 阶段）
/learn — 跨会话记忆
角色定位：团队记忆，管理项目特定知识
知识类型：
架构决策：
├── 为什么选择这个数据库？
├── 缓存策略是什么？
└── 第三方服务集成原因
约定规范：
├── 代码风格指南
├── 命名规范
└── 提交信息格式
团队流程：
├── 发布检查清单
├── 紧急修复流程
└── On-call 轮值表
使用方式：
/learn "我们的数据库是 PostgreSQL，因为我们需要事务支持"
↓
下次会话自动记住并应用
/retro — Eng Manager 周回顾
角色定位：工程经理，团队感知回顾
回顾维度：
1. 指标分析
├── 代码产出量
├── Bug 数量趋势
├── 交付周期
└── 技术债务变化
2. 个人分析
├── 工作满意度
├── 阻塞因素
├── 学习成长
└── 下周计划
3. 团队洞察
├── 协作效率
├── 沟通痛点
└── 改进建议
4.7 技能一览表
| 阶段 | 技能 | 角色 | 核心职能 |
|---|---|---|---|
| Think | /office-hours |
YC Partner | 产品追问 |
/plan-ceo-review |
CEO | 战略范围 | |
| Plan | /autoplan |
Pipeline | 一键审查 |
/plan-eng-review |
EM | 架构锁定 | |
/plan-design-review |
Designer | 设计评审 | |
/design-shotgun |
Explorer | 设计探索 | |
/design-html |
Design Eng | 原生 HTML | |
| Build | /review |
Staff Eng | 代码审查 |
/investigate |
Debugger | 根因调试 | |
/careful |
Guardrails | 安全警告 | |
/freeze |
Edit Lock | 边界锁定 | |
| Test | /qa |
QA Lead | 测试验证 |
/browse |
Browser | 浏览器控制 | |
/cso |
CSO | 安全审计 | |
| Ship | /ship |
Release Eng | 发布流程 |
/land-and-deploy |
Release Eng | 合并部署 | |
/canary |
SRE | 金丝雀监控 | |
| Reflect | /learn |
Memory | 知识管理 |
/retro |
EM | 团队回顾 |
5. 快速入门：30 秒安装
5.1 前提条件
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Claude Code | 最新版 | AI 编程工具 |
| Git | 任意版本 | 代码管理 |
| Bun | v1.0+ | 运行 gstack 核心 |
| Node.js | 任意版本 | 仅 Windows 需要 |
5.2 单人安装
# Step 1: 克隆仓库
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
# Step 2: 运行安装脚本
cd ~/.claude/skills/gstack && ./setup
# Step 3: 配置 CLAUDE.md
# 将 setup 输出中的 gstack 配置段添加到 ~/.claude/CLAUDE.md
5.3 团队安装（推荐）
# 安装并初始化团队配置
(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"
团队模式优势：
- 所有成员使用统一的 gstack 配置
- 确保团队遵循相同的工程流程
- 知识管理跨成员共享
5.4 其他 AI 代理安装
| 代理 | 安装命令 |
|---|---|
| OpenAI Codex CLI | ./setup --host codex |
| OpenCode | ./setup --host opencode |
| Cursor | ./setup --host cursor |
| Factory Droid | ./setup --host factory-droid |
| Slate | ./setup --host slate |
| Kiro | ./setup --host kiro |
| Hermes | ./setup --host hermes |
| GBrain | ./setup --host gbrain |
5.5 验证安装
安装完成后，在 Claude Code 中运行：
/office-hours
如果看到 YC Office Hours 的欢迎信息和问题清单，说明安装成功。
5.6 禁用遥测（可选）
export GSTACK_TELEMETRY=false
遥测内容（默认开启）：
- 技能名称、耗时、成败
- 版本号、操作系统
绝不发送：代码、文件路径、仓库名、提示词
6. 实战演示：从想法到部署
场景：开发一个"个人待办清单"应用
Step 1: Think — 产品思考
你输入：
我想做一个个人待办清单应用
gstack 激活 /office-hours：
🎯 YC Office Hours 开始了！
在开始之前，我需要问你 6 个关键问题：
1. **问题定义**
你在解决什么问题？个人待办管理有什么痛点？
2. **现有方案**
目前你（或目标用户）如何管理待办？
（纸笔？系统备忘录？其他 App？）
3. **差异化**
你的方案有何不同？为什么现在可行？
4. **成功指标**
如何衡量产品成功？
（日活？完成率？用户留存？）
5. **商业模式**
如何变现？
（免费增值？订阅？一次性购买？）
6. **竞争格局**
你的竞争对手是谁？为什么你能赢？
请回答这些问题。
你的回答：
- 痛点：现有 Todo App 太复杂，我只需要简单功能
- 现有方案：苹果备忘录 + 系统提醒
- 差异化：极简、无广告、本地优先
- 指标：7 日留存
- 模式：免费 + 可选 Pro 功能
- 竞争：Things 3、OmniFocus 太贵，Apple Reminders 太基础
/office-hours 输出设计文档：
# 个人待办清单 - 产品设计
## 核心价值主张
极简、本地优先、无广告的个人待办管理
## MVP 范围
- [ ] 添加待办（标题 + 截止日期）
- [ ] 完成待办
- [ ] 删除待办
- [ ] 列表视图
- [ ] 本地存储（IndexedDB）
## 不做
- [ ] 团队协作
- [ ] 云同步
- [ ] 提醒通知
- [ ] 标签/分类
## 成功指标
- 7 日留存 > 40%
- 平均每用户每日添加 2 条待办
Step 2: Plan — 架构设计
设计确认后，运行 /autoplan：
🚀 启动 autoplan 审查流程...
1/3: CEO 视角审查
范围决策：MVP 模式（保持）
理由：先验证核心假设，不做过度设计
2/3: 设计视角审查
UI 框架：单页应用 + 极简设计
设计系统：自定义 CSS，不引入框架依赖
3/3: 工程视角审查
技术选型：Vanilla JS + IndexedDB
数据模型：{ id, title, dueDate, completed, createdAt }
测试计划：单元测试 + E2E 测试
✅ 审查完成，仅呈现品味决策：
- 极简风格，参考 Linear 的设计语言
- 单文件部署，无需构建步骤
Step 3: Build — 代码实现
gstack 激活 Claude Code 执行计划：
📋 开始实现...
任务 1/5: 创建 HTML 结构
✅ 完成
任务 2/5: 实现 IndexedDB 存储层
🔍 代码审查：发现一处潜在的并发写入问题
✅ 已修复
任务 3/5: 实现 CRUD 操作
✅ 完成
任务 4/5: 添加样式
✅ 完成
任务 5/5: E2E 测试
🔄 运行中...
Step 4: Review — 代码审查
/review 自动执行：
🔍 运行代码审查...
发现 2 个问题：
🔴 阻塞性：无
🟡 严重：
- IndexedDB 缺少错误处理
- 未处理空标题的待办
🟢 建议：
- 添加键盘快捷键支持
🔧 自动修复严重问题...
✅ 修复完成
Step 5: Test — 质量验证
/qa 执行测试：
🧪 运行 QA 测试...
模式：E2E 测试（browse 模式）
测试场景：
✅ 添加新待办
✅ 完成待办
✅ 删除待办
✅ 空列表提示
✅ 长标题截断
✅ 截止日期选择器
发现 1 个 bug：
🟡 日期选择器在 Safari 下样式异常
🔧 修复中...
✅ 修复完成
生成回归测试用例：
- tests/e2e/date-picker.spec.ts
Step 6: Ship — 发布流程
/ship 执行发布：
🚀 开始发布流程...
1. 同步代码
✅ git pull 成功
2. 运行测试
✅ 所有测试通过
3. 覆盖审计
✅ 核心逻辑 100% 覆盖
4. 推送代码
✅ 已推送到 origin/main
5. 创建 PR
✅ PR #1: feat: MVP 个人待办清单
📋 PR 链接：https://github.com/your/repo/pull/1
Step 7: Deploy — 部署验证
/land-and-deploy 执行部署：
🚀 开始部署流程...
1. 合并 PR
✅ 已合并到 main
2. 等待 CI
✅ CI 通过 (3m 12s)
3. 部署到生产
✅ 部署完成
4. 验证生产健康
✅ 健康检查通过
5. 启动金丝雀监控
🔄 监控中...（5 分钟）
✅ 无异常检测
Step 8: Retro — 回顾总结
/retro 生成回顾：
📊 周回顾报告
指标概览：
- 代码行数：+892
- PR 数量：3
- Bug 修复：2
- 测试覆盖率：94%
个人洞察：
- 极简设计原则执行良好
- IndexedDB 学习曲线比预期高
- 下周计划：完成高级筛选功能
团队建议：
- 建立组件库，减少重复代码
- 添加性能监控
7. 架构深度解析
7.1 核心架构：守护进程模型
gstack 的核心技术是长期运行的 Chromium 守护进程：
┌─────────────┐
│ Claude Code │ ← CLI（发起命令）
└──────┬──────┘
│ HTTP POST (~100-200ms)
↓
┌─────────────┐
│ Bun Server │ ← 状态文件记录 PID、端口、令牌
└──────┬──────┘
│ CDP (Chrome DevTools Protocol)
↓
┌─────────────┐
│ Chromium │ ← 持久化标签页、Cookie、登录会话
└─────────────┘
为什么用守护进程？
| 设计选择 | 原因 | 效果 |
|---|---|---|
| 持久状态 | 一次登录，持续有效 | 无需重复认证 |
| 快速响应 | 首次后 ~100ms/命令 | 流畅交互体验 |
| 自动生命周期 | 空闲 30 分钟自动关闭 | 节省资源 |
7.2 为什么选择 Bun？
| 原因 | 说明 |
|---|---|
| 编译型二进制 | bun build --compile 生成 ~58MB 单文件，无需 node_modules |
| 原生 SQLite | 直接读取 Chromium Cookie 数据库，无需第三方 addon |
| 原生 TypeScript | 开发时无需编译步骤 |
| 内置 HTTP 服务器 | Bun.serve() 简洁高效，约 10 条路由 |
7.3 安全模型
双端口架构 (v1.6.0.0)
本地监听器：127.0.0.1:LOCAL_PORT
└── 完整命令面（内部使用）
隧道监听器：127.0.0.1:TUNNEL_PORT
└── 仅白名单端点（ngrok 转发）
安全属性：物理端口隔离，隧道调用者无法访问敏感端点。
Bearer Token 认证
# 每个会话生成随机 UUID 令牌
# 写入 .gstack/browse.json（权限 0o600）
# 所有请求必须携带 Authorization: Bearer <token>
Cookie 安全
1. Keychain 访问需用户手动授权
2. 解密在内存中进行，从不写入磁盘
3. 数据库以只读方式打开（复制到临时文件）
4. 密钥按会话缓存，服务器关闭后消失
5. 日志中不记录 Cookie 值
7.4 Ref 系统：AI 如何定位页面元素
传统方式：
await page.click('#app > div:nth-child(2) > button.save-btn');
gstack Ref 方式：
// AI 调用 $B snapshot -i 获取元素列表
// 每个元素被分配 ref：@e1, @e2, @c1, @c2...
// AI 使用语义化定位：
await $B.click('@e5'); // 点击"保存"按钮
工作原理：
1. $B snapshot -i 调用 Playwright page.accessibility.snapshot()
2. 解析器遍历 ARIA 树，分配序号 refs
3. 为每个 ref 构建 Playwright Locator
4. 存储 Map<string, RefEntry> 于 BrowserManager
优势：
- 无需编写脆弱的 CSS 选择器
- 自适应 UI 变化
- 语义化，易于 AI 理解
7.5 有意不实现的功能
| 功能 | 原因 |
|---|---|
| WebSocket 流式传输 | HTTP 请求/响应更简单、可调试 |
| MCP 协议 | 增加 JSON schema 开销和持久连接需求 |
| 多用户支持 | 每个工作区一个服务器、一个用户 |
| Windows/Linux Cookie 解密 | 仅支持 macOS Keychain（Cookie 加密平台差异大） |
| iframe 自动发现 | 需显式使用 $B frame 进入帧上下文 |
8. 最佳实践与安全指南
8.1 有效使用 gstack
| ✅ 推荐 | ❌ 避免 |
|---|---|
先运行 /office-hours 明确需求 |
直接让 AI 写代码 |
使用 /autoplan 进行完整审查 |
只做部分审查 |
定期运行 /qa |
跳过测试直接发布 |
使用 /learn 积累知识 |
每次重新解释项目背景 |
查看 /retro 回顾改进 |
做完就结束，不复盘 |
8.2 调试最佳实践
使用 /investigate 的正确姿势：
❌ 错误：直接问"为什么报错"
✅ 正确：先描述现象，/investigate 会引导你系统调查
流程：
1. 描述现象："登录按钮点击后没反应"
2. /investigate 提问："能复现吗？"
3. 回答问题，逐步深入
4. 最终找到根因
8.3 安全使用指南
使用 /careful / /guard
# 在修改危险区域前启用
/guard
# 调试完成后解除
/unfreeze
适用场景：
- 修改核心模块时锁定其他代码
- 调试时防止"顺手改一下"
- 多人协作时保护关键代码
Cookie 安全
- 只在使用
$B cookie-picker时授权 Keychain 访问 - 不在日志中查找敏感信息
- 共享工作区时注意 Cookie 泄露
8.4 隐私保护
gstack 默认关闭遥测，即使开启也绝不发送：
- 代码内容
- 文件路径
- 仓库名
- 提示词
本地分析命令：
gstack-analytics # 查看本地使用仪表板，无需联网
9. 方法论总结：如何写好工具教程
9.1 本教程的教学设计框架
| 环节 | 设计 | 理论依据 |
|---|---|---|
| 痛点导入 | 从独立开发者的困境切入 | 成人学习理论：动机来自解决真实问题 |
| 概念澄清 | 用"不是替代，是增强"定位工具 | 认知心理学：消除误解比灌输定义更有效 |
| 理念优先 | 先讲 ETHOS，再讲技能 | 建构主义：理解"为什么"才能正确"怎么做" |
| 角色映射 | 每个技能对应一个工程角色 | 情境学习：抽象概念依附具体角色 |
| 完整流程 | Think → Plan → Build → Review → Test → Ship → Retro | 经验学习圈：做中学 |
| 实战演示 | 从想法到部署的完整案例 | 案例学习：建立整体认知 |
9.2 教程结构模板
1. 痛点导入（5 分钟）
└── 读者面临的真实困境
2. 工具定位（5 分钟）
└── 这个工具是什么，在工具链中的位置
3. 核心理念（10 分钟）
└── 创始人的工程哲学，为什么要这样做
4. 技能详解（20 分钟）
└── 按阶段/角色分类，逐个讲解
5. 快速安装（5 分钟）
└── 30 秒跑起来的最小示例
6. 实战演示（30 分钟）
└── 端到端案例，覆盖完整流程
7. 架构解析（10 分钟）
└── 技术实现原理，满足技术读者
8. 最佳实践（5 分钟）
└── 经验总结和避坑指南
9. 方法论总结（5 分钟）
└── 教程本身的设计框架，便于复用
9.3 写作技巧清单
用类比降低理解门槛
- "把 Claude Code 变成虚拟工程团队"
- "守护进程 = 永不关闭的浏览器标签"
用表格建立结构
- 技能一览表
- 流程对比表
- 原则对照表
用代码展示能力
- 每个核心技能都有命令示例
- 包含边界条件和错误处理
用案例串联知识
- 完整的开发流程演示
- 从想法到部署的端到端
用方法论指导方法论
- 教程结尾总结教程本身的设计
- 便于读者未来写自己的教程
附录
A. 资源链接
| 资源 | 链接/位置 |
|---|---|
| GitHub 仓库 | https://github.com/garrytan/gstack |
| ETHOS（哲学） | ETHOS.md |
| 架构文档 | ARCHITECTURE.md |
| 技能详解 | docs/skills.md |
| 浏览器命令 | BROWSER.md |
B. 与 Superpowers 对比
| 维度 | Superpowers | gstack |
|---|---|---|
| 定位 | AI 方法论框架 | AI 软件工厂 |
| 核心能力 | 流程规范 | 完整工程团队角色 |
| 浏览器支持 | 无 | 有（browse） |
| 安全机制 | 基础 | 高级（双端口、Token、白名单） |
| 知识管理 | 基础 | GBrain 跨会话持久化 |
| 适用场景 | 单人开发流程 | 团队协作流程 |
| 学习曲线 | 低 | 中 |
C. 版本历史
- v6.x - 最新版本
- 查看完整变更：CHANGELOG.md
教程版本：v1.0
最后更新：2026-07-01
作者：AI 应用工程师 / 教育专家
对标教程：Superpowers 教程 v1.0