Gstack Skills 使用指南

基于 54 个 Gstack Skill 的完整 SKILL.md 文档整理。所有流程均来自官方文档。

体系概览

Gstack 是一套完整的软件开发框架，覆盖从想法到上线的全生命周期。54 个 Skill 共享统一的 preamble 基础设施（更新检查、会话跟踪、遥测、上下文恢复、学习记录等）。

核心基础设施

组件	说明
`$B` (browse daemon)	无头 Chromium 浏览器引擎，browse/scrape/canary/benchmark/diagram/qa-only/design-review/devex-review 共用
`$D` (designer)	设计变体生成器，design-shotgun/design-html/design-review 共用
`$P` (make-pdf)	Markdown→PDF 引擎
gbrain	知识库系统，setup-gbrain/sync-gbrain 管理
`gstack-*` CLI 工具	版本管理、路径解析、学习记录、review 日志等

场景一：从想法到上线（完整流程）

这是 Gstack 的主工作流链路。

第 1 步：探索想法

1	/office-hours

两种模式：

Startup 模式（产品诊断）—— 6 个强制性问题，一次一个：

Q1: 需求真实性
Q2: 现状是什么
Q3: 绝望的具体性
Q4: 最窄切入点
Q5: 观察与惊喜
Q6: 未来适配

Builder 模式（设计伙伴）—— 5 个生成性问题：

最酷的版本、给谁看、最快路径、最接近的东西、10x 版本

输出：设计文档 + 创始人信号合成 + 可执行的下一步。

第 2 步：生成 Spec

/spec

5 个阶段：

Phase 1：理解 Why（5W 追问）
Phase 2：确定范围和边界（Out of Scope、MVP 切割）
Phase 3：技术审查（硬性门：必须先读实际代码再提问。覆盖数据模型/API/后台/UI/基础设施/测试）
Phase 4：草案审查，迭代直到确认
Phase 5：提交 GitHub Issue + 本地存档

可选：--execute flag 在独立 worktree 中启动实现 Agent。

第 3 步：计划审查（四层递进）

可以单独运行，也可以用 /autoplan 一次跑完：

/autoplan

自动顺序执行四项审查，使用 6 项决策原则（完备性优先、煮沸湖泊、务实、DRY、显式优于巧妙、偏向行动）自动判定。

3a. CEO 审查

1	/plan-ceo-review

做什么：压力测试战略和范围。挑战前提、找 10x 产品、扩展视野。

流程：

前提挑战：这是正确的问题吗？什么都不做会怎样？
梦想状态映射：当前 → 此计划 → 12 个月理想
强制生成 2-3 个替代方案，用户必须选择
时间询问：映射第 1 小时到第 6+ 小时的决策

四种模式：范围扩展 / 选择性扩展 / 保持范围 / 范围缩减

3b. 工程审查

1	/plan-eng-review

做什么：锁定实现计划。在写代码之前发现架构问题。

前置硬门：第一个工具调用必须是 AskUserQuestion 确认审查范围。

复杂度检查：触及 8+ 文件或 2+ 新类 → 立即停止，询问用户。

4 个审查维度：架构、代码质量、测试、性能（每维度最多 8 个问题）

3c. 设计计划审查

1	/plan-design-review

做什么：在实现之前审查设计决策。0-10 评分法。

关键步骤：

初始设计评分（现在几分，满分 10 分是什么样）
默认生成视觉 mockup（$D variants）
开启对比面板，收集反馈，迭代
7 个设计维度逐一审查

3d. 开发者体验审查

1	/plan-devex-review

做什么：审查 API/CLI/SDK/平台的开发者体验。

前置调查（评分前先收集证据）：

开发者画像询问
共情叙事（150-250 字第一人称，走完真实的上手路径）
竞争 DX 基准测试
魔法时刻设计
开发者旅程追踪（Discover→Install→Hello World→Real Usage→Debug→Upgrade）

第 4 步：发布

/ship

21 步全自动流程：

