开发工作流
使用 hstack（工作树 + 栈 + dev-auth）本地开发 Kaiwu 的“一站式”指南。
本文旨在为开发者与 LLM 提供完备的指导，确保在 Kaiwu monorepo 中的操作安全且可复现。
初次使用请先阅读以下内容：
- 工作树与 Fork：Worktrees and forks
- 栈：Stacks (isolated instances)
- 路径与环境变量优先级：Paths, folders, and env precedence
- 快速上手（即拷即用工作流）：Quickstarts
- 运行模式（dev 与 start 的区别）：Running (dev vs start)
- 校验（类型检查、代码检查与测试）：Validation (typecheck, lint, test)
- CLI 命令参考：CLI reference (high-signal)
- 调试指南：Debugging (inspect + env knobs)
- 排障指南：Troubleshooting
核心概念（心智模型）
Monorepo
hstack 以 Monorepo 为核心构建：UI、CLI 以及服务器代码均存放在同一个 Kaiwu Git 仓库中。
当前目录结构：
apps/ui（UI）apps/cli（CLI 与守护进程）apps/server（服务器；提供轻量版和完整版两种形态）apps/stack（本工具）
工作区签出（代码存放位置）
你的工作区包含以下内容：
main/—— 稳定版本签出（请视为只读）dev/—— 标准开发签出（dev 分支）- 分类工作树：
pr/<...>—— PR 签出（hstack wt pr ...）local/⟦K24⟧/<...>—— 特性工作树tmp/⟦K25⟧/<...>—— 临时工作树
工作树（代码编写位置）
切勿直接在 main/ 中开发，请将其视为“启动器默认环境”。
所有功能实现均应在以下位置进行：
dev/，或- 位于
local/、tmp/、pr/下的工作树。
栈（安全测试方案）
栈是隔离的运行时环境（包含独立的端口、目录、数据库以及 CLI 主目录），存放在：
~/.Kaiwu/stacks/<stack>/...每个栈的配置位于：
~/.Kaiwu/stacks/<stack>/env通过使用栈，你可以在不污染“主”环境的前提下测试代码修改。
服务器形态（运行哪种后端）
每个栈仅运行一种服务器形态：
Kaiwu-server-light（推荐）—— 最简单的本地安装形态（默认使用 SQLite；可通过 PGlite 选用嵌入式 Postgres）Kaiwu-server（完整版）—— 由 Docker 管理的 Postgres/Redis/Minio 环境
详情参见：Server flavors。
原则底线（保障栈环境安全的开发纪律）
- 统一以
hstack作为入口- 如果需要栈级隔离行为，切勿直接运行裸命令
yarn dev、expo、docker compose等。 - hstack 需要依赖栈范围的环境变量与运行时记录来保持环境相互隔离。
- 如果需要栈级隔离行为，切勿直接运行裸命令
- 始终在工作树中开发
- 使用
dev/或hstack wt ...工作树；不要直接修改main/。
- 使用
- 在非
main栈中测试- 优先选用
hstack stack ⟦K26⟧ dev|start|test|typecheck|lint，避免变更污染默认栈。
- 优先选用
- 不要杀掉全局守护进程
- 系统设计上允许多个栈的守护进程并存（每个栈一个）。
- 请显式停止指定栈：执行
hstack stop或hstack stack stop ⟦K27⟧。
快速上手（常用开发流）
1) 典型特性开发（在单个工作树中同时修改 UI、CLI 和服务器）
基于上游创建工作树（推荐此做法以保持干净的 PR 提交历史）：
hstack wt new local/my-feature --from=upstream --use创建隔离栈并将其指向当前活动工作树：
hstack stack new exp1
hstack stack wt exp1 -- use active以开发模式运行：
hstack tui stack dev exp1如果无法使用 TUI（例如非交互式终端或 CI 环境），请运行：
hstack stack dev exp1执行校验：
hstack stack typecheck exp1
hstack stack lint exp1
hstack stack test exp12) 使用标准 dev/ 签出代替特性工作树
创建开发栈并将其固定到 dev/：
hstack stack new dev
hstack stack wt dev -- use dev
hstack tui stack dev dev
# (optional) mobile dev-client + QR:
hstack tui stack dev dev --mobile3) 本地测试上游 PR（推荐）
创建 PR 工作树：
hstack wt pr 123 --use创建隔离的 PR 栈（支持幂等更新）：
hstack stack pr pr123 --repo=123 --dev如果已经创建过 dev-auth 种子栈，可以追加参数：
hstack stack pr pr123 --repo=123 --dev --seed-auth --copy-auth-from=dev-auth --link-authPR 工作流（以 dev 分支为目标）
Kaiwu 的分支规划如下：
main：稳定分支dev：贡献分支（PR 的基准分支）
推荐流程：
- 基于
upstream/dev创建工作树 - 推送至个人 Fork 仓库（
origin） - 向
upstream/dev提交 PR
hstack 默认基于上游历史创建新工作树，并推荐使用 origin 推送，从而有效保障 PR 历史的整洁。
详情参见：Worktrees and forks。
若想通过引导式工作流从 dev 分支提取特性分支，可运行：
hstack contrib ensure-dev
hstack contrib extract my-feature --pushstart 与 dev 的区别
hstack start/hstack stack start ⟦K28⟧：接近生产环境的表现（使用构建后的 UI，文件监听进程更少）hstack dev/hstack stack dev ⟦K29⟧：开发环境（启动监听器与开发服务器，迭代更快速）
如果不确定该选哪个，请使用 hstack tui stack dev ⟦K30⟧（在非交互式环境中请使用 hstack stack dev ⟦K31⟧）。
开发者专属：一次性配置 dev-auth（推荐）
创建种子栈并完成交互式登录：
hstack auth seed后续创建新栈即可直接复用该认证凭据：
hstack stack auth <stack> copy-from dev-auth详情参见：Auth (dev-auth seeding)。
进程隔离（停止与重启操作安全的原因）
每个栈都会在专用的运行时状态文件中记录其归属的运行中进程：
~/.Kaiwu/stacks/<stack>/stack.runtime.jsonhstack 依此实现：
- 仅停止属于当前栈的进程
- 重启时尽可能复用临时端口
- 避免直接按端口号进行全局误杀
“上游优先”工作树工作流（推荐）
该流程的目标是：
- 保持个人 Fork 长期分支的整洁与稳定
- 快速创建面向基准上游的 PR 分支
- 避免将仅用于 Fork 的本地修改混入上游 PR 中
推荐操作模式：
- 基于
upstream/dev创建工作树：
hstack wt new local/my-feature --from=upstream --base=upstream/dev --use- 在隔离栈中进行开发与校验：
hstack stack new exp1
hstack stack wt exp1 -- use active
hstack stack dev exp1- 将分支推送到个人 Fork，并向
upstream/dev发起 PR：
hstack wt push active --remote=origin如果确实需要保留仅用于 Fork 的发行补丁（极少见），请放在独立分支中维护，切勿合并到面向由上游合并的 PR 工作树里。
监听模式与热重载迭代
hstack 默认使用 dev 模式进行开发，原因如下：
- 以适配开发的方式启动服务器
- 启动 UI 开发服务器（视具体应用决定启动 Expo 还是 Next）
- 基于栈自身的运行时状态安全重启各进程
在切换运行选项参数（如启用移动端）时，推荐使用 hstack 重启整个栈，而非逐个手动重启各个进程。
校验命令（类型检查、代码检查与测试）
推荐在栈作用域内执行校验，以确保测试环境与实际运行环境一致：
hstack stack typecheck exp1
hstack stack lint exp1
hstack stack test exp1针对当前活动的签出目录（非栈环境），也可以直接运行：
hstack typecheck
hstack lint
hstack testCLI 命令参考（高频核心）
核心操作：
- 初始化（源码安装）：
hstack setup-from-source --profile=dev|selfhost（已废弃别名：hstack setup） - 运行：
hstack start/hstack dev - 停止：
hstack stop - 诊断：
hstack where、hstack doctor
栈管理：
- 创建/列出/查看信息：
hstack stack new、hstack stack list、hstack stack info - 运行：
hstack stack dev ⟦K32⟧、hstack stack start ⟦K33⟧ - 切换仓库目录：
hstack stack wt ⟦K34⟧ -- use ⟦K35⟧ - 切换服务器形态：
hstack stack srv ⟦K36⟧ -- use Kaiwu-server-light|Kaiwu-server - 认证管理：
hstack stack auth ⟦K37⟧ status|login|copy-from - PR 栈：
hstack stack pr ⟦K38⟧ --repo=⟦K39⟧
工作树管理：
- 创建/使用：
hstack wt new ⟦K40⟧ --use - PR 签出：
hstack wt pr ⟦K41⟧ --use - 列出/状态/更新：
hstack wt list、hstack wt status、hstack wt update、hstack wt update-all - 推送：
hstack wt push active --remote=origin
认证播种：
- 种子栈：
hstack auth seed - 批量播种：
hstack auth copy-from dev-auth --all --except=main,dev-auth - 开发者密钥：
hstack auth dev-key
常用环境变量配置（高频核心）
路径配置：
Kaiwu_STACK_WORKSPACE_DIR（工作区根目录）Kaiwu_STACK_REPO_DIR（活动签出目录；通常由hstack wt use管理）Kaiwu_STACK_CLI_ROOT_DIR（从本地签出目录运行 hstack）
认证配置：
Kaiwu_STACK_AUTH_SEED_FROM（新栈的默认认证源；常用dev-auth）Kaiwu_STACK_AUTH_MODE（copy与link）
服务器选择：
Kaiwu_STACK_SERVER_COMPONENT（Kaiwu-server-light与Kaiwu-server）
排障指南（高频核心）
“hstack 究竟在使用什么配置？”
hstack where
hstack stack info <name>“为什么这个栈使用了错误的签出目录？”
检查已固定的仓库路径：
hstack stack info <name>
cat ~/.Kaiwu/stacks/<name>/env | rg Kaiwu_STACK_REPO_DIR重新指定路径即可修复：
hstack stack wt <name> -- use dev
# or:
hstack stack wt <name> -- use pr/123-fix-thing