SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场custom-plugin-refresh

custom-plugin-refresh

部署与运维

查看项目

更新于 10-15 13:50

技能介绍

用途

custom-plugin-refresh 是一套维护协议，用于那些“手写插件”——即不在 upstream-sync 技能同步表中的插件。这类插件内容由人工编写或基于调研，没有可重新拉取的上游源，因此不会像 vendored 插件那样通过 diff 发现变化，版本号、框架建议、破坏性变更说明以及“截至 2026 年”之类的表述会静默过期。该技能提供了一套对抗这种衰减的刷新流程。

刷新对象是 plugins/<name>/ 下手写的内核部分：plugin.toml、roles/、带 TOML sidecar 的 workflows/、skills/、contracts/ 和 policies/。宿主机制位于 adapters/ 下。导出产物与根 marketplace 目录是生成物，应修正其来源并重建，而不是直接编辑包副本。

主要能力：新鲜度风险分级

该协议要求把每个插件归入四类之一，类别决定刷新周期与优先级：

  • 极快（Very fast）：版本每隔几个月就升级，破坏性变更常见，生态频繁重组，建议每 3 个月刷新。示例包括 rag-development、digital-marketing/ga4-implementation、react-development。
  • 快（Fast）：框架每年发布 2-3 次，API 持续演进，建议每 6 个月刷新。示例包括 libgdx-development、opentelemetry、tauri-development、stripe、grabber-development、browser-extensions、pwa-expert、text-humanizer。
  • 中等（Moderate）：大约每年一次大版本，破坏性变更较少，建议每 12 个月刷新。示例包括 trading-broker-integration、csp（OR-Tools）、python-development、typescript-development、messaging（RabbitMQ 大版本）、obsidian-development、abstraction-architect。
  • 慢（Slow）：属于因行为改变而非版本升级而过期的流程知识，采取机会式审查，仅在出现症状时复查。示例包括 project-lifecycle、project-protocol、senior-review、project-knowledge、团队流水线工作流、marketplace-ops、system-utils、learning、research、business、clean-code、codebase-xray、platform-engineering、testing methodology、xterm、app-analyzer。

若不确定，默认归为“快”（6 个月）；首次刷新后根据实际变化量再重新分类。

ai-tooling 被描述为例外：其工作流内容属“慢”，但 agent-sdk-builder 记录的 SDK 在小版本之间就会产生破坏性变更，因此该技能属“极快”（每 3 个月）。文档提到 2026-08-10 的一次事实核查一次发现五处 API 漂移：fork_session 类型改变、plugins 从路径变为配置对象、thinking 变为仅对象形态、TypeScript V2 预览被完全移除、迁移指南中的 settings-source 默认值已被取代。自 ai-tooling 5.2.0 起，同样的快速节奏也适用于 prompt-engineering 技能的 references/model-guidance.md 以及其 SKILL.md 中的模型类别表，因为它们引用了厂商页面内容。

对版本敏感内容：刷新策略而非仅刷新事实

仅修正当下事实的刷新会给下一位读者留下同样的陷阱。当插件记录快速变化的外部 API 时，更持久的做法是给出“事实来源策略”加上对自身声明的分类，让内容明确告诉 agent 哪些陈述不可轻信。文档以 ai-tooling 5.0.0 为范例：一个决策核心承载优先级层级（项目已安装的 SDK、当前官方文档、捆绑参考），易变细节移入按需参考文件，并配有一张 STABLE / API-SENSITIVE / MODEL-SENSITIVE 表。

两个可复用的机制：

  • 标记无法确认的内容。刷新中无法通过文档解析确认的声明属于“未确认”，而非“确认不存在”。应就地标记为 (verify)，而不是删除或让它看起来像已验证；该标记同时也是下一次刷新的待办队列。
  • 优先使用相对路径与替代路径而非仓库路径。${CLAUDE_PLUGIN_ROOT}/... 和技能相对的 references/... 在安装后仍然有效；plugins/<name>/... 只在本仓库 checkout 中可解析。python scripts/lint_bundled_paths.py 会针对随附资源强制执行这一点；其 bundled-path 基线为空。跨插件消费者应加载所有者命名的技能，而不是直接访问其文件。

若刷新产生了值得保留的行为不变量（例如“前沿从不自动选取”“已安装 SDK 优先级高于捆绑参考”），应把用例加入该插件 evals/ 下的测试装置，模板是 evals/ai-tooling/。

硬编码版本通常藏在哪

