agents-generator 占位符填充全解：让 AGENTS.md 输出可验证的真实项目规则

agents-generator 占位符填充全解让 AGENTS.md 输出可验证的真实项目规则【免费下载链接】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,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skillsagents-generator 是 AAS 仓库中负责 AGENTS.md 模板生成的项目上下文工具。它不套模板而是先读懂目标代码库再把真实证据逐个填进assets/*.md的占位符产出可验证、零占位文本的AGENTS.md与.agents/rules/规则文件。问题在于怎么保证填进去的每个词都能被源码再次核验这正是这套占位符填充机制要回答的事也是接下来全部内容的主线。空洞模板才是最大的陷阱生成器最容易踩的坑不是少生成内容而是生成一堆看起来专业的空话。想象你打开一份AGENTS.md里面是这样的用Component表示组件用Service封装后端逻辑先validate input再call API这些词每个都对但每个都没用。Agent 读完判断不了这个项目用哪个包管理器测试跑哪条命令哪个目录是入口——因为它全是泛化词汇和任何一个 React 项目都能对上。说白了这种文档对 AI 的决策价值为零还不如没有。关键就在这里。template-filling-guide.md存在就是为了堵死这条路写进输出的每一个事实都必须能在目标项目里被再次验证——要么来自package.json、锁文件、配置要么来自目录结构、源码符号或 git 历史。填不进真实证据的就一个字都不要写。信号驱动检测信号如何决定生成什么检测器读入依赖清单、锁文件和目录结构后会得到一组信号。信号不直接产出文字而是先做一件更关键的事——决定该生成哪些规则文件。这套路由逻辑完整定义在 decision-matrix.md 里下面是速查版检测信号触发的规则 / 约定package.json存在workspacesMonorepo → 包依赖规则、共享包重建命令存在turbo.json/nx.json/lerna.jsonMonorepo 工具 → 适配turbo run/nx/lerna rundeps 含next且有app/或pages/Next.js 路由 → App Router服务端组件或 Pages Routerdeps 含nestjs/coreNestJS → 模块架构、guards、DTOdeps 含trpc/*tRPC → 与 REST 完全不同的后端规则deps 含react-hook-form/formik表单库 → 生成forms.mddeps 含next-intl/react-i18nexti18n → 生成i18n.mddeps 含prisma/drizzle-ormORM → 生成database.mddeps 含styled-components或存在.module.css非 Tailwind 的 CSS → 规则不同的styling.mddeps 含next-auth/clerk/nextjs/luciaAuth → 路由保护规则deps 含tanstack/react-query/swr服务端状态 → 与 Zustand / Redux 不同的状态规则devDeps 含vitest/jest/playwright测试运行器 → 命令正确的testing.md无 TypeScriptJS 项目 → 跳过tsc采用不同的类型安全规则约束只有一条且是硬性的只生成实际适用的规则文件不适用即省略。architecture.md、git-workflow.md、sdd-workflow.md三个总是生成其余全看信号——前端框架不存在就不生成frontend-patterns.md没检测到 Tailwind / CSS Modules / styled-components就不生成styling.md纯 CSS 不算没有 Prisma / Drizzle / Knex / TypeORM / Mongoose就不生成database.mddevDeps 里没有测试运行器就不生成testing.md既没有use server文件也没有 API 路由或 NestJS / Express / Fastify 后端就不生成server-actions.md。前端纯项目不得带出后端规则无 ORM 的项目不得带出数据库规则。这不是建议是底线。生成器宁可少一个文件也不输出空壳小节。占位符填充契约九个占位符的具体性规则九大占位符不是一条条平铺的清单而是按功能分成四组。每一组的共同目标只有一个让填进去的东西可被核验。版本溯源依赖清单精确到版本号{{STACK_TABLE}}落在 architecture.md 模板的 ## Stack 小节列头固定为 层 / 技术 / 版本Layer / Technology / Version。它的规矩很死每一行必须给出package.json里的精确版本号永远不许写latest或X.Y.Z。覆盖范围固定为 framework、UI、runtime、ORM、validation、testing、linting、analytics、fonts 九层。版本号从package.json与配置文件提取——这正是 SKILL.md 硬性规则里读取 deps/devDeps 并保存 scripts那一步的产物。质量基准给出的范例长这样Vitest 4.x、ESLint 10 react-doctor 0.9.3。每一个都能溯源没有一个含糊。结构映射用真实名字画出可核验的结构三个占位符共同负责一件事——让结构图能被项目成员对着源码逐一核对。{{ARCHITECTURE_DIAGRAM}}真实目录名的 ASCII 图。用项目里真实存在的目录名画图展示真实连接——哪个文件 import 哪个文件。禁止出现标着Component或Service的笼统框。Monorepo 画包依赖箭头单应用画app/ → components/ lib/ → 外部服务的链路。{{DATA_FLOW}}带真实函数名的数据流。用编号步骤写detectPlatform()而不是validate input写ttdl(url)而不是call API。完整链路是用户操作 → 前端 → 后端 / 服务端动作 → 外部库 / 数据库 → 响应 → UI 更新步骤间用 ASCII 箭头连接。server-actions.md 里REQUEST_FLOWvalidation → rate limit → logic → response与它一脉相承。数据流之所以要真实函数名是因为 Agent 后续要靠这些名字在源码里定位入口与边界。{{ROUTING_TABLE}}覆盖每一个路由文件。列出app/或pages/下发现的每一个路由文件每行包含路由路径、类型server / client / API、文件路径、一行用途描述描述用项目 UI 语言。检查清单包括page.tsx、layout.tsx、route.ts、error.tsx、loading.tsx、not-found.tsx、sitemap.ts、robots.ts、API 路由与动态路由。标题随框架走Next.js App Router 用 RoutesNestJS / Express 用 Endpoints。基准范例是detectPlatform() → downloadVideo() → downloadFromUrl() → ttdl()/igdl()/fbdown()/twitter()。对比反例 validation → API call → database——后者谁都能写前者只有真正读过代码才写得出来。命令与证据只输出真实脚本、测试数与 git 历史{{ESSENTIAL_COMMANDS}}不存在的脚本一律不写。只包含package.json中脚本键确实存在的命令格式{pm} run key或{pm} key与检测到的包管理器对齐bun 不带runnpm 用npm runpnpm / yarn 按惯例映射。脚本缺失就整行省略——绝不发明命令。核心行是 dev、build、lint、test、test:run、test:coverage加上存在时的 doctor / lint-staged。在 agents-full.md 里它渲染成 Command / Purpose / When 三列表多出何时运行决策列比如pnpm test:run— 单次测试 — 提交前跑。{{TEST_COUNT}}真实统计的测试数。统计所有测试文件里实际出现的test()/it()调用报告N tests和真实数字数不准就退而报告测试文件数N test files。同时报告运行器 版本、环境node / jsdom、覆盖率提供方与目标、是否严格 TDD 模式yes/no。testing.md 里TEST_RUNNER_INFO要精确到版本Vitest X.Y.Z。基准范例 74 tests5 个测试文件全在lib/是数出来的不是估出来的。{{COMMIT_EXAMPLES}}来自 git 历史的提交示例。给 2~3 个用项目近期 git 历史中真实文件名或功能名的示例有git log --oneline -5就读它。格式type: message每行一条。它嵌在 git-workflow.md 模板里该模板规定 Conventional Commits 类型feat:/fix:/refactor:/test:/chore:/docs:、一次提交只含一个逻辑变更、短祈使句、无句尾句号、禁止 Co-Authored-By 或 AI 署名并按项目语言COMMIT_LANGUAGE书写。{{VERIFICATION_CYCLE}}由已验证命令组装。按{typecheck} → {lint} → {test} → {doctor}拼装只包含工具确实存在的步骤用package.json里的确切命令格式。具体规则{typecheck}在 TypeScript 下是tsc --noEmitbun 项目为bunx tsc --noEmit无 TS 则跳过{lint}是{pm} run lint或检测到的 lint 命令{test}取test:run或test里单次运行的那个{doctor}仅在检测到 react-doctor 时加入。无测试运行器、无 lint、无 TypeScript 时分别跳过对应步骤。基准范例bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor每条命令都能在package.json里找到。约定表达可验证的项目专属约定{{GLOBAL_CONVENTIONS}}每条都得能从配置里验证。列 5~8 条项目专属约定方向涵盖包管理器、导入约定、命名、语言、校验方式。反面是通用建议。对比一下✅ Bun siempre. No npm ni yarn. 从 bun.lock 检测得出 ✅ Sin librería de validación externa — TypeScript types guards manuales. deps 里没有 zod ❌ Usar buenas prácticas de TypeScript. 泛化、无法验证 ❌ Código limpio y documentado. 泛化、无法验证{{CODE_STYLE}}同样要求仅使用可从配置验证的约定TypeScript strict、no any、单双引号、分号、导入约定、UI 语言。反例同样是- We use TypeScript不行- TypeScript strict mode才行。前者是废话后者才是一条能核验的规则。从检测到落盘七步流水线填充规则不是孤立存在的它嵌在SKILL.mdExecution Steps 定义的整体流程里。按执行顺序串起来是七步定位根目录git rev-parse --show-toplevel确定项目根后续所有路径以此为基准。先检测包管理器bun.lock→ bunpnpm-lock.yaml→ pnpmpackage-lock.json→ npmyarn.lock→ yarn。这一步排在最前且绝不默认 npm——它决定了后面每条命令的前缀。读取配置读package.json的 scripts、deps、workspaces把 scripts 存下来供命令校验。探查目录与配置读非机密配置文件、探查目录结构。排除所有.env*文件仅允许纯占位形式的.env.example环境变量名只能从.env.example的占位符与源码里的process.env.NAME引用推导。选择模式full / minimal / update / dry-run有歧义时问用户。填充与输出full 模式读agents-full.md和各规则模板逐项填占位符产出AGENTS.md包裹在!-- AGENTS-GENERATED-START --/!-- AGENTS-GENERATED-END --托管块之间与.agents/rules/*.md。后处理校验扫描{{、TODO、...并修正校验每条命令存在于 scriptsAGENTS.md超 300 行告警、超 500 行强制把内容迁到规则文件用 Conventional Commits 汇总变更报告检测、生成、跳过内容与置信度。这条流水线里埋着几个安全设计值得单独点出不读秘密值.env、.env.local、凭据存储一律不碰环境变量只取名字不取值。不执行项目脚本包管理器脚本是仓库可控的 shell 入口点生成器只检测并记录候选的 format / lint 命令默认不执行——除非用户单独授权且已审阅脚本体。生成即提案所有输出在用户批准前都只是提案不直接改写目标文件。先备份文件已存在时先拷到.agents/backups/并带时间戳。质量红线八条验收标准一票否决example-output/README.md 给出八条关键质量检查。它们不是建议是红线——任何一条没过这次生成就该重做命令精确写bun dev而不是npm run dev能从doctor: npx react-doctorlatest读出bun doctor。验证循环真实bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor每条命令都存在于package.json。约定匹配技术栈写 Sin librería de validación externa — TypeScript types guards manuales (isDownloadError())而不是凭空捏一个 Zod para validación。架构图具体ASCII 图展示真实目录app/、components/、lib/downloader/不是通用占位。数据流用真实函数名detectPlatform() → downloadVideo() → downloadFromUrl() → ttdl()/igdl()/fbdown()/twitter()不是 validation → API call → database。路由表完整每个路由文件都列出带类型client / server和项目 UI 语言的描述。测试数准确74 tests 是从实际测试文件数出来的不是估的。零占位文本在输出里搜{{、TODO、add here、...匹配数必须为零。第 8 条是最硬的检查也是唯一能用一条命令判生死的那条# 输出里搜索残留占位符匹配数必须为零 grep -rn {{\|TODO\|add here\|\.\.\. AGENTS.md .agents/rules/只要还有匹配这次输出就不合格。模板之间的条件型占位符也遵循同一红线{{SERVER_ACTION_VS_API_SECTION}}仅在 Server Actions 与 API 路由并存时生成{{RATE_LIMIT_SECTION}}仅在存在 rate-limit 中间件时生成含限额与过期时间{{LANGUAGE_SECTION}}仅在项目用 i18n 或非英语 UI 时生成——不适用即省略绝不输出空壳小节。能力边界知道它的限度再强的生成器也有明确的边。SKILL.md的 Limitations 写得很直白生成结果是提案所有指令需人工评审后才能采纳或提交生成器不替你背书。命令校验有边界校验只覆盖目标项目里可见的 scripts 与文件无法证明工具、服务或平台特定命令在所有环境都可用。包脚本是不可信代码项目提供的包脚本是不可信的可执行代码记录和文档化一个脚本不等于获得运行它的授权。写入范围受限它只在用户指定的项目范围内写入也不替代项目自身的安全、构建或部署评审。换句话说agents-generator 解决的是让AGENTS.md从空话变成可验证的项目事实但它交付的永远是一份待审的提案而不是可以直接合入的最终答案。把它当一个强力的起草器用而不是替身的审阅者。【免费下载链接】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,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考