主题
三、功能模块详解
本章速览:11 个模块按"用户能看到的功能"组织。每个模块先给一张模块卡(一句话职责 / 用户功能 / 关键设计 / 入口 / 数据表),点开折叠块才看类、状态机与失败边界。建议先读模块卡定位,再按需展开。
模块速查:11 个模块一句话定位(点开)
| 模块 | 一句话职责 | 主要数据表 | 你能用它做什么 | 小节 |
|---|---|---|---|---|
module_system | 身份、配置与站点底座 | sys_*(13) | 登录、改站点配置、传图、发订阅邮件、看审计 | §3.1 |
module_blog | 内容生产与门户数据面 | blog_*(14) | 写文章、发说说、管相册、评论留言、搜索 | §3.2 |
module_note | 完全私有的笔记 | note_*(5) | 记笔记、回收站、转文章草稿 | §3.3 |
module_daily | 日程、课表与提醒 | daily_*(5) | 待办/步骤/重复、按天课表、到点提醒 | §3.4 |
module_memory | 长期记忆、关系层与选材 | ai_* 记忆/关系表(10+) | 助手记住与回忆、线头/关怀/分歧、生活统计 | §3.5 |
module_llm | 模型通道与出网总闸 | ai_provider 等(4) | 配模型、看向量与成本、额度/熔断 | §3.6 |
module_ai | AI 产品层 | ai_conversation 等(5+) | 对话、分身、写作、知识库、每日日记 | §3.7 |
module_agent | MCP 工具面与人设 | agent_token 等(2) | 让微信/DSH 查日程、写记忆、记事件 | §3.8 |
module_conversation | 会话采集与附件 | agent_*、chat_attachment(7) | 回看历史对话、管聊天附件 | §3.9 |
module_notify | 通知唯一出口 | notify_*、proactive_log(3) | 晨报/提醒送达、失败重试 | §3.10 |
module_ops | 运维台与导入导出 | 跨模块只读 | 健康检查、清理、导入导出、能力看板 | §3.11 |
3.1 module_system:系统、身份与站点配置
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 身份、配置与站点基础能力的底座:登录/安全、配置开关、文件、邮件、导航/部件、订阅、心跳与审计。 |
| 用户功能 | 后台登录与安全中心;站点名称/页脚/开关等配置;图片与附件上传;邮件测试与订阅发信;导航/底部 Tab/部件;访问/搜索/登录审计;健康检查与外部心跳。 |
| 关键设计 | ① 配置写侧校验:脏值/非法枚举/错误时间格式当场拒绝,不靠消费方兜底;② 敏感值 enc: 加密入库、接口只回掩码;③ 三套鉴权主体分离,后台 IP 白名单先于 JWT 执行。 |
| 职责 | 认证与安全、站点配置、文件上传、邮件、导航/部件、访问与搜索日志、订阅、心跳 |
| 入口 | /api/admin/system(后台)、/api/portal/site(门户公开配置)、/api/health* |
| 数据表 | sys_user、sys_config、sys_file、sys_file_folder、sys_audit_log、sys_login_log、sys_job_log、sys_mail_log、sys_search_log、sys_subscriber、sys_visit_log、sys_widget、sys_api_key |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | AuthServiceImpl、SecurityServiceImpl、SysConfigServiceImpl、FileServiceImpl、MailServiceImpl、HeartbeatServiceImpl、StatsServiceImpl、AuthInterceptor、AuditAspect |
| 失败形态 | 登录失败锁定;SMTP 未配置静默跳过(不影响主流程);配置脏值写侧拒绝(§6.2) |
认证与安全
登录:POST /api/admin/auth/login 收用户名/密码;AuthServiceImpl 用 bcrypt 校验, 失败次数超阈值锁定(sys_login_log 记录 IP/UA/结果),成功后签 JWT(HMAC,COSMOS_JWT_SECRET)。 AuthInterceptor 只校验 /api/admin(除登录/验证码等白名单);前端把 token 放 Authorization: Bearer,过期统一 401 → 前端跳登录。
后台 IP 白名单(SecurityServiceImpl + AdminIpGuardInterceptor):白名单存在 site.security.* 配置里;拦截器先于 JWT执行,登录接口也受约束。匹配支持精确 IP 与 CIDR。 这是"网络层兜底":即使密码泄漏,非白名单 IP 也进不来。
API Key:sys_api_key 存哈希与前缀,供脚本/程序调用;check-agent-token.sh 做只读自检。
登录告警:异地/新 UA 登录写站内通知并发邮件(SecurityServiceImpl 告警链), 告警去重避免轰炸。
站点配置(全项目最关键的"开关面")
SysConfigServiceImpl:
- 存储:
sys_config(key, value, remark, secret);敏感项值以enc:前缀密文入库 (CryptoUtil+COSMOS_SECRET_KEY),接口列表只回******。 - 读取:
getValue(key, default)带单键 30 秒缓存;保存路径在事务提交后清缓存 (TxHooks.afterCommit),所以后台改完立即生效,直接改库最多 30 秒收敛。 - 写入:
saveBatch(items)做四件事 —— ① 键名格式校验(^[a-z][a-z0-9.-]{1,95}$);② 只允许更新迁移里已种下的键 (防止运行期凭空造键/重建已删旧键);③ 结构化取值校验(时间键必须HH:mm、 出网档位枚举、熔断模式枚举、额度键非负整数 —— 见 6.2);④ 提交后发布ConfigSavedEvent,让关心特定键的组件(如日报时间 → 扩展触发器 cron)同步。 - 敏感项留空 = 不修改(前端回显掩码,用户没动就不覆盖)。
为什么把校验放在写侧:消费方普遍采用"读不出来回落默认"以保证不因脏值停摆, 于是错值表现为"保存成功、行为未变/悄悄改变"。写侧拒绝没有停摆风险,还能当场说明格式。
文件与媒体
FileServiceImpl:上传 → 校验扩展名与 MIME 白名单 → 随机文件名 + 日期分目录 → 写 sys_file(url/大小/sha256/文件夹)→ 通过 FileStoragePort 落盘(生产为挂载卷 /opt/vite-cosmos/uploads)。删除时先查引用:MediaReferenceProvider 由各模块实现 (文章正文/封面、说说、相册、笔记图标、友链头像、站点配置…),引用反查不到就保守保留, 避免"清理孤儿文件"误删仅被某个新引用面引用的图(审查 #68 修的就是引用面漏项)。
上传安全:X-Content-Type-Options: nosniff、私有附件独立目录、下载时按服务端校验过的 扩展名推导 MIME(不信任客户端声明的类型)。
邮件、订阅与通知前置
MailServiceImpl:SMTP 参数全部来自 sys_config(授权码密文),未配置时静默跳过并只记 sys_mail_log(失败不影响主流程);sendToAdmin / sendToSubscriber 两个语义分开, 订阅退订链接带签名 token(site.subscribe.*)。
SubscriberServiceImpl:门户订阅 = 邮箱 + 验证码 + 限流;退订走带签名的链接; 新文章发布时 SubscriberNotifyListener 监听 ArticlePublishedEvent(AFTER_COMMIT), 按订阅列表批量发信,失败写日志但不阻塞发布。
导航、部件与门户配置
- 导航:
site.nav.items存 JSON(导航项 + 移动端底部 Tab),NavService读/写/重置默认; 门户通过/api/portal/site拿装配结果。 - 部件(Widget):区域 + 部件模型;
WidgetService.portalLayout()只返回enabled=1的部件, 按区域分组,并附带布局配置(侧栏位置、目录形态、注入代码、页脚版权开关)。 - 站点信息:
SiteController一次返回站点名/描述/页脚/备案/社交链接/开关等, 门户首屏只发一个请求。
心跳:让"外部进程活着"可查询
HeartbeatServiceImpl 把 bridge / chain-probe / ingest 的上报写进 sys_job_log (每个来源一行、update_time 即最后上报),HeartbeatWatchJob 每 5 分钟检查超时并恢复/告警。 好处:能力健康看板与 doctor.sh 不需要各自造轮子,"桥还活着吗"直接查库。
失败与边界
- JWT 过期/签名错 → 401;IP 不在白名单 → 403;账号锁定按失败次数与时间窗;
- SMTP 未配置/发送失败:主流程继续,日志留痕(订阅/告警可能因此静默——
doctor.sh会提示); - 配置缓存 30 秒内可能读到旧值(保存会主动失效,手改库最多 30 秒);
- 心跳写入失败只告警不重试(外部进程下一轮会再报)。
3.2 module_blog:内容、互动与门户数据
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 内容生产与门户数据面:文章、页面、说说、相册、评论/留言/友链、搜索与 SEO。 |
| 用户功能 | 写文章(草稿/定时/历史版本/系列/片段)、自定义页面、说说时间线、相册、评论与留言(含楼中楼与审核)、友链申请、分类/标签/归档、站内搜索、sitemap/rss。 |
| 关键设计 | ① 文章状态机 + AFTER_COMMIT 发布事件驱动订阅与 AI 增强;② 门户接口在 SQL 层强制 status=1/可见性;③ 访客写统一四层防护:验证码→限流→敏感词→审核。 |
| 职责 | 文章/页面/说说/相册/评论/留言/友链/分类/标签/系列/片段/搜索/SEO/订阅联动 |
| 入口 | /api/admin/blog(95 端点)、/api/portal/blog(只读 + 评论/留言/订阅) |
| 数据表 | blog_article、blog_article_history、blog_article_tag、blog_page、blog_talk、blog_album、blog_photo、blog_comment、blog_message、blog_friend_link、blog_category、blog_tag、blog_series、blog_snippet |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | ArticleServiceImpl、ArticlePublishJob、ArticleEventListener、CommentServiceImpl、SearchServiceImpl、SeoController、MarkdownRenderer |
| 失败形态 | 门户强制 status=1;评论四层防护;发布事件 AFTER_COMMIT;导入内容转义 |
文章:一条内容的完整生命周期
状态机:
草稿(status=0) ──发布──> 已发布(status=1) ──下架──> 草稿
│ │
│ 定时发布(pubDate) ├─ 修改 → 历史快照(blog_article_history)
└── 删除(软删) └─ 删除 → 回收站/软删(可恢复)- 保存:
ArticleServiceImpl.save统一入口;标题去空白、摘要缺省由正文截取、 Markdown 原文入contentMd、渲染 HTML 入content(MarkdownRenderer白名单清洗); 标签走blog_article_tag关系表(先删后插)。 - 定时发布:
ArticlePublishJob每分钟扫描status=0 AND pub_date <= now的文章并发布; 发布动作发ArticlePublishedEvent(事务提交后)。 - 历史版本:每次保存前把旧内容写
blog_article_history;后台可看 diff。 - 事件消费者:
SubscriberNotifyListener→ 订阅邮件;ArticlePublishAiListener→ 自动摘要/标签/向量化(异步,失败不阻塞发布);ActionRetainService(记忆模块)→ 把"发布"作为可统计事件。
- 门户可见性:所有 portal 服务在 SQL 层强制
status=1,文章详情额外按visibility与密码保护字段过滤;草稿/下架不可能从门户泄漏。
页面、说说与相册
| 类型 | 实现要点 |
|---|---|
自定义页面 blog_page | slug 唯一;Markdown 正文;导航可挂;门户 /page/:slug |
说说 blog_talk | 短文本 + 图片/表情;时间线倒序;门户首页/说说页分页 |
相册 blog_album + blog_photo | 两级结构;照片含描述/排序/EXIF 可选;门户瀑布流;封面可用第一张 |
系列 blog_series | 有明确阅读顺序(sort);文章详情返回"所属系列 + 上一篇/下一篇";删除系列只解除归属不删文章 |
片段 blog_snippet | 可复用 Markdown 块,编辑器一键插入(署名/免责声明/常用命令) |
分类、标签与搜索
- 分类:单层树(parent_id 预留),slug 唯一;删除前要求无文章或迁移。
- 标签:多对多;标签云按文章数排序。
- 搜索
SearchServiceImpl:覆盖文章 + 页面 + 说说三类公开内容;标题/正文/摘要多字段 LIKE + 相关度排序;门户/search与 MCP 搜索工具共用(MCP 侧走SearchService而非裸 SQL)。
SEO 与门户元数据
SeoController 输出 /sitemap.xml(只含已发布文章/页面/分类/标签/说说/相册)、/rss.xml (最近文章)、robots.txt;站点域名与是否启用由配置决定。MetaPortalController 提供 分类/标签/归档的聚合数据(归档按年月分组)。门户是 SPA,首屏 SEO 依赖这些服务端端点。
评论、留言与友链:同一条"访客写入防线"
访客写入口(评论/留言/友链申请)统一四层:
- 验证码(
CaptchaService,图片验证码,内存 TTL 存储,一次性消费); - IP 频率限制(内存滑动窗口,防刷屏);
- 敏感词(
site.comment.forbidden_words逗号分隔,命中直接拒绝并提示); - 审核开关(
site.comment.audit.*):需审核的进pending,博主批准后可见。
评论支持楼中楼(parentId)、博主回复、点赞、状态(显示/隐藏/待审)、举报(管理端处理); 留言板同理但无楼中楼。所有通过的内容都由 MarkdownRenderer 做 HTML 清洗, 防存储型 XSS。
失败与边界
- 文章不存在/未发布 → 门户 404 语义(
code=20001或 10004,按接口约定); - 定时发布与手动发布并发:发布动作幂等(状态判断),事件只发一次(同一事务内状态变更);
- 评论审核关闭时直接可见,但敏感词与限流仍生效;
- 订阅邮件失败不回滚发布;
- 导入外部内容(见 3.11)默认草稿且 HTML 转义,绝不直接发布。
3.3 module_note:完全私有的笔记
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 完全私有的笔记工作区,与公开博客严格隔离。 |
| 用户功能 | 笔记本树、Markdown 笔记、标签/星标、历史版本、回收站恢复、把笔记转成文章草稿。 |
| 关键设计 | ① 只有 admin 端点可达,不进门户/RAG/访客分身;② 删除保留标签关系,恢复不丢标签;③ 笔记转文章只创建草稿,发布由人决定。 |
| 职责 | 笔记本树、笔记 CRUD、标签、星标、历史、回收站、笔记↔文章互转 |
| 入口 | /api/admin/note(20 端点,全部 admin-only) |
| 数据表 | note_notebook、note_note、note_note_tag、note_tag、note_history |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | NoteServiceImpl、NotebookServiceImpl、NoteArticleSyncListener |
| 失败形态 | 删除保留标签关系(回收站恢复不丢标签,审查 #55);私有内容不进门户/访客 |
结构与实现
- 笔记本树:
note_notebook(parent_id, sort);移动节点时校验不能移入自己的子树; 删除笔记本要求其下无笔记(或指定迁移目标)。 - 笔记:Markdown 正文 + 摘要;
starred星标;notebook_id归属;标签多对多。 - 历史:
note_history保存每次修改前快照;可回滚(写回并再记一条历史)。 - 回收站:软删
deleted=1;trash/page列出、restore恢复;恢复时保留原有标签关系 (早期实现删除时清了关系,导致恢复丢标签 —— 审查 #55 修复)。 - 全文检索:后台列表的 keyword 查询走标题/正文 LIKE;不引入 ES(数据量在单用户量级)。
- 笔记↔文章:
NoteArticleSyncListener在笔记被转为文章(或文章存为笔记)时维护双向引用; 转文章时只创建草稿,是否发布由人决定(设计哲学第 4 条)。
隐私边界
笔记是"完全私有"数据:只有 admin 端点可达,不参与门户检索、不进 RAG 访客版、 不进访客分身上下文;记忆抽取默认也不把笔记正文当素材(见 3.5 的隐私口径)。
3.4 module_daily:日程、课表与提醒
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 日程、课表、节假日与提醒的单一事实来源。 |
| 用户功能 | 今日一屏、待办(多步/重复系列)、按天课表、节假日三值判定、到点提醒与补投、门户「今日」。 |
| 关键设计 | ① 课次按天存储,natural_key 唯一索引保证幂等与冲突可判;② 提醒用 dedup_key 幂等,失败可重试、超窗标 skipped;③ 时间锚点类提醒绝不提前,润色失败发模板。 |
| 职责 | 待办(含多步与重复系列)、课表(按天)、节假日、提醒投递、今日一屏、门户"今日" |
| 入口 | /api/admin/daily(35 端点)、/api/portal/daily、MCP daily_brief / daily_todo / daily_course 工具 |
| 数据表 | daily_todo、daily_todo_series、daily_course_session、daily_holiday、daily_reminder |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | DailyTodoServiceImpl、DailyTodoSeriesJob、DailyCourseSessionServiceImpl、HolidayServiceImpl、DailyReminderJob/ServiceImpl、DailyOverviewServiceImpl |
| 失败形态 | 课程冲突 409;提醒按模式去重;节假日三值判定;越权/越期告警 |
待办:一条待办可以有步骤,也可以重复
数据模型:daily_todo 自引用 —— parent_id 为空是任务,非空是步骤。好处是 "今日一屏"只需查一张表,步骤与任务共享状态机与排序。
状态机:
pending ──done──> done
│ └──drop──> dropped(可 restore 回 pending)
└─ skip(系列本次跳过,不改状态,仅不提醒)- 多步任务:步骤按
sort排序;完成全部步骤不会自动完成任务(由人决定); 删除任务级联删步骤;步骤的done单独记录时间。 - 重复系列:
daily_todo_series存规则(repeatRule:daily|weekdays|weekends|weekly:1,3,5)- 起始/结束日期;
DailyTodoSeriesJob每天 00:05 物化当天的实例(幂等:同 series+日期唯一); MCP/后台的series_stop/resume/skip/update管理系列。非法 repeatRule 在工具层明确拒绝 并给出可选值(不静默存一条"看起来会重复"的假规则)。
- 起始/结束日期;
- 提醒联动:保存/修改/删除待办时重算提醒计划(
daily_reminder),删除任务时取消未投递提醒。
课表:为什么改成"按天"
旧模型是"星期几 + 周次"的周模板,表达不了同一时段不同周次换课、节假日调课(真实课表就是)。 M165 起改为 daily_course_session:每行 = 某天的某一节课(日期 + 课程名 + 开始/结束时间 + 地点)。 natural_key 唯一约束保证"同日期+同课程名+同开始时间"幂等,重复 add 不会造出两条。
- 校验:
end_time > start_time(否则显式拒绝,交给调用方留空按 +2h 估算 —— 审查 #78); - 冲突:同一时段重叠返回 409(前端可弹"调整时间");
- 补课/调课:直接增删改当天行;
PATCH支持拖拽改期改时并重算提醒。
节假日:三值判定,而不是布尔
HolidayService 返回 workday | holiday | unknown 三值。为什么不是 boolean:节假日数据源 可能没覆盖某一年,unknown 必须与"确定是工作日"区分开,否则"今天上不上课"会被猜成确定答案。 数据来自公开源(当年 + 次年),HolidayFetchJob 按 site.daily.holiday.years-ahead(0–3) 拉取并缓存 daily_holiday;含调休(workday 覆盖周末)。晨报/提醒/判定都走这一接口。
提醒:DB 轮询 + 幂等 + 双通道
DailyReminderService 是"提醒点"的唯一真相:
- 计划:
planDue(now, catchUp)扫描课程/待办/自定义提醒,生成daily_reminder行,dedup_key = 类型:对象:时间唯一索引幂等;重复扫描不会产生两条。 - 投递:统一模式(
COSMOS_PROACTIVE_UNIFIED_ENABLED=true)下由扩展system.reminder每分钟触发,能力reminder.pending.read取出到点提醒,走"润色缓存 → 通知投递"; 旧路径deliverDue保留为降级/迁移期能力。 - 状态:
pending → sent / failed / skipped;失败可retry(后台/MCP); 补投窗口由catchUpMinutes控制(重启后不丢当天提醒)。 - 准点策略:到点前 10 分钟预润色(见 5.1),到点只读缓存;润色失败/缓存过期发模板, 绝不因为润色而晚发。发送判据:时间锚点类(课程/自定义)绝不提前,待办类最多提前 30 秒 (=调度器粒度)—— 审查 #69 的结论。
今日一屏与门户"今日"
DailyOverviewServiceImpl 聚合同一天的课程 + 待办(含逾期)+ 提醒计划 + 统计; PortalDailyServiceImpl 是它的隐私收窄版:门户只返回计数与课程名,不返回待办标题 (待办可能含私密信息)。两个服务共用底层查询,但输出字段不同 —— 这是"同一数据、不同可见性" 的典型实现。
失败与边界
- 课程冲突 409;非法时间显式拒绝;节假日数据缺失时
unknown而非猜; - 提醒重复扫描幂等;发送失败进入 retry,超次数记 failed;
- 重复系列物化失败会被下一次扫描补齐(幂等);
- 待办/提醒的时区固定
Asia/Shanghai(业务时间,不走扩展平台的 UTC 口径)。
3.5 module_memory:长期记忆、关系层与主动消息选材
这是全项目最复杂的模块(135 个文件、71 个端点),先给一张"层次图"再拆开讲。
调用方(MCP 工具 / 扩展 capability / 定时任务 / 后台)
│
▼
MemoryFacade(统一门面:策略在这层,不在 Backend)
│ ├─> HindsightMemoryBackend ─> HindsightClient(HTTP 8890)
│ └─> 结构化事件/账本:ai_mem_event、ai_hs_operation、ai_egress_log…
▼
MySQL(结构化事实/关系状态/主动账本) + Hindsight(语义记忆/观测/知识页)一条设计原则:语义记忆的权威在 Hindsight,结构化事件与关系状态的权威在 MySQL。 v18 之后不再维护 MySQL 的"记忆镜像表",避免两套写入互相漂移;ai_mem_event 只存 可聚合的生活事件(跑步/睡眠/消费/课程…),通过镜像 Job 生成 Hindsight 摘要。
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 长期记忆、关系层与主动消息的选材中心(全项目最复杂的模块)。 |
| 用户功能 | 助手记得事实/偏好/情绪/关系;语义召回与遗忘;未了线头/关怀/分歧/仪式/程序/叙事;生活事件聚合、模式与计划偏差;给主动消息选材。 |
| 关键设计 | ① 语义记忆权威在 Hindsight,结构化事件与关系状态在 MySQL,不维护双写镜像;② 隐私三级 + 每次出网记台账(不记正文);③ 主动产出「跳过必须有理由」(开关/预算/静默/无候选)。 |
| 职责 | 记忆写入/检索/遗忘、结构化事件、关系层(线头/关怀/分歧/仪式/流程/叙事)、生活模式与偏差、主动性选材、预润色缓存、Hindsight 运维 |
| 入口 | MCP 工具(memory_* / open_loop / emotion_note / care_reply / disagreement / procedure / ritual / narrative / profile_update / memory_verify / recall…)、扩展 capability、后台 /api/admin/hindsight 与 /api/admin/life |
| 数据表 | ai_mem_event、ai_mem_coverage、ai_mem_metric_schema、ai_open_loop、ai_care_checkin、ai_disagreement、ai_ritual、ai_memory_procedure、ai_narrative_chapter、proactive_compose(+ Hindsight 侧库、ai_hs_* 账本) |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | MemoryFacade、HindsightMemoryBackend、MemoryWriteServiceImpl、MemorySearchServiceImpl、MemoryForgetServiceImpl、OpenLoopServiceImpl、CareCheckInServiceImpl、DisagreementServiceImpl、RitualServiceImpl、ProcedureServiceImpl、NarrativeServiceImpl、CoverageServiceImpl、EventPatternServiceImpl、PlanDeviationServiceImpl、ProactiveComposeCacheService |
记忆写入:一条"记住"要过几道关
调用方(模型/扩展/后台)→ MemoryWriteCmd:
| 字段 | 作用 |
|---|---|
text | 自洽的一句话(写入前校验非空) |
type | fact/preference/goal/event/emotion/relation/pattern/drift;事件类还进结构化事件管道 |
subject/predicate/object | 结构化三元组(memory_fact_upsert 用;同主语+谓语旧事实被标记"已取代"而非删除) |
importance | 0–100;影响后续召回排序与分析素材门槛 |
privacy | public/internal/private;private 不进模型上下文 |
dedupe_key | 幂等键;同内容重复写不会产生第二条(服务端也会按内容算键) |
provenance | 来源:conversation/article/manual/digest;是否 verbatim 原话 |
occurred_at | 事件发生时间(不是写入时间)—— 影响"什么时候发生的"类召回 |
confidence | 低置信进"待确认队列",人工确认后才参与检索 |
写入路径(MemoryWriteServiceImpl → MemoryFacade.write):
- 参数/隐私/去重键归一;
- 写 Hindsight(
document_id/operation_id幂等;异步 operation 由HindsightOperationJob确认); - 落库校验:读回确认写入成功,失败如实返回错误(不假称"记下了");
- 返回
created / dedupe-hit / pendingReview三态,MCP 回执按三态给不同话术。
记忆检索:召回不是"搜一下"
MemorySearchServiceImpl:
- 构造检索请求:语义 query + 过滤(type/privacy/state/valid_until/时间窗);
- Hindsight
recall(读请求重试 2 次,仅对 5xx/限流/网络错误;Retry-After尊重); - 词面重排(
LexicalReranker.overlap):语义分数高但字面不相关时降权; - 置信校准(
contractScore):语义 0.5–0.6 的"话题相近"结果对外给 0,避免假相关; - 出网台账:把"交付给模型的内容"记入
ai_egress_log(级别条数/字节,不记正文); - 返回
why(为什么命中)与sourceRef(可回溯来源),让模型能引用而不是编造。
valid_until 过期的观测在检索时被过滤;privacy=private 的内容不进入上下文。
遗忘:三种粒度,必须有回执
MemoryForgetServiceImpl 支持按 id / 关键词 / 会话整段遗忘;mode=soft(失效可回溯) 或 hard(物理删除,连向量一起抹)。遗忘是幂等的:已经不在了也返回成功("之前就删过")。 删除后触发向量清理(MemoryVectorPort);孤儿向量由 OrphanVectorSweepJob 每周兜底清扫。
结构化事件与生活管道
ai_mem_event 记录有数值的生活事件(跑步距离/睡眠时长/消费/课程/照片…), LifeEventService 提供写入与聚合查询(次数/合计/平均/按天趋势/按地点), 供 MCP 的 event_record/event_query 使用。聚合在 SQL 层完成,不让模型自己加数字 (那是幻觉的主要来源)。
生活质量层:
| 能力 | 服务 | 实现要点 |
|---|---|---|
| 覆盖率闸门 | CoverageServiceImpl | "任何'他没做 X'的结论,先证明'他若做了我们会知道'";输出覆盖率而不是缺席断言 |
| 生活模式 | EventPatternServiceImpl | 统计窗口内某类事件的频率变化,产出"最近不跑步了"这种可问的候选,不直接下结论 |
| 计划偏差 | PlanDeviationServiceImpl | 课表/计划 vs 实际记录,措辞是"没有记录到"而不是"你缺课了";重复≥3 次才算模式 |
| 证伪探针 | FalsificationServiceImpl | 周期性挑一条高重要度记忆去问"还是这样吗",用回答修正/证伪 |
关系层:让"记得"变成"相处"
这一组服务共同维护关系连续性,每个都有自己的状态机:
| 服务 / 表 | 状态机 | 关键设计 |
|---|---|---|
未了线头 ai_open_loop | open → closed / dropped;raise 记提及次数与预算 | 读不产生副作用:listOpen 只读,提及由调用方显式 raise;预算防止"每份晨报都提同一条" |
主动关怀 ai_care_checkin | sent → replied / ignored;去重键 + 静默时段 | 只负责"记录与回溯";选材/预算/静默在扩展 handler(4.5),职责分离 |
分歧 ai_disagreement | open → conceded/held/settled/dropped;push_count 提两次自动收口 | 反谄媚:防"随风倒";markPushed 由 MCP disagreement(list) 触发(审查 #75) |
仪式 ai_ritual | proposed → active → paused/retired;done 记完成 | proposed 永不执行(未经同意不主动);到期判定由代码算(dueNow),不交给模型 |
程序记忆 ai_memory_procedure | candidate → confirmed(观察到第 2 次才升) | "一次是偶然,两次才是习惯";use_count 记录使用 |
叙事章节 ai_narrative_chapter | build → get;密度/覆盖天数 | 提取式(主题频次+事件重要度+情绪弧),density=thin 时不能当完整经历讲 |
关系档案(PersonaSnapshot,存 Hindsight directive;旧 MySQL 表 ai_profile 已删) | 阶段/直言度只由本人定 | 助手工具只能建议,不能改(红线写进工具注释) |
预润色缓存:为什么只有提醒用它
ProactiveComposeCacheService:到点前 lead 分钟(3–30,默认 10)把提醒文案交给 DSH 润色, 写入 proactive_compose(status=ready/failed,带模板+事实哈希、过期时间);到点只读。 失败行短 TTL(3 分钟)避免 DSH 故障时每分钟重试拖垮提醒任务;成功行额外留 40 分钟覆盖补投窗口。 其它主动消息(晨报/晚报/关怀/周复盘)到点同步润色,多等几秒没有代价,模板兜底保证不丢。
Hindsight 运维面
| 组件 | 作用 |
|---|---|
HindsightIngestJob/Service | MySQL 结构化数据 → Hindsight 增量摄取(水位 ai_hs_ingest_cursor) |
HindsightOperationJob | 轮询异步 operation,补"入队后无人确认"闭环(ai_hs_operation) |
EventHindsightMirrorJob | 结构化事件 → 语义摘要镜像(MySQL 仍是权威) |
BackfillEventJob | 历史回填(只补缺失,不重试失败) |
HindsightConsoleController/Service | 后台总览、观测列表、操作详情、审计统计、知识页 |
HindsightUpgradeController/Service | 版本升级/回滚(宿主脚本,审批 + 备份) |
HindsightHealthService | 健康探测(readiness、隔离/边界检查) |
ai_hs_usage / ai_memory_archive | 用量与归档(只读/复合主键,不走 MyBatis-Plus) |
失败与边界
- Hindsight 不可用:检索返回明确错误/降级(不编造);写入失败如实回报,不假称记住;
- 异步 operation 未确认:Job 轮询补确认,超时标 failed 并可见;
- 记忆写入与事件写入分属两条管道:事件聚合查询不依赖 Hindsight;
- 主动消息"跳过"必须给理由(开关/预算/静默/无候选),空产出不允许静默(
BuiltinOutputs.skip)。
3.6 module_llm:模型通道、出网闸与用量账
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 模型通道与所有 AI 出网的统一入口。 |
| 用户功能 | 多 provider 配置与连通性测试;chat/流式/向量化/生图;用量与成本报表;每日额度与熔断;提示词模板。 |
| 关键设计 | ① 所有出网走 AiGateway(出网闸 + 台账 + 用量);② 生图按固定 token 当量记账,不漏出限额;③ 熔断额度只统计门户侧,内部任务不挤占访客额度。 |
| 职责 | 多 provider 配置、统一网关(chat/stream/embed/image)、出网闸与台账、用量与熔断、提示词模板、知识库向量块 |
| 入口 | /api/admin/ai/provider(5 端点);其余为内部 SPI:AiGateway、EgressGatePort、AiUsageGuard |
| 数据表 | ai_provider、ai_prompt_template、ai_token_usage、ai_kb_chunk(+ ai_egress_log) |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | AiGatewayImpl、OpenAiCompatibleClient、EgressGate、EgressLedger、AiUsageGuardImpl、AiProviderServiceImpl、TokenUsageStatsServiceImpl、QueryVectorCache |
| 失败形态 | 出网被拒/供应商错误/超时;台账写失败不影响业务;熔断只拦门户侧 |
Provider 配置
ai_provider 一行一个通道:名称、类型(openai 兼容)、baseUrl、model、apiKey(enc: 密文)、 启用状态、超时/并发/成本单价。后台可测试连通性(发一条最小请求)、同类通道互斥激活。 AiGatewayImpl 按"启用 + 优先级"选通道,失败时按配置尝试备用通道。
网关:所有 AI 出网的唯一入口
四条路径:chat(同步)、chatStream(SSE)、embed(向量化)、image(生图)。
每条路径都做四件事:
- 出网闸(
EgressGate.check*):frozen一律拒绝;minimal只拦主动性/离线场景; - 隐私台账(
EgressLedger):记录交给外部的内容条数/级别/字节,不记正文; 生图按固定 token 当量(4000)记账,防止"生图不限额"的漏洞; - 调用与重试:HTTP 超时、5xx 重试有限次数(幂等读安全,写靠 request id);
- 用量(
ai_token_usage):场景、模型、prompt/completion tokens、成本、耗时、是否流式; 写失败只 warn,不影响回答。
QueryVectorCache:查询向量缓存 60 秒 / LRU 512 条 —— 同一句话重复检索不必重复付费。 TokenUsageStatsServiceImpl:给运维台做只读聚合(按场景/模型/日趋势/成本)。
用量熔断(AiUsageGuard)
site.ai.daily-token-limit(0=不限)只统计门户侧(avatar_portal 前缀)token, 不把内部任务(日报/记忆抽取/向量化)算进去 —— 否则内部任务会把访客额度顶穿。 超限后:
- 模式
off:不拦;alert:只发一次告警邮件;block:拒绝访客 AI 调用; - 告警每天最多一封,避免刷屏;
breaker-mode写脏值会在保存侧被拒绝(见 6.2);读侧未知值按block(安全默认)。
知识库向量块
ai_kb_chunk 存文档分块与向量引用:KnowledgeBaseServiceImpl 负责导入/分段/向量化, KbChunkService 负责按知识库/文档检索。向量本身在 Hindsight/向量端口,MySQL 只存块与映射, OrphanVectorSweepJob 与 VectorGcJob 负责清理孤儿/过期向量。
3.7 module_ai:分身、对话、写作、知识库与每日总结
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | AI 产品层:对话、数字分身、写作助手、知识库/RAG 与每日总结。 |
| 用户功能 | 后台 AI 对话(经 DSH)、门户数字分身、写作润色/扩写/翻译、知识库导入与问答、每日日记与文章草稿。 |
| 关键设计 | ① 访客分身走 SQL 层 publicOnly 过滤,私有内容进不了上下文;② 长任务异步 + 显式状态机(processing/draft/ignored/failed),失败冷却重试;③ 发布后的 AI 增强失败不影响发布本身。 |
| 职责 | 数字分身(门户访客版 + 博主版)、多会话 AI 对话(SSE)、写作助手、知识库/RAG、每日总结(日记)、发布后 AI 处理 |
| 入口 | /api/admin/ai(59 端点)、/api/portal/ai(访客分身)、MCP 无关(AI 能力多由扩展调用) |
| 数据表 | ai_conversation、ai_message、ai_chat_turn、ai_knowledge_base、ai_kb_document、ai_daily_digest、ai_diary_revision、ai_digest_cursor(+ ai_prompt_history) |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | AiChatServiceImpl、AiChatTurnService、AiAvatarServiceImpl、AiWritingServiceImpl、KnowledgeBaseServiceImpl、RagServiceImpl、DailyDigestJob/ServiceImpl、AdminChatDshClient |
| 失败形态 | 模型超时/限流;分身每日额度;总结失败进冷却重试;空输入记 ignored |
对话:会话、上下文与流式
- 数据模型:
ai_conversation(会话,带 scene 区分后台/分身)→ai_message(消息)→ai_chat_turn(一次问答的轮次与 token/耗时/状态,便于统计与重放)。 - 上下文装配:系统提示词 = 站点人设 + 场景指令 + 记忆/知识检索片段(可配场景开关); 长对话按 token 预算裁剪,保留最近 N 轮 + 摘要。
- 流式:
/stream用SseEmitter,前端fetch+ReadableStream逐段渲染;出错时发error事件并落库失败状态。 - 标题:首轮结束后异步生成会话标题(短、可重命名)。
- 后台对话走 DSH:后台 AI 对话(admin-chat)不是直连模型,而是通过微信桥调度 DSH 会话 (
AdminChatDshClient),桥把"超时但仍在执行"的回复登记为 pending,后端AdminChatPendingJob每 10 秒取回并落库;附件会物化到 DSH 工作目录,失败则回滚附件。
数字分身(两种可见性、同一套组件)
| 版本 | 数据来源 | 约束 |
|---|---|---|
门户访客版 /api/portal/ai/avatar | 公开知识库 + 公开文章摘要(publicOnly=true,SQL 层过滤) | 每日额度(site.ai.avatar.daily-limit,按访客 ID 限流)、敏感词/审核、免责声明、不读私有记忆 |
| 博主版(后台) | 私有记忆 + 笔记/日程(按隐私档) | 仍需出网台账;不对外 |
分身的"记忆"来自 RagService:访客版检索 SQL 强制 is_public=1,即使上层疏漏, 私有笔记也进不了上下文(这是数据层防线,不依赖调用方自觉)。
写作助手
/api/admin/ai/writing:润色、扩写、缩写、摘要、续写、翻译、标题生成。 场景化提示词存 ai_prompt_template(可后台编辑,支持 {变量} 占位), 输入长度与输出长度都有限制;结果只进编辑器,不自动发布。
知识库与 RAG
- 知识库
ai_knowledge_base(名称/描述/是否公开/来源过滤)→ 文档ai_kb_document(标题/来源/Markdown/状态)→ 分块ai_kb_chunk(序号/内容/向量引用)。 - 导入:手动粘贴 / 文章导入 / 笔记导入;分段按标题与长度切分;向量化走网关
embed(失败重试,状态可见)。 - 检索:
RagService按知识库范围 + 是否公开过滤,返回片段与来源;KbSourceFilter决定哪些内容可以进哪个分身。
每日总结(日记):时间点轮询 + 状态机
DailyDigestJob 每 60 秒轮询(fixedDelay),不解析 cron:读 site.ai.digest.time (默认 00:20),到点且"今天还没记录"就提交异步生成(aiExecutor,避免长 AI 调用占用调度线程)。 重启补偿:还没到今天的点、且"昨天"完全没有记录时补跑昨天(只补缺失,不重试失败)。
ai_daily_digest 状态机:
(无) ──claim──> processing ──成功──> note_only(只写日记)
│ └─ 配置开启 → draft(同时建文章草稿)
├─ 无输入 ──> ignored(不调模型,止住每分钟重试)
└─ 异常 ──> failed(记录 error;10 分钟冷却后定时重试)关键实现:
- 幂等:
date唯一键 + 行级 claim(processing抢占),重复触发不会生成两份; - 输入:当天对话轮次、待办完成情况、说说、课程、生活事件;备注等私密字段不进提示词;
- 输出:
summary_md(给人看的总结)与diary_md(第一人称日记);日记可选参考 Hindsight 长期背景(site.ai.digest.hindsight-context.enabled); - 人工编辑:后台可改日记(
ai_diary_revision存版本历史),可重新生成/回填最近 7 天; - 失败不阻塞:异常收敛为 failed 记录,定时任务冷却重试,不会每分钟轰炸模型。
发布后 AI 处理
ArticlePublishAiListener 监听发布事件(AFTER_COMMIT),异步做三件事: 生成摘要、推荐标签、向量化入库(知识库/RAG 可用)。任一失败只记日志,不影响文章已发布的事实 ——AI 是增强,不是发布的前置条件。
失败与边界
- 模型超时(默认 120s)与限流:错误如实返回;流式连接中断由客户端重连;
- 分身额度用尽:明确提示"今天的会话数已达上限";
- 每日总结:无输入记 ignored(省成本)、失败进冷却重试、人工可重生成;
- 发布后 AI 处理失败不回滚发布;
- 后台对话 DSH 超时:转 pending 由 Job 异步取回,用户不会"等到天荒地老"。
3.8 module_agent:AI 助理的工具面(MCP)与人设
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 把博客能力做成 AI 可调用的 MCP 工具面,并管理人设、模型与令牌。 |
| 用户功能 | 微信/DSH 通过工具查日程、写记忆、建提醒、写草稿、记生活事件;后台配置人设、模型、权限与令牌;生成 instructions。 |
| 关键设计 | ① 主 MCP 30 工具 + 扩展 MCP 40 工具,按 scope 校验;② 写工具回读校验后才说成功,更新 0 行必须如实报告;③ instructions 按预算裁剪,且生成时也记出网台账。 |
| 职责 | 把博客/日程/记忆能力暴露成 DSH 可调用的 MCP 工具;生成 instructions;人设与对话模型;令牌与 scope;后台对话 DSH 调度 |
| 入口 | POST /api/agent/mcp(主 MCP,30 工具)、POST /api/agent/extensions/mcp(扩展 MCP,40 工具)、GET /api/agent/instructions.md |
| 数据表 | agent_token、ai_prompt_history(+ 人设档案 PersonaSnapshot 存 Hindsight;旧 ai_profile 表已删;DSH session 文件) |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | McpToolServiceImpl、McpToolProvider 接口 + 9 个 provider、AgentInstructionsService、AssistantProfileServiceImpl、AdminChatDshClient、AgentAuthInterceptor |
| 失败形态 | 无权限 403;未知工具/参数错误明确返回;写工具"回读校验"后才能说成功 |
MCP 协议端点
McpController 实现 JSON-RPC 2.0 over HTTP(streamable-http):initialize、tools/list、 tools/call。鉴权由 AgentAuthInterceptor 完成:Bearer 专用令牌(600 权限文件)
- scope(
memory:write/daily:write/mcp/ext等)+ IP 白名单 + 限速; 每次调用写agent_tool_call_log(工具名、参数摘要、结果字节、耗时、caller)。
工具面分层:McpToolServiceImpl 只做协议与分发;具体工具按领域拆成 provider:
| Provider | 工具(示例) | 说明 |
|---|---|---|
DailyToolProvider | daily_brief、daily_todo(含步骤/系列)、daily_course、remind、schedule_fix | 只通过 module_daily 的 Service 读写 |
MemoryToolProvider | memory_search/write/fact_upsert/forget/verify、emotion_note、care_reply、open_loop、disagreement、ritual、procedure、narrative、profile_update | 13 个工具,关系层与记忆层的入口 |
LifeToolProvider | event_record、event_query、plan_deviation、image_ingest、coverage | 生活数据管道;聚合在 SQL 层 |
ContentToolProvider | article_draft_create、talk_publish、相册类 | 写内容只到草稿;发布权在人 |
SearchToolProvider | kb_search、session_search | 原文检索(文章/笔记/说说;历史会话原话) |
AlbumToolProvider | album_photo | 相册:收照片/查相册(从微信桥工作区取图) |
OpsToolProvider | job_run、job_status | 后台任务投递与查询 |
ReflectToolProvider | reflect | Hindsight 多轮推理 |
ExtensionToolProvider | extension_*(40 个) | 扩展平台的开发/安装/运行工具面 |
工具实现的四条纪律(所有 provider 共享):
- 权限先判:读工具要读 scope,写工具要写 scope;缺 scope 返回 403 并说明缺哪个。
- 参数必校验:缺必填/格式错要在工具层给出可执行提示(如"when 必须是绝对时间 YYYY-MM-DD HH:mm,先把'下周三'算出来"),不能把参数问题说成"存储坏了"。
- 回读校验:写成功后回查一次(id 存在/状态已变),
verified才说成功; 更新 0 行要如实说"没找到/没生效",不能假称成功(审查 #80/#81/#84 都是这类)。 - 回执给下一步:成功给"接下来会发生什么",失败给"怎么改参数"; 跳过给理由(
skipped而不是空字符串)。
主 30 工具清单见附录 K;扩展 40 工具由扩展包 manifest 声明、
ExtensionMcpController动态暴露(能力目录附录 N)。
instructions:给模型"人设 + 事实 + 边界"的提示词
GET /api/agent/instructions.md 由 AgentInstructionsService 生成,供微信桥每轮拉取 (桥会按时间头刷新)。内容分节:人设(来自 PersonaSnapshot / Hindsight directive;旧 ai_profile 表已删)、当前关系阶段/直言度、 今日日程摘要、未了线头、分歧、程序/仪式、记忆使用规则、工具使用规则、隐私红线。 生成时:
- 按 token/字数预算裁剪各节(超长节做摘要),避免提示词无限膨胀;
- 读取的私密内容不进入公开场景;
- 生成动作本身也记出网台账(上下文注入了哪些内容)。
人设与对话模型
- PersonaSnapshot(人设档案,v18 起存 Hindsight directive;旧
ai_profile表已删):昵称、作息、语气、兴趣、禁区、关系阶段、直言度。 助手可通过profile_update局部更新(只改传入字段,不会把没传的字段清空); 关系阶段/直言度是"本人定义",工具不给入口,只能建议。 - 模型配置:当前 provider/model/reasoningEffort 存在 DSH profile 的 patch 文件里; 后台可读可改(写前备份,改后验证),由
AssistantProfileServiceImpl与AssistantPermissionService管理权限与路径。 - 令牌:
agent_token只存前缀与哈希,明文只在创建时返回一次;可启停、删除、看最后使用时间。
后台 AI 对话:借道 DSH
后台"AI 对话"不是直连模型,而是:
后台 → AdminChatDshClient → 微信桥 /admin-chat → DSH 会话
│ 超时未答的 turn 登记 pending
▼
AdminChatPendingJob(每 10s)→ 取回 → 落库 → 前端轮询可见附件先由 ChatAttachmentService 存到私有目录,再物化到 DSH 工作目录(chat-cache)供其读取; 物化失败回滚附件记录,避免"上传成功但模型看不到"。
失败与边界
- 令牌无效/scope 不足:401/403 且给出缺哪个 scope;
- 工具参数错:
isError=true+ 可执行提示;未知名/未知 action 明确拒绝; - 写工具回读失败:如实报"没存上",绝不假成功;
- DSH 挂起/超时:后台对话转 pending 异步取回,不会无限等待;微信桥侧超时先回"还在做"。
3.9 module_conversation:DSH 会话采集、回看与附件
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 所有通知的唯一出口:微信 → 邮件 → 站内。 |
| 用户功能 | 晨报/提醒/告警的送达;失败自动重试并回写业务;主动消息预算与反馈台账。 |
| 关键设计 | ① 先插 pending 抢唯一键,天然防重复;② sent 只在通道自报成功时写(2xx 但业务失败不算);③ 站内兜底不掩盖外部失败,否则重试机制失效。 |
| 一句话 | 把 DSH 会话可靠地收进来、看得到,并把聊天附件安全地管起来。 |
| 用户功能 | 后台按会话回看对话与工具调用;聊天附件上传/下载;采集水位与心跳;原话检索。 |
| 关键设计 | ① 摄取先落 RAW 再解析(解析失败不丢数据);② 水位在服务端原子推进,失败不推进;③ 附件私有目录 + 归属校验 + nosniff,后台对话再物化给 DSH。 |
| 职责 | 采集 DSH 会话(增量、水位、幂等)、后台回看与检索、工具调用审计、聊天附件私有存储 |
| 入口 | POST /api/agent/ingest/session(宿主采集脚本调用)、/api/admin/agent、/api/admin/chat/attachments |
| 数据表 | agent_session、agent_turn、agent_session_raw、agent_ingest_log、agent_tool_call_log、agent_turn_attachment、chat_attachment |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | AgentIngestServiceImpl、AgentSessionQueryServiceImpl、ChatAttachmentServiceImpl、RawRetentionJob、LedgerRetentionJob、AdminChatPendingJob(在 module_ai) |
| 失败形态 | 摄取先落 RAW 再解析(解析失败不丢数据);水位在服务端,失败不推进 |
会话摄取:水位 + 幂等 + 降级
宿主 collect-sessions.sh 每 5 分钟读 ~/.dsh/sessions 的增量行,POST 到 /api/agent/ingest/session:
- 鉴权:采集令牌(
agent:ingestscope)+ IP 白名单 + 限速; - RAW 先落库:原始行进
agent_session_raw(去重键session_id + line_no), 解析失败也不丢原文; - 解析降级:能解析的写
agent_session/agent_turn(用户/助手/工具调用), 不能解析的保留 RAW 并计数; - 水位:
agent_ingest_log.last_line_no由服务端原子推进;客户端只有确认水位推进才继续下一批。 好处:断点续采、重启不重复、不丢消息。 - 心跳:摄取成功顺带上报 heartbeat,让"采集器还活着"可查。
DSH 会话只采微信与后台(cwd_slug 白名单/排除项),代码/终端会话不采,避免噪音与隐私。
回看与检索
- 后台会话列表(不含逐行正文,只看标题/轮数/时间),点进去按页取 turns;
SessionSearchService给 MCPsession_search提供"原话检索"(按关键词,带上下文窗口);AgentToolCallAuditService记录 DSH 调用的工具名/参数摘要/结果字节(不含正文);- 附件在 turn 上以
agent_turn_attachment关联。
聊天附件:私有存储 + 归属校验 + 物化
ChatAttachmentServiceImpl:
- 校验类型(第一期只接图片;扩展名 + 魔数)、大小上限;
- 计算 sha256,按
年/月/sha256.ext存到私有目录(COSMOS_CHAT_ATTACHMENT_DIR, 生产/opt/vite-cosmos/uploads/chat-files); - 写
chat_attachment(owner_type/owner_id、mime、size、storage_key、status); - 下载必须带归属会话(
owner_id)校验,响应头强制nosniff+inline; - 后台对话场景再物化到 DSH 工作目录;失败回滚记录与文件。
历史附件曾写在镜像内目录(随镜像更新丢失)—— deploy/scripts/migrate-chat-attachments.sh 已把旧目录迁到挂载卷;早期丢失的 1 个文件不可恢复,已在审查记录中标注。
保留策略
RawRetentionJob:agent_session_raw按天清理(默认 14 天,可配);LedgerRetentionJob:agent_tool_call_log+ai_egress_log按保留期(默认 180 天)分批清理, 删除 0 行也写日志;agent_turn保留默认永久(可配开关),审查记录里把它列为"积压可选清理"。
3.10 module_notify:通知投递与主动性预算
模块卡
| 项 | 内容 |
|---|---|
| 一句话 | 运维台:健康、清理、导入导出、版本回滚与 AI 能力看板。 |
| 用户功能 | 综合健康/数据库/日志查看;磁盘与日志清理;外链巡检;DSH 版本与回滚;Markdown/WordPress 导入;AI 域导出。 |
| 关键设计 | ① 清理前做引用反查,反查失败保守保留;② 导入默认草稿 + HTML 转义,绝不自动发布;③ 能力健康用「开关 + 产出物 + 日志」三看判据,避免把没运行当成健康。 |
| 职责 | 多通道通知投递(webhook→email→inapp 降级)、失败重试与业务回写、主动性账本与预算 |
| 入口 | 内部 SPI(NotifyService);无 HTTP 控制器(由扩展 effect 与业务调用) |
| 数据表 | notify_channel、notify_log、webhook_delivery、proactive_log |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | NotifyServiceImpl、WebhookNotifySender、EmailNotifySender、InappNotifySender、NotifyRetryJob、ProactiveBudgetServiceImpl |
| 失败形态 | 幂等抢占防重复;sent 只在通道自报成功时写;全失败记 failed 交给重试 |
投递模型(无 MQ 的现实约束)
- 幂等抢占:先插
notify_log(status=pending),dedup_key唯一索引兜底; 冲突即"同一条已投过",直接返回(宁可拒发也不重复轰炸)。 - 降级链:按
notify_channel.priority(小=优先)尝试可用通道: 微信(桥 webhook)→ 邮件(SMTP)→ 站内(inapp)。成功即sent并记录实际通道。 - 成功判据:通道自报成功才算 sent —— HTTP 2xx 且应答体没有业务错误码 (
WebhookNotifySender.detectBizError);否则记 failed,交NotifyRetryJob。 - 站内兜底:没有任何可用外部通道时降级 inapp;但"有通道却发失败"仍记 failed, 兜底不掩盖外部失败。
- 重试:失败按 retry<2 重投;重投成功通过
NotifyRetryLinkHandler回写业务表 (如提醒状态),避免"用户已收到、业务仍显示失败,再点重试又发一条"。 - 微信桥的附加保障:桥侧
/notify有 24 小时去重、发送重试 3 次、失败入待送队列, 并在/health暴露最近一次发送结果。
主动性预算账本
proactive_log 记录每条主动消息(晨报/晚报/关怀/线头/周复盘…)的去重键、结果、反馈。 ProactiveBudgetServiceImpl 提供幂等写入、日/月计数与反馈统计;真正的限额判定在扩展 handler 的 ProactiveSwitch/预算能力里(见 4.5),账本只负责"记过什么"。
3.11 module_ops:运维台、导入导出与 AI 看板
模块卡
| 项 | 内容 |
|---|---|
| 职责 | 健康自查、数据库观测、磁盘清理、版本/回滚、外链巡检、任务与审计日志、内容导入、AI 域导出、能力健康看板 |
| 入口 | /api/admin/system/ops(27 端点)、/api/admin/system/import、/api/admin/system/export、/api/admin/ops |
| 数据表 | 不拥有业务表(只读跨模块 + 系统日志表) |
实现细节(点开:类、状态机、表结构、失败边界)
| 项 | 内容 |
|---|---|
| 关键类 | OpsServiceImpl、CapabilityHealthService、AiOpsConsoleServiceImpl、ContentImportServiceImpl、AiDataExportServiceImpl、DashboardServiceImpl |
| 失败形态 | 清理有保底与引用反查;导入默认草稿;未知清理目标明确报错 |
健康与观测
/ops/health-report:DB 版本/连接、磁盘、Hindsight、桥、最近任务、备份新鲜度;/ops/db-info:表行数与体积(只读);/ops/logs:日志尾部(默认 200 行,限长);/ops/jobs:sys_job_log分页;/ops/jobs/{name}/run白名单触发任务;/ops/link-check:外链可用性巡检(并发 + 超时);/ops/version、/ops/rollback/status:版本与回滚就绪状态;/ops/cleanup:按目标清理 —— 孤儿文件(引用反查 fail-safe)、过期日志、过期备份、 审计/搜索/邮件/任务/访客日志(保留天数参数)。未知目标返回"未知清理目标",不静默成功;doctor.sh(宿主脚本)覆盖端口/挂载/令牌/备份/迁移/环回绑定等 25 项,发布后必跑。
AI 运维看板
CapabilityHealthService 用三看判据(开关 + 产出物时间戳 + 任务日志)给每个能力打状态: 只看任务日志不成立(多个 Job 在"开关关着/本周期已有产出/上一轮未结束"时故意不写日志); "判据为空 ≠ 通过"这条纪律就落在这里。AiOpsConsoleService 汇总用量/成本/预算/发现的问题 (findings:全局断网、最近一次 skipped、上游静默),全部只读。
内容导入(两个格式)
ContentImportServiceImpl:
| 格式 | 支持 | 关键点 |
|---|---|---|
| Markdown ZIP | Hexo/Leanote/Obsidian 等导出的 .md 集合(front-matter) | 单次 ≤500 篇、单篇 ≤2MB、ZIP ≤50MB;默认草稿;HTML 转义防 XSS;skipExisting 按标题幂等;识别导出包布局:有 articles/ 前缀时只导入该目录,notes/、README 等计为跳过(审查 #82) |
| WordPress WXR | content:encoded + wp:post_type=post | XML 解析限总量;HTML→Markdown 轻量转换(标题/段落/列表/链接/图片/代码/强调);XSS 转义 |
导入动作统一走 ArticleService.save,因此与手工发文一样有渲染、摘要、事件。
数据导出(带走自己的数据)
AiDataExportService/ExportAdminController:
- JSON:记忆、线头、洞察、画像、每日总结、课程/待办/提醒(程序可读);
- Markdown ZIP:文章(front-matter + 正文)、笔记、README;供备份/迁移;
- CSV/表格:用量等统计;
- 导出是只读动作,审计留痕由控制器负责。
失败与边界
- 清理:引用反查失败按"未知"保留;保留期可配;备份清理保留最新可恢复点;
- 导入:部分失败不阻塞其它文档,结果逐条说明;默认草稿,绝不自动发布;
- 看板:只读,不写业务表;能力健康判据在文档与响应里都解释清楚,避免"数字看起来正常"。