Metadata-Version: 2.1
Name: adp-operator
Version: 1.1.95
Summary: ADP operator management and C2C runtime tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: docker
Requires-Dist: fastapi
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: pyarmor
Requires-Dist: psutil
Requires-Dist: python-dotenv
Requires-Dist: python-multipart
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: uvicorn
Requires-Dist: colorlog
Requires-Dist: watchdog
Requires-Dist: websockets
Requires-Dist: clickhouse-driver

# ADP Operator

## C2C 连接首包

C2C TCP 连接建立后，双方必须先交换固定长度的二进制首包。首包校验通过后，连接才允许继续处理 JSON 业务指令。

首包固定为 512 bit，结构如下：

| bit 偏移 | bit 长度 | 字段 | 规则 |
| ---: | ---: | --- | --- |
| 0 | 24 | 固定标识 | 三个 ASCII 字符 `ADP` |
| 24 | 16 | 协议版本 | 16-bit 无符号整数，使用大端序，当前版本为 `7` |
| 40 | 256 | 实例编号 | 当前节点的 `instance_id`，固定32字节 |
| 296 | 8 | 功能控制区 | bit 0–2为功能开关，bit 3–7为保留位 |
| 304 | 208 | 全零保留区 | 必须全部为 `0` |

字符串字段统一使用 UTF-8 编码。字段长度不足时在尾部使用 `0x00` 填充，超过字段长度时按字段长度截断。

### 功能控制区

功能控制区固定为8 bit，每个功能占用一个 bit：

| bit | 功能 | `0` | `1` | 当前默认值 |
| ---: | --- | --- | --- | --- |
| 0 | UDP 主动发现 | 关闭 | 开启 | `1` |
| 1 | 额外 channel 通道 | 不支持 | 支持 | `1` |
| 2 | WebSocket 业务端口 | 关闭 | 开启 | `1` |
| 3–7 | 保留位 | 必须为零 | 不允许 | `0` |

当前默认控制区的二进制内容为：

```text
00000111
```

### 握手流程

1. TCP 客户端连接 C2C 服务端。
2. 客户端发送自己的 512 bit 二进制首包。
3. 服务端读取并校验完整首包。
4. 服务端校验通过后，向客户端返回自己的 512 bit 二进制首包。
5. 客户端校验服务端首包。
6. 双方校验均通过后，才开始发送 JSON 业务指令。

服务端会拒绝以下连接：

- 首包长度不足 512 bit；
- 固定标识不是 `ADP`；
- 目标节点协议版本低于发起连接节点的协议版本；
- `instance_id` 为空；
- 字符串字段的补零格式错误；
- 功能控制区保留位非零；
- 208 bit 全零保留区存在非零数据。

该首包适用于 C2C 直连、反向连接、多跳转发、额外 channel 通道、外部 `C2CSession` 和本地服务探测。未实现该二进制首包的旧节点无法与新协议节点建立连接，因此升级时需要同时更新同一网络中的全部 C2C 节点。

协议版本字段固定为16 bit，使用大端序表示无符号整数，取值范围为 `0`–`65535`。客户端收到服务端首包后比较版本：目标节点版本大于或等于本机版本时允许连接，目标节点版本低于本机版本时拒绝连接。例如本机版本为 `4`、目标版本为 `5` 时允许连接；本机版本为 `5`、目标版本为 `4` 时拒绝连接。

## C2C JSON 指令模型

本节只描述 JSON 控制指令，不包含文件、HTTP Body 或 Operator Channel 接管连接后的二进制数据流。C2C 指令需要同时按照寻址方式、响应模型和传播方式理解。

### 寻址方式

#### 当前节点处理

没有目标节点、也不需要向网络扩散的指令由当前入口节点直接处理，例如 `identify`、`discover`、`shutdown` 和 `close_session`。`discover` 返回当前节点已经掌握的注册表，但不会主动广播一次发现请求。

#### 自动路由的有指向指令

有指向指令使用 `identifier` 指定最终目标的 `node_id` 或 `instance_id`：

```json
{
  "type": "info",
  "identifier": "AdpCpuDispatch"
}
```

目标是当前节点时直接处理；目标不是当前节点时，通过 `route_probe` 主动寻找一条真实可达路径，然后转发原始指令。`run`、`call`、`info`、`kill`、`sync_files`、`hidden`、`visible` 和 `channel` 都可以使用这种模式。

