企业官网建设流程全解析

导读

本文以 PierreJS 多包仓库（monorepo）根目录的 CLAUDE.md 为入口，深入解析其唯一内容@AGENTS.md所指向的 AGENTS.md——一份面向 AI Agent 与开发者的完整协作规范。这份文档系统定义了 Agent 环境下终端会话的初始化方式、moon 任务在 CI 标记 shell 中的行为开关、proto 工具链管理、pnpm catalog 依赖纪律、Apache 2.0 许可检查、领域技能（Skills）加载流程，以及提交代码前的验证基线。读完本文，你将掌握如何在 PierreJS 仓库中正确初始化 Agent 环境、用moonx运行各类任务（含绕过 CI 门禁的--ignore-ci-checks）、遵循依赖与许可规范，并以moon run root:format root:lint等命令完成可复现的本地验证。

一、CLAUDE.md 与 AGENTS.md：Agent 入口文档的分层关系

在仓库根目录下，CLAUDE.md 全文只有一行：

@AGENTS.md

这是 Claude Code 风格的 include 语法，表示该文件的内容由 AGENTS.md 提供。因此，真正的规范主体是根目录的 AGENTS.md，它开篇即点明本仓库的身份——PierreJS Monorepo，并围绕"AI Agent 如何在仓库中工作"这一主题展开。这种"薄入口 + 厚主体"的组织方式意味着：任何 Agent 进入仓库后，都应从根目录的 AGENTS.md 开始读取协作约束，而不是被一行引用的文件误导。

需要区分的是，仓库中还存在另一层文档体系：skills/INDEX.md记录的是面向"消费 Pierre 包"的开发者的 package 技能索引（diffs、highlights、theme、theming、trees），而 AGENTS.md 中的 Skills 章节指向的是.agents/skills/——面向仓库内部开发的领域上下文，二者定位不同，阅读时不要混淆。

二、Agent 环境的正确初始化：AGENT=1与 CI 标记 shell

2.1 设置AGENT=1

AGENTS.md 要求在每个终端会话开始时设置环境变量，使 Bun 的测试运行器输出对 AI 友好的结果：

export AGENT=1

这是一条写入规范的环境约定：AGENT=1会改变 Bun 测试输出的格式（去噪、结构化），便于 Agent 解析测试失败信息。在进入 PierreJS 仓库做任何开发工作前，这一步都是前置动作。

2.2 moon 任务在 CI 标记 shell 中的行为

AGENTS.md 详细说明了 moon 任务的runInCI策略与 Agent harness 的关系：

• 本地工具类任务（格式化、基准测试、worktree 管理）在 moon.yml 中被配置为runInCI: 'always'，因此在 CI 标记的 shell（例如导出了CI=1的 Agent 环境）中依然可以运行；
• 与构建图相关的任务（dev server、prod serve、e2e 变体、发布守卫）保持 CI-skip 状态，在 CI 标记 shell 中需要用以下方式强制运行：

moonx <target> --ignore-ci-checks

例如文档给出的实战命令：

moonx docs:dev-diffs --ignore-ci-checks

• 对于非 moon 命令，如果该命令自身有 CI 门禁（如pnpm publish在 CI 环境中会被拒绝），则需要临时取消 CI 变量：

CI= pnpm publish --dry-run

从源码配置可以验证这套策略的实现：moon.yml 中，根项目的lint、lint-css、lint-css-fix、format、format-check、check-licenses、icons、chrome、wt、clean、clean-all任务均显式声明了runInCI: 'always'；而lint-fix（会基于类型信息修改代码）则设置了cache: false且runInCI: 'skip'，与 AGENTS.md"发布守卫类任务保持 CI-skip"的说明完全对应。文件头注释也解释了设计动机：runInCI: 'always'仅保留给没有图依赖边的任务——它们永远不会被图拉进 CI 流水线，因此可以安全地常驻启用。

三、工具链管理：proto 与.prototools

AGENTS.md 规定所有工具版本（bun、pnpm、node、moon、gh）都固定（pin）在.prototools中，并由 proto 实际内容为：

bun = "1.4.0" gh = "2.93.0" node = "24.11.0" proto = "0.57.4" pnpm = "11.9.0" moon = "2.3.3" [plugins] gh = "file://./.proto/plugins/gh.toml" [settings] auto-clean = false auto-install = true telemetry = false

