最小净空高度

英语 | 日本语

英语

______________________________________________________________________

用于编码代理的面部和操作员配套应用程序。

概览

通过手机控制您的PC编码代理 --通过移动浏览器批准、键入或说出命令。
与Claude Code、Codex CLI和Gemini CLI配合使用 --在终端中运行的任何代理。
tmux操作员桥 在浏览器UI和代理窗格之间中继输入/输出。
3D人脸+TTS+MCP信令 给你的代理人一个反映其状态的声音和表情。
多代理支持 （实验性）——在具有权限预设和持久任务跟踪的隔离工作树中生成辅助代理。看多代理指南.
Tailscale 服务 用于从手机或平板电脑进行安全的远程访问。

特性

操作员输入 --终端直接提示、浏览器PTT（JA/EN ASR）、文本回退、桌面 Space/Shift+Space 坚持谈论安全、关键控制(Esc, ↑, Select, ↓)
终端镜像 --500ms的只读tmux尾部快照仅更改间隔；线条以本机宽度水平滚动渲染，在触摸设备上，您可以捏住缩放（固定在手指下），双击重置
多代理 （实验性）--从桌面互动程序或移动列表、权限预设、任务分配和交付、所有者收件箱中生成/聚焦/删除助手。看多代理指南.
MCP信号 — face.event / face.say / face.ping 加上代理生命周期工具(agent.list, agent.spawn, agent.focus, agent.delete, agent.assign, agent.assignment.list, agent.inject, agent.report, owner.inbox.*)
三维面 --眉毛/眼睛/嘴巴/头部动画，状态模式(confused, frustration, confidence, urgency, stuckness, neutral)，拖动控制，面板切换
文本转语音 --Kokoro ONNX+Misaki默认，可选Qwen3 TTS日语后端，新鲜优先语音策略。看 TTS和语音指南.
自动语音识别 --长尾小鹦鹉批次，可选Voxtral实时。看操作员堆栈和ASR指南.
镜子 WebXR支持路径

系统流程图

静态导出：高级流PNG, 序列时间线PNG, 高级流SVG, 序列时间线SVG

高水位流量

flowchart LR
  U[User]
  TMUX[tmux Terminal
Agent pane]
  C[Coding Agent]
  MCP[MCP Server
face_event / face_say / face_ping]
  WS[face-app
WebSocket + HTTP :8765]
  FE[Frontend UI
Browser]
  BR[operator-bridge]
  ASRP[/POST /api/operator/asr/]
  ASR[asr-worker
Parakeet ASR
JA/EN]
  TTS[tts-worker
Kokoro TTS]
  TS[Tailscale VPN / serve]

  U -- Direct prompt --> TMUX
  U -- PTT recording --> FE
  U -- Text input --> FE

  FE -- Audio binary --> ASRP
  ASRP -- JSON (audioBase64,mimeType,lang) --> ASR
  ASR -- JSON transcript --> ASRP
  ASRP -- Transcript --> FE

  FE -- operator_response JSON --> WS
  WS -- relay --> BR
  BR -- tmux send-keys --> TMUX
  TMUX --> C
  C -- Work logs / results --> TMUX

  BR -- capture-pane (500ms, change-only) --> BR
  BR -- operator_terminal_snapshot --> WS
  WS --> FE

  C -- stdio tool calls --> MCP
  MCP -- WebSocket JSON --> WS
  WS --> FE

  WS -- say payload --> TTS
  TTS -- audio + tts state --> FE

  FE  TS
  TS  WS

序列时间线

sequenceDiagram
  autonumber
  participant U as User
  participant TS as Tailscale (optional)
  participant FE as Frontend UI
  participant FA as face-app (:8765, /ws, /api/operator/asr)
  participant ASR as asr-worker (Parakeet)
  participant BR as operator-bridge
  participant TM as tmux (Agent pane)
  participant CX as Coding Agent
  participant MCP as mcp-server
  participant TTS as tts-worker (Kokoro)

  opt Remote access
    U->>TS: Open Face UI URL
    TS->>FE: Serve forwarded UI
  end

  FE->>FA: Connect WebSocket /ws
  BR->>FA: Connect WebSocket /ws

  alt Input path A: direct terminal prompt
    U->>TM: Type prompt
    TM->>CX: Prompt arrives
  else Input path B: frontend PTT
    U->>FE: Hold PTT JA/EN
    FE->>FA: POST /api/operator/asr?lang=ja|en (audio)
    FA->>ASR: /v1/asr/ja|en (audioBase64,mimeType)
    ASR-->>FA: Transcript JSON
    FA-->>FE: Transcript response
    U->>FE: Tap Send
    FE->>FA: operator_response{text}
    FA-->>BR: Relay payload
    BR->>TM: tmux send-keys(text + Enter)
    TM->>CX: Prompt arrives
  else Input path C: frontend text
    U->>FE: Enter text + Send Text
    FE->>FA: operator_response{text}
    FA-->>BR: Relay payload
    BR->>TM: tmux send-keys(text + Enter)
    TM->>CX: Prompt arrives
  end

  loop During work
    CX-->>TM: Progress/result logs
    BR->>TM: capture-pane -e (500ms)
    BR-->>FA: operator_terminal_snapshot
    FA-->>FE: Terminal mirror update
  end

  CX->>MCP: face_event / face_say / face_ping
  MCP->>FA: Forward WebSocket JSON
  FA-->>FE: event/say/state payloads

  FA->>TTS: TTS request
  TTS-->>FA: tts_audio / tts_mouth / say_result
  FA-->>FE: Realtime status + audio
  FE-->>U: Voice, facial state, and status updates

