跳转至

工作区守护(workspace-guard)

为什么存在

agent 在用户的工作区里以完整的用户权限运行。它能 rm -rf 一个目录, 也能 rm -rf .git——后者更隐蔽,因为它看起来像一次普通的清理。 一旦工作区没了,用户的代码、提交历史、未推送的分支一起没了,而且往往没有第二份。

这个机制不试图让 agent 更小心。它假设 agent 会犯错,然后在用户权限之外 留一层独立恢复点:root 定时器每 30 分钟做一次快照,写在系统盘的 root-only 目录 /var/lib/linxira/guard 里。

职责边界

这是一个跨项目机制,横跨四个仓库:

部分 归属 内容
快照与恢复的执行 linxira-components linxira-components-guard 的 snapshot / restore,以及快照定时器
仓库目录、注册、启用 linxira-config linxira-config workspace-guard enable
装机时写入同盘配置 linxira-iso-direct shellprocess@linxira-workspace-guard 装机脚本
文档 本 wiki 本页与 ai/topics/workspace-guard.md

不归它:不备份系统本身(那是 timeshift 的事),不备份用户主目录整体, 不做增量同步或实时监控。它只做「把已注册工作区的完整快照按策略保留下来」。

两种「工作区」

「工作区」在本 wiki 里有两个含义,守护只管前一个:

守护注册的工作区 Agent 工作区
是什么 用户日常干活的目录,作为快照目标 agent 的 --cwd,会话与证据的落点
典型路径 $HOME/Linxira-OS、$HOME/Projects、$HOME/work、$HOME/src ~/Linxira/debug
谁在用 用户自己 agent

workspace-guard 登记的是快照目标,不是 agent 工作区;agent 工作区也不会 被它自动注册。两者路径、生命周期与用途都不同。agent 工作区的定义与规则见 Agent 工作区。

怎么用

启用(root)

sudo linxira-config workspace-guard enable

在系统盘创建 root-only 的 /var/lib/linxira/guard,写配置、注册工作区、 开启定时器。不创建分区,不改分区表,不碰第二块盘。命令幂等。 装机阶段默认执行同一套同盘配置(脚本失败不会阻塞安装,守护保持关闭); enable 用于补建或重新启用。

sudo linxira-config workspace-guard disable   # 只停定时器,保留仓库数据

日常(agent 可用,免授权部分)

linxira-config workspace-guard status
linxira-config workspace-guard status --json
linxira-components-guard status
linxira-components-guard list ~/Linxira-OS
linxira-components-guard list ~/Linxira-OS --json

未配置时这些命令安全降级,不报错——未配置是正常状态。linxira-config workspace-guard handbook 还会打印 AI 可读的手册清单。

恢复点操作(Polkit 授权)

linxira-components-guard snapshot ~/Linxira-OS
linxira-components-guard restore <id> --target ~/ws-restored

登记工作区(root)

sudo linxira-components-guard init
sudo linxira-components-guard register ~/Linxira-OS
sudo linxira-components-guard unregister ~/Linxira-OS

登记写的是守护仓库自己的 root 登记表,没有用户可见的副作用,也没有需要回滚的东西, 所以只允许管理员执行,不开一个能被反复触发的提权入口。 非 root 运行会直接拒绝,不会静默半途而废。

何时需要 root 与授权

  • 只读,免 root:linxira-config workspace-guard status [--json]、 linxira-components-guard status [--json]、linxira-components-guard list <path> [--json]、 linxira-config workspace-guard handbook。
  • 需要 root:linxira-config workspace-guard enable|disable, 以及 linxira-components-guard init|register|unregister。非 root 运行会被直接拒绝, 不会静默半途而废。
  • Polkit 授权:linxira-components-guard snapshot 与 linxira-components-guard restore 走系统 D-Bus 的计划与确认;Polkit 会要求 管理员认证。agent 可以发起,但不需要自己持有 sudo。

恢复点的生命周期

守护仓库在系统盘上,不创建独立分区,不写 /etc/fstab。目录是 root:root 0700; 普通用户 agent 读不到,root 可读写。定时器以 root 身份每 30 分钟跑一次, 不依赖 agent 自觉,也不依赖用户在场。

三条不变量

  1. 配置 agent 读不到。 /etc/linxira/workspace-guard.conf 是 root:root 0600。 这是安全前提,不是可配置项——不提供把它放到用户可读位置的选项。
  2. 恢复不覆盖。 restore 永远写入新目录,落在原工作区内、落在守护仓库内、 已存在且非空的目标全部拒绝。原工作区一个字节都不会动。
  3. 仓库目录 root-only。 /var/lib/linxira/guard 是 root:root 0700。 普通用户读不到也改不了;root 可以读写和删除。

已知限制

  • 仓库在根文件系统上(默认 /var/lib/linxira/guard),不建独立分区、不写 /etc/fstab。 enable 与安装器只提供同盘布局,没有选择另一块盘的选项;独立盘不在自动流程里。
  • 保留策略由 enable 写入的配置决定:定时快照保留 24 个、手动快照保留 10 个 (keep_scheduled / keep_manual);更早的恢复点会被修剪。
  • 每次都是完整副本,不是增量或实时同步;仓库会随工作区大小增长,磁盘空间不足时 快照会失败并如实报告。
  • enable 只自动登记执行 sudo 的那个用户主目录下已存在的 Linxira-OS、Projects、 work、src;其他目录要用 linxira-components-guard register 显式加入。
  • 它不备份系统本身,也不备份整个主目录;这两件事分别属于 Timeshift 与用户自己的备份。
  • restore 只写新目录,且拒绝落在原工作区内、落在守护仓库内、或已存在且非空的目标; 它不提供「原地回滚」。
  • 非 root 读不到 /etc/linxira/workspace-guard.conf 时,status 会明说「present but not readable」,恢复诊断则只能报告 configured: false。

深入设计

保留策略与快照目录布局由 linxira-components 负责;权限分层写在 AGENTS.md。 机器可读摘要见 linxira-wiki show workspace-guard。