Lu's Blog
Published on

g-stack 项目工作流浏览报告

Authors

gstack 项目工作流程总览

本文档由仓库内容扫描整理而来。原仓库扫描到 124 个 Markdown 文件；本文档是本次新增的总览文档，不计入原始扫描数量。

项目定位

gstack 是一套面向 AI 编程代理的工程工作流技能包。核心产物是多组 SKILL.md 文件：它们把一个完整软件团队里的角色拆成可调用的 slash command，例如产品/CEO 评审、工程评审、设计评审、代码审查、QA、发布、部署、复盘、安全审计、浏览器自动化等。

仓库的技术主线是：

  • 用 SKILL.md.tmpl 维护技能源模板。
  • 用 scripts/gen-skill-docs.ts 按宿主配置生成不同格式的 SKILL.md。
  • 用 setup 和 bin/* 把技能安装/链接到 Claude Code、Codex、Factory、OpenCode 等宿主。
  • 用 browse/ 提供一个持久化 Chromium 浏览器守护进程，让技能可以做真实页面测试、截图、抓取和远程配对。
  • 用 Bun 构建、测试、生成文档和编译二进制。

用户侧工作流

README 把 gstack 定义成一个流程，而不是零散工具。典型顺序是：

  1. Think: /office-hours 先重构需求，确认真实用户痛点和最小切入点。
  2. Plan: /plan-ceo-review、/plan-design-review、/plan-eng-review、/plan-devex-review 或 /autoplan 审查产品、设计、架构和 DX。
  3. Build: 开发者或代理按计划实现。
  4. Review: /review、/codex、/cso 找隐藏缺陷、跨模型挑战和安全问题。
  5. Test: /qa、/qa-only、/design-review、/devex-review、/benchmark 用真实浏览器验证。
  6. Ship: /ship 跑测试、检查 diff、更新版本/变更日志、提交并开 PR。
  7. Deploy: /land-and-deploy 合并、等待 CI/部署并用 /canary 监控生产。
  8. Learn: /retro、/learn、/context-save 把经验、上下文和趋势沉淀下来。
+-------------+     +--------------+     +-------------+
| office-hours| --> | plan reviews | --> | implement   |
| Think       |     | CEO/Design/  |     | Build       |
|             |     | Eng/DX       |     |             |
+-------------+     +--------------+     +-------------+
                                               |
                                               v
+-------------+     +--------------+     +-------------+
| learn/retro | <-- | deploy/canary| <-- | review/test |
| Reflect     |     | Verify prod  |     | QA/Security |
+-------------+     +--------------+     +-------------+
        ^                                      |
        |                                      v
        +------------------------------+ +-------------+
                                       | | ship / PR   |
                                       | | Release     |
                                       | +-------------+
                                       +---------------+

仓库开发工作流

修改 gstack 本身时，主要遵守“模板为源、生成文件为产物”的规则：

  1. 修改根目录或一级子目录中的 SKILL.md.tmpl。
  2. 运行 bun run gen:skill-docs 或 bun run gen:skill-docs --host all。
  3. 如果涉及浏览器命令，更新 browse/src/commands.ts；如果涉及 snapshot 参数，更新 browse/src/snapshot.ts。
  4. 运行 bun test 做免费静态/集成检查。
  5. 需要完整质量验证时运行 bun run test:e2e 或 bun run test:evals。
  6. 运行 bun run build 生成技能文档并编译 browse、design、make-pdf 等二进制。
        edit source
            |
            v
+--------------------+
| SKILL.md.tmpl      |
| command registry   |
| host configs       |
+--------------------+
            |
            v
+--------------------+      +--------------------+
| gen-skill-docs.ts  | ---> | generated SKILL.md |
| resolvers + hosts  |      | per target host    |
+--------------------+      +--------------------+
            |
            v
+--------------------+      +--------------------+
| skill:check / test | ---> | build binaries     |
| freshness + parser |      | browse/design/pdf  |
+--------------------+      +--------------------+
            |
            v
+--------------------+
| setup / install    |
| symlink skills     |
+--------------------+

浏览器运行时工作流

browse/ 是 gstack 里最重的运行时组件。它把 AI 代理的 shell 命令变成对持久 Chromium 的低延迟控制：

+-------------+      HTTP + token       +----------------+
| browse CLI  | ----------------------> | Bun daemon     |
| $B command  |                         | 127.0.0.1 port |
+-------------+                         +----------------+
       ^                                         |
       | plain text response                     | Playwright/CDP
       |                                         v
+-------------+                         +----------------+
| agent skill |                         | Chromium       |
| /qa /scrape |                         | tabs/cookies   |
+-------------+                         +----------------+

第一次调用会启动守护进程和 Chromium，之后调用复用 .gstack/browse.json 中的端口、PID 和 token。这样 /qa、/design-review、/scrape、/benchmark 等技能可以在同一会话里保留登录态、标签页、cookie、console/network 记录和元素 ref。

主要目录职责

路径作用
browse/浏览器 CLI、Bun HTTP daemon、Playwright/Chromium 控制、side panel、pair-agent、browser-skill 运行时。
design/视觉设计生成与设计到代码相关 CLI。
make-pdf/Markdown 到高质量 PDF 的渲染工具。
scripts/技能生成、宿主适配、评测、分析、健康检查等开发工具。
hosts/Claude、Codex、Factory、Kiro、OpenCode、Cursor、Slate、OpenClaw、Hermes、GBrain 的宿主配置。
bin/安装、路径解析、版本队列、gbrain、学习、遥测、浏览器、安全等 shell/TS 辅助命令。
test/技能解析、生成器、E2E、LLM eval 和黄金样例。
docs/架构、设计方案、OpenClaw、GBrain、远程浏览器等说明文档。
extension/GStack Browser 的 Chrome 扩展，包含 side panel、activity feed、inspector。
openclaw/OpenClaw 集成提示词和原生 OpenClaw 技能。
review/、qa/、cso/ 等技能目录每个目录通常承载一个 slash command 的生成版 SKILL.md、模板和辅助参考文档。

Markdown 文件用途清单

文件作用
PROJECT_WORKFLOW.md本文档：项目工作流、ASCII 流程图和 Markdown 文件用途总览。
AGENTS.md给 AI 代理的仓库级指令，列出 gstack 技能、构建命令、平台支持和关键约定。
ARCHITECTURE.md解释 gstack 的整体架构，尤其是持久浏览器 daemon、安全模型、ref 系统和日志架构。
BROWSER.md浏览器系统完整参考，覆盖 CLI、daemon、命令、snapshot、browser-skills、pair-agent 和安全层。
CHANGELOG.md项目版本变更记录。
CLAUDE.mdClaude Code 开发本仓库时使用的命令、测试、结构和 SKILL.md 工作流指南。
CONTRIBUTING.md贡献者指南，说明 dev mode、测试层级、E2E/eval、PR 工作流和本地开发方式。
DESIGN.mdgstack 自身设计系统说明。
ETHOS.mdgstack 的构建哲学和工作原则。
README.md项目介绍、安装、快速开始、技能总览、用户工作流和常见使用方式。
SKILL.md根技能生成文件，作为 gstack 主技能/浏览器能力入口之一。
TODOS.md项目待办、路线图和未来工作集合。
USING_GBRAIN_WITH_GSTACK.md说明如何把 GBrain 跨机器记忆系统与 gstack 搭配使用。
autoplan/SKILL.md/autoplan 技能：串联 CEO、设计、工程、DX 评审，自动形成完整计划审查。
benchmark-models/SKILL.md/benchmark-models 技能：横向比较 Claude、GPT/Codex、Gemini 等模型在技能任务上的表现。
benchmark/SKILL.md/benchmark 技能：用浏览器 daemon 采集页面性能基线和回归数据。
browse/PLAN-snapshot-dropdown-interactive.md浏览器 snapshot 对下拉框/自动完成/交互元素检测的设计计划。
browse/SKILL.md/browse 技能：快速头less/可视浏览器操作、QA、截图、表单和抓取入口。
browser-skills/hackernews-frontpage/SKILL.md示例 browser-skill：抓取 Hacker News 首页标题、分数和评论数。
canary/SKILL.md/canary 技能：部署后监控生产页面错误、性能和可用性。
careful/SKILL.md/careful 技能：对破坏性命令进行确认提示。
codex/SKILL.md/codex 技能：调用 OpenAI Codex CLI 做代码审查、挑战或咨询。
context-restore/SKILL.md/context-restore 技能：恢复 /context-save 保存的上下文。
context-save/SKILL.md/context-save 技能：保存 git 状态、决策和剩余工作，便于后续恢复。
cso/ACKNOWLEDGEMENTS.md/cso 安全审计相关致谢。
cso/SKILL.md/cso 技能：OWASP Top 10、STRIDE、供应链、CI/CD、LLM 安全审计。
design-consultation/SKILL.md/design-consultation 技能：从零建立产品设计系统和视觉方向。
design-html/SKILL.md/design-html 技能：把设计方向转成生产级 HTML/CSS。
design-review/SKILL.md/design-review 技能：真实页面视觉审查并修复设计问题。
design-shotgun/SKILL.md/design-shotgun 技能：生成多套设计变体、比较并迭代。
devex-review/SKILL.md/devex-review 技能：实际跑开发者上手流程，衡量 TTHW 和文档/CLI 摩擦。
docs/ADDING_A_HOST.md新增 AI 宿主适配的开发指南。
docs/ON_THE_LOC_CONTROVERSY.mdREADME 中关于 LOC/产能论述的方法、背景和争议说明。
docs/OPENCLAW.mdgstack 与 OpenClaw 的集成架构和调度方式。
docs/REMOTE_BROWSER_ACCESS.md远程代理如何通过 pair-agent 连接本地 GStack Browser 的说明。
docs/designs/BROWSER_SKILLS_V1.mdbrowser-skills v1 设计文档，描述把重复浏览器流程固化为脚本的机制。
docs/designs/BUN_NATIVE_INFERENCE.mdBun 原生提示注入分类器的研究计划。
docs/designs/CHROME_VS_CHROMIUM_EXPLORATION.md解释为什么使用 Playwright bundled Chromium 而不是系统 Chrome。
docs/designs/CONDUCTOR_CHROME_SIDEBAR_INTEGRATION.mdChrome sidebar 与 Conductor 集成需求和方案。
docs/designs/CONDUCTOR_SESSION_API.mdConductor session streaming API 提案。
docs/designs/DESIGN_SHOTGUN.md/design-shotgun 的浏览器到代理反馈循环设计。
docs/designs/DESIGN_TOOLS_V1.mddesign 二进制和视觉设计生成工具设计。
docs/designs/GCOMPACTION.mdGCompaction 设计和架构记录，标记为搁置。
docs/designs/GSTACK_BROWSER_V0.mdGStack Browser v0 设计文档。
docs/designs/ML_PROMPT_INJECTION_KILLER.mdML 提示注入防御方案设计。
docs/designs/PACING_UPDATES_V0.md进度更新机制设计文档。
docs/designs/PLAN_TUNING_V0.mdplan tuning v0 设计文档。
docs/designs/PLAN_TUNING_V1.mdplan tuning v1 设计文档。
docs/designs/SELF_LEARNING_V0.mdgstack 自学习基础设施设计。
docs/designs/SESSION_INTELLIGENCE.mdsession intelligence 层设计。
docs/designs/SIDEBAR_MESSAGE_FLOW.mdsidebar 消息流设计说明。
docs/designs/SLATE_HOST.mdSlate 宿主集成调研和设计。
docs/designs/SLOP_SCAN_FOR_REVIEW_SHIP.md在 /review 和 /ship 中集成 slop-scan 的设计。
docs/domain-skills.mddomain skills 机制说明。
docs/gbrain-sync-errors.mdgbrain-sync 错误查询和排障参考。
docs/gbrain-sync.mdGBrain 跨机器记忆同步说明。
docs/skills.md所有 gstack 技能的深度介绍、理念、流程和示例。
document-release/SKILL.md/document-release 技能：发布后同步 README、架构、贡献指南、变更日志和 TODO。
freeze/SKILL.md/freeze 技能：把编辑限制在指定目录。
gstack-upgrade/SKILL.md/gstack-upgrade 技能：升级 gstack 并展示变更。
guard/SKILL.md/guard 技能：组合 /careful 和 /freeze 的完整安全模式。
health/SKILL.md/health 技能：运行类型检查、lint、测试、死代码等并计算质量分。
investigate/SKILL.md/investigate 技能：按调查、分析、假设、实现流程做根因调试。
land-and-deploy/SKILL.md/land-and-deploy 技能：合并 PR、等待 CI/部署并验证生产健康。
landing-report/SKILL.md/landing-report 技能：只读查看 workspace-aware ship 的版本队列。
learn/SKILL.md/learn 技能：查看、搜索、裁剪和导出项目学习记录。
make-pdf/SKILL.md/make-pdf 技能：把 Markdown 渲染成排版质量较高的 PDF。
make-pdf/test/fixtures/combined-gate.mdmake-pdf 测试夹具，用于验证复杂 Markdown 渲染输出。
model-overlays/claude.mdClaude 模型族的生成提示覆盖/适配说明。
model-overlays/gemini.mdGemini 模型族的生成提示覆盖/适配说明。
model-overlays/gpt-5.4.mdGPT-5.4 模型族的生成提示覆盖/适配说明。
model-overlays/gpt.mdGPT 模型族通用生成提示覆盖/适配说明。
model-overlays/o-series.mdOpenAI o-series 模型的生成提示覆盖/适配说明。
model-overlays/opus-4-7.mdClaude Opus 4.7 的生成提示覆盖/适配说明。
office-hours/SKILL.md/office-hours 技能：以 YC office hours 方式在编码前重构产品想法。
open-gstack-browser/SKILL.md/open-gstack-browser 技能：启动可视 GStack Browser、sidebar 和实时活动流。
openclaw/agents-gstack-section.md给 OpenClaw AGENTS 文件插入的 gstack 使用段落。
openclaw/gstack-full-CLAUDE.mdOpenClaw full pipeline 提示词，覆盖完整 gstack 工作流。
openclaw/gstack-lite-CLAUDE.mdOpenClaw lite planning discipline 提示词，偏轻量计划约束。
openclaw/gstack-plan-CLAUDE.mdOpenClaw plan 模式提示词，运行完整评审关卡。
openclaw/skills/gstack-openclaw-ceo-review/SKILL.mdOpenClaw 原生 CEO 计划评审技能。
openclaw/skills/gstack-openclaw-investigate/SKILL.mdOpenClaw 原生系统化调试技能。
openclaw/skills/gstack-openclaw-office-hours/SKILL.mdOpenClaw 原生 YC office hours 技能。
openclaw/skills/gstack-openclaw-retro/SKILL.mdOpenClaw 原生周复盘技能。
pair-agent/SKILL.md/pair-agent 技能：通过受限 tunnel 把远程 AI 代理连接到本地浏览器。
plan-ceo-review/SKILL.md/plan-ceo-review 技能：从创始人/CEO 角度挑战方案、扩展或收缩范围。
plan-design-review/SKILL.md/plan-design-review 技能：计划阶段设计评审，评分并推动方案达到更好设计质量。
plan-devex-review/SKILL.md/plan-devex-review 技能：计划阶段开发者体验评审。
plan-devex-review/dx-hall-of-fame.mdDX 优秀案例参考库。
plan-eng-review/SKILL.md/plan-eng-review 技能：架构、数据流、状态、错误路径和测试覆盖评审。
plan-tune/SKILL.md/plan-tune 技能：调整计划阶段提问敏感度和用户偏好。
qa-only/SKILL.md/qa-only 技能：只报告不修改的 QA 测试。
qa/SKILL.md/qa 技能：真实浏览器 QA，发现、修复并复测问题。
qa/references/issue-taxonomy.mdQA 问题分类参考。
qa/templates/qa-report-template.mdQA 报告模板。
retro/SKILL.md/retro 技能：基于提交历史和质量指标做周复盘。
review/SKILL.md/review 技能：合并前代码审查，查找 CI 难以覆盖的生产风险。
review/TODOS-format.mdTODOS.md 格式规范和引用说明。
review/checklist.md合并前代码审查清单。
review/design-checklist.md轻量设计审查清单。
review/greptile-triage.mdGreptile 评论分流和处理指南。
review/specialists/api-contract.mdAPI 合同专项审查清单。
review/specialists/data-migration.md数据迁移专项审查清单。
review/specialists/maintainability.md可维护性专项审查清单。
review/specialists/performance.md性能专项审查清单。
review/specialists/red-team.md红队专项审查清单。
review/specialists/security.md安全专项审查清单。
review/specialists/testing.md测试专项审查清单。
scrape/SKILL.md/scrape 技能：以只读方式从网页提取结构化数据。
setup-browser-cookies/SKILL.md/setup-browser-cookies 技能：从真实浏览器导入 cookie 到 headless session。
setup-deploy/SKILL.md/setup-deploy 技能：检测部署平台、URL、健康检查和部署命令。
setup-gbrain/SKILL.md/setup-gbrain 技能：安装并初始化 GBrain，使代理具备跨机器记忆。
setup-gbrain/memory.mdgstack memory ingest 的本地/同步行为说明。
ship/SKILL.md/ship 技能：检测基分支、测试、审查 diff、更新版本/CHANGELOG、提交、推送和开 PR。
skillify/SKILL.md/skillify 技能：把最近成功的 /scrape 流程固化为可复用 browser-skill。
sync-gbrain/SKILL.md/sync-gbrain 技能：同步当前仓库代码到 GBrain 并刷新代理搜索指导。
test/fixtures/golden-ship-claude.md/ship Claude 生成输出的黄金样例/回归夹具。
test/fixtures/golden/claude-ship-SKILL.mdClaude 宿主下 /ship 技能生成文件的黄金样例。
test/fixtures/golden/codex-ship-SKILL.mdCodex 宿主下 /ship 技能生成文件的黄金样例。
test/fixtures/golden/factory-ship-SKILL.mdFactory 宿主下 /ship 技能生成文件的黄金样例。
test/fixtures/mode-posture/builder-idea.md模式姿态测试夹具：builder idea 输入。
test/fixtures/mode-posture/expansion-plan.md模式姿态测试夹具：scope expansion 计划。
test/fixtures/mode-posture/forcing-pitch.md模式姿态测试夹具：forcing pitch 输入。
test/fixtures/plans/ui-heavy-feature.mdUI-heavy 功能计划测试夹具。
unfreeze/SKILL.md/unfreeze 技能：清除 /freeze 设置的编辑边界。

维护注意事项

  • SKILL.md 大多是生成产物；修改技能时优先改对应的 SKILL.md.tmpl。
  • 修改浏览器命令后要同步命令注册表、技能文档生成和测试。
  • bun run skill:check 会检查技能命令、模板覆盖和多宿主生成文件 freshness。
  • bun test 是免费基础验证；test:e2e 和 test:evals 可能调用真实模型或外部服务。
Discuss on Twitter • View on GitHub