# cube-backend

**Repository Path**: haoj1eliang/cube-backend

## Basic Information

- **Project Name**: cube-backend
- **Description**: cube_platform项目的新版后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cube-backend —— 后端层（B 层）

> **定位**：五层架构（A/C/T/B/F，不含 G）的 **B 层——手-眼-小脑后端**：
> 手 = tools_hub（执行器，TCP 13710）、眼 = debug_hub（观测采集，TCP 13720）、
> 脑 = ide_hub_3（编排判定，WS 13999 前端入口）。
> **前身**：`cube-ide`（2026-08-31 更名/重构落点；旧目录/仓库已归档冻结）。
> **目录**：`/home/player/cube_platform/cube-backend`（gitee: `biparadox/cube-backend`）。

---

## 一、定位与架构

```
需求链（自上而下）：F（cube-front）→ B（本仓库）→ T（cube_tools）→ C（cubeos 基座）
能力链（自下而上）：C → T → B → F（产物信封 / IDE_VERIFY / FILE_TRANS / DEBUG_CONN）
```

| 层 | 仓库 | 角色 |
|---|---|---|
| A | cube_arch-1.5.2(-release) | 架构层：库/模块/主程序，**只读**（check-release-readonly.sh 校验） |
| C | cubeos 基座（并入 A 库） | 通用模块层：websocket_channel 等 |
| T | cube_tools | 工具层：project_scan / project_check / switch_check / module_make …（`bin/_tool.sh` + 信封） |
| **B** | **cube-backend（本仓库）** | **后端层：手-眼-小脑；cmd 操作契约；WS 13999** |
| F | cube-front | 前端层：交互 / 状态 / 渲染（FrameState SSOT） |

本仓库为**纯后端**：前端 UI / IDE 平台层构件已随 cube-ide → cube-backend 重构剔除归档（2026-09-02）。

## 二、目录结构

```
cube-backend/
├── config/                 # env.json（P1 契约单源：路径/端口/拓扑唯一权威）+ schema
├── hub/                    # 三 hub 实例 + exec_def 启动定义 + cmd 模板 + lib
├── scripts/                # 启动/看门狗/console 兜底/工具适配脚本
├── src/                    # 后端模块源码（ide_context / hello_ide；make → plugin/）
├── plugin/                 # 编译产物落点（*.so/*.cfg，不入库，见 .gitignore）
├── docs/                   # 后端设计文档 + 接口契约（docs/api/ 当前版）
│   └── interaction/        # 协同交互区（原 interaction 分支并入，见 cube-front/interaction）
├── skills/                 # B 层运维技能（08-30 skills-review 收敛 6 条后端专属）
├── define/  include/       # ide_define（B 层共享定义/头文件）
└── set_env.sh  env_build.sh # 应用环境 / 编译入口
```

## 三、三 hub（手-眼-脑）

| hub | 角色 | 端口 | 进程 | def |
|---|---|---|---|---|
| tools_hub | 手（执行器） | TCP 13710 | tools_proc | `hub/exec_def/_tools_hub.def` |
| debug_hub | 眼（观测采集） | TCP 13720 | debug_proc | `hub/exec_def/_debug_hub.def` |
| ide_hub_3 | 脑（编排判定，WS 入口） | WS 13999 | monitor_proc | `hub/exec_def/_ide_hub_3.def` |

启动（三 hub 必须同批）：

```bash
# ① 未激活环境（兜底单源 = config/env.json，端口 13710/13720/13999）
bash /home/player/cube_platform/cube-backend/scripts/start_ide_3hub.sh background

# ② 激活环境（推荐：环境运行根 + 独立端口段；基座单源=env/<env>/env.json 的 base_root）
CUBE_ENV_ROOT=/home/player/cube_platform/env/<env> \
  bash /home/player/cube_platform/cube-backend/scripts/start_ide_3hub.sh background
```

