chatlab-convert-cn

name	chatlab-convert-cn
description	将 ChatLab 暂不支持的本地聊天导出转换为经过验证的 ChatLab JSONL 或 JSON：分析源文件结构，编写并运行本地 Node.js 或 Python 转换脚本，并在导入前核对记录数量。当 ChatLab 无法识别 CSV、HTML、TXT、XML、SQLite/数据库、厂商自定义 JSON/JSONL、压缩包等聊天导出，或用户要求 Agent 适配未知聊天格式时使用。

ChatLab 聊天转换

在不修改源文件的前提下转换暂不支持的聊天导出。优先交付可复用的转换脚本和经过验证的 JSONL，而不是一次性改写文件。

安装命令：

npx skills add ChatLab/ChatLab --skill chatlab-convert-cn -g

不可省略的规则

• 始终以只读方式处理源文件。脚本、样本、解压文件和输出都写入独立的同级目录。
• 聊天数据只留在本机。不要上传到网络服务，也不要在 AI 可见的终端输出中打印消息正文。
• 先检查结构：字段名、列名、值类型、数量、时间戳形态和脱敏样本。诊断输出中的消息正文替换为类型和长度。
• 绝不静默跳过损坏或不支持的源记录。应携带源行号/索引失败，或保留为消息类型 99 并明确统计映射数量。
• 未经允许不要安装依赖或系统工具。优先使用已有 Node.js/Python 标准库；Shell 只用于检查和编排。
• 用户没有明确要求导入时，不要写入 ChatLab。用户明确说“转换并导入”，则所有门禁通过后无需二次确认。

工作流程

1. 确认源文件和 CLI

确认唯一、准确的源路径。存在多个候选文件时询问用户，不要猜测。每条命令都要给路径加引号。

clb --help
clb validate --help
clb formats
clb import "/absolute/path/to/source" --dry-run --json

如果 dry-run 已经识别源文件，不要重复转换，改用 chatlab-import-cn 完成导入。

如果 clb 不存在，或已有版本没有 validate 命令：

1. 告诉用户未检测到可用的 ChatLab CLI，但仍可使用本 Skill 内置的严格验证器继续转换；
2. 建议安装或更新 CLI，并在执行前征得用户同意：npm install -g chatlab-cli@latest；
3. 用户跳过安装、安装失败或当前无法联网时，不要阻断转换，改用 scripts/validate-chatlab.mjs；
4. 跳过 clb formats 和源文件 dry-run，并明确说明无法确认 ChatLab 是否已原生支持该源格式。

内置验证器需要 Node.js 22.19 或更高版本。如果 node --version 也不可用，可以继续编写转换器，但必须把结果标记为“尚未验证”，并引导用户安装 Node.js 和 chatlab-cli；未经同意不要自行安装。

不能用肉眼检查替代 CLI 或内置严格验证器。

2. 在不暴露正文的前提下检查结构

先检查文件元信息、编码、压缩包目录、JSON 字段、CSV 表头、XML/HTML 元素名或数据库表结构。不要运行会打印原始消息列的 cat、无限制 head 或 SQL 查询。

确实需要样本值时，编写一个简短的本地检查脚本，只输出：

• 字段名和数据类型；
• 记录数和空值数；
• 时间戳与标识符形态；
• <TEXT length=42> 这样的正文掩码；
• 少量结构不同的记录。

压缩包要解压到独立工作目录，并拒绝逃逸该目录的条目。数据库必须只读打开。

3. 确定字段映射

编写转换器前，完整阅读 references/chatlab-format.md。记录源字段到 ChatLab 字段的映射，包括：

• 会话边界以及群聊/私聊类型；
• 稳定的成员身份和本人身份；
• 时间戳单位与时区；
• 消息类型、正文、原始消息 ID 和回复关系；
• 源记录总数，以及无法完全表达的记录。

只有当歧义会改变身份、会话边界、时间含义或本人归属时才询问用户；这些字段不能猜测。

