krisolo/boss

Fork 0

Files

kris 3cb4405b14 docs: add attachment storage and ai processing spec

2026-03-29 15:03:02 +08:00

16 KiB

Raw Permalink Blame History

Boss 聊天附件、双存储与 AI 处理设计

日期：2026-03-29

1. 背景

当前 Boss 原生 Android 客户端已经完成：

微信式 会话 / 设备 / 我的 一级交互
线程 = 聊天窗口
会话信息、独立群聊、微信式消息转发

但聊天主链仍缺少真实的附件协作能力：

聊天框还不能直接发送本机图片、视频、文件
接收端还不能收到可预览/可下载的附件消息
存储目前只有服务器本地文件路线，没有可切换的对象存储
AI 还不能基于聊天里的附件自动或手动分析内容

这次工作要把这四条链路一起打通：

原生聊天框发送本机图片、视频、文件
默认服务器文件存储 + 可选阿里 OSS 私有桶
Web 端做最简化的用户级存储配置
主 Agent 统一处理附件分析，并把结果回写到聊天中

2. 目标

本次设计完成后，系统应满足：

原生 Android 聊天框左侧提供单个 + 附件入口。
点击 + 后通过底部抽屉选择 图片 / 视频 / 文件。
图片、视频在发送前需要预览确认；文件直接发送。
默认使用服务器文件存储。
用户可在 Web 端 我的 > 附件与存储 中切换到 OSS。
OSS 当前只支持 阿里 OSS，并使用私有桶 + 签名 URL。
存储配置按当前登录用户保存，不做全局唯一配置。
接收端收到的附件消息不感知底层存储差异，都能统一预览/下载。
图片 / PDF / 文本默认自动交给主 Agent 处理。
视频 / Office / 大文件默认手动触发分析。
“大文件”阈值固定为 20 MB。
AI 处理结果以“简短回复 + 可继续查看的分析卡片”形式回到当前聊天。

3. 非目标

本次明确不做：

非阿里云的 OSS / S3 / COS 接入。
语音附件、录音、外部分享面板。
跨应用分享、系统分享菜单接入。
附件版本管理、回收站、批量迁移工具。
视频高级转码、视频在线播放 CDN 优化。
Office / 视频的深度结构化解析引擎。
多租户复杂权限模型。

4. 已确认的产品决策

4.1 原生聊天入口

聊天输入框左侧保留单个 +
点击后打开底部抽屉
抽屉内固定展示：
- 图片
- 视频
- 文件

4.2 发送前确认

图片：选中后先进入发送确认态
视频：选中后先进入发送确认态
文件：直接进入发送，不额外确认

4.3 Web 配置入口

配置入口固定放在 我的 > 附件与存储
不放在会话页，不藏在多层设置后面

4.4 OSS 最小配置项

阿里 OSS 最小配置字段固定为：

AccessKey ID
AccessKey Secret
Bucket
Endpoint
Region
目录前缀（可选，默认 boss/）

4.5 AI 处理策略

图片 / PDF / 文本：默认自动处理
视频 / Office / 大文件：默认手动触发
大文件阈值：20 MB
所有附件分析统一走主 Agent

4.6 AI 结果展示

分析结果返回当前聊天时，固定使用混合展示：

一条简短的主 Agent 回复
一张分析结果卡片

5. 总体架构

5.1 发送链

发送链拆成两步：

原生 APP 选择附件并上传
服务端创建附件消息

用户视角上，它们仍是一条连续动作。

上传成功后，服务端会在目标会话写入统一的“附件消息”，而不是单独写“上传请求消息”。

5.2 存储链

存储层统一抽象成 AttachmentStorageProvider，底层实现两种：

server_file
aliyun_oss

所有附件都通过同一套元数据模型进入消息系统，聊天页和 AI 处理链不直接感知底层存储类型。

5.3 AI 处理链

AI 处理与上传解耦：

上传完成后先落附件消息
再由服务端根据文件类型和大小决定是否自动排队给主 Agent
不自动处理的附件，显示为“可分析”，由用户手动触发

5.4 接收链

接收端收到的消息固定是统一附件消息：

可看到文件类型、名称、大小、状态
图片支持预览
视频支持预览/下载
PDF / 文本 / Office / 其他文件支持下载
可看到 AI 分析状态与结果

6. 存储设计

6.1 用户级配置模型

每个登录用户拥有独立的存储偏好：

type AttachmentStorageMode = "server_file" | "oss";
type OssProvider = "aliyun_oss";

interface UserAttachmentStorageConfig {
  account: string;
  mode: AttachmentStorageMode;
  ossProvider?: OssProvider;
  aliyunOss?: {
    enabled: boolean;
    accessKeyId: string;
    accessKeySecretEncrypted: string;
    bucket: string;
    endpoint: string;
    region: string;
    prefix?: string;
  };
  updatedAt: string;
  validatedAt?: string;
}

