第二十二節 資料與備份
[!ref] 詳解見使用者手冊「升級、備份與同步」節。
22.1 備份內容
| 項 | 說明 |
|---|---|
| 工作區列表 | 名稱、路徑、歸檔狀態 |
| 工作階段歷史 | 全量訊息流，含工具呼叫、計畫、待辦、簽核 |
| 助手人設 | 內置 + 自定義 |
| 技能 | 全域 + 工作區 + 外掛提供 |
| 工具政策 | 三態權限 + 白名單 |
| 外部服務 | 憑證以加密形式存儲 |
| 通道綁定 | IM 對端 ↔ 工作區 |
| 設置項 | 一般 + 工作區 |
22.2 備份與復原
| 操作 | 步驟 |
|---|---|
| 備份 | 關閉應用 → 設置 → 資料 → 資料目錄 → 整目錄打包 |
| 復原 | 關閉應用 → 取代原資料目錄 → 啟動應用 |
| 跨設備遷移 | 備份後還原到新設備同名目錄 |
| 同步（實驗性） | 設置 → 資料 → 同步 啟用後多設備共享 |
22.3 完整清理
關閉應用 → 刪除應用本體 → 刪除資料目錄
資料目錄包含登入憑證、工作階段歷史、外部服務憑證；刪除後不可復原。
22.4 SSH 遠端工作區協議
| 欄位 | 類型 | 預設 | 說明 |
|---|---|---|---|
| 協議 | enum | zworkspace |
zworkspace / ssh |
| 主機 | string | — | user@host[:port] |
| 認證 | enum | password | password / private_key / private_key_with_passphrase |
| 私鑰路徑 | string | — | 文件選擇器挑選；本機解析 |
| 遠端根目錄 | string | ~ |
支持 ~ 自動展開為遠端家目錄。拒絕 /；.. 逃逸與 ~/..（含 ~//../）一層穿透均已封堵；展開並解析真實路徑後再按同一口徑二次校驗 |
| 憑證加密 | — | SM4-GCM | 國密落盤 + 本機綁定；每次儲存使用隨機鹽 |
| 憑證保留 | bool | 記住 | 「記住密碼 / 通行碼」複選框。未勾選則為臨時憑證：連線期內保留（保重連），應用啟動與結束時清除。工作區粒度，落盤為 ssh_secrets.yaml 的 remember 標記；存量無此欄位視同已記住 |
| 主機指紋 | — | 首連確認 | 首次連線展示 SHA256 指紋，由你核對確認後才釘住 known_hosts，確認前不發送密碼；已知主機換鑰硬拒（疑似中間人） |
SSH 工作區與本機工作區的差異：
| 能力 | 本機 | SSH |
|---|---|---|
fs.* 文件操作 |
本機 | 走 SFTP / 遠端 shell |
fs.grep |
Go RE2 | 遠端系統 grep（提速） |
fs.exec 同步 |
本機 | 遠端 shell |
fs.exec.start 後台長駐 |
啟用（工作階段隨 Interpreter 生命週期結束） | 啟用（工作階段狀態存遠端 <root>/.avlcode/sessions/，跨斷線重連與應用重新啟動存活；setsid 自成程序組，kill 連子孫一併收；記錄檔為完整文件、無本機版 256 MiB 環形丟尾；不做 venv 感知） |
| 文件變更面板 git | 本機 git | 遠端 git（無 git 時隱藏面板） |
| Skills / Plugins / Hooks | 本機 .avlcode/ |
遠端 .avlcode/ |
| 文件威脅掃描 | 本機位元組 | SFTP 取位元組後掃描 |
sys.info 報告身份 |
本機 | 遠端真實身份 |
| 「關閉並清除資料」選單項 | 顯示 | 不顯示 + 後端拒絕（避免誤刪遠端文件） |
| 「移除工作區」 | 刪本機記錄與憑證 | 刪本機記錄與憑證（不碰遠端文件） |
| 跨 OS 用戶端相容 | — | 遠端命令不注入本機環境變數（用遠端登入 shell 自帶環境）；遠端路徑一律按 POSIX 文法構造（Windows ↔ Linux 已徹底打通） |
22.5 工作階段附加目錄
| 欄位 | 類型 | 預設 | 說明 |
|---|---|---|---|
| 入口 | — | — | 輸入框「+」選單：附加目錄（只讀） / 附加目錄（讀寫） |
| 權限 | enum | — | ro（讀 / 列舉 / 搜尋） / rw（額外允許寫 / 刪 / 建立） |
| 作用域 | — | 工作階段 | 僅當前工作階段；其它工作階段不受影響 |
| 持久化 | — | 工作階段內 | 隨工作階段儲存；重新啟動後台自動重新生效 |
| 顯示 | — | 輸入框上方「附加路徑」條 | 可隨時移除 |
| 路徑標註 | — | 絕對路徑 | 搜尋 / 列舉結果標絕對路徑，來源一目了然 |
| 工作階段身份注入 | — | 系統在呼叫鏈注入 _session_id |
AI 不可偽造身份冒用別工作階段的附加權限 |
22.6 專案指令（AGENTS.md）
工作區根目錄放 AGENT.md / AGENTS.md / CLAUDE.md（按優先級取一份），自動作為系統提示裡的「# 專案指令」塊。
| 欄位 | 行為 |
|---|---|
| 檔名優先級 | AGENT.md > AGENTS.md > CLAUDE.md（取第一個存在的） |
| 注入位置 | 系統提示詞獨立「# 專案指令」塊 |
| 重新讀取 | 每輪重新讀，改了立即生效 |
| 子目錄注入 | AI 讀寫某子目錄下文件時，自動把路徑上各級 AGENT.md 一並注入（每工作階段每子目錄一次，去重不刷屏） |
| 截斷政策 | UTF-8 字元邊界安全截斷 + 截斷標記 |
| 軟鏈護欄 | EvalSymlinks 真實路徑校驗，不在工作區內則拒絕 |
| 內置編輯器 | 工作階段選單 / 工作區選單「編輯 AGENTS.md」；Cmd/Ctrl+S 儲存、Tab / Shift+Tab 縮排、未儲存保護、空狀態模板 |
22.7 訊息內鏈接與檔案路徑點擊行為
| 類別 | 識別 | 點擊行為 |
|---|---|---|
| 工作區內檔案路徑 | 帶常見副檔名（如 src/main.go / README.md） |
系統檔案管理員定位並選中 |
| 外部鏈接 | http(s) URL |
預設瀏覽器開啟 |
| 反引號內聯程式碼裡的路徑 | 帶副檔名 | 與普通鏈接同等識別 |
工具結果 / 回答裡的 文件:行 |
path:line(:col)? |
帶行號的工作區文件 → 「檢視」開啟源碼預覽並滾到該行 |
程式碼區塊裡單條 .md / .mdx 路徑 |
文件存在（非同步校驗後升級為可點） | 開啟 Markdown 預覽抽屜 |
| 普通內聯程式碼 | — | 不識別為鏈接 |
| 危險協議 | 非 http(s) |
攔截 |
| 純目錄 / 無副檔名片段 | 如 a/b、/etc/hosts |
不可點 |
點擊後彈出非模態浮動工具條（主動作「檢視 / 開啟」+「複製」），用 Popover API 渲染在頂層，彈窗內點擊同樣不被遮擋。「檢視」對帶行號的源碼走 PreviewSourceFile(target, line) 在程式碼視圖定位到該行，讓 code.search / code.ask 給出的 文件:行 證據可核對。