`route_probe` 返回的 `route` 只包含探测请求实际经过的 `instance_id`。注册表中的 `via`、远端服务目录或历史可达信息只能用于选择探测方向，不能用于拼接或压缩返回路径。因此返回路径中的任意两个相邻实例都必须能够作为实际业务转发的相邻跳。`route_probe` 收到第一条有效路径后立即返回，不等待全网结果，也不保证该路径最短。

#### 指定路径的有指向指令

`route` 不是新的业务指令，而是有指向指令的路由模式：

```json
{
  "type": "call",
  "identifier": "target-instance-id",
  "route": [
    "source-instance-id",
    "next-hop-instance-id",
    "target-instance-id"
  ]
}
```

每一跳按照 `route` 指定的下一实例转发，最终由 `identifier` 对应的实例执行。已经获得明确路径时使用该模式可以避免重复探测。

公开的 Python API 接受包含发起节点在内的完整 `instance_id` 路径。底层发送时会自动去掉本地实例，不需要调用方再提供 `identifier`、`strict_route` 或重复的目标实例参数：

```python
routes = session.route_probe_group("UniversalParser")
target = routes[0]

result = session.run({
    "operator_name": "UniversalParser",
    "route": target["route"],
    # 其他运行参数
})
```

`run()` 会自动补充顶层 `type = "run"`。`transfer_file()` 和 `sync_files()` 同样接受可选的 `route=`：

```python
session.transfer_file(
    "UniversalParser", source_path, "input.pdf",
    route=target["route"],
)
session.sync_files(
    "UniversalParser", ["input.pdf"],
    route=target["route"],
)
```

省略 `route` 时保持原有行为：按 `operator_name` 主动探测并使用第一条有效路径。

传入的明确 `route` 只用于锁定目标实例，不是永久缓存。如果本地目录已经找不到旧路径的下一跳，发送端或中间节点会使用 `route` 最后一项的 `instance_id` 重新执行 `route_probe`，再沿新路径继续原指令。重新寻址不会按同名 `operator_name` 换成另一个实例。

#### 无指向指令

无指向指令不指定唯一执行节点，但其停止条件和结果处理方式不同：

| 模式 | 指令 | 行为 |
| --- | --- | --- |
| 首个确认 | `probe` | 默认取最先到达的有效 `probe_ack`，保持原有低延迟行为 |
| 窗口内全部确认 | `probe(multiple=True)` | 迭代返回探测窗口内的 `probe_ack`，以 `probe_end` 结束 |
| 首条路径 | `route_probe` | 在网络中寻找指定身份，返回第一条有效路径 |
| 同名实例路径集合 | `route_probe_group` | 搜索内部网络和本地 Bridge 可达网络，返回全部同名实例的真实路径 |
| 全量聚合 | `scan` | 在响应窗口内收集所有扫描节点的结果，依次合并并去重 |
| 注册表扇出聚合 | 无 `identifier` 的 `kill` | 向当前已知节点发送终止请求，合并终止数量和错误 |
| 全域广播 | `event` | 所有可达节点处理并继续传播，每一跳只返回传输确认，不收集业务结果 |

`scan` 和 `kill` 都会合并多个结果，但实现不同：`scan` 是具有 TTL 和请求去重的网络传播波；`kill` 根据当前注册表向已知节点扇出有指向请求。

### 响应模型

| 响应模型 | 指令示例 | 响应方式 |
| --- | --- | --- |
| 单目标单响应 | `info`、`identify`、`discover`、`shutdown`、`hidden`、`visible` | 返回一个 ACK 后结束 |
| 单目标多阶段响应 | `run`、`call` | 依次返回接收、日志、结果和结束事件，或错误事件 |
| 首个有效响应 | 默认 `probe`、`route_probe` | 任意分支首先确认后结束等待 |
| 流式多响应 | `probe(multiple=True)` | 原样迭代返回多个 `probe_ack`，不额外封装结果数组 |
| 路径集合 | `route_probe_group` | 在响应窗口内收集同名实例路径、按实例去重并排序 |
| 多响应合并 | `scan`、全网 `kill` | 收集多个节点的结果后合并 |
| 广播与逐跳确认 | `event` | 每一跳返回 `event_ack`，不返回业务处理结果 |

`run` 的响应可能包含 `run_ack`、`run_start`、`run_running`、`log`、`run_result` 和 `run_end`；`call` 的响应可能包含 `call_ack`、`log`、`call_result` 和 `call_end`。因此它们虽然只执行一个目标，却不是普通的一问一答。

