host-execution-mcp 1.0.0

package/docs/HOP1_E2E_CHECKLIST.md

@@ -0,0 +1,128 @@
+# Hop1 端到端测试清单（3.0.0）
+
+**Last run:** 2026-07-16 — **43/43 PASS**  
+**Runner:** `scripts/hop1-e2e-one.mjs` + `scripts/hop1-e2e-all.mjs`（进程内 Engine，与包代码一致）  
+**Raw JSON:** [`HOP1_E2E_RESULTS.json`](HOP1_E2E_RESULTS.json)
+
+```bash
+# 单例
+TEST_ID=A1 node scripts/hop1-e2e-all.mjs   # 或 hop1-e2e-one.mjs
+# 全量
+node scripts/hop1-e2e-all.mjs
+```
+
+Job 类用例使用隔离 `BASTION_COPY_JOB_ROOT`。夹具：`%TEMP%\mcp-copy221-fixtures`（small-4k / large-34m）。
+
+---
+
+## A. 基础文件双向
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| A1 | local → bastion 小文件 | exit 0；MD5；`skippedBytes=0`；verified | **pass** | |
+| A2 | bastion → local 小文件 | 同上 | **pass** | |
+| A3 | local → bastion 大文件 | MD5；`usedFastPath=true` | **pass** | |
+| A4 | bastion → local 大文件 | MD5 | **pass** | |
+| A5 | 覆盖已存在远端（无 skip） | 内容为新源 MD5 | **pass** | |
+
+## B. 目录拷贝
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| B1 | 扁平目录 upload | 文件齐全 | **pass** | |
+| B2 | 嵌套目录 upload | 保留 `sub/` | **pass** | |
+| B3 | 目录 download | 本地结构一致 | **pass** | |
+| B4 | 空目录 upload | 创建远端空目录或明确错误 | **pass** | 行为：创建空远端目录 |
+| B5 | 目录 `verify=size` | verified | **pass** | |
+| B6 | 目录 `verify=size+sha256` | 逐文件 hash 成功 | **pass** (updated) | 不再整树拒绝 |
+
+## C. skipIfComplete / skippedBytes
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| C1 | upload 二次同 size + skip | `skippedBytes>0` | **pass** | |
+| C2 | download 残缺 size + skip | 全量重写；`skippedBytes=0` | **pass** | |
+| C3 | 同 size 错误内容 + size / sha256 | 记录 size 风险；sha256 不静默 | **pass** | size-only 可 false-skip；sha256 会纠正/失败 |
+| C4 | 默认无 skip | `skippedBytes=0` | **pass** | |
+| C5 | schema 禁止 `resume`；skip+none | Zod + Engine reject | **pass** | |
+
+## D. Verify
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| D1 | `verify=none` | verified=false | **pass** | |
+| D2 | `verify=size` 默认 | verified=true | **pass** | |
+| D3 | `verify=size+sha256` 文件 | verified + MD5 | **pass** | |
+| D4 | 损坏远端 + skip + sha256 | 校验失败后全量重传；`skippedBytes=0` | **pass** (fixed) | upload/download 均回落 rewrite |
+
+## E. 超时与 Abort
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| E1 | async 极小 totalTimeout | 终态 `timeout` | **pass** | |
+| E2 | sync 极小 totalTimeout | 抛错不挂死 | **pass** | |
+| E3 | cancel 大上传 | cancelled；exec SSH 存活 | **pass** | |
+| E4 | cancel 后再拷贝 | 新 SFTP 成功 | **pass** | |
+| E5 | 预 abort signal | 立即 Copy aborted | **pass** | |
+
+## F. 异步 Job API
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| F1 | start 小文件 → success | 立即 transferId | **pass** | |
+| F2 | start 大文件 + progress | percent→100；字段形状 | **pass** | |
+| F3 | sync transferId 查 status | Unknown | **pass** | |
+| F4 | orphan reconcile | failed + MCP restarted | **pass** | |
+| F5 | success 后 cancel | 仍 success | **pass** | |
+| F6 | cancel 后晚到 success | 仍 cancelled | **pass** | 注入 runner |
+
+## G. 同步/异步边界
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| G1 | sync 阻塞且无 job 文件 | 无 `jobs/<id>.json` | **pass** | |
+| G2 | 拒 `resume` / `idleTimeoutMs` | schema strict | **pass** | |
+| G3 | `timeoutMs` 映射 wall budget | 触发超时 | **pass** | |
+
+## H. Pipeline（含 Hop1）
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| H1 | local → pod | pod 内可读 | **pass** | ns=`his-test` |
+| H2 | local → host | host 文件存在 | **pass** | host=`10.121.32.74` |
+| H3 | pipeline cancel | SSH 存活；Hop2 best-effort | **pass** | 终态可为 cancelled/failed/success |
+
+## I. 连接隔离与并发
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| I1 | SFTP 中并行 bastion exec | exec 成功且 job success | **pass** | 双连接 |
+| I2 | 两路并行 Hop1 | 均 success | **pass** | |
+
+## J. 负向 / 清理
+
+| ID | 场景 | 期望 | 结果 | 备注 |
+|----|------|------|------|------|
+| J1 | 本地路径不存在 | 明确错误 | **pass** | |
+| J2 | 远端路径不存在 | 明确错误 | **pass** | |
+| J3 | 无 `.copy-meta.json` | 仅 size+verify | **pass** | |
+| J4 | 结果字段名 | 仅 `skippedBytes` | **pass** | 无 `resumedFrom` |
+
+---
+
+## skip / verify 等级（设计）
+
+| Level | 选项 | 行为 |
+|-------|------|------|
+| 1 默认 | skip + `verify=size` | size match → skip（便宜；C3 内容风险） |
+| 2 严格 | skip + `verify=size+sha256` | hash 门禁；fail → rewrite |
+| 禁止 | skip + `verify=none` | Engine/schema 拒绝 |
+
+## 已知风险（测试中确认）
+
+1. **Level 1**：同 size 不同内容可能误 skip（C3）。内容保证请用 Level 2。
+2. **Hop2 cancel** 仍为 best-effort（H3）；Hop1 cancel 会断开独立 SFTP，不影响 exec SSH。
+
+## 与旧 T1–T8 映射
+
+T1→E3；T2→C2；T3→C1；T4→E1；T5→D3；T6→B1；T7→F4；T8→F5。