# CCLite Worker Protocol 文档状态:0.8.x worker adapter 骨架说明 本文记录 SPHLite 侧 CCLite worker 入口的参数、状态、命令和错误语义。当前实现只完成 CLI 解析、纯逻辑状态/命令枚举和测试;Windows shared memory、named event 和真实 CCLite 联调仍未实现。 ## 1. CLI 参数 启用 worker: ```text sphlite.exe --cclite-worker --solver-id SPH --case sphlite.inp --ipc-name ``` 参数语义: | 参数 | 必填 | 默认值 | 含义 | |---|---:|---|---| | `--cclite-worker` | 是 | 无 | 进入 CCLite worker 模式 | | `--solver-id` | 否 | `SPH` | CCLite 侧识别的求解器 id | | `--case` | 是 | 无 | SPHLite 输入文件路径 | | `--ipc-name` | 是 | 无 | CCLite 分配的 IPC 基础名称 | | `--command-block` | 否 | 空 | command block 名称 | | `--data-prefix` | 否 | 空 | data block 名称前缀 | | `--log` | 否 | `sphlite_cclite_worker.log` | worker 日志路径 | | `--timeout-ms` | 否 | `30000` | 等待命令超时时间,必须为正整数 | | `--worker-id` | 否 | `sphlite` | worker 实例 id | `--cclite-worker` 与普通 CLI 参数 `--run`、`--check`、`--output`、`--version` 冲突。未启用 worker 时,普通 CLI 行为保持: ```text sphlite.exe model.inp sphlite.exe model.inp --check sphlite.exe model.inp --run --output result ``` 当前所有必填 worker 参数齐全时,程序会返回受控的 `UNSUPPORTED`,表示 IPC 阶段尚未实现。 ## 2. 状态枚举 | 状态 | 含义 | |---|---| | `CREATED` | worker 对象已创建但未 ready | | `READY` | worker 可接收命令 | | `RUNNING` | 命令执行中,预留给真实 IPC 主循环 | | `DONE` | 当前命令已完成并可写 ack | | `ERROR` | 当前命令失败或进入错误态 | | `STOPPED` | 收到 `STOP` 后停止 | ## 3. 命令枚举 | 命令 | 处理流程 | |---|---| | `INIT` | 清理 worker 侧状态;允许从 `ERROR` 恢复到可继续状态 | | `READ_INPUT` | 后续映射到 `sphlite_read_inp` | | `BUILD_MODEL` | 后续映射到 `sphlite_build_model` | | `EXPORT_INTERFACE` | 后续映射到 coupling region count/info、particle export 和 facet export | | `IMPORT_LOADS` | 后续映射到 particle force、facet pressure/traction/resultant、contact state 和 motion boundary 导入 | | `ADVANCE` | 后续映射到 `sphlite_advance_explicit` 或 worker 控制的子步循环 | | `WRITE_OUTPUT` | 后续映射到 `sphlite_write_output` | | `STOP` | 写入完成状态后退出 worker | 未知命令进入 `ERROR`,错误码为 `UNKNOWN_COMMAND`。 ## 4. Ack 和错误 ack 序号只接受严格递增的 command sequence: ```text command_sequence > last_ack_sequence ``` 错误码: | 错误码 | 含义 | |---|---| | `OK` | 命令成功 | | `ARGUMENT` | CLI 参数或内部参数错误 | | `CONFLICT` | 当前状态与命令冲突 | | `UNSUPPORTED` | 入口已识别,但当前能力未实现 | | `TIMEOUT` | 等待命令超时 | | `IPC` | IPC 打开、读取、写入或 signal/wait 失败 | | `UNKNOWN_COMMAND` | command id 未识别 | | `INTERNAL` | 其他内部错误 | 超时处理固定进入 `ERROR`,错误码为 `TIMEOUT`。已经 `STOPPED` 后收到除进程退出外的命令,固定保持 `STOPPED` 并返回 `CONFLICT`。