Files
CCLite/docs/07_real_worker_access_audit.md
2026-07-06 09:45:38 +08:00

7.6 KiB
Raw Permalink Blame History

07 真实 Worker 最小接入审计

1. 审计结论

CCLite 0.2.9 将真实 worker 审计提升为 V020_SINGLE_REAL_WORKER_SMOKE gate。0.2.10 发布候选继续复用该 gate 作为真实 worker 接入边界。该 gate 的目的不是声明真实 SPHLite/FEMLite 外部进程物理联调完成,而是确认当前 worker 能力、统一入口、协议差异和后续 adapter 缺口。

当前结论为:

EXTERNAL_WORKERS_READY_CCLITE_PROTOCOL_ADAPTER_REQUIRED
gate_status: CONTROLLED_PROTOCOL_GAP

含义如下:

  1. SPHLite 已提供 --cclite-capabilities,并报告 cclite_worker=yes、supports_real_ipc=yes、supports_sph_to_ccl_particle=yes、supports_ccl_to_sph_force=yes。
  2. FEMLite 已提供 --cclite-capabilities,并报告 cclite_worker=yes、worker_mock=yes、supports_real_ipc=yes、supports_fem_to_ccl_facet=yes、supports_ccl_to_fem_load=yes。
  3. 两个 worker 在没有 CCLite 预创建 IPC 资源时均会尝试打开真实 IPC,并返回可识别的 attach/open 失败,而不是参数缺失或未实现。
  4. CCLite 0.2.9 选择“混合过渡”策略:CCLite 内部继续使用 05 号接口文档定义的通用 command/data block;真实 SPHLite/FEMLite 外部边界通过求解器专用 adapter 对齐命名、二进制布局、payload 和错误码。
  5. 在 adapter 的进程级测试通过前,真实 worker gate 输出 CONTROLLED_PROTOCOL_GAP,mock worker 仍是 0.2.x 基础接触算法的可执行验收路径。

2. 固化的 worker 入口

真实 worker 至少应支持:

<solver.exe> --cclite-worker --solver-id <SPH|FEM> --case <solver.inp> --ipc-name <prefix> --timeout-ms <milliseconds>

CCLite 启动 worker 时还会补充新版求解器可识别的辅助参数:

--command-block <name>
--data-prefix <prefix>
--worker-id <SPH|FEM>

FEMLite worker 额外使用:

--worker-backend ipc

这些参数只说明启动入口已经统一,不代表二进制通信协议已经完全兼容。

3. Adapter 策略

0.2.9 确认采用:

HYBRID_GENERIC_BLOCK_PLUS_SOLVER_ADAPTER

策略说明:

  1. CCLite 内部契约保持统一:generic command block v1、generic data block header、AoR v1 payload、CCLite 负责资源创建和销毁。
  2. 外部真实 worker 边界增加求解器专用 adapter:SPHLite adapter 主要处理命名和 command/data 对齐;FEMLite adapter 还必须处理已发布的 native compact header。
  3. 不采用“只按求解器协议分叉”的原因是 controller、mock worker、诊断和接触算法已经共享同一套 CCLite 数据模型,分叉会复制校验逻辑。
  4. 不在 0.2.9 直接声明“通用 block 已接通”的原因是当前外部 worker 发布的对象命名和至少 FEMLite 的二进制 header 与 CCLite generic block 不一致。

后续 adapter 必须覆盖:

  1. command block name、command event、done/ack event 映射;
  2. command id、seq/ack、worker state 和 error code 映射;
  3. data header magic、version、layout、role、stride、capacity 映射;
  4. 空 payload 和可控 payload 的读取校验;
  5. 空 load block 和可控 load block 的 IMPORT_LOADS 导入校验;
  6. timeout、异常退出和资源释放映射。

4. 当前审计结果

本地审计命令由 Python/checkers/audit_real_workers.py 执行,并生成:

build-codex-gcc/output/real_worker_gap_report.json

0.2.9 还增加 gate checker:

Python/checkers/check_v020_real_worker_gate.py
build-codex-gcc/output/v020_real_worker_gate/verification_report.json

当前报告包含:

  1. adapter_strategy:CCLite adapter 策略;
  2. worker_capability_summary:worker 名称、版本探测、IPC 能力、block 能力和缺口状态;
  3. sphlite_standard_ipc:SPHLite 标准 worker 参数 attach 探测;
  4. femlite_standard_ipc:FEMLite 标准 worker 参数 attach 探测;
  5. femlite_explicit_ipc_backend:FEMLite --worker-backend ipc attach 探测;
  6. femlite_worker_mock:FEMLite 自运行 worker mock 探测;
  7. protocol_alignment:CCLite 当前协议与外部 worker 已发布协议的对齐状态;
  8. v020_adapter_gate:0.2.9 单真实 worker gate 的逐项结果。

