Skip to content

五、跨模块关键链路 ​

本章速览:单个模块看完了,真正容易出事的是跨模块的链。下面 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
会话采集宿主 cronRAW 先落库 → 解析 → 服务端水位解析失败保留 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/adminIP 白名单 → JWT后台用户Authorization: Bearer <JWT>401/403
/api/agent(MCP/ingest/heartbeat/instructions)AgentAuthInterceptorAgent / 程序专用令牌 + scope + IP 白名单 + 限速401/403/429
门户 /api/portal公开 + 访客防护访客验证码/限流(写操作)业务 code
微信桥 → 后端采集令牌(心跳)/ MCP 令牌(工具调用)桥进程600 权限令牌文件拒绝并告警

scope 在工具层二次校验(读工具要读 scope、写工具要写 scope);MCP tools/list 目前 不按 scope 过滤(见 13)。

5.11 出网与隐私:内容离开进程前的四道关 ​

  1. 数据层:门户/RAG 访客版 SQL 过滤(status=1、is_public=1);
  2. 调用方:隐私档(private 不进上下文;后台-only 内容不进门户);
  3. 网关/交付点:EgressGate 档位 + EgressLedger 台账(chat/embed/context 三个通道);
  4. 可追溯:台账按场景/通道/级别/字节记录,能回答"哪一次、把什么级别的多少内容交出去了"。

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 心跳与探针:外部进程的死活也要有判据 ​

来源频率写什么消费者
微信桥300ssys_job_log(bridgeHeartbeat)doctor.sh、能力健康看板、HeartbeatWatchJob
chain-probe.sh5 分钟sys_job_log(chainProbe)同上;链路异常时发邮件/站内告警
collect-sessions.sh5 分钟ingest 成功顺带上报同上
health-monitor.sh每分钟外部告警(邮件/webhook)博主

HeartbeatWatchJob 每 5 分钟检查超时心跳并恢复;超时的来源会在看板上显示为 stale, 不会把"进程死了"误读成"任务没跑"。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。