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

176 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 07 真实 Worker 最小接入审计
## 1. 审计结论
CCLite 0.1.10 已将真实 worker 审计从“参数是否存在”升级为“能力查询、真实 IPC attach 行为和协议对齐状态”三层检查。
当前结论为:
```text
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 应至少支持:
```text
<solver.exe> --cclite-worker --solver-id <SPH|FEM> --case <solver.inp> --ipc-name <prefix> --timeout-ms <milliseconds>
```
CCLite 0.1.10 启动 worker 时还会补充新版求解器可识别的辅助参数:
```text
--command-block <name>
--data-prefix <prefix>
--worker-id <SPH|FEM>
```
FEMLite worker 额外使用:
```text
--worker-backend ipc
```
这些参数用于补齐启动契约;它们不代表二进制协议已经自动兼容。
## 3. 当前真实 worker 审计结果
本地审计命令由 `Python/checkers/audit_real_workers.py` 执行,并生成:
```text
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 探测当前应表现为:
```text
status: IPC_ATTACH_ATTEMPTED
recognized_worker_cli: true
real_ipc_attach_attempted: true
```
FEMLite 标准 IPC worker 探测当前应表现为:
```text
status: IPC_ATTACH_ATTEMPTED
recognized_worker_cli: true
real_ipc_attach_attempted: true
```
FEMLite worker mock 探测当前应表现为:
```text
status: WORKER_MOCK_AVAILABLE
```
## 4. 协议对齐状态
CCLite 0.1.x 当前内部协议为:
```text
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 当前文档中的默认命名为:
```text
<ipc_name>.command
<ipc_name>.command_event
<ipc_name>.done_event
```
SPHLite 支持 `--command-block` 和 `--data-prefix` 覆盖部分名称,但真实外部 CCLite 进程联调仍需要 CCLite 侧 adapter gate 验收。
FEMLite 当前发布的真实 IPC worker 使用:
```text
<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 编号:
```text
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 外部进程物理联调完成。