91 lines
4.8 KiB
Markdown
91 lines
4.8 KiB
Markdown
# Adapter SDK：产品扩张的关键边界
|
||
|
||
方案 §6.4 的判断是对的——**适配器是产品扩张的关键**。每接一个客户，
|
||
新增的工作量应该收敛到"写一个适配器"，而不是改引擎。这一波把这条边界钉死。
|
||
|
||
实现：`services/host-agent/flashops_agent/adapters/`
|
||
|
||
## 契约（7 个方法，一个都不能少）
|
||
|
||
```python
|
||
class ToolAdapter(Protocol):
|
||
name: str
|
||
version: str
|
||
|
||
def discover(self, ctx: AdapterContext) -> Capabilities: ...
|
||
def precheck(self, ctx: AdapterContext) -> CheckResult: ...
|
||
def execute(self, step: StepSpec, ctx: AdapterContext) -> ExecutionHandle: ...
|
||
def collect(self, handle: ExecutionHandle) -> EvidenceArtifact: ...
|
||
def cancel(self, handle: ExecutionHandle) -> None: ...
|
||
def health(self) -> HealthStatus: ...
|
||
def normalize_result(self, raw: RawResult) -> UnifiedResult: ...
|
||
```
|
||
|
||
| 方法 | 职责 | 什么时候被调 |
|
||
|---|---|---|
|
||
| `discover` | 报告本工具在这台主机上能干什么（版本、支持的设备、能力位） | Agent 启动 / 资产刷新 |
|
||
| `precheck` | 执行前自检：工具在不在、权限够不够、设备在不在、参数合不合法 | 每个步骤执行前，**失败即拒绝执行** |
|
||
| `execute` | 启动执行，**立即返回句柄，不阻塞** | 步骤开始 |
|
||
| `collect` | 从句柄收集产物：stdout/stderr、结果文件、设备日志 | 步骤结束 / 中途取证 |
|
||
| `cancel` | 终止执行（含进程树），保证不留孤儿进程 | 紧急停止 / 超时 / 恢复前 |
|
||
| `health` | 适配器自身健康（工具还在吗、许可证过期没） | 心跳周期 |
|
||
| `normalize_result` | 把工具原生输出翻译成统一结果模型 | `collect` 之后 |
|
||
|
||
## `normalize_result` 是最重要的一个
|
||
|
||
它决定了失败签名能不能跨工具聚类。原生输出千奇百怪，统一模型只有一种：
|
||
|
||
```python
|
||
@dataclass
|
||
class UnifiedResult:
|
||
outcome: Literal["PASS", "FAIL", "ERROR", "TIMEOUT"]
|
||
error_codes: List[str] # 归一化后的错误码，如 ["NVME_STATUS_0x2002"]
|
||
log_templates: List[str] # 日志模板化后的指纹，数字/路径已替换为占位符
|
||
metrics: Dict[str, float] # iops / latency_p99 / temperature_c ...
|
||
device_state: DeviceState # 枚举状态、固件版本、SMART 关键项
|
||
integrity: IntegrityState # OK / MISMATCH / NOT_CHECKED
|
||
artifacts: List[str] # 产物 URI
|
||
```
|
||
|
||
**适配器的实现者只需要保证一件事**：同样的故障，`error_codes` 与
|
||
`log_templates` 要稳定。不稳定 → 签名散开 → 聚类失效 → 同一个问题重复提单，
|
||
客户第一时间就会发现这个系统在制造噪音。
|
||
|
||
日志模板化规则在 `flashops_agent/adapters/templating.py`：
|
||
数字 → `<N>`，十六进制 → `<HEX>`，路径 → `<PATH>`，UUID → `<UUID>`，
|
||
时间戳 → `<TS>`。所以
|
||
`"nvme0n1: I/O error, sector 12345678 at 2026-07-27T03:14:15"`
|
||
归一为 `"nvme<N>n<N>: I/O error, sector <N> at <TS>"`。
|
||
|
||
## 这一波带的适配器
|
||
|
||
| 适配器 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| `ShellAdapter` | ✅ 真实 | 执行签名命令模板，进程树管理、超时、输出捕获 |
|
||
| `NvmeCliAdapter` | ⚠️ 真实骨架 + 模拟回退 | 命令与解析是真的；无真实设备时走模拟器 |
|
||
| `FioAdapter` | ⚠️ 真实骨架 + 模拟回退 | 解析 fio `--output-format=json` |
|
||
| `SimulatedDutAdapter` | ✅ 模拟 | 可注入故障的假 DUT，让全链路无硬件可跑 |
|
||
| `VendorFlashAdapter` | ⬜ 占位 | 客户私有刷写工具——**这个必须等拿到真实 SOP 再写** |
|
||
|
||
`VendorFlashAdapter` 故意留空并在导入时抛 `NotImplementedError`。
|
||
猜客户的刷写工具长什么样是纯浪费——报告 Phase 0 的结论是先拿 SOP 再写代码。
|
||
|
||
## 写一个新适配器的清单
|
||
|
||
1. 继承 `BaseAdapter`，实现 7 个方法
|
||
2. 在 `adapters/__init__.py` 的 `REGISTRY` 里注册（key 就是工作流 YAML 里的 `adapter:`）
|
||
3. 危险命令**必须**在控制平面 `safety/templates.py` 注册签名模板；
|
||
适配器里不允许拼接任意命令行——参数只能来自模板 schema 校验过的字典
|
||
4. 写一个 `tests/adapters/test_<name>.py`：至少覆盖
|
||
`precheck` 失败路径、超时路径、`normalize_result` 的两个不同故障输出
|
||
5. 跑 `make test` 里的适配器契约测试（`test_adapter_contract.py` 会对
|
||
`REGISTRY` 里每个适配器自动断言 7 个方法齐全且签名正确）
|
||
|
||
## 边界纪律
|
||
|
||
- 适配器**不知道** Run、Workflow、状态机的存在。它只认 `StepSpec` 和 `AdapterContext`。
|
||
- 适配器**不做**重试和恢复决策。挂了就如实报告，重试与恢复是控制平面的事。
|
||
- 适配器**不写**数据库，产物写本地临时目录，由 Agent 上传。
|
||
- 适配器里**不允许**出现 `if customer == "X"` 这种分支。客户差异靠不同适配器 +
|
||
工作流参数表达，不靠代码里的 if。
|