企业官网建设流程全解析

1. 为什么“堆 AGENTS.md”正在拖垮前端团队的 AI Coding 实践

我带过三支不同规模的前端团队，从20人初创公司到300人以上的大厂业务线，几乎都经历过这个阶段：某天晨会，技术负责人兴奋地宣布“我们要接入 AI Coding”，接着就是一份命名规范统一、分类清晰、密密麻麻写满提示词和示例的AGENTS.md文件被推送到主干分支。文件里分了“代码生成类”“Bug 定位类”“文档补全类”“CR Review 类”，每个类别下又列了 5–8 个 agent 的名称、角色定义、输入约束、输出格式、典型 prompt 示例……看起来非常专业，甚至配了 Mermaid 流程图（虽然最后也没人真去跑）。但三个月后，这份文档基本就躺在 Git 历史里吃灰了——不是没人用，而是用得极其痛苦：新人照着 copy-paste 提示词，结果生成的代码要么漏了 React 18 的useId调用，要么把 TypeScript 的as const写成as any；老手想复用某个“组件重构 agent”，却发现它依赖的上下文模板和当前项目目录结构完全对不上；更常见的是，当线上出现一个跨 service worker + WebAssembly + CSS Container Queries 的复合型 bug 时，翻遍AGENTS.md也找不到能处理这种上下文粒度的 agent，最后还是得靠人肉 debug。

这就是标题里说的“堆 AGENTS.md”的本质：它把 AI Coding 简化成了“提示词管理工程”，而忽略了前端开发真正的复杂性——上下文不是静态文本，而是动态、分层、有依赖关系的工程事实集合。一个按钮点击事件的修复，可能需要同时理解：当前组件的 props 类型定义（TS 接口）、父级状态管理方案（Zustand 还是 Jotai）、CSS-in-JS 的主题注入逻辑（Emotion 还是 Styled Components）、构建产物的 chunk 分割策略（影响 runtime 错误堆栈可读性），甚至 CI/CD 中 E2E 测试的超时阈值（决定是否要加 loading 骨架屏）。这些信息散落在tsconfig.json、vite.config.ts、.eslintrc.cjs、jest.setup.ts、playwright.config.ts、package.json#scripts、src/lib/utils/featureFlags.ts等至少 7 类不同语义层级的文件中。AGENTS.md试图用扁平化的 Markdown 列表去承载这种立体结构，就像用 Excel 表格管理一座城市的交通调度系统——表格能记录红绿灯时长，但无法表达早高峰地铁换乘站与周边共享单车调度之间的耦合关系。

所以，“别再堆 AGENTS.md”不是反对写文档，而是反对把 AI Coding 当作“AI Prompt 工程”来建设。真正可执行的工程系统，必须回答三个问题：第一，如何让 AI 理解前端项目的“真实上下文”，而不是我们“希望它看到的上下文”？第二，如何把 AI 的输出，无缝嵌入到现有研发流程（Git Flow、Code Review、CI Pipeline）中，而不是另起一套“AI 操作台”？第三，如何让每个前端工程师，不依赖“AI 工程师”就能安全、可控、可追溯地使用 AI，就像他们现在用 ESLint 或 Prettier 一样自然？这三个问题的答案，不在.md文件里，而在一套分层、可插拔、与工程实践深度绑定的系统设计中。接下来我会拆解这套系统怎么落地，不讲概念，只讲我们团队在 6 个月里踩过的坑、验证过的配置、实测有效的参数，以及为什么某些看似“更先进”的方案最终被我们弃用。

2. 上下文分层：不是给 AI “喂数据”，而是帮它建立“工程认知地图”

2.1 为什么“一股脑扔代码”是最危险的上下文供给方式

很多团队的第一步，是让 LLM 读取整个src/目录下的所有.ts和.tsx文件。表面看很“全面”，实则埋下巨大隐患。我做过一组对比实验：用同一份 prompt（“请为登录表单添加邮箱格式校验，并确保错误提示符合设计规范”），分别喂给三种上下文：

