企业官网建设流程全解析

• 前端
• 后端
• Web框架

本文以 Modern.js monorepo 根目录的 AGENTS.md 为骨架，完整解析这份「给在仓库中工作的 AI Agent（Claude Code / Cursor 等）的常驻指引」：它如何用一份薄文件承载仓库分区、常用命令、禁改区、知识检索路由与 Skill 触发机制，并对照 package.json、pnpm-workspace.yaml、scripts/sync-skills.mjs 等源码与配置文件，说明每条规则背后的实现依据。读完你将掌握在 Modern.js 仓库内安全构建、测试、改代码与交付变更的完整流程，以及「用户向 Skills」与「维护者向 Skills」两套体系的边界与安装方式。

这份 AGENTS.md 是什么：薄约束，而非厚文档

Modern.js 仓库的 AGENTS.md 明确了自己的定位——保持精简：只放命令、约束、路由，详细知识查文档与 llms.txt，复杂流程走skills/。这与常见的「把全部知识塞进一份大文档」的做法相反：仓库采用三层分工：

• AGENTS.md（薄、常驻）：存放 Agent 进入仓库后必须第一时间知道的命令、边界与「该去哪查」的路由；
• llms.txt（厚、自动生成）：承载 API / 配置 / 概念等完整知识，由文档站的@rspress/plugin-llms插件自动产出；
• Skills（可验证的多步骤流程）：把高频、多步骤、可验证的复杂操作封装为带脚本与状态的 Skill。

一句话总结三者的边界（原文原话）：llms.txt = 知识（厚、自动生成）；AGENTS.md = 约束与路由（薄、常驻）；Skills = 可验证的多步骤流程（带脚本/状态）。这份指引面向的是「在仓库里开发 Modern.js 本身」的维护者 Agent，而非「用 Modern.js 开发应用」的用户 Agent——后者的入口是文档站的 AI 工具指南。

仓库全貌：pnpm + nx 的 monorepo 分区

AGENTS.md 首先交代了仓库的底座：基于 React 的渐进式 Web 框架 Modern.js，当前主仓为 v3，采用 pnpm + nx monorepo。包划分由 pnpm-workspace.yaml 定义，其 glob 规则覆盖了packages/*、packages/cli/*、packages/document/*、packages/runtime/*、packages/generator/*、packages/server/*、packages/solutions/*、packages/toolkit/*、scripts/*、tests、tests/integration/**/*、tests/e2e/**/*、examples/*、benchmark/*等十余个区域。

指引按「风险等级」给主要分区划了重点，这直接决定了 Agent 改代码时的谨慎程度：

任务编排层由 nx.json 承担：targetDefaults.build开启了缓存（"cache": true）并声明dependsOn: ["^build"]，输入为{projectRoot}/src/**/*、tsconfig、package.json、modern.config.*、rstack.config.*等（见 nx.json），这意味着按依赖拓扑构建与增量缓存是仓库日常开发的基础设施。对应地，根 package.json 提供了prepare-build等批量构建脚本（nx run-many -t build -p @modern-js/*），并声明了运行时约束：Node^22.18.0 || >=24.3.0、pnpm>=10.0.0、包管理器固定为 pnpm@10.13.1（见 package.json）。

常用命令速查：从安装到变更的完整链路

AGENTS.md 给出了六类高频命令，全部可以在根 package.json 的scripts中找到一一对应的实现。

安装与构建

pnpm install # 安装全部依赖（workspace 协议解析见 pnpm-workspace.yaml） pnpm --filter <pkg> build # 构建单个包，例如 pnpm --filter @modern-js/app-tools build

--filter是 pnpm 的包级过滤语法，配合 nx 的构建缓存，单包迭代成本很低。

测试：按类型分层跑

仓库刻意把测试分成四类，避免「一把梭」导致定位困难：

pnpm test:ut # 单元测试：根目录直接跑 rstest（package.json: "test:ut": "rstest"） pnpm --filter <pkg> test # 单包单测：包内即 rstest，例如 pnpm --filter @modern-js/utils test pnpm test:framework # 框架集成测试：cd tests 后跑 rstest 集成用例 pnpm test:builder # 构建器 e2e 测试：在 tests/e2e/builder 下执行 node tests/skill/run.mjs # Skill 回归：验证 modernjs-migrate-to-v3 node tests/skill/feature-enable.mjs # Skill 回归：验证 modernjs-feature-enable

从实现看（package.json + tests/package.json）：

• test:framework最终执行cd tests && pnpm run test:framework，即cross-env MODERN_SERVER_LOG_LEVEL=info rstest，统一注入服务端日志级别；
• test:builder进入tests/e2e/builder执行其自有测试（Playwright 体系）；
• Skill 回归脚本 tests/skill/run.mjs 与 tests/skill/feature-enable.mjs 会把tests/skill/fixtures/下的真实 fixture 复制到临时目录，依次跑scan-project.mjs/migrate.mjs、scan.mjs/enable.mjs并断言产物形态——例如断言「appTools({ bundler }) → appTools()」「BFF 启用后plugins: [appTools(), bffPlugin()]且幂等」。这套「先复制到临时目录再跑」的设计，保证了回归测试不会污染仓库本身。

代码质量与变更管理

pnpm check # Rstack CLI 全量检查（见 rstack.config.mts） pnpm lint # 仅代码校验 pnpm format # 全仓格式化 pnpm change # 生成 changeset（影响发布的改动必须加）

check/lint/format分别对应 package.json 的rs check/rs lint/rs fmt。底层配置在 rstack.config.mts：lint 启用了 JS/TS 的 recommended 规则集并显式关闭了一批存量违规规则（如no-explicit-any、ban-ts-comment），staged 钩子按文件类型分别执行rs lint/rs fmt，并对**/package.json额外跑pnpm check-dependencies校验依赖一致性。pnpm change即 changeset 的add命令（package.json），配合 commitlint 的 conventional 规范（package.json），任何影响发布的改动都必须携带 changeset，这是 monorepo 发版流水线（bump、release等脚本）的前置输入。

