SOP · agent 建连数接入与任务侧效率噪音清理

• 主题：remote-conn-count-20261011
• 日期：2026-10-11
• 类型：C 类变更（改共享库远端入口、计量脚本、常驻代理判定、skill 文案）
• 触发来源：用户指出「建连 / 精确可省重复仍不可机检」这句每轮固定输出已成噪音，且共享库远端入口本就有建连计数埋点，应当接入

1. 背景

cost_audit/wrapup.py 的「任务侧效率」块此前每轮固定输出一句 「（建连 / 精确可省重复仍不可机检：无 SSH 连接数埋点，cmd 只存首词）」。其中关于建连数的判断已过时：

• 建连埋点存在：~/py_public_modules/paramiko_module.py 的 SSHConnectionPool._connect_count，进程退出时打印「SSH连接池已关闭 | 本任务共新建连接 N 次」。
• agent 远端只读操作已统一走 ~/py_public_modules/remote_exec.py（2026-10-11 固化，配 merge-guard 判据 Z），它经同一连接池，天然具备该计数。

缺的不是埋点，是把该计数接到 wrapup.py 能读到的位置。按用户裁定：只动 agent 侧的共享库入口，不触碰任何工程部署器。

2. 目标

1. remote_exec.py 每次运行结束把 {ts, hosts, connect_count} 追加到 ~/.cache/agent_remote_conn.jsonl；
2. wrapup.py 的「任务侧效率」块按本轮时间窗汇总并显示「本轮经 remote_exec.py 共新建 SSH 连接 N 次」；取不到记录时不显示建连数，也不再打印旧占位句；
3. proxy.py 把 remote_exec 纳入远端识别，使该入口调用计入「远端步」并触发任务侧效率块；
4. 三处过时表述（wrapup.py 的 task_side_stats 注释、SKILL.md、wrapup-expand.md）同步修正。

3. 前置条件

• 操作机具备写 ~/.cache/ 与 token_proxy 工程目录的权限；
• remote_exec.py 可运行（依赖 paramiko，由共享库或任一工程 venv 提供）；
• 重启常驻代理用 systemctl --user restart token-proxy.service。该服务由 systemd user 管理；run.sh status 因 logs/proxy.pid 与 systemd 不同步会误报「未运行」，以 systemd 口径为准。

4. 影响范围

项	内容
主机	本机（无远端变更）
组件	共享库 paramiko_module.py、remote_exec.py；token_proxy 的 proxy.py、cost_audit/wrapup.py；skill ops-execution-efficiency 的 SKILL.md 与 references/wrapup-expand.md
停服	否。仅重启 token 计量代理（systemd user token-proxy.service）
窗口	无窗口要求
在跑业务	代理重启瞬间的请求会失败，实测无影响

5. 分步操作

步骤 1：共享库加只读计数接口

实现体：~/py_public_modules/paramiko_module.py（SSHConnectionPool.get_connect_count）。等价改动（紧跟 get_active_count 之后）：

# 在 SSHConnectionPool 内新增：
#     def get_connect_count(self) -> int:
#         """本进程累计新建的 SSH 连接数（诊断/统计用，不参与任何判定）。"""
#         return self._connect_count

注意事项与坑：_connect_count 是私有字段，直接取用破坏封装；补一个公开只读方法，供入口脚本与统计侧引用。

步骤 2：远端入口落盘建连数

实现体：~/py_public_modules/remote_exec.py（append_conn_log，在 main() 的 finally 内、connection_pool.shutdown() 之后调用）。等价改动：

# 新增模块级常量与函数：
# CONN_LOG_ENV = "AGENT_REMOTE_LOG"
# CONN_LOG_DEFAULT = os.path.expanduser("~/.cache/agent_remote_conn.jsonl")
# def append_conn_log(hosts, connect_count):
#     rec = {"ts": time.strftime("%Y-%m-%d %H:%M:%S"),
#            "hosts": len(hosts), "connect_count": int(connect_count)}
#     追加一行 JSON 到 _conn_log_path()；任何 OSError 静默
#
# main() 的 finally 内（重定向之外）：
#     append_conn_log(hosts, connection_pool.get_connect_count())

注意事项与坑：

• 落盘调用放在 contextlib.redirect_stdout(sys.stderr) 之外，避免污染 stdout 的 JSON 输出；
• 写失败必须静默（诊断数据，绝不因它改变命令退出码）；
• 路径经环境变量 AGENT_REMOTE_LOG 可覆盖，默认 ~/.cache/agent_remote_conn.jsonl，不硬编码到任何工程目录。

步骤 3：计量脚本读取并替换占位句

实现体：cost_audit/wrapup.py（新增 agent_remote_conns()，在「任务侧效率」块内调用）。等价改动：

