运行（dev 对比 start）

start vs dev

• hstack start / hstack stack start ⟦K17⟧：类生产环境（优先使用构建好的 UI，监听进程更少）
• hstack dev / hstack stack dev ⟦K18⟧：开发环境（监听模式，迭代更快）

如果不确定，请使用 hstack tui stack dev ⟦K19⟧（非交互式环境下使用 hstack stack dev ⟦K20⟧）。

仅适用于具名栈：start 还可以基于保存在栈目录下的已激活运行时快照运行，而无需依赖实时的代码仓库检出：

hstack stack build exp1 --activate-runtime
hstack stack start exp1 --runtime

适用于以下场景：

• 为 web + server + daemon 生成栈本地的生产构建产物
• 隔离同一检出目录下的源码重新构建，避免对已安装的服务造成干扰
• 与另一个栈中正在编辑的同一工作树保持关联，同时运行一个类生产环境的栈

如果需要监听进程、Metro 或快速的源码迭代，请继续使用 dev。

TUI 模式（交互式开发推荐）

对于本地交互式开发，建议在 hstack TUI 中包装运行命令：

hstack tui stack dev dev
# mobile dev-client + QR:
hstack tui stack dev dev --mobile

在非交互式终端 / CI 环境中（或 TUI 不可用时），请直接执行底层命令：

hstack stack dev dev

浏览器源隔离（重要）

如果始终使用 http://localhost:...，同时运行多个栈会导致浏览器状态（Cookie / localStorage）发生冲突。

在需要隔离时，hstack 会优先为非主栈分配栈专属的源（避免各栈争抢浏览器认证/会话状态）。

提示：若发现不同栈之间的“认证状态异常”，请检查：

• 当前正在使用哪个栈（hstack stack info ⟦K21⟧）
• 打开的是哪个 UI URL（请使用 hstack 输出的 URL）

自动打开浏览器（--no-browser）

在交互式运行中，hstack dev / hstack start 可能会自动在浏览器中打开 UI。

• 禁用：--no-browser
• 全局禁用：Kaiwu_STACK_NO_BROWSER=1

监听模式（类似热重载）

在交互式 TTY 运行中，hstack dev 默认启用监听模式：

• Kaiwu-cli 发生变更 → 重新构建并重启守护进程
• 当 hstack 确认某些常驻进程归属于当前栈时，可以安全地重启它们

控制标志：

• 强制启用：hstack dev --watch
• 禁用：hstack dev --no-watch

如果 hstack 提示因 PID 未知而禁用重启，请使用 --restart 重新运行，以便 hstack 能够派生并跟踪该进程。

基于运行时的具名栈

构建目标：

hstack stack build exp1 --web
hstack stack build exp1 --server
hstack stack build exp1 --daemon
hstack stack build exp1 --all

全量运行时激活：

hstack stack build exp1 --activate-runtime

部分运行时激活：

hstack stack runtime exp1 activate --web
hstack stack runtime exp1 activate --server
hstack stack runtime exp1 activate --daemon
hstack stack runtime exp1 activate --all

典型的类生产环境具名栈更新流程：

hstack stack build exp1 --activate-runtime
hstack stack service exp1 restart

单组件更新流程：

# UI-only: build the artifact, activate only web, then reload the browser
hstack stack build exp1 --web
hstack stack runtime exp1 activate --web

# Server-only: build + activate only server, then restart
hstack stack build exp1 --server
hstack stack runtime exp1 activate --server
hstack stack service exp1 restart

# CLI/daemon-only: build + activate only daemon, then restart
hstack stack build exp1 --daemon
hstack stack runtime exp1 activate --daemon
hstack stack service exp1 restart

启动选择：

hstack stack start exp1 --runtime
hstack stack start exp1 --source

持久模式：

hstack stack env exp1 set Kaiwu_STACK_RUNTIME_MODE=prefer

模式含义：

• source：始终使用实时检出代码
• prefer：存在已激活的运行时快照时优先使用，否则使用源码
• require：必须存在有效的已激活运行时快照，否则报错退出

重要说明：

• 为保持向后兼容，不带参数的 hstack stack build ⟦K22⟧ 仍然仅构建 Web Bundle。
• hstack stack build ⟦K23⟧ --web|--server|--daemon 仅更新构建产物。在激活新的运行时快照之前，运行中的栈不会切换到这些产物。
• --tauri 仍属于传统的本地 hstack build 流程，未纳入 v1 具名栈的产物/运行时构建体系。
• 运行时快照目前是具名栈的专属特性。仓库本地的 yarn tui、hstack dev 以及仓库本地的 hstack start 仍然基于源码运行。
• hstack stack dev ⟦K24⟧ 保持仅基于源码运行；运行时快照适用于 start 和栈服务。
• 仅激活 Web 部分会更新稳定的 runtime/current/ui 路径，因此刷新浏览器即可生效。
• 仅激活服务器或仅激活守护进程则需要重启，以便进程重新解析激活的运行时。
• 运行中的具名栈服务不会就地切换服务器/守护进程。请先重新构建或激活，再重启服务或栈进程，以便重新解析激活的快照。

安全重启

hstack start 和 hstack dev 均支持 --restart：

hstack dev --restart
hstack start --restart

针对具名栈：

hstack stack dev exp1 -- --restart
hstack stack start exp1 -- --restart

安全停止栈

停止单个栈：

hstack stack stop exp1

停止多个栈：

hstack stop --except-stacks=main --yes

常用标志：

• --aggressive：停止守护进程跟踪的其他会话（仍归属于该栈）
• --sweep-owned：最终清理：扫描其进程环境中仍携带该栈环境变量的进程
• --no-docker：跳过关闭由 Docker 管理的基础设施

CLI 构建行为（Kaiwu-cli）

运行栈时，hstack 会在需要时确保完成 CLI 构建（以便守护进程可以启动）。

控制选项：

• Kaiwu_STACK_CLI_BUILD_MODE=auto|always|never
• Kaiwu_STACK_CLI_BUILD=0（强制禁用）