需求

Node.js 20+（建议使用Node 24）
uv （适用于Python worker依赖关系）
Python 3.10+
ffmpeg （推荐；ASR worker回退解码用于webm/ogg/mp4）
Linux上声音TTS的可选功能：

- 要么PortAudio(libportaudio2)for sounddevice - 或ALSA aplay 后备方案

快速开始

根据你的目标选择一条创业道路。开始之前，请为MCP配置编码代理（请参阅代理设置)，设置特定代理 AGENTS.md，并反映 doc/examples/AGENT_RULES.md 在代理说明中。如果你想要一个现成的粘贴起点，请使用 doc/examples/AGENTS.sample.md 作为本地项目的模板 AGENTS.md.

如果您计划远程使用移动UI，提前启动Tailscale Serve会很方便：

tailscale serve --bg 8765

绑定到0.0.0.0用于docker/远程代理

若MCP客户端在docker或其他网络命名空间中运行，则face-app必须绑定到非环回地址。集 FACE_WS_HOST=0.0.0.0 在您的shell环境中。

当绑定外部环回时， MH_FACE_AUTH_TOKEN 是必需的。使用长随机令牌并保持操作系统防火墙/Tailscale边界不变：

export FACE_WS_HOST=0.0.0.0
export MH_FACE_AUTH_TOKEN="$(openssl rand -base64 32)"

没有 MH_FACE_AUTH_TOKEN，face应用程序拒绝启动 0.0.0.0.令牌保护HTTP API和WebSocket端点；静态UI文件仍然是公共的，因此浏览器可以引导，然后将令牌附加到API/WS调用。

当绑定到 0.0.0.0，除非被阻止，否则可以从LAN访问端口8765。如果您不希望LAN设备访问它，请在操作系统防火墙处明确拒绝LAN接口（保留 lo, tailscale0，以及 docker0 未被触碰，因此尾秤和集装箱仍然可以使用）：

sudo ufw deny in on  to any port 8765 proto tcp

替换 ` 使用您的实际以太网/Wi-Fi名称（例如 enp129s0, eth0, wlan0；检查 ip -brief addr`).

对于Tailscale Serve，使用令牌打开UI一次：

https://:8443/?auth_token=

浏览器将其存储在 sessionStorage，脸书应用程序也设置了 mh_face_auth 同一来源的饼干。然后清除可见的URL，这样移动主屏幕快捷方式就不需要将令牌保留在URL中。

本地浏览器访问方式相同：打开 http://127.0.0.1:8765/?auth_token= 一次并将结果页面添加书签。没有 ?auth_token=...，静态UI加载，但 /api/agents/state 返回401，仪表板显示 agent state error.

如果UFW（或其他主机防火墙）设置为默认拒绝传入，Docker将从非环回容器桥接到主机端口 8765 / 8081 也被封锁了。明确允许Docker默认地址池。UFW在大多数发行版上被禁用，直到 sudo ufw enable；检查 sudo ufw status。如果您是第一次在远程计算机上配置UFW，请运行 sudo ufw allow OpenSSH 之前 sudo ufw enable 为了避免把自己锁在外面。

sudo ufw allow from 172.16.0.0/12 to any port 8765 proto tcp comment 'docker → face-app'
sudo ufw allow from 172.16.0.0/12 to any port 8081 proto tcp comment 'docker → llm backend'
sudo ufw reload

172.16.0.0/12 涵盖了Linux上Docker的默认地址池。首先验证您的实际桥梁：

docker network ls -q | xargs -I{} docker network inspect {} --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}'

如果Docker已被重新配置为不同的池（例如 10.200.0.0/16 通过 daemon.json)，或者如果您的局域网本身位于 172.16/12 （一些公司网络确实如此——检查 ip -brief addr)，将规则缩小到特定的Docker网络子网（例如 172.20.0.0/16)并将该子网固定在组合中/ docker network create 因此，它不会偏离娱乐的轨道。使用典型的家庭局域网(192.168/16 或 10/8)和股票Docker 172.16/12 规则保留LAN和Tailnet(100.64/10)封锁。

令牌必须存在于启动face应用程序的shell、操作员网桥以及MCP服务器转发到face应用程序中的任何代理CLI中。如果你把它放在里面 ~/.config/minimum-headroom.env 源自于 .bashrc，也来源于 ~/.profile （或启动器包装器），因此非交互式和GUI启动的代理继承了它。从401 MCP WebSocket恢复： set -a; . ~/.config/minimum-headroom.env; set +a 在启动shell中，然后重新启动代理。

路径A：面+MCP（最小）

从存储库根目录：

./scripts/setup.sh
./scripts/run-face-app.sh

然后，在另一个终端中：

./scripts/run-mcp-server.sh

当您想要简单的面部UI和信号，而不需要完整的操作面板工作流时，请使用此路径。 run-face-app.sh 默认情况下隐藏操作面板。

