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

183 lines
7.6 KiB
Markdown
Raw Permalink 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.2.9 将真实 worker 审计提升为 `V020_SINGLE_REAL_WORKER_SMOKE` gate。0.2.10 发布候选继续复用该 gate 作为真实 worker 接入边界。该 gate 的目的不是声明真实 SPHLite/FEMLite 外部进程物理联调完成,而是确认当前 worker 能力、统一入口、协议差异和后续 adapter 缺口。
当前结论为:
```text
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 至少应支持:
```text
<solver.exe> --cclite-worker --solver-id <SPH|FEM> --case <solver.inp> --ipc-name <prefix> --timeout-ms <milliseconds>
```
CCLite 启动 worker 时还会补充新版求解器可识别的辅助参数:
```text
--command-block <name>
--data-prefix <prefix>
--worker-id <SPH|FEM>
```
FEMLite worker 额外使用:
```text
--worker-backend ipc
```
这些参数只说明启动入口已经统一,不代表二进制通信协议已经完全兼容。
## 3. Adapter 策略
0.2.9 确认采用:
```text
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` 执行,并生成:
```text
build-codex-gcc/output/real_worker_gap_report.json
```
0.2.9 还增加 gate checker:
```text
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 探测当前应表现为:
```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
```
## 5. 协议对齐状态
CCLite 0.2.x 当前内部协议为:
```text
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 当前默认命名为:
```text
<ipc_name>.command
<ipc_name>.command_event
<ipc_name>.done_event
```
SPHLite 已支持 `--command-block` 和 `--data-prefix` 覆盖部分名称,但仍需要 CCLite adapter gate 验证完整 command/data 行为。
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.2.x 当前 generic block 不是同一二进制布局,因此必须增加外部协议 adapter 或统一 05 号接口控制文档中的二进制契约。
## 6. 0.2.9 Gate 结果
Gate 编号:
```text
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 的完整进程级耦合已完成。