• Context A（全量代码）：src/下全部 127 个文件，约 42 万行代码（含 node_modules 未排除）；
• Context B（精准路径）：仅src/pages/LoginPage.tsx、src/components/FormInput.tsx、src/utils/validation.ts、src/styles/designTokens.css四个文件；
• Context C（分层结构）：LoginPage.tsx的 AST 结构化摘要（含 props interface、useEffect 依赖项、JSX 树深度）、FormInput.tsx的组件契约（props 类型、emits 事件、slot 规范）、validation.ts的函数签名与 JSDoc、designTokens.css的 CSS 变量映射表（如--error-color: #e53e3e→red.500）。

结果非常明确：Context A 的输出中，有 63% 的代码引入了不存在的import { useAuth } from '@/hooks/useAuth'（该 hook 在src/hooks/下实际叫useAuthentication），且错误提示用了alert()而非设计规范要求的Toast组件；Context B 的输出准确率提升到 89%，但仍有 11% 的 case 把Toast的position参数写成'top-right'（实际 API 是'top-right'与'top-left'，但设计规范强制要求'top-right'）；Context C 的输出 100% 符合要求，且生成的校验逻辑自动适配了validation.ts中已有的emailRegex常量，而非重复定义。

根本原因在于：LLM 的上下文窗口不是“搜索引擎”，而是“模式匹配器”。当喂入全量代码时，模型被迫在海量噪声中寻找信号，极易被相似但错误的代码片段干扰（比如src/pages/SignupPage.tsx里有个useAuth的旧版实现）。而分层结构化上下文，相当于给 AI 提供了一张“工程认知地图”——它不再需要从原始代码中“推理”出组件契约，而是直接获得经过工程验证的抽象层（AST 摘要、类型定义、设计 token 映射）。这就像教一个新同事熟悉项目，你不会让他通读全部源码，而是先给他看架构图、接口文档、设计规范手册，再带他看具体模块。

2.2 前端上下文的四层黄金结构：L0–L3 的职责与生成逻辑

我们最终确定的上下文分层模型，严格对应前端工程的实际生命周期，每一层都有明确的生成工具、更新触发机制和消费方：

这个分层不是理论模型，而是我们每天都在运行的生产系统。举个真实案例：上周一个同学提交 PR 修改了LoginForm的onSubmit处理逻辑，CI 中的CR Review Agent自动触发。它首先拉取 L0 层确认项目仍在用 Vite 4.5+（避免推荐已废弃的import.meta.glob语法），再读取 L1 层的apiClient类型，发现新代码里await apiClient.login()的返回类型与src/lib/api/types.ts中定义的LoginResponse不一致（缺少userRole字段），接着调用 L2 层的 AST 分析，定位到LoginForm.tsx中onSubmit函数体内的if (response.success)判断，指出此处应改为if ('userRole' in response && response.success)以兼容旧版 API。整个过程耗时 1.8 秒，比人工 Review 快 3 倍，且结论可追溯到具体的 L1/L2 文件版本。

提示：L2 层的 AST 摘要生成是性能瓶颈。我们实测发现，对一个 200 行的 React 组件，@typescript-eslint/parser解析耗时约 120ms，但生成人类可读的摘要（如“该组件使用了useState管理email和password，useEffect依赖[email]，JSX 中有 1 个button[type="submit"]”）需额外 80ms。为此我们做了两项优化：一是将 AST 解析结果缓存到.vscode/.ast-cache/，仅当文件 mtime 变更时重解析；二是摘要生成采用流式输出，Agent 可边接收边处理，不必等全部摘要完成。

2.3 如何让分层上下文“活”起来：基于 Git 的增量更新与版本绑定

分层结构如果只是静态快照，很快就会过期。我们的解决方案是：所有上下文层均与 Git commit hash 绑定，并支持增量更新。

• L0/L1 层：由 CI 流水线在git push后自动生成，存储在专用 S3 bucket，路径为s3://<project-name>/context/<commit-hash>/L0.json。每次 Agent 调用时，传入当前 workspace 的git rev-parse HEAD，服务端自动 fetch 对应 commit 的上下文。这样保证了即使开发者本地代码未提交，AI 也能基于“已知稳定版本”的上下文工作。