如果您的编码代理已经从其自己的MCP客户端配置启动了此存储库的MCP服务器，则不要同时运行 ./scripts/run-mcp-server.sh.
默认情况下， face-app 开始 tts-worker 除非你 FACE_TTS_ENABLED=0 已设置。默认后端为Kokoro；如果 face-app 进程启动时 TTS_ENGINE=qwen3，生成的worker将使用可选的Qwen3路径。

路径B：全移动运营商堆栈（推荐）

之后 ./scripts/setup.sh，建议一次性启动：

./scripts/run-operator-once.sh --profile realtime

当您需要完整的tmux支持的操作员工作流程、浏览器PTT、终端镜像、隐藏的移动恢复和最安全的默认桥接布线时，请使用此功能 --profile default 或 --profile realtime 除非你特别想要Qwen3-TTS。

run-operator-once.sh / run-operator-stack.sh 发射 face-app，以及 face-app 开始 tts-worker 默认情况下，除非 FACE_TTS_ENABLED=0 已设置。 qwen3 / qwen3-realtime 配置文件通过传递工作 TTS_ENGINE=qwen3 进入这条催生的工人之路。
run-operator-once.sh 出口 MH_FACE_AGENT_ID=__operator__ / MH_FACE_AGENT_LABEL=Operator 对于操作员窗格，集成操作员堆栈将其可选的MCP服务器绑定到相同的标识。助手窗格在生成时获得其分配的助手id；基于Docker的助手命令通过以下方式接收它 docker exec -e.
MCP面部工具自动填充 agent_id 从 MH_FACE_AGENT_ID 当他们的MCP服务器进程具有该绑定时，使用补救指南拒绝不匹配的显式id。如果您的MCP客户端运行单独的未绑定服务器，请通过 agent_id 明确地在每 face_ping, face_event，以及 face_say 呼叫，使用 MH_FACE_AGENT_ID 作为真理的源泉。
--agent-cmd 仅控制主操作员窗格。 MH_AGENT_DEFAULT_CMD 辅助代理启动模板是否由使用 face-app 稍后添加助手时。如果该辅助模板以开头 docker exec，最小净空插入每个助手 MH_FACE_AGENT_ID / MH_FACE_AGENT_LABEL 随着 docker exec -e；否则，它会在助手命令前加上前缀 env ...。参见操作员堆栈指南以Docker为例。
个人资料简写：

- --profile default：仅限Kokoro TTS+批量ASR - --profile realtime：Kokoro TTS+Voxtral实时ASR+长尾小鹦鹉回退 - --profile qwen3：仅限Qwen3 TTS+批量ASR - --profile qwen3-realtime：Qwen3-TTS+Voxtral实时ASR+长尾小鹦鹉回退

当您使用此应用程序在另一个存储库上工作时，请将项目放在本地 AGENTS.md 在该目标存储库中也是如此。起点 doc/examples/AGENTS.sample.md，然后在那里自定义特定于仓库的构建/测试/运行规则。
对于另一个存储库，您可以用以下任一等效样式启动运算符：

- 从该存储库运行并传递 --repo /path/to/target-repo - 或 cd 进入目标存储库并启动 /path/to/MinimumHeadroom/scripts/run-operator-once.sh ...

启动后，可以从浏览器UI或MCP工具生成和管理多代理助手。看多代理指南完整的工作流程。

有用的变体：

# work on another repository while keeping minimum-headroom as the operator shell
./scripts/run-operator-once.sh --profile realtime --repo /path/to/target-repo

# work from the target repository itself and call the script by absolute path
cd /path/to/target-repo
/path/to/MinimumHeadroom/scripts/run-operator-once.sh --profile realtime

# start with a shell in the agent pane first
./scripts/run-operator-once.sh --profile realtime --agent-shell

# resume an existing Codex conversation
./scripts/run-operator-once.sh --agent-cmd 'codex resume --last'

# keep the current shell instead of attaching to tmux
./scripts/run-operator-once.sh --profile realtime --no-attach

# choose Qwen3 TTS only when you want that path explicitly
./scripts/run-operator-once.sh --profile qwen3-realtime

代理设置

不要提交您的个人本地配置文件。

克劳德代码

通过CLI添加MCP服务器：

claude mcp add --transport stdio \
  --env FACE_WS_URL=ws://127.0.0.1:8765/ws \
  minimum-headroom -- /ABS/PATH/minimum-headroom/scripts/run-bound-mcp-server.sh

看 Claude代码设置详细信息用于权限预设和安全强化。

Codex CLI

使用 doc/examples/codex/config.toml 作为模板。地点： ~/.codex/config.toml 或 .codex/config.toml 在一个值得信赖的项目中。更新计算机的绝对路径。

[mcp_servers.minimum_headroom]
command = "/ABS/PATH/minimum-headroom/scripts/run-bound-mcp-server.sh"
args = []
env = { "FACE_WS_URL" = "ws://127.0.0.1:8765/ws", "MCP_TOOL_NAME_STYLE" = "underscore" }

run-bound-mcp-server.sh 启动MCP服务器并保留 MH_FACE_AGENT_ID / MH_FACE_AGENT_LABEL 从当前代理进程或其父进程（如果可用）。这让 face_ping, face_event，以及 face_say 省略 agent_id 在“最小净空”启动的操作员/助手窗格中。

