影响: key 多了人/AI 可读的用途说明(存加密 vault 内,不落明文文件); `xop list` 的搜索不用再打引号; `xop list` / `xop desc` 只碰元数据、 永不吐 value,因此不再弹指纹、不再问口令 —— agent 跑 xop 不会被打断。 118 unit + 40 integration 全绿。 改动: - 新增 `xop desc KEY [TEXT...]`: 描述存 vault 的 `__meta__` TOML 子表; 文字用空格 join(不用引号), 真打进 vault 的一层引号会被剥掉; 不写文字 = 清除描述(不用敲空引号 "") - `xop list [TERM...]`: 搜索默认改成大小写不敏感的子串匹配, 命中 key 名 或描述, 不用引号、不用通配符; 含 `*` `?` `[` 的词仍切 glob 语义 (老写法 `xop list 'git_*'` 行为不变); 多词取并集 - 新增 `Vault::open_metadata` / `open_metadata_at`: 只开元数据路径, 0600 keyring 静默解锁, 无 keyring 才回落手输 passphrase; `get`/`set`/`rm`/`run` 仍走 `Vault::open` 全套闸门 - 新增 `auth::Intent` + `auth::needs_gate(intent)`: 把"哪些操作要闸门" 写成纯函数; `Vault::open` 与 `open_metadata` 共享 `decrypt_with` 核心 - 新增 `src/glob.rs`: 轻量匹配器, `*` 任意长 / `?` 单字符, 零新依赖; 搜索用的 `has_meta` / `matches_ignore_case` / `contains_ignore_case` / `contains_glob_ignore_case` - 新增 `src/datadir.rs`: 数据目录 `~/.xop/` → `~/.x/xop/`, 迁移是 **复制不移动**(旧目录留作备份), 新 vault 已存在则跳过 - `keyring::load_at` / `save_at` 改 pub(路径显式化, 单测不碰全局 HOME) - `audit.rs` 新增 `vault_desc(name)`: 只记 key 名, 描述文字不入日志(I2) - 集成测试新增 pty 回归 `list_under_a_tty_never_prompts_for_biometrics`: `script -q /dev/null` 起真 pty + 30s 超时, 闸门若回来则失败而非挂死 - 版本 0.4.0 → 0.5.2; AGENTS.md / HANDOFF.md / docs/* 同步; examples 里 v0.5 搬家前的 `~/.xop/` 残留路径一并修正 设计: "搜索要打引号"的根因是 shell 通配符(`*` 在 zsh 下没匹配文件直接 `no matches found`), 不是 xop —— 所以正解不是"少打引号", 而是让日常 搜索根本不需要通配符: 默认子串匹配, `*`/`?`/`[` 只在用户显式写了时才 切回 glob。免闸门只给元数据操作: 闸门的意义是"释放真值前确认有人在场", 而 list/desc 永不吐 value; 值路径(get/set/rm/run)一行没动。 Co-Authored-By: Claude Code <[email protected]>
351 lines
38 KiB
Markdown
351 lines
38 KiB
Markdown
# 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 [email protected] '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=<script> + SSH_ASKPASS_REQUIRE=force 调用,srm -m 自动清理
|
||
xop run --askpass=ssh_pass -- ssh user@host
|
||
|
||
# 批量注入(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 免输)
|
||
- **`xop list` / `xop desc` 免密免 Touch ID**(v0.5.1,用户要求"AI 做会中断"):这两个只读/写**元数据**(key 名 + 描述),永远不吐 value,所以**跳过 OS 身份闸门**,走 `Vault::open_metadata`(keyring 静默解锁;没 keyring 才回落到手输 passphrase)。**`get` / `set` / `rm` / `run` 仍然全套过闸门**——`auth::needs_gate(Intent::Value) == true`
|
||
- `xop desc` 的文字**不用打引号**:`xop desc KEY 生产库 密码` 会被 join 成「生产库 密码」;`xop desc KEY`(不带文字)= 清除描述
|
||
|
||
---
|
||
|
||
## 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**:`~/.x/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`/`Intent`/`needs_gate`)+ `touchid.rs`(`Outcome`/`classify`) |
|
||
| **免密元数据读(v0.5.1)**:跳过闸门的 vault 打开路径 | `src/vault/mod.rs::open_metadata` / `open_metadata_at`(keyring 静默,无 keyring 才问 passphrase) |
|
||
| 子命令(init / set / list / get / rm / reset / key / desc / run) | `src/commands/{init,set,list,get,rm,reset,key,desc}.rs` + `src/lib.rs::run_join_and_exec` |
|
||
| **glob 匹配器(v0.5)**:`*` 任意长、`?` 单字符,大小写敏感,无依赖;v0.5.2 加 `has_meta` / `matches_ignore_case` / `contains_ignore_case` / `contains_glob_ignore_case`(搜索用) | `src/glob.rs`(`matches` / `matches_any` / `has_meta` / `contains_*`) |
|
||
| **数据目录(v0.5)**:`~/.x/xop/` 路径解析 + 旧 `~/.xop/` 一次性迁移(复制不移动) | `src/datadir.rs`(`home` / `legacy_home` / `migrate_legacy`) |
|
||
| **描述元数据(v0.5)**:vault 内 `__meta__` 子表存 desc | `src/vault/mod.rs`(`Meta` / `decode_plaintext` / `encode_plaintext` / `set_description` / `list_with_desc`) |
|
||
| `%XOP_KEY%` argv 占位符 + 单 vault open 协调 | `src/lib.rs::expand_xop_placeholders` + `src/injector.rs::scrub_argv` |
|
||
| **SSH_ASKPASS 注入(v0.4)**:mkdtemp + 0600 data + 0700 脚本,`Drop` 自动 `srm -m` | `src/askpass.rs` |
|
||
| 怎么注入到子进程 | `src/injector.rs::plan` + `build_envp_delta`(按 `argv_placeholder` 过滤;askpass 由 `run_exec` 单独 setup) |
|
||
| 子进程 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 文件清掉 | `askpass::AskpassHandle::Drop` 跑 `srm -m`,fallback `rm -rf`;`XOP_ASKPASS_DATA` 路径不暴露在 argv | `cargo test askpass::tests::drop_runs_teardown` + integration `run_askpass_cleans_temp_dir_on_exit` |
|
||
| **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 两次修订)**。例外(v0.5.1,用户要求):纯元数据操作(`list`/`desc`,永不吐 value)走 `open_metadata`,跳过闸门直接用 keyring** | `Vault::open`:`auth::authenticate() → Gate`;`AllowKeyring` 才 `keyring::load()`,`RequirePassphrase` 直接 prompt(SSH env / 无生物特征 / osascript 坏 / Linux 交互);`XOP_NO_KEYRING=1` 强制手输;keyring mode 非 0600 报错拒用;代码库无 `security(1)` 调用。**元数据例外**:`auth::needs_gate(Intent::Metadata) == false`,`Vault::open_metadata` 只在 keyring 命中时静默 | `cargo test auth::tests::decide_*`(5 条决策表)+ `cargo test auth::tests::metadata_operations_skip_the_gate_values_do_not` + `cargo test vault::tests::open_metadata_uses_the_keyring_without_prompting` + 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-22,v0.5)
|
||
|
||
✅ **已完成(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`(`~/.x/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 校验通过
|
||
|
||
✅ **v0.3 (2026-10-07,argv 占位符语法改名)**:
|
||
- argv 占位符语法从 `xop://KEY` 改为 `%XOP_KEY%`——更直观、grep 友好(`grep '%XOP_'` 一抓一个准)、无 shell 展开冲突
|
||
- 旧 `xop://KEY` 在 `expand_xop_placeholders` 前置 reject,清晰报错 `xop://KEY 占位符在 v0.3 移除;请改用 %XOP_KEY%`,不留静默坑
|
||
- regex 由 `xop://([A-Za-z_][A-Za-z0-9_]*)` 改为 `%XOP_([A-Za-z_][A-Za-z0-9_]*)%`(前缀需大写 `XOP_`,后缀 `%`)
|
||
- 64 unit + 17 integration 全绿;`run_masks_argv_placeholder_value` 用 `%XOP_PH%` 重写
|
||
|
||
✅ **v0.4 (2026-10-07,SSH_ASKPASS 注入)**:
|
||
- 新增 `xop --askpass=NAME` / `xop run --askpass=NAME`:解决「直连 `ssh user@host` 时密码无处放」的根问题——`%XOP_PASS%` 替换后会出现在 ps,`SSHPASS` env 只能给 `sshpass -e` 用,ssh 本身不读 env
|
||
- 实现:`mkdtemp(0700)` 建 `/tmp/xop-askpass-XXXXXX/`,写 0600 data + 0700 `getpass.sh`(`cat "$XOP_ASKPASS_DATA"`),子进程设 `SSH_ASKPASS=<script>` + `SSH_ASKPASS_REQUIRE=force` + `DISPLAY=:0` + `XOP_ASKPASS_DATA=<data>`,值永不进 argv/env
|
||
- `AskpassHandle::Drop` 跑 `srm -m`(无 srm 时 fallback `rm -rf`)——临时文件被回收(包括子进程崩溃、scope exit)
|
||
- `SecretRef::askpass()` 构造器 + `askpass: bool` 标志(沿用 v0.3 argv_placeholder 模式);`run_exec` 把 askpass refs 从 `envp_resolved` 切出来单独 setup,stdout guard 仍能 mask 全值兜底
|
||
- 移除 `injector::plan()` 的 SSH_* 自动检测:askpass 现在显式 opt-in,跟 v0.3「少魔法」一致——`--askpass=ssh_pass -- ssh user@host` 显式给,`--secret SSHPASS=ssh_pass -- sshpass -e ssh user@host` 显式走 sshpass
|
||
- 用法:`xop run --askpass=ssh_pass -- ssh user@host`(不在 argv、不在 env、不在 stdout)
|
||
- v0.4 单 secret 限制:多 secret askpass(e.g. ssh passphrase + sudo)P2;SIGKILL 残留靠 `/tmp` launchd 清理
|
||
- 68 unit(+4 askpass 单测)+ 6 askpass 集成测试(env 设置 / 脚本输出 / 临时目录清理 / 不进 env / 缺 key / 与 env 注入并行)
|
||
- **端到端实测通过 (2026-10-07,192.168.1.19)**:`xop run --askpass=s19_pass -- ssh '%XOP_s19_user%@host'` 真 SSH 登录跑通;`Drop` 跑完 `/tmp/xop-askpass-*` 零残留;stdout guard 把 `%XOP_s19_user%` 替换的真用户名也 mask 掉
|
||
|
||
✅ **v0.5 (2026-10-22,list glob 过滤 + 描述元数据 + 数据目录搬家)**:
|
||
- **影响**:`xop list` 从「一屏裸 key 名」变成「带描述、可过滤」;key 多了人/AI 可读的用途说明(存在**加密 vault 内**,不落明文文件)
|
||
- `xop list [GLOB...]`:可给多个 pattern 取并集,`*` 任意长、`?` 单字符、大小写敏感;内置轻量匹配器 `src/glob.rs`,**零新依赖**;`--names-only` 只列名字
|
||
- `xop desc KEY "文本"`:唯一形态(无 list-all / show-one / --clear 子形态),空串 `""` = 清除描述;描述存进 vault 的 `__meta__` 子表(TOML)——**引号与清除方式在 v0.5.1 改过,见下**
|
||
- vault 明文格式:无描述时保持**旧的扁平布局**(`KEY = "value"`),老版本 xop 二进制仍能读;有描述时追加 `[__meta__]` 子表
|
||
- **数据目录搬家**:`~/.xop/` → `~/.x/xop/`(key.db / keyring / audit.jsonl 全搬)。迁移是**复制不是移动**——旧目录留作备份,新 vault 已存在时迁移自动跳过
|
||
- 96 unit + 32 integration 全绿;`cargo fmt --all` + clippy 无新增告警
|
||
|
||
✅ **v0.5.1 (2026-10-22,两处用户反馈修正)**:
|
||
- **影响 1 · 描述不用打引号**:`xop desc KEY "文本"` → `xop desc KEY [TEXT...]`,多个词用空格 join(`xop desc KEY 生产库 密码`)。带引号也兼容(shell 通常会吃掉;真打进 vault 的会被剥一层)。**不写文字 = 清除描述**——不用再敲空引号 `""`
|
||
- **影响 2 · `xop list` / `xop desc` 免密免 Touch ID**(用户:"AI 做会中断"):这两个只碰元数据(key 名 + 描述),永不吐 value,所以**跳过 OS 身份闸门**(`Vault::open_metadata`,keyring 静默解锁;无 keyring 才回落手输 passphrase)。`get`/`set`/`rm`/`run` 仍全套过闸门(`auth::needs_gate(Intent::Value)`)
|
||
- 新增 `auth::Intent` + `auth::needs_gate(intent)` 把"哪些操作要闸门"写成可测的纯函数;`Vault::open` 与 `open_metadata` 共享 `decrypt_with` 核心
|
||
- 集成测试新增 pty 回归测试 `list_under_a_tty_never_prompts_for_biometrics`:用 `script -q /dev/null` 起真 pty(pty 里 `is_terminal()` 为真),带 30s 超时——闸门若回来就会卡在 Touch ID 弹窗上,测试即挂
|
||
- 107 unit + 36 integration 全绿
|
||
|
||
✅ **v0.5.2 (2026-10-22,`xop list` 搜索也不用打引号)**:
|
||
- **影响**:`xop list` 的搜索词默认是**纯子串匹配**——`xop list git_local` 直接命中 key 名或描述里含 "git_local" 的行,**不用引号、不用 `*`**。老写法 `xop list 'git_*'` 仍然可用
|
||
- **为什么**:`*` 是 shell 元字符——zsh 里 `xop list git_local*` 没匹配文件会直接报 `no matches found`,所以"带通配符的搜索"天生要引号。解法不是"少打引号",而是**让日常搜索根本不需要通配符**
|
||
- 匹配规则:搜索词**不含** `*` `?` `[` → 大小写不敏感的子串匹配,命中 **key 名或描述**;含元字符 → 该词切 glob 语义(整名匹配 key,或在描述里"某处出现"),老语义不变
|
||
- 多个搜索词取并集(`xop list git s19`);`--names-only` 不变
|
||
- `src/glob.rs` 加 4 个 helper:`has_meta` / `matches_ignore_case` / `contains_ignore_case` / `contains_glob_ignore_case`(底层 `matches` 仍大小写敏感、纯 glob 引擎)
|
||
- 118 unit + 40 integration 全绿
|
||
|
||
⚠️ **P1 / 未来工作**:
|
||
- ~~`spawn_child` 真实现~~ ✅ v0.2
|
||
- ~~`pipe_filter_loop` 真实现~~ ✅ v0.2
|
||
- ~~`build_envp_delta` 真实现~~ ✅ v0.2
|
||
- ~~`xop://KEY` argv 占位符 (v0.2 引入,v0.3 改名 `%XOP_KEY%`)~~ ✅
|
||
- ~~Askpass 注入策略(SSH_ASKPASS + DISPLAY=:0 + SSH_ASKPASS_REQUIRE=force)~~ ✅ v0.4
|
||
- ~~`xop list` glob 过滤 + `xop desc` 描述元数据~~ ✅ v0.5
|
||
- 多 secret askpass(v0.4 单 secret;P2)
|
||
- `NetworkGuard` 的 pf/iptables 真接入(当前是 stub,新 vault flow OK)
|
||
- `FileGuard` 的 sandbox-exec/landlock 真接入(当前是 stub)
|
||
- 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** — `~/.x/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`。
|
||
|
||
22. **vault key 名 ≠ 字面值** — `s19_user`/`s19_pass` 是 vault 里的 **key 名字**(`xop list` 列的那些),不是 SSH 用户名/密码的**真值**。SSH 命令里用户名走 `%XOP_s19_user%` argv 占位符,密码走 `--askpass=s19_pass`。若把字面 `s19_user` 当 SSH 用户名传过去,server 自然不认识 → "Permission denied"。调试时若拿不准 key 下存的是什么,用 `%XOP_key%` 占位符+stdout guard 拿 mask 前缀(不暴露值)反推;严禁 `xop get -v key`(明文进上下文)。
|
||
|
||
23. **数据目录搬家 `~/.xop/` → `~/.x/xop/` 是「复制不移动」** — 用户的真实 vault 有 18+ key,迁移只做**复制**(key.db / keyring / audit.jsonl),旧目录原样留作备份;新目录已有 vault 时迁移自动跳过。`src/datadir.rs::migrate_legacy_from(new, old)` 路径参数显式化,单测不碰全局 `HOME`(AGENTS.md 坑 18 同款纪律)。新目录 0700、复制出的文件 0600。
|
||
|
||
24. **vault 明文里加 `__meta__` 子表不破坏旧格式** — toml 0.8 序列化时**普通值先于表输出**,所以 `KEY = "value"` + `[__meta__]` 不会触发 ValueAfterTable。`encode_plaintext` 在 meta 为空时**完全省略 `__meta__` 表**,让没描述的 vault 保持旧的扁平布局,老版本 xop 二进制照样能读。
|
||
|
||
25. **glob 匹配器自研而不是引 globset** — 需求只有 `*` 和 `?`;引依赖会带来正则语义(`[]`/`{}`)与 xop「零外部依赖」的定位冲突。`src/glob.rs` 经典双指针 + 回溯 star 记录,11 条单测覆盖 exact/前缀/后缀/中缀/多星/问号/空串/大小写/并集。注意 `*` 不匹配字面 `_`:`matches("*_user","user")` = false。
|
||
|
||
26. **元数据操作要免闸门,值操作不能免** — 2026-10-22 用户反馈:"`xop list` 应该是免密免 touch 的吧,不然 AI 做会中断"。闸门的意义是"释放真值前要有人在场",而 `list`/`desc` 只给 key 名和描述,**永不吐 value**,所以跳过闸门不泄漏任何 secret。实现上别图省事把 `Vault::open` 的闸门参数去掉——那会让 `get`/`run` 也免掉;正确做法是**新增一条 `open_metadata` 路径**,并用 `auth::needs_gate(Intent)` 把策略写成可测的纯函数
|
||
|
||
27. **pty 回归测试用 `script -q /dev/null`** — macOS 的 `script` 能给子进程起真 pty(`test -t 0` 为真),正好复现"终端里跑 `xop list`"的场景。关键是要**带超时**:闸门一旦回来,子进程会卡在 Touch ID 弹窗上,测试会挂死而不是失败。用 `std::sync::mpsc::recv_timeout` + 后台线程收 `wait_with_output` 兜住
|
||
|
||
28. **描述文字不要求引号,但兼容引号** — 用户明确说「打引号很难输入」(中文输入法/键盘布局)。所以 `xop desc` 的文字参数用 `Vec<String>` + `trailing_var_arg`,多个词 join 成一句;用户真打进 vault 的一层引号在 `join_description` 里剥掉。注意剥引号时的切片安全:只认 ASCII 单字节引号,切点必然是 char 边界
|
||
|
||
29. **"搜索要打引号"的根因是 shell,不是 xop** — `xop list 'git_local*'` 必须加引号,因为 `*` 是 shell 通配符:zsh 下 `xop list git_local*` 没匹配文件直接报 `no matches found`,bash 下则被展开成一堆文件名。**引号是躲 shell 的,不是躲 xop 的**。所以正解不是"想办法少打引号",而是**让日常搜索根本不需要通配符**——v0.5.2 把默认搜索改成纯子串匹配(`xop list git_local`),`*`/`?`/`[` 只在用户显式写了时才切回 glob 语义。想给 shell 递一个"不展开"的参数只能靠引号或反斜杠,`xop` 这边无能为力
|
||
|
||
---
|
||
|
||
## 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. |