Files
CCLite/docs/07_real_worker_access_audit.md
T
2026-07-05 23:40:12 +08:00

6.9 KiB
Raw Blame History

07 真实 Worker 最小接入审计

1. 审计结论

CCLite 0.1.10 已将真实 worker 审计从“参数是否存在”升级为“能力查询、真实 IPC attach 行为和协议对齐状态”三层检查。

当前结论为:

EXTERNAL_WORKERS_READY_CCLITE_PROTOCOL_ADAPTER_REQUIRED

含义是:

  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. FEMLite worker mock 仍可运行,当前输出为 CCLite worker completed: mock。
  5. CCLite 0.1.10 尚不声明真实外部 SPHLite/FEMLite 进程联调完成,因为 FEMLite 发布的 IPC 结构和命名规则与 CCLite 0.1.x 当前通用 command/data block 不完全一致,仍需要 CCLite 侧协议/命名 adapter 和进程级 gate。

2. CCLite 固化的 worker 参数

真实 worker 应至少支持:

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

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

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

FEMLite worker 额外使用:

--worker-backend ipc

这些参数用于补齐启动契约;它们不代表二进制协议已经自动兼容。

3. 当前真实 worker 审计结果

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

build-codex-gcc/output/real_worker_gap_report.json

当前审计报告包含:

  1. sphlite_capabilities:SPHLite 能力查询;
  2. femlite_capabilities:FEMLite 能力查询;
  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 已发布协议的对齐状态。

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

4. 协议对齐状态

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

command block: CCLite generic command block v1
data header:   CCLite generic data block header v0.1
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 进程联调仍需要 CCLite 侧 adapter gate 验收。

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.1.x 当前通用 block 不是同一二进制布局,因此 CCLite 后续必须增加外部协议 adapter 或统一 05 号接口控制文档中的二进制契约。

5. 0.1.10 验收口径

0.1.10 完成以下工程目标:

  1. CCLite 可自动读取 SPHLite/FEMLite 的 --cclite-capabilities 输出;
  2. 真实 worker attach 失败被识别为 IPC_ATTACH_ATTEMPTED,不再误判为参数缺失或未实现;
  3. FEMLite 新版 mock 输出 CCLite worker completed: mock 被识别为 WORKER_MOCK_AVAILABLE;
  4. 审计报告明确输出 CCLITE_PROTOCOL_ADAPTER_REQUIRED;
  5. CCLite 主控启动 worker 时补充 --command-block、--data-prefix、--worker-id,FEMLite 补充 --worker-backend ipc;
  6. 0.1.x 可执行验收路径仍由 CCLite 内置 mock worker 完成;
  7. 真实 SPH-FEM 接触力、真实外部双 worker 联调、摩擦、FSI 和 Linux/MPI 不在 0.1.10 中声明完成。

6. 后续接入条件

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

  1. 明确采用统一 CCLite 05 号通用 block,还是为 SPHLite/FEMLite 各自协议增加 adapter;
  2. 建立 真实 SPHLite + mock FEM 的 1 step 和 100 step 空耦合 gate;
  3. 建立 mock SPH + 真实 FEMLite 的 1 step 和 100 step 空耦合 gate;
  4. 建立 真实 SPHLite + 真实 FEMLite 的 1 step 和 100 step 空耦合 gate;
  5. 将能力查询、协议版本、record stride、block 容量和错误码纳入自动报告;
  6. 在上述 gate 通过前,不把 supports_real_ipc=yes 解释为真实外部联调完成。

7. 0.2.0 Adapter Gate 定义

0.2.x 进入基础接触算法开发时,真实 worker 接入作为独立 gate 管理,不阻塞 mock worker 上的 A 层接触算法验收。

Gate 编号:

V020_SINGLE_REAL_WORKER_SMOKE

0.2.x gate 至少要求推进以下路径:

  1. 真实 SPHLite + mock FEMLite,1 step 空耦合;
  2. mock SPHLite + 真实 FEMLite,1 step 空耦合;
  3. 至少一条单真实 worker 路径完成 100 step 空耦合;
  4. 真实 worker 导出的空或受控 interface block 通过 CCLite header、role、layout、record stride 和 step id 校验;
  5. 真实 worker 可接收空或受控 load block,并响应 IMPORT_LOADS、ADVANCE 和 STOP。

通过条件:

  1. worker 可由 CCLite 标准 worker CLI 启动;
  2. command seq/ack 全程匹配;
  3. 真实 worker 的 payload 经过与 mock worker 相同的 CCLite 校验;
  4. worker 无 timeout、异常退出或残留进程;
  5. 验证报告包含 worker 名称、版本、IPC 能力、block 能力和 gate 状态。

受控缺口条件:

  1. 外部求解器发布的 command block 与 CCLite generic command block 二进制布局不同;
  2. 外部求解器发布的 data header 与 CCLite generic data block header 二进制布局不同;
  3. 共享内存和 event 命名无法通过当前参数完全映射;
  4. record stride、block role 或错误码不能被当前 CCLite reader 验证。

出现上述情况时,0.2.x 应输出 CONTROLLED_PROTOCOL_GAP 或等价状态,并继续使用 mock worker 完成基础接触算法验收。该状态不能被写成真实 SPH-FEM 外部进程物理联调完成。