SOP：Agent 远端操作入口固化 + 跨项目落盘口径¶
- 日期：2026-10-11
- 交付目录：
Documents/services/token_proxy/remote-exec-20261011/ - 类型：C 类变更（改 hook 脚本、规则、skill 正文；新增共享库工具）
1. 背景¶
两件事在本次一并固化：
- 远端只读操作碎片化。Agent 执行任务时如需在远端取数，惯常做法是逐条
ssh：每条ssh是一个独立进程（新建连接 + 进程启动 + 一次往返），且跨RunCommand调用无法复用连接。共享库已有能力（连接池 + 主机间并发 + 每台一条 shell 一次往返），但缺一个「拿来就用」的统一入口，导致每遇到远端操作就现写脚本。 - 跨项目落盘混用。多次出现「当前工作目录是 A 项目，却改了 B 项目的文件，而交付物 / backup / SOP 落在 A 项目」，多项目内容混在一起。判定「这次操作属于哪个项目」是语义判断，但「写盘是否跨出当前工作区」可机检。
实测对照（2026-10-11，6 台主机同批只读探测）：逐条 ssh 5.472 s / 6 轮；走共享库入口 0.927 s / 1 轮（约 5.9 倍墙钟、6 倍轮次）。
2. 目标¶
- 远端只读操作有统一入口：
~/py_public_modules/remote_exec.py，可 CLI 用、可import用。 - 检测到
ssh直连时 Hook 提醒改用入口（判据 Z，每会话一次，不阻断）。 - 写盘跨出当前工作区时 Hook 提醒落盘归属（判据 Y，每会话一次，不阻断）。
- 「跨项目操作：谁被改、落谁家」写入全局规则；「远端只读走入口」写入
ops-execution-efficiencyskill 正文。
3. 前置条件¶
- 共享库
~/py_public_modules/就位，paramiko_module/base_module可用（任一挂了共享库的 venv 里有 paramiko 即可，脚本自带兜底探测）。 - 目标主机 SSH 可达、密钥认证可用（默认
root+ 空密码，即本机~/.ssh/id_*）。 - Hook 体系在运行（
~/.trae-cn/hooks.json已挂merge-guard）。 - 备份已完成，见第 7 章。
4. 影响范围¶
| 项 | 内容 |
|---|---|
| 主机 / 组件 | 本机；不改任何远端主机状态 |
| 被改对象 | token_proxy/merge-guard/merge-guard.py、~/.trae-cn/user_rules/rule-ops-evidence-constraints.md、~/.trae-cn/skills/ops-execution-efficiency/SKILL.md |
| 新增对象 | ~/py_public_modules/remote_exec.py（纯新增） |
| 是否停服 | 否 |
| 窗口期 | 无（hook 与规则改动同会话即生效） |
| 在跑业务 | 无影响；全部为只读工具与提醒级判据 |
5. 分步操作¶
步骤 1：新增共享库远端只读入口¶
新增 ~/py_public_modules/remote_exec.py。它复用 paramiko_module.connection_pool（进程内连接复用）与 base_module.BaseModule.probe_per_host（主机间并发 + 主机内拼一段 shell）。对任意解释器做依赖兜底：paramiko 缺失时从已挂共享库的 venv site-packages 补一条只读搜索路径。
ls -l ~/py_public_modules/remote_exec.py
python3 ~/py_public_modules/remote_exec.py --hosts 192.168.31.16,192.168.31.17 --cmd hostname
预期：每台一段 == <host> == 与 cmd=<主机名>，退出码 0。
失败判断：报 No module named 'paramiko' 且兜底也找不到时，改用任一挂了共享库的 venv 解释器（如 ~/Documents/slurm/slurm_ins/.venv/bin/python）。
步骤 2：merge-guard 增加判据 Z（ssh 直连提醒）¶
在 merge-guard.py 加常量 SSH_DIRECT_RE、提醒文案 PROMPTS["Z"]、状态位 z_fired，并在 main() 中判定：RunCommand 命令里出现「ssh 作为命令」（前有行首 / 分隔符 / sudo，后有空白）时提醒一次。正则比既有 SSH_RE 严，以免把 ssh-keygen 误判为直连。
echo '{"session_id":"ztest","tool_name":"RunCommand","tool_input":{"command":"ssh root@192.168.31.16 hostname"},"cwd":"/home/rain/Documents/slurm/slurm_ins"}' \
| python3 ~/Documents/services/token_proxy/merge-guard/merge-guard.py
预期：输出 JSON 的 additionalContext 含「远端入口提醒」。
失败判断：无输出或报错 → 第 7 章回滚后用 python3 -m py_compile 复核语法。
步骤 3：merge-guard 增加判据 Y（跨项目写盘提醒）¶
同文件加常量 WORKSPACE_EVENT_KEYS / CROSS_PROJECT_WHITELIST、辅助函数 _workspace_root / _is_cross_project_write、提醒文案 PROMPTS["Y"]、状态位 y_fired。判定：写类工具的目标绝对路径不在当前工作区子树、也不在公共资产白名单（~/py_public_modules、~/.trae-cn、/tmp、/var/tmp）时，提醒一次。工作区根取不到时不判定（避免误报）。
echo '{"session_id":"ytest","tool_name":"Write","tool_input":{"file_path":"/home/rain/Documents/services/token_proxy/a.md","content":"x"},"cwd":"/home/rain/Documents/slurm/slurm_ins"}' \
| python3 ~/Documents/services/token_proxy/merge-guard/merge-guard.py
预期：additionalContext 含「落盘归属提醒」。
失败判断：同步骤 2。
步骤 4：规则加跨项目落盘口径¶
在 ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md 的「交付物位置」节追加一段：跨项目操作时交付物落在被操作对象所属项目根下的专用子目录，不落在当前工作目录，backup/ 与 SOP.md 同此口径。
grep -n "跨项目操作" ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md
预期：命中一行「跨项目操作（当前工作目录是 A 项目，却要改 B 项目）…」。
步骤 5：skill 正文加远端入口约定¶
在 ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md 的 §2「往返与连接」追加一条：远端只读操作统一走共享库入口，给出判定（同一任务对 ≥2 台主机做同类探测、或对 1 台主机做 ≥2 项探测即应走入口）。只改正文，不改 description，避免 skill 索引重建。
grep -n "远端只读操作统一走共享库入口" ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md
预期：命中一行。
6. 验证¶
cd ~/Documents/services/token_proxy/remote-exec-20261011 && python3 verify_guard_yz.py; echo "RC=$?"
预期：6 条用例全 OK，RESULT=ALL_OK，RC=0。跑两遍结果须一致（verify_guard_yz.py 每条用例用独立 session_id，避开判据的去重标记）。
用例覆盖：判据 Z 正例（ssh host cmd）/ 反例（ls）/ 反例（ssh-keygen）；判据 Y 正例（跨项目写）/ 反例（同项目写）/ 反例（白名单内写）。
7. 回滚¶
备份存放位置：Documents/services/token_proxy/remote-exec-20261011/backup/，台账见该目录下 README.md。
B=~/Documents/services/token_proxy/remote-exec-20261011/backup
cp -p "$B/merge-guard/merge-guard.py.bak.20261011-221701" ~/Documents/services/token_proxy/merge-guard/merge-guard.py
cp -p "$B/trae-cn-user_rules/rule-ops-evidence-constraints.bak.20261011-221701" ~/.trae-cn/user_rules/rule-ops-evidence-constraints.md
cp -p "$B/trae-cn-skills-ops-execution-efficiency/SKILL.md.bak.20261011-221701" ~/.trae-cn/skills/ops-execution-efficiency/SKILL.md
rm -f ~/py_public_modules/remote_exec.py
回滚后验证：python3 -m py_compile ~/Documents/services/token_proxy/merge-guard/merge-guard.py 返回 0；重发步骤 2 / 3 的 echo | python3 命令应不再出现 Y / Z 提醒。hook 脚本与规则 / skill 正文回滚后同会话下一次调用即生效，无需重启 Trae。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 判据 Y 误报（正当的跨项目写盘） | 提醒级、不阻断；公共资产与工作区子树已白名单；每会话至多一次 |
判据 Z 误报（ssh-keygen 等） |
正则要求 ssh 作为命令出现，ssh-keygen 不匹配 |
| 工作区根取不到导致判据 Y 静默 | 取不到即不判定（宁漏不误） |
remote_exec.py 在无 paramiko 的解释器下失败 |
脚本自带兜底探测；仍失败时可改用挂了共享库的 venv 解释器 |
并发过高触发目标 sshd MaxStartups 拒绝 |
--max-workers 默认 8；连接被拒是正确性约束，不靠提高并发解决 |
共享库混用不同 venv 的 site-packages 有版本风险 |
兜底只在 paramiko 缺失时启用，且优先完整 venv 解释器 |
来源：
/home/rain/Documents/services/token_proxy/remote-exec-20261011/SOP.md｜ 最后更新：2026-10-11 22:19（由build/sync.py同步，请勿在站点侧修改）