GSD Workspaces 列表总览基于 gsd-sdk 查询引擎的 list-workspaces 工作流实战指南【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读在 get-shit-doneGSD这套基于 Claude Code 的规格驱动开发Spec-Driven Development系统中工作区Workspace是用于并行隔离多仓库开发环境的独立目录。list-workspaces工作流负责扫描~/gsd-workspaces/目录汇总所有工作区的名称、仓库数量、克隆策略与 GSD 项目初始化状态并以一张可读的表格呈现给 Agent。阅读本文后你将完整掌握该工作流的前端路由方式、gsd-sdk query init.list-workspaces数据源的返回结构、底层initListWorkspaces实现的字段解析规则以及它如何与new-workspace、remove-workspace联动构成工作区全生命周期管理。一、工作流的定位工作区生命周期管理的一环工作流定义文件位于 get-shit-done/workflows/list-workspaces.md它的职责非常聚焦列出~/gsd-workspaces/下所有 GSD 工作区并附带状态信息。在 GSD 的命令体系中工作区管理被收敛为一条统一命令gsd:workspace其路由表定义在 commands/gsd/workspace.md标志动作路由工作流--new以 worktree/clone 策略创建工作区new-workspace--list扫描~/gsd-workspaces/输出摘要表格list-workspaces--remove确认并删除工作区目录remove-workspace也就是说用户在 Claude Code 中执行/gsd:workspace --list时会直接进入本文所讲的 list-workspaces 工作流。工作流通过gsd-sdk的查询层获取初始化数据再依据数据状态分支渲染输出全程不需要手工ls或解析文件系统。二、Setup 阶段通过 gsd-sdk 查询获取初始化数据工作流的第一步是向 GSD SDK 发起一次查询命令如下INIT$(gsd-sdk query init.list-workspaces) if [[ $INIT file:* ]]; then INIT$(cat ${INIT#file:}); fi这段脚本做了两件事调用gsd-sdk query init.list-workspaces获取工作区列表的扁平 JSON 数据处理file:前缀——当查询结果以file:开头时说明 SDK 将结果写入了临时文件此时用cat读取文件内容替换变量从而保证后续 JSON 解析拿到的是完整字符串。查询返回的 JSON 中需要解析三个关键字段字段含义workspace_base工作区根目录默认~/gsd-workspaces/workspaces工作区明细数组workspace_count工作区总数init.list-workspaces属于init查询族compound init commandsSDK 侧对其无参数要求No args这一点在 sdk/src/query/QUERY-HANDLERS.md 中有明确记录。三、底层实现initListWorkspaces 的字段来源解析init.list-workspaces查询由 SDK 查询族注册表 sdk/src/query/command-family-handlers.ts 中的init.list-workspaces: initListWorkspaces映射到实现函数。该实现位于 sdk/src/query/init.ts 的initListWorkspaces从源码结构看其核心逻辑如下确定根目录取$HOME/gsd-workspaces通过process.env.HOME || homedir()计算即workspace_base。扫描子目录遍历根目录下所有目录项仅保留目录只有目录内存在WORKSPACE.md清单文件时才视为一个合法工作区否则跳过。解析每个工作区的元数据Strategy策略从WORKSPACE.md中正则匹配^Strategy:\s*(.)$行取其值如worktree、clone匹配不到则为unknown。Repos仓库数统计WORKSPACE.md中表格数据行的数量——过滤规则是行首为|加单词字符、且行内不含Repo列名与---分隔线。GSD Project是否已初始化检查工作区目录/.planning/PROJECT.md是否存在。汇总输出将每个工作区整理为{ name, path, repo_count, strategy, has_project }结构连同workspace_base与workspace_count组成最终 JSON。从源码可见一个重要的判定细节WORKSPACE.md是工作区合法性的唯一准入标准。这也解释了为什么工作流展示的每个字段都能在磁盘上找到确切出处——Strategy与Repos来自WORKSPACE.mdGSD Project来自.planning/PROJECT.md的存在性探测。initListWorkspaces还遵循了 CJS 实现get-shit-done/bin/lib/init.cjs的cmdInitListWorkspaces的端口化约定保证 SDK 与旧版 CLI 输出行为一致。四、零工作区分支给出创建引导工作流首先检查workspace_count如果workspace_count为 0输出以下提示并结束No workspaces found in ~/gsd-workspaces/ Create one with: /gsd:workspace --new --name my-workspace --repos repo1,repo2这里的创建命令/gsd:workspace --new会路由到 new-workspace 工作流。其底层实现initNewWorkspacesdk/src/query/init.ts会返回若干初始化探测字段供创建流程参考字段含义default_workspace_base默认工作区根目录~/gsd-workspaceschild_repos/child_repo_count当前目录下的一级子 git 仓库清单及其数量检测.git目录并用git status --porcelain判断是否有未提交变更worktree_available是否安装了 git执行git --version探测is_git_repo当前目录本身是否为 git 仓库cwd_repo_name当前目录名用作默认工作区名五、有工作区分支表格渲染与字段语义如果存在工作区输出如下摘要表格GSD Workspaces (~/gsd-workspaces/) | Name | Repos | Strategy | GSD Project | |------|-------|----------|-------------| | feature-a | 3 | worktree | Yes | | feature-b | 2 | clone | No | Manage: cd ~/gsd-workspaces/name # Enter a workspace /gsd-remove-workspace name # Remove a workspace每行工作区的四个字段含义如下Name—— 目录名即~/gsd-workspaces/下的子目录名Repos—— 来自 init 数据中的repo_count由WORKSPACE.md表格行数统计得出Strategy—— 来自WORKSPACE.md的Strategy:行GSD Project——.planning/PROJECT.md是否存在存在为Yes否则为No。表格下方的 Manage 提示给出了两个高频操作cd ~/gsd-workspaces/name进入工作区以及/gsd-remove-workspace name删除工作区。其中/gsd-remove-workspace对应init.remove-workspace查询实现为initRemoveWorkspacesdk/src/query/init.ts它与 list 流程共享了WORKSPACE.md的解析规则按表格行正则^\|\s*(\S)\s*\|\s*(\S)\s*\|\s*(\S)\s*\|\s*(\S)\s*\|$提取Repo / Source / Branch / Strategy四列并会逐个仓库执行git status --porcelain检查未提交变更dirty_repos。值得注意的是initRemoveWorkspace对名称做了安全校验缺失名称、含/、\或..路径穿越序列时会抛出GSDErrorValidation 分类从而保证删除操作不能越出工作区根目录。六、WORKSPACE.md工作区元数据的磁盘真相由于WORKSPACE.md是判定工作区合法性与提取字段的核心理解其结构对排查列表与磁盘不一致问题至关重要。从initListWorkspaces与initRemoveWorkspace两个实现反向推导WORKSPACE.md包含两类可解析内容Strategy:行声明该工作区采用的仓库策略如worktree、clone正则要求行首为Strategy:解析后去除首尾空白。仓库表格至少包含| Repo | Source | Branch | Strategy |形式的四列表格每个数据行对应一个仓库仓库数即数据行数。解析器对表格行的过滤规则源自 sdk/src/query/init.ts是行首|后跟单词字符、且不包含Repo列名、不包含---分隔线——这套规则既规避了表头与分隔行也兼容仓库名以字母或数字开头的情形。七、测试验证与一致性保障initListWorkspaces的行为由 SDK 测试用例锁定见 sdk/src/query/init.test.tsdescribe(initListWorkspaces, () { it(returns flat JSON with workspaces array, async () { const result await initListWorkspaces([], tmpDir); const data result.data as Recordstring, unknown; expect(Array.isArray(data.workspaces)).toBe(true); expect(data.workspace_count).toBeGreaterThanOrEqual(0); }); });该测试断言返回结构为扁平 JSON 且workspaces是数组、workspace_count非负。此外在 SDK 的查询处理程序文档 sdk/src/query/QUERY-HANDLERS.md 中init.list-workspaces被列入SDK dispatchcanonical行列表明其输出与 CJS 实现保持全量toEqual对比的一致性要求——即无论经由新 SDK 还是旧 CLI 调用工作流拿到的初始化数据形状都是一致的这正是工作流可以放心依赖workspace_base / workspaces / workspace_count三个字段的前提。八、从触发到渲染的完整链路将上述内容串联list-workspaces 的完整执行链路为用户在 Claude Code 中输入/gsd:workspace --list或工作流被其他上下文直接引用命令路由表 commands/gsd/workspace.md 将--list映射到 list-workspaces 工作流工作流执行gsd-sdk query init.list-workspaces并处理file:前缀SDK 侧经 command-family-handlers.ts 分发到initListWorkspaces扫描~/gsd-workspaces/并汇总 JSON工作流解析workspace_count为 0 时输出创建引导大于 0 时按Name / Repos / Strategy / GSD Project渲染表格并附上进入cd与删除/gsd-remove-workspace的管理提示。九、适用前提与限制工作区根目录固定为~/gsd-workspaces由$HOME推导暂不支持自定义基目录配置仅目录内含WORKSPACE.md的子目录会被计入工作区无清单的目录一律忽略——如果列表少了某个目录优先检查该目录是否存在WORKSPACE.mdRepos数量来自WORKSPACE.md表格行的统计若清单表格结构不符合| Repo | Source | Branch | Strategy |约定计数可能为 0当前仓库以只读方式引用工作流与源码文中所有命令均为查看、运行与配置用途不涉及对仓库本身的修改。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考