SPHLite 标准 IPC worker 探测当前应表现为:

status: IPC_ATTACH_ATTEMPTED
recognized_worker_cli: true
real_ipc_attach_attempted: true

FEMLite 标准或显式 IPC worker 探测当前应表现为:

status: IPC_ATTACH_ATTEMPTED
recognized_worker_cli: true
real_ipc_attach_attempted: true

FEMLite worker mock 探测当前应表现为:

status: WORKER_MOCK_AVAILABLE

5. 协议对齐状态

CCLite 0.2.x 当前内部协议为:

command block: CCLite generic command block v1
data header:   CCLite generic data block header
control name:  <prefix>_CCL_COMMAND_<solver>
event names:   <prefix>_EVENT_COMMAND_<solver>, <prefix>_EVENT_ACK_<solver>
data names:    <prefix>_<ROLE>

SPHLite 当前默认命名为:

<ipc_name>.command
<ipc_name>.command_event
<ipc_name>.done_event

SPHLite 已支持 --command-block 和 --data-prefix 覆盖部分名称,但仍需要 CCLite adapter gate 验证完整 command/data 行为。

FEMLite 当前真实 IPC worker 使用:

<prefix>_COMMAND_BLOCK
<prefix>_COMMAND_EVENT
<prefix>_DONE_EVENT
<data-prefix>_FEM_TO_CCL_FACET
<data-prefix>_CCL_TO_FEM_LOAD

并在 FEMLite/cpu_release/include/femlite_cclite_ipc.h 中发布 femlite_cclite_command_block 和 femlite_cclite_data_header。这些结构与 CCLite 0.2.x 当前 generic block 不是同一二进制布局,因此必须增加外部协议 adapter 或统一 05 号接口控制文档中的二进制契约。

6. 0.2.9 Gate 结果

Gate 编号:

V020_SINGLE_REAL_WORKER_SMOKE
路径 当前状态 说明
真实 SPHLite + mock FEMLite,1 step 空耦合 CONTROLLED_PROTOCOL_GAP SPHLite 可识别 worker CLI 并尝试真实 IPC attach,但 CCLite 尚未执行命名和 block adapter
mock SPHLite + 真实 FEMLite,1 step 空耦合 CONTROLLED_PROTOCOL_GAP FEMLite 可识别 worker CLI 并尝试真实 IPC attach,但 native header 和命名与 CCLite generic block 不一致
单真实 worker,100 step 空耦合 CONTROLLED_PROTOCOL_GAP 依赖至少一条 1 step adapter 路径通过;当前不声明 seq/ack、timeout 或资源释放已验证
真实 worker payload 读取 smoke CONTROLLED_PROTOCOL_GAP 真实 worker export header 尚未映射为 CCLite generic data header,stride/role/step 无法由当前 reader 验证
真实 worker load import smoke CONTROLLED_PROTOCOL_GAP 真实 worker load header 尚未由 CCLite generic load block 映射,IMPORT_LOADS 响应未进入进程级验证

CONTROLLED_PROTOCOL_GAP 是 0.2.9 的可接受 gate 结果,前提是报告必须列出 worker 能力、已探测行为和阻塞字段。该状态不等价于真实 SPH-FEM 外部进程物理联调完成。

7. 后续接入条件

进入真实外部 worker 空耦合前,CCLite 侧必须完成:

  1. SPHLite 命名和 command/data adapter;
  2. FEMLite native header 和命名 adapter;
  3. 真实 SPHLite + mock FEMLite 的 1 step 和 100 step 空耦合 gate;
  4. mock SPHLite + 真实 FEMLite 的 1 step 和 100 step 空耦合 gate;
  5. 真实 worker payload header、role、layout、record stride、step id 校验;
  6. 真实 worker 空 load 或可控 load 的 IMPORT_LOADS、ADVANCE、STOP 校验;
  7. 资源释放、timeout、异常退出和残留进程检查。

在上述 gate 通过前,supports_real_ipc=yes 只能解释为 worker 具备真实 IPC 后端能力,不能解释为 CCLite 与真实 SPHLite/FEMLite 的完整进程级耦合已完成。