关键操作规则：

• 如果某个工具缺失或 pin 发生变化，运行proto use按.prototools恢复正确的版本集合；
• 严禁全局安装工具链版本；要升级只能修改.prototools中的 pin；
• 由于auto-install = true，直接运行pnpm、bun或moon也会按需触发 proto 安装，这一点在 CONTRIBUTING.md 的 Setup 章节有进一步说明。

此外，AGENTS.md 明确指出moon 是唯一的任务执行器，package.json里的 scripts 只是 npm 生命周期钩子（lifecycle hooks），不应被当作常规任务入口使用。

四、核心规则：包管理器、依赖与任务执行纪律

AGENTS.md 的 Core Rules 定义了四条硬性纪律：

4.1 只用 pnpm 做包操作

安装、添加、移除、去重、包管理器和发布工作一律使用pnpm；除非有特定理由，不使用bun、npm、yarn、npx等替代工具。根目录 package.json 中"packageManager": "pnpm@11.9.0"与此保持一致。

4.2 依赖版本统一走 catalog

依赖版本统一放在 pnpm-workspace.yaml 的catalog字段中，各包通过"catalog:"引用，禁止在包级package.json中直接写版本号（除非该已发布包确实需要自己的版本范围）。仓库的实际 catalog 涵盖了 React、Next.js、Shiki、Vite、TypeScript（7.0.2）等数十个依赖，并配置了minimumReleaseAge: 10080（发布年龄门槛）与allowBuilds白名单，是典型的集中式依赖治理样板。

4.3 用 moon 运行任务

• 从仓库任意位置运行moon run <project>:<task>（或其简写moonx <project>:<task>）；
• 传参用moonx <project>:<task> -- args转发参数；
• 用moon tasks <project>发现某项目的任务清单。

4.4 文件尾随换行与新手设置

• 保留文件末尾的尾随换行（trailing newline）；
• 新克隆仓库的完整 setup 步骤在 CONTRIBUTING.md 中：先装 proto 与 git-lfs，再proto use、pnpm install；git hooks 由 moon 的vcs.hooks（位于.moon/workspace.yml）在首次运行 moon 命令时自动生成，无需手动安装。

五、许可规范：Apache 2.0 全覆盖与check-licenses

AGENTS.md 的 Licensing 章节规定，packages/*与apps/*下的每个包：

• 在package.json中设置"license": "apache-2.0"（根包 package.json 即如此声明）；
• 在包根目录放置 Apache 2.0 的LICENSE.md，可直接从既有包（如packages/trees/LICENSE.md）复制一份；
• 引入的第三方 vendored 代码保留其原始许可证，并在包旁的NOTICE.md中记录归属，而不是修改其 LICENSE。

规范还要求提交前运行moon run root:check-licenses——该检查在 CI 中对每个 PR 强制执行。从 moon.yml 的check-licenses任务定义可以看到其实现：通过bun --silent scripts/check-licenses.ts扫描 scripts/check-licenses.ts，输入文件为**/package.json、**/LICENSE、**/LICENSE.md（并排除 node_modules、dist、.next、.source），确保"声明 apache-2.0 + 携带 LICENSE 文件"双条件成立。

六、Skills 加载：领域上下文的正确打开方式

AGENTS.md 要求任何任务开始前都遵循固定的 Skills 加载流程：

