mirror of
https://github.com/RhenCloud/Cloud-Home.git
synced 2026-06-11 00:24:56 +08:00
97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 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
|
||
- 优先保证开发环境可复现，避免依赖本机隐式状态。
|
||
- 常用命令：
|
||
|
||
```bash
|
||
nix develop
|
||
bun install
|
||
bun run dev
|
||
bun run build
|
||
bun run lint
|
||
```
|
||
|
||
## DevOps
|
||
|
||
- Docker 已支持，构建入口见 [Dockerfile](Dockerfile)，本地联动服务见 [docker-compose.yml](docker-compose.yml)。默认使用 `docker compose up --build` 启动整套环境。
|
||
- Nix flake 已支持，开发环境以 [flake.nix](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 风格指南](https://siiway.org/zh/dev/ts-style.html)
|
||
- 默认使用 `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。
|
||
- 修改后优先运行：
|
||
|
||
```bash
|
||
bun run lint
|
||
bun run typecheck
|
||
bun run build
|
||
```
|
||
|
||
- 如果某个检查失败，先修复根因，再继续扩大修改。
|
||
|
||
## 维护原则
|
||
|
||
- 保持本文件短小、可执行、面向 AI Agent。
|
||
- 只记录仓库中不容易通过扫描直接发现、但会影响正确性的约定。
|
||
- 细节说明优先链接到其他文档，不在此处重复展开。
|