Nexus/AGENTS.md

Nexus 6.0 — Agent 入口（薄 stub）

长文 SSOT: docs/project/nexus-functional-development-guide.md + 附录
会话接续: docs/project/AI-HANDOFF-2026-06-03.md
文档总索引: docs/README.md

项目概要

Nexus：2000+ 子机运维平台。后端 FastAPI + MySQL + Redis；前端 Vue 3 + Vuetify 4 + TypeScript SPA（15 页，frontend/src/pages/）；构建输出 web/app/；安装向导 web/app/install.html。

本地开发

docker compose up -d mysql redis
bash scripts/start-dev.sh          # API :8600
bash scripts/local_verify.sh     # L2b
cd frontend && npm run dev         # :3000/app/

路径见 linux-dev-paths.md。

Git（本机 + Gitea）

• 改完代码：git commit 后 bash scripts/git-push.sh 推到 Gitea（凭据 deploy/nexus-1panel.secrets.sh）；大仓库可用 scripts/git-push-axs-full.sh。
• 本地 commit 仍用于回滚；不要漏推 Gitea（用户约定 2026-07-09）。
• .env、SECRETS.md、*.pem、deploy/nexus-1panel.secrets.sh 已在 .gitignore，勿提交。
• 改代码仍写 docs/changelog/YYYY-MM-DD-*.md（≥10 行）。

强制约束

• 完美实现：.cursor/rules/perfect-implementation.mdc
• 安全 / 后端 / 前端：.cursor/rules/nexus-*.mdc
• 改代码必 docs/changelog/YYYY-MM-DD-*.md（≥10 行）
• 测试由 Agent 完成；用户只做终验

不可改

API_KEY · SECRET_KEY · ENCRYPTION_KEY · DATABASE_URL

部署

默认 本机 rsync → SSH 生产机；代码先 push Gitea 再部署（见上节 Git）：

bash deploy/pre_deploy_check.sh
bash scripts/git-push.sh              # 或 git-push-axs-full.sh
bash deploy/deploy-production.sh   # rsync + Docker upgrade --skip-git + 前端

可选：NEXUS_DEPLOY_VIA_GIT=1 恢复远程 git pull。

详情见功能指南 §17–18。

归档文档

历史审计合并卷：docs/archive/README.md

代码地图（Agent 先读这里，勿全库搜）

server/main.py          # 路由挂载入口
server/config.py        # 配置（.env + settings 表）
server/api/*.py         # HTTP/WebSocket 路由（按模块拆分）
server/application/     # 业务 services
server/infrastructure/  # DB / Redis / SSH / Telegram
server/domain/models/   # SQLAlchemy ORM
frontend/src/pages/     # Vue 页面（15 页 SPA）
frontend/src/router/    # Hash 路由 #/
frontend/src/api/       # 前端 API 客户端
frontend/e2e/           # Playwright 验收
tests/test_*.py         # pytest
docs/project/           # 功能/部署 SSOT
deploy/                 # 生产部署脚本
scripts/                # 本地验证、MCP、门控
.cursor/mcp.json        # mysql-mcp

问题 → 文件（常见锚点）

问什么	先看
某 API 怎么实现	server/main.py 找 router → server/api/<模块>.py
服务器列表/搜索/exec	server/api/servers.py, server/api/scripts.py
认证/JWT	server/api/auth.py, server/api/dependencies.py
Agent 心跳/安装	server/api/agent.py
WebSSH/终端	server/api/webssh.py, server/api/terminal.py
同步/文件/搜索	server/api/sync_v2.py, files.py, search.py
设置/审计/告警	server/api/settings.py
前端某页 UI	frontend/src/router/index.ts → frontend/src/pages/
MySQL MCP	.cursor/mcp.json, scripts/linux_mcp_mysql.sh
本地开发路径	docs/project/linux-dev-paths.md
14 页/API 全览	docs/project/nexus-functional-development-guide.md §9–10

探索规则（省 token）

详见 .cursor/rules/agent-exploration.mdc。要点：先地图再 Grep（带 path）→ Read ≤5 个文件 → 停止。