当面部应用程序绑定到环回外部并需要 MH_FACE_AUTH_TOKEN，the 相同的包装转发 MH_FACE_AUTH_TOKEN 根据当前环境父进程，或来自 MH_FACE_ENV_FILE。默认的env文件为 ~/.config/minimum-headroom.env.将真正的代币从Codex中取出配置文件。

Gemini CLI

使用 doc/examples/antigravity/mcp_config.json 作为模板。发生在 ~/.gemini/ 或本地项目 .gemini/ 文件夹。双子座需要 MCP_TOOL_NAME_STYLE=underscore.

{
  "mcpServers": {
    "minimum-headroom": {
      "command": "/ABS/PATH/minimum-headroom/scripts/run-bound-mcp-server.sh",
      "args": [],
      "env": {
        "FACE_WS_URL": "ws://127.0.0.1:8765/ws",
        "MCP_TOOL_NAME_STYLE": "underscore"
      }
    }
  }
}

看 Gemini设置详细信息用于权限预设和AGENTS.md指南。

代理说明

放置一个 AGENTS.md 在目标存储库根目录中（使用 doc/examples/AGENTS.sample.md 作为起始模板）。
包括来自的信号规则 doc/examples/AGENT_RULES.md 在代理说明中。
对于Claude Code，您还可以使用 CLAUDE.md 了解克劳德的具体项目说明。

工具名称样式

如果您的MCP客户端拒绝带有点的工具名称（例如 face.event)，设置环境 MCP_TOOL_NAME_STYLE=underscore。然后将工具发布为 face_event, face_say, face_ping.

详细指南

操作员堆栈和ASR指南 --启动器选择、tmux桥、操作员UI、键盘快捷键、隐藏移动恢复、批处理/实时ASR、Tailscale远程操作
TTS和语音指南 --Kokoro和Qwen3设置、语音门、长语音行为、合成前文本规范化
多代理指南 --生成助手、权限预设、任务分配、所有者收件箱、工作台隔离、安全强化

钩桥（遗忘脸安全网）

scripts/mh-hook.mjs 是一个映射每个代理运行时钩子的小型包装器事件a face_say + face_event （以及帮助者的所有者收件箱条目），所以即使客服忘记打电话，脸也会说话 face_say 自愿。目前支持Claude Code、Codex（新 hooks 系统+遗留 notify 回退）和Gemini CLI。

配置：

每个运行时示例（插入JSON/TOML）： doc/hook-bridge/
嵌入在每运行时设置README中： doc/examples/claude-code/README.md, doc/examples/codex/config.toml, doc/examples/antigravity/README.md

钩子只有在以下情况下才会着火 MH_FACE_AGENT_ID 在代理进程中设置环境，因此同一台机器上无关的Claude/Codex/Gemini会话不受影响。模板（每个活动上的台词）在 ~/.minimum-headroom/face-templates.json；如果不存在，则内置使用日语+英语默认值。语言从中自动检测代理人最近 face_say 历史（CJK→ ja，否则→ en)，与 MH_FACE_LANG 作为退路。

Codex在启动时自动过滤不受信任的钩子，因此是一次性的信任授予编辑后需要 ~/.codex/config.toml信任是持久的 [hooks.state.*] 在用户层面——一旦获得授权，每个后续的Codex 该用户的会话（包括由生成的助手 agent.spawn)继承它是自动的。您不需要输入单个助手窗格。这最简单的方法是 ./scripts/grant-codex-hook-trust.sh （产生短暂的 Codex位于私有tmux服务器内，遍历信任UI，退出）。手动：运行任何Codex一次，键入 /hooks，浏览浏览器，然后退出。仅重新授予当您更改钩子命令或匹配器时。看 doc/hook-bridge/README.md 对于整个过程。

可选代理技能

此存储库包括以下可重用的技能包 doc/examples/skills/:

release-ci-flow
minimum-headroom-ops
looking-glass-webxr-setup

每个文件夹都包含一个 SKILL.md 并且可以复制到您的本地技能目录中（例如 $CODEX_HOME/skills/)如果您的代理支持本地技能加载。

如果您使用的是最小净空运算符/助手运行时，请安装 minimum-headroom-ops它涵盖了预期的MCP生命周期流程(agent.list, agent.spawn, agent.assign, agent.inject, agent.assignment.list, owner.inbox.*, agent.delete)以及助手报告合同。

发布检查表

运行测试：

npm test

验证MCP启动：

./scripts/run-mcp-server.sh

验证面部应用程序启动和浏览器渲染：

./scripts/run-face-app.sh

验证TTS工人吸烟情况：

npm run tts-worker:smoke

验证ASR工作人员是否吸烟：

npm run asr-worker:smoke

验证操作员堆栈启动（在tmux内部或使用 MH_BRIDGE_TMUX_PANE 设置）：

./scripts/run-operator-stack.sh

存储库注释

运行时/本地文件（模型、本地MCP配置、缓存、venv）通过以下方式排除 .gitignore.

日本语

是面向编码代理的面部操作员支援应用程序。

全体像（要点）

