99 lines
11 KiB
Markdown
99 lines
11 KiB
Markdown
# ASR 管线 × Agent 耦合点 Review
|
||
|
||
**日期**：2026-09-18
|
||
**背景**：Hermes 网关从 .145 迁移到 .48 后，`meeting-status-notify.py` 因硬编码 `127.0.0.1:8644` 而 Telegram 通知失效（核心转录/整理流程本身不受影响）。这次故障暴露的不是孤立 bug，而是整条管线里 Claude/Hermes 两个 agent 以"硬编码地址/私有配置文件/直接 shell out"方式接入，缺乏稳定接口层。本文档目标：**列出所有耦合点，诊断问题，提出"预留接口 + 通用 skill"的解耦方案**，供下一轮重构使用。不在本文档内直接修改代码。
|
||
|
||
---
|
||
|
||
## 1. 涉及文件清单
|
||
|
||
### 1.1 生产代码（按耦合程度分类）
|
||
|
||
| 文件 | 耦合对象 | 耦合方式 | 严重度 |
|
||
|---|---|---|---|
|
||
| `OBSIDIAN/bin/meeting-status-notify.py` | Hermes | 硬编码 `http://127.0.0.1:8644/webhooks/...`；直接读 `~/.hermes/webhook_subscriptions.json` 取 HMAC secret | 🔴 高（本次故障根源） |
|
||
| `OBSIDIAN/recordings/bin/meeting-watch.py` | Hermes | `post_webhook()`/`post_status()` **重新实现**了一遍同样的 HMAC 签名 + 硬编码 URL 逻辑（与上面文件重复代码，两处维护） | 🔴 高（重复实现同一故障点） |
|
||
| `OBSIDIAN/asr-pipeline/asrpipe/vault.py` (`notify()`) | Hermes（间接） | 不直接硬编码地址，但通过 `CFG.notifier` 固定 `subprocess.run(["python3", meeting-status-notify.py, ...])`，位置参数契约无 schema | 🟡 中（依赖上面两个文件之一才能工作） |
|
||
| `OBSIDIAN/asr-pipeline/asrpipe/config.py` (`review_public_host`) | 部署环境 | 默认值硬编码 `192.168.50.145`（本机 IP），可用 env 覆盖 | 🟢 低（有 env 覆盖，且 review-web 确实还在 .145，不是错误，只是"写死默认值"的一贯风格问题） |
|
||
| `OBSIDIAN/bin/obsidian-asr-refine.sh`（**已停用**，仅供 rollback） | Claude Code | 直接 shell out `$HOME/.local/bin/claude -p`，依赖交互登录态 | 🟡 中（非活跃路径，但 rollback 会重新引入该耦合） |
|
||
| `OBSIDIAN/bin/obsidian-asr-hotwords.py`、`OBSIDIAN/bin/obsidian-asr-intake.sh` | 无（命名遗留） | 调用 `~/bin/hermes-qwen3-asr-smart`——**这是个纯 STT wrapper shell 脚本，跟 Hermes agent 运行时完全无关**，只是历史命名带 "hermes" 前缀，容易被误读为依赖 agent | 🟢 低（认知负担，不是真耦合，建议重命名去混淆） |
|
||
| `~/.config/systemd/user/obsidian-recording-watch.service` | Hermes | `Environment=MEETING_WEBHOOK_URL=http://127.0.0.1:8644/...` 在 systemd 层再硬编码一次 | 🔴 高（第三处需要同步修改的地方） |
|
||
| `asr-pipeline/asrpipe/llm.py` | Claude（仅模型选择） | 字符串形式引用 `anthropic/claude-sonnet-5` 等模型名做定价/no-temperature 判断 | 🟢 低（纯 API 层配置，非 agent 运行时耦合，正常） |
|
||
| `asr-pipeline/asrpipe/cli.py`、`config.py` 文件头注释 | 无 | 明确声明"no Claude Code, no opencode, no agent runtime"——这是**架构上已经做对的部分**，核心管线是纯 HTTPS+文件驱动，值得保留和强化 | 🟢 无耦合（正面案例） |
|
||
|
||
### 1.2 文档/Skill 层（描述与现状不一致，需要一并清理）
|
||
|
||
| 文件 | 问题 |
|
||
|---|---|
|
||
| `~/.claude/skills/memo-inbox/references/webhook-toolset-diagnostics.md` | 描述的是**已被取代的旧架构**：假设有一个"webhook agent"（Hermes）直接处理 `meeting-recording` 路由、需要 `hermes-webhook`/`file`/`skills` toolset、把转录内容发给 Hermes agent 做 memo-inbox 整理。但 `CLAUDE.md` 明确写着"已**取代**旧的 Hermes→Telegram agent 精修"，且 `meeting-watch.py` 里 `post_webhook()`（对应 `meeting-recording` 路由，携带正文）从未被实际调用，只有 `post_status()`（状态 ping）在用。**这份 skill 文档描述的故障排查对象已经不存在，但仍在 memo-inbox skill 里被索引，可能误导下一次排障。** |
|
||
| `~/.claude/skills/memo-inbox/references/asr-refine-pipeline.md` | 与 `CLAUDE.md`、`HANDOFF.md` 三份文档描述同一条管线，各有侧重但存在信息重复（例如五阶段说明在两份文档里几乎逐字重复）。不是错误，但增加了"改一处忘改另一处"的维护成本——这次 8644 端口就是同一类问题在配置层面的重演。 |
|
||
| `OBSIDIAN/asr-pipeline/HANDOFF.md` | 明确写了"Telegram 通知（hermes-gateway :8644 签名 webhook）"，是**当前唯一还把 Hermes 网关端口写进设计文档**的地方，本身没错但需要随实现一起更新。 |
|
||
| 目前**不存在** `agent-protocol.md`（据 hindsight 记忆，2026-07-17 曾规划把 obsidian skill 拆分出一份 Hermes/Codex/Claude Code 共用的 `agent-protocol.md`，统一七步协议） | 说明"通用协议文档"这个方向此前已经被认可过，但从未真正落地到 ASR 通知这一层，这次故障正好是没有该抽象层的直接后果。 |
|
||
|
||
---
|
||
|
||
## 2. 问题诊断
|
||
|
||
### 2.1 核心问题：通知通道是唯一的"横切关注点"，却用点对点硬编码实现
|
||
|
||
真正跨 Claude/Hermes 边界的交互只有一件事：**管线要把"状态变化"告诉人（Kai），而人在 Telegram 上**。当前实现把这件事等同于"调用 Hermes 网关在某个 IP:port 上开的私有 webhook"，导致：
|
||
|
||
- 通知目标地址在**三个物理位置**各写一份（`meeting-status-notify.py`、`meeting-watch.py`、systemd unit 的 `Environment=`），Hermes 一换主机全部失效，还都要单独改。
|
||
- 认证方式依赖读取 **Hermes 自己的私有配置文件** `~/.hermes/webhook_subscriptions.json`，管线对 Hermes 的内部文件结构做了假设——Hermes 的实现细节变了，管线也会跟着坏，而管线本身的 git 仓库里完全看不出这个依赖关系。
|
||
- `meeting-watch.py` 里的 `post_webhook`/`post_status` 和 `meeting-status-notify.py` 是**同一逻辑的两份实现**（都做 HMAC 签名 + POST），维护者容易改一处忘改另一处。
|
||
|
||
### 2.2 次要问题：文档层的"多真相源"
|
||
|
||
`CLAUDE.md`（基础设施说明）、`HANDOFF.md`（设计交接）、`asr-refine-pipeline.md`（skill 引用）三份文档对同一条管线各写一遍架构图和五阶段表格，`webhook-toolset-diagnostics.md` 甚至在描述一个已经退役的架构分支。这不是本次故障的直接原因，但预示着**如果解耦时只改代码不改文档索引，同样的"多处不同步"问题会在文档层重演**。
|
||
|
||
### 2.3 正面案例，值得保留的设计
|
||
|
||
- `asrpipe/` 核心包（S0-S4 五阶段 + fidelity gate + termbank）本身**已经是纯 HTTPS + 文件驱动**，不依赖任何 agent CLI 或登录态，`cli.py`/`config.py` 头部注释明确声明了这个边界——这是解耦该学的样子。
|
||
- `asr-review-web`/`control_web.py` 是一个独立 HTTP 服务，路由/状态机/上传都通过标准 HTTP 暴露，没有假设调用方是谁——**这个"HTTP 接口面"是天然可以承载 Claude/Hermes 通用交互的地方**，不需要另起炉灶。
|
||
|
||
---
|
||
|
||
## 3. 解耦方案建议（预留接口 + 通用 skill）
|
||
|
||
### 3.1 接口层：把"通知"做成可插拔的抽象，而不是"调用 Hermes"
|
||
|
||
建议参考 `config.py` 里其余配置项的风格（`use_termbank`/`use_hindsight` 等 boolean 开关 + env 覆盖），把通知也做成同一等级的可插拔能力：
|
||
|
||
- 在 `asrpipe/config.py` 增加 `notify_backend`（如 `webhook` / `none` / 未来的 `stdout`/`file` 等），而不是隐式认定"notifier = 某个写死路径的 python 脚本"。
|
||
- `meeting-status-notify.py` 改造成**唯一**的通知发送实现（`meeting-watch.py` 不再自己重新实现 HMAC 签名，改为 shell out 到同一份脚本，或提取成共享库函数），并且：
|
||
- 目标地址、密钥来源全部走 env / 独立配置文件（例如 `OBSIDIAN/bin/notify-target.json`），**不直接读 `~/.hermes/*`**——管线自己的配置与 Hermes 的私有配置解耦，Hermes 换主机/换协议时只改这一份 target 配置，不改代码。
|
||
- 把"目标是 Hermes 网关的 webhook"这件事，退化为该抽象接口的**一种实现**，而不是唯一实现——未来即使 Hermes 换成完全不同的通知方式（比如直接调 Telegram Bot API），也只是换一个 backend，管线代码不用动。
|
||
|
||
### 3.2 协议层：让 Claude 和 Hermes 通过同一份"通用 skill/协议文档"交互，而不是各自看各的私有细节
|
||
|
||
现状是 Hermes 一侧靠私有 webhook 配置、Claude 一侧靠读 `CLAUDE.md`/`HANDOFF.md`，两边对同一条管线的认知来自不同文档，容易出现你这次遇到的情况——迁移动作只在 Hermes 侧发生，ASR 侧的假设没人同步更新。
|
||
|
||
建议：
|
||
|
||
1. **落地此前已经规划过的 `agent-protocol.md`**（hindsight 记忆里 2026-07-17 就提出过这个方向，但目前尚未创建）。把"任何 agent（Hermes/Claude Code/Codex）如何得知 ASR 管线的状态变化、如何触发人工确认、通知目标怎么配置"写成一份三方共用的协议文档，而不是分散在 `CLAUDE.md` + `HANDOFF.md` + memo-inbox skill 引用里各写一份。
|
||
2. 把 `control_web.py` 已有的 HTTP 接口面正式定义为**唯一**对外交互入口：任何 agent 需要查询任务状态/触发处理，都走这个 HTTP API，而不是直接读 sqlite（`intake.db`）或直接改文件。目前 `meeting-watch.py` 直接读写 `CONTROL_DB`（sqlite），这本身也是一种"绕过接口层直连内部状态"的耦合，建议后续统一收敛到 `control_web.py` 的 API 之后。
|
||
3. 清理 `webhook-toolset-diagnostics.md`：要么标注为"历史架构，已废弃于 2026-07-25"，要么直接删除/归档，避免下次排障时被过时描述误导。
|
||
4. `CLAUDE.md` / `HANDOFF.md` / `asr-refine-pipeline.md` 三份重叠内容建议收敛为"一份权威来源 + 其余引用链接"的结构（类似 vault 侧 `AGENTS.md` 作为 SOP 索引、具体细则各自一份的模式），而不是三份都写一遍五阶段表格。
|
||
|
||
### 3.3 命名去混淆
|
||
|
||
`~/bin/hermes-qwen3-asr-smart` 建议评估是否重命名（例如 `qwen3-asr-transcribe-wrapper`）——它不依赖 Hermes agent 运行时，纯粹是历史命名，留着容易让人（或下一轮重构的 LLM）误判为真实耦合点而做无用功。
|
||
|
||
---
|
||
|
||
## 4. 优先级建议
|
||
|
||
| 优先级 | 事项 | 原因 |
|
||
|---|---|---|
|
||
| P0 | 通知 backend 抽象化 + 三处硬编码收敛为一处配置 | 直接对应本次故障，且是唯一真正跨 agent 边界的运行时依赖 |
|
||
| P1 | 落地 `agent-protocol.md`，清理 `webhook-toolset-diagnostics.md` 等过时文档 | 防止"文档多真相源"重演同类故障 |
|
||
| P2 | `meeting-watch.py` 收敛直连 sqlite 为走 `control_web.py` API | 减少内部状态的多点直连，但当前未造成故障，可延后 |
|
||
| P3 | `hermes-qwen3-asr-smart` 重命名 | 纯认知成本，无功能风险，可随手做 |
|
||
|
||
---
|
||
|
||
## 5. 明确不建议做的事
|
||
|
||
- 不建议把核心 `asrpipe/` 五阶段管线本身引入任何 agent 依赖——它当前"纯 HTTPS + 文件驱动"的设计是对的，解耦应该聚焦在通知/协议这一层，不要往核心管线里加 Claude/Hermes 相关代码。
|
||
- 不建议为了解耦而过度设计一套通用消息总线/插件系统——当前只有"一个通知需求 + 一个 HTTP 状态查询需求"，用简单的 backend 开关 + 现有 HTTP 接口面就够，避免过度工程化。
|