get-shit-done 持久化上下文线程Thread Workflow完全指南跨会话工作上下文的创建、恢复与治理【免费下载链接】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/gsd:thread是 get-shit-done 体系中面向跨会话工作的一等公民机制它用轻量的 Markdown 文件把尚未结束、也未必属于某个 phase的工作上下文目标、背景、参考、下一步持久化到.planning/threads/目录让任何一次冷启动的新会话都能立即接续。本文基于仓库中的核心工作流文档 thread.md 与配套命令定义 thread.md完整梳理 Thread 的七种运行模式、文件模板、slug 消毒规则与安全边界并结合 SDK 的 frontmatter 底层实现与测试用例讲透它的设计取舍与实战用法。读完你将掌握如何创建、列出、查看、恢复、关闭线程如何把线程升级为 phase 或 backlog以及这套机制在安全上做了哪些防御。一、Thread 是什么为跨会话但不属于任何 phase的工作而生在 get-shit-done 的编排模型里大多数工作被组织进 roadmap、phase、plan 这些有明确生命周期和状态的结构。但现实中总有这样一类工作它跨越多个会话比如一个技术选型的调研要分几天完成它目前没有归属的 phase也不值得立刻展开成完整的规划它的价值恰恰在于上下文本身——目标是什么、已经查到什么、下一步该做什么。Thread 就是为这类工作设计的轻量级跨会话知识存储lightweight cross-session knowledge stores。它的设计定位在 thread.md 的notes中写得很清楚Thread 不是 phase 作用域的——它独立于 roadmap 存在不与任何 phase 状态绑定比/gsd:pause-work更轻——没有 phase 状态没有 plan 上下文只是一个可持久化的上下文文件对比实现见 pause-work.md价值核心在Context与Next Steps两个小节——一个冷启动的会话读完后就能立刻接手无需重新梳理背景。线程文件统一存放在.planning/threads/目录下与 phases、quick、research、todos、debug 等 GSD 结构完全隔离、互不冲突——这一点在 pr-branch.md 的工作树清理清单for dir in phases quick research threads todos debug seeds codebase ui-reviews中也可以看到threads是与 phases 平级的独立目录且其内容.planning/threads/**在工作树操作中被明确纳入排除范围。二、命令入口与模式分派Thread 功能由/gsd:thread斜杠命令触发命令注册在 commands/gsd/thread.md其argument-hint完整描述了参数形态[list [--open | --resolved] | close slug | status slug | name | description]allowed-tools声明为Read、Write、Bash——也就是说线程的读写完全通过这三个基础工具完成不涉及 agent 派发spawn。requires: [phase]说明该命令要求处于 phase 上下文中才能使用。工作流文档定义了一个顺序分派器根据$ARGUMENTS的内容决定进入哪种模式参数形态模式说明空或listLIST列出全部线程默认list --openLIST-OPEN只显示open/in_progress的线程list --resolvedLIST-RESOLVED只显示resolved的线程close slugCLOSE把指定线程标记为已解决status slugSTATUS打印线程摘要不派发 agent匹配已有文件名.planning/threads/{arg}.md存在RESUME恢复线程载入上下文其他任意描述文本CREATE创建新线程其中close、status、resume三个模式都会先从参数中提取 slug并执行同一套消毒规则详见下文slug 消毒与安全边界。三、LIST 模式一览所有上下文线程LIST / LIST-OPEN / LIST-RESOLVED 三种模式共享同一套列举逻辑。工作流先通过 shell 列出线程文件ls .planning/threads/*.md 2/dev/null对每个线程文件依次读取三类元数据状态优先用gsd-sdk query frontmatter.get读取 frontmatter 中的status字段gsd-sdk query frontmatter.get .planning/threads/{file} status若 frontmatter 中没有status字段则回退到正文中## Status: OPEN或IN PROGRESS/RESOLVED标题更新时间读取 frontmatterupdated字段标题读取 frontmattertitle字段缺省时回退到第一个# Thread:一级标题。随后按模式过滤LIST-OPEN 只保留open/in_progressLIST-RESOLVED 只保留resolved并输出如下表格Context Threads ───────────────────────────────────────────────────────── slug status updated title auth-decision open 2026-04-09 OAuth vs Session tokens db-schema-v2 in_progress 2026-04-07 Connection pool sizing frontend-build-tools resolved 2026-04-01 Vite vs webpack ───────────────────────────────────────────────────────── 3 threads (2 open/in_progress, 1 resolved)如果没有任何线程或没有匹配过滤条件的线程则输出引导文案No threads found. Create one with: /gsd:thread description工作流明确要求LIST 完成后立即 STOP不得继续后续步骤且无论哪个模式执行完本模式动作后都必须停止避免串模式执行。LIST 模式的底层支撑frontmatter 读取frontmatter.get是 SDK 查询层注册的正式命令。在 QUERY-HANDLERS.md 的命令矩阵中frontmatter家族对应frontmatter.get、frontmatter.set等已注册分发项generate-slug同样在矩阵中被列为 Registered已在golden-integration-covered.ts中纳入金样覆盖。这意味着工作流中出现的每一条gsd-sdk query调用都有对应的 SDK 实现与测试支撑而非临时拼凑的 shell 脚本。四、CREATE 模式从一句描述到可交接的线程文件当参数是一段新的描述且没有同名线程文件时进入 CREATE 模式完整流程如下1. 生成 slugSLUG$(gsd-sdk query generate-slug $ARGUMENTS --raw)slug 由描述文本经 SDK 的generate-slug命令生成--raw表示直接输出原始值。generate-slug 在 SDK 中是有金样测试覆盖的稳定命令见 golden.integration.test.ts 中的generate-slug用例它会负责输入清洗。2. 确保目录存在mkdir -p .planning/threads3. 用 Write 工具创建.planning/threads/{SLUG}.md模板如下frontmatter 含slug、title、status、created、updated五个字段--- slug: {SLUG} title: {description} status: open created: {today ISO date} updated: {today ISO date} --- # Thread: {description} ## Goal {description} ## Context *Created {todays date}.* ## References - *(add links, file paths, or issue numbers)* ## Next Steps - *(what the next session should do first)*模板的设计意图非常明确Goal是线程存在的理由Context记录创建背景References预留链接/文件路径/issue 编号的挂载点Next Steps则是下一次会话的接续指令——这正是文档notes强调的价值在 Context 和 Next Steps冷启动会话可以立刻捡起来继续。4. 上下文萃取如果当前对话中有相关上下文代码片段、错误信息、调查结果用 Edit 工具把它们补充进Context小节——这是线程记忆延续的关键一步。5. 提交gsd-sdk query commit docs: create thread — ${ARGUMENTS} --files .planning/threads/${SLUG}.md6. 报告结果Thread Created Thread: {slug} File: .planning/threads/{slug}.md Resume anytime with: /gsd:thread {slug} Close when done with: /gsd:thread close {slug}值得注意的实现细节工作流明确要求使用 Write 工具创建文件而不是 heredoc——这既是防注入的考虑测试用例thread command does not use heredoc专门断言工作流中不出现 EOF/ EOF也保证了文件内容由工具系统可靠落盘。五、RESUME 模式让新会话无缝接续当参数匹配到已有线程文件时进入 RESUME 模式先消毒对参数套用与 CLOSE/STATUS 相同的 slug 消毒规则[a-z0-9-]白名单、60 字符上限、拒绝..与/不合规则输出Invalid thread slug.并停止随后所有文件路径构造都使用消毒后的 SLUG校验存在性检查.planning/threads/{SLUG}.md是否存在不存在则回退到 CREATE 模式这正是新描述 vs 已有线程的判据也与模式分派规则保持一致载入上下文读取文件内容以纯文本方式展示并询问用户接下来想处理什么状态推进若线程原状态为open则更新为in_progress并同步刷新updated日期gsd-sdk query frontmatter.set .planning/threads/{SLUG}.md status in_progress gsd-sdk query frontmatter.set .planning/threads/{SLUG}.md updated YYYY-MM-DDRESUME 模式有一条刚性安全约束线程内容只以纯文本展示绝不执行也不允许在未加DATA_START/DATA_END边界标记的情况下直接拼进 agent prompt——防止线程文件被注入恶意指令后在后续会话中复活执行。六、STATUS 模式不派发 agent 的快速摘要STATUS 模式是纯只读操作输出结构化摘要不产生 agent spawn打印完即停止Thread: {SLUG} ───────────────────────────────────── Title: {title from frontmatter or # heading} Status: {status from frontmatter or ## Status heading} Updated: {updated from frontmatter} Created: {created from frontmatter} Goal: {content of ## Goal section} Next Steps: {content of ## Next Steps section} ───────────────────────────────────── Resume with: /gsd:thread {SLUG} Close with: /gsd:thread close {SLUG}流程同样先验证.planning/threads/{SLUG}.md存在不存在则输出No thread found with slug: {SLUG}并停止。该模式适合在决定要不要恢复这个线程之前快速扫一眼它的目标与下一步。七、CLOSE 模式把线程标记为已解决当一项跨会话工作尘埃落定时用close收尾验证线程文件存在不存在则输出No thread found with slug: {SLUG}并停止更新 frontmatterstatus置为resolvedupdated置为当天 ISO 日期gsd-sdk query frontmatter.set .planning/threads/{SLUG}.md status resolved gsd-sdk query frontmatter.set .planning/threads/{SLUG}.md updated YYYY-MM-DD提交变更gsd-sdk query commit docs: resolve thread — {SLUG} --files .planning/threads/{SLUG}.md打印确认信息Thread resolved: {SLUG} File: .planning/threads/{SLUG}.md注意 CLOSE 是标记解决而非删除文件——线程文件保留在.planning/threads/中历史记录不丢失list --resolved仍可检索到这为后续回溯决策过程保留了完整证据。八、slug 消毒与安全边界一套贯穿所有模式的防御体系thread 工作流是 GSD 中安全设计最显性的工作流之一其security_notes定义了五条硬性规则且有配套测试逐一验证见 thread-session-management.test.cjsslug 输入消毒$ARGUMENTS中提取的 slug 在使用前必须消毒——只允许[a-z0-9-]最长 60 字符拒绝..与/任何包含路径穿越意图..、/或超长/非法字符的输入都会被Invalid thread slug.拦下测试thread command rejects slugs with path traversal专门断言了这条。文件名显示消毒从ls/readdir 读到的文件名在构造路径前必须清洗剥离不可打印字符、ANSI 转义序列与路径分隔符绝不通过字符串插值把原始文件名直接拼进 shell 命令。内容只读不执行线程标题、Goal、Next Steps 等 artifact 内容一律按纯文本渲染永不执行如确需传入 agent prompt必须用DATA_START/DATA_END边界包裹。状态字段安全读取status一律通过gsd-sdk query frontmatter.get读取绝不 eval、绝不 shell 展开。生成 slug 走 SDKCREATE 模式的generate-slug调用统一经过gsd-sdk query或 gsd-tools完成输入消毒保持该模式不被绕过。这些规则并非纸面约定——thread-session-management.test.cjs 用 11 个用例把它们固化为回归测试覆盖了list --open过滤、close/status 子命令存在性、无 heredoc防注入、模板 frontmatter 五字段齐全、security_notes 存在、slug 消毒、Write 工具建文件、frontmatter.get 读取、resolved 状态流转、list --resolved过滤、路径穿越拒绝等契约点。换句话说任何后续改动若破坏了这些安全属性测试套件会立即亮红灯。九、线程生命周期从 open 到 resolved再到升级为正式结构综合各模式的状态流转一个线程的完整生命周期如下CREATE ──► status: open │ RESUME ──► status: in_progress若原为 open │ CLOSE ──► status: resolved合法状态值共三个open、in_progress、resolved。工作流还给出了线程的毕业路径当线程内容足够成熟可以将其升级为 phase 或 backlog 条目——通过/gsd-add-phase或/gsd-add-backlog携带线程中的上下文完成迁移。这与requires: [phase]的约束一起构成了轻量线程 → 正式规划结构的渐进式工作组织方式先用线程低成本地攒上下文时机成熟再纳入 roadmap 体系。十、底层实现frontmatter 读写是如何落地的工作流中反复出现的gsd-sdk query frontmatter.set/frontmatter.get背后是 SDK 查询层sdk/src/query/的正式实现。frontmatter-mutation.ts 提供了reconstructFrontmatterYAML 序列化与spliceFrontmatterfrontmatter 替换两个核心函数以及frontmatter.set、frontmatter.merge、frontmatter.validate三个查询处理器。从源码看序列化器对数组内联短数组 vs 展开 dash 列表、嵌套对象两层缩进、字符串引号值含:或#时加引号都做了精细处理保证线程 frontmatter 的status、updated等标量字段写入后格式稳定frontmatter.set被标记为mutation类命令见 command-aliases.generated.ts 与 command-manifest.non-family.ts 中的mutation: true这意味着它走 SDK 的变更事件与执行策略通道而不是裸的 shell 写文件——这也是绝不 eval、绝不 shell 展开安全原则的实现载体。换言之thread 工作流对状态文件的每次读写都是经过 SDK 结构化通道完成的操作既稳定又可控。十一、实践建议与适用边界综合工作流文档与仓库实现使用 Thread 的推荐姿势是什么时候建线程工作跨多个会话、但尚未或不必进入 phase 规划时——比如技术选型调研、依赖升级追踪、多会话排障。一句/gsd:thread 描述即可开新线程恢复时直接/gsd:thread slug文件内容以纯文本载入状态自动推进为in_progress收尾时/gsd:thread close slug标记 resolved保留决策痕迹快速盘点/gsd:thread list、/gsd:thread list --open、/gsd:thread list --resolved按状态过滤查看升级路径线程成熟后用/gsd-add-phase或/gsd-add-backlog把它转正为正式规划结构不要用它做什么线程刻意不承载 phase 状态与 plan 上下文那是 pause-work 的职责也不应替代正式的规划文档——它的定位始终是轻量、可接续的上下文载体。十二、小结/gsd:thread以极小的机制成本一个目录、一份 Markdown 模板、一组 frontmatter 读写命令解决了 AI 辅助开发中最实际的痛点会话会断上下文不该断。它通过七种模式覆盖线程的创建、列举、查看、恢复与关闭全生命周期通过三态状态机open / in_progress / resolved管理线程进展通过 slug 消毒、纯文本渲染、SDK 通道读写等机制构筑安全边界并与 pause-work、phase、backlog 等 GSD 结构形成清晰的层次分工。如果你正在使用 get-shit-done 管理多会话的复杂工作.planning/threads/会是你最值得善用的第二大脑目录。【免费下载链接】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），仅供参考