人工智能AI 技能AI 插件开发工具【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址https://gitcode.com/GitHub_Trending/ps/pstack-claude点击查看免费下载本文是 pstack 技能栈中架构类原则之一「Migrate Callers Then Delete Legacy APIs」的完整技术指南。它回答一个在内部 API 演进中反复出现的问题当新 API 已经确定是正确设计时旧的调用者该怎么办答案不是铺一层兼容层而是在同一个重构波次中清点调用者、完成迁移、立即删除旧 API。读完本文你将掌握该原则的触发条件、四步执行流程、测试处置规则以及它如何与 pstack 中outcome-oriented-execution、sequence-verifiable-units、test-behavior-not-implementation等相邻原则协同直接落地到真实的重构现场。原则定义一个新 API 落地时的强制动作原文档plugins/pstack/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md给出的核心表述非常直接当我们判定新 API 是正确设计时应当在同一个重构波次中迁移调用者并移除旧 API而不是保留兼容层。这是一条行为规范不是建议。它的约束对象是内部 API的演进过程——即旧调用者全部存在于代码库内部、不涉及外部消费者契约的场景。该原则在 pstack 技能体系中的定位可以从 poteto-mode 的 Principles 索引 看到它被归入Architecture架构类别与model-the-domain、boundary-discipline、type-system-discipline、make-operations-idempotent、separate-before-serializing-shared-state并列说明它处理的是系统结构如何演化这一类基础性问题。四条核心规则原文档将规则浓缩为四条每一条都指向一个具体的行为约束规则一不要仅仅因为内部调用者还存在就保留旧 API 路径。这是原则的否定面。内部调用者的存在不是保留旧 API 的充分理由——调用者是可以被迁移的而迁移正是本次重构波次的工作内容。规则二清点调用者、迁移它们、立即删除旧 API。这是原则的肯定面也是执行顺序先搞清楚谁在用旧 API清点再把它们全部切到新 API迁移最后在同一波次内删除旧 API删除。三步缺一不可且不能跨波次拖延。规则三把临时适配器视为例外且必须设定期限而不是默认架构。临时适配器adapter/shim并非绝对禁止但它必须是例外 时间盒time-boxed的组合有明确的到期时间、有明确的清理任务不能无限期存活。一旦把适配器当作默认方案它就从临时桥退化为永久债务。规则四更新测试以断言新契约删除只保护重构前实现细节的测试。测试跟着契约走不跟着实现细节走。迁移后测试应当断言新 API 的契约行为那些仅仅为了旧实现细节而存在的测试例如断言某个私有中间状态、某个被删除函数的调用痕迹应当一并删除。适用条件何时触发这条原则原文档给出了三个触发条件三者共同界定同波迁移的适用边界没有外部用户依赖向后兼容。这是先决条件。如果存在必须保持兼容的外部消费者那就进入了另一个决策空间需要版本策略或兼容层本原则不再适用。项目能够承受协调一致的破坏性变更。同波迁移意味着所有调用者一次性改动这需要项目具备协调能力——通常是单一代码库或可控的多包结构。新 API 属于简化或重构倡议的一部分。原则服务于简化这个目的新 API 的价值不是多一条路径而是替代一条路径。反过来看当上述条件不满足时有外部依赖、无法协调、新 API 只是叠加而非替代保留旧路径可能才是合理选择——但这属于例外情形需要显式论证而不是默认做法。为什么不保留兼容层双路径复杂性的代价原文档用一句话点明了动机同时保留新旧 API 会产生双路径复杂性拖慢清理工作让代码库感觉像是只增不改append-only。append-only这个表述非常精准如果一个代码库只允许新增、不允许删除每次演进都在旧结构之上叠加新结构最终会积累出两套甚至多套并行实现调用方各自为政修复一个问题要在多条路径上重复。双路径复杂性的具体代价包括认知负担翻倍阅读代码时无法确定某条路径是当前事实还是遗留物每个调用点都要额外判断走的是哪条路修复成本翻倍一个 bug 修复若只覆盖新路径旧路径的调用者依然带着缺陷运行清理成本随时间上升旧调用者越多未来删除时的迁移面越大拖延只会让账越欠越多。这条动机与 pstack 的 principle-laziness-protocol 一脉相承——偏好删除、追求最小改动解决当前问题——也与 principle-outcome-oriented-execution 相互印证后者明确要求收敛到目标架构而不是保留带一次性兼容代码的平滑中间态并指出为保持每个中间步骤完全稳定而写的临时兼容代码常常变成长期债务。执行流程四步同波迁移将原文档的规则展开为可操作的执行步骤完整流程如下第 1 步清点调用者Inventory。找出旧 API 的全部调用点。这一步必须基于真实的代码检索结果而不是记忆或直觉——从源码结构看pstack 本身大量使用正则与文件扫描工具来定位引用清点结果应当覆盖源码、字符串、文档注释与反向引用等所有出现形式避免遗漏。第 2 步迁移调用者Migrate。将所有调用点切换到新 API。这一步建议按 principle-sequence-verifiable-units 的方式组织把迁移拆成已知良好状态 → 一个改动 → 运行检查 → 继续的小步括号每个调用点迁移后立即验证而不是批量改完再统一验证。该原则文档明确说明迁移属于典型的多步相似编辑场景按单元验证可以把出错的步骤定位成本降到最低。第 3 步删除旧 APIDelete。在同一波次内删除旧 API 定义不保留任何暂时留着以防万一的路径。删除与迁移之间不允许出现中间态窗口——这正是同一波次的含义。第 4 步处置测试Update/Delete tests。更新测试使其断言新契约删除只保护旧实现细节的测试。这一点与 principle-test-behavior-not-implementation 直接衔接该原则要求测试识别相关缺陷并断言要求的结果或可观察效果而不是断言某个替代品被调用了迁移后仍断言旧实现痕迹的测试恰恰属于保护重构前实现细节的类别应当删除。在 pstack 中的落地位置refactoring playbook这条原则不是孤立文档它被实际编排进了 pstack 的重构流程。在 refactoring playbook 的第 5 步中明确写道对于 API 重塑在同一个波次中迁移每个调用者并删除旧 APIprinciple-migrate-callers-then-delete-legacy-apis。不要兼容垫片不要新旧并行的路径。同一小节还给出了两条配套约束共同构成完整的执行语境行为保持不变playbook 开篇强调你拥有契约。结构改变行为不变——迁移是行为保持型重构若迁移过程中发现缺失功能或真实 bug应拆分为独立变更先交付结构变更机械编辑交给子代理playbook 建议把机械性编辑委托给配置了重构模型的子代理并给出明确范围文件路径、被移动的名称、需保持的行为避免重命名静默遗漏字符串、文档中的用法。从整体流程看该原则在 playbook 中处于先钉住契约 → 命名缺失结构 → 命名目标形态 → 先减法 → 同波迁移 → 在真实产物上证明 → 确认价值 → 整理提交链条的第 5 环与前后环节principle-subtract-before-you-add 的先删死代码再建新结构、principle-prove-it-works 的在真实产物上验证形成完整闭环。该原则如何驱动技能系统本身值得注意的一点是pstack 技能栈本身就是这套原则的实践样本。从仓库结构看plugins/pstack/skills/下的每一个原则都是独立的SKILL.md叶子文档如 principle-outcome-oriented-execution、principle-sequence-verifiable-units而 poteto-mode 只保留一份指向叶子文档的索引对于你应用的任何原则请完整阅读其叶子技能而不是把全部原则正文复制到主文档——这本身就是单一事实来源、不留冗余路径的体现。技能文件的加载机制同样遵循不留双路径的纪律plugins/pstack/pi/path-skills.ts展示了 Pi 运行时如何通过paths:glob 匹配让技能在触及匹配文件时自动提示加载而 Claude Code 则有对应的原生机制每个运行时只走自己的一条加载路径不存在需要同时维护的多套兼容逻辑。技能本身由 tools/validate-skills.mjs 统一校验frontmatter、链接、引用完整性保证文档体系可被机器验证——删除或迁移任何技能文件都必须同步更新引用这正是迁移调用者、删除旧 API在文档层面的镜像。实践判断清单将全文收敛为一份可直接对照的执行清单先确认适用性无外部兼容依赖项目可承受协调变更新 API 服务于简化/重构三者全满足才进入同波迁移任一不满足先停下来显式论证。清点要彻底调用者清单覆盖源码调用、字符串引用、文档提及、反向引用清点结果本身就是迁移的验收基准。迁移按小步验证每个调用点迁移后立即检查不批量推进旧调用者清零是删除旧 API 的前置门槛。删除不留窗口删除与迁移在同一波次完成临时适配器必须带到期时间并进入清理队列。测试跟随契约断言新契约的行为与结果删除仅保护旧实现细节的测试迁移后跑完整验证确认无回归。警惕只增不改如果本次改动在代码库中留下的净效果是多了一条路径这个改动就没有完成——它只是把债务推迟了。项目将这一原则以机器可读的技能文档形式固化frontmatter 中name与description字段用于运行时匹配user-invocable: false表示它由 poteto-mode 路由触发而非用户直接调用任何 Agent 在引入新内部 API 时都能被这条规则约束要么同一波次完成迁移与删除要么显式说明例外并承担双路径复杂性的成本。赞分享人工智能AI 技能AI 插件开发工具【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址https://gitcode.com/GitHub_Trending/ps/pstack-claude点击查看免费下载相关推荐Open-Falcon Dashboard Screen 删除接口实战DELETE /api/v1/dashboard/screen/:screen_id 原理与调用指南Open Falcon Dashboard Screen 删除接口实战DELETE /api/v1/dashboard/screen/:screen_id 原运维观测指标监控告警Realm Swift SDK 数据删除完全指南delete、deleteAll 与级联删除的实战与底层原理Realm Swift SDK 数据删除完全指南delete、deleteAll 与级联删除的实战与底层原理 本文是 Realm Swift SDK 官方 C数据库移动开发嵌入式数据库falcon-plus NoData 删除接口实战通过 DELETE /api/v1/nodata/:nid 移除 mockcfg 配置falcon plus NoData 删除接口实战通过 DELETE /api/v1/nodata/:nid 移除 mockcfg 配置 Open Falco运维观测指标监控告警上一篇visx/pattern纹理填充为图表元素添加丰富视觉效果的技巧下一篇TradingAgents-CN终极指南三步打造AI智能投资分析平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考