Hakoniwa

可编排、可接管的轻量 Linux 桌面会话。

Hakoniwa 为桌面自动化、应用测试和交互式工作流提供独立运行的 Wayland 桌面。通过命令行或 TypeScript SDK 操作应用，也可以打开查看器，接管同一个桌面。脚本结束或查看器关闭后，会话仍可继续运行。

功能

• 独立桌面：支持 Wayland 与 XWayland 应用，提供顶栏、应用 dock、中文输入和会话剪贴板。
• 桌面自动化：键鼠输入、窗口查询与操作、整屏及窗口截图，以及 AT-SPI 辅助功能树、文本和动作接口。
• 人工接管：查看器默认只读，接管后可操作桌面，再将控制权交还自动化流程。
• 音频与录像：每会话独立的虚拟扬声器和麦克风，支持音频注入、录音及带应用音频的桌面录像。
• 脚本编排：TypeScript / JavaScript SDK 提供类型化接口、条件等待、超时和取消。
• 可复现构建：Nix 打包 CLI、查看器、SDK 和桌面运行时，共享开发环境的依赖定义。

快速开始

需要 x86_64 Linux、启用 flakes 的 Nix，以及允许 bubblewrap 使用所需 namespace 的运行环境。查看器还需要图形显示环境。无需克隆仓库；在一个自己可写的工作目录打开终端，先构建产品包，并在同一个 Bash 或 sh 终端把包内命令加入 PATH：

cd /path/to/your-workspace
nix build git+https://git.gjz010.com/gjz010-harness/hakoniwa#hakoniwa
export PATH="$(readlink -f result)/bin:$PATH"
hakoniwa --help

export 只对当前 shell 生效，不会全局安装 hakoniwa；换终端后需要重新执行。首次构建会下载输入并编译，可能耗时。若当前就在仓库根目录，构建命令可简写为 nix build .#hakoniwa。准备完成后，启动桌面：

hakoniwa start --name my-desktop
hakoniwa exec -s my-desktop -- mousepad
hakoniwa viewer -s my-desktop

示例使用调用目录下的默认数据目录，要求 my-desktop 尚不存在。若之后切换目录，请固定 HAKONIWA_ROOT，否则 -s my-desktop 找不到原会话。

查看器在前台运行。关闭查看器后，可以截图与停止桌面：

hakoniwa screenshot -s my-desktop ./desktop.png
hakoniwa stop -s my-desktop

普通停止会请求应用关闭；遇到未保存文档时保留会话，供你处理保存提示。只有明确接受丢失未保存内容时，才使用 stop -s my-desktop --force。会话选择、ps、输出模式和 fish 补全等细节见 CLI 使用说明。完整的前置条件、目录约定和 SDK 安装见入门指南。

查看与接管

查看器提供全屏显示、控制权切换和音频开关，不自动同步宿主剪贴板。关闭查看器不会关闭桌面。了解查看器行为 →

脚本编排

@hakoniwa/sdk 通过同一个 CLI 控制桌面，适合将应用操作串成可重复执行的工作流。SDK 以本地 npm 归档随 Nix 包提供；使用 hakoniwa run ./my-flow.ts 执行自己的脚本。

安装与运行方式见入门指南，完整示例见 examples/orchestration/main.ts。

文档站

文档站直接读取仓库中的公开 Markdown，不维护第二套内容。公开页面清单维护在 apps/docs/src/lib/public-content.json，包括本 README、第三方许可说明，以及 docs 中面向使用者的指南与参考。站点同时提供品牌资源、产品截图、许可证和编排示例 main.ts 的明文下载。需要 Node 24 与 Yarn 4，在仓库根目录安装并启动：

yarn install
yarn docs:dev

浏览器打开 http://127.0.0.1:4321。构建与本地预览：

yarn docs:build
yarn docs:preview
yarn docs:check

yarn docs:build 输出到 apps/docs/dist，yarn docs:check 运行 Astro 严格 TypeScript 检查。文档站单独构建，不改变现有产品 yarn build 的行为。

文档

文档	内容
入门指南	会话管理、查看器、常用操作和 SDK
CLI 使用说明	会话选择、ps、输出模式和 fish 补全
插件	默认与可选插件、配置和开发参考
架构与技术栈	组件职责、通信路径与隔离边界
开发指南	环境配置、构建和测试
文档索引	公开指南、协议与打包参考入口

运行边界

默认桌面使用 headless 输出，renderer 默认 auto，优先真实 GPU 的 GLES2；没有可用 GPU 时使用 pixman 软件合成。可显式选择 GPU 与单个 DRM 物理输出，部署权限、共享与独占边界见 gpu 插件。GPU 渲染不等于硬件视频编码；真实声卡和查看器的物理麦克风权限流程需另行验证。会话隔离桌面服务、剪贴板与虚拟音频，但不应视为运行不可信代码的完整安全边界。大型应用需要另行提供。

许可证

Hakoniwa 采用 Apache License 2.0。第三方组件保留各自许可证，详见第三方许可说明。