从智能手机操作电脑编码代理 —您可以在移动浏览器中发送批准、输入和语音命令。
Claude Code、Codex CLI、Gemini CLI に対応 —任何在终端运行的代理都可以使用。
tmux操作员桥 将在浏览器UI和代理窗格之间中继输入和输出。
三维面+TTS+MCP信令 中的代理提供声音和表情，实时反映状态。
支持多代理（实验性）—在隔离工作树中生成helper，通过权限预设和任务跟踪进行管理。多代理指南请参照。
Tailscale 服务 从智能手机/平板电脑安全远程访问。

机能

操作员输入 —终端直接输入、浏览器PTT（JA/EN ASR）、文本输入、Desktop Space/Shift+Space 长按安全装置、按键操作（Esc, ↑, Select, ↓）
终端反射镜 —tmux尾部输出的只读快照（500毫秒，仅在更改时）。实际机器的宽度原封不动地被描绘，长行横滚动。在触摸终端中，以手指的位置为中心进行夹持变焦、双击等倍恢复
多代理（实验性）—从桌面平铺或移动列表中生成/聚焦/删除helper、权限预设、任务分配分发、owner inbox。多代理指南请参照。
MCP信令 — face.event / face.say / face.ping 和代理生命周期工具（agent.list, agent.spawn, agent.focus, agent.delete, agent.assign, agent.assignment.list, agent.inject, agent.report, owner.inbox.*）
三维面 —眉毛、眼睛、嘴巴、头部的动画、状态模式（confused, frustration, confidence, urgency, stuckness, neutral）、拖动控制、面板切换
文本转语音 —Kokoro ONNX+Misaki默认、任意Qwen3-TTS日语backend、新鲜度优先发言策略。TTS和语音指南请参照。
自动语音识别 --长尾小鹦鹉批次、任意 Voxtral实时操作员堆栈和ASR指南请参照。
镜子 WebXR 対応経路

系统流程图

静态导出：高级流PNG, 序列时间线PNG, 高级流SVG, 序列时间线SVG

高电平流动

flowchart LR
  U[ユーザー]
  TMUX[tmux ターミナル
Agent ペイン]
  C[Coding Agent]
  MCP[MCP サーバー
face_event / face_say / face_ping]
  WS[face-app
WebSocket + HTTP :8765]
  FE[フロントエンド UI
ブラウザ]
  BR[operator-bridge]
  ASRP[/POST /api/operator/asr/]
  ASR[asr-worker
Parakeet ASR
JA/EN]
  TTS[tts-worker
Kokoro TTS]
  TS[Tailscale VPN / serve]

  U -- 直接プロンプト --> TMUX
  U -- PTT録音 --> FE
  U -- テキスト入力 --> FE

  FE -- 音声バイナリ --> ASRP
  ASRP -- JSON (audioBase64,mimeType,lang) --> ASR
  ASR -- 文字起こしJSON --> ASRP
  ASRP -- 文字起こし結果 --> FE

  FE -- operator_response JSON --> WS
  WS -- relay --> BR
  BR -- tmux send-keys --> TMUX
  TMUX --> C
  C -- 作業ログ / 結果 --> TMUX

  BR -- capture-pane (500ms, change-only) --> BR
  BR -- operator_terminal_snapshot --> WS
  WS --> FE

  C -- stdio tool calls --> MCP
  MCP -- WebSocket JSON --> WS
  WS --> FE

  WS -- say payload --> TTS
  TTS -- audio + tts state --> FE

  FE  TS
  TS  WS

时间序列

sequenceDiagram
  autonumber
  participant U as ユーザー
  participant TS as Tailscale (任意)
  participant FE as Frontend UI
  participant FA as face-app (:8765, /ws, /api/operator/asr)
  participant ASR as asr-worker (Parakeet)
  participant BR as operator-bridge
  participant TM as tmux (Agent pane)
  participant CX as Coding Agent
  participant MCP as mcp-server
  participant TTS as tts-worker (Kokoro)

  opt リモートアクセス
    U->>TS: Face UI URLを開く
    TS->>FE: 転送されたUIを表示
  end

  FE->>FA: WebSocket /ws 接続
  BR->>FA: WebSocket /ws 接続

  alt 入力経路A: 端末直接入力
    U->>TM: プロンプトを入力
    TM->>CX: プロンプト到達
  else 入力経路B: フロントエンドPTT
    U->>FE: PTT JA/EN を押下
    FE->>FA: POST /api/operator/asr?lang=ja|en (audio)
    FA->>ASR: /v1/asr/ja|en (audioBase64,mimeType)
    ASR-->>FA: 文字起こしJSON
    FA-->>FE: 文字起こし結果
    U->>FE: Send を押下
    FE->>FA: operator_response{text}
    FA-->>BR: payload relay
    BR->>TM: tmux send-keys(text + Enter)
    TM->>CX: プロンプト到達
  else 入力経路C: フロントエンドテキスト
    U->>FE: テキスト入力 + Send Text
    FE->>FA: operator_response{text}
    FA-->>BR: payload relay
    BR->>TM: tmux send-keys(text + Enter)
    TM->>CX: プロンプト到達
  end

  loop 作業中
    CX-->>TM: 進捗/結果ログ
    BR->>TM: capture-pane -e (500ms)
    BR-->>FA: operator_terminal_snapshot
    FA-->>FE: ターミナルミラー更新
  end

  CX->>MCP: face_event / face_say / face_ping
  MCP->>FA: WebSocket JSON転送
  FA-->>FE: event/say/state payloads

  FA->>TTS: TTS request
  TTS-->>FA: tts_audio / tts_mouth / say_result
  FA-->>FE: リアルタイム状態 + 音声
  FE-->>U: 音声・表情・状態を表示