• L2 层：VS Code 插件监听文件系统事件。当用户保存src/pages/HomePage.tsx时，插件立即触发ast-context-extractor --file src/pages/HomePage.tsx --commit <current-hash>，生成的摘要存入本地./.context/L2/<current-hash>/HomePage.json。这里的关键是--commit参数——它确保摘要与当前 Git 状态强绑定。如果用户git stash后又恢复，插件会检测到 commit hash 变更，自动清理旧缓存并重建。

• L3 层：采用“懒加载 + TTL”策略。Agent 调用前，本地脚本env-fact-collector执行一次，结果存入内存（非磁盘），有效期 30 秒。超过时效则重新采集。这样既保证实时性，又避免频繁调用git status拖慢响应。

这套机制带来的最大收益是可重现性。当某个 AI 生成的代码在 CI 中失败时，我们只需记录下失败时的 commit hash 和 Agent ID，就能在任意机器上精确复现当时的全部上下文（L0–L3），无需猜测“是不是本地环境不同”。这彻底改变了团队对 AI 错误的认知——过去认为是“AI 不可靠”，现在定位为“上下文供给链某一层失效”，问题排查效率提升 70%。

3. 工程系统落地：从 VS Code 插件到 CI/CD 的全链路集成

3.1 VS Code 插件：让 AI Coding 成为“编辑器原生能力”，而非独立应用

我们放弃开发独立的 AI Coding IDE，而是将所有能力深度集成到 VS Code。核心原则是：AI 操作必须遵循编辑器原生交互范式，不打断开发者心流。插件名为Frontend-AI-Engine，它不提供聊天界面，只暴露三个命令：

• Frontend: Generate Component（快捷键Cmd+Shift+G）：光标在src/components/目录下时激活，弹出输入框“组件名（PascalCase）”，生成Button.tsx、Button.stories.tsx、Button.test.tsx三文件，且自动 import 到当前引用处；
• Frontend: Fix This Bug（快捷键Cmd+Shift+F）：光标在报错行时激活，自动提取错误堆栈、当前文件 AST、相关依赖模块，调用 Bug Fix Agent；
• Frontend: Review This PR（右键菜单）：在 Git 视图中选中 PR，一键触发 CR Review Agent，结果以 Code Lens 形式显示在 diff 行旁（如✅ Type safety: response.userRole is now checked）。

插件的技术栈非常克制：TypeScript + VS Code Extension API + WebSocket。所有 heavy lifting（上下文组装、LLM 调用、结果解析）都在远程服务端完成，插件只做三件事：1）采集本地上下文（L2/L3）；2）通过 WebSocket 发送请求并接收流式响应；3）将响应中的edit指令（如{ "file": "src/components/Button.tsx", "line": 12, "text": "const Button = ({ children, variant = 'primary' }: ButtonProps) => {" }应用到编辑器。

注意：我们严禁插件直接调用fetch请求 LLM API。所有通信必须走 WebSocket，且首帧必须携带auth_token（从 VS Code 的secretsAPI 获取）。这是为了防止用户误将 API Key 硬编码在插件配置中——去年某团队就因插件配置泄露导致 LLM 账号被盗刷 $2000。

最关键的用户体验设计是渐进式反馈。以Generate Component为例：

• 第 1 秒：显示🔍 Analyzing project context...（L0/L1 加载）；
• 第 2 秒：显示🧩 Building module graph for Button...（L2 AST 分析）；
• 第 3 秒：显示⚡ Generating component files...（服务端 LLM 调用）；
• 第 4 秒：Button.tsx文件自动打开，光标定位在export interface ButtonProps行，右侧显示 Code Lens✏️ Edit props interface；
• 第 5 秒：Button.stories.tsx和Button.test.tsx以 Tab 形式打开，且test文件中已预填it('renders with primary variant', () => { ... })。

这种设计让用户始终感知到“系统在工作”，而非等待黑盒。我们统计过，插件平均响应时间 4.2 秒，但用户主观等待感低于 2 秒，因为每一步都有明确的进度语义。

3.2 CI/CD 流水线：让 AI 成为“永不疲倦的 Senior Developer”