检测平台和 base 分支
展示 Review Readiness Dashboard
合并 base 分支到 feature 分支
4-6. 运行测试
测试覆盖率审计
计划完成度审计和范围漂移检测
Review Army：并行派遣 7 个专家子 Agent（Testing/Maintainability/Security/Performance/Data Migration/API Contract/Design）
对抗性审查（Codex + Claude 子 Agent）
版本号升级（gstack-version-bump：分类→决定级别→队列感知选择）
CHANGELOG 更新
TODOS.md 自动更新
可二分提交（squash WIP commits，逻辑分组）
验证门（代码有改动则重新验证）
推送前凭据检查
文档同步和 PR 创建
持久化发布指标

第 5 步：合入 + 部署 + 验证

1	/land-and-deploy

10 步：

CI 状态检查
合并冲突检测
等待 CI（超时 15 分钟）
VERSION 漂移检测
合入前就绪门（review 新鲜度、测试结果、PR body 准确性、文档检查）
合并 PR（gh pr merge --auto --delete-branch）
部署策略检测（GitHub Actions / Fly.io / Vercel / Netlify / 自定义）
等待部署
金丝雀验证：浏览器健康检查（页面加载/控制台错误/性能/内容/截图）
部署报告

场景二：质量保障

QA 测试

/qa

完整的”测试→发现 bug→修复→验证”循环。

/qa-only

仅报告不修复。系统化测试 Web 应用，输出结构化报告。

流程：

验证页面加载
遍历所有可达页面
每页：截图、控制台错误、交互元素、表单、导航、状态（空/加载/错误/溢出）
即时记录问题（交互 bug=前后截图+快照+复现步骤；静态 bug=单张标注截图+描述）
计算健康分数（Console 15% / Links 10% / Visual 10% / Functional 20% / UX 15% / Performance 10% / Content 5% / Accessibility 15%）

模式：Full（5-10 页）/ Quick（30 秒冒烟）/ Regression（对比基线）/ Diff-aware（自动检测分支影响范围）

代码审查

/review

审查军队：并行派遣 7 个专家子 Agent 做专项检查。

关键 pass：SQL 安全、竞态条件、LLM 信任边界、Shell 注入、枚举完整性。

对抗性审查（始终开启）：Codex 对抗性挑战 + Claude 子 Agent + Codex 结构化审查（200+ 行 diff 时）。

安全审计

/cso

15 个阶段的完整安全审计。

两种模式：

Daily：零噪音，8/10 置信度门
Comprehensive：月度深度扫描，2/10 门槛

覆盖：机密考古、依赖供应链、CI/CD 管道、基础设施、集成安全、LLM/AI 安全、Skill 供应链、OWASP Top 10、STRIDE 威胁建模、主动验证。

参数：--comprehensive / --infra / --code / --skills / --diff / --supply-chain / --owasp / --scope auth

性能

1	/benchmark <url>

9 个阶段：页面发现→性能数据采集→基线捕获→对比→最慢资源分析→性能预算检查→趋势分析→保存报告。

回归阈值：时间 >50% 增加或 >500ms 绝对值=REGRESSION；>20%=WARNING。

1	/benchmark-models

跨模型基准测试（Claude vs GPT vs Gemini）。选 prompt → 选模型 → 跑 → 输出最快/最便宜/最高质量的对比表。

场景三：设计体系

创建设计系统

1	/design-consultation

流程：

产品上下文（一句话记住什么）
行业调研（WebSearch 5-10 个竞品，browse 截图分析前 3-5 个）
三层合成（Layer 1: 已验证 / Layer 2: 新流行 / Layer 3: 第一性原理）
设计外部声音（Codex + Claude 并行设计方案）
构建完整设计系统 → 字体+颜色预览 → 写入 DESIGN.md

探索设计变体

1	/design-shotgun

流程：

收集上下文（Who/Job/Existing/Flow/Edge Cases）
读取消fe偏好档案
并行 Agent 生成 N 个变体 PNG
对比面板 + 反馈循环
保存 approved.json

生成生产级 HTML

1	/design-html

4 种模式：从 approved.json / 从 CEO plan / 从零开始 / 自由形式。

生成 Pretext 原生的自包含 HTML（CSS 自定义属性、Google Fonts、语义 HTML5、响应式断点、ARIA、暗色模式）。AI slop 黑名单过滤。Python 实时预览服务器。最多 10 次迭代。

设计审查

1	/design-review

