# xop · AI Agent 操作速查(上下文压缩后自动加载) > 本文件是 **xop 给 AI agent 的"可执行附录"**:Claude Code / WorkBuddy / 其他 agent harness 在每次会话开头、以及**上下文压缩(compact)后**都会自动重新加载它。 > 项目根:`/Users/xs/Documents/x/xop` > 完整交接文档在 [`HANDOFF.md`](./HANDOFF.md);架构/威胁模型/对比在 [`docs/`](./docs/)。 --- ## 0. 一句话定位 **xop = 自带加密 vault + OS-auth gate 的 secret 注入器**。`xop init | set | list | get | rm` 管理本地 vault(`~/.x/xop/key.db`,AES-256-GCM + argon2id,LAContext 真指纹预闸门,取消即拒绝,绝不弹系统密码框);`xop [flags] -- CMD` 把 vault 里的真值注入到子进程的 envp/Askpass/fd,同时强制 Deno 风格的 network/file policy,并在 stdout 里 mask 任何泄漏。**无外部后端依赖**——不调 `op` / `vault` / `security` CLI。 **改 Rust 源码 → 必须 `cargo check` + `cargo test --lib` + `cargo test --test integration` 通过 → 再交付**。编译错或测试红禁止 commit。 **解锁模型(v0.2.1,2026-10-02 两次实测修正)**:vault 密钥永远 = `argon2(passphrase)`。每次操作先过 **OS 身份闸门**,闸门结论决定 keyring 能不能静默解锁:① 本地真 TTY → 弹 **LAContext 真指纹验证**(只认手指、绝无密码输入框;**取消 = 拒绝操作 exit 77,不静默放行**)→ 通过后才允许 keyring 免输;② **SSH 会话**(stdin 是 pty 但检测到 `SSH_TTY/SSH_CONNECTION/SSH_CLIENT` env)→ **绝不弹指纹**(弹窗会飞到本机物理屏幕上,远程用户根本看不到/等不到),也**不走 keyring**——没有指纹现证,必须输入 **xop passphrase(管理员密码)**;③ 本地设备无可用指纹(未录入、锁定、无密码、无 GUI、osascript 坏)→ 同样强制输入 xop passphrase;④ Linux 交互会话 → 无指纹闸门可用(pkexec 系统口令框按"永不输系统密码"红线删除)→ xop passphrase;⑤ headless 非 TTY 自动化(agent/pipe/CI/`ssh host cmd` 无 pty)→ 跳过闸门,keyring 静默解锁(`xop run` 无人值守的依据)。解锁密钥来源:文件 keyring `~/.x/xop/keyring`(0600,存 hex 派生密钥,`xop init` 自动写入 / `xop key --save` 补写;`xop key --remove` 吊销)或终端手输(闸门要求输 passphrase / 无 keyring / `XOP_NO_KEYRING=1` 时)。**明确设计决定(2026-10-02):绝不使用 macOS Keychain**——keychain 方案在后台自动化时会弹系统授权对话框(曾被用户否决),xop 任何代码路径都不调 `security(1)`。keyring 权限位不合规(group/other 可读)直接拒用报错。release 二进制永不读 `XOP_VAULT_PASSWORD` env。子进程 stdout/stderr 中的任何 vault 值会被自动 mask 成 `12****【xop禁止将密钥泄漏】`(前 2 真实字符 + 星号 + 警告),`--on-leak=kill|refuse` 时直接 SIGKILL 子进程。 --- ## 1. 编译 + 测试 ```bash cd /Users/xs/Documents/x/xop # 快速检查(增量编译,最常用) cargo check --all-targets # 跑单元测试(68 个:args(含 get -v 解析)/ secret / policy / audit / vault / keyring / auth(touchid classify + decide 决策表)/ stdout-guard / error / injector / askpass) cargo test --lib # 跑集成测试(24 个:help / dry-run / bad-ref / secrets-file / mask 端到端 / keyring 免密解锁 / SSH-headless / get 默认 mask / get -v 明文 / 6 askpass) # 集成测试需要 auth bypass + 已知 passphrase。`XOP_VAULT_PASSWORD` 仅在 # `--features test-bypass` 构建中才被读取;release binary 永远不读这个 env # ——passphrase 必须用户亲输。所以集成测试必须显式启用 feature。 XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \ cargo test --features test-bypass --test integration -- --test-threads=1 # 完整构建 + smoke(默认 release build 不带 test-bypass feature) cargo build --release ./target/release/xop # banner ./target/release/xop help # 完整帮助 ./target/release/xop --dry-run --secret FOO=foo --allow-net=db.local:5432 --deny-net=* -- echo hi ./target/release/xop run --secret SSHPASS=ssh_pass -- sshpass -e ssh user@host # 跑全部测试(不要漏 env vars) cargo test --lib && \ XOP_AUTH_BYPASS=1 XOP_VAULT_PASSWORD=testpass \ cargo test --features test-bypass --test integration -- --test-threads=1 ``` **注意**: - 修改 `Cargo.toml` 加依赖后**必须 `cargo check`** 让 Cargo.lock 重新生成 - `--test-threads=1` 在集成测试里**必须带**,因为某些测试改 `HOME` / env 状态 - 集成测试用 `--features test-bypass` 构建;**release 永远不带这个 feature**(防止 `XOP_VAULT_PASSWORD` 变成绕过 vault 加密的后门) - 编译警告允许带 `#[allow(...)]`,但新代码不写 `unwrap()` 除非能证明 panic-safe --- ## 2. CLI 用法速记 ```bash # ── Vault 管理 ────────────────────────────────────────────────────── # 一次性初始化(init 本身不要求 Touch ID — 此时还没有可保护的东西) xop init # init 问 passphrase ×2,然后自动写 ~/.x/xop/keyring(0600 文件 keyring, # 存 argon2 派生密钥的 hex;不是 macOS Keychain): # 本地真 TTY:弹指纹 → 通过 → 静默读 keyring,零 passphrase # SSH 交互 / 无可用指纹 / Linux 交互:必须手输 xop passphrase(keyring 不参与) # headless 自动化(agent/pipe/无 pty):跳过闸门 + keyring 静默 # 管理:xop key(状态)/ xop key --save(补写,老 vault 用它启用免密) # xop key --remove(吊销,回到手输) # revoke:`xop reset --yes` 会级联删 keyring 文件 # 存 / 列 / 取 / 删 secret(keyring 已存则免 passphrase) xop set DB_PASS # TTY 上值输入带部分 mask(前 2 位明文 + *) echo "hunter2" | xop set DB_PASS # 非 TTY(pipe/agent)从 stdin 读值 xop list # 列 key 名 + 描述(不显示 value)——免密免 Touch ID xop list git_local # 搜索:**不用引号、不用通配符**(子串匹配 key 名 + 描述,大小写不敏感) xop list 'git_local*' # 带 * ? [ 的词自动切 glob 语义(老写法仍可用) xop list --names-only # 只列名字,不显示描述 xop desc DB_PASS 生产库密码 # 给 key 写描述(存进加密 vault)——免密免 Touch ID xop desc DB_PASS # 不带文字 = 清除描述(不用敲空引号) xop get DB_PASS # 默认脱敏输出 `su****【xop禁止将密钥泄漏】`(前 2 位)——要过闸门 xop get DB_PASS -v # 明文——人眼核对专用;AI agent 禁止 -v(明文会进模型上下文),用 xop run --secret 注入 xop rm DB_PASS # 删除单个 xop reset --yes # 删整个 vault + audit + keyring(应急) # ── Exec-mode:envp 注入(传统)────────────────────────────────────── xop --secret DB_PASS=db_pass \ --allow-net=mysql.local:5432 --deny-net='*' \ -- mysql -h mysql.local -u app mydb # ── `xop run`:envp 注入 + argv 占位符(推荐用于 SSH)──────────────── # envp 注入:vault 值 → 子进程环境变量(sshpass -e 读 $SSHPASS) xop run --secret SSHPASS=s11_pass \ --allow-net=192.168.1.19:22 --deny-net='*' \ -- sshpass -e ssh rong@192.168.1.19 'ls /Users' # argv 占位符:vault 值直接替换 argv 里的 %XOP_KEY% 字符串 # ⚠️ 替换后的字符串会出现在 /bin/ps 里 —— 密码用 --secret,命令行参数用 %XOP_KEY% xop run -- ssh user@host 'echo connect with %XOP_DB_PASS%' # SSH_ASKPASS 注入(v0.4,推荐用于直连 ssh)—— 密码既不进 argv 也不进 env: # mkdtemp 0700 临时目录里写 0600 data + 0700 getpass.sh,子进程通过 # SSH_ASKPASS=