gstack 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

gstack 是一个面向 Claude Code 及其他 AI 编程代理的开源工作流工具集。根据 README，它把产品规划、架构评审、设计检查、代码审查、浏览器测试、安全审计、发布和文档工作组织成可通过斜杠命令触发的角色化技能。

仓库资料显示，项目主要使用 TypeScript，许可证为 MIT，默认分支为 main，当前 package.json 版本为 1.66.0.0。GitHub 仓库资料中的统计为 128205 个 Star 和 19293 个 Fork；这些数字会随仓库变化，不能视为固定指标。

• 核心交互方式：在 Claude Code 中调用以 / 开头的技能命令。
• 主要运行时：Bun 1.0 及以上；README 另列出 Git，Windows 环境还需要 Node.js。
• 浏览器能力：仓库提供无头浏览器（headless browser）相关命令和依赖。
• 自动化范围：从需求澄清、计划制定到评审、QA、发布和复盘。
• 适用前提：使用者需要明确授权代码仓库、测试环境、浏览器目标和部署操作的范围。

定位与目标用户

gstack 的定位不是独立的持续集成平台、项目管理系统或云端部署服务，而是把工程活动编排为 AI 编程代理可以执行的本地技能。它的价值集中在流程结构化：用户不必从空白提示开始，而是可以选择产品、工程、设计、QA 或发布角色对应的命令。

README 将目标用户分为创始人和 CEO、首次使用 Claude Code 的用户，以及希望对每个 PR 执行严格审查、QA 和发布自动化的技术负责人。根据仓库资料，项目作者还将其描述为自己的开源软件工厂；这属于 README 的作者陈述，不等同于独立验证的生产效率结论。

工作流定位

技能命令负责提出问题、读取项目上下文、生成计划或执行检查，具体结果取决于命令、当前仓库、代理能力和用户提供的输入。README 中给出的最小路径是先运行 /office-hours 描述产品，再对功能运行 /plan-ceo-review，对有改动的分支运行 /review，最后对测试或预发布 URL 运行 /qa。

这意味着 gstack 更适合已经使用 Git 和 AI 编程代理的开发流程。资料没有声明其提供团队权限系统、远程任务队列、制品仓库、部署基础设施或服务等级协议。

核心功能

核心功能由一组 Markdown 技能和浏览器、PDF 等辅助工具组成。每项技能的触发方式是对应的斜杠命令，输入通常包括当前代码仓库、用户问题、分支改动或测试 URL，输出则由命令任务决定；仓库资料没有给出所有技能统一的结构化返回协议。

产品与技术方案评审

/office-hours 用于描述正在构建的产品或问题；README 将它放在整个流程的入口位置。/plan-ceo-review 用于从产品和范围角度检查功能想法，/plan-eng-review 用于工程计划，/plan-design-review 用于设计计划，/design-consultation 和 /design-shotgun 用于设计相关讨论。

这些命令的触发条件是用户在 Claude Code 中显式调用它们。其输入来自对话和当前工程上下文，输出重点是问题澄清、范围判断或计划建议；README 没有提供每个命令的参数表、返回字段或确定性保证。

设计与前端检查

/design-html 面向 HTML 设计输出，/design-review 用于设计检查。README 将设计师角色描述为用于识别 AI 生成的低质量设计，但资料没有给出具体视觉规则、浏览器兼容矩阵或像素级验收标准。

运行这类命令时，输入可以是当前仓库中的页面或设计任务，实际可检查范围取决于项目文件和代理能够访问的上下文。若任务需要访问外部站点或登录态，应先完成授权和浏览器会话配置，不应把第三方生产数据直接交给未审查的自动化流程。

代码审查、发布与变更交付

/review 针对存在改动的分支执行审查，README 的快速开始将它放在计划之后。/ship、/land-and-deploy、/canary 和 /document-release 对应发布、合并部署、金丝雀流程及发布文档相关任务。

这些技能涉及 Git 分支、变更内容和发布环境，因此输入不仅是自然语言，还包括仓库状态和用户授权。仓库资料没有声明这些命令能够替代代码所有者审批、CI 门禁、云平台权限检查或回滚制度，发布类命令应仅在隔离的测试环境或经过明确批准的生产流程中执行。

