从 Monorepo 克隆运行（仓库本地模式）

如果克隆了 Kaiwu monorepo，你可以直接在仓库根目录下运行 yarn 脚本，处理大部分日常工作流。

注意：GitHub 仓库的默认分支是 dev，可能不够稳定。若希望在基于源码运行时获得更稳定的环境，建议签出 preview。

该模式为仓库本地（repo-local，即无栈）模式：它会在 ~/.KAIWU/stacks/⟦K28⟧/... 下为当前签出目录创建隔离的栈，且无需指定栈名称。

重要说明：仓库本地模式本质上仍是基于源码运行（source-backed）的流程。

• yarn tui、yarn dev 以及仓库本地的 yarn start 均直接运行自当前签出源码。
• 若需要栈本地生产构建产物（web + server + daemon）及激活的运行时快照，请搭配 hstack stack build ⟦K29⟧ --activate-runtime 使用具名栈。
• 如果你想让第二个栈指向同一个签出目录，同时免受源码重新构建带来的变动影响，具名栈是理想选择。

前置准备

• 启用 Node + Corepack
• 在 monorepo 根目录下运行 yarn install

快速上手（开发模式）

cd /path/to/KAIWU
yarn dev

若要使用交互式终端 UI（TUI）：

yarn tui

如果设备已被 Agent 任务完全占满，可使用救援调度优先级启动控制面：

yarn tui --rescue

救援模式支持 macOS 和 Linux。它会请求 sudo 仅提升 TUI 和栈控制进程的优先级；新启动的 Agent 会话则会恢复为较低的调度优先级，不会继承控制面的提速权限。以普通用户身份运行 Yarn 即可——该命令仅在执行 renice 时请求提权。

在有人值守的 TUI 启动等待过程中，即便超过了就绪检测间隔，也不会直接销毁栈。只要归属的启动生命周期仍处于活跃状态，该检测间隔就会生成一个可见的“仍处于启动中”检查点，TUI 将继续等待。退出 TUI 依然是唯一的取消机制。非交互式栈和服务命令则保留有限的超时时限。

包含移动端（启动带 --mobile 的开发栈，从而可以使用 Expo dev-client 二维码流程）：

yarn tui:with-mobile

命令模型（仓库本地模式工作原理）

所有仓库根目录的运行时脚本均遵循以下包装器结构：

node ./apps/stack/scripts/repo_local.mjs <hstack-subcommand> [args...]

该包装器会自动处理以下关键操作：

• 强制基于当前 monorepo 签出目录执行（不会重定向到全局安装）。
• 使用与各签出目录隔离的栈名称（repo-⟦K30⟧-⟦K31⟧）。
• 在 ~/.KAIWU/stacks/⟦K32⟧/... 下设置栈作用域的环境变量文件和 CLI 主目录。
• 默认使用无栈模式的固定端口范围：
  • 服务端起始端口 52005
  • Expo 起始端口 18081
• 在大多数运行时命令执行前，按需自动安装依赖。

包装器默认行为与便捷改写规则：

• yarn tui 会变为 hstack tui dev（在未传入额外参数时）。
• yarn stop 会变为 hstack stack stop ⟦K33⟧。
• yarn mobile:install 会变为 hstack stack mobile:install ⟦K34⟧ --name="Kaiwu (Local)"，除非显式传入 --name。

传递参数与获取帮助

使用 Yarn v1 的参数转发机制，配合 -- 传参：

yarn logs -- --component=daemon --lines 200 --no-follow
yarn auth login -- --method=mobile --no-open
yarn service:enable -- --auth-now -- --method=web --webapp=hosted

查看帮助：

yarn <script> -- --help
yarn service -- --help
yarn remote -- --help

在任意位置运行 Kaiwu CLI（基于当前仓库签出）

若希望在任意终端中运行的 hstack / KAIWU 命令都基于当前克隆版本执行（而非运行时全局安装版本）， 可以激活仓库本地 shim：

yarn cli:activate

若要同时将 ~/.KAIWU-stack/bin 自动添加到 Shell 的 PATH（会修改 Shell 配置文件）：

yarn cli:activate:path

类生产环境启动（本地）

yarn start 会以类生产环境（prod-like）模式运行本地栈（包括服务端、守护进程，以及可选托管的预构建 UI 产物包）。

在执行 yarn start 之前，先构建导出的静态 UI 产物：

