工作区守护(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 自觉,也不依赖用户在场。
三条不变量
- 配置 agent 读不到。
/etc/linxira/workspace-guard.conf是root:root 0600。 这是安全前提,不是可配置项——不提供把它放到用户可读位置的选项。 - 恢复不覆盖。
restore永远写入新目录,落在原工作区内、落在守护仓库内、 已存在且非空的目标全部拒绝。原工作区一个字节都不会动。 - 仓库目录 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。