hstack（Kaiwu 栈）

hstack 用于直接从本地代码仓库运行 Kaiwu。它的核心职责是实现隔离：在同一台设备上并行运行多套完整的实例（栈），每个栈各自绑定独立的代码检出、端口和数据目录，避免正在测试的分支干扰日常开发分支。

进行交互式操作时，推荐使用 TUI 包装器。它可以实时展示各条命令的执行动态，无需自行翻阅日志文件：

hstack tui stack dev dev

准备工作

• 安装与配置 —— 安装 hstack、挑选工作区，以及初始化 main 和 dev 检出。
• 路径、目录与环境变量优先级 —— 各文件的存放位置，以及不同 env 文件的生效优先级。

日常开发

• 开发工作流 —— 一站式指南：协同使用工作树、栈与 dev-auth。
• 快速入门 —— 适用于特性开发、PR 测试和服务端改动的速查命令集。
• 运行模式（dev 与 start 的区别） —— 服务端、守护进程和 UI 的启动机制、监听模式及安全重启。
• 远程开发目标机 —— 将同一份代码检出同步镜像到 Linux、macOS 或 Windows 设备。
• 校验 —— 针对特定检出或栈执行类型检查、代码规范检查与测试。
• CLI 参考 —— 常用核心命令及关键参数详解。

隔离机制原理

以下四篇文档介绍了隔离机制的核心模型。若遇到两个栈意外共享资源的情况，请先参阅这些内容：

• 栈 —— 隔离实例：端口、目录与代码仓库绑定机制。
• 工作树与 Fork —— 保持上游 PR 工作树干净整洁，隔离 fork 专属补丁。
• 认证（dev-auth 预置） —— 一次性预置凭据，新栈随取随用，无需重复登录。
• 服务端版本类型 —— 轻量版（基于 SQLite，可选 PGlite）与完整版（由 Docker 托管的基础设施）。

跨设备访问栈

• 远程访问（Tailscale） —— 在手机或其他笔记本电脑上建立 HTTPS 安全上下文。
• 远程守护进程配置（SSH） —— 在远程主机上安装 Kaiwu 并完成凭据配对。
• 远程服务端配置（SSH） —— 在远程主机上安装自托管服务端。

其他运行终端

• 移动端（iOS） —— 面向本地栈的 dev-client 工作流。
• 桌面端应用（Tauri） —— 包裹 Web UI 的原生桌面应用壳。
• 菜单栏扩展（SwiftBar） —— 通过 macOS 顶部菜单栏监控栈状态并切换工作树。
• 隔离 Linux 虚拟机 —— 在 Apple Silicon 上使用纯净虚拟机进行可复现的验证。

工作流配套工具

• Edison —— 通过 hstack 运行任务调度、QA 和证据采集，确保隔离性不受破坏。
• Monorepo 迁移 —— 将旧版独立仓库中的提交合并迁移至 monorepo。

故障排查

• 调试指南 —— 实际生效路径、绑定的代码仓库、端口、日志以及修改它们的环境变量开关。
• 常见问题排查 —— 覆盖认证失效、端口冲突、代码检出错误、栈状态异常等高频故障。