yarn build
yarn start

默认情况下，yarn build 会将 Web UI 导出产物写入当前栈的根目录：

~/.KAIWU/stacks/<repo-stack>/ui

这里仅包含 Web 产物包。仓库本地模式目前不会为服务端和守护进程组装栈本地运行时快照。

若需要该级别的隔离，请改用具名栈：

hstack stack new prod-dev --repo=/absolute/path/to/this/checkout
hstack stack build prod-dev --activate-runtime
hstack stack env prod-dev set KAIWU_STACK_RUNTIME_MODE=prefer
hstack stack start prod-dev --runtime

系统服务（开机自启）

你可以安装系统服务，使 hstack start 在后台常驻运行（macOS 使用 launchd，Linux 使用 systemd）。

推荐做法（先构建 UI 再安装服务）：

yarn service:install
yarn service:enable

首次认证（推荐）

如果是首次在该设备上运行栈，服务会保持服务端和 UI 运行，但守护进程可能会处于停止状态，直到完成认证。

适合无图形界面环境（打印二维码/深度链接，不会自动打开浏览器）：

yarn service:enable -- --auth-now -- --method=mobile --no-open

适合笔记本电脑环境（使用托管 Web 应用呈现授权审批界面）：

yarn service:enable -- --auth-now -- --method=web --webapp=hosted

注意事项：

• 如果已启用服务，之后可通过 yarn auth login ... 完成认证——服务会自动检测凭据并启动守护进程。
• 若栈的公网 URL 为 localhost / 127.0.0.1（或为空）且未启用 Tailscale Serve，在配置公网 URL 之前无法通过手机使用 --method=mobile（详见下文 Tailscale 部分）。

其他服务相关命令：

yarn service status
yarn service logs
yarn service tail
yarn service restart
yarn service:disable
yarn service:uninstall

Linux 系统服务（高级）：

yarn service:install:system

Tailscale Serve（HTTPS 安全上下文）

如果使用 Tailscale，可以配置 tailscale serve 通过 HTTPS 暴露本地栈。

yarn tailscale:enable
yarn tailscale:url

其他 Tailscale 命令：

yarn tailscale status
yarn tailscale:disable

日志

持续跟踪日志（默认跟踪 --component=auto 选中的日志）：

yarn logs

常用日志流（无需额外参数）：

yarn logs:all
yarn logs:server
yarn logs:expo
yarn logs:ui
yarn logs:daemon
yarn logs:service

高级用法：向 hstack logs 传递参数（Yarn v1 需要使用 -- 才能将参数转发到底层命令）：

yarn logs -- --component=server --follow
yarn logs -- --component=expo --follow
yarn logs -- --component=daemon --lines 200 --no-follow

环境变量（针对单个仓库本地栈）

yarn env list
yarn env set KEY=VALUE
yarn env unset KEY

这些修改会持久化保存在：

~/.KAIWU/stacks/<repo-stack>/env

移动端

安装 iOS Release 构建版本（执行完整流程，无需指定栈名称）：

yarn mobile:install

其他仓库本地移动端工作流：

yarn mobile
yarn mobile-dev-client

命令参考（仓库本地运行时脚本）

本节汇总了 monorepo 根目录下提供的运行时命令，有意略过了面向维护者的测试、构建和发布脚本。

核心生命周期

认证、守护进程与 CLI 入口

日志

--component 的有效值包括：auto、all、runner、server、expo、ui、daemon、service。

环境变量

系统服务（开机自启）

服务日志输出行数默认为 120；可通过 KAIWU_STACK_LOG_LINES=⟦K40⟧ 覆盖该默认值。

Tailscale

移动端

高级工作流

hstack 与 npx 的等价关系

是的，用户可以直接使用 hstack 或 npx 来运行许多工作流，但两者有一个重要区别：

• yarn ⟦K42⟧ 会自动应用仓库本地包装器语义。
• hstack ... / npx ... hstack ... 则以纯粹的 hstack 行为运行，除非自行配置了等效的环境变量或栈参数。

示例：

# Published CLI (works, but not repo-local wrapper semantics by default)
npx --yes -p @KAIWU-dev/stack@latest hstack dev

# Equivalent to repo-local wrapper behavior from this checkout
node ./apps/stack/scripts/repo_local.mjs dev

# Recommended for contributors: activate this clone, then use hstack everywhere
yarn cli:activate
hstack dev