PotatoChat

595. PotatoChat聊天记录导出格式

作者：

user

在

你是想要一个“PotatoChat 聊天记录导出格式”的规范说明吗？我先给一个清晰、可直接实现的建议格式（兼顾可读性、可索引性与附件处理），并附上示例与实现/安全注意事项。若需要我也可以把它转成 JSON Schema、示例导出文件或生成导出/导入的代码片段（Python/Node.js）。

595. PotatoChat聊天记录导出格式

概览（PotatoChat Export Format v1.0）

  • 包装：单个 ZIP 包含一个主 JSON 元数据+消息文件（export.json）和一个 attachments/ 子目录（可选）。
  • 可选压缩：可直接以 JSON 文件导出（小会话）或 ZIP（含附件）。
  • 字符编码：UTF-8。
  • 时间戳：ISO 8601 带时区（例如 2026-03-03T12:34:56Z）。
  • 版本：在 export.json 中包含 format_version 字段，便于以后兼容。

export.json（顶层结构，示例字段）
{
"format_version": "1.0",
"exported_at": "2026-03-03T12:34:56Z",
"exported_by": {
"app_name": "PotatoChat",
"app_version": "2.5.1",
"user_id": "user_12345"
},
"conversation": {
"id": "conv_98765",
"type": "group", // "direct" 或 "group" 或 "channel"
"title": "项目讨论组",
"created_at": "2025-10-01T08:00:00Z",
"participants": [
{"id":"user_12345","display_name":"张三","role":"owner"},
{"id":"user_67890","display_name":"李四","role":"member"},
{"id":"bot_1","display_name":"翻译机器人","role":"bot"}
]
},
"messages": [
{
"message_id":"msg_0001",
"parent_id": null, // 用于线程/回复
"timestamp":"2026-03-01T09:00:00Z",
"sender_id":"user_12345",
"sender_display_name":"张三",
"type":"text", // text,image,file,sticker,voice,system
"content":"大家早上好，今天会议几点？",
"mentions":["user_67890"],
"reactions":[
{"emoji":"👍","user_ids":["user_67890"],"count":1}
],
"edited": false,
"deleted": false,
"pinned": false
},
{
"message_id":"msg_0002",
"parent_id":"msg_0001",
"timestamp":"2026-03-01T09:01:10Z",
"sender_id":"user_67890",
"sender_display_name":"李四",
"type":"image",
"content":"照片：会议室.png",
"attachments":[
{
"attachment_id":"att_100",
"filename":"meeting_room.png",
"mime":"image/png",
"size":345678,
"path":"attachments/att_100_meeting_room.png" // 或 "url" 字段
}
],
"edited": false,
"deleted": false
}
],
"attachments_index":[
{"attachment_id":"att_100","checksum":"sha256:…","path":"attachments/att_100_meeting_room.png"}
],
"metadata":{
"message_count":2,
"attachment_count":1
},
"encryption": {
"encrypted": false
}
}

字段说明（要点）

  • format_version：格式版本号，便于未来演进。
  • exported_at：导出时间（ISO 8601）。
  • exported_by：导出者/应用信息（用于审计）。
  • conversation：会话基本信息与参与者列表（每个参与者最少 id 与显示名）。
  • messages：按时间顺序（或索引顺序）列出的消息数组。每条消息至少包含：
    • message_id：全局唯一字符串（建议 UUID）。
    • parent_id：若为回复/线程消息则指向父消息 id，否则 null。
    • timestamp：ISO 8601。
    • sender_id / sender_display_name：发送者信息（冗余用于脱离系统查看）。
    • type：消息类型（text,image,file,sticker,voice,system 等）。
    • content：文本内容或简短描述（对非文本类型可放文件名或说明）。
    • attachments：可选数组，包含 attachment_id、filename、mime、size、path（指向 ZIP 内附件）或外部 url。
    • mentions：被提及的用户 id 列表。
    • reactions：数组，每项包含 emoji、user_ids（可选）及 count。
    • edited：boolean，标记是否编辑过（可额外提供 edits 历史）。
    • deleted：boolean（保留删除痕迹或直接物理删除，根据策略）。
    • pinned：boolean。
  • attachments_index：集中列出所有附件的校验与路径，便于完整性校验。
  • encryption：说明导出是否加密及加密方案/元数据（如果输出为加密文件必须注明）。
  • metadata：统计信息（可选）。

附件处理

  • 推荐把二进制附件放到 ZIP 的 attachments/ 目录，export.json 中用相对路径引用。
  • 文件名与 path 中避免特殊字符；附件名建议加入 attachment_id 前缀以避免冲突。
  • 提供 checksum（例如 sha256）和 size，便于完整性校验。
  • 如果附件存放外部 URL，需要同时保留 checksum 与 fetch_method 字段，注明是否需要认证。

CSV/纯文本导出（若需要简洁表格）

  • 一条消息一行，字段例如：
    message_id,timestamp,sender_id,sender_name,type,content,attachment_refs,edited,deleted,reactions
  • 注意 CSV 对换行和逗号的转义；对于长文本与表情推荐使用 JSON 导出。

版本与向后兼容

  • format_version 必须保留，新增字段应使用非破坏性方式（可选字段）。
  • 若删除敏感字段，需在文档中记录迁移策略。

隐私与法律/安全建议

  • 导出前应提示用户导出数据可能包含他人私密信息，并获得必要同意。
  • 对含敏感内容或大规模导出，建议提供加密选项（例如 AES-256 + 密钥派生），并在 export.json 中包含加密元数据（但不要把密钥写入导出文件）。
  • 限制导出频率与授权，防止滥用。
  • 对个人数据（例如电话号码、邮箱）如果不必要，可提供“脱敏导出”选项（把这些字段模糊化）。

文件命名建议

  • PotatoChat_export_<conversationId|title>_.zip
  • 例如：PotatoChat_export_conv_98765_20260303T123456.zip

示例用途

  • 备份/迁移到其他客户端、审计、离线查看、导入到数据库、用于法律合规备份。

如果你需要我做以下任意一项，请告诉我：

  • 输出完整 JSON Schema（可用于校验）；
  • 给出 Python / Node.js 导出示例代码（包含 ZIP 打包与附件引用）；
  • 给出一个实际导出小会话的完整示例（JSON + 附件清单）；
  • 或者说明某个现有 PotatoChat 客户端的导出格式（如果你有该客户端的具体要求或示例）。

更多文章