axi-pet

Imported from MoseLu/axi-pet (AGENTS.md). Install upstream with npx skills add MoseLu/axi-pet. Copyright stays with the author.

Axi Pet — 项目根级 AGENTS

本文件是 Axi Pet 仓库根级 AGENTS，是进入本仓库的 agent 第一站。 axi-pet 是 zh-primary 项目：本文件（中文）为权威源；英文镜像见 AGENTS.en.md（即根级 AGENTS.md 的英文原文，来自上游 proj-airi 移植）。 axi-pet 是大型 pnpm monorepo，从上游 proj-airi（moeru-ai/airi）fork 移植。包命名空间统一为 @proj-airi/*（沿用上游，不可改为 @axi-pet/*），仓库目录名 axi-pet 仅是工作区定位名。 任何对 apps/、packages/、plugins/、services/、engines/ 的修改必须先读本文件 + 该子包/子应用自带的 AGENTS.md / CLAUDE.md（如 apps/server/CLAUDE.md、services/computer-use-mcp/AGENTS.md）。

Scope

• 适用对象：所有 agent（Codex、Cursor、自动化扫描器、文档巡检子代理）首次接触 /Volumes/code/workspace/projects/axi-pet 时。
• 不适用对象：纯构建产物（node_modules/、pnpm-lock.yaml、dist/、turbo 缓存、.venv-local-stt）、社区/媒体子模块（bucket/、outputs/）、patches/ 中的 pnpm patchfile。
• 阅读顺序：本文件 → README.md（英文主源，本仓库尚未在根级建立 README.zh-CN.md，docs/README.zh-CN.md 仅为 Netlify 文档站镜像）→ AGENTS.en.md（如需英文）→ 目标子包/子应用的本地 AGENTS.md / CLAUDE.md（如 apps/server/CLAUDE.md、services/computer-use-mcp/AGENTS.md）→ 内部治理文档（见下表）。

Project Boundary

Axi Pet 是 「LLM 驱动的虚拟角色容器（Neuro-sama 复刻）」 大型 monorepo，覆盖桌面（Electron）、Web、移动（Capacitor）、后端服务、MCP 工具、Bot 适配等 5+ 形态。最小闭环为 聊天输入 → Provider 路由 → Stage 渲染 → Live2D / VRM / Spine / Three.js 呈现。

不要把 bucket/、outputs/、.venv-local-stt/、__pycache__/、node_modules/、.turbo/、.cache/ 当作可写范围。

Authoritative Sources

优先级冲突时：本文件（中文权威）> AGENTS.en.md（英文镜像）> 各子包/子应用本地 AGENTS.md / CLAUDE.md > docs/ai/context/ > 个人记忆。

Cross-Project Boundary

• 包命名空间：所有 @proj-airi/* 名称沿用上游 moeru-ai/airi，禁止改为 @axi-pet/*（会破坏与上游 sync、发布链路、Discord/Telegram 已有用户认知）。
• 上游同步：本仓库 fork 自 moeru-ai/airi，与上游的差异仅在工作区层面的 governance / docs / secrets 治理镜像（参见 app/docs/ 同源文档结构）；业务代码改回上游需走 PR。
• 可被消费：通过 workspace graph（workspace-project consumers axi-pet）查询本仓库作为 stage 容器、Live2D/VRM 渲染、Provider 协议、Bot 适配、computer-use MCP 工具被哪些项目消费；不要在业务代码里硬编码跨项目绝对路径。
• 可消费：docs/ai/context/ 中的 UI 组件 / 验证规约可被 Axi Pet 内部任何子包 import；packages/plugin-protocol / packages/plugin-sdk 对外暴露插件契约。
• 黑名单文件形态（HIGH 风险，禁止在 commit / 文档 / 聊天记录中以原文出现 IP、API key、个人路径、个人邮箱）：
  • docs/desktop-lane-status.md（仅列路径，禁止引用其内容；含个人 macOS 路径与桌面 lane 真实状态）
  • donor/BRANCH_STRATEGY.md 与 donor/ 下任何捐赠方分支策略文档（仅列路径）
  • 真实部署 / 凭据信息统一走 ~/credentials/axi-pet.env（待建，不写入仓库）

Verification

最小验证序列（按改动范围缩放）：

# 单一包 typecheck + 单测
pnpm -F <package.json name> typecheck
pnpm -F <package.json name> exec vitest run

# 根级全量（慢，覆盖已注册项目）
pnpm test:run            # vitest run + vishot + stage-ui

# Lint
pnpm lint                # moeru-lint .
pnpm lint:fix

# Build（按目标过滤）
pnpm -F @proj-airi/stage-tamagotchi build
pnpm -F @proj-airi/stage-web build
pnpm -F @proj-airi/server build

补充可选：

pnpm build:packages          # turbo 跨 packages/**
pnpm build:apps              # turbo 跨 apps/**
pnpm build:engines           # 跨 engines/**
pnpm -F @proj-airi/docs run dev   # Netlify 文档站本地预览

修改 packages/stage-ui/** 或 packages/ui/** → 至少 pnpm -F <pkg> typecheck + pnpm -F <pkg> exec vitest run 通过。 修改 apps/server/** → 至少 pnpm -F @proj-airi/server typecheck + 单测通过。 修改 services/computer-use-mcp/** → 至少 pnpm -F @proj-airi/computer-use-mcp typecheck，并遵循该包 AGENTS.md 中「GPT-5.5 Controller + Spark Worker Pool」的协作策略。 修改 docs/ai/context/** → 不需构建，但需保持与对应代码包同步。

House Rules

• 不要把 OMX 内部状态（.omx/metrics.json、.omx/state/*.json）写入 commit。
• 不要把 .omx/ 整体加入版本控制（仅允许 .omx/config/ 之类的显式配置例外）。
• 不要在没有 owner 显式指令的情况下合并到 main、推送标签、删除远程分支、发布正式 release（AIRI 上游由 moeru-ai/airi 团队发布）。
• 不要在结构化日志打印完整 API Key / Discord Token / Telegram Token / WeChat 凭证 / OpenAI/Anthropic key。
• 不要修改或重写 patches/ 中的 pnpm patch（除非该依赖已更新版本且 pnpm-workspace.yaml 的 patchedDependencies 同步调整）。
• 要保持 AGENTS.md（中文权威）与 AGENTS.en.md（英文镜像，来自上游 proj-airi）的同步演进，PR 描述中注明 i18n 是否同步。
• 要在 docs/ai/context/ui-components.md 同步 packages/ui/ 的组件变更（自动维护规约）。
• 要在改动跨包契约（@proj-airi/plugin-protocol、@proj-airi/server-sdk、@proj-airi/stage-shared）前先查 workspace-project consumers axi-pet。
• 要使用 UnoCSS（而非 Tailwind），uno.config.ts 是唯一 shortcut / 规则 / 插件登记点。
• 要使用 @moeru/eventa（Eventa）做 IPC/RPC 契约，@moeru/std 的 errorMessageFrom(error) 做错误归一化，@moeru/injeca 做 DI。

反向链接清单（关键内部文档）

• 根级门面：README.md · AGENTS.md（= AGENTS.en.md，英文主源）· AGENTS.zh-CN.md · CLAUDE.md · CLAUDE.zh-CN.md · LICENSE
• 内部治理（6 份中文镜像已建）：
  • apps/server/README.zh-CN.md（英文：apps/server/README.md）—— Hono 后端中文镜像
  • services/computer-use-mcp/AGENTS.zh-CN.md（英文：services/computer-use-mcp/AGENTS.md）—— 确定性执行底座中文镜像
  • AGENTS.zh-CN.md（英文：AGENTS.md）—— monorepo 跨包贡献者中文镜像
  • CLAUDE.zh-CN.md（英文：CLAUDE.md）—— CLAUDE 入口中文镜像（@AGENTS.md 指向）
• 子包 Agent 备注：packages/model-driver-mediapipe/AGENTS.md（单人动捕，FP 风格）
• AI 上下文：docs/ai/context/ui-components.md（reka-ui 组件 API）· docs/ai/context/verification-automation.md
• 方案归档：docs/solutions/developer-experience/agent-browser-mock-api-verification.md · docs/plans/2026-05-30-001-feat-voice-pack-tts-pool-lb-plan.md · docs/brainstorms/2026-05-30-voice-pack-requirements.md
• 项目门面：docs/README.{md,zh-CN.md,ja-JP.md,ko-KR.md,ru-RU.md,vi.md,fr.md}（Netlify 文档站）· docs/wechat.md（微信群）· docs/privacy.md · docs/terms-of-use.md
• 文档清单：docs/project-docs.manifest.json（axi-pet 主清单，状态 partial）

专有名标记：@proj-airi/*（包命名空间，不可改）· proj-airi / moeru-ai/airi（上游）· Discord / Telegram / WeChat / QQ（社群）· Spark / GPT-5.5 / GPT-5.4-mini / GPT-5.3-codex / GPT-4.1（computer-use-mcp Agent 协作角色）。

最后更新：2026-06-07 — 根级 AGENTS 首版（zh-primary），由 workspace-docs-gap 子代理 W8 落地。