# cube_tools

**Repository Path**: biparadox/cube_tools

## Basic Information

- **Project Name**: cube_tools
- **Description**: 基于cube架构实现的一些基础工具，包括模块创建，实例运行目录创建，头文件生成，消息记录文件生成，消息日志检查，实例信息实时获取等等
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cube_tools

独立工具层：**一族工具实例（cubeos）+ 一层管理脚本**。对外提供 `bin/cube` 单一入口（13 命令 CLI，接口 v0.12/v0.13——**门面外壳契约**）；**工具面 = `bin/_tool.sh` 16 工具统一分发器已全实现**（tools.json v1.2 机读注册表）。二者为**双形态关系**：门面 13 命令 = 工具子集的实例链封装（外壳契约，真实能力在 _tool.sh 直调分发；实例链仅 stat/version/help 具可执行形态，其余为 M2 占位），详见下文"实现进度"。

## 快速上手（迁移后：Linux 直连执行，无需 wsl 前缀）

```bash
# 全部命令在 Linux/WSL2 内直接执行，不再有 `wsl -d Ubuntu-22.04` 前缀
cd /home/player/cube_arch/cube_tools
bin/cube --help                       # 13 命令总览（stdout 恒单行信封 JSON，exit code ≡ 信封 result）
bin/cube version                      # 协议自述（result=0；hub.status 探测 13740）
bin/cube stat <dir> --direct          # 直调形态（逃生通道；不依赖实例链）
bin/cube stat <dir>                   # 实例链形态（B6 已通：result=0 信封 + run_report.json）
bash bin/_tool.sh test_unit --project-dir <dir> --task T1            # 工具面直调（16 工具，信封双落点 stdout+.tool_result）
bash bin/_tool.sh verify_hub_ctl --project-dir <dir> --op status     # 测试驱动中心生命周期（verify_proc :10098）
bash bin/_tool.sh driver_run --project-dir <dir> --task T1 --case-set user   # 回传式单测驱动（F R3A 按钮调用；judge 载体交付状态见下）
bash bin/tools-instance.sh status     # 工具实例治理（ensure/status/start/stop/restart/start-console）
```

- **环境通道**：`CUBEOS_ROOT` 可显式导出；缺省由门面自动推导（cube-ide/config/env.json 的 cubeos_root，回退 `../cubeos-1.5`）。
- **实例链现状（2026-08-22 B6 复验通过后）**：`stat` 实例链（console 三步链 → tools_hub :13740）**已通**——`bin/cube stat <dir>` 返回 result=0 信封 + `run/hub/run_report.json` 完成通知（C 层 B-1 sender 归一 + B-2 name 回退 sender 修复后，本层复验连续两次 result=0）。**C8 约束**：CMD_PARA para_value 现网字段 64B（安全 63B），超长参数门面显式报错并提示 `--direct`（运行目录/信封文件名已取短规避，见 bin/_facade_lib.sh 注释）；C 层 C8 扩容（para_value 128→512）落地后可放宽。每次实例链调用约 25s（console 驻留由门面 timeout 收割，设计形态）。
- **工具面 16 工具全实现（2026-08-30 实证）**：`bin/_tool.sh` 16 工具 case 全覆盖——module_make / module_create / header_gen / project_init / materialize / artifact_format / test_unit / test_integration / project_scan / artifact_stat / git_branch_op / git_show_file / instance_materialize / route_materialize / **verify_hub_ctl** / **driver_run**（= tools.json v1.2 机读注册表 16 条目；信封双落点 stdout + `{project_dir}/.tool_result/<tool>.json`（v1.13 Q1）；task_suffix 规则 T1-plaintext/空=无后缀；tool_tee_log L2 日志归档；hub_health_guard 观测链守卫）。
  - **R3A 窗口**（07 方案 08-24 批准）：`test_unit` 信封 data_fields 增 `unit.progress`/`unit.observe`；产物双源——方案 `test/unit/{task}/spec.json`（git 跟踪常驻）+ 结果 `R3/verify-unit[-{task}].json`（gitignore 可空，F 按 case id 回填，未执行显"⏳ 未执行"）。
  - **verify_hub_ctl**（tools.json #15）：测试驱动中心（verify_proc，10098 LISTEN + 13720 连出 debug_hub）生命周期 status/start/stop——B 层小脑按此运维；三处装配：`bin/steps/verify_hub_ctl.sh` + `cube-ide/scripts/verify_hub_ctl.sh` + `hub/ide_hub_3/cmd/verify_hub_ctl.cmd`。**待核对**：verify_hub_mode.sh（unit|integration 切换）当前工作区不存在（仅 origin/t1-plaintext 分支），R3A/R3B 模式切换语义悬空。
  - **driver_run**（tools.json #16）：24-方案 回传式单测驱动（judge 夹逼 + verify_hub 中心即时判定），F 层 R3A 运行按钮实际调用（app.js r3aRunUnit）；同步产出 `R3/verify-unit.json`（26-方案 F 回填契约，verdict_source=judge_verify）。**载体交付状态**：依赖的 judge 载体（judge_verify / combined_unit / driver_unit / exec_def 双 def / verify_hub_mode.sh）**仅存在于 `cube_projects/login_test` origin/t1-plaintext 分支（3f8306c），未部署到当前工作树**；部署快照 spec.json 无 test_items 字段（driver_run 读 test_items 取空）——使用前须核实交付。