AI Coding 的价值，只有在自动化流水线中才能最大化。我们在 GitLab CI 中嵌入了三个关键阶段：

• ai-lint阶段（并行于eslint）：调用lint-agent，输入为本次 commit 修改的所有.ts/.tsx文件。它不检查语法，而是检查“工程一致性”：例如，若修改了src/lib/api/client.ts，则必须同步更新src/lib/api/types.ts中的ApiError类型；若新增了useQueryhook，则必须在src/lib/queryClient.ts中注册对应的queryKey命名规范。违反规则时，输出类似❌ [API Contract] src/lib/api/client.ts line 45: new endpoint '/v2/users' requires corresponding type in src/lib/api/types.ts，且 exit code 1，阻断合并。

• ai-test-gen阶段（仅对src/下新增/修改的组件）：调用test-agent，为每个新组件生成 Jest 测试骨架。重点不是覆盖率，而是测试意图的准确性。Agent 会分析组件的 props 类型、useEffect 依赖项、事件 handler，生成describe('Button', () => { it('calls onClick when clicked', () => { ... }); it('disables when isLoading is true', () => { ... }); })。我们要求生成的测试必须能通过jest --dry-run，否则视为失败。

• ai-security-scan阶段（针对src/pages/下所有页面）：调用security-agent，专门检测 SSRF、XSS、CSP bypass 风险。例如，当检测到window.location.href = userControlledUrl时，Agent 会输出⚠️ [XSS Risk] src/pages/Dashboard.tsx line 88: Direct assignment to location.href without sanitization. Recommend using createSafeUrl() from src/lib/security.ts.并附上修复建议代码块。

这三个阶段全部开源，配置文件gitlab-ci.yml中仅需两行：

ai-lint: stage: lint script: npx @frontend-ai/agent-runner --type lint --commit $CI_COMMIT_SHA ai-test-gen: stage: test script: npx @frontend-ai/agent-runner --type test --commit $CI_COMMIT_SHA

实操心得：CI 阶段最易失败的不是 AI，而是网络超时。我们为所有 Agent 调用设置了严格的 timeout：ai-lint30s，ai-test-gen60s，ai-security-scan90s。超时后自动 fallback 到规则引擎（如ai-lintfallback 到eslint-plugin-import的路径检查），确保流水线不因 AI 不可用而中断。这是“可执行工程系统”的底线——AI 是增强，不是单点故障。

3.3 Code Review 协同：AI 不是替代者，而是“超级协作者”

我们严禁 AI 直接 approve PR。它的角色是：在人类 Reviewer 的决策链中，插入一个高可信度的事实核查节点。

具体流程：

1. 开发者提交 PR，标题格式为[FE-123] Add email validation to login form（Jira ID 强制）；
2. ai-cr-reviewAgent 自动触发，分析 PR 的 diff、L0–L3 上下文、关联的 Jira ticket 描述；
3. Agent 输出结构化报告（JSON），包含：
   • compliance：是否符合团队规范（如“所有新组件必须有 Storybook”）；
   • type_safety：TS 类型变更是否完整（如新增 prop 是否更新了 interface）；
   • test_coverage：是否新增了必要的测试（基于 diff 的组件变更分析）；
   • security_risk：高危模式检测（如eval()、innerHTML直接赋值）；
   • performance_impact：是否引入了不必要的 re-render（如在useMemo中遗漏依赖）；
4. 报告以 Comment 形式发布在 PR 下，但不带任何主观评价，只陈述事实。例如：

   ### AI Review Summary (v2.3.1) - ✅ Compliance: Storybook file `src/components/LoginForm.stories.tsx` added. - ⚠️ Type Safety: `LoginFormProps` interface updated, but `src/types/form.d.ts` not modified. Consider adding `emailValidation?: boolean`. - ❌ Test Coverage: No new tests for `validateEmail` utility function in `src/utils/validation.ts`. - ✅ Security: No high-risk patterns detected. - ✅ Performance: `useCallback` correctly implemented for `handleSubmit`.

