建议建议如何被塑造、编写、清理和分级。目录模式编写规则12 个清理器信封解包恢复分级标准Next.js 版本感知模式每条建议是一个匹配此 TypeScript 结构的 JSON 对象interfaceRecommendation{// 面向客户what:string;// 1 行以影响开头。可行时最多 80 字符。why:string;// 1-2 句。根因。引用代码库发现 计数。fix:string;// 分步。包含前/后代码块。足够具体以实现。bucket:cost|performance|reliability;effort:low|medium|high;affectedFiles:string[];// 已验证的文件路径来自 candidate.filescurrentBehavior:string;// 代码现在的行为带片段desiredBehavior:string;// 目标状态带片段risk?:string;// 可选例如移除 force-dynamic 可能向 /admin 提供陈旧数据verify:string;// 如何确认修复有效。例如重新运行 vercel metrics … 并观察 p95// 影响在第 4 步由 impact-magnitude.mjs 计算impactLabel:{performance?:string;// 精确将 /api/products p95 从 850ms 降低到约 250-400mscostMagnitude?:negligible|small|medium|large|very-large;costPhrase?:string;// 按当前流量每月数百美元billingDimension?:string;fractionReduced?:number;};impactTier:high|medium|low;billingDimension?:edge-requests|function-duration|image-optimization|isr-reads|isr-writes|bandwidth|data-cache-reads|cron-invocations|string;// 接地citations:string[];// 来自 references/docs-library.json 白名单。必需≥1 条。candidateRef?:string;// 此建议追溯到的门控候选例如 uncached_route:/api/productsfindingRefs?:string[];// 来自 verifiedFindings.json 的 文件:行 标记appliesAlsoTo?:Array{// 当匹配的建议折叠为一个面向客户条目时由去重添加。candidateRef?:string;affectedFiles?:string[];o11ySignal?:string;what?:string;};corroborationCount?:number;// 折叠到此条目的匹配已验证建议数包括自身。// 验证器输出在第 3.6 步计算verification?:{passRate:number;failed:Array{type:string;text:string;reason:string};};// 清理器审计跟踪在第 3.4 步计算sanitizerTrail?:string[];// [$-strip:2, version-mismatch:next15:1, ...]needsReview?:boolean;// 当清理器捕获到危险时设置// 分级第 3.5 步quality:{specificity:number;// 0-1actionability:number;grounding:number;evidence:number;overall:number;grade:Excellent|Good|Fair|Poor;};}编写规则推荐器提示词明确告诉代理遵循这些规则。清理器在生成后强制执行它们。语音和语调由references/voice.md管理。在撰写建议散文之前阅读它它让报告直接、指标接地、不含内部流程术语。以影响开头what字段以动词 变更开头而不是框架。比较❌ “考虑在 /api/products 路由上启用缓存”实质之前的填充词✅ “为 /api/products 添加带 s-maxage 的 Cache-Control”动词优先范围明确引用带行号的代码库发现why必须引用来自verifiedFindings.json的已验证发现❌ “该路由未缓存”可适用于任何地方✅ “src/app/api/products/route.ts:22 返回不带 Cache-Control 的 Response可观测性显示 1.2M 次调用/月 0% 缓存命中”客户字段中无 $ 字面量用户强制的规则。what/why/fix/impact/currentBehavior/desiredBehavior不得包含$N货币字面量。使用来自impact-magnitude.mjs的量级框架。❌ “通过添加 s-maxage 每月节省 $340”✅ “按当前流量每月数百美元”✅ 精确性能“将每月 1.2M 次调用移至 CDN预期缓存命中的 p95 从 850ms 降到约 50ms”$-strip清理器在输出时强制执行这一点但提示词也应指示 LLM 首先不要发出美元字面量。需要前/后代码块currentBehavior显示有问题的片段。desiredBehavior显示目标。语言标签的代码块。两者都保持在约 20 行以内。引用库中的至少一个 URLcitations[]必须包含至少一条来自references/docs-library.json的条目。missing-citation清理器丢弃未引用的建议。unknown-citation和version-mismatch清理器剔除无效引用。匹配用户的框架版本不要向 Next.js 13 用户推荐use cacheNext 15。推荐器提示词只接收对用户技术栈有效的引用子集——但 LLM 仍然可能虚构。version-mismatch清理器捕获漏网者。12 个清理器每个清理器在变更字段时将其操作记录在rec.sanitizerTrail中。标签格式tag:detail。标签在词法上稳定——下游消费者 grep 它们。#清理器触发操作跟踪标签1$-strip客户字段中的货币字面量正则替换为计费成本$-strip:N2vercel-directive-stripcache-control 中的stale-if-error/proxy-revalidate剔除指令Vercel CDN 不遵守vercel-directive-strip:directive3rate-limit并发 × 延迟 已知提供商速率限制前置注意事项设置 needsReviewrate-limit:provider:prescribed/limit4pre-release修复启用-rc/-beta/-canary功能追加需要预发布版本注意事项pre-release:pkgversion5middleware-conflict建议目标路由被中间件匹配器覆盖追加中间件 {matcher} 可能拦截注意事项middleware-conflict:matcher6undeclared-dep修复导入 package.json 中没有的包前置先添加依赖npm i {pkg}undeclared-dep:pkg7count-correct引用计数 验证计数基准真值已知重写为带验证计数的约 Ncount-correct:token:cited→actual8count-strip引用计数 验证计数无基准真值重写为若干count-strip:token9rendering-mode-mislabel建议将静态页面的问题归咎于 ISR/SSR追加警告设置 needsReviewrendering-mode-mislabel10unknown-citationURL 不在references/docs-library.json中剔除 URL全部剔除时设置 needsReviewunknown-citation:url11version-mismatchURL 的applicableFrameworks与技术栈不匹配剔除 URL全部剔除时设置 needsReviewversion-mismatch:url12missing-citation其它清理器之后citations.length 0完全丢弃建议不发出建议末尾计数清理器顺序很重要先运行美元剔除便宜、确定性然后是内容清理器最后是引用清理器。这保证引用计数是针对最终状态计算的。recordSanitizer(rec, tag)辅助函数是唯一入口点——清理器必须在变更字段之前调用它。否则审计跟踪会腐烂。提供商速率限制由清理器 #3 使用。这些提供商限制是公开的契约值提供商限制文档 URLNotion3 rpshttps://developers.notion.com/reference/request-limitsOpenAI30 rpshttps://platform.openai.com/docs/guides/rate-limitsStripe100 rpshttps://docs.stripe.com/rate-limitsAnthropic10 rpshttps://docs.anthropic.com/en/api/rate-limits档位/计划不同这些是第一档默认值。如果建议规定了更高的并发清理器会前置注意事项。信封解包恢复不是清理器——是一个恢复步骤。LLM 偶尔将 JSON 输出包裹在信封中{data:{recommendations:[...]}}{result:{recommendations:[...]}}{insights:{recommendations:[...]}}attemptManualRecovery在模式验证之前剥去一层包裹。递增hygieneCounters.envelopeUnwraps。将解包记录到运行日志。这是技能所做的唯一创造性解析。任何其它未通过模式验证的内容都会被拒绝。分级标准每条建议在四个轴线上评分每个 0-1。平均 → 等级轴线衡量什么强1.0信号具体性具体文件、行号、代码片段三反引号代码块或内联代码 ≥10 字符 已验证文件路径可执行性清晰的先做这个再做那个步骤编号步骤每步有动词无考虑/“也许”接地性声明追溯到发现或指标数据sourceIndex匹配发现或建议有 affectedFiles 代码块推定证据证据数字、观测的声明计数字错误、查询、调用 单位% / ms / s / K / M等级阈值Excellent≥ 0.85Good0.70 – 0.85Fair0.55 – 0.70Poor 0.55 → 在第 4 步的质量底线被丢弃Next.js 版本感知推荐器的引用库由signals.json.stack.frameworkframeworkVersion过滤。代理在选择推荐哪些 API 时仍应自查版本功能可用说明App RouterNext ≥ 13.0自 14 起为默认generateStaticParamsNext ≥ 13.0为 App Router 取代 getStaticPathsFetchnext: { revalidate }Next ≥ 13.0注意默认 fetch 缓存语义在 Next 15 中翻转unstable_cacheNext 14-15在 16 中被 ‘use cache’ 取代use cache指令Next ≥ 15.0持久缓存原语cacheLife()、cacheTag()Next ≥ 15.0与 ‘use cache’ 配合after()Next ≥ 15.0非阻塞响应后工作Partial PrerenderingNext ≥ 15.0稍后稳定为目标——按版本验证revalidateTag/revalidatePathNext ≥ 13.4基于标签的按需失效cookies()/headers()异步Next ≥ 15.015 中的异步模式技能精选的引用库通过applicableFrameworks编码这些约束。如果贡献者添加新的 Next.js 功能 URL他们必须在references/docs-library.json中设置正确的 semver 范围。