企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

AIRI 是一个由十余个应用、五十余个内部包组成的 pnpm 单仓（monorepo），其根目录的 AGENTS.md 不是普通的项目说明，而是一套为 AI 编码 Agent 设计的核心工作规则：它定义了仓库的项目地图、可用的 pnpm 工作区命令、代码与依赖规范、文档提交纪律，以及"任务到技能文件"的路由表。本文以该文档为骨架，结合仓库中的真实源码与配置逐节展开，读完你可以理解如何在这样一个大型单仓中定位模块、执行单工作区的 typecheck 与测试、遵循// NOTICE:与依赖注入约定，并按任务类型读取对应的技能（skills）与嵌套AGENTS.md文件。

一、这份文档在 AIRI 中的定位

AIRI 根 AGENTS.md 开篇声明了其作用范围："This file gives the core rules for all work in themoeru-ai/airimonorepo. Skills and nestedAGENTS.mdfiles give the rules for specific tasks." 也就是说，它承担三层规则体系中的顶层：

仓库根目录的 CLAUDE.md 只有一行内容@AGENTS.md，即引用根 AGENTS.md，让 Claude Code 这类工具读取同一份规则。当前仓库实际存在 6 个AGENTS.md：

• AGENTS.md（根）
• packages/i18n/AGENTS.md
• packages/model-driver-mediapipe/AGENTS.md
• server/AGENTS.md
• server/apps/api/AGENTS.md
• services/computer-use-mcp/AGENTS.md

其中根文档的"任务路由"一节明确要求：在server/下工作时先读 server/AGENTS.md，在server/apps/api下工作时还要追加读 server/apps/api/AGENTS.md。这种"根规则 + 目录覆盖"的分层结构，是 AIRI 管理跨 Web / Electron / 移动端 / 后端多端代码的关键设计。

二、项目地图：一张表定位整个单仓

AGENTS.md 的 "Project Map" 一节是理解 AIRI 架构的入口。它首先给出技术栈基线——所有应用统一使用 Vue 3、Vite、TypeScript、Pinia、VueUse、UnoCSS、Vitest 和 ESLint——然后以表格形式列出各路径的职能：