其中：

mode=server_file 时，不要求任何 OSS 字段
mode=oss 时，必须要求 ossProvider=aliyun_oss
prefix 默认值为 boss/

6.2 密钥存储策略

由于当前系统仍使用文件持久化，阿里 OSS 的 AccessKey Secret 不能明文直接写入 boss-state.json。

本次设计采用：

boss-state.json 中只保存加密后的 accessKeySecretEncrypted
服务器本地使用单独密钥对该字段做对称加密
该本地密钥不进入仓库，不通过客户端下发

推荐实现方式：

优先读取环境变量，如 BOSS_STORAGE_SECRET_KEY
如果不存在，则在服务器本地生成仅运行时可见的密钥文件并持久化到数据目录

6.3 默认服务器文件存储

默认存储后端为服务器本地文件。

建议目录结构：

data/uploads/<account>/<yyyy>/<mm>/<messageId>-<safeFileName>

优势：

符合当前“极轻云 + 本地设备端”路线
不引入额外云资源即可先跑通
与现有 boss-state.json 路线一致

6.4 阿里 OSS 存储

阿里 OSS 固定采用：

私有桶
临时签名 URL

服务端负责：

上传对象
生成对象 key
在下载或预览时生成短期签名 URL

对象 key 建议结构：

<prefix>/<account>/<yyyy>/<mm>/<messageId>-<safeFileName>

其中：

prefix 默认为 boss/
用户可在配置中改为其他目录前缀

6.5 统一下载入口

前台不直接拼 OSS URL，也不直接暴露本地文件路径。

统一下载/预览入口建议为：

GET /api/v1/attachments/[attachmentId]/download

该接口统一负责：

鉴权当前用户是否可访问对应会话
如果是 server_file：
- 流式返回文件
如果是 aliyun_oss：
- 生成短期签名 URL
- 302 跳转，或由服务端转发流式响应

这样可以保证：

客户端体验统一
存储切换不影响聊天 UI
不暴露底层凭证

7. 附件消息模型

7.1 新消息类型

现有消息类型只有文本和若干 intent 占位，不足以表达真实附件。

本次应扩展消息模型：

type MessageKind =
  | "text"
  | "voice_intent"
  | "image_intent"
  | "video_intent"
  | "forward_notice"
  | "forward_single"
  | "forward_bundle"
  | "attachment";

7.2 附件元数据

type AttachmentKind =
  | "image"
  | "video"
  | "pdf"
  | "text"
  | "office"
  | "binary";

type AttachmentStorageBackend = "server_file" | "aliyun_oss";

type AttachmentAnalysisState =
  | "not_applicable"
  | "queued_auto"
  | "ready_manual"
  | "processing"
  | "completed"
  | "failed";

interface MessageAttachment {
  attachmentId: string;
  fileName: string;
  mimeType: string;
  fileSizeBytes: number;
  attachmentKind: AttachmentKind;
  storageBackend: AttachmentStorageBackend;
  storagePath: string;
  previewAvailable: boolean;
  uploadedAt: string;
  uploadedBy: string;
  analysisState: AttachmentAnalysisState;
  analysisSummary?: string;
  analysisCardId?: string;
}

每条附件消息可以先只支持单附件，避免第一轮就把消息结构做成多附件复合体。后续若要支持一条消息多个附件，再扩展成数组。

7.3 附件消息结构

interface Message {
  id: string;
  sender: MessageSender;
  senderLabel: string;
  body: string;
  sentAt: string;
  kind?: MessageKind;
  attachment?: MessageAttachment;
  forwardSource?: ForwardSource;
  forwardBundle?: ForwardBundlePayload;
}

附件消息的 body 用作聊天摘要和兼容展示，例如：

图片：已发送图片：车间异常截图.png
视频：已发送视频：工位巡检录像.mp4
文件：已发送文件：北区回归报告.pdf

8. AI 分析模型

8.1 分析任务

附件分析统一走主 Agent，不让单个普通线程自行处理。

建议新增任务模型：

type MasterAgentTaskType =
  | "chat_reply"
  | "attachment_analysis";

interface AttachmentAnalysisTaskPayload {
  projectId: string;
  messageId: string;
  attachmentId: string;
  fileName: string;
  mimeType: string;
  attachmentKind: AttachmentKind;
  fileSizeBytes: number;
  downloadUrl: string;
  triggerMode: "auto" | "manual";
}

8.2 自动 / 手动分析规则

自动进入主 Agent 的条件：

attachmentKind=image
attachmentKind=pdf
attachmentKind=text
文件大小 <= 20 MB

手动触发的条件：

attachmentKind=video
attachmentKind=office
文件大小 > 20 MB

8.3 AI 处理执行者

统一执行者为主 Agent：

优先走 Master Codex Node
只有在容灾路径明确支持时，才考虑 openai_api

在能力未覆盖的情况下，应返回明确状态，不要假装已完成分析。

