主题
五、跨模块关键链路
本章速览:单个模块看完了,真正容易出事的是跨模块的链。下面 9 条链路覆盖了系统的"动态部分",每条都给出入口、关键机制、失败降级与代码锚点。
| 链路 | 起点 | 关键机制 | 失败 / 降级 | 详见 |
|---|---|---|---|---|
| 主动消息 | 扩展触发器 | 选材 → DSH 润色 → deliver.message → 通知降级 | 润色失败用模板;预算/静默跳过带理由 | §5.1 |
| 提醒 | 扩展(每分钟) | dedup_key 幂等 + 预润色缓存 + 准点判据 | 缓存不可用发模板;超补投窗口标 skipped | §5.2 |
| 每日总结 | DailyDigestJob | 时间点轮询 + 行级 claim + 异步生成 | 无输入记 ignored、失败冷却重试、可人工重生成 | §5.3 |
| 记忆 | MCP / 扩展 | Hindsight 幂等写入 + 检索校准 + 出网台账 | 写失败如实回报,不假称记住 | §5.4 |
| 微信对话 | 桥长轮询 | 去抖 → DSH 会话 → 分片回发 | 30s 先回"还在做";发送失败入待送队列 | §5.5 |
| 后台 AI 对话 | 后台页面 | 桥 /admin-chat → pending Job 取回 | 超时转 pending;附件物化失败回滚 | §5.6 |
| 会话采集 | 宿主 cron | RAW 先落库 → 解析 → 服务端水位 | 解析失败保留 RAW;失败不推进水位 | §5.7 |
| 发布事件 | 后台"发布" | AFTER_COMMIT 监听订阅 / AI / 记忆 | AI 与订阅失败不影响已发布 | §5.8 |
| 通知重试 | 业务 / 扩展 | 幂等抢占 → 降级链 → 重试回写业务 | 站内兜底不掩盖外部失败 | §5.9 |
单个模块看完了,真正容易出事的是"跨模块的链":谁选材、谁润色、谁投递、失败怎么降级、 怎么保证不重复。这一章按一次完整业务动作把模块串起来,给出时序与代码入口。
5.1 主动消息:从"该说话了"到"微信收到"
主动消息(晨报/晚报/关怀/周复盘/访谈邀请/线头提起)是同一个骨架,差异只在 handler:
触发器(extension trigger,UTC 调度)
│ ExtensionRunService.execute
▼
策略:全局开关/安装 active/静默时段/月预算/花费/每小时上限/主动日限额 ← ExtensionPolicyService
│ allowed
▼
builtin handler(如 BriefBuiltinHandler)
│ ① 读开关(site.ai.proactive.enabled)
│ ② 选材:日程 + 记忆检索 + 线头 + 关系视角 + 上次反馈 (只读,不产生副作用)
│ ③ 读预算/去重:proactive_log 里同 dedup_key 已发过 → skip
│ ④ compose:DSH 润色(compose.resolve)或模板兜底
│ ⑤ 产出 deliver.message effect
▼
ExtensionEffect(幂等键 = installation:trigger:identity:capability:seq)
│ EffectApplier
▼
MessageCenterService → extension_message / delivery
│
▼
NotifyService:按 priority 选通道 → 微信(桥 /notify)→ 邮件 → 站内
│ 成功写 notify_log(sent);失败 failed → NotifyRetryJob(retry<2)
▼
微信桥:24h 去重 → 分片(长文)→ 发送(重试 3 次)→ 失败入待送队列设计要点(每条都能在代码里找到对应):
- 润色不是必需:
ProactiveComposeService同步调桥/compose,超时/失败/守卫不过就原样返回模板; 润色层挂了消息也不会丢(设计哲学第 6 条)。 - 预算与静默:日限额读
site.ai.proactive.daily-limit;静默时段site.notify.quiet-hours; 提醒管道豁免静默与主动预算(用户自己排的确定性事务不能被闲聊预算挤掉)。 - 去重:
proactive_log.dedup_key幂等;同一场景同一天只发一次。 - 反馈闭环:
system.feedback.judge读用户对主动消息的反馈(有用/无用),回写proactive_log,影响后续选材与预算判断。 - 可观测:run 事件、策略判定现场、消息投递、notify_log、桥日志五层都能查"为什么发了/为什么没发"。
5.2 提醒:必须准点的那条链路
提醒与其它主动消息的最大区别是:到点必须发,润色只能加分不能拖后腿。
DailyTodoService/DailyCourseService 变更 ──> DailyReminderService.planDue(每分钟,幂等)
│ dedup_key 唯一
▼
daily_reminder(status=pending, remind_at)
│
┌────────────────────────────────────┴─────────────────────┐
│ 到点前 lead 分钟(3–30,默认10) │ 到点
▼ ▼
ProactiveComposeCacheService.prefetch system.reminder handler
compose.prefetch → DSH 润色 → proactive_compose(ready) reminder.pending.read
失败:failed 行 + 3 分钟短 TTL(期间直接回退模板) compose.cached 命中则用润色文案
│ │
└──────────────────────┬───────────────────────────┘
▼
deliver.message → 通知链(微信/邮件/站内)
▼
daily_reminder.status = sent / failed / skipped准点判据(审查 #69 的结论):
| 类型 | 规则 | 理由 |
|---|---|---|
course/custom(时间锚点) | 绝不提前,到点后第一个调度 tick 发(最多晚 30s) | 文案写着"现在开始",提前发等于说错话 |
| 待办类 | 最多提前 30 秒(=调度器粒度) | 避免因轮询延迟变成晚到 |
失败/超时:缓存不可用发模板;投递失败进 retry;超过补投窗口(默认 120 分钟)的提醒标 skipped, 避免重启后轰炸过期提醒。
5.3 每日总结(日记):一次"可控的长 AI 任务"
DailyDigestJob(每 60s 轮询,读 site.ai.digest.time,默认 00:20)
│ 到点且 ai_daily_digest(date) 不存在
▼
异步 aiExecutor(不占调度线程)
│
├─ 行级 claim:processing(并发/重复触发只有一条能生成)
├─ 组装输入:当天对话轮次 + 待办完成 + 说说 + 课程 + 生活事件
│ (备注等私密字段不进提示词;Hindsight 背景可选)
├─ 调模型(超时 180s)→ summary_md / diary_md
├─ 写 ai_daily_digest:
│ note_only(只写日记)或 draft(同时建文章草稿,可配)
├─ 无输入 → ignored(不调模型,止住每分钟重试)
└─ 异常 → failed(记录 error;10 分钟冷却后再试)- 幂等:
date唯一 +processing抢占;重复任务/重启补跑不会生成两份。 - 补偿:还没到今天时间点、且"昨天"完全没记录 → 补跑昨天(只补缺失,不重试失败)。
- 人工通道:后台可查看/编辑日记(版本历史),可重新生成或回填最近 7 天; 生成的文章只是草稿,发布仍由人决定。
- 可观测:每次运行写 job log;状态与错误在后台"每日总结"页可见。
5.4 记忆:写入、召回、遗忘的三条路
写入:MCP memory_write / 扩展 capability / 后台
→ MemoryWriteService 校验(text/隐私/去重键/置信度)
→ MemoryFacade.write → Hindsight(document_id 幂等;异步 operation 由 Job 确认)
→ 回读校验 → 三态回执(created / dedupe-hit / pendingReview)
召回:MCP memory_search / daily_brief / 关怀选材
→ MemorySearchService:语义 query → Hindsight recall(读重试 2 次)
→ 词面重排(LexicalReranker)→ 置信校准(contractScore)
→ 过滤 private / valid_until 过期
→ EgressLedger 记"交付给模型的内容"(级别条数/字节)→ 返回 why/sourceRef
遗忘:MCP memory_forget / 后台
→ soft(失效可回溯)或 hard(物理删除 + 向量清理)
→ 幂等;孤儿向量由 OrphanVectorSweepJob 每周兜底关键取舍:语义记忆在 Hindsight,结构化事件在 MySQL;MySQL 不维护"记忆镜像", 避免双写漂移。事件聚合查询(跑了多少公里/睡了几小时)走 MySQL SQL,不让模型自己算。
5.5 微信对话:一条消息的旅程
微信服务器 ──长轮询──> bridge.mjs cmdRun
│ ① 去抖 debounce(图+文字合并成一条,默认短窗口)
│ ② 解析引用/文本/媒体:媒体下载 → 私有目录 → 上传到博客附件(owner=agent_session)
│ ③ 刷新 instructions(/api/agent/instructions.md)+ 取回 sessionId
│ ④ 调 dsh(--session-id 续会话;超时默认 420s,分两段:30s 先回"还在做")
│ ⑤ 输出解析:只取正文;空正文重试一次;超时/错误分类记录
└─> 回发微信(长文分片;失败重试 3 次;仍失败入待送队列,下一条消息时补发)会话连续性:一个微信用户 ↔ 一个 DSH 会话(sessions.json);首轮从事件流取回 sessionId, 之后每轮续上。会话体积达到 600KB 自动换新会话(rotateDecision,换会话前提示可选), 避免单会话无限膨胀。空闲 7 天的 DSH 会话会被清理(保留最近一条)。
上下文一致性:桥每次回复前会"补上主动消息上下文"——如果几分钟前刚推过一条主动消息, 把它写进本轮提示,避免模型答非所问(例:博主回"听力听完了"是在回答提醒)。
失败形态:DSH 超时/错误 → 分类记录(reply-outcome),不静默;微信发送失败 (ret=-2 prepare failed 常见于 context_token 过期)→ 重试 → 待送队列;恢复方式: 用微信给 bot 发一句话刷新 token(无需重新扫码)。
5.6 后台 AI 对话:借道 DSH 的异步回复
后台页面 ──POST──> 后端 /api/admin/ai/chat/** → AdminChatDshClient
→ 微信桥 POST /admin-chat(独立工作目录,Hindsight 不收录后台会话)
→ DSH 会话执行
├─ 正常:桥返回正文 → 后端落 ai_chat_turn
└─ 超时未答:桥登记 admin-chat pending
│
AdminChatPendingJob(每 10s)
│ 取回 pending / ack / archive
▼
后端落库 → 前端轮询/SSE 展示
附件:ChatAttachmentService 私有存储 → 物化到 DSH 工作目录(失败回滚)设计意图:后台对话与微信共用同一套 DSH 能力,但工作目录与记忆收录隔离(后台对话不进 Hindsight)。
5.7 会话采集:水位在服务端
宿主 cron(每 5 分钟)collect-sessions.sh
→ 读取 ~/.dsh/sessions 增量(zstd 多帧解压)
→ POST /api/agent/ingest/session(采集令牌 + IP 白名单 + 限速)
→ RAW 先落库(按 session_id+line_no 去重)
→ 解析:agent_session / agent_turn(解析失败保留 RAW)
→ 原子推进 last_line_no(服务端水位)
→ 成功才继续下一批;失败不推进 → 下一轮重试,不丢不重采集只覆盖微信与后台会话(cwd slug 白名单/排除 --root-code-- 等),代码/终端会话不采。
5.8 发布事件:一条内容牵动五件事
人点"发布"(后台)
└─ ArticleServiceImpl 状态变更(事务内)
└─ AFTER_COMMIT:ArticlePublishedEvent
├─ SubscriberNotifyListener → 订阅邮件(失败只记日志)
├─ ArticlePublishAiListener → 摘要/标签/向量化(异步,失败不影响发布)
├─ ActionRetainService(记忆模块)→ "发布"作为可统计事件
└─ 门户缓存/SEO 自然更新(下次请求即最新)为什么用 AFTER_COMMIT:监听器要读到已提交的数据;若在事务内发通知,出现"邮件发了但事务回滚" 的鬼故事。架构闸强制业务事件监听器必须 AFTER_COMMIT。
5.9 通知与重试:不重复、不丢失
业务/扩展 → NotifyService.notify(title, content, dedupKey)
→ 幂等抢占:插 notify_log(pending),dedup_key 唯一冲突即返回
→ 按 priority 尝试外部通道(微信 webhook → 邮件)
├─ 成功:sent + 实际通道
└─ 全部失败:failed(retry=0)
→ NotifyRetryJob(每分钟)重投 retry<2 的 failed
└─ 成功 → NotifyRetryLinkHandler 回写业务表(如 daily_reminder.status=sent)
→ 无任何外部通道:降级 inapp(只写库)成功判据:HTTP 2xx 且响应体无业务错误码;"200 但内容说失败"不算成功(审查修过)。
5.10 鉴权链:三套主体、互不混用
| 入口 | 拦截器 | 主体 | 凭证 | 失败 |
|---|---|---|---|---|
/api/admin | IP 白名单 → JWT | 后台用户 | Authorization: Bearer <JWT> | 401/403 |
/api/agent(MCP/ingest/heartbeat/instructions) | AgentAuthInterceptor | Agent / 程序 | 专用令牌 + scope + IP 白名单 + 限速 | 401/403/429 |
门户 /api/portal | 公开 + 访客防护 | 访客 | 验证码/限流(写操作) | 业务 code |
| 微信桥 → 后端 | 采集令牌(心跳)/ MCP 令牌(工具调用) | 桥进程 | 600 权限令牌文件 | 拒绝并告警 |
scope 在工具层二次校验(读工具要读 scope、写工具要写 scope);MCP tools/list 目前 不按 scope 过滤(见 13)。
5.11 出网与隐私:内容离开进程前的四道关
- 数据层:门户/RAG 访客版 SQL 过滤(
status=1、is_public=1); - 调用方:隐私档(private 不进上下文;后台-only 内容不进门户);
- 网关/交付点:
EgressGate档位 +EgressLedger台账(chat/embed/context 三个通道); - 可追溯:台账按场景/通道/级别/字节记录,能回答"哪一次、把什么级别的多少内容交出去了"。
5.12 扩展运行链
见 4.4:策略 → 能力网关 → 效果提交 → 自愈。与主动消息链的区别是 "谁产出文案":扩展 handler 产出,通知链负责送达。
5.13 发布、备份与恢复链
发布:deploy-server.sh → 构建 jar → 构建镜像 → 起容器 → 健康检查 → 打 tag
备份:每天 03:00 mysql-backup.sh(db + uploads + hindsight), 保留 7 天/7 份
恢复:mysql-restore.sh(默认恢复到临时库,生产恢复需白名单+4 个显式开关)
restore-all.sh / restore-drill.sh(全量恢复与演练)
体检:doctor.sh(25 项)+ check-deploy-guards.sh(发布守卫)关键安全设计:恢复脚本默认不碰生产;生产恢复必须显式允许(白名单 + --allow-production
--drop-existing+--yes),且只按 dump 覆盖同名表,不 DROP 生产库。
5.14 心跳与探针:外部进程的死活也要有判据
| 来源 | 频率 | 写什么 | 消费者 |
|---|---|---|---|
| 微信桥 | 300s | sys_job_log(bridgeHeartbeat) | doctor.sh、能力健康看板、HeartbeatWatchJob |
| chain-probe.sh | 5 分钟 | sys_job_log(chainProbe) | 同上;链路异常时发邮件/站内告警 |
| collect-sessions.sh | 5 分钟 | ingest 成功顺带上报 | 同上 |
| health-monitor.sh | 每分钟 | 外部告警(邮件/webhook) | 博主 |
HeartbeatWatchJob 每 5 分钟检查超时心跳并恢复;超时的来源会在看板上显示为 stale, 不会把"进程死了"误读成"任务没跑"。