Zuiti-Desktop: Instructions file for Codex

AGENTS.md

本文件给后续在本仓库工作的 AI 编码代理使用。目标是让改动贴合 Zuiti 的架构、隐私边界和本地优先状态策略。

项目概览

Zuiti 是一个 Electron + React + TypeScript 桌面宠物应用。渲染进程负责透明悬浮 UI、已校验宠物包渲染、数据驱动 motion 执行和锚点道具叠加；主进程负责系统能力、LLM 调用、上下文快照、active pet package 加载校验、vision、memory、behavior、motion plan 校验和 SVG prop skills。

核心数据流：

1. 用户输入、周期触发或窗口切换进入主进程行为决策。
2. 主进程从 ENABLED_PET 指定的 pet_resources/pets/<pet_id>/ 读取 active pet 包，并把 visionSummary、memoryText、skillIndex、motion tool prompt 和短期对话窗口放入稳定快照。
3. textAgent 基于稳定快照输出 dialogue、mood_tag、可选 motion_plan 和可选 prop_intent。
4. 主进程按 active pet manifest 校验 motion plan；skills 模块从 active pet 的 enabled 道具 skill 中选择，或生成、校验、审核新的 SVG prop skill。
5. 主进程通过 IPC 把只读宠物渲染包、mood、对白和 activity 发给 renderer。

主回复 prompt 的稳定顺序是：

SOUL -> motion tool prompt -> memory -> skill index -> recent window -> current event

目录地图

• src/main/：Electron 主进程、LLM provider、vision、memory、skills、behavior、IPC 注册。
• src/preload/：安全暴露给 renderer 的 window.zuiti API。
• src/renderer/src/：React UI、Zustand store、IPC wiring、桌宠和气泡组件。
• src/shared/types.ts：跨进程共享类型与 IPC channel 常量。
• pet_resources/：主进程加载的宠物包根目录，存放内置宠物骨架、部件 SVG、表情、motion tools、prompt、memory、skills 和 PET_SKELETON_STANDARD.md。
• resources/：Electron 图标和构建资源，不放宠物骨架资源。
• docs/：架构与模块文档。改动模块行为时同步更新对应文档。
• tests/：Node test runner 单元测试，使用 scripts/register-ts.cjs 注册 TS 源码。
• pet_resources/pets/default-cat/memory/SOUL.md：默认猫人格源文件，应纳入版本控制。
• pet_resources/pets/default-cat/memory/memory.example.md：长期记忆示例。
• pet_resources/pets/default-cat/skills/example-soft-wave/：可提交的示例 skill 包。

运行命令

常用命令：

npm install
npm run dev
npm run test:unit
npm run typecheck
npm run lint
npm run build

提交前优先运行：

npm run test:unit
npm run typecheck
npm run lint

涉及打包、Electron 配置或跨进程入口时，再运行：

npm run build

开发环境要求见 docs/modules/development.md。ENABLED_PET=default-cat 选择 active pet 包；LLM_PROVIDER=mock 可离线启动基础流程；接入真实模型时需要配置 .env，但不要提交 .env。

编码约定

• 使用 TypeScript，遵守现有 ESLint、Prettier 和 electron-vite 结构。
• 优先复用本仓库已有模块边界，不要把主进程职责塞进 renderer。
• 跨进程协议统一从 src/shared/types.ts 扩展；新增 IPC channel 时同步更新 preload API 和 renderer 类型。
• renderer 只通过 window.zuiti 与主进程交互，不直接使用 Node/Electron 主进程能力。
• 新增 UI 状态优先放在现有 renderer store / hook 结构中，保持 PetView、BubbleLayer、SettingPanel 职责清晰。
• 宠物包资源放在 pet_resources/pets/<pet_id>/，并遵守 pet_resources/PET_SKELETON_STANDARD.md；不要把骨架资源放进 Electron 的 resources/。
• renderer 不把整个 pet_resources/ 作为 publicDir；memory 和 runtime skills 只由主进程读写，renderer 只能通过 window.zuiti.petPackageGet() 获取校验后的只读渲染包。
• 骨架动作只暴露 active pet manifest 里的受限语义 motion tool；新增 tool 时更新该 pet 的 manifest、prompt、mood fallback 和测试，不要在系统代码里硬编码 tool 名称。
• 主进程后台任务应避免阻塞用户输入路径；文本回复优先使用最近完成的稳定快照。
• 注释保持简短，只解释不明显的安全、隐私或异步时序原因。