### 全域传播机制

C2C 当前存在四类全域传播机制：

1. `route_probe`：寻找指定身份和第一条可达路径，不执行目标业务。
2. `route_probe_group`：寻找全部同名实例，返回每个实例的真实路径。
3. `probe`：携带业务条件寻找确认节点；默认第一条确认生效，`multiple=True` 时返回窗口内的全部确认。
4. `event`：向所有可达节点广播业务事件，不等待业务结果。

`route_probe_group` 的每个结果包含 `node_id`、`operator_name`、`instance_id`、`weight` 和 `route`。相同 `instance_id` 只保留一条路径，结果按照权重 `high`、`medium`、`low` 排序，同一权重下优先路径较短的实例。该排序只影响组查询结果，不改变普通 `route_probe` 的“第一条有效路径”规则。

`scan` 是独立的聚合扫描波：它传播到整个可达网络，但需要在窗口内收集并合并所有有效响应，不采用“首个响应即结束”的规则。

### Probe 单响应与多响应

默认调用保持原有返回值，一个确认字典或 `None`：

```python
ack = session.probe({"type": "channel_service", "service": "mysql"})
```

需要发现窗口内全部匹配实例时传入 `multiple=True`。返回值是迭代器，响应不会被重新包装：

```python
for ack in session.probe(
    {"type": "channel_service", "service": "mysql"},
    timeout=10,
    multiple=True,
):
    print(ack["node_id"], ack["instance_id"], ack["route"])
```

`multiple` 是探测协议的控制参数，不属于业务 `payload`。迭代会在所有分支完成或超时后结束；相同 `instance_id` 只返回一次。

### EventBus 业务事件

EventBus 不维护业务事件类型枚举。节点可以发布任意具有非空 `type` 的事件：

```python
self.c2c.client.event_bus.publish({
    "type": "operators_reloaded",
    "status": "completed",
})
```

C2C 使用固定的顶层 `event` 指令封装业务事件：

```json
{
  "type": "event",
  "event_id": "全局事件编号",
  "node_id": "事件来源节点",
  "sender_node_id": "当前转发节点",
  "created_at": 1793600000.0,
  "expires_at": 1793600060.0,
  "event": {
    "type": "operators_reloaded",
    "status": "completed"
  }
}
```

顶层 `type` 属于 C2C 协议，`event.type` 属于节点业务。即使业务事件名为 `run` 或 `call`，它仍位于 `event` 对象内部，不会被解释成同名控制指令。

EventBus 负责生成 `event_id`、补充来源身份、设置 TTL、逐跳确认、根据 `event_id` 防环和去重，并在直连、反向连接和多跳网络中继续传播。监听器只能观察和处理事件，不能通过返回值阻止传播；单个监听器异常也不会中断网络扩散。

### 固定指令清单

TCP C2C 当前支持28种顶层 JSON 指令：

| 类别 | 指令 |
| --- | --- |
| 路由与组网 | `route_probe`、`route_probe_group`、`probe`、`discover`、`scan`、`get_path`、`connect`、`handshake`、`join` |
| 节点身份与生命周期 | `identify`、`info`、`visible`、`hidden`、`shutdown`、`kill` |
| 算子执行与事件 | `run`、`call`、`event` |
| 文件与会话控制 | `receive_file`、`file_manifest`、`sync_files`、`close_session` |
| 流和自定义通道控制 | `file_stream`、`http_stream`、`channel`、`data`、`reverse_stream_attach` |

这里的 `file_stream`、`http_stream`、`channel` 和 `reverse_stream_attach` 只描述建立或切换数据通道的 JSON 控制阶段，不包含其后的二进制流。JSON `handshake` 是节点业务握手指令，不是连接建立时交换的512 bit 二进制首包。

WebSocket 支持 `scan`、`info`、`visible`、`hidden` 和独有的 `subscribe`，因此 TCP 与 WebSocket 合并后共有29种对外唯一指令。

UDP 使用 `announce`、`heartbeat`、`leave` 和 `renamed` 进行节点发现和状态通知。反向连接内部使用 `reverse_request`、`reverse_response`、`reverse_error` 和 `reverse_stream_open`。Bridge 启动直连探测与短连接目录同步使用 `bridge_direct_probe` 和 `bridge_sync`。它们都不是算子应该直接发送的业务指令。

### 命名空间边界

