Project AIRI 单体仓库 Agent 开发指南技术栈、目录职责、工程命令与 TypeScript 深度规范【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiCLAUDE.md 是 Project AIRImoeru-ai/airi为 AI Agent 与人类贡献者准备的入口文档其全部内容通过第一行的AGENTS.md引用指向仓库根目录的 AGENTS.md。本篇以该 Agent 指南为主体完整梳理 AIRI 跨 Web / Electron / Capacitor 多端 monorepo 的技术栈选型、目录职责划分、pnpm 工作区命令、强制仓库技能Skills、i18n 术语表工作流以及从命名、注释、回退优先级到 Pinia 跨窗口同步的一整套 TypeScript 工程规范并结合仓库实际源码与配置逐项佐证帮助你在动手改 AIRI 任何模块前建立正确的心智地图。技术栈按「表面Surface」划分AGENTS.md 将项目按运行端surface划分技术栈这与仓库apps/目录的三个应用一一对应端目录技术栈桌面端Desktopapps/stage-tamagotchiElectron、Vue、Vite、TypeScript、Pinia、VueUse、EventaIPC/RPC、UnoCSS、Vitest、ESLintWeb 端apps/stage-webVue 3 Vue Router、Vite、TypeScript、Pinia、VueUse、UnoCSS、Vitest、ESLint后端为 WIP移动端Mobileapps/stage-pocket在 Web 端栈基础上叠加 Kotlin、Swift、Capacitor共享层UI / Shared Packages的核心分工packages/stage-uistage-web 与 stage-tamagotchi 共享的核心业务组件、composables、stores是「stage 工作的重心」packages/stage-ui-threeThree.js 绑定 Vue 组件当前仓库中还存在stage-ui-live2d、stage-ui-mmd、stage-ui-spine、stage-ui-tachie等平行渲染端包packages/stage-ui-pixi文档标注为「计划中的 Pixi 绑定」从当前仓库目录列表看该目录尚未落盘属于规划项packages/stage-shared跨 stage-ui、stage-ui-three、stage-web、stage-tamagotchi 的共享逻辑packages/ui基于 reka-ui 构建的标准化基础组件输入框、textarea、按钮、布局业务逻辑最少packages/i18n集中式翻译服务端通道packages/server-runtime、packages/server-sdk、packages/server-shared为services/与plugins/供能文档还记录了crates/旧 Tauri 桌面端为 Legacy——从当前仓库顶层目录看该目录已不再可见当前桌面端由 Electron 实现。目录结构与职责边界托管后端server/server/apps/apiHono 资源 API 与业务域server/apps/auth独立的 Better Auth 与 OIDC 服务server/packages后端私有的 schema 与 Node 基础设施包仓库内实际可见server/packages/auth-shared、server/packages/server-sdk-sharedserver/dev/caddy仅本地使用的 Auth/API 边缘路由路由文件为 Caddyfiledocker-compose.yaml完整的本地后端栈编排。应用层apps/stage-webcomposables/stores 位于src/composables、src/stores页面位于src/pagesdevtools 位于src/pages/devtools路由配置经由apps/stage-web/vite.config.tsstage-tamagotchi渲染进程页面位于src/renderer/pagesdevtools 位于src/renderer/pages/devtools设置页布局为 settings.vue路由配置经由apps/stage-tamagotchi/electron.vite.config.ts设置/devtools 路由依赖route langyaml块中的meta: layout: settings声明且要求相应注册路由与图标对应桌面端 settings.vue 布局 与 Web 端的apps/stage-web/src/layouts/settings.vue共享页面基座packages/stage-pages。Stage UI 内部结构packages/stage-ui/srcProvidersstores/providers.ts与stores/providers/标准化 provider 定义Modulesstores/modules/AIRI 编排构建块。从源码实际内容可以印证该目录包含airi-card.ts、artistry.ts、consciousness.ts、gaming-minecraft.ts、gaming-factorio.ts、hearing.ts、speech.ts等模块及其配套测试如 artistry.test.ts与项目「Minecraft / Factorio / 实时语音」的核心能力直接对应Composablescomposables/面向业务的 Vue 助手函数Componentscomponents/其中components/scenarios/存放页面/用例特定部件Storiespackages/stage-ui/stories histoire.config.ts如components/misc/Button.story.vue。IPCEventa与依赖注入injecaIPC/Eventa一律使用moeru/eventa做类型安全、框架/运行时无关的 IPC/RPC。契约集中定义例如apps/stage-tamagotchi/src/shared该目录实际包含desktop-overlay-heartbeat.ts、mcp-config.ts、model-settings-runtime.ts、spotlight-shortcut.ts等共享契约main/renderer 集成模式参考apps/stage-tamagotchi/src/main/services/electronDI服务 / Electron 模块 / 插件 / 前端统一使用injeca组合模式见 main 入口样式UnoCSS 配置位于根目录 uno.config.ts现有动画参考apps/stage-web/src/styles优先 UnoCSS 而非 Tailwind若需统一样式应在uno.config.ts中增加 shortcuts / rules / plugins构建 / CI / LintCI 流水线位于.github/workflows仓库内可见ci.yml、autofix.yaml、crowdin-cron-sync.yml、crowdin-manual-upload.yml等。AGENTS.md 写作时 lint 规则文件名为eslint.config.js当前仓库实际为 eslint.config.ts且根package.json的lint脚本实际执行moeru-lint .以仓库现状为准。关键路径索引什么在哪里AGENTS.md 的「Key Path Index」章节给出了全仓库的速查表核心条目如下已按仓库根目录相对路径给出AGENTS.md本指南本体packages/stage-ui核心 stage 业务组件 / composables / stores含src/stores/providers.ts、src/stores/modules/、src/composables/、src/components/与src/components/scenarios/packages/stage-ui-three、packages/stage-shared、packages/ui、packages/i18n见上文分工托管后端server/apps/api、server/apps/auth、server/packages、server/dev本地工具服务端通道packages/server-runtime、packages/server-sdk、packages/server-shared页面packages/stage-pages共享基座apps/stage-web/src/pages与apps/stage-tamagotchi/src/renderer/pagesdevtools 在各应用.../pages/devtools下路由配置apps/stage-web/vite.config.ts、apps/stage-tamagotchi/electron.vite.config.tsIPC/Eventa 契约与示例apps/stage-tamagotchi/src/shared、apps/stage-tamagotchi/src/main/services/electronDI 示例main/index.tsinjeca样式uno.config.ts、apps/stage-web/src/styles文档中提到的docs/solutions/用于按类别记录过往修复与流程经验YAML frontmatter 含module、tags、problem_type在实现、调试或验证相关领域时应参考从当前仓库目录列表看该目录暂未出现属于规划/阶段性记录位置。开发命令pnpm 工作区过滤器AGENTS.md 要求用 pnpm workspace filters 限定任务范围过滤器参数为目标工作区的package.json name如proj-airi/stage-tamagotchi、proj-airi/stage-web、proj-airi/stage-ui。类型检查pnpm -F package.json name typecheck # 例 pnpm -F proj-airi/stage-tamagotchi typecheck # 执行 tsc vue-tsc单元测试Vitest# 定向单文件 pnpm exec vitest run apps/stage-tamagotchi/src/renderer/stores/tools/builtin/widgets.test.ts # 工作区级 pnpm -F proj-airi/stage-tamagotchi exec vitest run # 根级 pnpm test:run根级test:run会跨所有已注册项目运行全部测试。若提示「未找到测试」需检查 vitest.config.ts 的 include 模式。从源码可以确认根 vitest.config.ts 通过test.projects显式注册了各测试工程server/apps/auth、server/apps/api、apps/ui-server-auth、apps/stage-tamagotchi/vitest.node.config.ts、packages/cap-vite、packages/ccc、packages/core-agent、packages/i18n、packages/better-ws、packages/plugin-sdk、packages/plugin-sdk-tamagotchi、packages/scenarios-stage-tamagotchi-browser、packages/scenarios-stage-tamagotchi-electron、packages/server-runtime、packages/server-sdk、packages/stage-shared、packages/vitest-plugin-fakemic——每个 app/package 也可拥有自己的vitest.config.ts。这与根package.json中test:run脚本串联test-stage-tamagotchi:run、test-audio-pipelines-transcribe:run、test-ui:run的写法互相印证。Lintpnpm lint # 规则moeru-lint . pnpm lint:fix # 格式化同样由 ESLint 处理构建pnpm -F package.json name build # 例 pnpm -F proj-airi/stage-tamagotchi build # typecheck electron-vite build根级pnpm build则等价于turbo run build -F./packages/* -F./apps/* -F./server/**见根 package.json。强制仓库技能Enforced Repository SkillsAGENTS.md「Enforced Repository Skills」一节规定特定工作类型必须调用对应的仓库本地技能skill。这些 SKILL.md 文件在.agents/skills/下均可验证存在触发场景必须使用的技能位置测试、Vitest、回归复现、mock、测试导入边界工作enforce-rules-for-vitest.agents/skills/enforce-rules-for-vitest/SKILL.mdUnoCSS、Vue 样式、UI 组件、动画、图标、color-modeenforce-rules-for-unocss.agents/skills/enforce-rules-for-unocss/SKILL.mdWeb/Electron 中通过 HTML input、动态 input 或文件选择器上传本地文件$use-agent-browser-with-input-fileElectron 目标再加$agent-browser、$agent-browser-electron.agents/skills/use-agent-browser-with-input-file/SKILL.mdAIRI Live2D / VRM / MMD 跨端stage-web、stage-tamagotchi、stage-pocket导入与渲染测试$use-agent-browser-for-airi内部复用文件上传技能并补充 AIRI 特定路由、状态准备、格式行为与渲染器验证.agents/skills/use-agent-browser-for-airi/SKILL.md编辑、撰写、重构、重写代码以及提交 issue / PR / 文档 / 注释$simple-english.agents/skills/simple-english/SKILL.md创建 / 发布 PR仓库本地create-pr技能为用户可见变更编排use-vishot与匹配的运行时变体并在 PR 正文上传前后截图.agents/skills/create-pr/SKILL.md开发实践Development Practices保持清晰的模块边界共享逻辑放入packages/运行时入口保持精简把重逻辑移入 services/modules使用 Valibot 做 schema 校验schema 贴近其消费者需要结构化 IPC/RPC 契约时使用 Eventamoeru/eventa用moeru/std的errorMessageFrom(error)提取错误信息替代error instanceof Error ? error.message : String(error)手工模式需要默认值时配合?? fallback不添加向后兼容保护。若确需扩展支持应写 refactor 文档并通过 shell 命令另起一个 Codex 或 Claude Code 实例、以清晰指令和预期重构后形态完成实现小范围重构则逐步step by step进行涉及node:*内建模块、DOM 操作、Vue composables、React hooks、Vite 插件或 GitHub Actions 工作流的新需求先深度调研现有库/开源模块不要自行选择通用工具库如es-toolkit、unjs 工具、tinylib 小工具必须先请用户选择并协助判断若用户在做 spec 驱动开发用简洁的 Markdown 对比表列出候选项。TypeScript / IPC / 工具约定AGENTS.md「TypeScript / IPC / Tools」一节是全仓库的硬约束JSON Schema 必须 provider 合规显式type: object、声明 required 字段、避免无界 recordElectron 与后端相关包使用injeca管理依赖除非扩展浏览器 API避免新增类层次类更难以 mock/测试Eventa 契约集中化所有事件走moeru/eventa类型从拥有该契约的模块/包导入不要为使用更窄子集而在本地重声明外部/公共契约也不要当原始无副作用类型源可用时经本地运行时组装模块转发类型导入相对导入、动态导入与再导出中省略 TS/JS 源扩展名写./module而非./module.ts/./module.js仅当运行时或资产格式要求时保留扩展名不要直接改tsconfig.json来消灭导入/类型错误。先排查编译行为、package.json的exports声明、类型声明以及依赖是否暴露预期的 browser/node 入口Node-only 与 browser-only 类型经同一条导入链混合时把类型声明拆到中性类型文件、运行时模块保持环境特定不要仅为拿类型而导入带副作用模块的值错误/缺失 export 引发的报错先追溯完整导入链与副作用链再改叶子处导入优先修包/模块 exports 与所属边界而非加本地绕行导入把循环导入当设计问题先重审所有权、模块边界、共享类型/纯助手是否需要移动若无法有把握解决先向用户求方向用户要求使用某个工具/依赖时先查 Context7 文档再用搜索工具检查本仓库中的实际用法多个名称返回且区分不明时请用户确认文档与 typecheck 结果冲突时检查node_modules下依赖源码定位根因并修类型/修 bug。i18n 与术语表Glossary工作流翻译的增改统一放在packages/i18n避免 i18n 逻辑散落在各 app/package默认只改英文源 locale 与开发者当前使用的 locale。其他 locale 文件由 Crowdin 集成管理——直接本地编辑可能在下次 Crowdin 上传/同步后被未翻译的源内容覆盖未被明确要求时不要编辑其他 locale术语表源文件为 packages/i18n/glossary/terms.yaml给出每个产品概念的核准英文术语。pnpm -F proj-airi/i18n glossary:build对应 packages/i18n/package.json 中glossary:build: tsx glossary/build-tbx.ts生成 Crowdin 导入的 TBX 文件字段映射由schema.ts记录。从terms.yaml头部注释可以确认该仓库拥有英文源语言的所有权其余 8 种语言由 Crowdin 拥有翻译术语经由 PR 回到packages/i18n/glossary/translations/写或改用户可见字符串前先读terms.yaml使用其中给出的术语不要编辑packages/i18n/glossary/translations/下次 Crowdin 下载会覆盖它术语取自界面查文档是为了确认一个术语而不是寻找一个术语。何时加术语——当它能防止两类失败之一时才加只看源字符串的译者会选错词两位译者选了不同的词、且两个词都正确。何时不加它是代码——被翻译的控制 token、JSON key、文件名、包名会破坏应用且不报错是具通常含义的普通英文词如 Speed、Volume其各部分都已有词条且整体含义不超出各部分之和如 VRM model只有一个功能使用它、且最多两位译者可能分歧。但译者可能搞错的罕见词应保留——原文以Tachie全文件仅出现两次却是最强词条为例。terms.yaml不存理由因为每个字段都必须映射到 TBX 元素理由写在 PR 里。定义用一句话描述「事物」而非「词」否定性规则放note句子短而主动因为多数译者不以英语为第一语言。可读性、命名与注释规范命名所有文件名用 kebab-case让模块边界提供上下文除非符号跨越了会丢失该上下文的边界避免在符号中重复包、产品、协议或传输名函数按领域操作命名而非实现层已解析的领域概念用名词转换/副作用用动词若一个符号需要多个所有权限定词才能看懂重新审视模块边界或引入更清晰的领域概念。注释注释只解释代码无法清晰表达的信息意图、约束、所有权、不变量、优先级、生命周期、顺序、副作用、协议形态、非显然的兜底。禁止复述名字、类型或可见操作的注释。契约注释应解释生产者与消费者之间的关系先解释值为什么存在再解释代码如何表示它若不同取值选择不同控制流/UI 路径描述每个可观察结果值跨模块/组件边界时指出消费者如何应用它表示细节单位、坐标系、阈值、钳制、源 API 字段放在行为之后背景证据浏览器行为、issue 链接、调查历史、移除条件放在契约之后。名称、类型与周边代码已表达完整契约时省略注释。实现注释放在其解释的分支、计算、转换或副作用旁边计算密集代码中非显然的坐标系、单位、换算、钳制、舍入、聚合、优先级应紧邻相关中间值或分支。优先用更清晰的命名、类型与结构化状态替代补偿隐藏/编码概念的注释。移动代码时保留仍准确的注释删除不再描述当前行为的注释。调查型注释写成短段落背景、观察到的失败、为何显然修复不足、选定的修复及其移除条件/引用。标记约定// TODO:后续工作// REVIEW:需要他人意见的关注点// NOTICE:变通方案、魔法值、外部约束及其他重要非显然上下文。回退Fallback与优先级超过两个来源的回退链必须显式声明优先级若回退来源代表不同 schema 版本、兼容行为、特异性级别或用户/系统覆盖每个非主分支必须解释其存在原因与优先级原因任何分支非显然时避免用嵌套三元表达回退链用命名中间变量或if/else if块让注释能贴近相关分支不要拿新对象/数组当随手回退value ?? {}、value ?? []、value || {}、value || []每次都创建新引用绝不在响应式 getter、computed、watcher 源或 Pinia state 投影中内联对象/数组回退——新引用会引发伪变更、watcher 循环与状态广播不可变空回退合理时复用稳定的模块级值需要时 freeze??仅当null/undefined表示值缺失时使用||仅当false、0、空串也应选中回退时使用不要静默保留向后兼容回退临时回退标// NOTICE:并写移除条件永久性回退作为受支持策略文档化而不是叫它 legacy在非显然的领域/协议代码中回退返回空串、陈旧值、缓存值、默认值或被忽略结果时在返回点/分支处解释为何安全。有状态与协议代码实现协议、状态机、生命周期、缓存、请求/响应流、事件路由、watcher、session、cookie 或清理序列的代码须在实现附近文档化状态模型用命名或就近注释区分持久化配置、发现的文件系统状态、运行时加载状态、缓存状态、session/cookie 状态、watcher 状态、外部副作用看似状态迁移的方法setEnabled、load、unload、dispose、start、stop、refresh等在不显然时须说清它改变哪个状态匹配事件/响应时显式文档化相关键与隔离规则requestId、sessionId、ownerExtensionId、bindingId、路由命名空间、源窗口事件处理器必须让「被忽略的事件」可理解因路由不匹配、所有者不匹配、过期请求 id、已销毁生命周期或错误源而忽略时原因应在代码中可见或被命名谓词捕获请求/响应流在生产者与消费者附近定义或命名 envelope 形态文档化超时、关闭、卸载、销毁、发布失败时挂起请求的命运跨所有者的清理保持顺序可见并解释顺序为何重要返回快照/回退值/陈旧值/缓存值时在返回点文档化新鲜度语义watcher、事件监听器、异步后台工作须明确所有权与关闭行为什么启动/停止工作、是否允许重复启动、卸载/销毁时在途工作如何处置。Pinia 跨窗口同步pinia-plugin-synced把pinia-plugin-synced当作快照复制 leader 路由 RPC——它不在渲染进程间共享 Vue ref仅给需要跨窗口所有权的 store 加synced同步最小可序列化真源状态state: true在每次本地变更后发送整 store 提案瞬态/高频状态放未同步 storestate、action 参数与 action 结果必须支持structuredClonecomputed、查询状态、运行时客户端、控制器、pending promise 与组件状态留在同步 state 之外远端快照会触发本地 Vue watcher——对同步状态的 watcher 不得直接写同步状态watcher 可调用同步 action 来强制 leader 拥有的不变量但必须 await 该 actionaction 必须幂等因为每个渲染进程都可能观察到同一快照跨字段不变量在显式 action 内、状态提交前强制不要用 watcher 修复被复制的状态setup store 中返回的每个函数都是 Pinia action只读投影用 computed 或纯助手synced.actions只列 leader 拥有的副作用 action必须异步且调用方必须 await未列出的 action 在调用者渲染进程执行其变更在state: true时成为整状态提案同步与持久化保持为独立边界给持久化的同步状态唯一显式持久化所有者不要为同步状态添加双向持久化 composable 或 storage-event 监听器用显式持久化命令每个 Electron 渲染进程显式设置领导模式工具窗/最小窗必须是follower-only同步变更需加多窗口回归测试远端快照不得产生本地同步状态提案watcher 调同步 action 时验证重复调用收敛且无重复副作用。模块设计原则深模块优于浅模块模块应隐藏一个有意义的决策——策略、持久化边界、协议/schema 契约、调度语义、模型 prompt 契约、领域不变量或生命周期关注点不要仅按执行顺序切分代码模块边界应表示可独立理解的稳定职责内聚的领域流程在出现被证明的拆分压力前保持在一起200–400 行的内聚模块优于互相传递同一 context/options 的多个浅模块运行时/浏览器 API 与拥有状态、生命周期或稳定领域边界的实质业务模块优先用类纯转换与局部助手用函数依赖注入只用于外部边界数据库、模型运行时、队列、缓存、文件系统、网络、时钟、环境、feature gate内部只调兄弟助手或转发参数的函数不要引入依赖对象新建createXService/XDependencies前验证X是否带来策略、校验、状态、重试/错误处理、IO 边界或可复用抽象否则保持私有助手或内联避免createXService({ yService })这类X不增加任何策略/校验/状态/抽象的透传服务特例靠近其影响的分支助手若操作编码 key、所有权、文件路径、路由或协议形态数据其不变量应在结构、命名或就近文档中显式化通过稳定公共行为测试不要为让私有实现可 mock 而新建导出、依赖包或包装服务可复用领域契约与渲染/构建逻辑保留在拥有该领域的 package 中运行时入口只做依赖装配与调用边界。PR 与工作流程约定创建、打开、发布或准备 PR 时始终使用仓库本地create-pr技能对用户可见变更它会编排use-vishot与匹配的运行时变体并在 PR 正文上传前后截图作为 GitHub user asset对应 .agents/skills/create-pr/SKILL.md用 rebase 拉取分支命名username/feat/short-name提交信息清晰禁止 gitmoji总结变更、测试方式命令与后续工作改进你碰到的 legacy 代码避免一次性one-off模式变更保持收敛使用工作区过滤器pnpm -F package script为每个packages/与apps/条目维护结构化README.md它做什么、怎么用、何时用、何时不要用完成任务后始终运行pnpm type-check与pnpm lint提交信息用 Conventional Commits如feat(package name): add runner reconnect backoff规划或编写新工具/函数前先搜索仓库内部已有实现若逻辑可成为共享工具主动向用户/开发者提议共享方案。TypeScript 编码规范全 monorepo 适用AGENTS.md 为全仓库 TypeScript 代码给出了一组可核查的硬规范其中几个格式模板值得原样继承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).JSDoc 调用栈图——runner / CLI 入口必须带/** ... */JSDoc 并含清晰 ASCII 调用栈图按需使用{link ...}引用服务端编排器仅在澄清稳定架构边界时加图/** * ... * * Call stack: * * collectEvalEntries (../runner) * - {link createRunnerSchedule} * - {link createMatrixCombinations} * - {link VievalScheduledTask}[] */Normalizer 文档格式——导出的归一化函数输出、格式、文件名、值不含配置默认值归一化必须带example展示代表性输入输出/** * Normalizes target. * * example * normalizeTarget(ExampleInput) * // example-output */回归测试根因块格式——回归测试在适用时// ROOT CAUSE: // // If XXXX, some XXX case happens. // This happens because where line ... // // before-patch behavior/code // // We fixed this by XXX, XXX, XXX. // after-patch behavior/code其余要点实现期间不为 spec 创建提交已实现模块尽量用 Vitest 验证行为与通过测试优先类型泛型禁用any仅在几乎无法避免且类型无法安全修复时才用as unknown as targetJSDoc 面向公共 API、包级导出、共享架构边界与非显然导出成员只文档化签名无法表达的契约细节假设、副作用、生命周期、返回保证不要仅为满足测试或文档规则而导出助手函数平凡助手、局部投影、透传函数不加 JSDoc固定分节模板避免复述名字签名导出的测试助手/非显然测试 fixture 在澄清用法时加example普通describe/it/expect*不挂 JSDoc 或example导出接口/类型别名顶层 JSDoc 聚焦类型表示什么细粒度语义放字段上泛型参数用param有默认值的每个 option 加default非显然的 OS/exec/process/参数/网络/文件/目录处理就近解释约束或目的创建工具函数时优先es-toolkit注意此条与前述「不得自行选择通用工具库」的约束并存前者针对工具创建优先级、后者针对引入新库的决策流程须按 AGENTS.md 原文语境理解错误处理优先moeru/std模式一次性或两次使用的常量留在使用处附近通常 imports 后顶部并配/** ... */解释原因不要全塞进常量区有默认值的可配置 option 优先用moeru/std合并函数、把默认值定义为带文档对象而非宽泛独立常量重试/退避/限额值不要用单个独立常量覆盖一切避免硬编码 Unix/macOS/Windows 路径字面量优先 path-safe 数组参数与跨平台处理测试不要只做 smoke——先复现 bug/失败再打补丁并保留解释根因与修复理由的注释不要用分隔符把模块切成「section」内聚私有助手分组或仅在拥有独立职责时拆模块不要仅为减少嵌套、行数或制造测试接缝拆文件不过度使用表驱动风格多数情况下表数组内联并直接.map(...)优先早返回、函数保持简单为可读性限制嵌套可以但不为降缩进引入透传助手或浅模块。可读性评审检查清单评审复杂 TypeScript 模块时按 AGENTS.md 末尾的 checklist 逐项核对拥有的状态、外部副作用、生命周期迁移、清理、新鲜度语义能否在不追踪多个邻居文件的情况下被识别协议 envelope、相关键、隔离规则、回退优先级是否在其决策点显式化模块与助手边界是否隐藏了有意义的策略而非仅仅转发上下文或遮蔽特例注释是否在不复述名字、类型、可见操作的前提下解释了相关代码旁非显然的决策小结如何在仓库中落地这份指南CLAUDE.md 的全部价值在于把 AGENTS.md 这份 Agent 指南设为贡献者无论人或 AI的统一契约按 surface 识别技术栈、按 Key Path Index 定位模块、用pnpm -F过滤命令收敛变更范围、按.agents/skills/强制技能覆盖测试/样式/浏览器自动化/PR 等专项工作、并按 i18n 术语表、注释标记、NOTICE/ROOT CAUSE 块、Pinia 跨窗口同步与模块设计原则完成代码。配合根 vitest.config.ts 的工程注册表、uno.config.ts 的样式入口、server/docker-compose.yaml 的本地后端栈与.github/workflows下的 CI 流水线可以完整复现 AIRI 多端 monorepo 的开发、验证与交付闭环。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考