为 Server Actions 项目生成后端规则：agents-generator 的 server-actions 模板深度解析

为 Server Actions 项目生成后端规则agents-generator 的 server-actions 模板深度解析【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本文围绕仓库中 agents-generator 技能的 server-actions 模板系统讲解如何为采用 Server Actions或 API Routes、NestJS的项目生成项目专属的.agents/rules/server-actions.md规则文件。读完本文你将掌握该模板的五大核心小节入口点、请求流程、响应类型、错误处理、速率限制的填充规则理解它在完整检测流程中的触发条件并学会对照质量基准产出零占位符、可执行、与真实代码一一对应的后端规则。模板在整个技能中的定位agents-generator技能见 SKILL.md的目标是通过分析目标代码库生成一份与真实工具链完全匹配的AGENTS.md及配套的.agents/rules/*.md规则文件而不是输出带占位符的通用模板。在技能的资源引用表中server-actions.md属于Full 模式的必备规则模板之一其用途被明确描述为 Server actions / backend template优先级文件用途Requiredassets/agents-full.md完整 AGENTS.md 模板25 小节及填充规则Requiredassets/agents-minimal.md30 行精简 AGENTS.md 模板Full modeassets/server-actions.mdServer actions / backend 规则模板Full modeassets/backend.mdBackend/NestJS 模板技能在 What you get 一节中给出了直观示例对于 Bun Next.js 16 Tailwind Vitest Server Actions 的项目生成的.agents/rules/server-actions.md应包含 downloadVideo()flow,DownloadResulttype, rate limiter——即模板中的三大核心内容。触发条件什么时候生成 server-actions.md模板本身并不包含何时启用的逻辑这一判断由 decision-matrix.md 完成。其中第 15 节 Backend pattern 定义了五种后端模式的检测信号信号模式文件中包含use serverServer Actionsapp/api/下存在route.tsNext.js API RoutesNestJS controllersNestJS RESTExpress/Fastify 路由文件REST APItRPC routerstRPC API随后在 Rule File Selection 表中server-actions.md的启用条件是Uses server actionsORhas API routesORhas NestJS/Express/Fastify backend也就是说只要目标项目存在上述三种信号之一就需要基于本模板生成规则文件。反之纯前端项目无任何后端信号则跳过该文件——这符合技能 Generate only what applies 的硬性规则SKILL.md Hard Rules 第 3 条。需要特别区分的是server-actions.md与backend.md的职责边界server-actions.md覆盖 Server Actions、API Routes 以及一般 REST 后端backend.md仅在依赖中检测到nestjs/core时才启用专讲 NestJS 的模块化架构见 backend.md 的 Generation RulesThis template is only used whennestjs/coreis detected in dependencies。模板五大小节解析server-actions.md由五个占位小节构成下面逐一拆解其填充规则。1. Entry Point入口点该小节回答请求从哪里进来要求按后端形态分别描述Server Actions列出包含use server指令的主文件、导出的函数、函数参数API Routes列出app/api/下的文件、HTTP 方法、参数NestJS列出主要的 controllers、guards、DTOs。填充时应参考 template-filling-guide.md 中{{DATA_FLOW}}的真实函数名原则——不要写 validate input 这类抽象描述而要写出项目里真实存在的函数名例如downloadVideo(url)并标注其所在文件路径。2. Flow请求流程要求以编号步骤描述一次典型请求的完整链路并明确了默认顺序validation → rate limit → logic → response这四步构成 Server Actions 后端的标准处理管线先做输入校验再经过速率限制然后执行核心业务逻辑最后返回响应。填充时需结合项目的真实调用链。仓库提供的质量基准 example-output/README.md 给出了一个可复制的范例detectPlatform()→downloadVideo()→downloadFromUrl()→ttdl()/igdl()/fbdown()/twitter()它强调Not validation → API call → database. 即流程步骤必须使用真实函数名允许在步骤之间用 ASCII 箭头串联展示从用户动作、前端、服务端 action、外部库直到响应与 UI 更新的完整链条。3. Response Type响应类型模板要求输出响应类型的名称与定义标题本身也是一个占位符RESPONSE_TYPE_TITLE填写主响应类型名例如DownloadResult、ApiResponse或项目实际使用的响应类型名RESPONSE_TYPE给出该类型的 interface/type 定义并为可选字段与必填字段添加注释。以示例项目为例即应在规则文件中给出DownloadResult的完整类型定义逐字段标注required/optional及含义让后续 Agent 在不读源码的情况下也能正确构造和解析响应。4. Error Handling错误处理错误处理是模板中规则最细的一节按项目实际情况从三个维度记录如果存在ErrorCode枚举完整列出所有错误码及其含义如果存在GlobalExceptionFilter记录该全局过滤器说明它如何统一捕获未处理异常如果存在detectErrorCode之类的函数记录其启发式判定逻辑——即如何从异常对象/状态码推断出错误码。这与 backend.mdNestJS 场景中的错误处理要求相互印证全局异常过滤器捕获所有未处理异常、处理数据库错误唯一约束、记录不存在、外键、关系违例、业务错误使用类型化 code 一致消息、500的错误自动记录堆栈。两份模板共同强调错误必须是结构化的、可被解析的而不是裸错误字符串。5. Rate Limiting速率限制仅当项目存在rate-limit.ts或相应中间件时填写要求记录三要素机制mechanism如何实现限流——例如基于内存计数、滑动窗口还是外部存储限制limits具体的速率阈值如每 IP 每分钟 N 次请求过期expiry限流窗口或键的过期时间。同源模板 architecture.md 的RATE_LIMIT_SECTION占位符也要求If rate-limit.ts or rate limiting middleware exists, document it with limits and expiry. 说明速率限制信息在架构规则与 server-actions 规则中都会出现两者应保持一致。占位符填充的通用规范server-actions.md末尾的 Generation Rules 是对上述五小节的填充规则汇总。它与技能整体禁止占位符的硬性要求SKILL.md Hard RulesNo placeholders. Scan output for{{,TODO,add here,.... Reject if any remain.完全一致——模板中的{{PLACEHOLDER}}只是生成阶段的输入最终产出的.agents/rules/server-actions.md必须全部替换为真实项目数据。填充时还应遵守 template-filling-guide.md 的两条核心原则具体性输出要与 example-output 同等具体必须能从配置文件验证而不是通用建议例如 ❌ Usar buenas prácticas de TypeScript. 这类不可验证的写法应被拒绝真实性命令必须来自package.jsonscripts、类型必须来自真实源码、调用链必须来自真实导入关系。完整生成流程中的位置在 Full 模式下见 SKILL.md Execution Stepsgit rev-parse --show-toplevel定位项目根依据 lockfile 检测包管理器bun.lock→bun、pnpm-lock.yaml→pnpm、package-lock.json→npm、yarn.lock→yarn绝不默认 npm读取package.jsonscripts、deps、workspaces读取非机密配置文件、探索目录结构排除.env*读取assets/agents-full.md并用真实数据填充全部占位符对于每个适用的规则类别读取对应assets/模板并生成.agents/rules/文件——server-actions.md即在此步被读取和填充若检测到 Claude.claude/或CLAUDE.md则生成薄版CLAUDE.md。生成后还需执行扫描{{/TODO/...并修复、验证所有命令存在于package.jsonscripts、AGENTS.md 超过 300 行时警告、超过 500 行时强制迁移内容到规则文件、以 conventional commit 格式总结变更并报告检测摘要、生成/跳过清单与置信度评分。质量基准如何判断 server-actions 规则合格example-output/README.md 定义了 8 项质量检查其中与 server-actions 直接相关的是命令精确写bun dev而不是npm run dev依据 lockfile 与 scripts 决定{pm}前缀调用链真实数据流使用detectPlatform()→downloadVideo()→downloadFromUrl()→ttdl()/igdl()/fbdown()/twitter()这类真实函数名类型与限流具体DownloadResult类型、rate limiter 的 limits 与 expiry 必须来自真实源码零占位符搜索{{、TODO、add here、...应为零命中。同时注意技能的局限声明SKILL.md Limitations生成的规则只是提案需要人工审查后才能采纳或提交命令验证只覆盖目标项目可见的 scripts 与文件无法证明所有工具在任意环境可用项目提供的 package scripts 属于不可信可执行代码生成和文档化脚本不等于授权运行。实战要点小结触发条件检测到use server文件、app/api/route.ts、或 NestJS/Express/Fastify 后端信号时生成server-actions.md纯前端项目跳过。五要素齐全入口点、请求流程validation → rate limit → logic → response、响应类型含可选/必填注释、错误处理ErrorCode / GlobalExceptionFilter / detectErrorCode 启发式、速率限制机制、limits、expiry。与真实代码一一对应所有函数名、类型名、命令、错误码都来自目标项目源码与配置禁止通用模板文本。与相邻规则保持一致architecture.md中的RATE_LIMIT_SECTION、backend.mdNestJS 专属的错误处理规范应与 server-actions 规则交叉一致。通过这套模板与配套检测逻辑agents-generator让生成的 Server Actions 后端规则不再是泛泛的工程建议而是可以直接指导 Agent 调用入口函数、解析响应类型、识别错误码并遵守限流约束的项目级操作手册。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考