diff --git a/CALENDAR_DESIGN.md b/NEXT_WAVE_DEV_DIRECTION.md similarity index 77% rename from CALENDAR_DESIGN.md rename to NEXT_WAVE_DEV_DIRECTION.md index c528636..eefdf06 100644 --- a/CALENDAR_DESIGN.md +++ b/NEXT_WAVE_DEV_DIRECTION.md @@ -8,6 +8,13 @@ 为 HarborForge 新增日程表(Calendar)系统,支持 Agent/人类用户的任务调度、周期性计划、以及通过 OpenClaw 插件心跳自动唤醒 Agent 执行日程。 +同时记录一项项目结构调整: +- Propose 改名为 Proposal +- Proposal Accept 不再生成单个 Feature Task +- 改为在 Proposal 下维护多个 Essential;Accept 时将该 Proposal 下所有 Essential 按类型生成对应的 story task,并落到 Proposal 选择的 Milestone +- story 整个大类改为 restricted,只允许通过 Proposal Accept 创建 +- Essential 拥有独立的 EssentialCode,编码风格参考 ProjectCode / TaskCode 等既有结构 + 同时包含一个 bug fix:acc-mgr 用户密码不可修改,前端隐藏修改密码入口。 --- @@ -40,7 +47,7 @@ **Job:** ```json { - "type": "Task|Support|Meeting", + "type": "Task|Support|Meeting|Essential", "code": "TASK-42", "working_sessions": ["session-id-1", "session-id-2"] } @@ -283,7 +290,74 @@ hf user create [--agent-id ] [--claw-identifier ] ... --- -## 八、前端 +## 八、项目结构调整记录(与 Calendar 相关联的设计备注) + +### 8.1 命名调整 + +- `Propose` 统一改名为 `Proposal` + +### 8.2 新结构 + +```text +Project +└─ Proposal + ├─ Essential + │ ├─ feature + │ ├─ improvement + │ └─ refactor + └─ accept -> 将该 Proposal 下所有 Essential 生成对应类型的 story task,并创建到 Proposal 选择的 Milestone +``` + +### 8.3 Proposal Accept 语义变更 + +旧行为: +- Proposal Accept 后生成单个 `story/feature` task + +新行为: +- Proposal Accept **不再生成单个 Feature Task** +- 每个 Proposal 可维护多个 Essential +- Accept 时,遍历该 Proposal 下全部 Essential +- 按 Essential 类型映射生成对应的 story task: + - `feature` -> `story/feature` + - `improvement` -> `story/improvement` + - `refactor` -> `story/refactor` +- 生成目标 Milestone 由 Proposal 在 Accept 前或 Accept 时明确选择 + +### 8.4 Story 创建限制 + +- `story` 整个大类视为 **restricted** +- 任何 `story/*` task 都不允许通过通用 task create endpoint 直接创建 +- `story` 仅允许通过 `Proposal Accept` 工作流生成 + +### 8.5 Essential + +新增 `Essential` 概念,用于承载 Proposal 下的可落地核心条目。 + +建议字段: + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | int (PK) | | +| essential_code | VARCHAR(64), UNIQUE | EssentialCode,风格参考 ProjectCode / TaskCode / MilestoneCode / ProposalCode | +| proposal_id | FK -> proposals.id | 所属 Proposal | +| type | Enum(feature, improvement, refactor) | Essential 类型 | +| title | VARCHAR(255) | 标题 | +| description | TEXT, nullable | 描述 | +| created_by_id | FK -> users.id, nullable | 创建人 | +| created_at | datetime | 创建时间 | +| updated_at | datetime | 更新时间 | + +### 8.6 代码生成 + +- `Essential` 拥有独立 `EssentialCode` +- 编码规则参考现有类似结构,例如: + - `ProjectCode` + - `MilestoneCode` + - `TaskCode` + - `ProposalCode` +- 具体前缀与编号策略待后续单独定稿 + +## 九、前端 - 每个用户可查看/调整自己的日程表 - Admin 可查看/调整所有用户的日程表 @@ -291,16 +365,18 @@ hf user create [--agent-id ] [--claw-identifier ] ... --- -## 九、Bug Fix +## 十、Bug Fix - acc-mgr 用户:后端禁止修改密码(admin 也不行) - 前端:acc-mgr 用户不显示修改密码入口 --- -## 十、待定项 +## 十一、待定项 - Entertainment 事件子类型设计 - MinimumWorkload 存储方式(JSON 字段 vs 独立表) - 前端日程表 UI 详细设计 - Agent 唤醒的提示词模板 +- Proposal / Essential 的详细数据模型、API、前端页面与 accept 流程实现细节 +- Story restricted 后,现有 task create / propose accept / milestone flow 的兼容迁移策略 diff --git a/DEVELOPMENT_PLAN.md b/archive/achieve/DEVELOPMENT_PLAN.md similarity index 100% rename from DEVELOPMENT_PLAN.md rename to archive/achieve/DEVELOPMENT_PLAN.md diff --git a/archive/achieve/OPENCLAW_PLUGIN_DEV_PLAN.md b/archive/achieve/OPENCLAW_PLUGIN_DEV_PLAN.md new file mode 100644 index 0000000..3b684a1 --- /dev/null +++ b/archive/achieve/OPENCLAW_PLUGIN_DEV_PLAN.md @@ -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 运行时逻辑。 diff --git a/docs/milestone-propose-requirements.md b/archive/achieve/milestone-propose-requirements.md similarity index 100% rename from docs/milestone-propose-requirements.md rename to archive/achieve/milestone-propose-requirements.md diff --git a/archive/achieve/monitor-server-connector-plan.md b/archive/achieve/monitor-server-connector-plan.md new file mode 100644 index 0000000..2a2ae0b --- /dev/null +++ b/archive/achieve/monitor-server-connector-plan.md @@ -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. diff --git a/archive/achieve/openclaw-monitor-plugin-plan.md b/archive/achieve/openclaw-monitor-plugin-plan.md new file mode 100644 index 0000000..30d196c --- /dev/null +++ b/archive/achieve/openclaw-monitor-plugin-plan.md @@ -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: ` + +### 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