简体中文 · English · 日本語 · Deutsch · Русский · 繁體中文
把 TRAE 会话完整带到 OpenCode。
自动导出、脱敏、映射与导入，并在写入后逐项回读核验。
项目网站 · 快速开始 · 操作手册 · 兼容性 · 故障排查 · 更新记录
Important
首次使用请先阅读操作手册。macOS 必须从终端以调试参数启动 TRAE，否则工具无法读取完整消息正文。
打开目标会话所在的 TRAE 项目窗口，然后在仓库根目录运行：
npm run migrate:local按编号选择窗口和一个或多个会话即可。工具不会要求手动输入 workbench ID 或 session ID， 中断后也可以基于已生成的迁移记录安全续跑。
| 交互式选择 | 安全处理 | 双协议适配 | 写入后验证 |
|---|---|---|---|
| 自动发现项目窗口与会话 | 凭据识别、脱敏与覆盖保护 | OpenCode v1 / v2 自动识别 | 消息、推理、工具记录与 Hash 对账 |
flowchart LR
A["TRAE 会话<br>只读提取"] --> B["导出与脱敏<br>Migration Bundle"]
B --> C["协议映射<br>OpenCode v1 / v2"]
C --> D["原生导入"]
D --> E["回读核验<br>内容与 Hash 对账"]
| 组件 | 要求 |
|---|---|
| TRAE 来源 | TRAE CN 3.3.104，已登录，并以本机 CDP 端口 9222 启动 |
| OpenCode v2 目标 | 已验证基线：2.0.0（legacy）、2.0.12、2.0.16；其他稳定 2.x 自动检测兼容性 |
| OpenCode v1 目标 | 已验证基线：1.16.0 / 1.17.0（legacy）、1.17.9 / 1.18.32；其他稳定 1.x 自动检测兼容性 |
| 系统 | macOS、Windows 可直接读取本机 TRAE；Linux 只支持导入已导出的 bundle |
| Node.js | >=18.18，推荐 Node.js 22 |
附件、Skill 与 MCP 资源不在当前迁移范围内。未知的 TRAE 来源版本仍会被拒绝。
OpenCode 根据实际协议 profile 和隔离往返结果决定能否迁移。v2 自动区分旧版与当前
HTTP SessionTransfer 路径；v1 自动区分 legacy 与当前会话 schema，均通过
opencode import / opencode export 子命令。
Note
未收录的 OpenCode 稳定版本不会仅因版本号被拒绝。CLI 与目标服务必须为同一版本， 必要路由和 schema 必须完全匹配或仅有安全增量；工具还会在独立临时库中验证导入、 导出、回读、冲突与删除保护，通过后才允许迁移。
Warning
预发布版本、未知主版本、破坏性 schema 变化或行为验证失败仍会停止。
opencode-ai@1.15.x 无法保留安全所有权 metadata，1.14.x 的 OpenAPI 不暴露完整会话
schema，因此同样拒绝写入；工具不会直写旧版数据库。
本项目尚未发布到 npm。克隆仓库后，进入仓库根目录安装依赖：
git clone https://github.com/yororoA/Trae2OpenCode.git
cd Trae2OpenCode
npm ci确认本地环境可用：
node --version
npm run checkv2：
npm install -g @opencode/cli@2.0.16
opencode --versionv1（若本机本来就在用 OpenCode 1.x，通常已随它安装）：
npm install -g opencode-ai@1.18.32
opencode --version建议新安装使用上述当前基线；已有 2.0.0 或 1.16/早期 1.17 环境无需为了迁移强制升级，
工具会选择 legacy profile。其他稳定 1.x/2.x 会在迁移前自动检测兼容性。
也可运行 npm run verify:opencode 单独检查本机 OpenCode，命令复用相同协议规则和
隔离往返验证，支持 --binary、--output 与 --json；详见独立验证说明。
migrate:local 会读取
OpenCode 当前 service descriptor 发现动态端口，并检查本机 http://127.0.0.1:4096。没有可用
服务时会临时启动仅监听本机的 4097 进程，沿用当前本地 OpenCode 会话库，迁移结束后只关闭
该临时进程。因此通常不需要手动启动 OpenCode server。
Windows 上 npm 只会生成 .cmd / .ps1 垫片，Node 无法直接执行它们，因此工具会自动解析
垫片里指向的原生 opencode.exe；解析失败时可用 T2O_OPENCODE_BINARY 或 --binary 指定。
正在运行的未收录版本会先接受协议检测。若本机 CLI 版本与它不同，请安装同版本 CLI，
或用 T2O_OPENCODE_BINARY 指定同版本可执行文件。隔离验证使用独立临时数据库，
不会另启进程并发访问用户会话库。2.0.16 桌面端可直接作为迁移目标。
保存工作并完全退出 TRAE，再从终端启动。macOS 示例：
"/Applications/Trae CN.app/Contents/MacOS/Electron" \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222不要使用 open -a ... --args：当前 TRAE 版本可能忽略其中的调试参数。
启动后登录 TRAE，打开包含目标会话的项目窗口，并确认能在历史面板看到这些会话。
Windows PowerShell 示例：
& "$env:LOCALAPPDATA\Programs\Trae CN\Trae CN.exe" `
--remote-debugging-address=127.0.0.1 `
--remote-debugging-port=9222如果 TRAE 安装在其他目录，请替换上面的可执行文件路径。
在仓库根目录运行：
npm run migrate:local需要预先决定覆盖策略时，可以直接使用：
npm run migrate:local -y # 自动确认 OVERWRITE
npm run migrate:local -n # 自动跳过需要 OVERWRITE 的会话这两个参数只控制覆盖策略，workbench 和会话仍通过列表选择。不带参数时，程序继续要求
手动输入 OVERWRITE。
程序会显示可用的 TRAE 窗口和该窗口所属项目的会话。会话支持单选、逗号分隔、 连续范围或全部选择：
发现多个 TRAE workbench，请选择：
1. Trae2OpenCode
2. another-project
请输入 workbench 编号：1
请选择要迁移的 TRAE 会话（支持多选）：
1. 修复迁移流程 · complete · 2026/09/24 15:30:00
2. 阅读 README · partial · 2026/09/24 14:20:00
3. 发布检查 · complete · 2026/09/24 13:10:00
请输入编号（如 1,3-5；输入 all 全选）：1,3
随后工具依次完成：
- 为每个所选会话创建独立 bundle 和 manifest。
- 自动剥离正文、标题和工具 payload 中已识别的凭据。
- 在真正写入前检查迁移完整性和 OpenCode 兼容性。
- 逐个导入到 OpenCode，并回读消息、reasoning、工具记录和 hash；单个失败不阻止后续会话。
- 成功后保留最新迁移记录，清理同一会话已被替代的旧终态记录。
如果目标中已存在同一来源会话，并且本地保留着本工具上次成功迁移的 manifest，程序会
提示输入 OVERWRITE。确认后先校验旧会话未被修改，再安全覆盖；外来会话、已修改会话
或缺少可信 manifest 的目标不会被删除。使用 -y 会自动完成该确认；使用 -n 会跳过
需要覆盖的会话，并继续迁移本次选择中无需覆盖的其他会话。
OpenCode 服务重启后动态端口可能改变。已有 manifest 至少包含一个成功会话时，工具会 同时核验目标版本、schema、迁移所有权、完整性快照和整条内容 hash；全部证据匹配后才会 把 manifest 安全绑定到新端口。尚无成功会话或目标内容发生变化时仍会停止。
成功时终端会显示以下之一：
本次结果：已新建会话并通过回读校验。迁移记录：.../migration-run/session-.../
本次结果：当前 manifest 已完成并通过回读校验；未启动新的 OVERWRITE。
本次结果：已执行 OVERWRITE，旧目标已安全替换，当前版本通过回读校验。
然后在 OpenCode 中打开对应项目，检查会话标题、消息数量和最近一轮内容。迁移完成不代表 TRAE 本身的历史被删除，源数据始终保持只读。
完整的逐步说明、失败处理、续跑和回滚见 操作手册。
- 必须打开目标会话所属项目的 TRAE workbench。窗口可在后台或最小化，但不能关闭； 完整消息正文由该窗口的 renderer 提供。空白新窗口没有项目上下文，不能用于迁移。
- 同一个 workbench 中会列出该项目的全部本地会话，不限于当前前台会话。关闭的项目窗口 对应会话当前只能发现部分元数据，不能安全迁移完整内容。
- 单个 bundle 最大为
1 GiB，其中单会话 runtime/transfer 最大为384 MiB。 Bundle 读写和哈希采用流式处理；接近上限时仍需为映射与回读对象预留足够内存。 - 发现可安全定位的凭据会替换为
[REDACTED_SECRET]，会话标记为partial； 若凭据位于 ID、路径或来源定位等不可安全改写字段，迁移会停止。 - assistant 在任务执行期间已持久化的进度描述会按原顺序映射为 OpenCode 原生
reasoning part，与命令工具共同显示在可折叠的任务过程中；最终输出保持为普通正文，
不再插入 Markdown 分隔线。私有
reasoning_content仍保持独立的 reasoning part。 - TRAE 的
exec_command会映射为 OpenCode 原生 shell 工具，可展开查看具体命令和 已持久化的终端输出；原始工具字段仍保存在 metadata 中。 - 迁移消息使用与 OpenCode 时间线兼容的稳定递增 ID，因此迁移后继续对话、撤销和 重做不会让当前窗口丢失历史。超大历史会自动加入少量原生 compaction checkpoint； 完整旧消息仍可查看；v2 checkpoint 的角色化摘录只写入隐藏上下文，不会重复显示为正文。
- 目标是 OpenCode 1.x 时没有 carry-summary 的 compaction 消息：超大历史按原样导入，
需要长对话时请在 1.x 内使用它自己的 summarize。v1 也不保存消息级 metadata，
逐事件来源改存于会话级
metadata.trae2opencode.events。 - v1 要求逐块的 reasoning 时间，而 TRAE 只持久化工具时间；此时使用所属 assistant 轮次
已记录的时间并输出
T2O_OPENCODE_V1_PART_START_PROJECTED/_PART_END_PROJECTED。 源会话若缺少 assistant 完成时间或可解析的回复对象，v1 无法无损表示，会以T2O_OPENCODE_V1_UNSUPPORTED_STATE阻止，而不是写入不完整数据。 - TRAE 未持久化的工具输出或最终 assistant 正文不会被编造。工具记录会保留缺失标识； 缺失的最终正文会显示明确提示，内部工具 JSON 不会作为聊天正文显示。
每次成功迁移会在仓库根目录生成：
| 目录 | 用途 | 是否含会话正文 |
|---|---|---|
trae-export/ |
最新 bundle，用于重新映射和续跑 | 是 |
migration-run/ |
manifest、回读证据和迁移状态 | 否 |
Caution
这两个目录均为本地私人数据，已经在 .gitignore 中忽略。不要提交、共享或上传。
工具只自动清理由当前 verified 版本替代的旧终态目录；失败、进行中或无法确认安全性的记录 会保留，供续跑或排查使用。
| 终端提示 | 处理 |
|---|---|
无法发现 TRAE workbench |
完全退出后，用上面的终端命令重新启动 TRAE；确认目标项目窗口已打开。 |
所选 workbench 没有可迁移的本地会话 |
选择正确的项目窗口，并在 TRAE 中打开该项目后再运行。 |
无法自动启动 OpenCode |
确认 opencode --version 可运行，再用 npm run verify:opencode 检查兼容性；需要重装时可选择上述已验证基线。 |
OpenCode 版本或协议不受支持 |
确认是稳定 1.x/2.x；目标必须匹配当前或 legacy profile，并保留安全所有权和回读能力。 |
未收录的 OpenCode 版本需要同版本 CLI |
安装与目标服务相同版本的 CLI，或用 T2O_OPENCODE_BINARY 指定。 |
隔离导入、回读或删除验证失败 |
尚未向目标写入会话；使用已验证基线版本，保留错误码用于排查。 |
所选会话包含当前无法无损映射的内容 |
工具尚未写入 OpenCode。保留产物并查看故障排查。 |
目标会话已存在，但缺少可验证的旧 manifest |
目标归属无法证明，因此不会覆盖；恢复对应 manifest 或在 OpenCode 中人工确认处理。 |
迁移 bundle 超过 1 GiB |
选择更小的会话；不要修改 bundle 来绕过限制。 |
| 主题 | 文档 |
|---|---|
| 开始使用 | 操作手册：准备、迁移、验证、续跑与回滚 |
| 兼容性 | OpenCode 协议兼容性检测 · 产品与数据格式版本管理 · 变更记录 |
| 故障处理 | 常见故障与错误码 · 开发环境故障排查 |
| 迁移机制 | 离线 CLI、dry-run、导入与回读 · 迁移记录与续跑 |
| 安全与恢复 | 凭据处理边界 · 回滚与恢复 |
| 设计与验收 | 实现规划与验收矩阵 · 真实来源验收报告 |
Copyright © 2026 yororoA。本项目采用 ISC License。