Cloud-Home/AGENTS.md

AGENTS.md

本文件用于指导 AI Coding Agents 在本仓库内高效、安全、一致地工作。优先遵循现有实现与仓库约定；除非必要，不要引入新架构。

项目概览

• 这是一个 Nuxt.js + TypeScript + Tailwind CSS + Bun 项目。
• 默认使用 Bun 作为包管理器与运行时。
• 优先采用 SSR 与 Nuxt conventions。
• 优先使用 Composition API。
• TypeScript 必须保持 strict mode。

环境与工具链

• 优先通过 nix develop 或 nix shell 补全缺失工具，不要假设系统已全局安装 node、npm、pnpm。
• 如果缺少开发工具，优先补充 flake.nix，或补充 shell.nix / devShell。
• 默认使用 Bun：
  • 安装依赖：bun install
  • 运行脚本：bun run <script>
  • 避免使用 npm、pnpm、yarn
• 优先保证开发环境可复现，避免依赖本机隐式状态。
• 常用命令：

nix develop
bun install
bun run dev
bun run build
bun run lint

DevOps

• Docker 已支持，构建入口见 Dockerfile，本地联动服务见 docker-compose.yml。默认使用 docker compose up --build 启动整套环境。
• Nix flake 已支持，开发环境以 flake.nix 为准；优先通过 nix develop 进入可复现 shell，再执行 Bun 命令。
• GitHub Actions 已配置 CI，检查顺序与本地一致：安装依赖、bun run lint、bun run typecheck、bun run build。
• 自动格式化使用 bun run format，修改代码后优先执行，保证 Prettier 与 Tailwind 排版一致。
• 自动 lint 与自动 typecheck 依赖仓库脚本和 CI；本地修改后优先跑 bun run lint 和 bun run typecheck，避免把问题留到流水线。

TypeScript 规范

• 参考规范：TypeScript 风格指南
• 默认使用 const，禁止 var。
• 避免 any；必要时先收窄类型，再使用显式断言。
• 优先使用 type，仅在需要扩展或声明合并时使用 interface。
• 不要使用 enum，优先使用 literal union。
• 避免大型类，优先函数式与组合式设计。
• 公共 API 必须显式声明返回类型。
• 文件名使用 kebab-case。
• composables 使用 useXxx 命名。
• Vue 组件使用 PascalCase 命名。
• 避免默认导出，Nuxt 特殊约定除外。
• 保持 import 顺序稳定，依赖 ESLint + Prettier 自动格式化。

Nuxt / Vue 约定

• composables 放在 /composables。
• server routes 放在 /server/api。
• shared types 放在 /types。
• 通用工具函数放在 /utils。
• 页面逻辑保持轻量，复杂业务下沉到 composables / server / utils。
• 避免在 components 中写复杂业务逻辑。
• 优先使用 useFetch、useAsyncData 与 Nuxt auto imports。
• Tailwind class 要保持可读性，避免过长 class chain。
• 优先使用语义化 wrapper components，而不是把样式逻辑散落在页面里。

AI Agent 行为规则

• 修改代码前先阅读现有实现与相邻调用点。
• 修改前优先搜索已有 utility / composable / server helper，避免重复造轮子。
• 优先遵循现有代码风格，不要强行引入新的架构风格。
• 最小化修改范围，优先做局部且可验证的改动。
• 不要随意增加依赖；新增依赖必须说明原因。
• 不要破坏 SSR、hydration 或 Nuxt 自动导入约定。
• 不要绕过 TypeScript 类型系统。
• 不要通过关闭 lint、typecheck 或 build 来“修复”问题。

测试与质量

• 所有改动应尽量通过 typecheck、lint、build。
• 修改后优先运行：

bun run lint
bun run typecheck
bun run build

• 如果某个检查失败，先修复根因，再继续扩大修改。

维护原则

• 保持本文件短小、可执行、面向 AI Agent。
• 只记录仓库中不容易通过扫描直接发现、但会影响正确性的约定。
• 细节说明优先链接到其他文档，不在此处重复展开。