8.4 分析结果回写

分析结果固定回写到当前聊天会话中，形式为：

一条简短主 Agent 回复
一张分析结果卡片

简短回复示例：

主 Agent：已分析《北区回归报告.pdf》。核心问题是登录态恢复链和 OTA 覆盖安装文档不一致。

分析卡片中至少应包含：

分析对象文件名
分析模式（自动 / 手动）
核心结论摘要
关键提取点列表
分析完成时间

9. API 设计

9.1 Web 配置接口

新增用户级附件存储配置接口：

GET /api/v1/storage/config
PATCH /api/v1/storage/config
POST /api/v1/storage/config/validate

语义：

GET：获取当前用户的附件与存储配置
PATCH：更新当前用户配置
validate：校验阿里 OSS 是否配置可用

validate 至少检查：

AK/SK 是否能通过认证
Bucket 是否存在
Endpoint / Region 是否匹配
是否具备读写权限

9.2 附件上传接口

新增统一附件上传接口：

POST /api/v1/projects/[projectId]/attachments

建议使用 multipart/form-data，字段至少包括：

file
sourceType: image | video | file

该接口负责：

鉴权
解析文件类型
读取当前用户存储配置
上传到对应后端
生成附件消息
决定是否自动创建主 Agent 分析任务

返回值应直接带回新创建的消息和分析状态。

9.3 手动分析接口

新增：

POST /api/v1/projects/[projectId]/attachments/[attachmentId]/analyze

用途：

对 ready_manual 的附件手动触发 AI 分析

9.4 统一下载接口

新增：

GET /api/v1/attachments/[attachmentId]/download

用途：

图片预览
视频预览或下载
文件下载

9.5 SSE 刷新

现有 /api/v1/events 继续承担刷新出口，需要增加这些事件：

attachment.uploaded
attachment.analysis.queued
attachment.analysis.updated
attachment.analysis.completed
attachment.analysis.failed

10. 原生 Android 设计

10.1 聊天输入区

聊天输入区固定为：

左侧 +
中间输入框
右侧发送按钮

点击 + 后弹出底部抽屉，包含：

图片
视频
文件

10.2 系统文件选择

原生 Android 需要新增：

图片选择器
视频选择器
文件选择器

建议基于 ActivityResultContracts.OpenDocument / GetContent 实现。

10.3 发送前确认

图片：展示预览 + 取消 / 发送
视频：展示预览或文件摘要 + 取消 / 发送
文件：直接进入上传

10.4 聊天中的附件渲染

图片消息：

缩略图
文件名
大小
分析状态

视频消息：

缩略图或占位封面
文件名
大小
分析状态

文件消息：

文件图标
文件名
类型
大小
下载/查看动作
分析状态

10.5 分析状态呈现

附件卡片需能表示：

queued_auto：自动分析排队中
ready_manual：可分析
processing：分析中
completed：分析完成
failed：分析失败，可重试

11. Web 配置页设计

11.1 入口

入口固定为：

我的 > 附件与存储

11.2 页面结构

第一页只做两层：

存储方式选择
- 服务器文件存储（默认）
- OSS
如果选 OSS
- 供应商选择：当前只显示 阿里 OSS
- 展开最小配置表单

11.3 表单交互

表单交互应尽可能简化：

AccessKey ID
AccessKey Secret
Bucket
Endpoint
Region
目录前缀（可选）

按钮建议只有两个：

测试并保存
切回服务器文件存储

不做额外的高级设置入口作为第一屏主内容。

12. 与主 Agent 的关系

主 Agent 不再只处理文本请求，也需要能理解附件分析任务。

这次要求主 Agent：

收到附件任务时，知道当前附件来自哪个会话、哪条消息
能通过统一下载 URL 获取附件
对图片 / PDF / 文本自动分析
对手动模式附件在用户触发后再分析
把结果回写为：
- 一条简短消息
- 一张分析卡片

如果主 Agent 当前无法处理某类附件，应明确返回失败原因，而不是静默成功。

13. 错误处理

至少覆盖以下错误：

用户未配置 OSS，但切换到了 OSS
OSS 配置无效
Bucket 无权限
上传中断
本地文件 URI 无法读取
附件消息已创建但自动分析排队失败
分析任务执行失败
下载 URL 失效
原文件已被删除或不可用

错误处理原则：

上传失败：不创建成功消息，前台保留失败提示
上传成功、分析失败：保留附件消息，但把分析状态标为 failed
下载失败：允许用户重试，不直接删除消息

14. 测试与验收

14.1 Web / 服务端

至少验证：

默认服务器文件存储上传成功
阿里 OSS 上传成功
用户级配置切换生效
未配置 OSS 时不能误走 OSS
图片 / PDF / 文本能自动排队分析
视频 / Office / 大文件默认进入手动分析
下载接口能正确返回本地文件或 OSS 签名 URL

14.2 原生 Android