人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本篇技术指南围绕 GSD-2 仓库内置的dep-upgrade工作流模板展开讲解如何在项目中安全地升级依赖先评估破坏性变更再增量升级、修复破坏、最后全量验证。读完本文你将掌握 GSD-2 工作流模板的注册与触发机制、/gsd start dep-upgrade的完整执行过程、四阶段的操作规范以及它与dependency-upgrade技能配合使用时按风险分批、批间验证、一个 major 一个 commit的实战策略。一、什么是 dep-upgrade 工作流模板GSD-2 是一个面向长周期自主运行的元提示meta-prompting、上下文工程与规范驱动开发spec-driven development系统。为了让 Agent 在处理高频任务时不必每次都搭建完整里程碑仓库在 src/resources/extensions/gsd/workflow-templates 目录下预置了一批工作流模板workflow templatesdep-upgrade就是其中之一用于处理升级项目依赖这一类高频且高风险的任务。模板的完整定义位于 dep-upgrade.md其核心目标是Upgrade project dependencies safely. Assess breaking changes before upgrading, fix issues incrementally, and verify everything works. Handles both single-package upgrades and bulk dependency refresh.即安全升级依赖——升级前评估破坏性变更增量修复问题并验证一切正常同时支持单包升级与批量依赖刷新两种场景。模板注册与元信息模板并不是散落的 Markdown 文件而是通过 registry.json 统一注册。dep-upgrade在注册表中的条目如下dep-upgrade: { name: Dependency Upgrade, description: Assess impact, upgrade dependencies, fix breaking changes, file: dep-upgrade.md, mode: markdown-phase, phases: [assess, upgrade, fix, verify], triggers: [upgrade, update, dependency, deps, bump, outdated, npm update, renovate], artifact_dir: .gsd/workflows/upgrades/, estimated_complexity: medium, requires_project: false }各字段含义与在本次升级场景中的实际影响字段取值说明nameDependency Upgrade模板显示名称用于/gsd templates info等展示场景filedep-upgrade.md模板正文文件被加载后注入workflow-start提示词modemarkdown-phase执行模式表示按 Markdown 中定义的阶段顺序推进非 oneshot、非 yaml-step、非 auto-milestonephasesassess / upgrade / fix / verify四阶段流水线也是目录命名与状态跟踪的基础triggersupgrade、update、deps、bump、outdated、npm update、renovate 等关键词触发用于从自然语言描述中自动识别该模板artifact_dir.gsd/workflows/upgrades/产物目录前缀每次运行会生成一个编号子目录estimated_complexitymedium预估复杂度medium 表示中等规模的例行任务requires_projectfalse不强制要求已初始化.gsd/项目可即开即用模板自身头部还包含一段template_meta声明见 dep-upgrade.md其中mode: markdown-phase、requires_project: false、artifact_dir: .gsd/workflows/upgrades/与注册表条目保持一致二者共同决定引擎如何调度。四种执行模式从 workflow-templates.ts 的源码可以看出模板共有四种执行模式oneshot一次性任务、yaml-stepYAML 引擎驱动、markdown-phase按 Markdown 阶段推进、auto-milestone基于数据库的完整里程碑流程。dep-upgrade属于markdown-phase执行时会经历完整的阶段状态机与产物记录。二、如何触发 dep-upgrade 工作流触发方式分为显式指定与自动识别两种两者都收敛到同一个handleStart调度入口见 commands-workflow-templates.ts。显式指定模板/gsd start dep-upgrade # 直接指定模板description 可为空 /gsd start dep-upgrade 升级 React 与 TypeScript # 附带描述用于生成分支与产物命名模板别名机制见 workflow-templates.ts也允许你用更口语化的词触发upgrade、deps、update-deps都会被解析映射到dep-upgrade。关键词自动识别当输入中没有显式模板名时引擎会调用autoDetect(description)见 workflow-templates.ts把用户描述与每个模板的triggers关键词做匹配打分短语命中多词 trigger如npm update得分更高每个词计 2 分单词命中计 1 分得分 ≥4 判定为high置信度≥2 为medium否则low。例如输入upgrade react to v19时upgrade命中dep-upgrade的 trigger。这一点也有对应的单元测试覆盖在 workflow-templates.test.ts 中autoDetect(upgrade react to v19)的返回结果被断言必须包含dep-upgrade。如果多个模板同时命中引擎会列出前 4 个候选并提示你显式选择不会擅自执行。常用命令一览根据 gitbook/features/workflow-templates.md 与源码实现与 dep-upgrade 相关的命令包括/gsd start # 无参数列出模板或提示正在进行的可恢复工作流 /gsd start resume # 恢复最近一次未完成的工作流 /gsd start --list # 同 /gsd templates列出所有模板 /gsd start --dry-run dep-upgrade 升级 axios # 预览本次运行的产物目录与分支名不执行任何操作 /gsd templates # 列出全部模板及各自阶段 /gsd templates info dep-upgrade # 查看该模板的详细元信息阶段、触发词、复杂度等注意/gsd start在 auto-mode 运行期间会被拦截提示先/gsd pause因为工作流模板会自行切换 git 分支并派发消息与 auto-mode 的派发循环冲突。三、执行时引擎做了什么源码级行为当模板被解析成功后引擎并不只是把 Markdown 丢给 Agent而是会完成一整套运行前准备见 commands-workflow-templates.ts创建产物目录在.gsd/workflows/upgrades/下生成形如YYMMDD-N-slug的目录例如.gsd/workflows/upgrades/261006-1-upgrade-react-typescript。其中编号通过对已存在目录扫描自增getNextWorkflowNumslug 由描述文本 URL 化而来slugify最长 40 字符。创建 git 分支自动执行git checkout -b gsd/dep-upgrade/slug把升级工作隔离在独立分支上避免污染主分支。若 git 偏好配置了isolation: none则跳过建分支。写入状态文件在产物目录中写入STATE.json包含模板名、描述、分支、四阶段及各自状态、开始时间这是/gsd start resume恢复进度的依据。恢复时会读取最近的未完成工作流按assess ✓ → upgrade ← → fix → verify的形式展示各阶段进度✓表示已完成←表示当前阶段。派发workflow-start提示词把模板全文dep-upgrade.md内容、模板描述、阶段列表、分支、产物目录等注入提示词模板通过pi.sendMessage触发一次 Agent 轮次。模板的读取与注入逻辑见 workflow-templates.ts 的loadWorkflowTemplate。此外如果项目或全局存在同名dep-upgrade的 Markdown 格式插件覆盖引擎会优先使用覆盖版本resolvePlugin否则回退到内置模板。四、四阶段工作流详解这是模板正文dep-upgrade.md的核心内容是 Agent 在每个阶段必须执行的规范。Phase 1: Assess评估——升级前先搞清楚要面对什么目标在改变版本号之前充分了解你将面临什么。列出过期的依赖运行npm outdatedNode.js 生态或等价命令Python 用pip list --outdated、Rust 用cargo outdated、Ruby 用bundle outdated、Go 用go list -m -u all。对每个目标升级包阅读 changelog / release notes识别破坏性变更breaking changes查找是否有官方迁移指南评估对代码库的影响面用rg等工具 grep 被影响的 API 调用处。排定优先级决定哪些现在升级、哪些推迟。产出ASSESSMENT.md内容必须包含依赖清单标注当前版本 → 目标版本每个依赖的破坏性变更升级顺序先升级被依赖的底层包再升级依赖它们的包风险评估。Gate门禁将评估结果交给用户复核确认本次升级范围。这一阶段的核心理念是先侦察、后动手。结合仓库自带的dependency-upgrade技能见 SKILL.mdAssess 阶段还应顺手记录npm audit结果与语言运行时、构建工具、测试运行器的当前版本作为风险分级的输入。Phase 2: Upgrade升级——增量应用版本提升目标以小步方式应用版本提升。每次只升级一个依赖或一组相互关联的依赖每次升级后运行测试每次升级单独提交提交信息遵循约定chore(deps): upgrade package to version如果测试失败立即针对该依赖进入 Phase 3修复完成后再继续。这里体现的是小步提交、失败即停的原则任何一个升级导致测试失败都应当即定位、即修复而不是带着失败继续堆积下一个升级。Phase 3: Fix修复——解决升级带来的破坏目标解决升级引入的破坏性变更。修复 API 变更、类型错误、弃用deprecation问题按需更新配置单独提交修复与升级提交分离提交信息遵循约定fix(deps): adapt to package vversion changes。提交分离的价值在于让 git 历史说真话升级提交只包含版本变化修复提交只包含适配代码回滚时可以只回滚其中一个。Phase 4: Verify验证——确认一切协同正常目标确保所有部分协同工作。运行完整测试套件运行构建build运行 linter检查输出中的弃用警告deprecation warnings产出SUMMARY.md内容必须包含已升级的依赖from → to遇到的破坏性变更及其解决方式任何推迟升级的依赖及推迟原因。ASSESSMENT.md 与 SUMMARY.md 会写入该次运行对应的产物目录.gsd/workflows/upgrades/YYMMDD-N-slug/与STATE.json一起形成可审计的升级档案。五、与 dependency-upgrade 技能的配合执行层的深度增强GSD-2 在模板之外还内置了一个配套技能dependency-upgradesrc/resources/skills/dependency-upgrade/SKILL.md其定位是模板的 execute 层细节——模板定义四阶段的骨架技能则回答具体怎么批量、怎么验证、升级坏了怎么恢复。按风险分批不按惰性分批技能的核心原则是不要盲目运行npm update因为它会把安全与危险的变化混进同一个 commit一旦出问题就无法定位是哪个依赖导致的。正确的分批顺序是Batch 1 — 开发依赖的 patch 与 minor风险最低、反馈最快包括 linter、formatter、类型定义、测试运行器Batch 2 — 运行时依赖的 patch一起处理Batch 3 — 运行时依赖的 minor若某个 minor 携带风险说明则单独成批否则合并为一批Batch 4 — 每个 major 单独处理一个 major 一个 commit框架级升级React、Next.js、Vue、TypeScript各自独立提交Batch N — 语言运行时Node/Python/Rust 的升级放在最后因为它会改变所有代码的编译/运行环境。同时跳过暂缓含unreleased、pre、beta、rc标签的版本除非用户明确要求跟踪预发布以及已知被其他依赖阻塞的升级。批间验证与提交规范每执行一个批次都要按序完成从干净工作区开始git status→ 应用升级 → 必要时完整重新生成 lockfile → 跑真实构建而非仅 typecheck→ 跑完整测试套件而非子集→ lint 对变更文件跑lsp diagnostics→ 如果有运行界面则做冒烟测试。任一步失败都要先调查、不跳过该批次。提交信息建议使用结构化模板deps: bump scope — what changed in one line - package-a: 1.2.3 → 1.2.9 (patch) - package-b: 2.1.0 → 2.4.0 (minor — no breaking changes in CHANGELOG) - package-c: 3.0.1 → 3.0.2 (patch) Verified: npm test (84/84 pass), npm run build exit 0, lsp diagnostics clean.处理卡住的 major 升级若某个 major 升级破坏面过大先读迁移指南不要猜测 API 变更用rg摸清影响范围然后二选一——要么立即升级把迁移工作拆成独立 slice升级只是其中一项任务迁移完成后端到端验证要么推迟提一个/gsd start refactor后续工作流并暂时钉住当前 major 版本。汇总报告所有批次结束后产出汇总报告对应模板的SUMMARY.md建议包含已完成批次与对应 commit、推迟项及原因、仍有意的过期项钉住原因、安全公告处置情况CVE resolved by package upgrade/ 已 triage 判定当前用法不可利用。非显而易见的升级坑也应追加到.gsd/KNOWLEDGE.md沉淀为项目知识。反模式清单与成功标准技能中明确列出的反模式即 Agent 应避免的行为盲目npm update——安全与风险混在一个无法诊断的 commit 中多个 major 塞进一个 commit——坏了分不清是谁的锅批间不做验证——把失败堆到无法工作跳过 CHANGELOG——只是个 minor直到它不是用--force强合并失败的批次——要么修复要么回滚不要向 git 撒谎忽略--legacy-peer-deps警告——它在告诉你依赖图已经不自洽。成功标准可用于检查升级是否真正完成每个批次有独立 commit 且信息精确major 升级一包一提交每个批次之后测试套件、构建、lint 均通过卡住的升级有明确的下一步已记录为 slice/里程碑或已说明原因地钉住安全公告已处置或已明确 triage存在供用户审阅的汇总报告。六、恢复与审计如何接续和复盘一次升级由于每次运行都写入了STATE.json并创建了独立分支升级工作天然可恢复、可审计中途恢复/gsd start resume会定位最近一次未完成的工作流提示当前进度如assess ✓ → upgrade ← → fix → verify与分支、产物目录然后把模板内容重新注入 Agent 轮次从当前阶段继续无参启动提示直接运行/gsd start时如果存在进行中的工作流会先提示你已找到进行中的工作流运行/gsd start resume继续审计档案每个产物目录.gsd/workflows/upgrades/YYMMDD-N-slug/同时保存ASSESSMENT.md、SUMMARY.md与STATE.json配合按约定命名、语义清晰的 git 提交历史可以完整复盘一次依赖升级的决策与执行过程。结语GSD-2 的dep-upgrade工作流把升级依赖从一次性的危险操作变成了有评估门禁、有小步提交、有独立修复、有全量验证、有产物档案的规范流程。模板定义骨架dep-upgrade.md注册表定义元信息与触发registry.json调度引擎负责分支、产物、状态与恢复commands-workflow-templates.ts配套技能补齐执行层细节SKILL.md。对任何需要长期、自主、可审计地维护依赖健康的项目而言这套assess → upgrade → fix → verify的组合拳都值得直接落地复用。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Langfuse 依赖升级实战指南基于 pnpm-upgrade-package Skill 的安全依赖升级工作流Langfuse 依赖升级实战指南基于 pnpm upgrade package Skill 的安全依赖升级工作流 本文基于 Langfuse 开源仓库中的人工智能LLMOps可观测性AI 评测LLM 网关后端前端npm 依赖升级审查工作流指南React Cosmos review-dep-upgrade 技能实战与源码解析npm 依赖升级审查工作流指南React Cosmos review dep upgrade 技能实战与源码解析 本文以仓库内的 Agent 技能文档 SKI开发工具前端测试使用 astrojs/upgrade 一键同步升级 Astro 官方集成与依赖使用 astrojs/upgrade 一键同步升级 Astro 官方集成与依赖 Astro 官方提供了一条专门用于升级的命令行工具 astrojs/upgr前端Web框架SSR前端构建上一篇终极指南John the Ripper密码工具的GPLv2合规红线与法律风险规避下一篇使用 AWS CLI 创建 Amazon Chime 聊天室create-room 命令详解与源码解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考