人类 Reviewer 只需看这一条评论，就能快速定位关键问题。我们统计过，使用该流程后，PR 的平均 Review 时间从 22 分钟降至 9 分钟，且严重 Bug 漏检率下降 41%。最关键的是，AI 的评论永远可追溯——点击⚠️ Type Safety后的链接，直接跳转到 L1 层的form.d.ts文件历史，看到该 interface 上次修改的 commit 和 author。

4. 实操避坑指南：那些没写在文档里的血泪教训

4.1 “Prompt 工程师”是个伪命题：前端团队必须自己掌握 LLM 微调能力

初期，我们聘请了一位“AI Prompt Engineer”，他的工作是优化AGENTS.md中的提示词。结果三个月后，他离职了，留下的是一堆无法维护的 prompt。根本问题在于：前端领域的专业性，无法被通用 prompt 技巧覆盖。例如，要让 AI 正确生成一个兼容 React Server Components（RSC）和 Client Components 的组件，prompt 里写“请生成 RSC 兼容代码”是无效的——模型不知道use client指令的边界、asyncserver component 的限制、fetch的缓存策略差异。真正有效的是：用 LoRA 微调一个 Qwen2.5-7B 模型，训练数据来自团队内部 2000+ 个已验证的 RSC 组件 PR。

我们现在的做法是：每个季度，由前端 Tech Lead 主导一次“微调冲刺”（Fine-tuning Sprint）。流程如下：

• Step 1：从 Git 历史中筛选出 50 个“高质量 RSC 组件 PR”，标准是：无 CI failure、无后续 hotfix、被至少 3 位 Senior 点赞；
• Step 2：将每个 PR 的 diff（git show <commit>）清洗为训练样本，格式为：

  { "instruction": "Convert this client-side component to a React Server Component compatible with Next.js App Router.", "input": "export default function UserProfile({ userId }) { const [data, setData] = useState(null); useEffect(() => { fetch(`/api/users/${userId}`).then(r => r.json()).then(setData); }, []); return <div>{data?.name}</div>; }", "output": "export default async function UserProfile({ userId }) { const data = await fetch(`/api/users/${userId}`).then(r => r.json()); return <div>{data.name}</div>; }" }

• Step 3：用 Unsloth 库进行 LoRA 微调，GPU 使用 A10，batch_size=4，epochs=3，learning_rate=2e-4；
• Step 4：微调后模型部署到内部 vLLM 服务，替换原有基础模型。

实测效果：微调后，RSC 转换任务的准确率从 68% 提升至 94%，且生成的代码 100% 通过next build。更重要的是，团队掌握了模型迭代的主动权——当 Next.js 发布新版本时，我们能在 2 天内完成微调，而不是等第三方模型厂商适配。

4.2 “AI 生成的代码不能直接 merge”：建立三层防护网

我们曾因一条“信任 AI”的 Slack 消息付出代价：一位同学直接 merge 了 AI 生成的useAuthhook，结果它在 Safari 15.6 下因AbortControllerpolyfill 缺失而崩溃。从此，我们建立了铁律：所有 AI 生成代码，必须通过三层防护才可进入主干。

• Layer 1：本地预检（Pre-commit Hook）
  husky+lint-staged配置：对所有.ts/.tsx文件，运行npx @frontend-ai/precheck --file <file>。该脚本会：

  • 检查文件是否含// AI-GENERATED注释（强制）；
  • 验证// AI-GENERATED后是否紧跟// @source: <commit-hash>（确保可追溯）；
  • 运行轻量级 AST 分析，确认无eval()、new Function()、document.write()等高危模式。

• Layer 2：CI 静态分析（GitLab CI）
  ai-static-check阶段，使用@typescript-eslint的自定义 rule：

  • no-unsafe-dom-manipulation：禁止innerHTML、outerHTML直接赋值，除非有// @safe-dom注释；
  • require-type-assertion：AI 生成的any类型必须有// @type-assertion: <reason>注释；
  • enforce-jest-mock：所有jest.mock()调用必须有// @mock-reason: <why>。