1. 列出.agents/skills/*/SKILL.md；
2. 只读取各技能 frontmatter 中的描述，识别与当前任务相关的技能；
3. 只完整读取与任务相关的SKILL.md文件。

并明确警告：不要加载与任务无关的技能。当前仓库的.agents/skills/下实际存在 5 个技能：

• .agents/skills/browser-automation/SKILL.md
• .agents/skills/testing-and-verification/SKILL.md
• .agents/skills/tooling-and-dependencies/SKILL.md
• .agents/skills/typescript-monorepo/SKILL.md
• .agents/skills/worktrees-and-dev-servers/SKILL.md

这套"先看描述、按需精读、避免噪音"的加载策略，直接服务于 Agent 在大型 monorepo 中快速定位领域约定，避免无关上下文污染推理。与之平行的还有面向包使用者的 skills/INDEX.md，其中明确给出了各 Pierre 包的适用场景（例如@pierre/diffs用于渲染与编辑代码/补丁/合并冲突，@pierre/trees用于交互式文件树），并说明@pierre/theme提供主题对象、@pierre/theming负责选择与映射、@pierre/diffs与@pierre/trees负责渲染的依赖关系。

七、Agent 工件目录：.agents/ignore/

AGENTS.md 规定，仅 Agent 使用的规划与草稿工件默认写入.agents/ignore/：

• 计划（Plans）：.agents/ignore/plans/YYYY-MM-DD-<topic>.md
• 规格（Specs）：.agents/ignore/specs/YYYY-MM-DD-<topic>.md

.agents/ignore/已被 gitignore，因此这些内容不会进入版本库；同时明确禁止把源文件、测试或需要提交的文档放进该目录。这条规则的目的是隔离 Agent 的临时思考产物与仓库的正式资产，避免污染提交历史。

八、验证基线：改动后的最小验证集合

AGENTS.md 的 Verification Baseline 是全文最可操作的部分：代码改动后，只有运行了以下命令才视为验证完成（可从仓库任意位置执行）：

moon run root:format root:lint

在此基础上，还需运行受影响区域的 typecheck 与聚焦测试，例如：

moonx <project>:typecheck moonx <project>:test # 或仅检查受影响的项目 moonx :typecheck --affected

对于纯文档（docs-only）或 AGENTS/skills 类改动，如果未触及可执行代码或包配置，格式化和 lint 即可满足要求。结合 CONTRIBUTING.md 的"Before you push"章节，完整的提交流程为：

moon run root:format root:lint moon exec :typecheck --affected moonx <project>:test # 聚焦测试

其中root:format对应 moon.yml 中的oxfmt .（全仓格式化，cache: false），root:lint对应oxlint --type-aware --tsconfig tsconfig.oxlint.json .（类型感知 lint，依赖所有 dist 产出包先构建），因此这套基线天然覆盖了"格式化 + 类型感知静态检查"两个维度。

九、代码可读性规范：面向新读者的注释纪律

AGENTS.md 对注释风格提出了明确要求，核心是"写给刚接触代码路径的读者"：

• 新增非平凡辅助函数时，在函数正上方加一段简短注释，说明它做什么以及为什么存在；
• 避免含糊的简写（例如直接写 "snapshot" 却不解释捕获/派生了什么数据）；
• 优先使用函数级注释而非大量行内注释，行内注释仅用于仍然不直观的特定步骤；
• 保持注释具体、以行为为中心（behavior-focused）。

这一节的价值在于统一 Agent 生成的代码风格，让 AI 产出的代码同样符合人工维护者的可读性预期。

十、从规范到实践：Agent 在 PierreJS 的完整工作流

综合 AGENTS.md 全文与仓库配置，一个标准的 Agent 开发流程可以归纳为：

1. 初始化环境：export AGENT=1；必要时用moonx <target> --ignore-ci-checks运行 CI-skip 任务（如moonx docs:dev-diffs --ignore-ci-checks）；
2. 加载技能：列出.agents/skills/*/SKILL.md，按需精读相关技能，不加载无关内容；
3. 定位任务：用moon tasks <project>/moon project <project>发现任务，用moonx <project>:<task> -- args执行；
4. 遵守纪律：包操作只用pnpm，依赖版本走pnpm-workspace.yamlcatalog，新包声明 apache-2.0 并携带 LICENSE.md（vendored 代码记入 NOTICE.md）；
5. 放置工件：规划与草稿写入.agents/ignore/plans/与.agents/ignore/specs/；
6. 完成验证：moon run root:format root:lint，加上受影响项目的moonx <project>:typecheck与聚焦测试；纯文档改动仅需 format/lint；
7. 发布前自查：遵循 CONTRIBUTING.md 的 pre-push 流程（格式、lint、受影响 typecheck、聚焦测试），CI 会通过moon ci --include-relations执行受影响图部分。

十一、常用命令速查

说明：以上命令与配置均以当前仓库实际内容为准（工具版本见 .prototools，任务定义见 moon.yml，依赖目录见 pnpm-workspace.yaml）。若版本 pin 或任务配置在后续提交中变化，请以仓库内最新文档与配置为准。