必要环境

Node.js 20+（Node 24 推奨）
uv（Python worker依存管理）
Python 3.10+
ffmpeg（推荐。用于ASR worker的webm/ogg/mp4回退解码）
在Linux上输出声音时（可选）：

- PortAudio(libportaudio2) + sounddevice - 或ALSA aplay

快速启动

请根据需要选择启动路径。开始前，使用编码代理进行MCP设置（代理设置），面向代理 AGENTS.md 选项卡页面上创建或编辑条目doc/examples/AGENT_RULES.md 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。如果需要马上就能使用的雏形的话doc/examples/AGENTS.sample.md 项目名称 AGENTS.md 中所述修改相应参数的值。

如果要远程使用移动UI，请先启动Tailscale Serve。

tailscale serve --bg 8765

以0.0.0.0绑定到docker/远程代理

在MCP客户端在另一网络命名空间（如docker）中运行的配置中，必须将face-app绑定到回送以外的位置。在壳环境中 FACE_WS_HOST=0.0.0.0 中所述修改相应参数的值。

在动态输入提示中单击MH_FACE_AUTH_TOKEN 对较大场景进行渲染期间已观察到该故障。请设置长随机token，并保持操作系统firewall/Tailscale边界。

export FACE_WS_HOST=0.0.0.0
export MH_FACE_AUTH_TOKEN="$(openssl rand -base64 32)"

MH_FACE_AUTH_TOKEN 缺少 0.0.0.0 将条目添加到文档注册表。此token保护HTTP API和WebSocket。静态UI文件保持公开状态，以便浏览器先启动，然后在API/WS上添加token。

0.0.0.0 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。如果不想让LAN终端触摸，请在OS防火墙中明确拒绝LAN接口（lo / tailscale0 / docker0 tailscale容器将保持不变，因为它不会被触摸到）：

sudo ufw deny in on  to any port 8765 proto tcp

` 是实际的有线/Wi-Fi名称（例如： enp129s0, eth0, wlan0、ip -brief addr` 中所述修改相应参数的值。

通过Tailscale Serve，请只打开第一次带token的URL。

https://:8443/?auth_token=

浏览器是 sessionStorage 中保存token，face-app也同样是origin的 mh_face_auth 设置cookie。之后，为了从显示URL中删除token，不需要在移动的主页画面快捷方式中留下带token的URL。

电脑浏览器的本地访问也是同样的步骤。http://127.0.0.1:8765/?auth_token= 只打开第一次，如果把那个状态做书签的话，从下次开始就点击一次。?auth_token=... 无需打开时，即使导入了静态UI /api/agents/state 变成401，在仪表板上 agent state error 中找到最佳实践。

UFW等host firewall default deny incoming 中所述修改相应参数的值8765 / 8081 的ingress也会下降，所以请明确允许Docker默认address pool。在很多迪斯特罗，UFW sudo ufw enable 进行动态观察时的轴心点sudo ufw status 查看项目中可用的所有族。首次在远程计算机上设置UFW时，为了防止锁定 sudo ufw enable 的，之前的 sudo ufw allow OpenSSH 来修改标记元素的显示属性。

sudo ufw allow from 172.16.0.0/12 to any port 8765 proto tcp comment 'docker → face-app'
sudo ufw allow from 172.16.0.0/12 to any port 8081 proto tcp comment 'docker → llm backend'
sudo ufw reload

172.16.0.0/12 是Linux上标准Docker的默认地址池的覆盖范围。请先查看实际的bridge：

docker network ls -q | xargs -I{} docker network inspect {} --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}'

daemon.json 的，之 default-address-pools 中的另一个范围（例如： 10.200.0.0/16），或者LAN本身 172.16/12 （有时在企业LAN上ip -brief addr 中确认）是特定Docker network的subnet（例如： 172.20.0.0/16），模板名称将采用不同的格式docker network create 请在/compose侧固定subnet，防止重新制作时的偏差。家庭局域网（192.168/16 啊 10/8）+如果是标准Docker的典型结构172.16/12 在规则中使用LAN和Tailnet（100.64/10）继续被拒绝。

token将进行face-app·operator bridge·MCP forwarding的agent CLI 要启动的壳中所述修改相应参数的值。~/.config/minimum-headroom.env 的 .bashrc 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。~/.profile 但是请source，或者用启动包装器传递env。当MCP的WebSocket在401中掉落时，在启动壳中 set -a; . ~/.config/minimum-headroom.env; set +a 之后由应用程序进行调用。

Path A: Face + MCP（最小构成）

./scripts/setup.sh
./scripts/run-face-app.sh

然后，在另一个航站楼：

./scripts/run-mcp-server.sh

这适用于只想使用简单的face UI和信令的情况。run-face-app.sh 默认情况下，隐藏operator panel。

