chore(ide): 将 .qoder 指令层纳入版本控制
工作区根 own/vps 不是 git 仓库，.qoder/rules 与 .qoder/agents 长期无版本化、无异地备份。 现将两类手写指令资产实体迁入本仓库 .qoder/ 下，工作区根原路径改为相对符号链接指回仓库， IDE 加载路径与规则 glob（vps-manager/**/*.py）保持不变。 .gitignore 仅跟踪 .qoder/rules 与 .qoder/agents，repowiki、better-harness 报告等可重生成产物不入库。
This commit is contained in:
gouki
@@ -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/
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: code-reviewer
|
||||
model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)"
|
||||
skills: []
|
||||
mcpServers: []
|
||||
additionalPrompt: ""
|
||||
---
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: full-stack-engineer
|
||||
model: "[DeepSeek-V4-Flash](custom:model_1782810182073_t04l2pm)"
|
||||
skills: []
|
||||
mcpServers: []
|
||||
additionalPrompt: ""
|
||||
---
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: qa
|
||||
model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)"
|
||||
skills: []
|
||||
mcpServers: []
|
||||
additionalPrompt: ""
|
||||
---
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: researcher
|
||||
model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)"
|
||||
skills: []
|
||||
mcpServers: []
|
||||
additionalPrompt: ""
|
||||
---
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
name: ui-operator
|
||||
model: "[Kimi-K3](custom:model_1785499173383_zeg8vro)"
|
||||
skills: []
|
||||
mcpServers: []
|
||||
additionalPrompt: ""
|
||||
---
|
||||
@@ -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 或邮件渠道
|
||||
- 未配置渠道自动跳过，不中断通知流程
|
||||
@@ -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
|
||||
```
|
||||
@@ -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`（项目依赖仅在虚拟环境中可用）
|
||||
- 全部通过才视为改动完成
|
||||
- 如有失败，先修复再提交
|
||||
Reference in New Issue
Block a user