Chobits

一个住在 Zellij 终端里、由 LLM 驱动的跨平台 Live2D 终端桌宠。

• Linux
• macOS†
• Windows*

† 针对 macOS 发布的预编译二进制文件未经过 Apple 公证，可能被 Gatekeeper 拦截。您可以选择从源码构建，或按照 Apple 官方说明手动放行。

* 在 Windows 上编译需要 MSYS2 UCRT64 或 MINGW64。编译生成的二进制文件可直接在原生 Windows 上运行，无需 MSYS2。

您可以通过以下命令安装最新版本的 Chobits。安装器会自动将 chobits-start 命令加入用户 PATH，并在终端打印 config.toml 的 [llm] 配置示例。

需要 Bash 或 Zsh。默认安装位置：~/.local/share/Chobits。

. <(curl -LsSf https://raw.githubusercontent.com/NewComer00/Chobits/main/scripts/install.sh)

需要 Bash 或 Zsh。默认安装位置：~/.local/share/Chobits。

安装完成后请重新打开终端，PATH 修改才会生效。

curl -LsSf https://raw.githubusercontent.com/NewComer00/Chobits/main/scripts/install.sh | sh

Chobits 的相关命令可能被 Gatekeeper 拦截（提示 operation not permitted），请按照 Apple 官方说明手动放行。

需要 PowerShell 5.1 及以上版本。默认安装位置：%LOCALAPPDATA%\Chobits。

irm https://raw.githubusercontent.com/NewComer00/Chobits/main/scripts/install.ps1 | iex

首次运行前，请先编辑 config.toml。默认路径为 ~/.local/share/Chobits/config.toml（Linux / macOS）或 %LOCALAPPDATA%\Chobits\config.toml（Windows）。

找到配置文件中的 [llm] 部分，Chobits 支持以下 LLM 后端：

Ollama（本地推理）

[llm]
backend    = "ollama"
url        = "http://localhost:11434"
model      = "qwen3:0.6b"
max_tokens = 512

OpenAI 兼容接口（backend 填写除 ollama 以外的任意值）

[llm]
backend    = "deepseek"
url        = "https://api.deepseek.com"
model      = "deepseek-v4-flash"
max_tokens = 512
api_key    = "sk-..."

🎉 至此一切就绪，执行 chobits-start 命令即可启动 Chobits！🚀

手动安装请参考从发行版下载或从源码构建。完整配置项说明见配置章节。

wget https://github.com/NewComer00/Chobits/releases/latest/download/Chobits-x86_64-unknown-linux-musl.tar.gz
tar -xzf Chobits-x86_64-unknown-linux-musl.tar.gz

curl -LO https://github.com/NewComer00/Chobits/releases/latest/download/Chobits-aarch64-apple-darwin.tar.gz
tar -xzf Chobits-aarch64-apple-darwin.tar.gz

Invoke-WebRequest -Uri "https://github.com/NewComer00/Chobits/releases/latest/download/Chobits-x86_64-pc-windows-gnu.zip" -OutFile "Chobits-x86_64-pc-windows-gnu.zip"
Expand-Archive -Path "Chobits-x86_64-pc-windows-gnu.zip" -DestinationPath .

pacman -S ${MINGW_PACKAGE_PREFIX}-{git,git-lfs,rust,rust-wasm,jq,wget,gcc} unzip make
cargo install cargo-binstall  # 首次编译可能需要一些时间

git lfs install
git clone --depth 1 https://github.com/NewComer00/Chobits.git
cd Chobits
# git checkout v0.2.0   # 可选：切换到指定发行版标签
./scripts/build.sh --locked -y

mkdir -p install/Chobits

cargo install --path "crates/chobits-start" --root install/Chobits

for c in "" "-bar"; do cargo install --path "crates/chobits$c" --root install/Chobits/local; done
cargo install --path crates/chobits-zellij --root install/Chobits/local --target wasm32-wasip1

cargo install --git https://github.com/NewComer00/live-ascii --root install/Chobits/local

# 从 Cargo.toml 读取版本号，确保与插件兼容
ZELLIJ_VER=$(cargo metadata --format-version 1 | jq -r '.packages[] | select(.name == "zellij-tile") | .version')

# 从源码编译：
cargo install zellij --version ${ZELLIJ_VER} --root install/Chobits/local

# 或使用 cargo-binstall 获取预编译二进制：
# cargo binstall zellij@${ZELLIJ_VER} --root install/Chobits/local

# MSYS2 UCRT64/MINGW64 用户也可直接从 GitHub Releases 下载预编译二进制：
# wget https://github.com/zellij-org/zellij/releases/download/v${ZELLIJ_VER}/zellij-x86_64-pc-windows-msvc.zip
# unzip zellij-x86_64-pc-windows-msvc.zip -d install/Chobits/local/bin

python tool/list_vts_hotkeys.py   # 查看当前模型的 VTS 热键名称

mkdir -p install/Chobits/models
wget https://cubism.live2d.com/sample-data/bin/hiyori/hiyori_en.zip
unzip hiyori_en.zip
cp hiyori_free install/Chobits/models/ -r

cp example_config.toml install/Chobits/config.toml

cargo fmt --all --check && cargo clippy-all && cargo test-all && cargo check -p chobits-zellij --target wasm32-wasip1

Chobits/
├── .chobits-root
├── bin/
│   └── chobits-start          # Windows 下为 .exe
├── config.toml
├── .zellij/                   # Zellij 配置/数据（[zellij] 路径）
├── .chobits/
│   └── vts_token.json           # VTS 插件认证 token（首次连接后自动创建）
├── local/
│   └── bin/
│       ├── chobits
│       ├── chobits-bar
│       ├── chobits-zellij.wasm
│       ├── live-ascii
│       └── zellij               # Windows 下为 .exe
└── models/
    └── hiyori_free/
        └── runtime/
            └── hiyori_free_t08.model3.json  （含贴图、动作等）

所有配置集中在 Chobits 根目录下的 config.toml 文件中。快速安装的默认配置文件位于 ~/.local/share/Chobits/config.toml（Linux / macOS）或 %LOCALAPPDATA%\Chobits\config.toml（Windows）。

您在配置文件里填写的路径可以是绝对路径，也可以是相对于 Chobits 根目录（即 config.toml 所在目录）的相对路径，与启动位置无关。

驱动桌宠回应的 LLM 后端。可接入任意 Ollama 或 OpenAI 兼容 API。

Ollama 示例：

[llm]
backend    = "ollama"
url        = "http://localhost:11434"
model      = "qwen3:0.6b"
max_tokens = 512

其他 OpenAI 兼容服务示例（backend != "ollama"）：

[llm]
backend    = "deepseek"
url        = "https://api.deepseek.com"
model      = "deepseek-v4-flash"
max_tokens = 512
api_key    = "sk-..."

定义桌宠角色的个性，将影响角色每一次回答时的风格。

[persona]
name        = "Chi"
description = """
Curious and warm terminal companion.
You speak in short, casual reactions — one or two sentences max.
You genuinely care about what the user is working on.
"""

控制 Zellij 插件捕获当前焦点面板快照（文本）的方式和频率。快照会被截断到 max_bytes，然后通过 Zellij 的 web_request API 以 HTTP POST 发送到 http://127.0.0.1:{port}/snapshot（仅本地回环，不对外网暴露）。守护进程在空闲时将变化的快照转发给 LLM。

若焦点面板内容自上次轮询以来未发生变化，守护进程将跳过 LLM 调用以节省 token。

[snapshot]
port          = 7880
max_bytes     = 4096
interval_secs = 10

控制 chobits-bar 滚动面板。鼠标滚轮可翻阅历史；只有当您已在底部时，新消息才会自动滚动。按 q、Esc 或 Ctrl+C 退出反应栏面板。

[bar]
port           = 7879
history_length = 50

[live-ascii]
model_set      = "models/hiyori_free/runtime/hiyori_free_t08.model3.json"
enable_vts     = true
vts_port       = 8001
enable_mouse   = true
enable_physics = true
image_protocol = "halfblock"
bg_color       = "rgba(0,0,0,0)"
scale          = "550%"
offset_x       = "0%"
offset_y       = "95%"

[zellij]
config_dir = ".zellij/config"
data_dir   = ".zellij/data"
layout     = """
layout {
    pane size=1 borderless=true {
        plugin location="tab-bar"
    }
    pane split_direction="vertical" {
        pane size=1 borderless=true command="{chobits_bin}" {
            args "--quiet"
        }
        pane focus=true
        pane split_direction="horizontal" size="30%" {
            pane command="{live_ascii_bin}" name="LIVE-ASCII" {
                args {live_ascii_args}
            }
            pane command="{chobits_bar_bin}" size="30%" borderless=true
        }
        pane size=1 borderless=true {
            plugin location="file:{plugin_path}" {
                snapshot_port "{snapshot_port}"
                interval_secs "{interval_secs}"
                max_bytes "{max_bytes}"
            }
        }
    }
    pane size=1 borderless=true {
        plugin location="status-bar"
    }
}
"""

┌─────────────────────┬──────────┐
│   终端              │live-ascii│
│   (zellij 原生      │          │
│    含插件           ├──────────┤
│    通过面板滚动区   │  回应栏  │
│    轮询快照)        │(ratatui) │
└─────────────────────┴──────────┘

[idle]
idle_timeout_secs = 30

[vts]
url                  = "ws://127.0.0.1:8001"
plugin_name          = "Chobits"
developer            = "Chobits"
auth_token_path      = ".chobits/vts_token.json"
connect_timeout_secs = 30

[vts.motion_alias]
idle      = "Idle #2"
happy     = "Idle #1"
thinking  = "Flick #0"       # LLM 等待动画；也用于 LLM 响应中的 thinking 标签
worried   = "Flickdown #0"
surprised = "Tap #0"
sad       = "Flick@Body #0"

# 带 .exp3.json 表情的模型可添加 [vts.expression_alias]
# happy = "My Expression Name"

使用快速开始安装器安装后，在任意目录执行：

chobits-start

手动安装或从发行版解压后，在能访问 Chobits 根目录的位置执行：

Chobits/bin/chobits-start

配置文件位于 <Chobits 根目录>/config.toml。首次运行前请先编辑 [llm]。示例参见快速开始。

首次启动会自动创建新的 Zellij 会话。后续运行时，chobits-start 会自动检测并重连已有会话；若存在多个会话，会提示您选择。

在 Zellij 中按 Ctrl+o 再按 d 可分离会话而不终止它，再次运行 chobits-start 即可重新连接。按 Ctrl+q 或关闭所有面板可彻底退出会话。

将参数直接传递给内置的 Zellij 实例：

chobits-start zellij <args>

# 示例
chobits-start zellij ls                  # 列出所有会话
chobits-start zellij attach --session <name>
chobits-start zellij --help

这等价于使用正确的隔离路径执行 zellij --config-dir ... --data-dir ... <args>，无需手动指定路径。

chobits-start 启动 Zellij，其中运行守护进程、live-ascii、chobits-bar 和 chobits-zellij WASM 插件。默认本地端口：

数据流（客户端连接时）：

chobits-start ──▶ zellij 会话（布局来自 config.toml）
                      │
chobits-zellij ──get_pane_scrollback──▶ 快照 JSON
                      │
                      └──HTTP POST :7880──▶ chobits ──┬── TCP:7879 ──▶ chobits-bar
                                              ├── HTTP REST ──▶ LLM 后端
                                              └── WebSocket:8001 ──▶ live-ascii (--vts)

客户端分离（detach）时，插件跳过面板轮询。

布局（Zellij 内部）：

flowchart TB
    subgraph Zellij["Zellij 会话"]
        direction LR
        Terminal["主终端\nchobits-zellij 插件"]
        Daemon["chobits 守护进程"]
        LiveAscii["live-ascii"]
        Bar["chobits-bar"]
    end

    LLM["LLM 后端\n(Ollama 或兼容 API)"]

    Terminal -->|"HTTP POST :7880"| Daemon
    Daemon -->|"HTTP REST"| LLM
    Daemon -->|"WebSocket :8001"| LiveAscii
    Daemon -->|"TCP :7879"| Bar

从运行中的 live-ascii 实例查询热键（需要 pip install websockets）：

# 终端 1：带 --vts 启动 live-ascii
# 终端 2：
python tool/list_vts_hotkeys.py

将输出的热键 name 填入 config.toml 的 [vts.motion_alias] 或 [vts.expression_alias]。

• NewComer00/live-ascii（派生自 Arcelyth/live-ascii，Copyright (c) 2026 Arcelyth，MIT 许可证）

MIT