feat: introduce spec system + dashboard + health pipeline (AgentsMeeting template)

2026-07-19 10:50:34 +08:00
parent 81c6dd2314
commit 747fdfe467
19 changed files with 1826 additions and 0 deletions
@@ -0,0 +1,105 @@
+# MoFin — Dashboard API 参考
+
+> 版本: v1.0 | 端口: 5804 | 入口: http://192.168.1.246:5804
+
+---
+
+## Tab 结构
+
+```
+MoFin Dashboard
+├── Services     — 服务状态总览（MoFin API / Dashboard / 知微 Gateway / ejabberd / DB）
+└── 开发原则
+    ├── G 规范   — 开发规范 + Spec 文档
+    └── F 健康   — 系统健康监控（Tier1/Tier2）
+```
+
+---
+
+## API 端点清单
+
+### 服务监控
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/services` | 所有注册服务状态（含健康检查结果） |
+| GET | `/api/expected` | 期望状态矩阵（含实际状态对比） |
+| GET | `/api/monitor` | 聚合监控数据（tasks + Tier1 + Tier2） |
+| GET | `/api/health` | Dashboard 自身健康检查 |
+
+### 知识管理
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/module-spec/<module>` | 读取 `specs/{module}.json`（?§ 按钮后端） |
+
+### 响应格式
+
+**GET /api/services**:
+```json
+{
+  "services": [
+    {
+      "name": "mofin_api",
+      "label": "MoFin API",
+      "port": 8899,
+      "type": "http",
+      "layer": "核心服务",
+      "critical": true,
+      "health": {"ok": true},
+      "detail": "HTTP 200"
+    }
+  ],
+  "summary": {"ok": 5, "total": 5}
+}
+```
+
+**GET /api/monitor**:
+```json
+{
+  "tasks": [
+    {"name": "agents-health-check", "status": "cron_ok"},
+    {"name": "agents-daily-health", "status": "not_deployed"},
+    {"name": "dashboard", "status": "running", "detail": "services: 5/5"}
+  ],
+  "tier1": {"summary": {"ok": 5, "total": 5}, "services": [...]},
+  "tier2": {"summary": {"ok": 0, "total": 0}, "services": []},
+  "generated_at": "2026-07-19 10:00:00"
+}
+```
+
+---
+
+## 前端架构
+
+- 纯 HTML/CSS/JS（无框架）
+- 深色主题（GitHub Dark 风格）
+- 5 秒自动轮询（Services Tab）
+- ?§ Spec 系统（human_help + ai_spec）
+
+### Spec 系统（?§ 按钮）
+
+每个有 spec 的模块在 UI 上显示两个按钮：
+- `?` → 读取 `human_help` → 人类可读的帮助文档
+- `§` → 读取 `ai_spec` → AI 可用的接口/约束/依赖
+
+**Spec 文件位置**: `specs/{module}.json`
+**API 端点**: `GET /api/module-spec/{module}`
+
+---
+
+## 数据流
+
+```
+crontab (每 5 分钟)
+  └── agents_health_check.py → last_health_check.json
+
+Dashboard (:5804)
+  ├── /api/services ← 实时 TCP/HTTP 检测
+  ├── /api/monitor ← 聚合读取 health check JSON
+  └── /api/module-spec/<module> ← 读取 specs/
+
+前端 (dashboard.html)
+  ├── 5s 轮询 /api/services
+  └── 按需请求 /api/monitor（F Tab 打开时）
+```