这个划分与 package.json 中的workspaces字段完全对应：packages/**、plugins/**、integrations/**、services/**、examples/**、docs/**、engines/**、apps/**、server/**九个 glob 覆盖了全部工作区。根 package 名为@proj-airi/root，packageManager固定为pnpm@11.24.0，这解释了后文所有命令为何都以pnpm -F过滤工作区。

项目地图还列出了一组"关键文件与目录"，这些是跨模块开发的固定落点：

• 页面位于apps/stage-web/src/pages和apps/stage-tamagotchi/src/renderer/pages，开发调试页面（devtools）在各自目录的devtools子文件夹中；
• 路由配置在 apps/stage-web/vite.config.ts 和 apps/stage-tamagotchi/electron.vite.config.ts；
• 设置页布局分别是 packages/stage-layouts/src/layouts/settings.vue（stage-web）和 apps/stage-tamagotchi/src/renderer/layouts/settings.vue。新增设置或 devtools 页面时，页面必须带<route lang="yaml"> meta: layout: settings </route>声明，并在设置布局中登记路由与图标——settings.vue 中通过route.meta的 computed 读取该声明；
• packages/stage-ui/src内，provider 定义在stores/providers/，编排模块在stores/modules/；业务 composables 在packages/stage-ui/src/composables/，业务组件在packages/stage-ui/src/components/；只服务单一页面或用例的组件放入packages/stage-ui/src/components/scenarios/；
• 组件 Stories 在packages/stage-ui/stories，配合 packages/stage-ui/histoire.config.ts 运行（pnpm dev:ui即story:dev）；
• Electron 的 IPC 契约（Eventa contracts）集中在apps/stage-tamagotchi/src/shared，主进程与渲染进程的使用示例在apps/stage-tamagotchi/src/main/services/electron；
• 样式配置在根 uno.config.ts，现有动画在apps/stage-web/src/styles；
• CI 流水线在 .github/workflows，Lint 规则在 eslint.config.ts。

三、命令体系：用 pnpm 工作区过滤器把命令限制在单个工作区

AGENTS.md 的 "Commands" 一节规定：用 pnpm 工作区过滤器把命令限制到单个工作区，<package name>替换为对应package.json的name字段，例如@proj-airi/stage-tamagotchi。完整命令表如下：

对照 package.json 可以确认每条命令的真实落点：

• lint脚本是moeru-lint .，lint:fix是moeru-lint --fix .。仓库使用moeru-lint封装 ESLint，规则定义在根 eslint.config.ts（依赖@antfu/eslint-config、@moeru/eslint-config、eslint-plugin-format、eslint-plugin-oxlint等）。"ESLint 也负责格式化"这条规则意味着仓库没有单独的 Prettier 步骤；
• 根目录 vitest.config.ts 以 Vitestprojects方式聚合了server/apps/auth、server/apps/api、apps/ui-server-auth、packages/stage-shared、packages/stage-ui-live2d等几十个测试工程，这就是pnpm test:run在"Vitest 找不到测试"时要检查include模式的原因——测试工程按子工程注册，而不是靠根级 glob 全量扫描；
• 根级test:run实际是一条链：vitest run之后依次追加 stage-tamagotchi（browser 工程）、stage-web 的 VRM 位置 browser 测试、stage-pages、stage-ui、stage-ui-live2d 的专属vitest run，与根 package.json 中test-stage-tamagotchi:run、test-stage-web:run等脚本一一对应；
• 修改共享包或导出类型后，文档要求追加运行根级pnpm typecheck，其脚本是turbo run typecheck -F="./packages/*" -F="./apps/*" -F="./server/**" -F="./services/*" -F="./docs"，即基于 Turborepo 的全仓类型检查。

此外，package.json 中还有若干与文档工作流直接相关的脚本可作为上下文：postinstall会执行simple-git-hooks并构建包，build使用turbo run build覆盖packages/*、apps/*、server/**，up使用taze批量更新依赖。

四、变更范围与验证纪律（Scope and Checks）

文档 "Scope and Checks" 一节规定了对每次变更的验证义务，核心要点：

• 每次变更保持在任务范围内；在改动的函数、组件或测试内部，顺手修正违反现行规则的代码，但不要仅为"改进"而改动其他代码；
• 不要添加一次性模式。写新工具函数前先搜索仓库中是否已有内部实现；
• 新逻辑若可成为共享工具，应先向用户提出共享方案；小重构分步进行；
• 任务完成后，对每个改动过的工作区运行 typecheck 和相关测试；改动共享包或导出类型时，追加运行根级pnpm typecheck；收尾前必须运行pnpm lint；
• 只汇报实际运行过的检查，给出每条命令及其结果；最后总结变更内容、运行过的命令与后续工作。

仓库的 git 钩子把"先 lint 再提交"固化了下来：package.json 配置了simple-git-hooks，pre-commit执行pnpm nano-staged，而nano-staged对所有暂存文件运行moeru-lint --fix。也就是说，文档中"Runpnpm lintbefore you finish"的纪律，与本地钩子和 .github/workflows 中的 CI 检查（如autofix.yaml、ci.yml）形成了从本地到 CI 的三级闭环。

五、代码规则：从文件命名到// NOTICE:注释格式

"Code Rules" 一节是全文技术密度最高的部分，逐条对应仓库中的真实实现。

5.1 模块边界与命名

• 共享逻辑放packages/，保持模块边界清晰；所有文件名使用 kebab-case。观察仓库可见这一约定严格执行，例如apps/stage-tamagotchi/src/shared/desktop-overlay-heartbeat.ts、packages/i18n/glossary/build-tbx.ts；
• 禁止any，优先类型泛型；仅在类型无法安全修复时使用as unknown as <Type>；
• 相对导入、动态导入与 re-export 中省略 TS/JS 源码扩展名，写./module而不是./module.ts；
• 不允许修改tsconfig.json来掩盖导入或类型错误，必须找到根因修复；
• 循环导入被视为设计问题：先重新考虑所有权与模块边界，无法自信解决时询问用户。

5.2 IPC 与依赖注入：Eventa 与 injeca

两条关于进程边界的规则在桌面端入口有直接对应实现：

IPC 规则：所有 IPC、RPC 与跨进程事件必须使用@moeru/eventa，契约定义在单一中心位置。以apps/stage-tamagotchi/src/shared为例，该目录包含eventa/、desktop-overlay-heartbeat.ts、mcp-config.ts、spotlight-shortcut.ts等契约文件；主进程侧的调用示例分布在apps/stage-tamagotchi/src/main/services/electron及main/services/airi/下的各模块（onboarding、godot-stage、apple-vision 等目录均引用了@moeru/eventa）。

依赖注入规则：DI 只用于外部边界——数据库、模型运行时、队列、缓存、文件系统、网络、时钟、环境变量与特性开关，且使用injeca库；仅调用同级辅助函数或转发参数的内部函数不要引入依赖对象。apps/stage-tamagotchi/src/main/index.ts 正是文档指定的 DI 参考实现：它导入createLoggLogger, injeca, lifecycle，然后以injeca.provide(...)逐一注册外部边界服务，例如：

const appConfig = injeca.provide('configs:app', () => createGlobalAppConfig()) const electronApp = injeca.provide('host:electron:app', () => app) const serverChannel = injeca.provide('modules:channel-server', { ... }) const airiHttpServer = injeca.provide('modules:airi-http-server', { ... }) const mcpManager = injeca.provide('modules:mcp-manager', { ... }) const ioTraceRecording = injeca.provide('services:io-trace-recording', { ... })

可以看到命名约定按configs:、host:、modules:、services:、windows:、libs:前缀区分服务类别，与"DI 只用于外部边界"的规则一致：被注入的有自动更新器、i18n、服务端通道、Godot 舞台管理器、Apple 语音/视觉服务、MCP 管理器、IO trace 录制等，没有纯内部工具函数。

5.3 结构偏好与校验

• 面向运行时或浏览器 API 时优先用类；拥有状态、生命周期或稳定领域边界的较重业务模块也优先用类；纯转换与局部辅助函数优先用函数；
• Valibot 用于 schema 校验，schema 要贴近其消费方定义。这一点在后端被强化：server/AGENTS.md 规定凡跨越信任边界的服务端数据（HTTP、Pub/Sub 消息、队列任务、WebSocket 事件、数据库 JSON、provider 响应）一律用 Valibot 校验，schema 由契约所有者就近定义，且 TS 类型必须从 Valibot schema 推断、不得在 interface 中重复契约。仓库内如 packages/stage-ui/src/services/characters.ts 等文件确实引入了 Valibot；
• 错误信息统一使用@moeru/std的errorMessageFrom(error)，需要默认值时补?? 'fallback'。packages/stage-ui/src/stores/voice-controls.ts等文件即是使用示例。

5.4// NOTICE:注释：可追溯的 workaround 协议

文档要求每个 workaround 都必须以固定的// NOTICE:注释块标记，格式为四行结构：

// NOTICE: // Why this workaround is needed. // Root cause summary. // Source/context (file, issue, URL, or node_modules reference). // Removal condition (when it can be safely deleted).

这个协议的价值在于把"临时补丁"变成了可审计对象：注释必须同时回答为什么需要、根因是什么、证据在哪、何时可删除。仓库中已有大量遵循此格式的实例（如 integrations/minecraft/src/main.ts、integrations/vscode/vscode-airi/scripts/shared.ts 等文件均含// NOTICE:块），说明该约定已是实际执行的仓库纪律而非纸面规则。

六、向后兼容与依赖管理两条专项规则

6.1 向后兼容：默认不加兼容层

文档 "Backward Compatibility" 小节的原则非常明确：

• 不要添加向后兼容守卫；
• 若旧调用方或旧数据需要延长支持期，先写一份说明目标形态的重构文档，然后从 shell 另开一个 Codex 或 Claude Code 会话去执行重构；
• 兼容回退必须长期保留时，用// NOTICE:标注并写明移除条件；若回退是永久的，则作为受支持策略记录在案，不得称为 legacy；
• 嵌套AGENTS.md可以为公共契约覆盖此规则，但必须指名被覆盖的根规则。

从源码结构看，这条规则与仓库"激进演进、单版本维护"的风格一致：AIRI 以0.12.0-beta.5这类 beta 版本快速迭代，各端通过bump.config.ts与 release 相关 workflow 管理发版，而非在代码中保留多层兼容路径。

6.2 依赖选型流程

"Dependencies" 小节规定了一条完整的选型流程：

1. 通用工具库优先选es-toolkit；要加另一个通用工具库（如unjs、tinylib系）必须先询问用户；
2. 涉及node:*内建模块、DOM 操作、Vue composables、React hooks、Vite 插件、GitHub Actions 的特性，先调研现有库；
3. 选定库之前请用户决策，并帮助其对比选项；用户以 spec 驱动工作时，候选库以 Markdown 对比表呈现；
4. 用户指定工具或依赖时，先读其文档，再检查本仓库的使用方式；
5. 文档与 typecheck 结果冲突时，深入node_modules中的依赖源码找原因。

仓库本身对es-toolkit的使用可作佐证：如 packages/stage-ui-three/src/composables/render-target.ts、packages/stage-ui/src/stores/providers/provider.ts 等文件均从es-toolkit引入工具函数，与"优先 es-toolkit"的规则吻合。

七、文档纪律：ADR 位置、提交捆绑与 i18n 边界

"Documentation" 小节对文档变更施加了四条可执行约束：

• 项目级与客户端 ADR 放 docs/ai/adr/，托管后端 ADR 放 server/docs/ai/adr/ 并遵守 server/AGENTS.md 的 ADR 规则；
• 文档变更必须与它描述的代码位于同一提交或同一 PR（适用于 ADR、README 与组件参考）；
• Agent 配置变更必须单独提交或单独 PR——Agent 配置包括AGENTS.md、CLAUDE.md、skills 与.github/copilot-instructions.md；
• 每个packages/与apps/入口保留结构化README.md，说明它做什么、怎么用、何时用、何时不用；
• 所有翻译放packages/i18n，默认只改英文源语言和自己的语言；其他语言由 Crowdin 管理，本地编辑会在下次 Crowdin 同步中被覆盖；不得在他人语言文件中放英文占位文本。

后端的 ADR 要求在 server/AGENTS.md 中进一步细化：实现类 ADR 必须包含模块依赖图、受影响文件树与时序图，并写明决策、范围、非目标与测试计划；accepted状态只能在决策被确认之后保留。根 docs/ai/adr/ 下现存2026-09-22-sherpaw-model-assets.md、2026-09-24-presence-bubble-in-canvas.md等按日期命名的 ADR，与上述"文档与代码同 PR"的规则互相印证。

i18n 的目录级规则在 packages/i18n/AGENTS.md 中有完整展开：术语表 packages/i18n/glossary/terms.yaml 给出每个产品概念的批准英文术语，pnpm -F @proj-airi/i18n glossary:build生成 Crowdin 导入用的 TBX 文件，packages/i18n/glossary/schema.ts 定义字段，且glossary/translations/目录禁止手改（下次 Crowdin 下载会替换它）。CI 侧由 .github/workflows 中的crowdin-cron-sync.yml、crowdin-manual-upload.yml、i18n-locale-check.yml等流水线承接这条同步链路。

八、写作规范：以 ASD-STE100 简化技术英语约束所有文本

"Writing" 一节把 .agents/skills/simple-english/SKILL.md 技能应用到所有人类可读文本——文档、代码注释、commit message、PR 与 issue 文本，且不适用于代码、标识符、命令或引用的错误信息。

该技能基于ASD-STE100 Issue 9（2025-01-15）标准（航空航天维护手册使用的受控语言），强制 53 条规则、20/25 词句长限制、一词一义、主动语态、条件先于命令等约束。SKILL.md 明确写出其目标："Write for that tired reader. Each sentence must survive one read."（为一个疲倦的读者写作，每句话必须一次读完就能理解）。根 AGENTS.md 还列出本仓库最常违反的五条规则：

• 不写 "should"、"may"、"might"、"could"、"would"；写 "must" 或 "can"，或直接陈述事实；
• 不使用分号，拆成两个句子；
• 写 "for example" 与 "that is"，不写 "e.g."、"i.e."、"etc."；
• 指令不超过 20 词，描述不超过 25 词；
• 条件句放在命令之前。

值得注意的是，AGENTS.md 全文本身正是这套规则的示范文本——短句、无 "should/may"、无分号、条件先于命令。这套规范对中文协作的启示是：面向多语言读者与非母语工程师的文本，应优先消除模糊情态动词与超长从句。

九、Git 与 Pull Request 纪律

"Git and Pull Requests" 小节给出四条规则：

1. 使用 Conventional Commits，例如feat(<package name>): add runner reconnect backoff，禁止 gitmoji；
2. 分支命名为username/feat/short-name；
3. 拉取时用 rebase 合并；
4. 创建、打开、发布或准备 PR 时，使用.agents/skills/create-pr/SKILL.md技能，该技能同时覆盖视觉证据（截图）与评审跟进流程。

配套的 create-pr 技能目录包含SKILL.md、agents/与references/子目录，说明它带附属资源；而 .github/workflows 中的pr-review-labels.yml、pr-triage-dispatch.yml、pr-review-event.yml等流水线，则是 PR 纪律在 CI 侧的自动化执行者。

十、任务路由表：从任务类型到技能文件的分发机制

AGENTS.md 最后一节 "Task Routing" 是整个文档的枢纽。它声明 skills 统一存放在.agents/skills/<name>/SKILL.md，并要求开始任务前先读表中所列文件。路由表原文如下：

路由表还点名两个额外拥有独立AGENTS.md的目录，要求进入前先读：packages/model-driver-mediapipe/与services/computer-use-mcp/（即 packages/model-driver-mediapipe/AGENTS.md 与 services/computer-use-mcp/AGENTS.md）。

从源码结构看，.agents/skills 目录远比路由表所列更庞大：除路由表直接引用的技能外，还有eventa、pinia、pnpm、tsdown、unocss、vue、vue-best-practices、xsai、release-note-writer、use-vishot-*系列（含 Web/Electron/Capacitor/输入文件等变体）、upload-github-attachment等约 26 个技能目录，且多数技能采用SKILL.md+agents/*.yaml（Agent 元数据）+references/（详细参考）+ 可选scripts/（配套脚本）的统一结构。部分技能如 pnpm/SKILL.md、unocss/SKILL.md 自带GENERATION.md与大量参考文档，属于可从上游同步生成的"知识库型"技能，而enforce-rules-for-*系列则是 AIRI 自研的仓库规则执行器。

十一、把规则落回实操：一个典型工作流

把文档各节串起来，在 AIRI 中完成一次桌面端功能开发的完整流程是：

1. 定位：按项目地图确定改动落在apps/stage-tamagotchi（Electron 端）还是packages/stage-ui（共享业务组件），必要时对照 package.json 的workspaces与包name字段（如@proj-airi/stage-tamagotchi）；
2. 路由：若是 Vue/TS 代码改动，先读 enforce-rules-for-typescript；涉及测试则读 enforce-rules-for-vitest；涉及进程边界则参考 apps/stage-tamagotchi/src/main/index.ts 的 injeca 注入模式与src/shared中的 Eventa 契约；
3. 实现：共享逻辑下沉packages/，文件名 kebab-case，schema 用 Valibot 且贴近消费方，workaround 一律带四行式// NOTICE:注释，不引入向后兼容守卫；
4. 验证：pnpm -F @proj-airi/stage-tamagotchi typecheck、pnpm -F @proj-airi/stage-tamagotchi exec vitest run；若改动共享包或导出类型，追加pnpm typecheck；收尾前pnpm lint；
5. 提交：Conventional Commits（feat(@proj-airi/stage-tamagotchi): ...），分支username/feat/short-name，rebase 后按 create-pr 技能准备 PR，文档与代码同 PR 提交，Agent 配置（AGENTS.md/CLAUDE.md/skills）单独提交。

小结

根 AGENTS.md 用约 160 行英文（严格遵循 ASD-STE100 简化英语规则）为整个 AIRI 单仓建立了一套可执行的协作契约：项目地图回答"代码在哪"，命令表回答"如何验证"，代码规则与// NOTICE:协议回答"代码怎么写"，文档与 Git 纪律回答"如何交付"，任务路由表则把每类任务分发到.agents/skills下的专项技能或目录级AGENTS.md。对阅读者而言，这份文档既是新贡献者的导航图，也是评估一个大型多端 monorepo 如何同时管理人类与 AI Agent 协作的样本：规则全部指向仓库内真实存在的文件（如 eslint.config.ts、vitest.config.ts、server/AGENTS.md、packages/i18n/AGENTS.md），每一条约束都能在源码、配置或 CI 中找到对应的执行载体。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手