# Repository Guidelines

## 项目结构与模块组织
本仓库是一个 `pnpm` monorepo。核心代码位于 `packages/`：`backend` 为 NestJS API，`frontend` 为 Vue 3 + Vite 前端，`desktop` 为 Tauri 桌面端，`ai-core` 为 AI 能力核心，`shared` 为跨包复用的类型、常量和工具，`skills/node` 为技能运行时。补充文档位于 `docs/`，脚本位于 `scripts/`，环境变量示例见 `.env.example`。`packages/backend/dist`、`packages/desktop/src-tauri/target` 等目录均为生成产物，不应手动修改。

## 构建、测试与开发命令
请在仓库根目录使用 `pnpm`。

- `pnpm dev`：先检查端口，再同时启动 `frontend` 和 `backend`。
- `pnpm dev:all`：同时启动 `frontend`、`backend` 和 `desktop`。
- `pnpm build`：构建 `packages/*` 下的工作区包。
- `pnpm test`：执行各包的 `test` 脚本；当前主要对 `packages/backend` 有效。
- `pnpm lint`：执行已定义的 lint 脚本。
- `pnpm --filter @neta/frontend build`：仅构建指定包。
- `pnpm --dir art-design-pro-main dev`：运行独立的设计原型前端。

## 编码风格与命名约定
仓库根目录的 TypeScript 使用严格模式。前端使用 ESLint、Prettier、Stylelint，统一 2 空格缩进、单引号、无分号。保持现有命名方式：Vue 页面或组件通常使用 `PascalCase` 目录或 `index.vue`；NestJS 模块按 `src/modules/<domain>` 组织；DTO 文件命名使用 `create-*.dto.ts`、`update-*.dto.ts`、`query-*.dto.ts`。新增类型、常量或工具前，优先复用 `packages/shared` 中的已有导出。

## 测试规范
后端测试通过 `pnpm --filter @neta/backend test` 运行，底层框架为 `jest`。当前仓库尚未配置统一的前端测试框架，也没有强制覆盖率门槛，因此新增后端功能时应补充自动化测试；前端或桌面端改动需在 PR 中说明手动验证步骤。新增测试文件优先使用 `*.spec.ts` 命名，并遵循所在包的现有习惯。

## 提交与 Pull Request 规范
提交历史采用带作用域的 Conventional Commits，例如 `feat(frontend): add Skill dialog component`、`docs: add Agent management system design spec`。建议格式为 `type(scope): summary`，常用类型包括 `feat`、`fix`、`docs`。PR 应包含变更说明、影响范围、关联任务或问题、已执行命令（如 `pnpm lint`、`pnpm test`），涉及界面变更时附上截图。

## 协作与回复语言
仓库内的自动化代理、协作者文档和交互说明统一使用中文。无论提问者使用中文、英文或其他语言，回复都应使用中文，除非任务明确要求保留某段原文或代码片段的原始语言。

## 安全与配置提示
建议使用 Node 20 及以上版本，尤其是 `art-design-pro-main` 对版本要求更高。请从 `.env.example` 复制本地配置，禁止提交密钥、日志文件或本地产生的二进制产物。