# auto_notify_new_file.sh 架构：入队模式 vs 直接执行模式

## 根因（2026-06-30）

`auto_notify_new_file.sh` 原本自己启动 `uwf thread exec -c 5`（前台模式）来执行合同审查 workflow。
但 hermes ACP 适配器在前台模式下有 asyncio stdin 注册 bug（`KeyError: '0 is not registered'`），
导致每次 spawn `hermes acp` 子进程都立即失败，日志中全是 `agent command failed (uwf-hermes)`。

**对比**：`contract-queue-runner.sh` 使用 `uwf thread exec --background` 模式，正常工作。

## 当前架构（2026-06-30 修复后）

```
企微收到文件
  → auto_notify_new_file.sh (inotifywait 监控)
    → 识别 sender (邱律师=QiuTing)
    → 上传 Nextcloud 待审查/
    → 入队 /tmp/contract-queue/manifest.txt
    → 检查 contract-queue-runner.sh 是否在运行，不在则启动
      → contract-queue-runner.sh 串行执行（--background 模式）
        → uwf thread start + thread exec --background
        → uwf-hermes → hermes acp（正常）
```

## 关键文件

| 文件 | 路径 | 职责 |
|------|------|------|
| auto_notify | `~/.hermes/scripts/auto_notify_new_file.sh` | 监控文件到达、上传、入队 |
| queue runner | `~/.hermes/skills/devops/uwf/scripts/contract-queue-runner.sh` | 串行执行 workflow |
| watchdog | `~/.hermes/scripts/contract-queue-watchdog.sh` | 每20分钟检查卡住的 thread |
| auto_notify watchdog | `~/.hermes/scripts/auto_notify_watchdog.sh` | 每5分钟检查 auto_notify 进程 |

## 禁止回退

**绝不可把 auto_notify 改回自己启动 `uwf thread exec` 的模式**。前台模式有 ACP stdin bug，
只有 `--background` 模式能正常工作。如果未来需要修改 auto_notify 的 workflow 启动逻辑，
必须通过 contract-queue-runner 间接执行。

## 入队逻辑

```bash
# 入队到 contract-queue
cp "$filepath" "$QUEUE_DIR/${orig_name}"

# 追加到 manifest（去重）
if ! grep -qFx "$orig_name" "$QUEUE_DIR/manifest.txt" 2>/dev/null; then
    echo "$orig_name" >> "$QUEUE_DIR/manifest.txt"
fi

# 检查 queue runner 是否在运行，不在则启动
if ! ps aux | grep -q "[c]ontract-queue-runner"; then
    nohup bash "$HOME/.hermes/skills/devops/uwf/scripts/contract-queue-runner.sh" >> "$QUEUE_DIR/queue.log" 2>&1 &
fi
```