10 个阶段：第一印象→设计系统提取→逐页视觉审查→交互流审查→跨页一致性→报告→外部声音→分类→修复循环→最终审查→TODOS 更新。

10 类检查清单（~80 项）：视觉层级/排版/颜色与对比度/间距与布局/交互状态/响应式设计/动效/内容与文案/AI Slop 检测（10 个反模式+11 个黑名单）/性能。

场景四：调试与诊断

根因分析

1	/investigate

铁律：没有根因调查，绝不修复。

5 个阶段：

根因调查：收集症状→读代码→追溯数据流→查近期变更→确定性复现→输出根因假设
模式分析：匹配已知模式（竞态/null 传播/状态损坏/集成失败/配置漂移/过期缓存）
假设检验：临时日志/断言验证。3 次假设失败则 AskUserQuestion（继续/升级/加日志）
实现修复：最小 diff + 回归测试
验证与报告：结构化 DEBUG REPORT（症状/根因/修复 file:line/证据/回归测试/状态）

诊断循环

1	/diagnosing-bugs

6 阶段（mattpocock skill，与 gstack /investigate 互补）：

构建反馈回路（按优先级尝试：失败测试→curl→CLI→无头浏览器→trace 回放→harness→模糊测试→bisect→对比→人工）
复现+最小化
提出 3-5 个排序的可证伪假设
探测验证
修复+回归测试
清理+复盘

场景五：浏览器自动化

无头浏览器

/browse

底层浏览器引擎。提供 14 种核心 QA 模式 + 完整命令参考（导航/读取/提取/交互/检查/视觉/快照/元信息/标签/服务器）。

$B goto <url> / $B snapshot -i / $B console --errors / $B perf / $B screenshot 等。

数据抓取

/scrape

流程：

确定抓取意图
拒绝写入意图（submit/post/send/login/click/fill/delete/create 等→路由到 /automate）
匹配已有 browser-skill → $B skill run
无匹配则原型：$B goto → $B snapshot --text → $B html → 迭代 selector
输出 JSON → 提示 /skillify

固化为永久 Skill

/skillify

把最近成功的 /scrape 流程固化为永久 browser-skill：

提取名称+触发器+host
合成 script.ts（导入 browse-client，导出 parseFromHtml + Output 接口）
捕获 fixture HTML
写测试文件（至少一个两星断言）
原子写入→测试→批准→提交→验证

浏览器配对

1	/pair-agent

生成一次性 setup key，让其他 AI Agent（OpenClaw/Codex/Cursor/Claude Code）共享你的浏览器。每个 Agent 独立标签页，作用域隔离。

导入 Cookies

1	/setup-browser-cookies

从真实 Chromium 浏览器导入 cookies → 无头浏览会话（用于需要登录的测试）。

场景六：文档

生成文档

1	/document-generate

Diataxis 四象限框架：

Reference（基础，先写）：API/接口、选项/配置、示例、相关链接
Explanation（回答”为什么”）：问题、方法、权衡、替代方案
How-To Guides（任务导向）：标题”How to”开头、前置条件、可操作步骤、验证、故障排除
Tutorials（学习导向）：3 步内完成第一个结果

质量自检：准确性门（代码示例有效、API 描述匹配）、完整性门（100% 公共接口在 Reference、前 3 个任务在 How-to）、语调门。

发布后文档更新

1	/document-release

在 /ship 之后、PR 合并之前运行。

流程：diff 分析→Diataxis 覆盖地图→审查每个文档文件→打磨 CHANGELOG（绝不覆写）→TODO 清理→VERSION bump→提交。

发现覆盖缺口时建议运行 /document-generate。

生成图表

/diagram

英文描述→三元组输出：

.mmd — mermaid 源码
.excalidraw — 可编辑场景（仅 flowchart）
.svg / .png — 渲染图

生成 PDF

/make-pdf

Markdown→PDF（通过 Chromium + Paged.js）。

