Files
CCLite/docs/07_real_worker_access_audit.md
T

141 lines
5.3 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` 解释为真实外部联调完成。