从 Trellis 迁移
Trellis 与 mini-trellis 共用 .trellis/。已有 Trellis 的项目应通过迁移命令替换集成，避免两套指令同时生效。操作前先备份项目知识与宿主配置，包括被 Git 忽略的文件。
mini-trellis migrate --dry-run # 预览迁移变更
mini-trellis migrate # 确认迁移，默认 no
迁移会将检测到的宿主的 hook、settings、skill 和命令替换为 mini-trellis 版本，移除 Trellis 专用的流程文件（skill、命令、agent、每轮注入插件、workflow.md、task.py），替换 AGENTS.md 中的 Trellis 管理块，并移除 .trellis/.version，停止 Trellis CLI 在该项目中的更新提示。
集成与配置更新
宿主配置按字段合并：
.claude/settings.json和.codex/hooks.json会先去掉指向inject-*.py、statusline.py和旧session-start.py的 Trellis hook，再写入 mini-trellis 的 SessionStart。用户自己的 hook、env和其他字段保留。- 0.3.5 同样合并
.codebuddy/settings.json。已识别的 Trellis 阶段 hook 即使脚本已丢失也会清理，同事件下的用户 hook 保留。配置无效时在修改文件前停止迁移。 - Kiro 迁移将 Trellis 技能、四个内置 Trellis Agent 和流程状态 Hook 替换为 CLI V3 / IDE 1.x 的项目技能与独立 SessionStart Hook；保留其他 Agent 和 Hook 文件。使用
kiro-cli chat --v3启动；若原默认 Agent 为 Trellis，切换到 Kiro 内置 Agent。 - 迁移会在
.zcode/config.json的hooks.events中移除已识别的 Trellis hook 调用，包括 process/args 和脚本已缺失的注册；保留其他 hook、技能和配置。配置无效时在修改前停止。迁移后用zcode hooks trust review --workspace . --json审查新声明，接受后自行授予摘要信任；迁移不改用户级配置或信任。 .pi/settings.json会去掉./extensions/trellis/index.ts和npm:pi-subagents，保留其他 extension 与 package。.codex/config.toml会去掉 Trellis 写入的说明和[agents] max_depth = 1，再写上 mini-trellis 的项目配置。用户自己的键会附在后面。
如果上一次迁移已经删掉脚本，但配置里还留着 inject-*.py，再运行一次 mini-trellis migrate 会清理这些条目。
任务材料的去向
.trellis/tasks/ 中的任务材料迁入研究目录：
- 每个任务目录转为一个 research topic：
.trellis/tasks/<name>/→.trellis/research/<name>/，归档任务迁入.trellis/research/archive/YYYY-MM/<name>/。日期前缀和目录名保留，保留内容内部的相对链接不变。指向已移入legacy/或删除文件的链接（如../prd.md）不会修复。 - 每个 topic 保留
research/子树和design.md的结构。其余任务材料——task.json、prd.md、implement*、check.jsonl、drafts/及未识别文件——按迁移开始时的选择归档到.trellis/research/<topic>/legacy/或删除。默认归档，--yes同样使用归档方式。 - 留在原地的笔记里，repo-relative 的
.trellis/tasks/…提及按完整来源路径改指到新位置；归档前的旧路径只在任务名唯一时修复。有歧义或不支持的引用保持原样并计数告警，其他仓库的引用不改写。 .trellis/.runtime/sessions/*.json里的current_task指针置 null；tasks/搬空后才删除。
如果 .trellis/research/ 下已有目标路径，或任务根已有 legacy 条目，migrate 会在修改前停止并列出冲突。请移动或重命名冲突条目后重试。迁移目录必须是真实目录；tasks/ 中未处理的条目（包括失效符号链接）会保留并告警，不会随目录删除。改写笔记时不会跟随符号链接。
迁移前请备份项目知识和自定义配置，包括被 Git 忽略的文件。迁移命令不会自动创建备份；选择删除的文件将被永久移除。
迁移之后
.trellis/spec/、research/、workspace/原样保留。已有 spec 内容，包括 Trellis 创建的backend/、frontend/文档，仍可检索；SessionStart 提供短入口，文档按需查找。.trellis/config.yaml和.trellis/scripts/会被 mini-trellis 版本覆盖，自定义配置和脚本修改需在迁移后重新应用。- 缺少
.trellis/.gitignore时会补上，让本地身份与运行状态保持在 Git 之外，已有用户规则保留。不会取消 Git 对已跟踪文件的跟踪。 - 迁移后的任务目录是
.trellis/research/下的 topic，mem recall可查活跃和归档笔记，启动时不枚举全部主题；只有没有未处理条目时才删除.trellis/tasks/。 .trellis/.version被移除，mini-trellis 自己不会再写这个文件，Trellis CLI 在这个项目里不会再有更新提示。
迁移时的 OpenCode 协议
0.3.5 新项目默认 V2；迁移保留已有的 V1 入口作为兼容，不静默跨协议升级。迁移需要明确选择协议时，用 migrate --opencode-version 1|2 --dry-run 预览。未托管的 Trellis 入口不能直接跨协议替换：先原地迁移，再检查 refresh --opencode --opencode-version 2 --dry-run。切换只移除 manifest 证明未修改的旧托管入口，其他插件保留；迁移和刷新均不修改宿主二进制、API、模型或全局信任。
迁移后整理已有历史
迁移保留项目知识，不会把所有旧聊天自动变成 spec。安装 0.3.6 或更新版本并刷新技能后，可明确要求 mini-trellis-session-insight 整理选定的已支持会话或提供的 Markdown/文本导出，更新已有文档、保留来源，未解决冲突保持开放。该整理流程使用 --no-commit，即使旧配置开启自动提交也不自动提交。见历史整理指南。