QA、浏览器和调查

/qa 用于对 URL 执行质量保证测试，/qa-only 用于仅执行 QA，/browse 提供浏览器相关能力，/connect-chrome 和 /setup-browser-cookies 用于连接浏览器或配置 Cookie。README 要求在 CLAUDE.md 中使用 gstack 的 /browse 技能进行网页浏览，并明确不要使用 mcp__claude-in-chrome__* 工具。

浏览器工作流的输入可以是授权的测试 URL、页面状态或 Cookie 配置，输出是代理对页面行为的检查结果。package.json 列出了 Playwright、Puppeteer Core 和 Socks 等依赖，但资料没有说明每项依赖在具体命令中的调用关系，也没有提供固定端口、浏览器版本或并发限制。

安全审计、调试与工程维护

/cso 对应安全相关工作，README 将其描述为执行 OWASP 与 STRIDE 审计；/investigate 用于调查和根因分析，/retro 用于工程复盘，/benchmark 用于基准相关任务，/devex-review 和 /plan-devex-review 面向开发者体验。

/autoplan 用于自动规划，/codex 用于 Codex 相关工作，/careful、/freeze、/guard、/unfreeze 用于更谨慎的操作控制。由于资料没有给出这些技能的完整实现文件内容，不能据此推断它们具备强制访问控制、不可绕过的审批或安全审计认证。

系统架构与关键模块

从仓库资料可以确认的架构是“Claude Code 技能层＋TypeScript/Bun 工具层＋浏览器与文档辅助组件”。技能以 Markdown 形式存在，安装脚本将其部署到 Claude Code 的技能目录；package.json 则暴露命令行入口并管理浏览器、文档转换和模型评测相关依赖。

技能层

README 列出了包括 /office-hours、/review、/qa、/browse、/ship、/cso、/autoplan 和 /learn 在内的技能清单。安装时，用户需要把 gstack 章节加入 CLAUDE.md，并声明可用技能；团队模式还会把项目初始化配置提交到仓库。

资料称项目包含 23 个专家角色和 8 个能力工具，但没有在所给文件中提供逐项分类表，因此这里不对“23”和“8”进一步拆分。技能的实际提示词、输入输出和边界应以当前仓库对应技能文件为准。

浏览器与文档模块

package.json 的 bin 字段暴露了 browse 和 make-pdf 两个命令，分别指向 ./browse/dist/browse 与 ./make-pdf/dist/pdf。依赖列表包含 playwright、puppeteer-core、html-to-docx、marked 和 xterm，这些名称说明仓库包含浏览器、Markdown、DOCX 和终端界面相关组件。

不能仅凭依赖名称断言所有组件都会在每次安装时被执行，也不能推断支持的浏览器、文档格式或具体转换选项。构建脚本还包括 vendor:xterm 和 build:diagram-render，分别涉及 xterm 静态资源复制和图表渲染模块构建。

评测与测试模块

package.json 提供了免费测试、Windows 测试、端到端测试、门禁评测和周期评测脚本。test:evals 使用 ANTHROPIC_API_KEY 执行 LLM-as-judge 评测，test:e2e 和相关脚本覆盖技能路由、技能端到端、Codex 和 Gemini 测试文件。

评测脚本会使用 Bun 的测试命令，并通过环境变量 EVALS、EVALS_ALL、EVALS_TIER 和 EVALS_CONCURRENCY 控制部分运行模式。资料没有提供具体评测分数、通过率、基准结果或测试数据集，因此不能把脚本名称解释为已达到某项性能指标。

依赖与运行环境

运行 gstack 至少需要 Claude Code、Git 和 Bun 1.0 及以上；README 明确指出 Windows 还需要 Node.js。package.json 的 engines 字段只声明 Bun 版本约束，未声明 Node.js 的版本范围。

依赖的精确安装结果还会受到 Bun、操作系统和锁定文件的影响。资料未提供锁文件内容、支持的操作系统矩阵、最低 CPU 或内存要求，部署前应以仓库当前 README 和构建结果为准。

快速开始

最小闭环包括安装 gstack、在 Claude Code 中触发一个技能，以及对结果进行可见验证。以下命令来自 README 的安装方式，使用浅克隆以减少本地获取内容；执行前应确认目标目录没有需要保留的同名内容。

