工作树与 fork

本仓库旨在本地运行 Kaiwu 栈，同时方便你：

在日常开发中继续使用自己的 Fork
快速创建干净的上游 PR 分支（不夹带仅属于 Fork 的补丁）

hstack 优先支持单一代码库（Monorepo）：UI、CLI 与服务端均位于同一个 Kaiwu Git 仓库中。

核心思路：保持稳定检出目录不变

在 ⟦K25⟧/main 保留一份稳定的检出副本（视为只读）。
所有开发工作均在 ⟦K26⟧/dev 或 ⟦K27⟧/{pr,local,tmp}/... 下的工作树中进行。
通过 KAIWU_STACK_REPO_DIR 将栈指向对应的仓库检出目录。
- 由 hstack wt use ... 与 hstack stack wt ... 统一管理。

工作区目录结构

默认路径（实际取值请参见 hstack where）：

稳定检出目录：⟦K28⟧/main
开发检出目录：⟦K29⟧/dev（由 hstack setup-from-source --profile=dev 创建）
工作树：
- PR：⟦K30⟧/pr/...
- 本地：⟦K31⟧/local/⟦K32⟧/...
- 临时：⟦K33⟧/tmp/⟦K34⟧/...

单一代码库内部结构：

apps/ui（UI）
apps/cli（CLI + 守护进程）
apps/server（服务端；轻量版/完整版）

规范语法（可传给 `--repo` / `wt use` 的参数）

凡是需要指定“仓库/工作树”的位置，均支持以下标识符/规范：

main / default → ⟦K35⟧/main
dev → ⟦K36⟧/dev
active → 当前活跃仓库（你的 Shell 环境变量 / env.local）
pr/<...> → ⟦K37⟧/pr/<...>
local/<...> → ⟦K38⟧/local/⟦K39⟧/<...>（所有者为你的本地用户名）
tmp/<...> → ⟦K40⟧/tmp/⟦K41⟧/<...>
Kaiwu 单一代码库检出目录或工作树的绝对路径

示例：

hstack wt use dev
hstack wt use pr/123-fix-thing
hstack stack wt exp1 -- use local/my-feature
hstack stack typecheck exp1 --repo=/abs/path/to/checkout

Fork 工作流（upstream 对比 origin）

惯例约定：

upstream：Kaiwu 官方权威仓库（wuji-labs/kaiwu）
origin：你的 Fork（用于推送分支）

“上游优先”的工作流程如下：

基于 upstream 创建工作树（保持提交历史干净）
将特性分支推送到 origin
向 upstream/dev 提交 PR

选择 hstack 运行的检出目录

hstack 通过以下变量选择当前活跃的仓库检出目录：

KAIWU_STACK_REPO_DIR（单一代码库根目录的绝对路径）

推荐的设置方式：

# Switch the active checkout for non-stack commands:
hstack wt use dev

# Switch the repo for a specific stack env:
hstack stack wt exp1 -- use dev

单次覆盖（不修改任何环境配置文件）：

hstack stack typecheck exp1 --repo=pr/123-fix-thing
hstack stack build exp1 --repo=/absolute/path/to/checkout

创建工作树（`wt new`）

创建新的工作树（默认归入 local 分类，基于 upstream 分支）：

hstack wt new local/my-feature --use

临时工作树：

hstack wt new tmp/scratch --use

将当前活跃工作树的分支推送到你的 Fork：

hstack wt push active --remote=origin

说明：

--from=upstream|origin 用于控制使用哪个远程仓库作为基准。
默认基准分支为 dev（可通过 KAIWU_STACK_DEV_BRANCH 配置）。

在本地测试 GitHub PR（`wt pr`）

在 PR 的 HEAD 引用处创建工作树：

hstack wt pr https://github.com/wuji-labs/kaiwu/pull/123 --use

# or just the PR number (remote defaults to upstream)
hstack wt pr 123 --use

PR 发生变动时进行更新：

hstack wt pr 123 --update --stash

说明：

若 PR 发生过强制推送导致更新无法快进（fast-forward），--update 会采取关闭式失败策略；此时可追加 --force 重新运行。
--stash 会在更新过程中妥善保存你尚未提交的修改。

在栈中测试 PR（推荐）

若想保持 PR 栈易于维护，推荐使用 hstack stack pr：

hstack stack pr pr123 --repo=123 --dev --reuse

工作流辅助命令

`wt status`

hstack wt status active
hstack wt status dev

`wt list`

hstack wt list

包含 main/、dev/ 以及 pr/、local/、tmp/ 下的所有分类工作树。

`wt sync` / `wt sync-all`

将远程引用同步到本地镜像分支（在创建新工作树前非常实用）：

hstack wt sync --remote=upstream
hstack wt sync-all --remote=upstream

`wt update`

从基准分支更新工作树（发生冲突时默认采取关闭式失败，除非显式开启 --force）：

hstack wt update pr/123-fix-thing
hstack wt update pr/123-fix-thing --stash
hstack wt update pr/123-fix-thing --force

暂存区（Stash）行为：

--stash：自动暂存；若更新过程干净无冲突，则自动弹出恢复
--stash-keep：自动暂存但保留在暂存区（后续由你手动应用）

`wt update-all`

hstack wt update-all

试运行（Dry-run）：

hstack wt update-all --dry-run

`wt git`

在解析后的工作树中执行 Git 命令：

hstack wt git pr/123-fix-thing -- status
hstack wt git dev -- checkout -b feature/foo

`wt shell`

在工作树中打开一个“真实”的交互式 Shell：

hstack wt shell dev

编辑器（`wt code` / `wt cursor`）

hstack wt cursor dev
hstack wt code pr/123-fix-thing

`wt duplicate`

复制工作树（适用于“基于相同基准开展不同实验”的场景）：

hstack wt duplicate active tmp/try-alt --use

`wt archive`

归档并移除工作树目录（可选同时删除分支）：

hstack wt archive pr/123-fix-thing --dry-run
hstack wt archive pr/123-fix-thing

若有栈固定指向该工作树，可使用 --detach-stacks 解除绑定。

交互模式与 JSON 模式

大多数命令均支持：

--interactive / -i（仅限 TTY 终端的引导向导）
--json（机器可读输出）

示例：

hstack wt use --interactive
hstack wt pr 123 --json
hstack wt list --json

切换服务端版本（轻量版对比完整版）

选择栈运行时所使用的后端版本：

hstack srv status
hstack srv use KAIWU-server-light
hstack srv use KAIWU-server
hstack srv use --interactive

说明：

此操作仅选择运行时版本（轻量版/完整版），不会切换到其他 Git 仓库。
两个版本均来自同一代码库中的同一套服务端代码（apps/server）。

Fork 配置（针对贡献者）

在贡献者工作流中，hstack 要求如下设置：

upstream → 提交 PR 的权威仓库
origin → 你的 Fork（用于推送分支）

如果运行 hstack setup-from-source --profile=dev 时 origin 仍指向 upstream（且你对其没有推送权限），设置向导会引导你为 origin 配置 Fork URL。

非交互式选项：

export KAIWU_STACK_FORK_URL="https://github.com/<you>/KAIWU.git"
hstack setup-from-source --profile=dev

配置完成后，常见的 PR 流程如下：

hstack wt new local/my-feature --from=upstream --use
hstack wt push active --remote=origin

如果你更倾向于在长期保留的 dev/ 检出目录中工作，可以使用 hstack contrib extract 干净地创建特性分支。详情请参阅开发工作流。

On this page