Files
xop/AGENTS.md
T
2026-10-02 18:25:29 +08:00

276 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# xop · AI Agent 操作速查(上下文压缩后自动加载)
> 本文件是 **xop 给 AI agent 的"可执行附录"**:Claude Code / WorkBuddy / 其他 agent harness 在每次会话开头、以及**上下文压缩(compact)后**都会自动重新加载它。
> 项目根:`/Users/xs/Documents/xop`
> 完整交接文档在 [`HANDOFF.md`](./HANDOFF.md);架构/威胁模型/对比在 [`docs/`](./docs/)。
---
## 0. 一句话定位
**xop = 自带加密 vault + OS-auth gate 的 secret 注入器**。`xop init | set | list | get | rm` 管理本地 vault(`~/.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 `~/.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/xop
# 快速检查(增量编译,最常用)
cargo check --all-targets
# 跑单元测试(64 个:args(含 get -v 解析)/ secret / policy / audit / vault / keyring / auth(touchid classify + decide 决策表)/ stdout-guard / error / injector)
cargo test --lib
# 跑集成测试(17 个:help / dry-run / bad-ref / secrets-file / mask 端到端 / keyring 免密解锁 / SSH-headless / get 默认 mask / get -v 明文)
# 集成测试需要 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,然后自动写 ~/.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)
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 值 → 子进程环境变量
xop run --secret SSHPASS=s11_pass \
--allow-net=192.168.1.19:22 --deny-net='*' \
-- sshpass -e ssh [email protected] 'ls /Users'
# argv 占位符:vault 值直接替换 argv 里的 xop://KEY 字符串
# ⚠️ 替换后的字符串会出现在 /bin/ps 里 —— 密码用 --secret,命令行参数用 xop://
xop run -- ssh user@host 'echo connect with xop://DB_PASS'
# 批量注入(commit-safe 的 .env.xop 文件,每行 KEY=NAME)
xop --secrets-file .env.xop -- ./deploy.sh
# Dry-run:只看 policy,不真执行(AI 自检的 killer feature)
xop --dry-run --secret FOO=foo --allow-net=db:5432 --deny-net=* -- deploy.sh
```
**注意**:
- `KEY=NAME` 必须在 `--` 之前;`--` 后是子命令 + 它的 args
- bash 会展开 `$VAR`,所以 secret 引用**不要**直接写在命令行里——用 `--secret` flag 或 `xop://KEY` 占位符
- v0.2 删了 `--backend` 和所有 scheme 前缀(`op://`、`vault://`)——只有 bare key
- `--dry-run` 在 resolve 之前短路,**不开 vault、不过 OS 闸门**——纯本地打印有效 policy(集成测试 `dry_run_prints_effective_policy` 无 bypass env 也过)
- Passphrase 提示策略:stdin 是真 TTY → 走 `/dev/tty`(隐藏输入),stdin 不是 TTY(agent / pipe / expect)→ fallback 到 stdin。**Release binary 永远不读 `XOP_VAULT_PASSWORD` env**——passphrase 必须用户亲输(或走 keyring 免输)
---
## 3. 模块地图
| 想了解 | 看哪里 |
|---|---|
| CLI 所有 flag + 解析 + Subcommand enum | `src/args.rs` |
| ref 长啥样 + 怎么解析(bare `KEY=NAME` + `argv_placeholder` 标志) | `src/secret.rs` |
| 错误类型 + 退出码(BSD sysexits) | `src/error.rs` |
| 权限策略(allow/deny 默认值) | `src/policy.rs::DEFAULT_DENY_READ` + `Policy::from_args` |
| **本地 vault**:文件格式 + 加密 | `src/vault/mod.rs` + `src/vault/format.rs` |
| **文件 keyring**:`~/.xop/keyring` 0600 免密解锁(非 Keychain) | `src/vault/keyring.rs`(路径显式的 `*_at` 核心 + env 门控 wrapper) |
| **OS auth gate**:macOS 真指纹(LAContext via JXA)+ `Gate` 决策(headless/SSH/无指纹/取消) | `src/auth/mod.rs`(`Gate`/`Bio`/`decide`/`ssh_session`)+ `touchid.rs`(`Outcome`/`classify`) |
| 子命令(init / set / list / get / rm / reset / key / run) | `src/commands/{init,set,list,get,rm,reset,key}.rs` + `src/lib.rs::run_join_and_exec` |
| `xop://KEY` argv 占位符 + 单 vault open 协调 | `src/lib.rs::expand_xop_placeholders` + `src/injector.rs::scrub_argv` |
| 怎么注入到子进程 | `src/injector.rs::plan` + `build_envp_delta`(按 `argv_placeholder` 过滤) |
| 子进程 stdout 怎么过滤 | `src/guard/stdout.rs::pipe_filter_loop` |
| 网络/文件策略怎么落 | `src/guard/{network,file}.rs`(STUB,P1) |
| 审计日志格式 + 不变量 | `src/audit.rs`(test `no_value_field_in_any_event` 扫 4 个关键字) |
| 编排 exec-mode pipeline | `src/lib.rs::run_exec`(9 阶段) |
| TTY-aware passphrase prompt(`/dev/tty` vs stdin fallback) | `src/vault/mod.rs::rpassword_prompt` |
| Test-only `XOP_VAULT_PASSWORD` 旁路(gated by Cargo feature) | `src/vault/mod.rs` 的 `#[cfg(feature = "test-bypass")]` 块 + `Cargo.toml::[features]` |
| spawn 真实现(pre_exec + setrlimit) | `src/lib.rs::spawn_child` |
---
## 4. 关键不变量(违反任一 = 安全漏洞)
| # | 不变量 | 谁保证 | 验证方式 |
|---|---|---|---|
| I1 | LLM API / IPC / shell history **永远不出现 secret value** | `--secret KEY=NAME` flag 设计 + vault 用 `SecretBox<String>` 包装值 | code review:grep `expose_secret` 限定在 injector / guard 内 |
| I2 | 审计日志**没有 `value`/`plaintext`/`ciphertext`/`passphrase` 字段** | `audit::AuditLog` 只接收 `serde_json::Value`,不接收 `ResolvedValue` | `cargo test audit::tests::no_value_field_in_any_event` |
| I3 | `SecretBox::Debug` 打印 `<secret>` | `secrecy` crate 保证 | `cargo test secret::tests` |
| I4 | 真值只在 fork 前短暂活在 parent 内存 | `injector::build_envp_delta` 拷贝值进 envp 后立刻 drop parent 端 | 手动 review spawn_child |
| I5 | `--allow-net`/`--deny-net` 默认 deny-by-default | `Policy::from_args` 不接受空 allow 等于全 deny | `cargo test policy::tests` |
| I6 | 子进程退出时 temp 文件清掉 | injector::askpass 负责 `srm -m` + `rm`(P1) | 手动 review + OS-level verification |
| **I7** | **vault 文件只有 passphrase 能解密**(v0.2 新增) | AES-256-GCM + argon2id KDF;OS auth 只是 pre-gate | `cargo test vault::format::tests` |
| **I8** | **keyring 静默解锁只在身份已被证明时允许(本地指纹通过 / headless 自动化);SSH 与无指纹交互场景必须输 xop passphrase,keyring 不参与;且 xop 从不触碰 macOS Keychain**(v0.2.1 两次修订)| `Vault::open`:`auth::authenticate() → Gate`;`AllowKeyring` 才 `keyring::load()`,`RequirePassphrase` 直接 prompt(SSH env / 无生物特征 / osascript 坏 / Linux 交互);`XOP_NO_KEYRING=1` 强制手输;keyring mode 非 0600 报错拒用;代码库无 `security(1)` 调用 | `cargo test auth::tests::decide_*`(5 条决策表)+ code review `vault/mod.rs::open` |
| **I11** | **子进程 stdout/stderr 里的 vault 值必被 mask**(v0.2.1 新增) | `pipe_filter_loop` 行缓冲 + `StdoutGuard::filter`;`--on-leak=kill/refuse` 时 SIGKILL | `cargo test guard::stdout::tests` + integration `run_masks_*` |
| **I9** | **release binary 不读 `XOP_VAULT_PASSWORD` env**(v0.2 新增) | 旁路仅在 `#[cfg(feature = "test-bypass")]` 编译时存在;release 用 `cargo build --release`(不带 feature) | `strings target/release/xop \| grep XOP_VAULT_PASSWORD` 应无匹配 |
| **I10** | **vault 每次 exec 只开一次**(v0.2 新增) | `--secret` 和 `xop://KEY` 占位符共享同一个 `resolve_all` 调用 | code review:`run_join_and_exec` + `run_exec` |
---
## 5. 当前状态(2026-10-02,v0.2.1)
✅ **已完成(v0.2 pivot 完成)**:
- 删除 `src/backend/{op,vault,kc,env}.rs` + `mod.rs`(4 个外部后端)
- 新增 `src/vault/`:AES-256-GCM + argon2id,atomic write,单元测试覆盖 round-trip / wrong key / 不同 passphrase
- 新增 `src/auth/`:macOS Touch ID(osascript)+ Linux PAM(pkexec)subprocess 方式;TTY 检测 + 1FA fallback
- 新增 `src/commands/`:`init`/`set`/`list`/`get`/`rm`/`reset` 6 个子命令
- 新增 `xop run` 子命令:`--secret KEY=NAME`(envp 注入) + `xop://KEY`(argv 占位符),通过 `SecretRef::argv_placeholder` 区分
- 新增 `xop reset --yes` 子命令:清空 vault + audit
- subcommand enum:`init / set / list / get / rm / reset / run / help`
- `Args` 重构:`subcmd: Option<Subcmd>` + flat exec 字段 + `Args::as_exec()` + `ExecArgs.argv_placeholders`
- `run_join_and_exec`:单次 vault 开锁统一解析 `--secret` 和 `xop://KEY`;`scrub_argv` 替换 argv、`build_envp_delta` 仅生成 envp
- `spawn_child` 真实现:`tokio::process::Command` + `pre_exec` 闭包设 `RLIMIT_CORE=0`
- `pipe_filter_loop` 真实现:stdout/stderr 双 pipe reader,过滤后写回 inherited
- `build_envp_delta` 真实现:从 `ResolvedValue[]` 生成 `Vec<(String, String)>`,按 `argv_placeholder` 过滤
- TTY-aware `rpassword_prompt`:stdin 是 TTY → `/dev/tty`;stdin 不是 TTY → fallback stdin(agent / pipe / expect 友好)
- Cargo feature `test-bypass`:仅在 `cargo test --features test-bypass` 时启用 `XOP_VAULT_PASSWORD` 旁路;**release 永不包含**
- 39 unit test + 11 integration test 全绿
- `Makefile`:build / install(`/usr/local/bin/xop`)/ uninstall / test / smoke / clippy / clean
- 4 篇 docs 全部更新到 v0.2(design / architecture / threat-model / comparison)
- 端到端 SSH 实测:`xop run --secret SSHPASS=s11_pass -- sshpass -e ssh [email protected] ls /Users` 跑通
✅ **v0.2.1(2026-10-02,用户实测 4 问题修复)**:
- `xop set` 值输入不再明文回显:TTY 走 rpassword `password_feedback_partial_mask('*', 2)`(前 2 位明文 + 其余 `*`)
- 免密解锁改用**文件 keyring**:`src/vault/keyring.rs`(`~/.xop/keyring`,0600 hex 密钥,`xop init` 自动写);OS 预闸门照旧先跑,之后 `set/list/get/rm/run` 免 passphrase → **AI agent 可无人值守跑 `xop run`**。曾实现过 macOS Keychain 方案,因自动化时弹系统授权对话框被用户否决并整体删除——xop 不调 `security(1)`
- OS 闸门改为**真指纹**:`src/auth/touchid.rs` 用 `osascript -l JavaScript` 调 `LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)`(biometrics-only,弹窗里没有密码框可点)。旧的 `do shell script "…" with administrator privileges` 实为**系统登录密码框**,且取消后被当"不可用"静默降级继续执行(实测 `xop set` 取消指纹仍存了 secret)——现取消/拒绝一律 `AuthCancelled` exit 77;无指纹设备/会话 → xop passphrase;Linux pkexec 系统口令框删除(gate 变为 no-op)
- 新增 `xop key [--save|--remove]` 子命令:查看/补写/吊销 keyring(用户既有 vault 跑一次 `xop key --save` 即启用免密)
- `xop get` 默认脱敏:输出 `su****【xop禁止将密钥泄漏】`(前 2 位,同 I11 mask 格式),明文只在显式 `-v/--value` 时打印且 stderr 带警示。动因:agent 会话里 `xop get` 的 stdout 直接进模型上下文/日志/shell history——I1 在"读取"路径上原本不设防。`-v` 是人眼专用逃生门,agent 用密钥必须走 `xop run --secret` 注入
- SSH 实测二次修正:闸门返回 `Gate`(`auth::decide` 纯函数决策表)——**SSH 交互会话绝不弹指纹**(`SSH_TTY/SSH_CONNECTION/SSH_CLIENT` 检测;LAContext 弹窗只会出现在本机控制台),且**无指纹现证(SSH/无生物特征/Linux 交互/osascript 坏)时 keyring 不参与解锁,强制输入 xop passphrase**;只有「本地指纹通过」或「headless 非 TTY 自动化」允许 keyring 静默。`Vault::open` 按 Gate 分支。Linux 不再有 `pam.rs`
- stdout leak guard 修复真 bug:`pipe_filter_loop` 的 `guard_for_reader` 原来是直通 stub(这就是用户看到 `xop run echo xop://s19_pass` 打印明文 `123456` 的原因);现在按行 buffer(跨 chunk 的密钥不漏检)+ mask 格式 `12****【xop禁止将密钥泄漏】` + `kill/refuse` 时 SIGKILL 子进程 + audit `leak_event`
- `xop reset --yes` 级联删 keyring 文件
- 64 unit + 17 integration 全绿(端到端 mask ×2、keyring 免密解锁 ×1——`env_remove` 掉口令通道验证 `run` 仍成功、touchid LAError 分类 ×8、auth 决策表 decide ×5、SSH+headless 仍走 keyring ×1、get 默认 mask ×2);release 构建 I9 strings 校验通过
⚠️ **P1 / 未来工作**:
- ~~`spawn_child` 真实现~~ ✅ v0.2
- ~~`pipe_filter_loop` 真实现~~ ✅ v0.2
- ~~`build_envp_delta` 真实现~~ ✅ v0.2
- ~~`xop://KEY` argv 占位符~~ ✅ v0.2
- `NetworkGuard` 的 pf/iptables 真接入(当前是 stub,新 vault flow OK)
- `FileGuard` 的 sandbox-exec/landlock 真接入(当前是 stub)
- Askpass 注入策略(SSH_ASKPASS + DISPLAY=:0 + SSH_ASKPASS_REQUIRE=force)
- argv scrubber(检测 `--password=value` 等显式模式)
完整 TODO 列表见 [`HANDOFF.md`](./HANDOFF.md)。
---
## 6. 常见踩坑(来自实测 + 设计权衡)
1. **bash 会展开 `$VAR`** — `xop ssh user:$SSH_PASSWORD@host` 在 bash 里 `$SSH_PASSWORD` 先被 bash 展开成真值,xop 看到的是真值。**永远用 `--secret KEY=NAME` flag**。
2. **`secrecy::SecretBox` 的 `expose_secret()`** — 必须 `use secrecy::ExposeSecret;` 才能调。如果 import 漏了,编译错 E0599。`./src/{secret,guard/stdout,vault/mod.rs}.rs` 都已加。
3. **`async fn` in trait 必须 `#[async_trait]`** — `Auth::authenticate` 和 `Guard::setup/teardown` 都是 async。trait 必须 derive `async_trait::async_trait`,且 `Cargo.toml` 依赖 `async-trait = "0.1"`。
4. **`tokio::process::Command` 不支持 setrlimit** — 想在子进程设 `RLIMIT_CORE=0` 必须用 `pre_exec` 闭包(runs after fork, before exec)。当前 `lib.rs::spawn_child` 已实现,参考 `nix::sys::resource::setrlimit`。
5. **`Secret<String>` 在 secrecy 0.10 改名成 `SecretBox<String>`** — 别按 0.8 文档写代码。
6. **stdout mask 用 `Vec<u8>` 不是 `String`** — 子进程的 stdout 可能是 UTF-8 invalid(binary data);用 bytes 避免 `from_utf8` panic。
7. **`audit log` 写之前调 `.flush()`** — 否则 child crash 时 audit 丢失。`AuditLog::write_event` 已 flush。
8. **macOS 指纹 = `osascript -l JavaScript` 调 LAContext,不是 admin 弹窗** — `do shell script … with administrator privileges` 是**系统登录密码框**(红线禁止),且 osascript 会命中 admin 授权缓存导致"看起来免密"其实是缓存放行。正确姿势:JXA `ctx.evaluatePolicyLocalizedReasonReply(1, reason, fn)`(policy 1 = biometrics-only,无密码选项)+ 主线程 `NSRunLoop.runUntilDate` 自旋等 block 回调。实测 JXA 能把**私有队列**的 block 回调 marshal 回 JS 线程(NSOperationQueue 探针 107ms 通过);LAContext 无缓存,每次调用都真弹指纹。取消分类:-128/-5/-12 → 拒绝操作;-7/-8/-10/-11/-1008/-1/-6 → 无指纹降级 passphrase。
10. **Linux 交互 = 直接输 xop passphrase(`pam.rs` 已删除)** — 旧实现 `pkexec -- true` 弹的是 polkit **系统密码框**,违反"任何时候不要让用户输入系统密码"红线(2026-10-02)。Linux 没有可移植的纯指纹 CLI 闸门,身份无法被生物特征证明 → `decide` 返回 `RequirePassphrase`(keyring 也不参与);headless 自动化仍走 keyring 静默。真 Touch ID 闸门仅 macOS 有。
11. **atomic vault write 用 tmp + rename** — `~/.xop/key.db.tmp.<pid>` 写完 fsync 后 rename 到 `key.db`,断电不留下半截文件。
12. **argon2id 参数:m=64 MiB, t=3, p=4** — 慢 ≈250ms / attempt,现代 CPU 上比 bcrypt/scrypt 都强。**别调低**。
13. **`XOP_VAULT_PASSWORD` 是 release 后门,必须 gated** — v0.2 早期把它当 CI/agent 旁路直接读 env,等于"任何有 env 的进程都能解密 vault"。当前用 `#[cfg(feature = "test-bypass")]` 包住;release 永远不编译这段。**校验手段**:`strings target/release/xop | grep XOP_VAULT_PASSWORD` 必须空。
14. **TTY-aware passphrase prompt 怎么选** — `is_terminal(stdin)` 决定走 `/dev/tty` 还是 stdin fallback。如果用 `/dev/tty` 检测(`/dev/tty` 文件存在性)会误判(SSH 下文件存在但不可用)。**用 `std::io::IsTerminal`**(POSIX `isatty(fd)`)才是真信号。
15. **vault 不要开两次** — 早期 `xop run` 内部先 `expand_xop_placeholders` 开一次 vault,再 `run_exec` 开一次,导致用户输两次 passphrase。修复:让 `expand_xop_placeholders` 只收集名字(不开 vault),把 placeholder 加进 `SecretRef::argv_placeholder=true` 的列表,让 `run_exec::collect_refs` 一次性带去 `resolve_all`。**原则:vault 整个进程最多 open 一次**。
16. **`SecretRef::argv_placeholder` 标志位** — 区分 envp 注入(`--secret KEY=NAME`)和 argv 占位符(`xop://KEY`),但走同一个 vault 解析。`build_envp_delta` 跳过 placeholder,`scrub_argv` 处理 placeholder。`ResolvedValue` 镜像这个标志位。
17. **绝不在后台自动化里对真实钥匙串做写/删** — v0.2.1 曾实现 macOS Keychain 存 passphrase,`security(1)` 在 agent 会话里会弹出**系统授权对话框**("xop wants to delete/modify keys"),用户看到就是安全事故,方案整体否决删除。免密改走 0600 文件 keyring:无 GUI、无弹窗、可 `xop key --remove` 秒吊销。
18. **keyring 静默解锁必须"身份有来源"** — `Vault::open` 先 `auth::authenticate() → Gate`:`AllowKeyring`(本地指纹刚通过 / headless 非 TTY 自动化)才读 keyring;`RequirePassphrase`(**SSH 交互会话**、无可用生物特征、osascript 坏、Linux 交互)**直接强制手输 xop passphrase,keyring 根本不参与**——否则"免密"就没有任何身份验证垫底。旧两版 bug:keychain 方案"命中即连闸门都不问";指纹闸门版把 SSH/无指纹也当"降级继续"仍走 keyring。另外:**lib 单元测试禁止改全局 env(`HOME`/`XOP_NO_KEYRING`/`SSH_*`)**——并行跑会互相污染(实测 4 个 keyring 测试因 set_var("HOME") 竞态随机红),文件逻辑/决策逻辑要抽成参数显式的纯函数(`auth::decide(tty, ssh, bio)`、`keyring::*_at(&Path)`)测。
20. **SSH 会话里 `isatty(0)` 是 true,但绝不能弹指纹** — SSH 的 stdin 是 sshd 分配的 pty,TTY 检测≠本地控制台。`LAContext` 的 Touch ID 窗口只会出现在**本机物理控制台**,远程用户既看不到也点不了,表现为"卡住/错弹"。正确做法:检测 `SSH_TTY/SSH_CONNECTION/SSH_CLIENT` env(sshd 注入、本地 Terminal 不会有)→ 直接 `Gate::RequirePassphrase`(用户输管理员密码,keyring 免谈);`ssh host cmd` 无 pty 的自动化场景走 headless keyring 静默。顺序必须 `!tty → AllowKeyring` 先判,tty+ssh 才 RequirePassphrase。
19. **stdout mask 必须按行 buffer** — 子进程输出的一个 4096 字节 chunk 可能把密钥劈成两半;`pump()` 只在遇到 `\n` 时才 filter+flush 完整行,残行留在 carry buffer,EOF 再补一次。直接 filter 每个 chunk 会漏检跨 chunk 密钥。expect/Tcl 断言 mask 时注意 glob 的 `*` 匹配任何字符——要用 `regexp {to\*+} $log` 匹配字面星号。
21. **`xop get` 默认输出的 `su****【xop禁止将密钥泄漏】` 不是 bug,是闸门** — agent 会话里工具 stdout 直通模型上下文;`get` 若回显明文,注入链路(run 子进程 mask)做得再好也白搭——密钥从"读取"这条路就出去了。看到 mask 说明值存在且对路,**继续用 `xop run` 注入即可;严禁给 agent 路径加 `-v`**(`-v` 是给人眼核对的逃生门,stderr 会打警示)。测试:integration `get_masks_value_by_default` / `get_dash_v_prints_plaintext`。
---
## 7. 与 xstudio 的衔接(未来)
xop 是**独立项目**,但定位上是 xstudio `xstudio.ai.runAgentLoop` 的"secret 安全层"。集成路径:
- **短期**:xstudio plugin 通过 `Process.run("/usr/local/bin/xop --secret ... -- <cmd>")` 调用 xop
- **中期**:xop 暴露 `pub use xop::run` library mode,xstudio 直接 link
- **不集成**:xop 永远不需要知道 xstudio 存在(独立开源)
参考 xstudio 项目里的 `xstudio-control` skill(同义物)。
---
## 8. 文档索引
| 想看 | 路径 |
|---|---|
| 一句话定位 + CLI 速查 | 本文件(AGENTS.md) |
| **完整交接 / 实施路线图** | [`HANDOFF.md`](./HANDOFF.md) |
| 整体设计 + 命令 + 架构 + 不变量 | [`docs/design.md`](./docs/design.md) |
| 12 个威胁 + v0.2 缓解状态 | [`docs/threat-model.md`](./docs/threat-model.md) |
| vs secret-agent / op run / Vault Agent / Deno | [`docs/comparison.md`](./docs/comparison.md) |
| 模块依赖图 + 数据流 + trait 表面 | [`docs/architecture.md`](./docs/architecture.md) |
| 参考实现 | `refs/secret-agent/` |
| 实战示例 | `examples/{init,list,get,ssh,mysql,dry-run}.sh` |
| 集成测试 | `tests/integration.rs` |
---
## 9. License
MIT.