禁改区与安全红线：哪些文件绝不能手碰

AGENTS.md 用单独一节强调了三类禁改区，且这一约束被各 Skill 的「安全红线」反复强化：

1. 不手改pnpm-lock.yaml、dist/、node_modules/、各包CHANGELOG.md——lockfile 只能通过pnpm install的锁文件流程维护（根脚本提供了fix:lockfile、update:lockfile两个专用入口）；CHANGELOG.md由 changeset 版本脚本自动生成；
2. 不改框架运行时语义而不加测试——运行时在packages/runtime/*、packages/server/*等高风险区，语义改动必须由 tests 下的集成用例覆盖；
3. 不提交 secret / token。

这条红线在 modernjs-migrate-to-v3 的 SKILL.md 中体现为「不手改pnpm-lock.yaml/dist/CHANGELOG/node_modules/ secret」，在 dependency-audit 的 SKILL.md 中体现为「只读分析 + 给建议；不自动改 lockfile / dist / node_modules；改package.json前先展示 diff、让人确认」。可见这份约束不是停留在指引文本，而是贯穿到了每个自动化流程的实现纪律中。

知识检索：llms.txt 与随包文档

AGENTS.md 规定：API / 配置 / 概念问题优先查https://modernjs.dev/llms.txt，全文索引在https://modernjs.dev/llms-full.txt（体积大、按需取片段），并要求「回答须匹配仓库当前版本，勿用更新版本未发布的特性」。

这一路由在文档站侧有完整实现支撑。文档包 packages/document/package.json 依赖@rspress/plugin-llms（v2.0.2），由 rspress 文档站自动生成 llms.txt 索引与全文；面向用户的 AI 工具指南 还说明了更进一步的机制：随包文档——与安装版本一致的英文文档会随@modern-js/app-tools一起分发到node_modules/@modern-js/app-tools/docs/，离线可用，让 Agent 获取与当前框架版本严格匹配的 API、配置与约定，而不是依赖可能过时的训练数据。新建项目时npx @modern-js/create默认生成项目级AGENTS.md（--no-agents-md跳过），已有项目可随时用--agents-md-only重新生成，且框架只维护<!-- BEGIN:modernjs-agent-rules -->标记内的内容、不碰用户自定义部分。

Skills 体系：两类来源，一条同步链路

AGENTS.md 最核心的路由指令是：复杂流程走 Skills，且两类 Skill 分两处源、别混（详见 skills/README.md）。

用户向 Skills：服务「用 Modern.js 开发应用」的 Agent

唯一手写源是仓库根 skills/ 下带SKILL.md的目录，遵循 Agent Skills 开放标准，用户用标准skillsCLI 安装：

# 列出可安装的 Skills npx skills add web-infra-dev/modern.js --list # 安装单个 Skill（--agent 可选 claude-code / codex / cursor） npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y # 锁版本：仓库后加 #<tag>（tag / 分支 / commit） npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y

当前已落地的用户向 Skill 有两个（skills/README.md）：

• modernjs-migrate-to-v3：Modern.js v2 → v3 迁移。核心流程为「扫描（scan-project.mjs产出context.json，判定 v2/v3）→ 安全自动改写（migrate.mjs，依赖升级、import 路径改写、appTools({ bundler })→appTools()、dev.port→server.port、src/pages→src/routes等）→ 人工清单（report.json的manual）→ 安装依赖 → lint → 构建验证」，全程以 guides/upgrade 系列文档 为事实依据，且对 workspace/link 协议依赖、注释里的伪配置等边界做了「不误迁、不写半成品」的防御（见 SKILL.md）；
• modernjs-feature-enable：为 v3 应用启用可选功能。能力矩阵分两档——可自动启用（BFF、SSG、styled-components：装插件 + 改modern.config+ 必要文件，全自动闭环）与脚手架（Tailwind CSS、自定义 Web Server：自动生成可构建骨架，业务语义人工补全），并明确modern new命令在 v3 已移除、不再作为现行依据（见 SKILL.md）。

维护者向 Skills：服务「开发 Modern.js 仓库」的 Agent

唯一手写源是scripts/skills/，故意不放在根skills/——避免被对外skillsCLI 默认发现而误分发。当前已落地dependency-audit（依赖健康体检：幽灵依赖、循环依赖、重复多版本、安装体积归因，见 SKILL.md），规划中（P1+）还有modernjs-issue-triage、modernjs-pr-review。

.claude/skills、.agents/skills、.cursor/skills只是pnpm sync:skills生成的镜像（派生物，已 gitignore）。这条规则的实现可以直接在 scripts/sync-skills.mjs 中读到：

• 源目录硬编码为scripts/skills（第 13 行），且仅含SKILL.md的目录会被识别（第 105-107 行）；
• 目标目录映射为claude → .claude/skills、codex → .agents/skills、cursor → .cursor/skills（第 15-19 行）；
• 同步采用相对路径符号链接而非复制（syncSkill函数第 177-195 行），并自动清理旧版残留（modernjs-dependency-audit等 legacy 链接）与失效链接；
• 支持--target=claude|codex|cursor|all与--dry-run，终端交互式运行时会提示选择目标 Agent 目录（第 59-73 行）。

这与根 package.json 的"sync:skills": "node ./scripts/sync-skills.mjs"一一对应。

Skill 的准入纪律

AGENTS.md 特别强调：Skills 默认不强装、不隐式安装；只在多步骤 + 可验证 + 高频场景才做成 Skill，其余沉淀进本文件或文档。换言之，AGENTS.md 自身也是一个「缓冲池」——不够格成为 Skill 的知识先留在指引里，避免 Skill 目录膨胀。这与仓库为每个 Skill 配备独立回归测试（tests/skill/run.mjs、tests/skill/feature-enable.mjs）的「可验证」要求是配套的：没有自动化断言兜底的多步骤流程，不应上升为 Skill。

给 Agent 的落地建议：在仓库内安全工作的四条准则

综合 AGENTS.md 全文与其背后的实现，可以提炼出在该仓库内工作的实操准则：

1. 先路由再动手：命令、约束类问题读 AGENTS.md；API/配置/概念查 llms.txt（或随包文档）；多步骤复杂操作（迁移、启功能、依赖审计）优先触发对应 Skill，而不是自己临时拼命令；
2. 改动前先分清风险区：app-tools、cli/*、runtime/*、server/*是高风险区，任何语义变更都必须配套测试（pnpm test:framework/pnpm test:builder等）；
3. 严守禁改区：不手改 lockfile、dist、node_modules、CHANGELOG；需要变更发布内容时用pnpm change生成 changeset；
4. 验证链路要跑全：pnpm lint/pnpm check→ 分层测试 →pnpm format，最后确认改动符合 Node/pnpm 版本约束（Node^22.18.0 || >=24.3.0、pnpm>=10）。

结语

Modern.js 的 AGENTS.md 是一份设计克制的 Agent 治理文件：它不追求「写全」，而追求「路由对、边界清、纪律明」——薄薄的几十行，指向了仓库分区、命令体系、禁改区、知识检索与 Skill 体系五条主线，每条主线都能在 package.json、pnpm-workspace.yaml、nx.json、scripts/sync-skills.mjs 与各 SKILL.md 中找到可验证的实现依据。对于要在该仓库中工作的 AI Agent 或维护者而言，先通读这份指引、再按「命令 → 约束 → 路由 → Skill」的顺序执行，就是最稳妥的入场方式。

• 前端
• 后端
• Web框架