---
name: v4.5.41-hook-module-over-inline-preference
description: "用户明确偏好: gateway/run.py 等核心文件不要加塞业务逻辑, hook 必须放在 skill 目录下作为独立模块"
version: 1.0.0
type: reference
---

# v4.5.41 (2026-07-30) Hook 放 skill 模块, 不要内联到 gateway/run.py

## 用户原话

> "不要在 run 里改，把文件加到对应的skill下"

## 上下文

v4.5.40 我把 signal_inbox hook 代码 **inline** 到 `gateway/run.py:10617-10674` (~58 行)。修完用户立刻纠正。

## 用户偏好的本质

| 偏好 | 含义 |
|------|------|
| **run.py 不加塞业务逻辑** | gateway 是 hermes-agent 核心, 修改要 git commit 到主仓库 (`~/.hermes/hermes-agent`), 不是 `~/.hermes/skills/`。频繁动核心文件 = 频繁 commit 上游 = 易冲突 |
| **hook 放 skill 目录** | skill 目录是用户的私人扩展空间 (`~/.hermes/skills/<skill>/`), git 在 `~/.hermes/skills/trading`, 修改不影响上游 |
| **会丢就 commit** | 用户原话 "现在要把文件加到 git 里, 不会丢" → skill 脚本靠 git track 防丢, 不靠 inline 防御 |

## 这跟 v4.5.40 cleanup-defense 矛盾

v4.5.40 的 inline 方案就是**因为** signal_inbox.py 被 cleanup 删了 → 用 inline 防止再被删。用户最新偏好说：

| 选项 | v4.5.40 观点 | v4.5.41 用户偏好 |
|------|-------------|------------------|
| Inline 到 run.py | ✅ 防 cleanup 删除 | ❌ 不动核心文件 |
| 放 skill 目录 + git track | ❌ 会被 cleanup 删 | ✅ 不会丢 + 不动核心 |

**最终方案 (v4.5.41)** = 放 skill 目录 + 立即 git commit。cleanup 删了 `git checkout` 就能恢复, 不需要 inline 防御。

## 当前代码 (v4.5.41 已部署)

### gateway/run.py hook (12 行, 只做 import + try/except)

```python
# ── [Hermes Hook] 信号自动入队 (v4.5.4) ────────────────────────
# 调 signal_inbox.enqueue_if_signal (位于 okx-auto-position/scripts/)
# 实现逻辑全部在模块里, 这里只做 import + try/except
try:
    import importlib
    import sys as _sys_hook
    _sig_skill = os.path.expanduser(
        "~/.hermes/skills/trading/okx-auto-position/scripts"
    )
    if _sig_skill not in _sys_hook.path:
        _sys_hook.path.insert(0, _sig_skill)
    _sig_mod = importlib.import_module('signal_inbox')
    await _sig_mod.enqueue_if_signal(source, event.text or "")
except Exception as _hook_err:
    logger.warning(f"[signal_inbox] hook 异常 (不致命): {_hook_err}")
```

### skill 模块

**路径**: `~/.hermes/skills/trading/okx-auto-position/scripts/signal_inbox.py`

**git**: `commit b91f677 v4.5.4: signal_inbox.py hook helper for gateway`

## 防御策略调整

| 风险 | v4.5.40 防御 | v4.5.41 防御 |
|------|-------------|-------------|
| 文件被 cleanup 删 | Inline 到 run.py | `git checkout okx-auto-position/scripts/signal_inbox.py` 恢复 |
| run.py hook 失败 | (无) | 已知 try/except, hook 静默也不致命 (signal-queue-retry cron 兜底) |
| hook 不工作 | 看 inline 代码 | `git log --all --oneline -- signal_inbox.py` 找 commit + checkout |
| 改坏 core 文件 | (无) | 用户偏好禁止; 改坏就 `git checkout gateway/run.py` |

## 给下次 session 的指令

**用户偏好优先级** (这次的明令):
1. **改 hook / 业务逻辑 → 放 skill 目录** (`~/.hermes/skills/<skill>/scripts/`)
2. **不要 inline 到 gateway/run.py 等核心文件**
3. **新文件立即 `git add` + commit**, 防 cleanup 删除
4. **inline 是最后手段**, 仅在用户明确授权 + 无 skill 模块路径时

**违反这条偏好 = 用户会立即反驳**。如不确定, 先问用户"放 skill 还是改 core"。