```text
顶层 type
    C2C 固定 JSON 控制指令

identifier
    最终目标身份

route
    到达最终目标的指定路径

event.type
    节点自定义业务事件

HTTP method + path
    HTTP Gateway 路由

Operator channel
    算子自定义协议
```

当前共有29种对外指令、4种 UDP 发现消息、4种反向连接内部帧和2种 Bridge 内部消息，共39种固定协议消息类型；EventBus 业务事件数量不受限制。

## 本机调试网络

设置环境变量后，C2C 节点只加入当前机器上的调试网络：

```bash
export C2C_DEBUG_LOCAL_ONLY=1
```

该模式只改变 UDP 发现：节点公告仅发送到 `127.0.0.1` 的发现端口范围，
同时忽略所有非本机地址发送的 UDP 发现包。因此节点不会自动发现局域网内
其他机器，其他机器也无法通过 UDP 发现该节点。

TCP 和 WebSocket 行为保持不变。需要按指定地址主动回连时，启动 `operators_lib.c2c_bridge_node` 并传入 `--target IP[:PORT]`。

未设置该变量，或变量值不是 `1`、`true`、`yes`、`on` 时，保持原有局域网发现和监听行为。

## 聚合启动节点

`C2CCollect` 可以在同一进程中聚合多个节点类。成员仍保留各自的执行队列、依赖、后台服务和业务实现；Collect 只合并 C2C 网络层，因此整组只监听一套 UDP/TCP 端口并维护一套观察者连接。

```python
from adp_operator.collect import C2CCollect
from adp_operator.operators.c2c_http_gateway import C2CHttpGateway
from adp_operator.operators.c2c_panel_node import C2CPanelNode

C2CCollect(
    C2CHttpGateway,
    C2CPanelNode,
    node_id="GatewayPanel",
    network="192.168.20.206",
).serve()
```

同组成员之间的 `call`、`run` 和 HTTP handler 调用走进程内分发；成员自己启动的 WebSocket、HTTP 或其他通道仍按原逻辑监听。网络中的其他节点只观察到 `GatewayPanel` 这个物理节点，但仍可按成员的 `operator_name` 探测和调用。C2C Panel 会把物理节点绘制成 Collect 容器，成员显示在容器内部；TCP/观察者/Bridge 连线属于容器，业务依赖线连接到具体成员。

## C2C 网络的后续方向

以下是设计目标，不代表当前已经具备自动加密或网络加速能力。

### 按连接选择传输方式

同一张 C2C 网络中，不同节点之间的连接可以采用不同方式：

| 连接条件 | 预期方式 |
| --- | --- |
| 两端可直达且允许明文通信 | 直接 C2C TCP |
| 跨网连接必须加密 | 经加密桥接节点连接 |
| 一端无法接受入站连接 | 桥接节点通过 `--target` 建立反向连接 |
| 同时需要加密和反向连接 | 桥接节点经加密通道反向接入 |

直连节点应继续直连。桥接节点负责接入、发现和转发，不要求普通算子了解加密软件，也不为此修改 `run`、`call`、EventBus 或二进制流的业务语义。传输方式属于节点之间的连接属性，不应由算子业务参数在网络中层层透传。

### 加密桥接的候选方案

固定远端入口时，可在服务端运行 `ss-server`，客户端运行 `ss-tunnel`。客户端桥接节点对本地 tunnel TCP 端口指定 `--target`；tunnel 将每条连接加密转发到服务端桥接节点的 C2C 业务端口。`ss-tunnel` 是固定目标端口转发，不是点对点组网或自动选路。若需要动态选择多个远端目标，可另行评估 `ss-local` 与本地 SOCKS5 转发入口。

现有反向连接的数据流会在主连接之外重新建立 TCP 连接，所以首次接入和后续数据连接必须都能重复进入同一本地 tunnel 端口。跨机器 UDP 广播不会随 TCP tunnel 传输；各机器仍在本地发现节点，再由 C2C 的节点同步与多跳路由扩散可达信息。落地前还须解决远端 C2C 业务端口动态分配、tunnel 启动就绪、断线重连、旧路由失效，以及容器内 `127.0.0.1` 所属网络命名空间的问题。

### 路由策略与延迟

C2C 当前以可达性为主进行路由探测，不按 RTT、丢包、吞吐或加密要求持续选择最优路径。添加加密桥接之后，不能假定网络会自动避开仍然可达的明文路径。需要强制加密的连接，必须有明确的传输策略和路由约束；在此之前应通过部署隔离不允许使用的直连路径。

