- gRPC：控制平面与 Agent 之间的主要契约，也是推荐的服务间集成方式。
- HTTP/JSON：面向用户的接口（流水线、运行、身份、设置等），由 UI 与外部 自动化使用。
- WebSocket：日志与状态的推送通道。
gRPC 服务
Proto 定义位于api/ 目录，使用
Buf 管理。共五个服务模块（路径形如 */v1）：
Agent 服务要点
Heartbeat、Register、Unregister：Agent 生命周期。FetchStepRun：Agent 主动拉取与自身标签匹配的 StepRun。ReportStepRunStatus、CancelStepRun：双向状态流。UpdateLabels：在线动态更新标签，无需重启。Connect：Agent 与 Gateway 之间的双向控制通道。
Gateway 服务要点
PushLogs：高吞吐、批量、容忍丢失的日志流。PushEvents：可靠、幂等、可重试且支持部分接受的事件流。
Pipeline 服务要点
CRUD 加运行控制：CreatePipeline、UpdatePipeline、GetPipeline、
ListPipelines、DeletePipeline、TriggerPipeline、StopPipeline、
GetPipelineRun、ListPipelineRuns。触发方式覆盖 manual、cron/调度、
event/Webhook。
StepRun 服务要点
CRUD 加执行控制：CreateStepRun、GetStepRun、ListStepRuns、
UpdateStepRun、DeleteStepRun、CancelStepRun、RetryStepRun、
ListStepRunArtifacts。Step 支持插件动作、重试策略、产物收集、按标签路由
以及 when 条件表达式。
Stream 服务要点
StreamStepRunStatus、StreamJobStatus、StreamPipelineStatus：状态实时 推送。AgentChannel：Agent 与 Server 双向通道。StreamAgentStatus、StreamEvents：Agent 在线情况与系统事件。
arcentra.<对象>.<生命周期> 模式，例如
arcentra.step.started、arcentra.pipeline.failed。
生成 gRPC 客户端
使用 Buf 生成代码：HTTP API
HTTP API 由控制平面提供，默认监听:8080。所有接口需要 Bearer Token：
code、msg、可选 detail 与 timestamp；
错误使用 errMsg 与 path 替代 detail。
/api/v1/pipelines/... 是最常用的 HTTP 端点，详细请求/响应字段见
流水线。
其他常见的 HTTP 模块：
- 身份与设置：用户、角色、租户管理。
- 项目与上传：项目增删改查与资源上传。
- Agent：Agent 列表与标签查询。
internal/control
中的注册情况为准。
WebSocket 网关
WebSocket 入口为GET /api/v1/ws（WebSocket 握手使用 HTTP GET）。
请求格式
channel必填：channel_log/channel_status。action默认subscribe。params必填，pipelineId、jobId、stepRunId都需要传入。
响应格式
日志通道（channel_log）
Log 字段：
状态通道（channel_status）
status_snapshot：来自数据库（t_step_run）的初始快照。status：StepRun 仍在运行（状态1/2/3）时的 Kafka 实时事件。unsubscribed：取消订阅响应。error：错误。