gstack 完整技能地图与构建规范：AGENTS.md 详解

gstack 完整技能地图与构建规范AGENTS.md 详解【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstackgstack 是 Garry Tan 开源的 AI 工程工作流套件一组 SKILL.md 文件为 AI Agent 提供结构化角色——CEO 评审官、工程经理、设计师、QA 负责人、发布工程师、调试员等。本文以仓库根目录的 AGENTS.md 为骨架完整解析其中的七大技能目录、五个构建命令、平台支持矩阵与六条关键工程约定并结合 package.json、hosts/index.ts、bin/gstack-paths、browse/src/claude-bin.ts 等源码逐条印证其实现。读完本篇你可以按图索骥地调用任意一个 gstack 技能并理解其背后的模板生成、状态路径解析与跨平台机制。AGENTS.md 定位面向 Agent 的项目操作手册AGENTS.md 开篇给出项目一句话定义gstack is a collection of SKILL.md files that give AI agents structured roles for software development. Each skill is a specialist: CEO reviewer, eng manager, designer, QA lead, release engineer, debugger, and more.README 将其定位为把 Claude Code 变成虚拟工程团队的工具集MIT 协议、全部为 slash 命令 Markdown。技能安装位置有两种.agents/skills/通用 Agent 目录~/.claude/skills/gstack/Claude Code 安装方式调用方式统一为按名称触发例如/office-hours。技能目录分布在仓库顶层的独立目录中——每个技能一个目录ship/、review/、qa/、ios-qa/……目录内为SKILL.md生成物SKILL.md.tmpl模板 可选的sections/子章节与src//daemon/代码。这与 CLAUDE.md 中one directory per skill的项目结构约定一致。技能目录全览AGENTS.md 将全部技能按工作流阶段分为七类。以下完整继承原文档的四张技能表与一张 iOS 伴随 CLI 表。1. 计划模式评审Plan-mode reviewsSkill作用/office-hours起点。在写代码前重构你的产品想法/plan-ceo-reviewCEO 级评审从需求中找到10 星产品/plan-eng-review锁定架构、数据流、边界情况与测试/plan-design-review每个设计维度打 0-10 分并解释满分长什么样/plan-devex-reviewDX 模式评审TTHW、魔法时刻、摩擦点、角色画像追踪/plan-tune逐题自调 AskUserQuestion 敏感度/autoplan一条命令跑完 CEO → design → eng → DX 四段评审/design-consultation从零构建完整设计系统/spec五阶段把模糊意图变成精确可执行规格提交 GitHub issue可选在独立 worktree 中派生 Claude Code Agent并让/ship在合并时关闭源 issue/autoplan是典型的编排型技能其目录 autoplan/sections/ 下包含ceo-phase.md、design-phase.md、dx-phase.md、eng-phase.md四个阶段模板与manifest.json印证了它按CEO → 设计 → 工程 → 体验顺序串联四个评审技能的实现方式。2. 实现 评审Implementation reviewSkill作用/review落地前 PR 评审找出能过 CI 但会炸生产的 bug/codex通过 OpenAI Codex 获取第二意见支持 review / challenge / consult 三种模式/investigate系统化根因调试不调查不修复/design-review对线上站点做视觉审计 原子提交的修复循环/design-shotgun生成多个 AI 设计变体、对比板、迭代/design-html生成生产级 Pretext 原生 HTML/CSS/devex-review真实流程下的开发者体验审计TTHW 实测/qa打开真实浏览器找 bug、修 bug、复验/qa-only与 /qa 同方法论但只报告不改代码/scrape从网页拉数据首次调用出原型固化后约 200ms/skillify把最近一次成功的 /scrape 流程固化为永久 browser-skill/scrape与/skillify构成原型 → 固化的闭环固化后的浏览器技能存放在 browser-skills/例如现成的hackernews-frontpage/技能底层由 browse/src/browser-skills.ts 与 browse/src/domain-skills.ts 加载执行。3. 发布 部署Release deploySkill作用/ship跑测试、评审、推送、开 PR带 workspace 感知的版本队列/land-and-deploy合并 PR等待 CI 与部署完成验证生产健康/canary部署后监控循环基于 browse daemon/landing-reportworkspace 感知 ship 队列的只读仪表盘/document-release更新所有文档以匹配刚发布的内容/document-generate从代码生成 Diataxis 四象限文档tutorial / how-to / reference / explanation/setup-deploy一次性部署配置检测Fly.io、Render、Vercel 等/gstack-upgrade将 gstack 升级到最新版本/ship是全套件中体量最大的技能之一ship/sections/ 下有 18 个阶段模板md tmplCLAUDE.md 明确提到ship、plan-ceo-review、office-hours是合法打包 25-35K token 行为的大技能。4. 运维 记忆Operational memorySkill作用/context-save保存工作上下文git 状态、决策、剩余工作/context-restore从保存的上下文恢复可跨 Conductor workspace/learn管理 gstack 跨会话学到的东西/retro每周复盘含按人拆解与连续交付统计/health代码质量仪表盘类型检查、lint、测试、死代码/benchmark性能回归检测页面加载、Core Web Vitals/benchmark-models技能跨模型基准Claude / GPT / Gemini 并排对比/csoOWASP Top 10 STRIDE 安全审计/setup-gbrain配置 gbrain 跨机会话记忆同步/sync-gbrain用当前仓库代码刷新 gbrain更新 CLAUDE.md 中的 Agent 检索指引/sync-gbrain的配套使用方式详见 USING_GBRAIN_WITH_GSTACK.mdgbrain 相关共享库集中在 lib/如 lib/gbrain-exec.ts、lib/gbrain-sources.ts。5. 浏览器 Agent 集成Browser agent integrationSkill作用/browse无头浏览器——真实 Chromium、真实点击约 100ms/命令/open-gstack-browser启动带侧边栏 stealth 的可见版 GStack Browser/setup-browser-cookies从真实浏览器导入 cookie 用于登录态测试/pair-agent把远程 AI AgentOpenClaw、Codex 等接入你的浏览器/browse背后是 browse/src/cli.ts 入口、browse/src/commands.ts 命令注册与基于 Playwright 的 CDP 桥browse/src/cdp-bridge.ts 等。完整的浏览器子系统文档在 BROWSER.md。6. iOS QAUSB/Tailscale 驱动物理 iPhonev1.43.0.0Skill作用/ios-qa通过 USB CoreDevice 隧道 内嵌 StateServer 做真机 iOS QA可选经 Tailscale 暴露给远程 Agent/ios-fix带回归快照捕获的自治 iOS 修复器/ios-design-review在真机 iPhone 上做设计师视角QA10 维 Apple HIG 评分/ios-clean便捷技能Release 构建前剥离 DebugBridge #if DEBUG 接线/ios-sync按上游最新模板重新生成 iOS debug bridgeiOS 能力由 Mac 侧三个伴随 CLI 支撑运行在插上设备的那台 Mac 上命令作用gstack-ios-qa-daemonMac 侧 broker默认仅 loopback--tailnet增加带能力分层capability tiers与审计日志的 Tailscale 监听器gstack-ios-qa-minttailnet 白名单的属主授权 CLIgrant/revoke/listgstack-ios-qa-regen重新生成规范的本地 DebugBridge 包与类型化访问器--app-source/--bridge-dir这三个 CLI 在 bin/ 中均有对应脚本gstack-ios-qa-daemon、gstack-ios-qa-mint、gstack-ios-qa-regendaemon 的 TypeScript 实现位于 ios-qa/daemon/src/而regen生成的 Swift 模板StateServer.swift.template、DebugBridgeWiring.swift.template等 9 个在 ios-qa/templates/。端到端操作手册Xcode 16 CoreDevice 隧道、Developer Mode、Apple 团队 ID、Tailscale bearer token 等完整步骤见 docs/howto-ios-testing-with-gstack.md。7. 安全 范围控制Safety scopingSkill作用/careful破坏性命令rm -rf、DROP TABLE、force-push前预警/freeze把编辑锁定在单个目录——硬阻断不是警告/guard同时激活 careful freeze/unfreeze移除目录编辑限制/make-pdf把任意 markdown 变成出版级 PDF/diagram英文进、图表出mermaid 源码 可编辑 .excalidraw SVG/PNG离线运行AGENTS.md 约定安全技能careful、freeze、guard采用内联建议式散文inline advisory prose实现——每次破坏性操作前必须先确认。/make-pdf对应 make-pdf/src/ 的 13 个 TS 源文件与独立make-pdf可执行入口见 package.json 的bin字段/diagram的渲染管线在 lib/diagram-render/。构建命令及其实现映射AGENTS.md 给出五个核心构建命令bun install # 安装依赖 bun run test # 经 strict shard runner 跑免费测试不花 API 费约 90-100s bun run test:windows # 精选的 Windows 安全子集在 windows-latest 上运行 bun run build # 生成文档 编译二进制 bun run gen:skill-docs # 从模板重新生成 SKILL.md bun run skill:check # 全部技能的健康仪表盘对照 package.json 的scripts字段可以精确看到每条命令的底层实现命令实际执行说明bun run testbun run scripts/test-free-shards.ts (bun run slop:diff ...)N 个并发分片进程、片内串行每片带 strict-output 分类缺 bun 终端汇总行的分片直接判失败杜绝静默截断报绿bun run test:windowsbun run scripts/test-free-shards.ts --windows-only同一 runner 的--windows-only过滤bun run buildbash scripts/build.sh文档生成 二进制编译bun run gen:skill-docsbun run scripts/gen-skill-docs.ts模板 → SKILL.md另有--respect-detection的gen:skill-docs:user变体bun run skill:checkbun run scripts/skill-check.ts技能健康检查CLAUDE.md 补充了两条关键纪律永远不要裸跑bun test跑整套免费测试它会遍历全仓库、误加载付费 eval 文件并绕过 strict 分类器付费的 LLM 评审与 E2E 走test:evals系列脚本且测试分为gateCI 默认阻断合并与periodic周级 cron两层CI 只跑 gate 层。免费层由 .github/workflows/free-tests.yml 作为必填检查在每个 PR 上运行无 secret、fork PR 也能出信号Windows 子集由 .github/workflows/windows-free-tests.yml 的windows-free-testsjob 承担——这正是 AGENTS.md 平台支持一节提到的 CI 管道。平台支持AGENTS.md 的平台矩阵macOS Linux完整测试套件支持Windows精选 Windows 安全子集经windows-free-testsCI job 在windows-latest上运行./setup目前要求 Git Bash 或 MSYS原生 PowerShell 支持列为后续扩展。Windows 兼容性的核心是bin/gstack-paths这个状态路径解析助手。从 bin/gstack-paths 源码头部注释看它按显式回退链解析三个根目录GSTACK_STATE_ROOT: GSTACK_HOME - CLAUDE_PLUGIN_DATA仅当 CLAUDE_PLUGIN_ROOT 含 gstack- $HOME/.gstack - .gstack PLAN_ROOT: GSTACK_PLAN_DIR - CLAUDE_PLANS_DIR - $HOME/.claude/plans - .claude/plans TMP_ROOT: TMPDIR - TMP - .gstack/tmpbest-effort mkdir三个值得注意的实现细节插件环境污染防护只有CLAUDE_PLUGIN_ROOT确认当前跑的是 gstack 插件时才信任CLAUDE_PLUGIN_DATA避免其他插件如 codex泄漏进会话环境的同名变量把 gstack 状态写错目录printf %qshell 引号输出Windows 下$TMP是C:\Users\me\...这类反斜杠路径裸echo会让eval把反斜杠当转义吃掉、带空格的路径会被词法切分——源里注释明确这是唯一在调用方拿到值之前就能修复的引号方式尾斜杠归一化macOS 的$TMPDIR默认带尾/源头剥掉所有拼接$TMP_ROOT/name的消费方都不再产生双斜杠对应回归测试regression-issue2091-bsd-mktemp一类问题。调用方式即 AGENTS.md 所述eval $(gstack-paths)随后得到GSTACK_STATE_ROOT、PLAN_ROOT、TMP_ROOT三个已引号保护的变量尊重GSTACK_HOME、CLAUDE_PLUGIN_DATA、CLAUDE_PLANS_DIR。关键工程约定Key conventions及其实现依据AGENTS.md 最后列出六条仓库级约定逐条都有源码可查证1. SKILL.md 由模板生成——改模板不要改产物。每个技能目录的SKILL.md头部都写着AUTO-GENERATED from SKILL.md.tmpl — do not edit directly见根目录 SKILL.md。生成入口是 scripts/gen-skill-docs.tsCodex 专属产物用bun run gen:skill-docs --host codex重新生成。宿主host体系由 hosts/index.ts 注册ALL_HOST_CONFIGS收录 claude、codex、factory、kiro、opencode、slate、cursor、openclaw、hermes、gbrain 共十个宿主配置每个宿主一份 hosts/define-host.ts 类型的配置支持别名解析如agents→codex。新增宿主是一个 TS 配置文件、零代码改动见 docs/ADDING_A_HOST.md。CLAUDE.md 还说明生成的 SKILL.md 超过 160KB约 40K token会触发特征膨胀预警它是观察护栏而非硬门禁。2. browse 二进制提供无头浏览器访问技能中统一使用$B command调用。新命令加在 browse/src/commands.ts 后重新构建$B变量在技能 preamble 中指向安装位置的 browse 可执行文件bin字段声明为./browse/dist/browse。3. 安全技能用内联建议式散文破坏性操作前必须确认。/careful、/freeze、/guard的 SKILL.md 中直接嵌入顾问式指令文本而非依赖外部脚本拦截。4. 状态路径经bin/gstack-paths解析eval $(...)引入尊重GSTACK_HOME、CLAUDE_PLUGIN_DATA、CLAUDE_PLANS_DIR——回退链细节如上节所述。5.claudeCLI 二进制的跨平台解析。解析逻辑在 browse/src/claude-bin.ts采用两级优先1. GSTACK_CLAUDE_BIN回退 CLAUDE_BIN——绝对路径或可经 PATH 解析的命令 2. 未设覆盖时直接 Bun.which(claude)GSTACK_CLAUDE_BIN_ARGS支持 JSON 数组如[claude, --no-cache]或单标量参数且仅在覆盖生效时追加。AGENTS.md 给出的 Windows/WSL 场景即由此实现GSTACK_CLAUDE_BINwsl GSTACK_CLAUDE_BIN_ARGS[claude] # 在 Windows 上经 WSL 运行 Claude函数在任何都解析不到时返回null调用方降级而非抛错例如 transcript 分类器返回degraded:true——这与根 SKILL.md 中degraded mode降级语义一脉相承。小结AGENTS.md 是理解 gstack 的最短入口七类技能表覆盖了想法 → 规划 → 实现 → 评审 → 发布 → 运维 → 安全的完整工作流每个技能对应仓库内一个可独立阅读的目录五个构建命令在 package.json 中全部映射到 scripts/ 下的具体 runner平台支持与六条约定则分别由 bin/gstack-paths、hosts/index.ts、browse/src/claude-bin.ts 等源码兜底。当前仓库版本以 VERSION 文件为准1.71.0.0iOS QA 系列技能标注需 v1.43.0.0。如果你要在自己的 AI 工程中引入这套角色化技能体系建议的路径是/office-hours起步 →/autoplan出计划 →/review与/qa把关 →/ship落地全程用/careful/freeze兜底。【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考