如果正在使用编码代理从MCP客户端设置自动启动该存储库的MCP服务器./scripts/run-mcp-server.sh 请不要双重启动。
默认情况下 face-app 的 tts-worker 来定义自定义外观FACE_TTS_ENABLED=0 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。默认backend为Kokoroface-app 打开 TTS_ENGINE=qwen3 中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。

Path B:Full Mobile Operator Stack（推荐）

./scripts/setup.sh 建议运行后启动一次：

./scripts/run-operator-once.sh --profile realtime

这是tmux协作browser PTT、terminal mirror、它是最实用的配置，包括隐式恢复和bridge安全的默认布线。如果没有特别想使用Qwen3TTS理由--profile default 啊 --profile realtime 请从…开始。

run-operator-once.sh / run-operator-stack.sh 啊 face-app 启动，然后单击 face-app 默认值 tts-worker 中所述修改相应参数的值。FACE_TTS_ENABLED=0 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。qwen3 / qwen3-realtime 此子启动的工件 TTS_ENGINE=qwen3 中所述修改相应参数的值。
run-operator-once.sh 在operator pane上 MH_FACE_AGENT_ID=__operator__ / MH_FACE_AGENT_LABEL=Operator 导出，集成operator stack的任意启动MCP server也绑定到相同的identity。helper pane接受spawn时分配的helper id，通过Docker的helper command docker exec -e 将条目添加到文档注册表。
MCP face tools为MCP server process MH_FACE_AGENT_ID 框中，选择“默认值”agent_id 中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。在MCP client启动其他未绑定server的结构中MH_FACE_AGENT_ID 为正 face_ping / face_event / face_say 全部call agent_id 中所述修改相应参数的值。
--agent-cmd 仅指定primary operator pane。MH_AGENT_DEFAULT_CMD 在以后添加helper时 face-app 将条目添加到文档注册表。这个helper模板 docker exec 开始时，最小高度 MH_FACE_AGENT_ID / MH_FACE_AGENT_LABEL 的 docker exec -e 的双曲正切值。如果不是Docker env ... 将条目添加到文档注册表。Docker的具体例子是操作员堆栈指南来修改标记元素的显示属性。
简介含义：

- --profile default：仅限Kokoro TTS+batch ASR - --profile realtime：Kokoro TTS+Voxtral实时ASR+长尾小鹦鹉回退 - --profile qwen3：仅限Qwen3TTS+batch ASR - --profile qwen3-realtime：Qwen3-TTS+Voxtral实时ASR+长尾小鹦鹉回退

使用这个应用程序处理其他的工作资料库的时候，那个target repository方面也有project-local AGENTS.md 请放下。doc/examples/AGENTS.sample.md 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。
在另一个工作存储库中使用的启动方法有以下两种。

- 从这个存储库侧 --repo /path/to/target-repo 启动 - 向target repository侧 cd 自从…以后 /path/to/MinimumHeadroom/scripts/run-operator-once.sh ... 呼唤

关于启动后的多代理操作多代理指南来修改标记元素的显示属性。

常用派生示例：

# minimum-headroom を operator shell として使いながら、別 repo を作業対象にする
./scripts/run-operator-once.sh --profile realtime --repo /path/to/target-repo

# target repository 側から absolute path で script を呼ぶ
cd /path/to/target-repo
/path/to/MinimumHeadroom/scripts/run-operator-once.sh --profile realtime

# まず agent ペインをシェルだけで開く
./scripts/run-operator-once.sh --profile realtime --agent-shell

# 直前の Codex セッションを再開
./scripts/run-operator-once.sh --agent-cmd 'codex resume --last'

# 起動だけ行い、現在のシェルを維持
./scripts/run-operator-once.sh --profile realtime --no-attach

# Qwen3 TTS を使いたい時だけ明示的に選ぶ
./scripts/run-operator-once.sh --profile qwen3-realtime

代理设置

不要将个人本地配置文件提交到存储库。

克劳德代码

在CLI中添加MCP服务器：

claude mcp add --transport stdio \
  --env FACE_WS_URL=ws://127.0.0.1:8765/ws \
  minimum-headroom -- /ABS/PATH/minimum-headroom/scripts/run-bound-mcp-server.sh

有关权限预设和安全增强的详细信息，请参见 Claude代码设置请参照。

Codex CLI

doc/examples/codex/config.toml 作为模板~/.codex/config.toml 或在项目中 .codex/config.toml 中描述的相应参数的值。绝对路径请配合各自的环境。

[mcp_servers.minimum_headroom]
command = "/ABS/PATH/minimum-headroom/scripts/run-bound-mcp-server.sh"
args = []
env = { "FACE_WS_URL" = "ws://127.0.0.1:8765/ws", "MCP_TOOL_NAME_STYLE" = "underscore" }

run-bound-mcp-server.sh 启动MCP server，如果可能，请从当前的agent process或父process MH_FACE_AGENT_ID / MH_FACE_AGENT_LABEL 的支持。在从最低高度启动的operator/helper pane中 face_ping / face_event / face_say 的，之 agent_id 可以省略。

将face-app bind到回环外 MH_FACE_AUTH_TOKEN 时褪色为此颜色相同的wrapper是当前环境、父进程和MH_FACE_ENV_FILE 从 MH_FACE_AUTH_TOKEN 中所述修改相应参数的值。默认的env file ~/.config/minimum-headroom.env 是。实际token为Codex config 请不要办理入住手续。

