chatlab-convert

ChatLab 转换

在不修改源文件的前提下转换不受支持的本地导出数据。优先使用可复现的脚本和经过验证的 JSONL 结果，而不是一次性改写文件。

遵循用户要求的回复语言；否则使用对话语言，并在适用时保留用户使用的中文变体。保持命令、字段名、ID 和证据标记不变。

不可妥协的规则

• 将所有源文件保持为只读。将脚本、样本、解压文件和输出写入单独的工作目录；如用户指定了输出位置，则使用该位置。
• 将聊天数据保留在本地。不要上传数据、发送到网络服务，也不要将消息正文输出到模型可见的终端内容中。
• 先检查结构：键、列名、值类型、数量、时间戳格式和脱敏样本。在诊断输出中，将消息文本替换为其类型和长度。
• 绝不静默跳过格式错误或不受支持的源记录。应报告其源行号/索引并失败，或将其保留为消息类型 99，并明确统计映射数量。
• 未经批准，绝不安装软件包或系统工具。优先使用已安装的 Node.js/Python 标准库；仅用 shell 进行检查和编排。
• 除非用户明确要求导入，否则不要导入或修改 ChatLab 数据。在所有关卡通过后，“转换并导入”的请求即为充分授权。

工作流

1. 确认源文件和 CLI

根据请求和对话确定源文件；只有仍有歧义时才提问。每条命令都要引用路径。只检查一次可用能力，并在任务中复用检查结果。

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

如果试运行能识别源文件，则报告无需转换。只有在用户要求导入时才进行导入，并在可用时使用 chatlab-import，否则执行以下预览/写入步骤。

如果无法使用 clb validate，则继续使用 scripts/validate-chatlab.mjs，不要暂停转换并提议安装。打包的验证器需要 Node.js 22.19 或更高版本。较旧的 CLI 可能仍支持 formats 和导入试运行；使用其实际提供的能力。如果没有可用的 CLI，应说明无法检查原生格式支持和导入准备情况。

如果严格验证器都无法运行，则尽可能完成转换，并报告输出尚未验证。不要以目视检查替代严格验证。只有缺少运行时或 CLI 会阻碍用户要求的结果时，才请求安装授权。

2. 检查内容，不暴露数据

从文件元数据、编码、归档成员、JSON 键、CSV 标题、XML/HTML 元素名称或数据库表架构开始检查。不要运行 cat、不加限制的 head，也不要执行会打印原始消息列的 SQL 查询。

必须抽样查看值时，编写简短的本地检查器，仅输出：

• 字段名和值类型；
• 记录数和空值数；
• 时间戳和标识符格式；
• 脱敏文本，例如 <TEXT length=42>；
• 数量有限、结构各异的记录。

对于归档文件，将其解压到单独的工作目录，并拒绝任何会解压到该目录之外的条目。对于数据库，以只读方式打开。

3. 定义映射

编写转换器前，先阅读 references/chatlab-format.md 中的字段约定和选定的输出格式。记录源字段到 ChatLab 字段的映射，包括：

• 对话边界以及群聊/私聊类型；
• 稳定的成员身份和所有者身份；
• 时间戳单位和时区；
• 消息类型、内容、原始消息 ID 和回复关系；
• 源记录数，以及无法精确表示的记录。

只有当歧义会影响身份、对话边界、时间戳含义或所有权时才询问用户。不要猜测这些字段。

一个 ChatLab 文件仅代表一个对话。如果源文件包含多个对话，则每个对话分别生成一个输出文件，并使用可避免名称冲突的确定性命名；绝不要意外合并对话。

4. 编写确定性转换器

优先使用 JSONL。只有当导出数据规模较小、结构自然且能明确确保完整结果可安全地保存在内存中时，才使用 JSON。

选择已安装的 Node.js 或 Python 运行时中最简单且合适的一种；源格式不要求使用特定语言。

转换器必须：

• 将输入和输出路径作为参数接收，而不是写入本地路径；
• 保持源文件不变，并拒绝覆盖源文件；
• 将内容写入临时输出文件，仅在成功后重命名；
• 保留源数据顺序，或按时间戳加稳定的源序号排序；
• 保留源 ID；当 ID 缺失时，除非回复需要确定性 ID，否则省略可选的消息 ID；
• 根据稳定的身份字段确定性地生成缺失的成员 ID，不得使用随机值；
• 对大型文件逐条流式处理记录，并打印进度，但不输出消息正文；
• 在解析失败时以非零状态退出，并打印最终的源记录数、输出记录数和跳过记录数摘要。

将 skipped 默认为 0。将未知消息映射为类型 99 属于保留数据，不算跳过记录。

5. 验证小样本

对于大型文件或映射不确定的情况，先在本地运行有界样本转换。小型输入可以直接完整转换和验证。若 CLI 可用，请使用以下命令验证输出：

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

若 CLI 不可用，请找到包含此 SKILL.md 的目录，并使用附带的验证器：

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

修复所有验证错误后，再运行完整转换。检查警告并说明每条警告为何可以接受；不要自动忽略警告。

6. 转换并验证全部内容

运行完整转换，然后使用 CLI 或附带的验证器验证每个生成的文件。若 CLI 可用，还要运行导入试运行：

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/scripts/validate-chatlab.mjs" "/absolute/path/to/converted.jsonl"

明确区分以下结果级别：

• 格式已验证：CLI 或附带的严格验证器返回 ok: true；转换器和验证器的消息计数一致；源消息数等于输出消息数加上明确接受的跳过记录数；且未隐藏任何源解析错误。
• 导入已验证：格式验证已通过，且 clb import --dry-run --json 也返回 ok: true。

若 CLI 不可用，只报告“格式已验证”。告知用户之后可以安装 CLI 来运行试运行，或将结果拖入 ChatLab。不得声称导入验证已通过。

7. 仅在用户要求时导入

如果用户只要求转换，请在当前环境中完成所有可用的验证后停止。报告输出文件和脚本的路径、对话数、成员数、消息数、跳过记录数、警告、映射限制，以及实际达到的验证级别；不要引用消息内容。

如果用户明确要求导入，请对同一个已验证文件运行命令，但不带 --dry-run：

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

如果 CLI 仍不可用，请说明自动导入需要 chatlab-cli，建议安装，并在安装前征求用户许可。不得将“格式已验证”视为已导入。

对于多个输出文件，分别预览并导入。报告每个生成的会话 ID 和数量；不要删除转换器或转换后的文件。