• Layer 3：人工终审（Human Gate）
  PR 描述中必须包含：

  • AI-Generated Files列表（自动提取）；
  • Changes Summary（由git diff --stat生成）；
  • Verification Steps（如“已在 Chrome/Firefox/Safari 测试登录流程”）；
  • Risk Assessment（由开发者填写，如“低风险：仅修改 UI，无逻辑变更”）。

这三层不是增加负担，而是将责任显性化。数据显示，启用该流程后，AI 生成代码的线上故障率从 0.8% 降至 0.03%，且 92% 的故障发生在 Layer 1 被拦截。

4.3 性能陷阱：不要低估 LLM Token 计算的隐性成本

很多人只关注 LLM API 的调用费用，却忽略了 Token 计算的工程成本。我们曾遇到一个严重问题：ai-lint阶段在大型 monorepo 中耗时飙升至 5 分钟。根因不是模型慢，而是上下文组装。

• 问题定位：ai-lint需要 L0/L1/L2/L3 全部上下文。L2 层对每个修改文件生成 AST 摘要，但我们的ast-context-extractor默认输出完整 AST JSON（约 1.2MB/文件），而 LLM 服务端需将其解析为字符串再计算 token。10 个文件就是 12MB，仅 token 计算就占 80% 时间。

• 解决方案：我们重构了 L2 摘要生成器，采用“按需序列化”：

  • 第一阶段（fast path）：只生成核心摘要（组件名、props interface、useEffect 依赖项），体积 < 5KB；
  • 第二阶段（slow path）：仅当 Agent 明确请求“详细 AST”时（如security-agent需要检查innerHTML赋值），才生成完整 AST；
  • 第三阶段（cache）：所有摘要存入 Redis，key 为l2:<file-path>:<mtime>，TTL 1 小时。

改造后，ai-lint平均耗时从 302s 降至 18s。更重要的是，我们为每个 Agent 设定了严格的 token 预算：

• lint-agent：≤ 2000 tokens（只读 L0/L1 + 核心 L2）；
• test-agent：≤ 4000 tokens（需 L2 详细 AST）；
• security-agent：≤ 8000 tokens（需完整 L2 + L3 环境变量）。

超出预算时，Agent 自动降级（如security-agentfallback 到正则扫描innerHTML=），并记录告警。这让我们能精准控制成本，避免“AI 无限吞噬资源”。

5. 从“AGENTS.md”到“Engineering System”：一场关于信任的重构

最后分享一个真实的转变时刻。上个月，团队新来了两位应届生。入职第一天，导师没给他们看AGENTS.md，而是直接打开 VS Code，演示Frontend: Generate Component。当Button.tsx自动生成并正确 import 到HomePage.tsx时，其中一位同学脱口而出：“这比我们学校教的 React 教程还直观。” 导师没多解释，只说：“记住，AI 不是来教你写代码的，它是来帮你省掉那些重复的、枯燥的、容易出错的‘工程 glue code’的。你真正的价值，永远在‘为什么这么写’的判断力上。”

这句话，正是我们放弃AGENTS.md的终极原因。那份文档本质上是在教人“如何向 AI 提问”，而工程系统的目标是让人“忘记 AI 的存在”——就像你不会思考“为什么 ESLint 能发现未使用的变量”，你只关心它是否帮你避免了 bug。当我们把上下文分层、CI 集成、三层防护网都变成像npm install一样透明的基础设施时，AI Coding 才真正完成了从“酷炫功能”到“必备能力”的跃迁。

我个人在实际落地中最深的体会是：最大的技术挑战从来不是模型本身，而是如何让模型的输出，与前端工程师每天面对的真实世界——那个充满 webpack 配置、TypeScript 版本冲突、浏览器兼容性列表、设计系统 token 的世界——严丝合缝地咬合在一起。这需要的不是更多 prompt，而是更深的工程洞察。当你开始用git commit的 hash 来索引上下文，用AST而不是string来传递信息，用CI exit code而不是chat message来定义成功时，你就已经走在了把 AI Coding 做成工程系统的路上。至于AGENTS.md？它现在安静地躺在我们 Wiki 的“历史文档”栏目里，标题旁标注着一行小字：“v1.0，2024.03，已归档”。