Gemini CLI

doc/examples/antigravity/mcp_config.json 作为模板~/.gemini/ 或在项目中 .gemini/ 中描述的相应参数的值。Gemini是 MCP_TOOL_NAME_STYLE=underscore 中所述修改相应参数的值。

{
  "mcpServers": {
    "minimum-headroom": {
      "command": "/ABS/PATH/minimum-headroom/scripts/run-bound-mcp-server.sh",
      "args": [],
      "env": {
        "FACE_WS_URL": "ws://127.0.0.1:8765/ws",
        "MCP_TOOL_NAME_STYLE": "underscore"
      }
    }
  }
}

关于权限预设和AGENTS.md的详细信息 Gemini设置请参照。

Hook桥（face_say安全网）

代理 face_say 忘记呼叫，等待批准而沉默的情况下，或者没有最终report turn结束的情况下，从运行时的hook机构自动说出face的结构。Claude Code/Codex（新 hooks 系列）/Gemini CLI对应。

下拉列表设置示例： doc/hook-bridge/
在每个运行时的setup README（Claude/Codex/Gemini）中也刊登了同样的片段
详细设置步骤： doc/hook-bridge/README.md

MH_FACE_AGENT_ID 如果未将hook设置为agent process，则hook将以exit0结束，因此不会影响无关的其他session。发言模板是 ~/.minimum-headroom/face-templates.json 中描述的场景，使用下列步骤创建明细表，以便在概念设计中分析体量的周长。语言是最近的 face_say 根据履历自动判定（CJK文字→ ja除此之外 en）、MH_FACE_LANG 后退。

Codex在启动user-defined hook时作为untrusted silent skip~/.codex/config.toml 在动态输入提示中单击 只有一次 需要trust授予。trust是user-level的 [hooks.state.*] 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。不需要每次进入helper pane进行trust操作。

最简单的是 ./scripts/grant-codex-hook-trust.sh 的方法（在背面竖起一个短命codex自动trust→结束）。手动做的时候用平时使用的codex做一次 /hooks 对话框，您可以在此定义自定义格式。只在编辑hook的command/matcher时需要重新trust。了解更多信息 doc/hook-bridge/README.md。

设置代理说明

在target repository的根上 AGENTS.md 对齐doc/examples/AGENTS.sample.md 作为模板）。
doc/examples/AGENT_RULES.md 的信令规约包含在代理指示中。
对于Claude Code CLAUDE.md 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

工具名称样式

MCP客户机为带点的工具名（例如： face.event）时，环境变量 MCP_TOOL_NAME_STYLE=underscore 中所述修改相应参数的值。工具是 face_event, face_say, face_ping 中所述修改相应参数的值。

详细指南

操作员堆栈和ASR指南 —如何选择启动脚本tmux bridge、operator UI、键盘快捷键batch / realtime ASR、隐式恢复，Tailscale远程操作
TTS和语音指南 —Kokoro/Qwen3的设置、发话门、长句发话、发话前的正规化
多代理指南 —生成helper、权限预设、任务分配、owner inbox、worktree隔离、安全增强

可选技能

doc/examples/skills/ 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

release-ci-flow
minimum-headroom-ops
looking-glass-webxr-setup

每个文件夹都包含 SKILL.md 支持的代理具有本地技能目录（例如： $CODEX_HOME/skills/）来定义自定义外观。

使用minimum-headroom的operator/helper runtime时minimum-headroom-ops 对较大场景进行渲染期间已观察到该故障。agent.list, agent.spawn, agent.assign, agent.inject, agent.assignment.list, owner.inbox.*, agent.delete 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。

发放核对表

测试运行：

npm test

MCP起动确认：

./scripts/run-mcp-server.sh

face-app启动和浏览器显示确认：

./scripts/run-face-app.sh

TTS worker smoke确认：

npm run tts-worker:smoke

ASR工人吸烟確認:

npm run asr-worker:smoke

operator stack起动确认（tmux内or MH_BRIDGE_TMUX_PANE 指定）:

./scripts/run-operator-stack.sh

补足

运行时本地文件（模型、本地MCP设置、高速缓存、venv等） .gitignore 中所述修改相应参数的值。

Minimum Headroom

快速接入

详细介绍

最小净空高度

英语

目录

概览

特性

系统流程图

高水位流量

序列时间线

需求

快速开始

绑定到0.0.0.0用于docker/远程代理

路径A：面+MCP（最小）

路径B：全移动运营商堆栈（推荐）

代理设置

克劳德代码

Codex CLI

Gemini CLI

代理说明

工具名称样式

详细指南

钩桥（遗忘脸安全网）

可选代理技能

发布检查表

存储库注释

日本语

目次

全体像（要点）

机能

系统流程图

高电平流动

时间序列

必要环境

快速启动

以0.0.0.0绑定到docker/远程代理

Path A: Face + MCP（最小构成）

Path B:Full Mobile Operator Stack（推荐）

代理设置

克劳德代码

Codex CLI

Gemini CLI

Hook桥（face_say安全网）

设置代理说明

工具名称样式

详细指南

可选技能

发放核对表

补足

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP