人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载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. 也就是说它承担三层规则体系中的顶层层级载体作用顶层核心规则AGENTS.md仓库根项目地图、命令、代码规则、文档纪律、任务路由任务级技能.agents/skills/name/SKILL.md特定任务类型的细化规则如 TypeScript、Vitest、UnoCSS 规则目录级覆盖各目录嵌套的AGENTS.md针对特定子系统的额外约束如 i18n、server仓库根目录的 CLAUDE.md 只有一行内容AGENTS.md即引用根 AGENTS.md让 Claude Code 这类工具读取同一份规则。当前仓库实际存在 6 个AGENTS.mdAGENTS.md根packages/i18n/AGENTS.mdpackages/model-driver-mediapipe/AGENTS.mdserver/AGENTS.mdserver/apps/api/AGENTS.mdservices/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——然后以表格形式列出各路径的职能路径内容apps/stage-webWeb 应用使用 Vue Routerapps/stage-tamagotchiElectron 桌面应用apps/stage-pocket移动端应用使用 Vue Router、Capacitor、Kotlin 和 Swiftpackages/stage-uistage-web 与 stage-tamagotchi 共享的业务组件、composables 与 storespackages/stage-ui-threeThree.js 绑定与 Vue 组件packages/stage-sharedstage 包与 stage 应用共享的逻辑packages/stage-pages共享页面基类packages/stage-layouts共享布局包括 stage-web 的设置页布局packages/ui基于 reka-ui 的原语输入框、按钮、布局等业务逻辑最少packages/i18n全部翻译packages/server-runtime、packages/server-sdk、packages/server-sharedservices/与plugins/使用的服务端通道server/apps/api托管的 Hono 资源 API 及其业务域server/apps/auth独立的 Better Auth 与 OIDC 服务server/packages仅后端使用的 schema 与 Node 基础设施包server/dev/caddy本地 Auth 与 API 的边缘路由server/docker-compose.yaml完整的本地后端栈这个划分与 package.json 中的workspaces字段完全对应packages/**、plugins/**、integrations/**、services/**、examples/**、docs/**、engines/**、apps/**、server/**九个 glob 覆盖了全部工作区。根 package 名为proj-airi/rootpackageManager固定为pnpm11.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.vuestage-web和 apps/stage-tamagotchi/src/renderer/layouts/settings.vue。新增设置或 devtools 页面时页面必须带route langyaml 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:devElectron 的 IPC 契约Eventa contracts集中在apps/stage-tamagotchi/src/shared主进程与渲染进程的使用示例在apps/stage-tamagotchi/src/main/services/electron样式配置在根 uno.config.ts现有动画在apps/stage-web/src/stylesCI 流水线在 .github/workflowsLint 规则在 eslint.config.ts。三、命令体系用 pnpm 工作区过滤器把命令限制在单个工作区AGENTS.md 的 Commands 一节规定用 pnpm 工作区过滤器把命令限制到单个工作区package name替换为对应package.json的name字段例如proj-airi/stage-tamagotchi。完整命令表如下目的命令单工作区类型检查pnpm -F package name typecheckstage-tamagotchi 会同时运行tsc和vue-tsc测试单个文件pnpm exec vitest run path测试单个工作区pnpm -F package name exec vitest run测试全部项目pnpm test:run若 Vitest 找不到测试检查vitest.config.ts的include模式Lintpnpm lintESLint 同时负责格式化pnpm lint:fix修复 lint 与格式错误构建单个工作区pnpm -F package name buildstage-tamagotchi 会先 typecheck 再electron-vite build对照 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-tamagotchibrowser 工程、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-hookspre-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 小节规定了一条完整的选型流程通用工具库优先选es-toolkit要加另一个通用工具库如unjs、tinylib系必须先询问用户涉及node:*内建模块、DOM 操作、Vue composables、React hooks、Vite 插件、GitHub Actions 的特性先调研现有库选定库之前请用户决策并帮助其对比选项用户以 spec 驱动工作时候选库以 Markdown 对比表呈现用户指定工具或依赖时先读其文档再检查本仓库的使用方式文档与 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 92025-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 小节给出四条规则使用 Conventional Commits例如feat(package name): add runner reconnect backoff禁止 gitmoji分支命名为username/feat/short-name拉取时用 rebase 合并创建、打开、发布或准备 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并要求开始任务前先读表中所列文件。路由表原文如下任务先读设计、修改或评审 UI 外观与交互DESIGN.md编写、重构或评审 TypeScript 或 Vue 代码enforce-rules-for-typescript编写或调试测试、复现 bug、添加 mock、修复测试导入边界enforce-rules-for-vitest改动 UnoCSS、Vue 样式、UI 组件、动画、图标或颜色模式enforce-rules-for-unocss给 Pinia store 加synced或修改 synced storeenforce-rules-for-pinia-synced编写或修改用户可见字符串、术语表条目packages/i18n/AGENTS.md评审待审 Crowdin 翻译或排查已批准翻译未回库的原因enforce-rules-for-i18n在server/下工作server/AGENTS.mdserver/apps/api下还要读 server/apps/api/AGENTS.md编写文档、代码注释、commit message、PR 与 issue 文本simple-english用保存的 IO trace 分析聊天/语音/音频回合为何慢或失败analyze-io-traces创建或准备 PRcreate-pr在 Web 或 Electron 应用里经文件输入/文件选择器上传本地文件use-agent-browser-with-input-file 与 agent-browserElectron 再读 agent-browser-electron在 stage-web、stage-tamagotchi、stage-pocket 中测试 Live2D、VRM 或 MMD 导入与渲染use-agent-browser-for-airi路由表还点名两个额外拥有独立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.mdagents/*.yamlAgent 元数据references/详细参考 可选scripts/配套脚本的统一结构。部分技能如 pnpm/SKILL.md、unocss/SKILL.md 自带GENERATION.md与大量参考文档属于可从上游同步生成的知识库型技能而enforce-rules-for-*系列则是 AIRI 自研的仓库规则执行器。十一、把规则落回实操一个典型工作流把文档各节串起来在 AIRI 中完成一次桌面端功能开发的完整流程是定位按项目地图确定改动落在apps/stage-tamagotchiElectron 端还是packages/stage-ui共享业务组件必要时对照 package.json 的workspaces与包name字段如proj-airi/stage-tamagotchi路由若是 Vue/TS 代码改动先读 enforce-rules-for-typescript涉及测试则读 enforce-rules-for-vitest涉及进程边界则参考 apps/stage-tamagotchi/src/main/index.ts 的 injeca 注入模式与src/shared中的 Eventa 契约实现共享逻辑下沉packages/文件名 kebab-caseschema 用 Valibot 且贴近消费方workaround 一律带四行式// NOTICE:注释不引入向后兼容守卫验证pnpm -F proj-airi/stage-tamagotchi typecheck、pnpm -F proj-airi/stage-tamagotchi exec vitest run若改动共享包或导出类型追加pnpm typecheck收尾前pnpm lint提交Conventional Commitsfeat(proj-airi/stage-tamagotchi): ...分支username/feat/short-namerebase 后按 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 AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐Omarchy 仓库开发规范全解从 CLAUDE.md 到 AGENTS.md 的任务指南、命令路由与测试体系Omarchy 仓库开发规范全解从 CLAUDE.md 到 AGENTS.md 的任务指南、命令路由与测试体系 本指南围绕 Omarchy一个基于 Arch操作系统人工智能AI AgentProject AIRI 单体仓库 Agent 开发指南技术栈、目录职责、工程命令与 TypeScript 深度规范Project AIRI 单体仓库 Agent 开发指南技术栈、目录职责、工程命令与 TypeScript 深度规范 CLAUDE.md 是 Project人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务AzerothCore 的 AI Agent 协作规范全解AGENTS.md 规则体系与仓库源码级解析AzerothCore 的 AI Agent 协作规范全解AGENTS.md 规则体系与仓库源码级解析 AzerothCore 是一个基于 C 的 MMO后端游戏开发上一篇基于 PostgreSQL 内省自动构建 GraphQL Schemagraphile-build-pg 插件体系实战指南下一篇Forza Mods AIO完整指南3步掌握极限竞速地平线游戏修改终极技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考