> **目录名口径（2026-09-12 修正）**：基座检出目录为**下划线** `cube_arch-1.5.2-release`
> （与 dev 树 `cube_arch-1.5.2` 同族）；连字符 `cube-arch-1.5.2-release` 只是**远端仓库名**，**不当路径用**。
> 路径口径唯一权威 = `config/env.json` 的 `cubeos_root`（或激活环境的 `base_root`）；P1 含基座**存在性**判据（`4.5.1b`）。

- 启动自带 P1 校验：根单源 / **基座存在性** / 三 hub def 同批 / cmd 零旧树 / CUBE_TOOLS_BIN 注入 / 构建指纹。
- 停止：**`bash scripts/stop_ide_3hub.sh`**（按 HUB_ROOT 全路径归属核对，只停本环境；
  `--status` 只看不停）。`scripts/cleanup_procs.sh` 为**兜底**手段（按 cwd/def 精准清理，
  `--force` 需二次确认），**首选 `stop_ide_3hub.sh`**。
- 看门狗：`scripts/hub_watchdog.sh startbg`；console 兜底：`scripts/console_send_msg.sh`。

### 三 hub 职责（P4 收口）与 WS 单槽纪律（P3）

- 手只执行、眼只观测、脑只编排（P4，2026-08-31 对齐）；纪律全文见 `docs/interaction/collaboration.md`。
- WS 单槽（13999 单连接，禁探测，指数退避）；CLOSE-WAIT 已知缺陷登记 A-layer-debug-request-4。

## 四、契约与协同

- **P1 契约单源**：`config/env.json`（路径/端口/基座依赖唯一权威；cmd 模板经 `${CUBE_TOOLS_BIN}` 注入）。
- **B 层路径变量（B21，D 层裁定 6 / G-2）**：**`CUBE_B_PATH`** = 本仓根，头面 = `$(CUBE_B_PATH)/include`；
  另有派生 `CUBE_B_INCLUDE`。供给面三处齐备：`scripts/_lib.sh`（角色锚点段）、`set_env.sh`（编译入口）、
  三 hub `exec_def`（实例级显式声明）＋ `start_ide_3hub.sh` 运行态注入。
  用例侧模块若依赖 B 层头，须**显式声明外部依赖**（短名 **`B`** ↔ 映射键 **`CUBE_B_PATH`**，
  与 `CUBE_<N>_PATH` 约定一致）；**禁止**用未定义变量（旧写法 `$(CUBE_IDE_ROOT)` 在"只 source 基座"
  的构建流程里会展开成 `-I/include` **静默降级**）。判据件：`bash scripts/check_b_path.sh`（5 判据）。
- **协同交互区**：`docs/interaction/`（原 interaction 分支并入；前后端请求-回执对账，
  与 `cube-front/interaction/` 两区互映）。
- **接口契约**：`docs/api/`（当前版 `接口定义-前端与后端-v1.15.md`、`后端与工具-v0.13.md`；
  历史版本已归档至 git 历史）。
- **工具层**：`cube_tools/`（bin/_tool.sh + 信封）；**前端**：`cube-front/`。

## 五、开发与技能

- 编译模块：`bash env_build.sh`（src/ → plugin/*.so + *.cfg；产物不入库）。
- 技能沉淀：`skills/`（B 层排障/运维 6 条；历史移交条目去向见 skills/README 登记）。

## 六、历史（cube-ide → cube-backend）

- 2026-08-31：更名/重构落点（前端 P1-P4 协同需求回执），交互区先行。
- 2026-09-02：目录更名 cube-ide → cube-backend 收敛；main 纯化（剔除 archive/ui-legacy 旧前端、
  figure/、docs/archive、skills/archive 已移交条目、plugins/ 前端构件、scripts/legacy、
  docs/api/history 历史版本、plugin/*.so 编译产物）；gitee `cube-ide` 仓库归档冻结。
- 历史内容如需回看：git 历史可回溯；移交技能见对应仓库（cube-exchange / cube-frontend-op / cube_tools）。