第二十二节 数据与备份
[!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 给出的 文件:行 证据可核对。