步骤一：安装

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup

安装命令会把仓库放到 ~/.claude/skills/gstack，然后执行仓库提供的 setup 脚本。README 要求随后在 Claude Code 中加入 gstack 章节，并声明使用 /browse 进行网页浏览、不要使用 mcp__claude-in-chrome__* 工具。

步骤二：运行一个本地工作流

打开 Claude Code，在已经允许读取的本地项目目录中运行以下技能。这个例子不访问外部目标，也不触发部署，适合先验证技能是否被识别。

/office-hours
请描述当前本地项目正在构建的功能，并记录需要进一步澄清的问题。

/plan-ceo-review
请对刚才描述的功能进行产品范围评审，不修改代码。

/review
请检查当前分支中的代码改动，并输出发现的问题。

最小验证标准是 Claude Code 能识别这些命令并返回对应任务结果。资料没有提供统一的成功退出码、固定输出格式或独立诊断命令，因此不能把某个文本结果当作官方健康检查接口。

步骤三：加入团队模式

在需要让同一仓库的协作者自动获得 gstack 时，可以从目标仓库执行 README 给出的团队初始化命令。该命令会修改 .claude/ 和 CLAUDE.md，并创建一次 Git 提交。

(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"

required 表示要求模式；README 说明也可以替换为 optional，用于提示而不是阻止。自动更新检查默认每小时节流一次，并且网络失败时保持安全、静默；这是 README 的行为描述，仍应在实际团队仓库中验证配置变更是否符合本地政策。

配置说明

仓库提供的配置线索主要来自 package.json 和 .env.example。下面只列出资料中确实出现的字段；“默认值”一栏不把版本约束误写成运行时默认值，未提供的内容明确标记。

环境变量与密钥处理

.env.example 要求复制为 .env 后填写值，并注明 Bun 会自动加载 .env，不需要 dotenv。示例中的密钥只是占位格式，不能直接使用；应通过本地未提交文件、受控密钥存储或 CI 的秘密变量注入。

cp .env.example .env
# 编辑 .env，仅在本地评测环境填写：
# ANTHROPIC_API_KEY=<你的-API-KEY>
bun run test:evals

<你的-API-KEY> 是占位符，不是有效凭据。资料没有说明密钥的轮换周期、权限范围、保留时间或计费方式，使用者应遵循 Anthropic 账户和所在组织的凭据管理政策。

进阶用法

进阶用法主要分为团队自动更新、OpenClaw 调度、其他 AI 编程代理适配，以及仓库自身的构建和评测。每条路径都应先在非生产环境验证，因为技能命令可能读取代码、访问浏览器或产生 Git 变更。

OpenClaw 调度

README 说明 OpenClaw 可以通过 ACP 启动 Claude Code 会话；当 Claude Code 已安装 gstack 时，gstack 技能可以在这些会话中工作。对于安全审计、代码审查、QA 和端到端功能开发，README 给出了分别调用 /cso、/review、/qa 和 /autoplan 后实施并发布的示例。

OpenClaw 的调度提示应明确说明“加载 gstack”以及所需技能。资料还列出四个可直接安装到 OpenClaw 的原生技能名称，但没有提供它们在当前仓库之外的实现细节；安装前应核对对应分发渠道和版本。

构建与开发脚本

package.json 提供 bun run build、bun run dev、bun run server、bun run start 和 bun run gen:skill-docs 等脚本。dev 执行 browse/src/cli.ts，server 与 start 执行 browse/src/server.ts；资料没有给出服务监听端口，因此不应在脚本外推断 URL。

cd ~/.claude/skills/gstack
bun run build
bun run skill:check
bun run test:free

这里的验证顺序是先构建，再执行技能检查和免费测试。test:free 会调用 scripts/test-free-shards.ts；test 还会调用 slop diff 检查，但资料没有给出测试通过标准或扫描规则的完整定义。

评测运行模式

需要模型评审的脚本包括 test:evals、test:evals:all、test:gate 和周期性评测脚本。test:evals 使用 EVALS=1，默认并发参数来自 ${EVALS_CONCURRENCY:-15}；test:evals:all 额外设置 EVALS_ALL=1。

这些命令需要 Anthropic API 密钥，且会调用模型评审流程。若组织不允许源代码或测试样本发送到外部模型服务，应停用这类评测，仅运行不需要该密钥的测试脚本。

可观测性与运维

仓库资料提供的是本地脚本级运维能力，而不是完整的在线可观测性平台。可确认的运维入口包括评测后台运行、评测列表、评测比较、评测摘要、评测监控和分析脚本。

• eval:list：运行 scripts/eval-list.ts，用于列出评测相关信息。
• eval:compare：运行 scripts/eval-compare.ts，用于比较评测结果。
• eval:summary：运行 scripts/eval-summary.ts，用于生成评测摘要。
• eval:watch：运行 scripts/eval-watch.ts，用于观察评测任务。
• analytics：运行 scripts/analytics.ts\，用于仓库声明的分析脚本。

README 还说明团队模式的自动更新检查按小时节流，并且网络失败时静默处理。资料没有提供日志格式、指标名称、告警阈值、持久化位置、审计事件模型或 SLA，因此这些内容应由使用团队自行制定，而不能视为 gstack 的内置保证。

安全与合规边界

gstack 涉及浏览器自动化、Cookie 配置、代码分析和安全审计，安全边界应以授权、数据最小化和环境隔离为前提。本文只讨论在自有项目、明确批准的测试系统和组织授权范围内使用，不提供面向未授权目标的攻击教程，也不提供绕过检测或规避访问控制的技巧。

授权与数据范围

• 运行 /qa 或 /browse 前，仅使用组织明确授权的本地、测试或预发布 URL。
• 使用 /setup-browser-cookies 或 /connect-chrome 前，应确认 Cookie 对应的账号、数据范围和保存位置符合组织规定。
• 运行 /cso 前，应明确安全评估范围、时间窗口、测试凭据和停止条件。
• 运行 /ship、/land-and-deploy 或 /canary 前，应确认代理拥有的 Git、部署和云资源权限是最小必要权限。
• 运行带有 Anthropic API 的评测前，应确认源代码、提示词、测试数据和密钥不会违反隐私、保密或数据出境要求。

技术边界

README 要求使用 gstack 的 /browse 技能进行网页浏览，并禁止使用 mcp__claude-in-chrome__* 工具。这是仓库工作流约束，不等于操作系统级隔离或浏览器沙箱的安全证明。

资料未提供渗透测试报告、CVE 修复承诺、合规认证、密钥加密方案、数据保留政策或多租户隔离保证。涉及个人信息、生产凭据、支付数据或受监管数据时，应在组织批准的隔离环境中进行，并以组织的安全制度和适用法律为准。

许可证与商用条款

仓库 LICENSE 文件明确采用 MIT License，版权标注为 Copyright（c）2026 Garry Tan。MIT 许可证允许获得软件的人员使用、复制、修改、合并、发布、分发、再许可和出售软件副本，因此在许可证授予范围内可以用于商业场景。

分发软件或其实质部分时，必须保留版权声明和许可证声明。LICENSE 同时规定软件按“现状”提供，不提供适销性、特定用途适用性和非侵权保证，作者在许可证规定范围内不对损害承担责任。

上述说明只针对仓库 LICENSE 文件中的项目许可证，不代表所有第三方依赖都使用 MIT。分发修改版、二进制包或包含第三方依赖的产品时，应分别核对依赖许可证、版权和通知要求，以仓库 LICENSE 及相关依赖的许可证文本为准。

局限性与已知限制

资料能够说明 gstack 的技能清单、安装流程和部分脚本，但没有提供完整 API 文档、所有技能的输入输出契约或统一错误处理规范。使用者需要把技能看作面向代理的工作流指令，而不是具有稳定协议的远程 API。

• 未提供固定服务端口，因此不能根据 bun run server 推断访问地址。
• 未提供 CPU、内存、磁盘、浏览器版本或并发容量要求。
• 未提供 QA 的测试覆盖率、准确率、误报率或性能基准。
• 未提供发布命令对具体云平台、容器平台或 CI 系统的适配清单。
• 未提供安全审计的认证等级、漏洞评级规则或合规报告格式。
• LLM-as-judge 评测需要 API 密钥，外部模型调用会引入数据治理和成本管理问题。
• 团队自动更新依赖网络可达性；README 说明网络失败会静默处理，但没有说明更新失败时的具体告警方式。

如果需要上述缺失信息，官方仓库未提供该信息，建议以最新 README、当前源码和实际测试结果为准。

适合谁 / 不适合谁

选择 gstack 的关键判断标准是团队是否愿意把 AI 编程代理纳入有边界的工程流程，而不是 Star 数量。以下信号可以帮助评估采用条件。

适合谁

• 已经使用 Claude Code，并希望用固定角色命令替代空白提示的个人开发者或技术创始人。
• 需要在功能开发前执行产品、工程和设计评审，并且愿意把计划保存到项目流程中的小型团队。
• 拥有可访问的本地或预发布测试 URL，希望通过 /qa 和浏览器技能执行授权测试的前端或全栈团队。
• 需要对分支变更执行 /review，并希望把发布文档、复盘和开发者体验检查纳入日常工作的技术负责人。
• 能够接受 Bun 1.0+、Git，以及在 Windows 上安装 Node.js，并有能力管理 API 密钥和浏览器凭据的团队。

不适合谁

• 不允许代码、测试数据或提示词发送给外部模型服务，且无法关闭相关模型评测的组织。
• 要求固定 API、严格可重复输出、强制审批和审计证据链，但不准备自行补充这些控制措施的团队。
• 没有任何授权测试环境，却希望直接对第三方网站、生产系统或他人账号执行浏览器操作的使用者。
• 只使用不兼容 Claude Code、Bun 或 README 所列其他代理环境，且不愿进行适配和验证的团队。
• 需要官方 SLA、托管控制面板、云端任务队列或供应商级技术支持承诺的组织；资料没有声明这些能力。

常见问题与排查（FAQ / Troubleshooting）

排查应先确认运行时、安装目录、项目配置和命令上下文，再判断是否属于技能自身问题。下面的建议只使用资料中已出现的路径和命令，不把未提供的端口或接口当作诊断依据。

为什么 Claude Code 无法识别技能

先确认仓库是否位于 ~/.claude/skills/gstack，并且已在该目录执行 ./setup。再检查 CLAUDE.md 是否加入了 gstack 章节和技能清单；团队模式下还应确认 .claude/ 与 CLAUDE.md 已被提交到目标仓库。

执行评测时提示缺少密钥怎么办

根据 .env.example，LLM-as-judge 评测需要 ANTHROPIC_API_KEY。复制 .env.example 为 .env，并将占位符替换为有效密钥；不要把真实密钥写入 Git，也不要把密钥放进公开日志。

Windows 环境安装失败怎么办

README 将 Node.js 列为 Windows 要求，同时项目 package.json 将 Bun 最低版本声明为 >=1.0.0。应先确认 Git、Bun 和 Node.js 均可用，再重新执行克隆和 ./setup；Windows 专用脚本或兼容性细节官方仓库未提供该信息，建议以最新 README 为准。

浏览器测试是否需要固定端口

资料没有给出 gstack 服务端口，也没有声明 /qa 的端口参数。应使用已经存在且获得授权的测试 URL；如果是本地项目，应先依据项目自身文档启动服务，再把实际 URL 提供给技能。

如何确认升级是否生效

团队模式包含自动更新检查，README 说明检查频率节流为每小时一次，并在网络失败时静默处理。要核对本地版本，可以查看 package.json 中的 version 字段；如果需要强制执行仓库提供的升级流程，可使用技能清单中的 /gstack-upgrade，具体行为以当前仓库实现为准。

测试脚本是否等同于发布门禁

不是。package.json 提供 test、test:free、test:e2e、test:gate 等脚本，但资料没有声明它们自动接入某个组织的合并规则或部署平台。根据本文作者的经验判断，团队仍应把测试结果与人工审查、依赖检查、权限审批和回滚方案结合起来。

项目地址与资源

以下资源均出现在仓库资料或 README 的官方关联信息中，版本和页面内容会随上游更新。

• gstack GitHub 仓库
• Claude Code 官方文档
• Git 官方网站
• Bun 官方网站
• Node.js 官方网站
• OpenClaw GitHub 仓库
• Y Combinator 官方网站
• Garry Tan 的 X 主页