# Repository Guidelines

## 1. 远程安全

- 服务器 `1.13.22.133` 有两套系统：
  - 固定资产：`/opt/equipment-management`，容器前缀 `equipment-*`
  - 摄影借还：`/opt/shebeiguanli`，容器前缀 `shebeiguanli-*`
- 任何远程操作只能针对固定资产系统。
- 不得进入 `/opt/shebeiguanli`，不得修改、停止、重建、删除 `shebeiguanli-*` 容器，也不得碰它的数据库、数据卷、配置。
- 部署、查日志、查库前，先确认目标路径、容器名、数据库名都属于固定资产系统。
- 远程自动化默认优先使用 `plink`。

## 2. 协作方式

- 本项目默认采用官方 `lead + 可复用子代理编排`。
- 用户只提目标、问题、期望效果，不需要做技术判断。
- 主代理默认承担 `lead`：负责理解需求、拆任务、判断是否启用子代理、整合结果、统一汇报。
- 主代理在 `spawn_agent` 前，默认先执行一次 `list_agents`，优先检查当前是否已有可复用的同职责子代理。
- 本项目默认团队分工：
  - `frontend-worker`：使用官方 `worker`，只负责前端文件。
  - `backend-worker`：使用官方 `worker`，只负责后端 / 数据库相关文件。
  - `review-explorer`：使用官方 `explorer`，只负责代码审查、找问题、提风险，不直接改代码。
- 子代理按职责复用，不必每次换一套；但仍遵守官方能力边界，不自定义内建类型。
- 默认固定复用以上 3 个命名子代理；同职责任务优先继续派发给现有同名子代理，不要为相同职责反复新开线程。
- 默认同职责只保留 1 个活跃子代理：
  - 前端任务优先发给 `frontend-worker`
  - 后端任务优先发给 `backend-worker`
  - 审查、排查风险优先发给 `review-explorer`
- 只有以下情况才允许新开同职责子代理：
  - 当前不存在该职责子代理
  - 现有子代理已经关闭或不可用
  - 任务明确需要并行，且写入范围完全不重叠
- 给已存在子代理继续分派工作时，优先使用 `assign_task` 或 `send_message`，不要为了“清空上下文”而随手重建。
- 同一个功能周期内，尽量保留子代理连续上下文；不要刚做完一个相邻子任务就关闭再重开，避免重复解释背景。
- 只有在该子代理本轮职责已经完成、后续短期内不再需要，或继续保留会明显增加干扰时，才执行 `close_agent`。
- 如果现有同职责子代理正在处理相关任务，主代理应先判断是否可以复用同一线程继续推进；不要因为等待而机械式再开一个同类子代理。
- 子代理任务描述必须写清楚文件归属和边界，避免前后端、审查与实现之间职责漂移。
- 不魔改为“常驻团队系统”；子代理只用官方支持的能力边界。
- 本项目内所有子代理默认统一使用 `gpt-5.4`。
- 所有 `worker` 类子代理固定使用 `gpt-5.4 + xhigh` 思考等级。
- `explorer` / 其他子代理思考等级按任务复杂度选择，但最低不得低于 `medium`。
- 只有涉及线上、真实数据、密钥账号、证书、付费资源、不可逆操作时才暂停确认。

## 3. 前端规则

- 前端改动前先读：`D:\AI Code\GuDingZiChan\前端视觉规范.md`
- 视觉方向固定为：极简、统一、深色主题。
- 优先使用：`btn-primary`、`btn-secondary`、`btn-icon`、`input`、`select`、`card`、`panel`、`page-header`、`page-meta`、`section-title`、`field-stack`、`field-grid`
- 禁止继续使用旧类：`btn-apple-*`、`input-apple`、`card-apple`、`text-apple-*`、`bg-apple-*`、`text-system-label-*`、`bg-system-gray-*`、`border-system-gray-*`、`rounded-apple`、`surface-note`、`page-subtitle`、`section-subtitle`
- 页面间距优先统一用 `gap-4` / `gap-6`，并同时检查桌面端和移动端效果。

## 4. 改动与验证

- 前端优先改：`frontend/src/views/`、`frontend/src/components/`、`frontend/src/api/`、`frontend/src/stores/`、`frontend/src/router/`
- 后端优先改：`backend/src/routes/`、`backend/src/controllers/`
- 数据库 / 部署 / 认证优先改：`backend/prisma/`、`backend/src/utils/`、`docker-compose.yml`、`Dockerfile`、`deploy.sh`
- 主要使用 TypeScript，保持现有 2 空格缩进；先读上下文，尽量复用现有实现，不做无关改动。
- 默认至少执行：
  - `cd frontend && npm run build`
  - `cd backend && npm run build`
- 涉及接口改动时，额外检查相关页面流程与 `GET /api/health`
- 涉及 Prisma 或表结构改动时，额外执行：`cd backend && npm run prisma:generate`
- 不提交真实密码、数据库连接串或生产地址；相关配置优先走环境变量。