# 新增 CONN_LOG_ENV / CONN_LOG_DEFAULT 与 agent_remote_conns(rows)：
#   - 按本轮时间窗（首请求 ts 至末请求 ts 加 600 秒缓冲）匹配 jsonl 记录
#   - 汇总 connect_count；无记录返回 None
# 「任务侧效率」块末：
#   conns = agent_remote_conns(cur)
#   if conns is not None:
#       print("（本轮经 `remote_exec.py` 共新建 SSH 连接 %d 次）" % conns)

注意事项与坑：时间窗末点加 600 秒缓冲，因入口运行时刻可能略晚于本轮最后一个请求的 ts。

步骤 4：代理纳入远端识别

实现体：proxy.py（REMOTE_HINTS）。等价改动：

# 原：REMOTE_HINTS = ("ssh", "scp", "rsync", "sftp")
# 改：REMOTE_HINTS = ("ssh", "scp", "rsync", "sftp", "remote_exec")

注意事项与坑：不改这里，python3 remote_exec.py ... 不被判为远端步，任务侧效率块不触发、建连数也就无从显示。本轮首次验证即撞到（remote=0）。

步骤 5：重启代理并同步文案

systemctl --user restart token-proxy.service
systemctl --user is-active token-proxy.service      # 预期 active

同步修正三处过时表述：cost_audit/wrapup.py 的 task_side_stats docstring、~/.trae-cn/skills/ops-execution-efficiency/SKILL.md（收尾自查清单节）、references/wrapup-expand.md（任务侧效率节与上限须知节），统一改为「建连数已可机检（入口落盘）、仅精确可省重复仍不可机检」。

6. 验证

# ① 语法
python3 -c "import ast,sys;[ast.parse(open(f,encoding='utf-8').read(),f) for f in sys.argv[1:]];print('SYNTAX_OK')" \
  ~/py_public_modules/paramiko_module.py ~/py_public_modules/remote_exec.py \
  "$HOME/Documents/services/token_proxy/cost_audit/wrapup.py"
# 预期：SYNTAX_OK

# ② 入口落盘
python3 ~/py_public_modules/remote_exec.py --hosts 192.168.31.16 --cmd hostname
tail -n 3 "$HOME/.cache/agent_remote_conn.jsonl"
# 预期：新增一行 {"ts": "...", "hosts": 1, "connect_count": 1}

# ③ 计量侧显示
cd "$HOME/Documents/services/token_proxy" && python3 cost_audit/wrapup.py
# 预期：出现「任务侧效率」块，末行为「（本轮经 `remote_exec.py` 共新建 SSH 连接 N 次）」；旧占位句消失

实测（2026-10-11）：

检查项	结果
语法	SYNTAX_OK
入口运行	rc=0，.16 返回 slurm-master-01
落盘	两遍各 1 行，connect_count 均 1
req_shape	含 remote_exec 的步 remote=1（改前为 0）
任务侧效率块	出现，远端步 1，末行「共新建 SSH 连接 2 次」，占位句消失

7. 回滚

备份位置：remote-conn-count-20261011/backup/，逐条见 backup/README.md。

cd /home/rain/Documents/services/token_proxy/remote-conn-count-20261011/backup
TS=20261011-235655
cp -p py_public_modules/paramiko_module.py.bak.$TS /home/rain/py_public_modules/paramiko_module.py
cp -p py_public_modules/remote_exec.py.bak.$TS      /home/rain/py_public_modules/remote_exec.py
cp -p proxy.py.bak.20261011-235904                  /home/rain/Documents/services/token_proxy/proxy.py
cp -p cost_audit/wrapup.py.bak.$TS                  /home/rain/Documents/services/token_proxy/cost_audit/wrapup.py
cp -p skills/ops-execution-efficiency/SKILL.md.bak.$TS \
      /home/rain/.trae-cn/skills/ops-execution-efficiency/SKILL.md
cp -p skills/ops-execution-efficiency/references/wrapup-expand.md.bak.$TS \
      /home/rain/.trae-cn/skills/ops-execution-efficiency/references/wrapup-expand.md
systemctl --user restart token-proxy.service
rm -f "$HOME/.cache/agent_remote_conn.jsonl"     # 可选：清理落盘记录

回滚后验证：wrapup.py 恢复输出旧占位句；req_shape 新记录不再把 remote_exec 计入远端。

8. 风险说明

风险	说明与缓解
代理重启瞬间请求失败	重启为秒级；实测无影响。规则允许直接重启常驻服务
落盘 jsonl 无限增长	每行约 60 B，且仅在 agent 走远端入口时写入；如需可后续加轮转
时间窗漏计或多计	首请求至末请求加 600 秒缓冲；每次入口调用即新进程，不涉及跨轮复用
_connect_count 语义变化	新增方法只读，不改计数逻辑；其「不参与任何判定」的既有约定未动

附录：交付物清单

文件	角色
本文件	变更档案
backup/	6 个被改文件的原件快照，台账见 backup/README.md
被改实现体	见第 4 章组件列

---

来源：/home/rain/Documents/services/token_proxy/remote-conn-count-20261011/SOP.md ｜ 最后更新：2026-10-12 00:00（由 build/sync.py 同步，请勿在站点侧修改）