依赖刷新手册（dependency-refresh）
为 agent-service-toolkit 仓库执行安全、有纪律的月度依赖与版本刷新，覆盖 Python 锁文件、Actions、uv CLI、基础镜像与基础设施镜像。
项目自身的依赖升级流程（要求先读完整 playbook 文档再动手，不允许即兴改动），服务于该项目维护者。
这个 Skill 能做什么，适合哪些场景？
dependency-refresh 是 agent-service-toolkit 仓库内的一个自包含运维技能，提供完整的依赖刷新剧本。它不只更新 pyproject.toml 和 uv.lock 中的 Python 包，还覆盖 Docker 基础镜像、GitHub Actions 固定版本、uv CLI 的四处同步位置、受支持的 Python 版本区间，以及 compose 与冒烟测试使用的 postgres/mongo/LangFuse 镜像。技能内置两层冷却机制：由 uv exclude-newer 强制执行的全局 14 天解析器冷却，以及针对关键依赖的三个月大版本冷却。每轮刷新产出一个 PR，其正文同时作为下一轮刷新的状态记录。配套的 references 目录记录版本耦合约束与端到端验证方法。
第 0 步先搜索最近一次刷新 PR，恢复延期大版本表和验证注意事项；随后对照 PyPI API 与各非 Python 表面盘点所有可升级项；按分级原则和双重冷却策略逐项评估；对安全升级直接修改 pyproject.toml 中的钉定版本；运行 uv lock --upgrade 重新解析，将钉定值与锁文件对齐；执行 uv sync --frozen、ruff check、ruff format --check、pyrefly check 和 pytest；需要时按 references/live-e2e.md 运行假模型 HTTP 阶梯测试和 Streamlit 浏览器冒烟，涉及 checkpointer、AG-UI 或 LangFuse 时运行 scripts/smoke_test.sh 对应目标；最后按约定格式（分支 claude/dependency-refresh-YYYY-MM-DD、标题 chore(deps): dependency refresh YYYY-MM-DD、含 What moved / Deferred majors / Verification 三个正文板块）提交 PR。
- 独自维护 LangGraph/FastAPI/Streamlit 项目、需要按月规律升级依赖但不想追新踩坑的开发者
- 收到 Dependabot 安全公告、需要立即绕过冷却合入修复的维护者
- langchain 与 langgraph 等强耦合包需要同步升级、经常遇到解析器冲突的团队
- postgres/mongo 等镜像大版本可能改变磁盘格式、需要谨慎等待的运维人员
- 希望每次升级都有可追溯 PR 记录（什么动了、什么延期、验证结果）的 AI 维护代理场景
- 需要保持 Python 支持区间、CI 矩阵、ruff 目标版本和 Docker 基础镜像相互一致的项目
这个 Skill 有哪些优点和局限？
- 自包含的完整剧本，从状态恢复到 PR 提交全流程有据可依
- 两层冷却机制（uv 强制的 14 天 + 流程强制的 3 个月大版本冷却）显著降低引入损坏或被投毒新版本的风险
- PR 即状态的约定使每轮刷新可追溯，延期大版本表跨轮次自动结转
- references/coupling-constraints.md 沉淀了 langchain⇄langgraph 锁步、checkpointer 大版本等实际踩坑经验
- 安全修复有明确的唯一豁免通道，且要求临时覆盖带注释并在下轮移除
- 深度绑定 agent-service-toolkit 的文件布局（uv.lock、compose.yaml、scripts/smoke_test.sh 等），直接用于其他仓库需大量改造
- 流程性约定（三个月冷却、PR 模板）依赖模型自觉遵守，无法机械强制
- 冒烟测试需要 Docker 守护进程，LangFuse 目标被明确标注为重量级（要启动完整自托管栈）
- 运行状态存放在历史 PR 描述中而非文件，依赖 PR 搜索能成功找到上一次刷新
如何安装这个 Skill？
该技能属于 JoshuaC215/agent-service-toolkit 仓库捆绑的 4 个技能之一，路径为 .claude/skills/dependency-refresh/。将整个技能目录（含 SKILL.md 和 references/ 下的 coupling-constraints.md、live-e2e.md）放入你的 Claude Code 项目的 .claude/skills/ 目录即可。仓库 README 描述的是整个集合的安装；针对此单个技能的独立安装步骤未在文档中说明。
如何使用这个 Skill？
在配置了该技能的仓库中，对 Claude 发出类似「update dependencies」「bump versions」「do a dependency refresh」的请求，或等待定期的月度依赖刷新触发。技能会自动按步骤执行：先恢复上次 PR 状态，再盘点、分级、应用安全升级、重新锁定、静态验证、端到端验证，最后产出格式化的刷新 PR。注意该剧本针对 agent-service-toolkit 的具体结构编写，references 中包含项目特定的耦合约束，移植到其他仓库需要相应调整。
这个 Skill 与同类方案有什么区别？
与直接运行 uv lock --upgrade 或依赖 Dependabot 自动合并相比，本技能额外提供冷却策略、关键依赖大版本延期、跨表面（Actions/uv CLI/镜像）同步，以及把每轮状态写入 PR 的可追溯流程；代价是更重、更慢，且与单一仓库结构耦合。