一个 ChatLab 文件只能表示一个会话。如果源文件包含多个会话，要使用防冲突且确定性的文件名分别输出，绝不能误合并。

4. 编写确定性的转换器

默认输出 JSONL。只有源文件较小、天然结构化，并且可以明确安全地放入内存时才使用 JSON。

选择当前已安装且最简单的运行时：

• JSON、JSONL、HTML 和 JavaScript 风格数据优先使用 Node.js；
• CSV、SQLite、XML、编码复杂的文本和表格数据优先使用 Python；
• Shell 只负责发现文件和组合命令。

转换器必须：

• 通过参数接收输入、输出路径，不写死本机路径；
• 保持源文件不变，并拒绝覆盖源文件；
• 先写临时输出，成功后再重命名；
• 保留源顺序，或按时间戳加稳定的源序号排序；
• 优先保留源 ID；没有消息 ID 时省略可选字段，只有回复关联需要时才生成确定性 ID；
• 缺少成员 ID 时根据稳定身份字段确定性生成，绝不能使用随机值；
• 大文件流式处理，进度输出不得包含消息正文；
• 解析失败时以非零状态退出，并输出源记录数、输出数和跳过数汇总。

skipped 默认为零。把未知消息映射为类型 99 属于保留，不计为跳过。

5. 先证明小样本

先对受限的本地样本或脚本的 sample 模式运行转换器，然后验证。有 CLI 时运行：

clb validate "/absolute/path/to/sample.jsonl" --json

没有 CLI 时，定位本 SKILL.md 所在目录，并使用随 Skill 分发的验证器：

node "/absolute/path/to/chatlab-convert-cn/scripts/validate-chatlab.mjs" "/absolute/path/to/sample.jsonl"

修复全部 error 后才能全量转换。逐项检查 warning 并说明为什么可以接受，不能自动忽略。

6. 全量转换并双重验证

运行完整转换，然后使用 CLI 或内置验证器验证每一个输出文件。有 CLI 时继续执行导入 dry-run：

clb validate "/absolute/path/to/converted.jsonl" --json
clb import "/absolute/path/to/converted.jsonl" --dry-run --json

没有 CLI 时运行：

node "/absolute/path/to/chatlab-convert-cn/scripts/validate-chatlab.mjs" "/absolute/path/to/converted.jsonl"

按验证能力区分结果，不能混用结论：

• 格式验证通过：CLI 或内置严格验证器返回 ok: true，转换器输出消息数等于验证器消息数，源消息数等于输出消息数加上用户明确接受的跳过数，且没有隐藏源解析错误；
• 导入验证通过：在格式验证通过的基础上，clb import --dry-run --json 也返回 ok: true。

没有 CLI 时只能报告“格式验证通过”，并提醒用户之后可以安装 CLI 完成 dry-run，或将结果文件拖入 ChatLab；不能声称已经通过导入验证。

只有同时满足以下条件，才能认为转换结果已经通过完整导入验证：

• 严格验证返回 ok: true；
• 导入 dry-run 返回 ok: true；
• 转换器输出消息数等于验证器消息数；
• 源消息数等于输出消息数加上用户明确接受的跳过数；
• 没有隐藏任何源解析错误。

7. 仅在用户要求时导入

如果用户只要求转换，在当前环境可完成的验证后停止。报告输出路径、脚本路径、会话数、成员数、消息数、跳过数、警告、映射限制和实际达到的验证级别，不要引用消息正文。

如果用户明确要求导入，使用同一个已验证文件移除 --dry-run：

clb import "/absolute/path/to/converted.jsonl" --json

如果此时仍没有 CLI，说明自动导入需要 chatlab-cli，建议安装并征得用户同意；不能把“格式验证通过”当成已经导入。

存在多个输出时，逐个预览并独立导入。报告每个结果的会话 ID 和数量；不要删除转换脚本或转换结果。