- **门面 13 命令（双形态）**：门面命令解析/用法校验齐全；实例链仅 `stat`（lib/stat.sh + cmd/stat.cmd，M0/M1 批次）与 `version`/`help` 具可执行形态；其余 10 命令（scan/materialize/test/git/fmt/module_new/def2h/instance_new/route/project_new）实例链为 M2 批次待实现占位——`--direct` 返回 `result=2 "命令未实现"` 信封（见 docs/archive/工具开发方案-2026-08-18.md §五开发批次）——**门面是"外壳契约"，真实能力以 `_tool.sh` 16 工具直调分发为准**（B 适配层调用面 `bash cube <命令>` → 信封 不变）。

## 文档导览（现行权威源）

| 文档/机器源 | 内容 |
|---|---|
| [tools.json](tools.json)（v1.2，16 条目） | **机器权威源**：工具清单/参数/产物路径/日志通道/完成判据（F 层 app.js 已机读注册表，硬编码仅兜底） |
| [docs/盘点-cube_tools工具输入输出日志标准化-2026-08-21.md](docs/盘点-cube_tools工具输入输出日志标准化-2026-08-21.md)（v2.0） | tools.json 的 **source 文档**：四要素/日志三通道/完成判据/全工具盘点（12 工具 + v1.2 增量 2 条目）与缺口 G1-G12 状态 |
| [docs/cube_tools架构设计-2026-08-19.md](docs/cube_tools架构设计-2026-08-19.md)（v2.1 + §十三 增量） | **内部架构**：管理脚本/工具实例分层、实例接口登记表、脚本驱动时序、模块归属三分法（§十三 补 08-19 后增量：分项物化/双模式/测试驱动中心） |
| [docs/致cubeos-通用模块与架构修改建议-2026-08-19.md](docs/致cubeos-通用模块与架构修改建议-2026-08-19.md) | 转 cubeos 开发任务的建议件（纯净版，S1–S6；S2/S4/S5/S6/S7 已由 C 侧落地，S1/S3 批次四未启动——stat/scan 仍走 .cmd 过渡） |
| flowtest 契约（`cube_projects/work/contracts/login_test-flowtest-20260830-070559/{T,B,C}.out.md`） | **现行判定/工具契约**：verify_hub 主链（log_query→login_verify→IDE_VERIFY）、命中判据 result_code==-1、T-CAP-1~8、ENUM 名字文本序列化 |

其余 docs/ 内文档为**历史快照/过程性文档**：`接口定义-后端与工具-v0.12.md` 与 `工具开发方案-2026-08-18.md` 已移 [docs/archive/](docs/archive/)（历史契约，被 tools.json v1.2 + flowtest 契约取代）；回执/通知/排错/建议/交接系列（08-18~08-21）机制结论均已定案，勿当现行操作流程读；`回应8-19-1` 结论已并入架构设计 §六/§九（勿当待决方案读）。

## 目录速查

```
bin/        管理脚本（cube 门面 / _tool.sh 16 工具分发器 / steps/*.sh 驱动步骤 / tools-instance.sh 实例治理）
define/     工具专用数据结构（TOOL/* 消息与记录）
src/        工具专用模块（instance_skeleton / template_render / result_report）
instance/   工具实例装配模板（tools_hub / trigger / module_tools / ...）
templates/  模板库（fmt 阶段模板 / 实例骨架 / 路由策略 / 项目骨架）
cmd/        cmd_exec 命令脚本库（.cmd）
plugin/     专用模块编译产物（gitignore）
run/        运行区：物化实例、run/<调用号>/、日志（gitignore）
skills/     T 层技能接收位（路径切面与配置可迁移 v1.2）
tools.json  工具机读注册表（v1.2，16 条目；F 层机读）
docs/       文档（docs/archive/ 为历史契约归档：接口定义-v0.12、工具开发方案-08-18）
```