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

agents-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 里，下面是速查版：

约束只有一条，且是硬性的：只生成实际适用的规则文件，不适用即省略。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.md；
• devDeps 里没有测试运行器，就不生成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_FLOW（validation → 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 用 "Routes"，NestJS / Express 用 "Endpoints"。

基准范例是detectPlatform() → downloadVideo() → downloadFromUrl() → ttdl()/igdl()/fbdown()/twitter()。对比反例 "validation → API call → database"——后者谁都能写，前者只有真正读过代码才写得出来。

命令与证据：只输出真实脚本、测试数与 git 历史

{{ESSENTIAL_COMMANDS}}：不存在的脚本一律不写。只包含package.json中脚本键确实存在的命令，格式{pm} run <key>或{pm} <key>，与检测到的包管理器对齐（bun 不带run，npm 用npm run，pnpm / 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 tests"（5 个测试文件，全在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 --noEmit（bun 项目为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.md"Execution Steps" 定义的整体流程里。按执行顺序串起来是七步：

1. 定位根目录：git rev-parse --show-toplevel确定项目根，后续所有路径以此为基准。
2. 先检测包管理器：bun.lock→ bun，pnpm-lock.yaml→ pnpm，package-lock.json→ npm，yarn.lock→ yarn。这一步排在最前，且绝不默认 npm——它决定了后面每条命令的前缀。
3. 读取配置：读package.json的 scripts、deps、workspaces，把 scripts 存下来供命令校验。
4. 探查目录与配置：读非机密配置文件、探查目录结构。排除所有.env*文件（仅允许纯占位形式的.env.example），环境变量名只能从.env.example的占位符与源码里的process.env.NAME引用推导。
5. 选择模式：full / minimal / update / dry-run，有歧义时问用户。
6. 填充与输出：full 模式读agents-full.md和各规则模板，逐项填占位符，产出AGENTS.md（包裹在<!-- AGENTS-GENERATED-START -->/<!-- AGENTS-GENERATED-END -->托管块之间）与.agents/rules/*.md。
7. 后处理校验：扫描{{、TODO、...并修正；校验每条命令存在于 scripts；AGENTS.md超 300 行告警、超 500 行强制把内容迁到规则文件；用 Conventional Commits 汇总变更；报告检测、生成、跳过内容与置信度。

这条流水线里埋着几个安全设计，值得单独点出：

• 不读秘密值：.env、.env.local、凭据存储一律不碰，环境变量只取名字不取值。
• 不执行项目脚本：包管理器脚本是仓库可控的 shell 入口点，生成器只检测并记录候选的 format / lint 命令，默认不执行——除非用户单独授权且已审阅脚本体。
• 生成即提案：所有输出在用户批准前都只是提案，不直接改写目标文件。
• 先备份：文件已存在时先拷到.agents/backups/并带时间戳。

质量红线：八条验收标准，一票否决

example-output/README.md 给出八条关键质量检查。它们不是建议，是红线——任何一条没过，这次生成就该重做：

1. 命令精确：写bun dev而不是npm run dev；能从"doctor": "npx react-doctor@latest"读出bun doctor。
2. 验证循环真实：bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor，每条命令都存在于package.json。
3. 约定匹配技术栈：写 "Sin librería de validación externa — TypeScript types + guards manuales (isDownloadError())"，而不是凭空捏一个 "Zod para validación"。
4. 架构图具体：ASCII 图展示真实目录（app/、components/、lib/downloader/），不是通用占位。
5. 数据流用真实函数名：detectPlatform() → downloadVideo() → downloadFromUrl() → ttdl()/igdl()/fbdown()/twitter()，不是 "validation → API call → database"。
6. 路由表完整：每个路由文件都列出，带类型（client / server）和项目 UI 语言的描述。
7. 测试数准确："74 tests" 是从实际测试文件数出来的，不是估的。
8. 零占位文本：在输出里搜{{、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