From 73fdcafb81facc991353527a588f7ff1c4122d17 Mon Sep 17 00:00:00 2001 From: Your Name Date: Mon, 1 Jun 2026 11:58:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=95=B4=E4=BA=A4=E6=8E=A5?= =?UTF-8?q?=E6=96=87=E4=BB=B6=20(15=E7=AB=A0=E8=8A=82=20+=20Cursor?= =?UTF-8?q?=E6=8F=90=E7=A4=BA=E8=AF=8D=20+=20=E9=83=A8=E7=BD=B2=E9=97=AE?= =?UTF-8?q?=E9=A2=98)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/handoff-2026-06-01.md | 173 ++++++++++++++++++++++++++----------- 1 file changed, 123 insertions(+), 50 deletions(-) diff --git a/docs/handoff-2026-06-01.md b/docs/handoff-2026-06-01.md index 0faada11..69968a08 100644 --- a/docs/handoff-2026-06-01.md +++ b/docs/handoff-2026-06-01.md @@ -2,7 +2,64 @@ > 生成时间: 2026-06-01 > 当前分支: main (与 origin/main 同步) -> 最后 commit: a20cefc docs: 审计+changelog 全站bug审查修复 +> 最后 commit: 91d0d41 docs: 添加 .cursorrules 供 Cursor 接管 + +--- + +## 零、Cursor 接管第一步 + +### 1. 已为你准备好的文件 + +| 文件 | 位置 | 作用 | +|------|------|------| +| **Cursor Rules** | `.cursorrules`（项目根目录）| 强制规则、部署流程、文件速查 — Cursor 自动读取 | +| **MCP 配置** | `C:\Users\uzuma\.cursor\mcp.json` | nexus/playwright/gitea/fetch/context7 — 已写好 | +| **项目规则** | `CLAUDE.md`（项目根目录）| 完整项目记忆、决策、实现状态、部署常遇问题 | +| **交接文件** | `docs/handoff-2026-06-01.md` | 本文件 | + +### 2. Cursor 中使用步骤 + +1. 用 Cursor 打开 `C:\Users\uzuma\Desktop\svn\Nexus` +2. MCP 自动加载（`~/.cursor/mcp.json` 已配置好） +3. `.cursorrules` 自动生效（Cursor 自动读取项目根目录的此文件） +4. 直接开始对话 + +### 3. 给 Cursor Agent 的开场提示词（复制到 Chat） + +``` +读取 docs/handoff-2026-06-01.md 了解项目全貌，然后读取 CLAUDE.md 了解强制规则。项目 ~99% 完成，当前待续事项见交接文件第八节。用中文回复。 +``` + +### 4. 更完整的 Agent System Prompt（如需配置 Custom Agent） + +``` +你是 Nexus 6.0 项目的开发助手。这是一个 2000+ 服务器运维管理平台。 + +技术栈: +- 后端: FastAPI 0.115.6 + Async SQLAlchemy 2.0 + Redis 5.2 + WebSocket + Telegram +- 前端: Vue 3 + Vuetify 4 + TypeScript SPA (14个页面) +- 构建工具: Vite 8，输出到 web/app/ +- 部署: Gitea → SSH git pull → supervisorctl restart (后端)，Vite build → tar+scp (前端) + +强制规则: +1. 所有实现必须是完美实现 — 不允许降级、妥协、留技术债 +2. 安全铁律: 禁止明文密码前端、禁止静默吞错、禁止f-string拼SQL、禁止硬编码密钥 +3. 文档纪律: 每次修改必须写 changelog (docs/changelog/，行数≥10)，新功能必须先有设计文档 +4. 修改流程: 实现 → 验证 → 审计8步 → 部署 → 健康检查 → 浏览器验证 → changelog +5. 用中文回复 +6. 部署用 SSH: ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main && supervisorctl restart nexus" +7. 前端部署: cd frontend && npx vite build && cd .. && tar czf /tmp/nexus-frontend.tar.gz -C web/app index.html assets/ && scp /tmp/nexus-frontend.tar.gz nexus:/tmp/nexus-frontend.tar.gz && ssh nexus "cd /www/wwwroot/api.synaglobal.vip/web/app && tar xzf /tmp/nexus-frontend.tar.gz && rm /tmp/nexus-frontend.tar.gz" +8. 健康检查: ssh nexus "sleep 3 && curl -s http://127.0.0.1:8600/health" → 预期 "ok" + +生产环境: +- 域名: https://api.synaglobal.vip +- SSH 别名: ssh nexus (root@47.254.123.106) +- 管理员: admin / Nexus@2026 +- 数据库: MySQL nexus/Nexus@2026!@127.0.0.1:3306/nexus + +详细项目文档: 项目根目录 CLAUDE.md +交接文件: docs/handoff-2026-06-01.md +``` --- @@ -51,9 +108,7 @@ ## 三、MCP 服务器配置 -### Cursor 中配置 MCP - -Cursor 的 MCP 配置在 `~/.cursor/mcp.json`，格式： +### Cursor MCP 配置（已写入 `~/.cursor/mcp.json`） ```json { @@ -86,7 +141,7 @@ Cursor 的 MCP 配置在 `~/.cursor/mcp.json`，格式： } ``` -### Claude Code 中的 MCP 配置 +### Claude Code MCP 配置（参考） **全局配置位置**: `C:\Users\uzuma\.claude.json` → `mcpServers` @@ -165,6 +220,18 @@ cd frontend && npm run dev # http://localhost:3000/app/ Vite proxy 配置: `/api` → `https://api.synaglobal.vip`, `/ws` → `wss://api.synaglobal.vip` +### 部署常遇问题 + +| 问题 | 解决 | +|------|------| +| `/app/` 返回 404 | AppAuthMiddleware 拦截 — 确认 `/app/` 和 `/app/index.html` 在 `_APP_PUBLIC_PATHS` 中 | +| `/app/` 返回旧 HTML (Tailwind/Alpine) | `git reset --hard` 恢复了旧文件 — 需要重新 tar+scp 前端构建产物 | +| MCP deploy → git pull 失败 `could not read Username` | 服务器 remote URL 没配 token，用 `git remote set-url` | +| Gate 2 Audit BLOCKED | 创建 `docs/audit/YYYY-MM-DD-topic.md`，含 Step3+Closure+DoD | +| Gate 3 Test BLOCKED (401) | 服务器 .env 中 `NEXUS_TEST_ADMIN_PASSWORD` 与数据库不一致 | +| Gate 6 Security BLOCKED (bandit HIGH) | md5 → sha256 等，参看 bandit 报告修复 | +| Gate 7 Review BLOCKED | 审计文件缺少实际改动文件清单 | + --- ## 六、7道门控 (deploy/pre_deploy_check.sh) @@ -229,15 +296,15 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK | 优先级 | 问题 | 文件 | 说明 | |--------|------|------|------| | P1 | 批量操作按钮无反应 | ServersPage.vue | 服务器列表顶部「升级/安装/卸载 Agent」按钮，选中后点击没反应 | +| P1 | agent script-callback 无 API Key 认证 | server/api/agent.py | 端点仅靠 job_id+secret 验证，无 API Key 校验 | +| P1 | 访问令牌 30 天有效期过长 | server/config.py | 行业标准 15-60 分钟 + refresh token 轮换，当前 30 天 | | P2 | 47.121.118.30 持续发 422 | server/api/agent.py | 该 IP 不在数据库但持续发心跳，需静默丢弃或注册 | | P2 | 422 调试日志是临时的 | server/main.py | RequestValidationError handler 仅用于调试，确认问题后应移除 | +| P2 | Admin 废弃列未清理 | server/domain/models/__init__.py | jwt_refresh_token/jwt_token_expires 旧单token设计遗留 | +| P2 | 壁纸 URL 请求命中单数端点 | LoginPage.vue | 浏览器缓存旧 JS 时请求 `/bing-wallpaper` 而非 `/bing-wallpapers`，清缓存可解决 | | P3 | agent.py on_event 弃用 | server/api/agent.py | `on_event("startup")` 已弃用应改 lifespan | | P3 | Agent 心跳缺指数退避 | server/api/agent.py | 心跳失败时无退避策略 | -| P2 | 壁纸 URL 请求命中单数端点 | LoginPage.vue | 浏览器缓存旧 JS 时请求 `/bing-wallpaper` 而非 `/bing-wallpapers`，清缓存可解决 | -| UX | 命令输入栏高亮与输入框对齐 | TerminalPage.vue | cmd-highlight 定位需要与 v-text-field 输入区精确对齐，可能在不同浏览器/分辨率下有偏差 | -| P1 | agent script-callback 无 API Key 认证 | server/api/agent.py | 端点仅靠 job_id+secret 验证，无 API Key 校验 | -| P2 | Admin 废弃列 jwt_refresh_token/jwt_token_expires | server/domain/models/__init__.py | 旧单 token 设计遗留，现用 Redis 多设备，应清理 | -| P1 | config.py 访问令牌 30 天有效期 | server/config.py | 过长，行业标准 15-60 分钟 + refresh token 轮换 | +| UX | 命令输入栏高亮与输入框对齐 | TerminalPage.vue | cmd-highlight 定位可能在不同浏览器/分辨率下有偏差 | --- @@ -257,12 +324,14 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK | 快捷命令 CRUD | server/api/terminal.py | | Agent 心跳 | server/api/agent.py | | 同步引擎 | server/application/services/sync_engine_v2.py | +| 认证服务 | server/application/services/auth_service.py | | 前端入口 | frontend/src/main.ts | | 路由 | frontend/src/router/index.ts | | API 客户端 | frontend/src/api/index.ts | | Auth Store | frontend/src/stores/auth.ts | | 登录页 | frontend/src/pages/LoginPage.vue | | 终端页 | frontend/src/pages/TerminalPage.vue | +| WebSocket composable | frontend/src/composables/useWebSocket.ts | | Vite 配置 | frontend/vite.config.mts | | 部署脚本 | deploy/deploy-frontend.sh | | 门控脚本 | deploy/pre_deploy_check.sh | @@ -270,7 +339,8 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK | Nginx | deploy/nginx_https.conf | | DB 备份 | deploy/db_backup.sh | | 健康检查 | deploy/health_monitor.sh | -| 项目记忆 | CLAUDE.md (非常详尽) | +| 项目规则 | CLAUDE.md (非常详尽，279行) | +| Cursor 规则 | .cursorrules (项目根目录) | --- @@ -284,17 +354,15 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK --- -## 十一、Cursor Rules / CLAUDE.md 位置 +## 十一、规则文件位置 | 文件 | 路径 | 说明 | |------|------|------| -| 全局规则 | `C:\Users\uzuma\.claude\CLAUDE.md` | 完美实现原则、安全铁律、文档纪律、执行顺序 | -| 项目规则 | `C:\Users\uzuma\Desktop\svn\Nexus\CLAUDE.md` | 项目概述、目录结构、已确认决策、实现状态、部署流程 | -| 项目 Memory | `C:\Users\uzuma\.claude\projects\C--Users-uzuma-Desktop-svn-Nexus\memory\MEMORY.md` | 语言偏好(中文)、浏览器偏好(Playwright)、SSH配置、部署流程、Vuetify进度 | - -**重要**: Cursor 中对应的规则文件位置： -- `.cursorrules` 或 `.cursor/rules/` 目录 -- 需要把 CLAUDE.md 内容复制为 `.cursorrules` 格式 +| **Cursor 规则** | `.cursorrules`（项目根目录）| 已创建，Cursor 自动读取 | +| **Cursor MCP** | `C:\Users\uzuma\.cursor\mcp.json` | 已创建，Cursor 自动读取 | +| 全局规则 (Claude) | `C:\Users\uzuma\.claude\CLAUDE.md` | 完美实现原则、安全铁律、文档纪律、执行顺序 | +| 项目规则 (Claude) | `C:\Users\uzuma\Desktop\svn\Nexus\CLAUDE.md` | 项目概述、目录结构、已确认决策、实现状态、部署流程 | +| 项目 Memory (Claude) | `C:\Users\uzuma\.claude\projects\C--Users-uzuma-Desktop-svn-Nexus\memory\MEMORY.md` | 语言偏好(中文)、浏览器偏好(Playwright)、SSH配置、部署流程、Vuetify进度 | --- @@ -304,7 +372,7 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK 需求确认 → 设计文档 → 技术文档 → 实现 → 测试验证 → changelog →（必要时）更新 CLAUDE.md ``` -**强制文件修改流程**: +**强制文件修改流程（不可跳步）**: ``` 实现 → WSL本地验证 → ★审计8步★ → 部署 → 健康检查 → 浏览器验证 → changelog ``` @@ -314,40 +382,45 @@ MCP deploy 工具自动执行门控，任何一门不过返回 🚫 DEPLOY BLOCK □实现 □WSL验证 □审计8步 □部署 □健康检查 □浏览器验证 □changelog ``` +审计8步：登记→全文Read→规则扫描H→Closure表→入口表→输入→Sink→归类→DoD + --- -## 十三、Cursor Agent 接管要点 - -### 给 Cursor Agent 的提示词 - -复制以下内容到 Cursor 的 Agent/Chat 中作为上下文： +## 十三、数据流 ``` -你是 Nexus 6.0 项目的开发助手。这是一个 2000+ 服务器运维管理平台。 - -技术栈: -- 后端: FastAPI + Async SQLAlchemy + Redis + WebSocket + Telegram -- 前端: Vue 3 + Vuetify 4 + TypeScript SPA (14个页面) -- 部署: Gitea → SSH git pull → supervisorctl restart (后端)，Vite build → tar+scp (前端) - -强制规则: -1. 所有实现必须是完美实现 — 不允许降级、妥协、留技术债 -2. 安全铁律: 禁止明文密码前端、禁止静默吞错、禁止f-string拼SQL、禁止硬编码密钥 -3. 文档纪律: 每次修改必须写 changelog (docs/changelog/)，新功能必须先有设计文档 -4. 修改流程: 实现 → 验证 → 审计8步 → 部署 → 健康检查 → 浏览器验证 → changelog -5. 用中文回复 -6. 部署用 SSH: `ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main && supervisorctl restart nexus"` - -生产环境: -- 域名: https://api.synaglobal.vip -- SSH 别名: ssh nexus (root@47.254.123.106) -- 管理员: admin / Nexus@2026 -- 健康检查: curl http://127.0.0.1:8600/health → "ok" - -详细项目文档: 项目根目录 CLAUDE.md -交接文件: docs/handoff-2026-06-01.md +Agent心跳(60s) → Redis(实时) → 前端直读 → 10min批量 → MySQL(历史) +告警: CPU/mem/disk > threshold → WebSocket推送浏览器 + Telegram推送手机 +恢复: 之前告警的指标恢复正常 → 自动推送恢复通知 +Redis心跳key: heartbeat:{server_id} (HSET, TTL=600s) +Redis告警key: alerts:{server_id} (SET, TTL=3600s) ``` -### Cursor Rules 文件 +--- -在项目根目录创建 `.cursorrules` 文件，内容从 `CLAUDE.md` 复制。或者创建 `.cursor/rules/` 目录，按模块拆分规则。 +## 十四、已确认的关键决策 + +| 不可改项 | 原因 | +|---------|------| +| API_KEY | 加密一致性 + 子服务器认证 | +| SECRET_KEY | 加密回退密钥 | +| DATABASE_URL | 启动必需 | +| ENCRYPTION_KEY | 凭据加密 | + +| 可改项 | 说明 | +|--------|------| +| system_name/title | 前端显示 | +| pool_size/overflow | 安装向导自动推荐 | +| redis_url | Redis 连接 | +| 告警阈值 | 默认 80% | +| Telegram 配置 | 告警推送 | + +--- + +## 十五、用户审查清单 + +验证 AI 是否偷懒： +1. 看 `deploy/gate_log.jsonl` — 每次门控都有记录，没有记录 = 没过门控 +2. 看审计文件 — 必须有 Closure 表（每个H的判定+依据）、Step 3 规则扫描、DoD +3. 看进度条 — ☑必须在□前面，否则跳步 +4. 看 changelog — 行数≥10，不能是空壳