docs: archive completed plans and rename next wave doc
This commit is contained in:
656
archive/achieve/DEVELOPMENT_PLAN.md
Normal file
656
archive/achieve/DEVELOPMENT_PLAN.md
Normal file
@@ -0,0 +1,656 @@
|
||||
# HarborForge 开发计划
|
||||
|
||||
**版本**: 0.3.0
|
||||
**日期**: 2026-03-19
|
||||
**状态**: 开发中
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
HarborForge 是一个 **AI Agent 与人类协同的任务管理平台**，用于管理项目、里程碑、任务和提案(Propose)。
|
||||
|
||||
### 核心特性
|
||||
- 项目驱动的任务管理
|
||||
- 里程碑(Milestone)状态机管理
|
||||
- 任务(Task)状态机管理
|
||||
- 提案(Propose)工作流
|
||||
- 角色权限系统(RBAC)
|
||||
- 服务器监控集成
|
||||
- Webhook 扩展能力
|
||||
- OpenClaw 插件生态
|
||||
|
||||
---
|
||||
|
||||
## 2. 系统架构
|
||||
|
||||
### 2.1 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 客户端层 │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
|
||||
│ │ Web Frontend │ │ OpenClaw CLI │ │ OpenClaw Plugin │ │
|
||||
│ │ (React/Vite) │ │ │ │ (Server Monitor) │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │
|
||||
└─────────┼─────────────────┼─────────────────────┼──────────────┘
|
||||
│ │ │
|
||||
└─────────────────┼─────────────────────┘
|
||||
│ HTTP/WebSocket
|
||||
┌───────────────────────────▼─────────────────────────────────────┐
|
||||
│ HarborForge.Backend │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ FastAPI + SQLAlchemy + MySQL │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ Projects│ │Milestones│ │ Tasks │ │Proposes │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ Auth │ │ RBAC │ │ Monitor │ │ Webhooks│ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
└──────────────────────────────────────────────────────┐
|
||||
│
|
||||
┌────────────────────────────────────────────────────────────────▼┐
|
||||
│ 外部集成 │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
|
||||
│ │ LLM Providers│ │ Keycloak │ │ AbstractWizard │ │
|
||||
│ │ (Claude/etc) │ │ (Auth) │ │ (Config Management) │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 模块划分
|
||||
|
||||
| 模块 | 技术栈 | 职责 |
|
||||
|------|--------|------|
|
||||
| **Backend** | FastAPI + SQLAlchemy + MySQL | REST API + WebSocket，业务逻辑 |
|
||||
| **Frontend** | React + Vite + TypeScript | 用户界面，管理后台 |
|
||||
| **OpenclawPlugin** | Node.js + TypeScript | OpenClaw 集成，服务器监控 |
|
||||
| **Backend.Test** | pytest | 独立测试套件 |
|
||||
| **Frontend.Test** | Playwright | E2E 测试 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据模型
|
||||
|
||||
### 3.1 核心实体关系
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Project │◄────┤ Milestone │◄────┤ Task │
|
||||
│ │ │ │ │ │
|
||||
│ - id │ │ - id │ │ - id │
|
||||
│ - name │ │ - title │ │ - title │
|
||||
│ - owner_id │ │ - status │ │ - status │
|
||||
│ - project_code│ │ - project_id│ │ - type │
|
||||
└──────┬──────┘ └─────────────┘ └──────┬──────┘
|
||||
│ │
|
||||
│ ┌─────────────┐ │
|
||||
└────────►│ Propose │◄─────────────┘
|
||||
│ │
|
||||
│ - id │
|
||||
│ - title │
|
||||
│ - status │
|
||||
│ - feat_task_id (accept时创建)
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
### 3.2 状态机定义
|
||||
|
||||
#### Milestone 状态
|
||||
```
|
||||
open ──freeze──► freeze ──start──► undergoing ──close──► closed
|
||||
│ │
|
||||
│ └──auto-complete──► completed
|
||||
│
|
||||
└──────────────────────────────────────────────────► closed
|
||||
```
|
||||
|
||||
#### Task 状态
|
||||
```
|
||||
open ──assign+start──► undergoing ──finish+comment──► completed ──close──► closed
|
||||
│ │
|
||||
│ └──reopen──► open
|
||||
│
|
||||
└──pending──► undergoing ──(同上)
|
||||
```
|
||||
|
||||
#### Propose 状态
|
||||
```
|
||||
open ──accept──► accepted (创建 feature story task)
|
||||
│
|
||||
└──reject──► rejected ──reopen──► open
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API 接口设计
|
||||
|
||||
### 4.1 认证接口
|
||||
|
||||
```yaml
|
||||
POST /auth/token
|
||||
# JWT 登录
|
||||
Body: { username: string, password: string }
|
||||
Response: { access_token: string, token_type: "bearer" }
|
||||
|
||||
GET /users/me
|
||||
# 获取当前用户信息
|
||||
Headers: Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
### 4.2 项目接口
|
||||
|
||||
```yaml
|
||||
GET /projects
|
||||
# 列表（支持分页）
|
||||
Query: { page: int, page_size: int }
|
||||
|
||||
POST /projects
|
||||
# 创建
|
||||
Body: { name: string, description?: string, project_code?: string }
|
||||
|
||||
GET /projects/{id}
|
||||
# 详情
|
||||
|
||||
PATCH /projects/{id}
|
||||
# 更新
|
||||
|
||||
DELETE /projects/{id}
|
||||
# 删除（需确认）
|
||||
```
|
||||
|
||||
### 4.3 里程碑接口
|
||||
|
||||
```yaml
|
||||
GET /projects/{project_id}/milestones
|
||||
# 列表
|
||||
Query: { status: "open|freeze|undergoing|completed|closed" }
|
||||
|
||||
POST /projects/{project_id}/milestones
|
||||
# 创建
|
||||
Body: { title: string, description?: string, due_date?: datetime }
|
||||
|
||||
GET /projects/{project_id}/milestones/{id}
|
||||
# 详情
|
||||
|
||||
PATCH /projects/{project_id}/milestones/{id}
|
||||
# 更新（仅在 open 状态允许修改大部分字段）
|
||||
|
||||
DELETE /projects/{project_id}/milestones/{id}
|
||||
# 删除
|
||||
|
||||
# 状态机动作
|
||||
POST /projects/{project_id}/milestones/{id}/freeze
|
||||
POST /projects/{project_id}/milestones/{id}/start
|
||||
POST /projects/{project_id}/milestones/{id}/close
|
||||
|
||||
# 预检接口
|
||||
GET /projects/{project_id}/milestones/{id}/preflight
|
||||
# 返回 { can_freeze: bool, can_start: bool, reasons: [...] }
|
||||
```
|
||||
|
||||
### 4.4 任务接口
|
||||
|
||||
```yaml
|
||||
GET /projects/{project_id}/tasks
|
||||
# 列表
|
||||
Query: {
|
||||
status: "open|pending|undergoing|completed|closed",
|
||||
assignee_id: int,
|
||||
milestone_id: int,
|
||||
task_type: "issue|story|test|..."
|
||||
}
|
||||
|
||||
POST /projects/{project_id}/tasks
|
||||
# 创建
|
||||
Body: {
|
||||
title: string,
|
||||
milestone_id: int,
|
||||
task_type: "issue|story|test|maintenance|research|review|resolution",
|
||||
priority: "low|medium|high|critical",
|
||||
assignee_id?: int
|
||||
}
|
||||
|
||||
GET /projects/{project_id}/tasks/{id}
|
||||
# 详情（包含 comments）
|
||||
|
||||
PATCH /projects/{project_id}/tasks/{id}
|
||||
# 更新
|
||||
# 注意：undergoing/completed/closed 状态限制 body 编辑
|
||||
|
||||
DELETE /projects/{project_id}/tasks/{id}
|
||||
# 删除
|
||||
|
||||
# 状态机动作
|
||||
POST /projects/{project_id}/tasks/{id}/transition
|
||||
Body: {
|
||||
action: "open|start|finish|close|reopen",
|
||||
comment?: string, # finish 时必填
|
||||
close_reason?: string # close 时可选
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 Propose 接口
|
||||
|
||||
```yaml
|
||||
GET /projects/{project_id}/proposes
|
||||
# 列表
|
||||
|
||||
POST /projects/{project_id}/proposes
|
||||
# 创建
|
||||
Body: { title: string, description?: string }
|
||||
|
||||
GET /projects/{project_id}/proposes/{id}
|
||||
# 详情
|
||||
|
||||
PATCH /projects/{project_id}/proposes/{id}
|
||||
# 更新（仅在 open 状态允许）
|
||||
|
||||
# 状态机动作
|
||||
POST /projects/{project_id}/proposes/{id}/accept
|
||||
Body: { milestone_id: int } # 指定 milestone 创建 feature story task
|
||||
|
||||
POST /projects/{project_id}/proposes/{id}/reject
|
||||
|
||||
POST /projects/{project_id}/proposes/{id}/reopen
|
||||
# rejected -> open
|
||||
```
|
||||
|
||||
### 4.6 监控接口
|
||||
|
||||
```yaml
|
||||
GET /monitor/public/overview
|
||||
# 公开概览数据
|
||||
|
||||
# 管理接口
|
||||
GET /monitor/admin/servers
|
||||
POST /monitor/admin/servers
|
||||
DELETE /monitor/admin/servers/{id}
|
||||
POST /monitor/admin/servers/{id}/api-key
|
||||
DELETE /monitor/admin/servers/{id}/api-key
|
||||
|
||||
# 服务器上报（插件调用）
|
||||
POST /monitor/server/heartbeat-v2
|
||||
Headers:
|
||||
X-API-Key: string
|
||||
Body:
|
||||
identifier: string
|
||||
openclaw_version: string # 远程主机上的 OpenClaw 版本
|
||||
plugin_version: string # harbor-forge 插件版本
|
||||
cpu_pct: float
|
||||
mem_pct: float
|
||||
disk_pct: float
|
||||
swap_pct: float
|
||||
load_avg: [float, float, float]
|
||||
uptime_seconds: int
|
||||
agents: [...]
|
||||
```
|
||||
|
||||
### 4.7 其他接口
|
||||
|
||||
```yaml
|
||||
# 评论
|
||||
GET /projects/{project_id}/tasks/{task_id}/comments
|
||||
POST /projects/{project_id}/tasks/{task_id}/comments
|
||||
|
||||
# 角色权限
|
||||
GET /roles
|
||||
GET /roles/{id}
|
||||
POST /roles
|
||||
PATCH /roles/{id}
|
||||
DELETE /roles/{id}
|
||||
|
||||
# Webhook
|
||||
GET /webhooks
|
||||
POST /webhooks
|
||||
DELETE /webhooks/{id}
|
||||
|
||||
# Dashboard
|
||||
GET /dashboard/stats?project_id={id}
|
||||
|
||||
# 健康检查
|
||||
GET /health
|
||||
GET /version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全设计
|
||||
|
||||
### 5.1 认证
|
||||
- **JWT Token**: 基于 `python-jose`，有效期 configurable
|
||||
- **API Key**: 支持服务间调用
|
||||
- **Admin 权限**: `users.is_admin` 字段控制
|
||||
|
||||
### 5.2 项目权限 (RBAC)
|
||||
|
||||
| 角色 | 权限范围 |
|
||||
|------|----------|
|
||||
| admin | 全局所有操作 |
|
||||
| owner | 项目内所有操作 |
|
||||
| mgr | 里程碑/任务管理，接受/拒绝 propose |
|
||||
| dev | 任务操作，创建 propose |
|
||||
| guest | 只读访问 |
|
||||
|
||||
### 5.3 监控插件安全
|
||||
|
||||
```
|
||||
1. 服务器注册
|
||||
2. 管理员生成 API Key
|
||||
3. 插件将 API Key 写入 OpenClaw plugin config
|
||||
4. sidecar 通过 X-API-Key 调用 /monitor/server/heartbeat-v2
|
||||
5. 服务端按 API Key 识别并接收遥测
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 开发里程碑
|
||||
|
||||
### P0 - 基础框架 ✅
|
||||
- [x] 项目初始化 (FastAPI + SQLAlchemy)
|
||||
- [x] 用户认证 (JWT)
|
||||
- [x] Docker Compose 部署
|
||||
|
||||
### P1 - 核心 CRUD ✅
|
||||
- [x] Projects CRUD
|
||||
- [x] Milestones CRUD
|
||||
- [x] Tasks CRUD
|
||||
- [x] Comments
|
||||
|
||||
### P2 - 权限系统 ✅
|
||||
- [x] Role/Permission 模型
|
||||
- [x] RBAC 中间件
|
||||
- [x] 项目成员管理
|
||||
|
||||
### P3 - 里程碑状态机 ✅
|
||||
- [x] freeze/start/close 动作
|
||||
- [x] 自动完成钩子
|
||||
- [x] 编辑限制
|
||||
|
||||
### P4 - 任务依赖 ✅
|
||||
- [x] depend_on 字段
|
||||
- [x] 依赖检查工具
|
||||
- [x] 批量操作
|
||||
|
||||
### P5 - 任务状态机 ✅
|
||||
- [x] open/start/finish/close/reopen
|
||||
- [x] 负责人检查
|
||||
- [x] 完成时必须评论
|
||||
- [x] 编辑限制
|
||||
|
||||
### P6 - Propose 系统 ✅
|
||||
- [x] Propose CRUD
|
||||
- [x] accept/reject/reopen
|
||||
- [x] accept 时创建 feature story task
|
||||
|
||||
### P7 - 任务类型重构 ✅
|
||||
- [x] 移除 task 类型
|
||||
- [x] issue 作为默认
|
||||
- [x] 前端同步更新
|
||||
|
||||
### P8 - 里程碑预检 ✅
|
||||
- [x] preflight 接口
|
||||
- [x] 前端按钮状态
|
||||
|
||||
### P9 - 任务操作 UI ✅
|
||||
- [x] 操作按钮
|
||||
- [x] 完成评论弹窗
|
||||
- [x] 关闭原因弹窗
|
||||
|
||||
### P10 - Propose UI ✅
|
||||
- [x] Propose 列表页
|
||||
- [x] Propose 详情页
|
||||
- [x] 编辑弹窗（仅 open 状态）
|
||||
|
||||
### P11 - 监控后端 ✅
|
||||
- [x] Provider 账户管理
|
||||
- [x] 服务器注册/挑战
|
||||
- [x] 心跳接收
|
||||
- [x] WebSocket 支持
|
||||
|
||||
### P12 - CLI 工具 ✅
|
||||
- [x] 命令行交互
|
||||
- [x] Webhook 管理
|
||||
- [x] 配置查看
|
||||
|
||||
### P13 - 测试 ✅
|
||||
- [x] Backend 单元测试 (pytest)
|
||||
- [x] 里程碑状态机测试
|
||||
- [x] 任务状态机测试
|
||||
- [x] Propose 测试
|
||||
- [x] Frontend E2E 测试
|
||||
|
||||
### P14 - OpenClaw 集成 🔄
|
||||
- [x] Plugin 架构设计
|
||||
- [x] 遥测服务器
|
||||
- [x] 安装脚本
|
||||
- [ ] 完整测试
|
||||
|
||||
### P15 - 文档与发布 📋
|
||||
- [ ] API 文档 (OpenAPI)
|
||||
- [ ] 部署文档
|
||||
- [ ] 用户手册
|
||||
- [ ] v1.0 发布
|
||||
|
||||
---
|
||||
|
||||
## 7. 远程服务器通信协议
|
||||
|
||||
### 7.1 注册流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Admin
|
||||
participant Monitor
|
||||
participant Server
|
||||
participant Plugin
|
||||
|
||||
Admin->>Monitor: POST /admin/servers
|
||||
Monitor->>Admin: { challenge_uuid, expires_at }
|
||||
|
||||
Admin->>Server: 配置 challenge_uuid
|
||||
|
||||
Plugin->>Monitor: GET /public/server-public-key
|
||||
Monitor->>Plugin: { public_key_pem, key_id }
|
||||
|
||||
Plugin->>Plugin: 加密 payload
|
||||
Note right of Plugin: RSA-OAEP + SHA256
|
||||
|
||||
Plugin->>Monitor: POST /server/heartbeat
|
||||
Note right of Plugin: 或 WS /server/ws
|
||||
|
||||
Monitor->>Monitor: 验证 challenge_uuid
|
||||
Monitor->>Monitor: 验证 timestamp (防重放)
|
||||
Monitor->>Monitor: 存储 server_state
|
||||
```
|
||||
|
||||
### 7.2 心跳协议
|
||||
|
||||
**HTTP Heartbeat:**
|
||||
```http
|
||||
POST /monitor/server/heartbeat
|
||||
Content-Type: application/json
|
||||
X-Server-Identifier: vps.t1
|
||||
X-Challenge-UUID: abc-123-def
|
||||
|
||||
{
|
||||
"identifier": "vps.t1",
|
||||
"challenge_uuid": "abc-123-def",
|
||||
"timestamp": "2026-03-19T14:00:00Z",
|
||||
"cpu_pct": 12.5,
|
||||
"mem_pct": 41.2,
|
||||
"disk_pct": 62.0,
|
||||
"swap_pct": 0.0,
|
||||
"uptime_sec": 86400,
|
||||
"load_avg_1m": 0.5,
|
||||
"platform": "linux",
|
||||
"hostname": "vps.t1",
|
||||
"openclaw_version": "1.2.3",
|
||||
"openclaw_agent_count": 3,
|
||||
"openclaw_agents": [
|
||||
{ "id": "dev", "name": "Developer", "status": "running" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**WebSocket 连接:**
|
||||
```javascript
|
||||
// 1. 建立连接
|
||||
const ws = new WebSocket('wss://monitor.example.com/monitor/server/ws');
|
||||
|
||||
// 2. 发送加密握手
|
||||
ws.send(JSON.stringify({
|
||||
encrypted_payload: "base64_encoded_rsa_encrypted_json"
|
||||
}));
|
||||
|
||||
// 3. 接收确认
|
||||
// Server: { "status": "authenticated" }
|
||||
|
||||
// 4. 定期发送遥测
|
||||
setInterval(() => {
|
||||
ws.send(JSON.stringify({
|
||||
type: "telemetry",
|
||||
data: { /* 同上 */ }
|
||||
}));
|
||||
}, 30000);
|
||||
```
|
||||
|
||||
### 7.3 加密格式
|
||||
|
||||
```python
|
||||
# Payload 结构 (加密前)
|
||||
{
|
||||
"identifier": "vps.t1",
|
||||
"challenge_uuid": "uuid-from-admin",
|
||||
"nonce": "random-128bit-hex", # 防重放
|
||||
"ts": "2026-03-19T14:00:00Z" # UTC ISO8601，10分钟有效期
|
||||
}
|
||||
|
||||
# 加密
|
||||
encrypted = RSA_OAEP_SHA256_encrypt(
|
||||
plaintext=json.dumps(payload),
|
||||
public_key=monitor_public_key
|
||||
)
|
||||
|
||||
# 传输 (base64)
|
||||
encrypted_payload_b64 = base64.b64encode(encrypted).decode()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 技术规范
|
||||
|
||||
### 8.1 代码规范
|
||||
- **Backend**: PEP8, Black formatter, mypy type hints
|
||||
- **Frontend**: ESLint, Prettier, strict TypeScript
|
||||
- **Commits**: Conventional Commits (`feat:`, `fix:`, `test:`, `docs:`)
|
||||
|
||||
### 8.2 数据库规范
|
||||
- 所有表必须有 `id` (PK, auto_increment)
|
||||
- 时间字段使用 `DateTime(timezone=True)`
|
||||
- 枚举使用 SQLAlchemy `Enum` + `values_callable`
|
||||
- 外键必须建索引
|
||||
|
||||
### 8.3 API 规范
|
||||
- RESTful 设计
|
||||
- 统一响应格式: `{ data: ..., error?: ..., message?: ... }`
|
||||
- HTTP 状态码规范使用
|
||||
- 分页: `{ items: [...], total: N, page: 1, page_size: 20 }`
|
||||
|
||||
### 8.4 测试规范
|
||||
- 测试覆盖率 > 80%
|
||||
- 单元测试: SQLite in-memory
|
||||
- E2E 测试: 独立 Docker 环境
|
||||
- CI: GitHub Actions / Gitea Actions
|
||||
|
||||
---
|
||||
|
||||
## 9. 部署架构
|
||||
|
||||
### 9.1 生产环境
|
||||
|
||||
```yaml
|
||||
# docker-compose.prod.yml
|
||||
services:
|
||||
mysql:
|
||||
image: mysql:8.0
|
||||
volumes:
|
||||
- mysql_data:/var/lib/mysql
|
||||
|
||||
backend:
|
||||
build: ./HarborForge.Backend
|
||||
environment:
|
||||
- DATABASE_URL=mysql+pymysql://...
|
||||
- SECRET_KEY=${SECRET_KEY}
|
||||
|
||||
frontend:
|
||||
build: ./HarborForge.Frontend
|
||||
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- ./nginx.conf:/etc/nginx/nginx.conf
|
||||
- ./ssl:/etc/nginx/ssl
|
||||
```
|
||||
|
||||
### 9.2 监控插件部署
|
||||
|
||||
```bash
|
||||
# 1. 在 Monitor 注册服务器并生成 API Key
|
||||
# 2. 在服务器安装插件
|
||||
node scripts/install.mjs
|
||||
|
||||
# 3. 配置 ~/.openclaw/openclaw.json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"harbor-forge": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"enabled": true,
|
||||
"apiKey": "YOUR_API_KEY",
|
||||
"monitor_port": 9100
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# 4. 重启 Gateway
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 参考资源
|
||||
|
||||
### 代码仓库
|
||||
- `HarborForge.Backend` - FastAPI 后端
|
||||
- `HarborForge.Frontend` - React 前端
|
||||
- `HarborForge.Test` - 测试套件
|
||||
- `HarborForge.OpenclawPlugin` - OpenClaw 插件
|
||||
|
||||
### 关键文件
|
||||
- `app/models/` - SQLAlchemy 模型
|
||||
- `app/api/routers/` - API 路由
|
||||
- `app/schemas/schemas.py` - Pydantic 模型
|
||||
- `app/services/` - 业务逻辑
|
||||
- `tests/` - 测试文件
|
||||
|
||||
### 外部依赖
|
||||
- FastAPI 0.109
|
||||
- SQLAlchemy 2.0
|
||||
- React 18 + Vite 5
|
||||
- OpenClaw Gateway
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: 0.3.0
|
||||
**最后更新**: 2026-03-19
|
||||
**维护者**: HarborForge Team
|
||||
77
archive/achieve/OPENCLAW_PLUGIN_DEV_PLAN.md
Normal file
77
archive/achieve/OPENCLAW_PLUGIN_DEV_PLAN.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# OpenClaw Plugin 开发计划（当前版）
|
||||
|
||||
**状态**: API Key 方案已落地，challenge / WebSocket 旧方案已废弃。
|
||||
|
||||
## 当前架构
|
||||
|
||||
- HarborForge Monitor Backend 提供服务器注册与遥测接收接口
|
||||
- OpenClaw Gateway 加载 `harbor-forge` 插件
|
||||
- 旧 sidecar (`server/telemetry.mjs`) 已移除
|
||||
- 插件通过 Gateway/runtime 路径直接提供 OpenClaw 元数据
|
||||
- Monitor 可选通过本地 `monitor_port` 桥接读取补充信息
|
||||
|
||||
## 当前后端接口
|
||||
|
||||
### 公开接口
|
||||
- `GET /monitor/public/overview`
|
||||
|
||||
### 管理接口
|
||||
- `GET /monitor/admin/servers`
|
||||
- `POST /monitor/admin/servers`
|
||||
- `DELETE /monitor/admin/servers/{id}`
|
||||
- `POST /monitor/admin/servers/{id}/api-key`
|
||||
- `DELETE /monitor/admin/servers/{id}/api-key`
|
||||
|
||||
### 插件上报接口
|
||||
- `POST /monitor/server/heartbeat-v2`
|
||||
- Header: `X-API-Key`
|
||||
- Body:
|
||||
- `identifier`
|
||||
- `openclaw_version`
|
||||
- `plugin_version`
|
||||
- `agents`
|
||||
- `cpu_pct`
|
||||
- `mem_pct`
|
||||
- `disk_pct`
|
||||
- `swap_pct`
|
||||
- `load_avg`
|
||||
- `uptime_seconds`
|
||||
|
||||
## 数据语义
|
||||
|
||||
- `openclaw_version`: 远程服务器上的 OpenClaw 版本
|
||||
- `plugin_version`: 远程服务器上的 `harbor-forge` 插件版本
|
||||
|
||||
## 已废弃内容
|
||||
|
||||
以下旧方案已经废弃，不再作为实现路径：
|
||||
|
||||
- challenge UUID
|
||||
- `GET /monitor/public/server-public-key`
|
||||
- `POST /monitor/admin/servers/{id}/challenge`
|
||||
- `WS /monitor/server/ws`
|
||||
- challenge / nonce 握手逻辑
|
||||
|
||||
## 前端管理页要求
|
||||
|
||||
Monitor 管理页应提供：
|
||||
|
||||
- Add Server
|
||||
- Generate API Key
|
||||
- Revoke API Key
|
||||
- Delete Server
|
||||
|
||||
不再提供 `Generate Challenge`。
|
||||
|
||||
## 运行流程
|
||||
|
||||
1. 管理员在 Monitor 中注册服务器
|
||||
2. 管理员为服务器生成 API Key
|
||||
3. 将 API Key 写入 `~/.openclaw/openclaw.json`
|
||||
4. 如需本地桥接补充信息，配置 `monitor_port`
|
||||
5. 重启 OpenClaw Gateway
|
||||
6. 插件直接参与遥测链路；若本地桥接可达，则额外提供 OpenClaw 补充元数据
|
||||
|
||||
## 备注
|
||||
|
||||
当前保留了对旧 challenge 数据表的**删除兼容清理**（仅为兼容老数据库中的遗留数据），但不再保留 challenge 功能入口、WebSocket 方案或 sidecar 运行时逻辑。
|
||||
1745
archive/achieve/milestone-propose-requirements.md
Normal file
1745
archive/achieve/milestone-propose-requirements.md
Normal file
File diff suppressed because it is too large
Load Diff
54
archive/achieve/monitor-server-connector-plan.md
Normal file
54
archive/achieve/monitor-server-connector-plan.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Monitor Server Connector Plan
|
||||
|
||||
## Current design
|
||||
|
||||
The plugin and Monitor communicate over a local bridge port (`monitor_port` / `MONITOR_PORT`).
|
||||
|
||||
### Data flow
|
||||
|
||||
1. **Monitor → Plugin** (GET): Plugin queries `GET /telemetry` on the bridge for host hardware data.
|
||||
2. **Plugin → Monitor** (POST): Plugin pushes OpenClaw metadata via `POST /openclaw` to the bridge.
|
||||
3. **Monitor → Backend**: Monitor heartbeats to `POST /monitor/server/heartbeat-v2` with `X-API-Key`, enriched with any available OpenClaw metadata.
|
||||
|
||||
### Bridge endpoints (on Monitor, 127.0.0.1:MONITOR_PORT)
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/health` | GET | Health check, returns monitor version and identifier |
|
||||
| `/telemetry` | GET | Latest hardware telemetry snapshot |
|
||||
| `/openclaw` | POST | Receive OpenClaw metadata from plugin |
|
||||
|
||||
### Plugin behavior
|
||||
|
||||
- On `gateway_start`, plugin begins periodic metadata push (aligned with `reportIntervalSec`).
|
||||
- Initial push is delayed 2s to allow Monitor bridge startup.
|
||||
- If bridge is unreachable, pushes fail silently. Plugin remains fully functional.
|
||||
- On `gateway_stop`, periodic push is stopped.
|
||||
|
||||
## No longer used
|
||||
|
||||
The following design has been retired:
|
||||
|
||||
- challenge UUID / RSA handshake / WebSocket telemetry
|
||||
- Plugin-side `server/` sidecar process
|
||||
|
||||
## Heartbeat payload
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": "vps.t1",
|
||||
"openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
|
||||
"plugin_version": "0.2.0",
|
||||
"agents": [],
|
||||
"cpu_pct": 10.5,
|
||||
"mem_pct": 52.1,
|
||||
"disk_pct": 81.0,
|
||||
"swap_pct": 0.0,
|
||||
"load_avg": [0.12, 0.09, 0.03],
|
||||
"uptime_seconds": 12345,
|
||||
"nginx_installed": true,
|
||||
"nginx_sites": ["default"]
|
||||
}
|
||||
```
|
||||
|
||||
`openclaw_version`, `plugin_version`, and `agents` are optional enrichment from the plugin. If plugin never pushes metadata, these fields are omitted and the heartbeat contains only hardware telemetry.
|
||||
78
archive/achieve/openclaw-monitor-plugin-plan.md
Normal file
78
archive/achieve/openclaw-monitor-plugin-plan.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# HarborForge Monitor / OpenClaw Plugin Connector Plan
|
||||
|
||||
## 目标
|
||||
|
||||
使用 **API Key + HTTP heartbeat** 连接 HarborForge Monitor 与远程 OpenClaw 节点。
|
||||
|
||||
## 认证方式
|
||||
|
||||
- 管理员为服务器生成 API Key
|
||||
- 插件通过 `X-API-Key` 调用 heartbeat 接口
|
||||
- 不再使用 challenge / RSA 公钥 / WebSocket 握手
|
||||
|
||||
## 上报接口
|
||||
|
||||
`POST /monitor/server/heartbeat-v2`
|
||||
|
||||
### Headers
|
||||
- `X-API-Key: <server-api-key>`
|
||||
|
||||
### Payload
|
||||
```json
|
||||
{
|
||||
"identifier": "vps.t1",
|
||||
"openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
|
||||
"plugin_version": "0.1.0",
|
||||
"agents": [
|
||||
{ "id": "agent-bot1", "name": "agent-bot1", "status": "configured" }
|
||||
],
|
||||
"cpu_pct": 12.3,
|
||||
"mem_pct": 45.6,
|
||||
"disk_pct": 78.9,
|
||||
"swap_pct": 0,
|
||||
"load_avg": [0.12, 0.08, 0.03],
|
||||
"uptime_seconds": 12345
|
||||
}
|
||||
```
|
||||
|
||||
## 语义
|
||||
|
||||
- `openclaw_version`: 远程主机上的 OpenClaw 版本
|
||||
- `plugin_version`: `harbor-forge` 插件版本
|
||||
|
||||
## 插件生命周期
|
||||
|
||||
- 插件注册名为 `harbor-forge`
|
||||
- 不再启动独立 `server/telemetry.mjs` sidecar
|
||||
- 插件直接通过 Gateway/runtime 路径暴露 OpenClaw 元数据
|
||||
- 如配置了 `monitor_port`，插件还可通过本地桥接与 HarborForge.Monitor 交互
|
||||
|
||||
## 配置位置
|
||||
|
||||
`~/.openclaw/openclaw.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"harbor-forge": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"enabled": true,
|
||||
"backendUrl": "http://127.0.0.1:8000",
|
||||
"identifier": "vps.t1",
|
||||
"apiKey": "your-api-key",
|
||||
"monitor_port": 9100
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 已废弃
|
||||
|
||||
- challenge UUID
|
||||
- server public key
|
||||
- WebSocket telemetry
|
||||
- encrypted handshake payload
|
||||
Reference in New Issue
Block a user