【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇技术指南聚焦 gsd-core 中一个容易被忽视却极其关键的安全细节gsd-sdk query milestone.complete --help以及所有原生可变mutating查询处理器在收到--help/-h参数时不再执行任何磁盘写入而是被调度层短路到只读的帮助输出。文章会结合 milestone.cts 的处理器级校验与 command-routing-hub.test.cjs 的回归测试拆解「调度层 fail-closed 短路 处理器层防御纵深」的实现原理并给出安全使用milestone.complete的实战方法。一、问题背景为什么query前缀下藏着破坏性命令在 gsd-core 的命令体系里query是一个调用兼容性元前缀meta-prefix它暗示调用者这是一次读取。然而milestone.complete这个命令的实际行为完全是破坏性的从 init.cts 的注释可以看到milestone.complete会归档ROADMAP.md并且按照 milestone.cts 中的错误信息描述它还会归档REQUIREMENTS.md、把对应版本的每个 phase 目录移动进.planning/milestones/并重写STATE.md。问题正出在这里调用者持有query前缀意味着只读的单侧信念而命令本身却会写盘。一旦有人习惯性地敲下gsd-sdk query milestone.complete --help如果系统把--help当作普通参数或版本号继续执行一次想看看帮助的操作就可能真的完成一次里程碑归档——这正是本变更PR 3272类型Fixed要消除的威胁模型。二、第一道防线调度层 fail-closed 短路变更的核心修复位于命令调度层对于任何原生 mutating 处理器native mutating handler只要参数列表中出现--help或-h调度器就**直接短路short-circuit**到非变更non-mutating的帮助桩输出不再把参数透传给真正的处理器。这一层防护有两个关键性质fail-closed 默认在没有明确证据表明参数是合法业务输入时默认按需要帮助处理而不是默认执行写操作。即使处理器后续逻辑有漏洞破坏性路径也根本不会进入。覆盖全部 mutating 处理器修复不只针对milestone.complete而是覆盖所有原生 mutating 查询处理器属于调度器级别的统一闸门而不是逐命令打补丁。这与仓库里早已确立的 #1818 不变量一脉相承。在 command-routing-hub.test.cjs 的注释中记录了该不变量的完整演进gsd-tools 绝不能静默忽略--help/-h否则模型agent的幻觉参数可能演变成意外数据丢失例如phases clear --help真的清空 phase 目录。该测试还对比了历史响应形态过去--help导致非零错误退出现在--help渲染顶层用法并以退出码 0 结束不执行破坏性命令。对应的回归测试同一文件中 L1062-L1083直接验证了这一行为phases clear --help渲染用法且不清空 phase 目录generate-slug hello --help渲染用法且不产出 slug对照组generate-slug hello不带--help则正常产出结果。这套测试模式就是帮助请求与真实执行互斥的仓库级规范milestone.complete的修复正是把同一不变量扩展到query前缀下的 mutating 处理器。三、第二道防线处理器级防御纵深调度层短路是第一道闸但防御纵深要求在处理器内部也独立拒绝--help/-h。本变更同时让milestoneComplete在任何磁盘写入之前就把--help/-h作为非法版本值拒绝。为什么需要这一层因为version是milestone.complete的位置参数positional会被插值进多个文件系统写入点。在 milestone.cts 的cmdMilestoneComplete入口处可以看到处理器对版本值已经有一套严格的校验#2288 安全要求// #2288 security: version is a CLI positional that is interpolated into // multiple filesystem sinks below — path.join(archiveDir, ${version}-ROADMAP.md), // ${version}-REQUIREMENTS.md, ${version}-MILESTONE-AUDIT.md, and the // ${version}-phases archive directory that phase dirs are MOVED into. if (!ARCHIVE_VERSION_LABEL_RE.test(version)) { error(milestone complete: version ${version} is invalid — a milestone version label may contain only letters, digits, ., - and _, and must not contain path separators or ...); }这段校验原本是为了阻止路径穿越path traversal一个被构造的版本值不能把内容写到.planning/milestones/之外。本变更把它进一步收紧为--help/-h一旦混入版本位置参数同样在写盘前被拒。于是即使调度层短路被绕过、参数被错误透传处理器自己也会在第一条校验处终止。值得注意的是处理器级的这一拒绝对--help/-h的拒绝发生在任何磁盘写入之前且早于后续的确认闸门因此是一条独立的、不依赖调度器的兜底路径。四、破坏性命令本身的完整护栏确认闸门与 dry-run理解了--help的拦截后再看milestone.complete的完整执行护栏会更有价值——这些护栏共同保证了没有明确确认就不会写盘#3726 确认闸门见 milestone.cts确认闸门confirmation gatemilestone complete是不可逆操作。除非显式传入--confirm否则命令在完成参数校验后、任何读树操作之前就拒绝执行保证未确认的调用在磁盘上是绝对无操作no-op。--dry-run优先--dry-run不产生任何写入且不需要--confirm是官方推荐的第一步——先预览究竟会移动什么。--force不等于确认--force只放宽范围/状态类校验例如 phase 未全部 COMPLETE 时的强制归档绝不隐含--confirm。--confirm必须单独显式给出。结合这三条护栏milestone.complete的调用路径被明确划分为只读预览与确认写入两类而本次--help修复让查看帮助成为第三种、且被两层防线共同保证的纯只读路径。五、实战建议与验证方法1. 查看帮助永远安全以下命令现在是纯只读操作可以放心执行gsd-sdk query milestone.complete --help gsd-sdk query milestone.complete -h调度层会短路到非 mutating 帮助桩处理器层也会把--help/-h作为非法版本值拒绝——两条路径都保证零写盘。2. 真正完成里程碑归档的标准流程# 第一步只读预览无需 --confirm gsd-sdk query milestone.complete v1.0 --dry-run # 第二步确认后真正执行不可逆 gsd-sdk query milestone.complete v1.0 --confirm版本标签只能包含字母、数字、.、-、_不能含路径分隔符或..ARCHIVE_VERSION_LABEL_RE校验。3. 回归验证仓库的 command-routing-hub.test.cjs 提供了同类的可复制测试模式对任意破坏性命令断言「带--help时渲染用法且不产生副作用」与「不带--help时正常执行」同时成立。这条不变量从phases clear、generate-slug一路扩展到query前缀下的 mutating 处理器是 gsd-core 命令行安全测试的标准范式。六、小结本变更PR 3272用两层独立的防线回答了同一个问题帮助请求永远不该变成数据写入。调度层用 fail-closed 短路覆盖所有原生 mutating 处理器处理器层用版本值校验兜底milestoneComplete自身再加上既有的--confirm确认闸门与--dry-run预览机制milestone.complete这条看似查询、实为归档的命令终于在任何维度上都无法被--help意外触发。相关实现可分别查阅 milestone.cts、command-aliases.cts 中的命令规范映射以及 command-routing-hub.test.cjs 的回归测试。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD Core 安装期 Stale SDK 阴影检测用 npm ls -g 拦截残留 open-gsd/sdk 的 fail-closed 方案GSD Core 安装期 Stale SDK 阴影检测用 npm ls g 拦截残留 open gsd/sdk 的 fail closed 方案 导读 本文解决Micron R1常见问题3D打印爱好者必备故障排除手册解决Micron R1常见问题3D打印爱好者必备故障排除手册 Micron R1是一款备受欢迎的3D打印机以其出色的打印质量和稳定性赢得了众多爱好者的青睐。FGO-py云部署AWS/Azure/GCP云平台运行指南FGO py云部署AWS/Azure/GCP云平台运行指南 FGO py是一款针对Fate/Grand Order命运 冠位指定的自动化助手工具支持通过网页爬虫网络上一篇5种不同面粉对酸面团发酵的影响及选择指南从新手到专家的终极指南下一篇终极指南如何用AKShare为AI模型提供高质量的财经训练数据 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考