檔案傳輸與區域網直連

Agent、Exchange、CLI、網頁控制台和手機控制端支援檔案傳輸。支援的裝置會宣告 files 能力。

檔案傳輸

remote-cli file i5m ls /tmp
remote-cli file i5m upload ./example.zip /tmp/example.zip
remote-cli file i5m download /tmp/example.zip ./downloaded.zip
remote-cli file i5m fetch https://example.com/example.zip ./example.zip

預設不覆蓋已有檔案；上傳或下載時新增 --overwrite 才允許覆蓋。CLI 使用 Ctrl+C 取消，網頁和手機控制端提供取消按鈕。網頁在裝置詳情的“檔案”頁操作，手機控制端從裝置詳情進入“檔案傳輸”。

傳輸分塊為 64 KiB，每塊確認後繼續。單檔案上限 1 GiB；網頁下載上限 128 MiB，較大檔案請使用 CLI 或手機控制端。目錄最多回傳 1000 項，不支援遞迴目錄上傳。上傳在目標目錄寫入臨時檔案，完整接收後原子替換；取消、斷線或逾時會清理未完成的臨時檔案。CLI 下載也使用臨時檔案，手機端下載到快取後呼叫系統分享/儲存。

檔案訪問使用 Agent 程序的系統許可權，不限制在某個共享目錄。唯讀帳號不能列目錄、上傳或下載；Exchange 沿用裝置所屬工作區、會話隔離和操作審計，不記錄檔案內容。Android 上 . 指向 Agent 應用檔案目錄，訪問其他目錄受 Android 許可權限制，不能繞過系統沙箱。

透過 Agent 下載網路檔案

在網頁檔案頁輸入 HTTP/HTTPS 網址，或執行 file DEVICE fetch URL LOCAL。Agent 從自身網路下載並串流傳回 Console 電腦，不在 Agent 儲存檔案。網頁上限 128 MiB，CLI 上限 1 GiB；取消、斷線或失敗不儲存未完成檔案，覆寫既有 CLI 目的檔案需要 --overwrite。原生系列（桌面、Linux、Android、OpenWrt）支援此功能，瀏覽器擴充套件不提供檔案傳輸。下載驗證憑證，拒絕內嵌帳密與 HTTPS 降級，最多跟隨五次重新導向。

下載不沿用管理伺服器的 --insecure。

類 curl 的 HTTP 請求

在裝置 HTTP 請求頁貼上 curl，Console 傳送密封請求，由所選 Agent 執行並回傳狀態碼、耗時、標頭與本文。支援 -X/--request、-H/--header、-d/--data、--data-raw、內嵌 --data-binary、--json、-I/--head、-L/--location、-m/--max-time、--url；不執行 shell 或讀取 @file。原生 Agent 無需安裝 curl。擴充套件需要網站權限、不攜帶瀏覽器 Cookie，拒絕禁止標頭；Chromium 隱藏的重新導向會提示使用最終網址。唯讀權限不可請求。請求本文上限 256 KiB、逾時上限 120 秒；原生回應最多 1 MiB、擴充套件 128 KiB，超出會標示截斷。二進位或大檔請使用網路檔案下載。

密封訊息為 net_req。瀏覽器能力：net。CLI 對應指令：remote-cli net DEVICE http URL -X POST -H 'Content-Type: application/json' -d '{"message":"hello"}'

curl -X POST 'https://example.com/api' -H 'Content-Type: application/json' --data-raw '{"message":"hello"}'

區域網控制連接埠

區域網控制預設關閉，預設 TCP 連接埠為 7277。僅在可信區域網中啟用。啟用前裝置必須已經固定工作區根（remote-agent seal root，或先連上 Exchange 完成 TOFU）。沒有區域網訪問令牌。不要把連接埠轉發到公網。

在現有 Agent JSON 設定中新增：

{
  "lan_enabled": true,
  "lan_port": 7277
}

保留設定中原有的 server、device_id 和 token 欄位。也可使用 --lan-enabled、--lan-port，或 REMOTE_LAN_ENABLED、REMOTE_LAN_PORT。未固定工作區根時，啟用 LAN 會拒絕啟動。

桌面設定頁和 LuCI 設定頁均有開關。修改後重新啟動 Agent；桌面設定頁要求先停止連線再修改。關閉開關並重啟後，不再監聽此連接埠。程式不會自動建立防火牆放行規則。

CLI 直連單獨寫設定，不要用 login（它要求非空令牌）。server 填裝置的 http://IP:7277，token 留空，請求不帶 Authorization：

server = "http://192.168.1.20:7277"
token = ""

用 REMOTE_CLI_CONFIG 指向該檔案可以保留另一份雲端登入。密封身分和授權快取放在這份設定所在目錄：seal-grants.json 中的離線 grant，以及 seal-chains.json 中根簽發在前的憑證鏈。所有裝置操作只開啟密封會話，包括裝置卡片帶 local 或區域網地址上 /api/auth/me 回傳 401 的直連裝置。Agent 不簽發、不續簽這些授權。雲端離線時只能使用快取中仍有效的根鏈授權。sessions 和 session-kill 不可用：區域網沒有會話目錄，裝置會話仍由 Exchange 管理。

直連只暴露本機裝置。外層只接受私有、鏈路本機或迴環地址，並校驗 Origin。GET /api/devices 在透過這些檢查後只回傳裝置 ID 和啟動密封握手所需的 seal_key / seal_mode。GET /api/auth/me 在密封握手之前不回傳操作員身分。GET /ws/operator 只接受密封會話，不提供明文相容路徑。

用戶端在 open_sealed 的 hello 裡內聯提交操作員公鑰證明，以及上述離線快取的 grant（hello.grant）和可選憑證鏈（hello.chain，根簽發的在前）。裝置用與 Exchange 路徑相同的規則核對本機根、裝置範圍和 view/manage，會話內容保持密封。網頁控制台仍透過 Exchange 連線裝置。預設監聽 IPv4 所有介面；雲端離線時仍可使用。LAN 繫結失敗會記錄錯誤，雲端重連繼續執行。

迴歸驗證

python scripts/file-transfer-smoke.py --agent target/debug/remote-agent --cli target/debug/remote-cli
python scripts/agent-ui-smoke.py --agent target/debug/remote-agent --platform linux

需要 Python 3.11+ 與 websockets。Windows 使用 .exe 路徑和 --platform windows。測試使用臨時設定與檔案，不修改現有登入或裝置。