docs: archive completed plans and rename next wave doc

2026-03-29 11:17:48 +00:00
parent 27696c70f9
commit c2b9242aca
6 changed files with 289 additions and 4 deletions
--- a/NEXT_WAVE_DEV_DIRECTION.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 <username> [--agent-id <id>] [--claw-identifier <id>] ...

 ---

-## 八、前端
+## 八、项目结构调整记录（与 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 <username> [--agent-id <id>] [--claw-identifier <id>] ...

 ---

-## 九、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 的兼容迁移策略
--- a/archive/achieve/DEVELOPMENT_PLAN.md
+++ b/archive/achieve/DEVELOPMENT_PLAN.md
--- a/archive/achieve/OPENCLAW_PLUGIN_DEV_PLAN.md
+++ 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 运行时逻辑。
--- a/archive/achieve/milestone-propose-requirements.md
+++ b/archive/achieve/milestone-propose-requirements.md
--- a/archive/achieve/monitor-server-connector-plan.md
+++ 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.
--- a/archive/achieve/openclaw-monitor-plugin-plan.md
+++ 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: <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