按优先级排列的常见位置：

  • Agent 正文——"Core Knowledge" / "Library Landscape" 章节列出包名与版本
  • SKILL.md——"Quick Start" 步骤中的安装命令带版本号
  • 参考文件——changelog / breaking-changes 章节、基准数字、"as of YYYY" 行
  • 审计命令——引用特定版本门槛功能的检查清单
  • plugin.toml 描述——如果描述中直接点名版本（如 "RabbitMQ 4.x coverage"）；目录会从该声明派生

其中按每分钟刷新工作量的价值看，Agent 正文与 SKILL.md 是最高价值目标。参考文件对普通用户影响较小（渐进式披露），但对高级用户最重要。

更新协议

无论风险等级，刷新步骤相同，只有周期不同：

  1. 用 research:deep-researcher 重新调研该领域，至少优先使用一手与最新来源。文档给出了填充后的提示词模板，要求调研框架当前版本、自插件内版本以来的破坏性变更、推荐依赖基线版本、弃用项、生态变化，关注会改变现有知识库建议的事实；来源族为官方/一手文档与 changelog、最新来源（发行说明、迁移指南）；预算为 15 次搜索 / 12 个页面 / 4 轮；返回格式为研究者报告。可选：若覆盖真实使用模式，可在来源族中加入社区来源。
  2. 将调研发现与插件进行 diff。派 Explore agent 在插件中 grep 调研中出现的具体版本字符串与章节标题，逐项判断：明确的更新（过期事实且有确认的替代，直接编辑）；微妙的偏移（框架改了默认值但旧方法仍可用，两者都提）；无变化（调研确认内容仍准确）；开放问题（调研不确定，留注释下轮再看）。只做外科手术式编辑，不重写整个文件，替换具体行句，保持结构以便未来刷新有稳定锚点。
  3. 递增版本。在变更内核的 plugin.toml 中递增版本：事实更新用 patch（1.2.3 -> 1.2.4），新增章节、文件或参考用 minor（1.2.3 -> 1.3.0）。同时递增 .claude-plugin/marketplace.json 中的 metadata.version（除非 marketplace 形态本身变了，否则 patch 即可）。该 metadata 字段是编译器的版本输入，目录条目仍为生成物。内核变更后，用 python scripts/daodan_build.py 重建所有宿主，并用 python scripts/sync_plugin_docs.py 重新生成组件/依赖参考。发布前运行 python scripts/daodan_build.py --check、python scripts/sync_plugin_docs.py --check 以及所需仓库门禁。
  4. 提交证据，而不仅是结论。一次刷新在 docs/superpowers/specs/ 下与其设计记录并列、以同一日期命名提交三个文件：实际运行的研究提示词、研究者报告的逐字记录、以及逐来源验证文件，说明哪些来源对照其主要页面核查过、哪些被更正、哪些完全未验证。每个文件携带正文的 sha256。

文档强调这是保留规则而非礼节，因为刷新的设计记录无法承载这些信息：记录只用一行说明来源已验证，只有逐来源文件才能告诉后来者其中五个未验证，且其中一个仍在已发布正文中带有声明。研究运行自身的输出目录不算数：.peer-review/ 和 scratchpad 都在 git 之外，新 clone 两者都没有。验证失败的来源在引用处标记 (verify)，验证文件则让读者知道该标记不是装饰。

  1. 用刷新标签提交，格式为：Refresh <plugin-name> for <framework> v<new-version> (v<plugin-version>)。把变更的内核、证据以及所有重新生成的导出/目录与文档参考一起提交。如果仓库工作流技能有变化，用 python scripts/sync_codex_instructions.py 重新生成其原生 Codex 适配，并用 --check 校验一致性。这样 git 日志就成为“哪些插件何时被关注”的可检索记录，可用来决定接下来刷新什么：任何在一个完整风险等级周期内未被触及的都算逾期。

按需分诊

当开始一轮刷新却不知从何入手时，文档给出命令：用 git log --since="6 months ago" --name-only --pretty=format: -- plugins/ 结合 grep/awk/sort 列出近期被触及的插件，再与 plugins/*/plugin.toml（权威内核清单）比较，差集即为待办队列。若队列中有“极快”和“快”类别则优先刷新；“中等”和“慢”类别除非有具体触发原因，否则推迟。

何时把自定义插件升级为上游同步

若在刷新过程中发现他人开源仓库现已发布与某个自定义插件显著重叠的内容，应评估改为 vendoring 而非从零维护。遵循 external-repo-intake 技能，然后把该插件的行加入 upstream-sync 技能中的同步表。

限制

资料未提供该技能的安装方式、依赖环境、适用平台或收费信息。