mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-26 01:01:40 +00:00
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
---
|
||
title: Codex Bridge 异步任务需要持久化完成通知状态
|
||
date: 2026-04-25
|
||
category: docs/solutions/developer-experience/
|
||
module: Codex Bridge
|
||
problem_type: developer_experience
|
||
component: assistant
|
||
severity: medium
|
||
applies_when:
|
||
- 异步 agent 任务由本地 bridge 启动，但完成结果需要回到原平台会话
|
||
- 任务状态已经持久化，但缺少完成后主动送达能力
|
||
- 测试不能向真实外部平台发送消息
|
||
tags: [codex-bridge, async-notification, app-server, send-message, watcher]
|
||
---
|
||
|
||
# Codex Bridge 异步任务需要持久化完成通知状态
|
||
|
||
## Context
|
||
|
||
Codex Bridge 已经通过 app-server stdio 启动 Codex 任务，并把状态写入 `codex_bridge.db`。dogfood 暴露出的体验问题是：异步任务完成后没有主动通知原 Feishu/平台会话，用户必须再次触发 Hermes 查询 `status` 或 `list` 才能知道结果。
|
||
|
||
这类问题不需要先做多租户调度系统。MVP 的关键是让任务在启动时可选记录通知目标，并让一个 one-shot watcher 可以可靠地处理 terminal 任务。
|
||
|
||
## Guidance
|
||
|
||
在已有任务表上补齐三个概念，而不是重写底层通信协议：
|
||
|
||
- `notify_target`：启动时可选记录目标，例如 `local` 或 `feishu:<chat_id>`。
|
||
- `notification_status`：记录通知生命周期，例如 `pending`、`sent`、`failed`、`no_target`。
|
||
- `notified_at` / `notification_error`：让 watcher 重启后能防重复，并保留失败原因。
|
||
|
||
watcher 应该只扫描 terminal 状态任务，并做幂等处理：
|
||
|
||
- 有目标：构造简洁完成摘要，调用可注入 notifier，成功后标记 `sent`。
|
||
- 无目标：标记 `no_target`，不发送，避免每次扫描重复捞到同一任务。
|
||
- dry-run：返回预览，不发送，也不写通知状态。
|
||
|
||
默认 notifier 可以复用现有 `send_message` 能力，但核心 manager 方法要允许注入 notifier。这样单元测试可以用 fake notifier 验证行为，避免真实平台副作用。
|
||
|
||
## Why This Matters
|
||
|
||
异步 bridge 的产品承诺不是“能启动后台任务”，而是“任务结束后用户能在原上下文看到结果”。如果只有状态表但没有通知状态，系统会卡在“完成但无人查收”的灰区；如果没有持久化防重复，watcher 或 daemon 重启又可能重复推送。
|
||
|
||
把通知状态做成任务元数据，可以在不引入 mailbox/outbox/inbox 通信机制的情况下满足 MVP，并为后续实时 approval / `requestUserInput` 扩展留下同一套 target 语义。
|
||
|
||
## When to Apply
|
||
|
||
- 异步任务生命周期已经持久化，但完成后需要跨平台送达。
|
||
- 现有平台发送能力已经存在，新增功能只需要选择目标和调用发送。
|
||
- 需要保证测试环境不触发真实外部消息。
|
||
- 需要 watcher/daemon 重启后不重复通知。
|
||
|
||
## Examples
|
||
|
||
启动时记录目标：
|
||
|
||
```python
|
||
codex_bridge(
|
||
action="start",
|
||
prompt="Investigate the failing tests",
|
||
notify_target="feishu:chat-1",
|
||
)
|
||
```
|
||
|
||
one-shot watcher dry-run：
|
||
|
||
```bash
|
||
python skills/codex-bridge/references/cli.py notify-completed --dry-run
|
||
```
|
||
|
||
测试中注入 notifier：
|
||
|
||
```python
|
||
deliveries = []
|
||
manager.notify_completed(
|
||
notifier=lambda target, message: deliveries.append((target, message)) or {"ok": True}
|
||
)
|
||
```
|
||
|
||
## Related
|
||
|
||
- `docs/brainstorms/2026-04-25-codex-bridge-completion-notification-requirements.md`
|
||
- `docs/plans/2026-04-25-codex-bridge-completion-notification-plan.md`
|
||
- `tools/codex_bridge_tool.py`
|
||
- `skills/codex-bridge/references/cli.py`
|