Monorepo 移植（历史拆分仓库）

使用 `hstack monorepo port` 将提交从拆分仓库移植到 Kaiwu monorepo（冲突友好）。

本文档介绍 hstack monorepo port。该辅助工具可将一个或多个“独立仓库”源的提交应用至目标 Kaiwu monorepo 分支。

其工作原理是先生成补丁（git format-patch），再通过 git am 将补丁应用到目标仓库中。

当你需要将早期工作成果或外部补丁合入 monorepo 目录结构时，该工具尤为适用。

快速上手

查看帮助信息：

hstack monorepo port --help

交互式引导（推荐；需要 TTY）：

hstack monorepo port guide

非交互式移植（进阶；尽力而为）：

hstack monorepo port --target=/abs/path/to/Kaiwu-monorepo --branch=port/my-changes

状态查看与继续执行辅助命令（当 git am 正在进行时）：

hstack monorepo port status --target=/abs/path/to/monorepo
hstack monorepo port continue --target=/abs/path/to/monorepo

路径映射说明

hstack monorepo port 专为迁移至 Kaiwu monorepo 目录结构设计，会将补丁应用至以下目录：

UI：apps/ui/（兼容旧路径：expo-app/）
CLI：apps/cli/（兼容旧路径：cli/）
服务端：apps/server/（兼容旧路径：server/）

这意味着支持从以下源进行移植：

旧版独立仓库（UI、CLI、服务端各自独立的仓库），或
另一个 monorepo 检出副本（例如希望变基到其他基准分支上的一系列可 cherry-pick 变更）

移植辅助命令（引导 / 预检 / 状态 / 继续）

命令族包含：

hstack monorepo port guide —— 交互式向导（仅限 TTY）
hstack monorepo port preflight —— 验证目标仓库是否干净且准备就绪（尽力而为）
hstack monorepo port status —— 报告当前阻塞 git am 的补丁及冲突
hstack monorepo port continue —— 运行 git am --continue（支持时可一并暂存文件）

LLM 辅助冲突解决（可选）

当移植因冲突中断时，可以请求大语言模型辅助解决：

hstack monorepo port llm --target=/abs/path/to/monorepo --launch

或者复制提示词以便手动粘贴：

hstack monorepo port llm --target=/abs/path/to/monorepo --copy

常见故障（预期内）及应对策略

“target repo is not clean”

目标仓库必须保持干净。请先在目标仓库中提交或暂存更改，然后重新运行。

“a git am operation is already in progress”

请先解决或中止正在进行的 git am：

git -C /abs/path/to/target am --continue
# or
git -C /abs/path/to/target am --abort

“patch does not apply”

通常表示该补丁与当前目标基准不匹配（如存在重命名、国际化频繁变动、代码格式化变更等）。

可选方案：

基于其他基准重新运行（--base=⟦K14⟧）
启用三方合并回退（--3way）
失败时继续执行（记录失败项但保持运行直至完成）：--continue-on-failure

文件路径缺失错误 / 双重前缀问题

请使用 guide 模式，并确保正确识别源仓库类型（来自 monorepo 的源不应被重复添加前缀）。

常用参数选项

以下是最高频使用的参数：

--target=/abs/path/to/monorepo（默认为当前仓库根目录）
--target-repo=⟦K15⟧ + --clone-target（将目标克隆至新目录）
--branch=port/⟦K16⟧（为本次移植创建新分支）
--base=⟦K17⟧（选择目标基准引用；默认尽力对齐远程 HEAD）
--onto-current（直接应用到当前检出的分支，不切换分支）
--dry-run（仅计算并预览，不实际应用）
--skip-applied（检测到已存在的补丁时直接跳过）
--json（输出机器可读格式）

移植策略（推荐）

创建独立的栈（避免改动 main）：

hstack stack new monorepo-port

为目标 monorepo 分支创建干净的工作树：

hstack wt new tmp/monorepo-port --from=upstream --use

在该工作树中创建新分支并将变更移植至该分支（--onto-current）。

如果移植因冲突中断，此时处于常规的 git am 会话中：

解决冲突标记（<<<<<<<、=======、>>>>>>>）
git add <files...>
git am --continue

目录结构映射

Kaiwu monorepo 采用如下目录划分：

UI：apps/ui
CLI：apps/cli
服务端：apps/server

若从旧版源码移植，补丁通常需要落入上述目录中。

使用 guide 模式可避免路径重复添加前缀，并能预览补丁的应用目标路径。