主题
Session、Memory、文件与生成物数据流方案
1. 方案摘要
本方案把会话上下文、长期记忆、Agent workspace、Session files 和生成物分成不同数据域，并通过统一文件服务交付。核心原则是：Session 文件属于会话，workspace 属于 Agent，生成物属于任务结果；任何路径访问都必须经过租户、会话和 realpath 边界校验。
2. 设计目标与非目标
设计目标
- 建立会话、记忆、工作区和生成物的清晰归属。
- 保证文件访问隔离、可分享、可归档和可恢复。
- 让本地文件系统和对象存储实现可替换。
非目标
- 不把 Agent workspace 当成任意会话文件目录。
- 不在文件服务中承载业务权限判断之外的 Agent 逻辑。
- 不要求所有生成物都永久保存。
3. 架构范围与视图
会话状态、长期记忆、工作区文件和生成物分别由谁管理并存储在哪里？
本图展示数据归属与读写关系，不展开数据库表字段和具体渲染器实现。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| Chat / Task | 数据库中的用户可见会话状态、任务状态、owner 和 SDK session id。 |
| SessionService | 控制同一会话执行、取消、暂停、继续和释放。 |
| MemoryService | 读取和写入按租户、用户与 Agent 组织的长期记忆。 |
| Agent workspace | 保存运行规则、技能链接和当前 Agent 工作文件。 |
| Session files | 会话附件与运行产物的统一读取、下载、分享和归档恢复入口。 |
| Artifacts | 文件、Widget、发布页面、分享页面和右侧面板展示。 |
| MyFS | 在本地文件系统或 S3 兼容对象存储之间提供统一接口。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- PromptComposer 只组合授权范围内的 Memory、workspace 和 Session files。
- MyFS 统一处理路径解析、权限检查、读写、归档和对象存储适配。
- Widget、分享页和发布页引用生成物标识，不直接暴露物理路径。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 任务读取 Chat 与 Session 上下文
- PromptComposer 组合 Memory 和工作区信息
- Agent 使用 workspace 与 session files
- 生成文件或 Widget
- 文件服务执行权限和路径校验
- 终态归档并由 UI / Channel 交付
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- Chat/Task/Session 元数据以数据库为准，文件内容以文件服务存储为准。
- 生成物写入完成后再发布可见事件，避免用户看到未完成文件。
- 归档恢复同时恢复元数据引用和文件对象，不能只恢复路径字符串。
当前专题的关键约束
- Session 文件读取不回退到任意 Agent workspace 路径。
- 文件定位必须执行租户、Session 和 realpath 边界校验。
- 生产共享文件不能依赖单 Pod 本地目录。
8. 异常、恢复与安全边界
- realpath、租户或 Session 校验失败时拒绝访问。
- 对象存储上传中断时保留失败状态，不发布可下载链接。
- 文件清理采用引用确认，避免删除仍被 Session 或分享页使用的对象。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 单机可使用本地文件系统，生产多副本应使用共享或对象存储。
- 文件服务可独立扩展，但必须保持统一权限和对象标识语义。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- 统一 Session 文件 API、分享与归档恢复
- Memory、workspace、Widget 与发布页面
规划或待完善
- 本专题暂未列出独立规划项。
演进方向
- 增加大文件分片、病毒扫描、生命周期策略和内容寻址。
- 把 Widget、分享和发布结果统一到可追踪的 artifact manifest。
11. 方案验收要点
- 跨租户、跨 Session 和路径穿越访问均被拒绝。
- 任务恢复后能找到原有 Session files 和生成物。
- 不同存储后端对上层暴露相同的文件服务契约。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。