From 6edafc93450ad214a5f742b0961bec6df549e7ef Mon Sep 17 00:00:00 2001 From: gouki Date: Mon, 12 Oct 2026 21:39:54 +0000 Subject: [PATCH] =?UTF-8?q?chore(ide):=20=E5=B0=86=20.qoder=20=E6=8C=87?= =?UTF-8?q?=E4=BB=A4=E5=B1=82=E7=BA=B3=E5=85=A5=E7=89=88=E6=9C=AC=E6=8E=A7?= =?UTF-8?q?=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 工作区根 own/vps 不是 git 仓库，.qoder/rules 与 .qoder/agents 长期无版本化、无异地备份。 现将两类手写指令资产实体迁入本仓库 .qoder/ 下，工作区根原路径改为相对符号链接指回仓库， IDE 加载路径与规则 glob（vps-manager/**/*.py）保持不变。 .gitignore 仅跟踪 .qoder/rules 与 .qoder/agents，repowiki、better-harness 报告等可重生成产物不入库。 --- .gitignore | 6 + .qoder/agents/builtin/code-reviewer.md | 7 + .qoder/agents/builtin/full-stack-engineer.md | 7 + .qoder/agents/builtin/qa.md | 7 + .qoder/agents/builtin/researcher.md | 7 + .qoder/agents/builtin/ui-operator.md | 7 + .qoder/rules/coding-standards.md | 56 ++++++++ .qoder/rules/deploy-verification.md | 142 +++++++++++++++++++ .qoder/rules/vps-manager-pytest.md | 14 ++ 9 files changed, 253 insertions(+) create mode 100644 .qoder/agents/builtin/code-reviewer.md create mode 100644 .qoder/agents/builtin/full-stack-engineer.md create mode 100644 .qoder/agents/builtin/qa.md create mode 100644 .qoder/agents/builtin/researcher.md create mode 100644 .qoder/agents/builtin/ui-operator.md create mode 100644 .qoder/rules/coding-standards.md create mode 100644 .qoder/rules/deploy-verification.md create mode 100644 .qoder/rules/vps-manager-pytest.md diff --git a/.gitignore b/.gitignore index 418a212..69e7bd9 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,9 @@ data/ .env.local .DS_Store .pytest_cache/ + +# IDE 指令层：仅跟踪手写资产 .qoder/rules 与 .qoder/agents +# 其余 .qoder 产物（repowiki / better-harness 报告）可由 IDE 重生成，不入库 +.qoder/* +!.qoder/rules/ +!.qoder/agents/ diff --git a/.qoder/agents/builtin/code-reviewer.md b/.qoder/agents/builtin/code-reviewer.md new file mode 100644 index 0000000..12066e1 --- /dev/null +++ b/.qoder/agents/builtin/code-reviewer.md @@ -0,0 +1,7 @@ +--- +name: code-reviewer +model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)" +skills: [] +mcpServers: [] +additionalPrompt: "" +--- diff --git a/.qoder/agents/builtin/full-stack-engineer.md b/.qoder/agents/builtin/full-stack-engineer.md new file mode 100644 index 0000000..b0e4ba9 --- /dev/null +++ b/.qoder/agents/builtin/full-stack-engineer.md @@ -0,0 +1,7 @@ +--- +name: full-stack-engineer +model: "[DeepSeek-V4-Flash](custom:model_1782810182073_t04l2pm)" +skills: [] +mcpServers: [] +additionalPrompt: "" +--- diff --git a/.qoder/agents/builtin/qa.md b/.qoder/agents/builtin/qa.md new file mode 100644 index 0000000..fac6f2b --- /dev/null +++ b/.qoder/agents/builtin/qa.md @@ -0,0 +1,7 @@ +--- +name: qa +model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)" +skills: [] +mcpServers: [] +additionalPrompt: "" +--- diff --git a/.qoder/agents/builtin/researcher.md b/.qoder/agents/builtin/researcher.md new file mode 100644 index 0000000..de73627 --- /dev/null +++ b/.qoder/agents/builtin/researcher.md @@ -0,0 +1,7 @@ +--- +name: researcher +model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)" +skills: [] +mcpServers: [] +additionalPrompt: "" +--- diff --git a/.qoder/agents/builtin/ui-operator.md b/.qoder/agents/builtin/ui-operator.md new file mode 100644 index 0000000..1720d54 --- /dev/null +++ b/.qoder/agents/builtin/ui-operator.md @@ -0,0 +1,7 @@ +--- +name: ui-operator +model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)" +skills: [] +mcpServers: [] +additionalPrompt: "" +--- diff --git a/.qoder/rules/coding-standards.md b/.qoder/rules/coding-standards.md new file mode 100644 index 0000000..4ed2010 --- /dev/null +++ b/.qoder/rules/coding-standards.md @@ -0,0 +1,56 @@ +--- +description: vps-manager 核心编码规范，每次会话自动加载 +alwaysApply: true +--- + +# vps-manager 编码规范 + +## 技术栈 + +- 后端：Python + FastAPI + SQLModel +- 前端：Vue 3 + Tailwind CSS（本地化、深色模式、PWA） +- 数据库：SQLite 分库（assets.db / metrics.db） +- 加密：cryptography.Fernet（MASTER_KEY 存 .env） +- 部署：cc1 节点，Gitea push 自动更新，HTTPS via Tailscale + +## 前端：移动端优先 + +- UI 设计遵循移动端优先原则，采用底部导航栏适配小屏幕 +- 确保页面 scrollWidth 等于 clientWidth，避免横向溢出 +- 桌面端使用侧边栏布局，移动端使用底部 Tab 导航 +- 静态资源基于文件 mtime 自动注入 `?v={mtime}` 版本号，配合 Service Worker 实现缓存失效 + +## Service Worker 缓存策略 + +- HTML 导航请求：`network-first`（回源失败才用缓存） +- 静态资源：`stale-while-revalidate`（SWR），配合 `?v={mtime}` 版本号 +- API 请求：纯网络模式，不经过 Service Worker +- `sw.js` 本体由服务端设置 `Cache-Control: no-cache` + +## 数据库分库 + +- `data/assets.db`：资产核心数据（Provider / Asset / VPSDetail / DomainDetail / AIAccount / Credential） +- `data/metrics.db`：监控指标与日志（MetricPoint / ServerInfo / SecurityCheck / EventLog） +- 备份策略：assets.db 每日备份保留 14 份，metrics.db 每周备份保留 4 份 + +## 凭证与加密 + +- 凭据中心化架构：`credentials` 表作为登录凭据唯一事实源 +- 使用 `cryptography.Fernet` 加密敏感字段，MASTER_KEY 存于 `.env` +- 账号表降级为纯"归属 + API 配置"容器，通过 `account.credential_id` 关联凭据 + +## 云厂商适配层 + +- 位于 `app/adapters/`：BaseAdapter 抽象基类 + registry 装饰器注册 +- 按 `Provider.sdk_type` 路由，已实现 Vultr / DO / Cloudflare / 阿里云 / 腾讯云 +- sync_service 以 `(provider_id, external_id)` 去重同步入库 + +## 平台分类 + +- `category` 字段仅作主业务标签用于列表排序和兜底展示，不设"综合平台"分类 +- 资产关联平台时以 `services` 多标签为准，优先匹配目标资产类型对应的服务能力 + +## 通知 + +- 通知服务根据 `.env` 配置自动选择 Telegram 或邮件渠道 +- 未配置渠道自动跳过，不中断通知流程 diff --git a/.qoder/rules/deploy-verification.md b/.qoder/rules/deploy-verification.md new file mode 100644 index 0000000..4c28eb9 --- /dev/null +++ b/.qoder/rules/deploy-verification.md @@ -0,0 +1,142 @@ +--- +description: 部署验收检查点，git push 或执行 deploy/deploy.sh 后必须完成 /health 与核心 API 验证 +alwaysApply: true +--- + +# 部署验收检查点 + +## 触发条件 + +当 Agent 执行以下任一操作后，**必须**自动进入部署验收流程： + +- `git push` 到 Gitea（触发 cc1 自动更新） +- 执行 `deploy/deploy.sh` +- 任何会导致远端代码变更并触发 cc1 自动拉取的操作 + +## 验收流程 + +### 1. 等待自动更新 + +cc1 上的 `vps-manager-update.timer` 每 1 分钟触发一次 `update.sh`，push 后最多 60 秒开始更新。 + +### 2. 调用 /health 端点 + +轮询 `https://dify.taile5765c.ts.net/health`，直到 commit 追平或超时。 + +**端点契约：** + +```json +{ + "status": "ok", + "app": "vps-manager", + "version": "x.x.x", + "commit": "7位短hash" +} +``` + +**验收标准：** + +| 字段 | 预期值 | 说明 | +|------|--------|------| +| `status` | `"ok"` | 服务可用 | +| `commit` | 与本地 `git rev-parse --short=7 HEAD` 一致 | 代码已生效 | +| `version` | 与本地 `VERSION` 文件一致 | 版本号正确 | + +**轮询参数：** + +- 间隔：15 秒 +- 单次请求超时：10 秒（`curl --max-time 10`） +- 总超时：120 秒（Agent 验收场景；deploy.sh 用 720 秒含首次部署余量） + +### 3. 核心 API 验证 + +commit 追平后，逐一验证以下端点返回 HTTP 200： + +``` +/api/assets +/api/accounts +/api/providers +/api/stats/overview +``` + +### 4. 记录验收结果 + +验收完成后，在终端输出结构化结果： + +``` +✅ 部署验收通过 + commit: abc1234 + version: v0.5.0 + health: ok + apis: 4/4 passed +``` + +## 失败处理 + +### 网络超时 + +当 curl 请求超时或无响应时，输出明确提示： + +``` +❌ 部署验收失败：网络超时 + 可能原因： + 1. cc1 节点不可达（Tailscale 连接断开） + 2. vps-manager 服务未启动或启动中 + 3. 防火墙/网络策略阻断 + 排查：ping cc1 / curl -v https://dify.taile5765c.ts.net/health +``` + +### Commit 未追平 + +超时后 commit 仍不一致： + +``` +❌ 部署验收失败：版本未追平 + 期望 commit: abc1234 + 线上 commit: def5678 + 超时: 120s + 排查：ssh cc1 'journalctl -u vps-manager-update.service -n 30' +``` + +### API 验证失败 + +commit 追平但核心 API 返回非 200： + +``` +❌ 部署验收失败：API 异常 + /api/assets -> 200 ✓ + /api/accounts -> 200 ✓ + /api/providers -> 500 ❌ + /api/stats/overview -> 200 ✓ + 排查：ssh cc1 'journalctl -u vps-manager -n 50' +``` + +## 实现参考 + +Agent 执行验收时，使用以下命令序列： + +```bash +# 1. 获取本地版本 +LOCAL_SHORT=$(git rev-parse --short=7 HEAD) + +# 2. 轮询 health（带超时） +deadline=$(( $(date +%s) + 120 )) +while [ "$(date +%s)" -lt "$deadline" ]; do + response=$(curl -s --max-time 10 https://dify.taile5765c.ts.net/health 2>/dev/null) || { + echo "⚠️ 请求超时，15s 后重试…" + sleep 15; continue + } + remote=$(echo "$response" | python3 -c "import json,sys; print(json.load(sys.stdin).get('commit',''))" 2>/dev/null) + if [ "$remote" = "$LOCAL_SHORT" ]; then + echo "✅ commit 已追平: $LOCAL_SHORT" + break + fi + sleep 15 +done + +# 3. 验证核心 API +for path in /api/assets /api/accounts /api/providers /api/stats/overview; do + code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "https://dify.taile5765c.ts.net$path") + echo " $path -> $code" +done +``` diff --git a/.qoder/rules/vps-manager-pytest.md b/.qoder/rules/vps-manager-pytest.md new file mode 100644 index 0000000..6827d41 --- /dev/null +++ b/.qoder/rules/vps-manager-pytest.md @@ -0,0 +1,14 @@ +--- +paths: + - vps-manager/**/*.py +--- + +编辑 vps-manager 下的 Python 源文件后，必须立即运行测试验证： + +```bash +cd vps-manager && .venv/bin/python -m pytest tests/ -x -q +``` + +- 必须使用 `.venv/bin/python`（项目依赖仅在虚拟环境中可用） +- 全部通过才视为改动完成 +- 如有失败，先修复再提交