C2C 和 Shadowsocks 都不能凭空降低物理链路的 RTT。桥接、多跳、加解密和额外建流通常会增加开销；只有实际底层路径优于原路径时，绕路才可能降低延迟。未来若要优化延迟，应先测量各连接的 RTT、成功率、吞吐和负载，再在满足安全策略的可用路径中选路，避免为了加速让本可直连的流量绕桥。

实施顺序建议为：先验证固定入口的加密反向桥接和双向业务流；再补齐连接恢复及加密路径约束；最后依据真实链路指标决定是否实现动态选路。性能评估应分别比较直接 TCP、未加密反向连接和经加密 tunnel 的反向连接，覆盖小型 `call`、长任务、文件和 HTTP 二进制流，分别记录延迟、吞吐与两端 CPU。


### 多目录算子检索

`AdpOperatorDispatch` 的 `operator_directory` 支持单个字符串、`Path` 或目录列表，旧配置可继续使用。例如：

```python
dispatch = AdpCpuDispatch(operator_directory=["/opt/operators/local", "/opt/operators/shared"])
```

按列表顺序检索，遇到同名算子使用第一个目录中的配置。上传只写入第一个目录；算子索引也存放在第一个目录下。全部目录都会监听变化。扫描结果的 `operator_directory` 字段表示来源目录，前端支持展示和搜索来源目录及源码路径。


### 算子权重与同名实例

`C2COperatorBase.weight` 表示同名实例的调度优先级，可取 `high`、`medium` 或 `low`，默认值为 `medium`。权重随节点元数据发布，可通过 `info` 获取，并显示在 C2C Panel 的节点详情中。

权重默认由启动方式决定，普通算子通常不需要单独设置：

| 启动方式 | 默认权重 |
| --- | --- |
| `adp serve <Operator>` 主动启动 | `high` |
| `bootstrap.py` 或直接启动常驻节点 | `medium` |
| `AdpOperatorDispatch` 派生算子 | `AdpOperatorDispatch.operator_weight`，默认 `medium` |

需要降低某个 Dispatch 派生实例的优先级时，可将该 Dispatch 的 `operator_weight` 设置为 `low`。底层命令行也支持 `--weight low|medium|high`，Dispatch 会自动把自身配置的权重传给派生进程。

权重不会改变普通 `route_probe` 的返回规则；它只用于 `route_probe_group` 的结果排序。调用方可以从有序结果中选定实例，并把该结果的完整 `route` 交给 `run()`、`transfer_file()` 或 `sync_files()`，避免后续按同名算子重新选择目标。


### 算子依赖与冻结

算子可通过 `dependent = ["ADPRedis"]` 声明依赖，名称匹配 C2C 节点的 `operator_name`。默认空列表保持原有行为。

依赖节点未发现、已过期或通告 `dependency_ready = false` 时，节点冻结：不执行新的业务指令，`ActiveOperator` 暂停后续采样。发现、路由、身份查询和生命周期管理继续运行，依赖恢复后自动解冻。保留中转节点以支持跨网段路由，不按依赖列表裁剪网络拓扑。

节点通告包含 `dependent`、`missing_dependencies` 和 `dependency_ready`，便于诊断。冻结业务请求不会返回业务响应，调用方可能收到连接关闭或超时。冻结不会强制中断已经开始的任务。依赖判断基于发现信息及 TTL，不保证依赖服务在实际调用瞬间可用，因此算子仍应处理调用中的连接错误。


### Bridge 网络隔离

普通节点的常驻节点表仅维护本地网络。Bridge 通告远端服务目录（`remote_services`），普通节点可按名称发起主动探测，但不会把远端物理地址长期保存为本地直连邻居。`route_probe` 和 `route_probe_group` 可以临时返回跨 Bridge 的完整真实路径；返回路径只用于当前业务发送，不写入普通节点的长期路由缓存。

未指定 `route` 的普通业务请求可在跨越 Bridge 时由 Bridge 继续选路；调用方明确提供的真实 `route` 则严格逐跳执行，任何相邻下一跳不可用都会立即返回路由错误，不会静默压缩路径或改选同名实例。

依赖状态与通道发现使用 Bridge 提供的服务目录；本地 Bridge 不可用时，其代理服务也不可用。远端完整拓扑单独保存在面板展示缓存，不参与普通节点邻居选择或拓扑转发。只有 Bridge 互相交换跨网络节点信息。