模式：80% 场景（memo/letter）、出版模式（封面+TOC+章节）、草稿水印、无品牌模式、HTML/DOCX 导出、CI 严格模式。支持 ```mermaid fence 嵌入。

场景七：运维与监控

金丝雀监控

1	/canary <url>

7 个阶段：

创建目录结构
基线捕获（--baseline 模式：部署前截屏）
页面发现（自动提取 top 5 导航链接）
部署前快照
持续监控循环（每 60 秒检查：页面加载/控制台错误/性能）
健康报告（HEALTHY/DEGRADED/BROKEN）
基线更新

告警级别：CRITICAL（页面加载失败）、HIGH（新控制台错误）、MEDIUM（性能回归>2x 基线）、LOW（新 404）。

部署队列仪表盘

1	/landing-report

只读队列仪表盘：当前 VERSION、哪些 PR 占用了版本槽、兄弟 Conductor 工作空间、冲突警告、/ship 下一个会选什么槽位。

场景八：安全与管控

危险命令警告

/careful

Bash PreToolUse hook。保护 8 类危险命令（rm -rf、DROP TABLE、TRUNCATE、git push -f、git reset --hard、git checkout .、kubectl delete、docker rm -f）。安全例外：node_modules、.next、dist 等。

目录编辑限制

/freeze

Edit/Write PreToolUse hooks。限制所有文件编辑到指定目录。Read/Bash/Glob/Grep 不受影响。

/unfreeze

清除 freeze 边界。

/guard

/careful + /freeze 二合一。最大安全模式。

上下文保存与恢复

1	/context-save [标题]

捕获 git 状态、已做决策、剩余工作 → 写入 ~/.gstack/projects/<slug>/checkpoints/。

1	/context-restore

加载最近保存的上下文（跨分支默认）。分支不匹配时警告。提供继续工作/查看完整文件/只需上下文的选项。

场景九：工程管理

工程回顾

/retro

14 步：12 路并行 git 命令收集原始数据→计算指标（功能数/提交数/LOC/贡献者/PR 数/测试比/版本范围）→提交时间分布→工作会话检测（45 分钟间隔阈值）→提交类型分布→热点分析→PR 大小分布→专注分数+本周之舰→团队成员分析→周环比趋势→连续记录追踪→加载历史对比→保存 JSON 快照→叙述性报告（3000-4500 字）。

全局模式：/retro global 跨项目回顾。

代码健康仪表盘

/health

6 步：检测健康栈（类型检查/代码检查/测试/死代码/Shell 检查/gbrain）→运行工具→打分（类型检查 22%、Lint 18%、测试 28%、死代码 13%、Shell 9%、gbrain 10%）→展示仪表盘→持久化历史→趋势分析+建议。

学习管理

/learn

命令：

/learn — 显示最近 20 条学习
/learn search <query> — 搜索
/learn prune — 清理过时/矛盾条目
/learn export — 导出 markdown
/learn stats — 统计
/learn add — 手动添加

第二意见（Codex）

/codex

三种模式：

Review：独立 diff 审查，PASS/FAIL 门（[P1] 发现=FAIL）
Challenge：对抗模式，试图破坏你的代码
Consult：提问，有会话连续性

自我调优

1	/plan-tune

功能：问题敏感度自调优（v1 观察式）。

子功能：查看 profile / 审查问题日志 / 设置偏好（never-ask/always-ask）/ 编辑声明 profile / 显示差距 / 统计 / 审计未标记问题 / Dream 循环审查

升级

1	/gstack-upgrade

检测安装类型（global-git/local-git/vendored）→ stash→fetch→reset→运行 setup→执行版本迁移脚本→展示 CHANGELOG 5-7 条→恢复原 skill。

场景十：iOS 开发

iOS QA

1	/ios-qa --source <app-dir>

架构：Mac daemon (bun/TS) ↔ USB CoreDevice IPv6 隧道 ↔ iPhone StateServer。

流程：

读 Swift 源码，识别 @Observable + @Snapshotable 类
代码生成 typed state accessor
添加 DebugBridge SPM 依赖→构建→部署→启动→启动 daemon→auth token rotation
视觉驱动 Agent 循环：截图→读元素→读状态快照→决策→执行 tap/swipe/type→重新截图→对比→记录 bug

iOS Bug 修复

/ios-fix

铁律：没有复现快照，绝不修复。

复现：读 /ios-qa 发现→POST /state/restore 恢复状态→截图对比
定位：追踪代码路径（视图→ViewModel→数据流→状态变更）
修复：最小 Swift diff→xcodebuild→daemon 自动重连
验证：状态恢复→新截图对比
回归测试：写 test/fixtures/ios-fix/<bug>.test.ts

其他

/ios-clean — 移除所有 DebugBridge 和 #if DEBUG 接线
/ios-sync — 基于最新 gstack 模板重新生成 debug bridge
/ios-design-review — 真机视觉设计审查（10 维度评分）

场景十一：知识管理 (gbrain)

设置

1	/setup-gbrain

6 条路径：Supabase 已有 URL / 自动 provision / 手动 Supabase / PGLite 本地 / Remote MCP / 切换引擎。

安装 gbrain CLI→初始化 brain→注册 MCP→设置 per-remote 策略→artifacts 同步→transcript 收录→写入 CLAUDE.md→冒烟测试。

同步

1	/sync-gbrain

5 步：状态探测→本地引擎预检→运行编排器（code→memory→brain-sync 三阶段）→代码索引健康检查→刷新 CLAUDE.md 中的搜索指引。

参数：--full / --dream / --code-only / --dry-run / --refresh-cache / --audit

技能调用关系图

                    ┌─────────────────────────────────────┐
                    │         共享基础设施层                │
                    │  $B (browse daemon)                  │
                    │  $D (designer)    $P (make-pdf)     │
                    │  gbrain            gstack-* CLI      │
                    └─────────────────────────────────────┘
                                      │
    ┌─────────────┬─────────────┬─────┴─────┬─────────────┐
    │             │             │           │             │
    ▼             ▼             ▼           ▼             ▼
  设计线        开发线        质量线      运维线        iOS线
    │             │             │           │             │
design-      office-hours    browse      canary       ios-qa
consultation     │          scrape     benchmark     ios-fix
    │           spec        qa-only    landing-      ios-clean
design-      plan-ceo-       /qa        report       ios-sync
shotgun       review       /review    land-and-      ios-design
    │        plan-eng-    investigate   deploy       -review
design-html   review     diagnosing-     /ship
    │        plan-design-   bugs       context-*
design-       review        /cso       setup-deploy
review       plan-devex-   /health
               review     /codex
            autoplan      /learn
            /retro

设计线

1	design-consultation` → `design-shotgun` → `design-html` → `design-review

开发线

1	office-hours` → `spec` → `plan-*` → `ship` → `land-and-deploy

质量线

browse (引擎) → qa-only (仅报告) / qa (测试-修复-验证) / scrape (数据提取)
review (代码审查) / investigate (根因分析) / cso (安全审计)

运维线

canary (金丝雀) / benchmark (性能) / landing-report (队列仪表盘)

快速路由参考

不知道用哪个 Gstack Skill？用 /_gstack-command 或参考下表：

你想做什么	用这个
探索新想法	`/office-hours`
生成 Spec/Issue	`/spec`
战略审查	`/plan-ceo-review`
架构审查	`/plan-eng-review`
设计审查（计划）	`/plan-design-review`
DX 审查（计划）	`/plan-devex-review`
全部审查自动跑	`/autoplan`
创建设计系统	`/design-consultation`
探索 UI 变体	`/design-shotgun`
生成 HTML	`/design-html`
视觉 QA（线上）	`/design-review`
测试网站找 bug	`/qa` 或 `/qa-only`
调试	`/investigate` 或 `/diagnosing-bugs`
代码审查	`/review`
安全审计	`/cso`
发布	`/ship`
合入+部署	`/land-and-deploy`
部署后监控	`/canary <url>`
性能测试	`/benchmark <url>`
模型对比	`/benchmark-models`
写文档	`/document-generate`
发布后更新文档	`/document-release`
画图	`/diagram`
生成 PDF	`/make-pdf`
数据抓取	`/scrape`
固化为 Skill	`/skillify`
工程回顾	`/retro`
代码健康	`/health`
管理学习	`/learn`
危险命令保护	`/careful` / `/guard`
限制编辑范围	`/freeze` / `/unfreeze`
保存/恢复进度	`/context-save` / `/context-restore`
第二意见	`/codex`
调优偏好	`/plan-tune`
iOS 测试	`/ios-qa`
设置知识库	`/setup-gbrain`
升级 Gstack	`/gstack-upgrade`