[!info] related notes

• 所属 MOC：MemoFlow 项目 MOC
• 面试题：MemoFlow 项目面试题库
• 通用边界：Agent Runtime · Agent Decision Authority · 共享类型契约

MemoFlow 多端 AI 应用架构

架构主线

MemoFlow 不是“给 Todo 应用加一个聊天框”，而是把 AI 作为受控应用能力接入既有 Goal、Task、Routine、Notification 等业务域：

Web / Desktop UI
  ↓
统一 Use Case / AI Client Port
  ├─ Web：HTTP + SSE adapter
  └─ Desktop：Electron IPC adapter
  ↓
TypeScript / Mastra Runtime
  ↓
Proposal / Approval / Execution
  ↓
Domain Service / Repository
  ↓
PostgreSQL / PowerSync / Event / Trace

最重要的边界是：模型可以提出候选操作，但业务系统决定它是否有权执行、当前状态是否允许执行，以及怎样持久化。

为什么 Runtime 在 TypeScript 产品 API 内

MemoFlow 的核心业务域、共享 contract 和多端适配都以 TypeScript 为主。把 Agent Runtime 放进产品 API，可以减少跨语言 DTO 漂移，让 AI 用例直接复用领域服务、鉴权、事务和稳定错误模型。

这不是“所有 Agent 都应该做成 Node 单体”。当模型计算、专业 Python 生态或独立扩缩容成为主要约束时，独立 AI Service 仍然合理。BodySense 与 MemoFlow 的差异来自领域和运行边界，而不是框架偏好。

Proposal → Approval → Execution

模型生成 proposal
→ runtime schema parse
→ authorization / domain invariant / revision check
→ 用户或策略 approval
→ 生成幂等 execution command
→ domain service 执行
→ 持久化结果与 audit event

Zod 或结构化输出只保证形状；它不能证明用户有权限、目标对象仍存在、状态未变化、动作没有重复执行。

HTTP 与 IPC 的统一边界

统一的是用例语义和 domain result，不是底层 transport：

• Web adapter 处理 HTTP status、headers、SSE framing、网络断开；
• Desktop adapter 处理 IPC channel、preload 暴露、renderer 隔离和进程生命周期；
• 业务组件只依赖 port，不写 if (isElectron)；
• 两个 adapter 通过同一组 contract tests 验证输入、输出和稳定错误码。

因此 transport error 与 domain error 应分层：网络断开不是“任务不存在”，IPC channel failure 也不是业务校验失败。

Server State 与多端收敛

TanStack Query 管服务器拥有的数据：fetch、cache、stale、refetch、mutation、invalidation；局部 UI store 管客户端交互状态。不要把 query data 再复制一份到 Zustand/Pinia 形成双真值。

Desktop 离线同步或 PowerSync 负责本地数据可用性与同步，但不自动替代权限、业务命令和 AI Run 的 runtime state。多窗口最终仍要以服务端 revision / durable state 收敛。

并发 401 刷新

多个请求同时收到 401 时，应共享同一个 refresh Promise：

第一个 401 → 创建 refreshPromise
后续 401 → await 同一个 promise
刷新成功 → 各请求按原配置重试一次
刷新失败 → 清理会话并统一失败
finally → 清空共享 promise

这更准确地叫 refresh coalescing / singleflight。它只合并同一时刻的刷新工作，不等于通用互斥锁；还要排除 refresh 请求自身、限制重试次数，并处理多 tab / 多窗口协调。

可观测性与失败语义

• requestId 关联一次入口请求；
• traceId 关联跨服务/跨步骤的一条执行链；
• 稳定错误码给客户端做可预测分支；
• 内部 cause、stack、provider error 和 tool trace 只进入日志/trace；
• SSE 正常结束、取消、超时和失败都要落 durable terminal state，不能把“连接关了”当完成。

exact-SHA 发布

可靠发布链应把 commit、tag、manifest、镜像 digest、桌面产物和 release record 连接起来。latest 可以作为便利别名，不能作为不可变身份。

Release PR 负责版本与 changelog 的可审查变更；tag 触发正式构建；Draft Release 允许多个平台产物在发布前汇聚和核验；manifest 记录每个产物对应的源码和校验信息。

回答边界

本页描述稳定架构与设计意图。某一项是否已经 E3 闭环，必须以 MemoFlow 当前代码、测试、CI 和 release evidence 为准。