### Start desktop app with npm start

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Launches the desktop application.

```bash
npm start
```

--------------------------------

### Start Release Console UI

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-update-release.md

Start the local web UI for release management.

```bash
npm run release:ui
```

--------------------------------

### Start Recording

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/focus-banner.html

Starts recording audio from the microphone and sets up audio processing.

```javascript
async function startRecording() { if (isRecording) { stopRecording(); return } if (!backendPort) { setTranscript(t('focus.waitingBackend'), 'interim'); return } try { micStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false }) } catch { setTranscript(t('focus.allowMic'), 'interim') setVoiceBtnState('error') return } audioCtx = new AudioContext({ sampleRate: 16000 }) const src = audioCtx.createMediaStreamSource(micStream) scriptProcessor = audioCtx.createScriptProcessor(4096, 1, 1) src.connect(scriptProcessor) scriptProcessor.connect(audioCtx.destination) scriptProcessor.onaudioprocess = (e) => { if (!cloudWs || cloudWs.readyState !== WebSocket.OPEN) return const f32 = 
```

--------------------------------

### Start backend only with npm run start:backend

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Starts only the local backend server.

```bash
npm run start:backend
```

--------------------------------

### Run LAN mode and backend with npm run start:lan and npm run start:backend:lan

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Uses the repository's startup scripts to run the app in LAN mode and start the backend with LAN support.

```bash
npm run start:lan
npm run start:backend:lan
```

--------------------------------

### Install Dependencies for Target Architecture

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Install dependencies with the target architecture and verify the platform and architecture.

```bash
npm install
node -p "process.platform + ' ' + process.arch"
```

--------------------------------

### Start secure LAN mode with npm run start:lan

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Starts the app in secure LAN mode, generating a long-term local root certificate and an HTTPS certificate for the current LAN address. Outputs the root certificate installation address and an HTTPS access URL with a pairing token.

```bash
npm run start:lan
```

--------------------------------

### Build Windows installer

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Install dependencies and build the Windows installer. Only x64 is supported and must run in an x64 Windows Node process. The build checks for Windows-specific binaries and runs a smoke test on the produced artifact.

```bash
npm ci
npm run build:win
```

--------------------------------

### 记录失败命令和平台信息

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

如果 install 或 postinstall 失败，先记录失败命令和平台信息。

```bash
node --version
npm --version
node -p "process.platform + ' ' + process.arch"
xcode-select -p
```

--------------------------------

### Install dependencies with npm install

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Installs project dependencies before running the application.

```bash
npm install
```

--------------------------------

### Development startup commands

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to start the application in development mode: launch the Electron app, start only the backend, or start the backend in watch mode.

```bash
npm start
```

```bash
npm run start:backend
```

```bash
npm run dev
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Install Xcode Command Line Tools if xcode-select or xcrun swiftc is missing.

```bash
xcode-select --install
```

--------------------------------

### GET /settings

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves a summary of settings.

```APIDOC
## GET /settings

### Description
Retrieves a summary of settings.

### Method
GET

### Endpoint
/settings

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### Localization Setup

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/focus-banner.html

Initializes localization and sets the voice transcript placeholder.

```javascript
import { localizeDom, observeDomLocalization, t, translateUiText } from './src/ui/brain-ui/i18n/index.js'
```

```javascript
localizeDom(document)
```

```javascript
observeDomLocalization(document.body)
```

```javascript
document.getElementById('voiceTranscript').dataset.placeholder = t('focus.voicePlaceholder')
```

--------------------------------

### Debug npm Install or Postinstall Failures

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to debug npm install or postinstall failures.

```bash
npm install --foreground-scripts
npm ls electron electron-builder better-sqlite3
```

--------------------------------

### Windows Release Command

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/cross-platform-update-release.md

Build and sign the Windows x64 installer.

```powershell
npm run release:win
```

--------------------------------

### Check and Install Xcode Command Line Tools

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to check and install Xcode Command Line Tools.

```bash
xcode-select -p
xcrun --sdk macosx swiftc --version
```

```bash
xcode-select --install
```

--------------------------------

### Surface JSON Structure Example

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/SCENE-PROTOCOL.md

Example of the surface structure in JSON with comments, showing required and optional fields and their constraints. Use for creating surfaces in scene updates.

```jsonc
{
  "id": "weather-bj",     // 必填。稳定身份;shell 靠它在帧间追踪同一元素做过渡动画
  "kind": "weather",      // 必填。渲染端词汇表中的一种,见 §6
  "data": { ... },        // 必填。语义内容,纯数据;结构由 kind 定义。无内容用 {}
  "intent": "inform",     // 选填。语义重要性:ambient | inform | confront。缺省 inform
  "focus": false,         // 选填。是否当前焦点;同一时刻最多一个 surface 为 true。缺省 false
  "order": 0,             // 选填。排序权重,见 §5.2。缺省按数组顺序
  "data_rev": 7           // 选填。data 的内容版本号,便于 shell 判断是否需 morph。缺省不提供
}
```

--------------------------------

### Initialization and intervals

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/brain-ui/worldcup-broadcast-v2.html

Initialization calls: start clocks, set intervals for updates, fit the view, and load initial data.

```javascript
tickTopClock(); setInterval(tickTopClock, 1000); setInterval(tickHeroClock, 1000); setInterval(() => { if (MODE === 'real') load(); }, 120000); fit(); load();
```

--------------------------------

### Run backend in dev mode with npm run dev

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Starts the backend in development mode with automatic restart on changes.

```bash
npm run dev
```

--------------------------------

### ui.set API and Scene Manifest

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/Agent-驱动UI-设计方案.md

Two code examples: the first shows the ui.set API with idempotent upsert and removal semantics; the second shows a compact manifest of current UI surfaces with id, kind, summary, and intent.

```javascript
ui.set(id, { kind, data, intent, focus })   // 幂等 upsert:第一次是"显示",再调就是"更新"——同一个动作
ui.set(id, null)                              // 置空 = 移除
```

```text
当前界面上的卡片:
- weather-bj  (weather)  「北京 18° 晴」     ambient
- choice-1    (choice)   「现在出门吗?」     confront  ← 焦点
```

--------------------------------

### Canvas visualization setup

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/ACUI (Remix)/Voice Component.html

The main React component that initializes the canvas renderer and manages the animation loop for the point cloud. It handles state transitions for microphone input and uses the states defined in CFG.

```javascript
const { useState, useEffect, useRef } = React;
```

--------------------------------

### GET /settings/tts

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves TTS settings.

```APIDOC
## GET /settings/tts

### Description
Retrieves TTS settings.

### Method
GET

### Endpoint
/settings/tts

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### GET /memories

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Queries memories.

```APIDOC
## GET /memories

### Description
Queries memories.

### Method
GET

### Endpoint
/memories

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### GET /settings/voice

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves voice recognition settings.

```APIDOC
## GET /settings/voice

### Description
Retrieves voice recognition settings.

### Method
GET

### Endpoint
/settings/voice

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### Check Signature and Gatekeeper

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Check Gatekeeper assessment and verify code signing of the installed app.

```bash
spctl --assess --verbose "/Applications/Bailongma.app"
codesign --verify --deep --strict --verbose=2 "/Applications/Bailongma.app"
```

--------------------------------

### macOS Remote Build Commands

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-remote-build-quickstart.md

Commands for checking the environment, installing dependencies, building macOS packages, verifying artifacts, and reporting results.

```bash
node --version
npm --version
git --version
xcode-select -p
xcrun --sdk macosx swiftc --version
```

```bash
xcode-select --install
```

```bash
git clone <repo-url> bailongma
cd bailongma
git status --short --branch
git log -1 --oneline
```

```bash
npm install
```

```bash
node -p "process.arch"
file "$(which node)"
```

```bash
npm run build:mac
```

```bash
npm run build:mac:arm64
```

```bash
npm run build:mac:x64
```

```bash
ls -lh dist
```

```bash
npm run smoke:mac-artifacts
```

```bash
git log -1 --oneline
ls -lh dist
```

--------------------------------

### GET /quota

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves quota and rate limit information.

```APIDOC
## GET /quota

### Description
Retrieves quota and rate limit information.

### Method
GET

### Endpoint
/quota

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### GET /status

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves the current running status of the application.

```APIDOC
## GET /status

### Description
Retrieves the running status.

### Method
GET

### Endpoint
/status

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### GET /events

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Subscribes to the SSE event stream for real-time updates.

```APIDOC
## GET /events

### Description
Subscribes to the SSE event stream.

### Method
GET

### Endpoint
/events

### Parameters
None

### Response
#### Success Response (200)
- SSE stream of events

```

--------------------------------

### GET /settings/heartbeat

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves the heartbeat switch and default interval.

```APIDOC
## GET /settings/heartbeat

### Description
Retrieves the heartbeat switch and default interval.

### Method
GET

### Endpoint
/settings/heartbeat

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### postinstall 脚本

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

`postinstall` 脚本会运行 `install-app-deps`，为 Electron 安装或重建原生应用依赖。

```bash
node ./node_modules/electron-builder/cli.js install-app-deps
```

--------------------------------

### Get DOM element by id

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/brain-ui/worldcup-broadcast.html

Helper function to get DOM element by id.

```javascript
const $ = (id) => document.getElementById(id);
```

--------------------------------

### 默认 macOS 构建命令

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

运行 `npm run build:mac` 会依次构建两个架构（x64 和 arm64）。

```bash
npm run build:mac
```

--------------------------------

### CSS for startup page layout and animations

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/electron/startup.html

Styles the startup page with a shell grid, step list, progress bar, and status colors. Includes a pulse animation and responsive adjustments for narrow screens.

```css
text-overflow: ellipsis; } .state { color: var(--soft); font-size: 12px; font-variant-numeric: tabular-nums; } .running .state { color: var(--accent); } .done .state { color: var(--ok); } .error .state { color: var(--error); } @keyframes pulse { 0%, 100% { box-shadow: 0 0 0 0 rgba(86, 214, 178, 0.22); } 50% { box-shadow: 0 0 0 7px rgba(86, 214, 178, 0); } } @media (max-width: 860px) { body { overflow: auto; } .shell { min-height: auto; grid-template-columns: 1fr; align-items: start; padding: 28px; } .steps { max-height: none; } .step-list { max-height: none; } h1 { font-size: 38px; } }
```

--------------------------------

### Linux Release Command

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/cross-platform-update-release.md

Build the Linux x64 AppImage.

```bash
npm run release:linux
```

--------------------------------

### 构建命令等价序列

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

`npm run build:mac` 等价于依次执行以下命令，分别构建 x64 和 arm64 架构的 DMG。

```bash
node scripts/prebuild-clean.mjs
node scripts/build-macos-speech.mjs x64 --required
node ./node_modules/@electron/rebuild/lib/cli.js -f -w better-sqlite3 -v 33.4.11 -a x64
node ./node_modules/electron-builder/cli.js --mac dmg --x64
node scripts/build-macos-speech.mjs arm64 --required
node ./node_modules/@electron/rebuild/lib/cli.js -f -w better-sqlite3 -v 33.4.11 -a arm64
node ./node_modules/electron-builder/cli.js --mac dmg --arm64
```

--------------------------------

### POST /admin/start

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Resumes the main loop.

```APIDOC
## POST /admin/start

### Description
Resumes the main loop.

### Method
POST

### Endpoint
/admin/start

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### Handshake: hello and welcome messages

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/SCENE-PROTOCOL.md

Shell sends hello with identity and capabilities; core responds with welcome including scene revision. Shell must not assume screen state before receiving first scene.

```jsonc
// shell → core
{ "v": 1, "type": "hello", "shell": "cinematic", "shellVersion": "0.1.0", "caps": ["scene", "patch"] }

// core → shell
{ "v": 1, "type": "welcome", "rev": 0, "serverVersion": "2.1.x" }
```

--------------------------------

### Check Platform and Reinstall Dependencies

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to check platform/architecture and reinstall dependencies.

```bash
node -p "process.platform + ' ' + process.arch"
npm ls better-sqlite3 electron @electron/rebuild
rm -rf node_modules
npm install
```

--------------------------------

### GET /conversations

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Queries recent conversations.

```APIDOC
## GET /conversations

### Description
Queries recent conversations.

### Method
GET

### Endpoint
/conversations

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### POST /activate

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Writes Provider configuration and activates the application.

```APIDOC
## POST /activate

### Description
Writes Provider configuration and activates the application.

### Method
POST

### Endpoint
/activate

### Parameters
#### Request Body
- (not specified in source)

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### JavaScript for live scene projection

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/scene-shell/index.html

Creates a Shell instance and a SceneClient connected to ws://127.0.0.1:3721/scene. Forwards user intents to the core via client.sendIntent, applies incoming scenes to the shell, and updates the status indicator based on connection state.

```javascript
// live 测试页:连接运行中的 app,把真实 scene 投影出来。
import { Shell } from './shell.js'
import { SceneClient } from './client.js'

const stage = document.getElementById('stage')
const status = document.getElementById('status')
const statusText = document.getElementById('status-text')

const shell = new Shell(stage, {
  onIntent: (intent) => {
    // 用户交互 → 上行给 core。shell 只显示与上报,绝不在此做业务决策。
    console.log('[intent →]', intent)
    client.sendIntent(intent)
  },
})

const client = new SceneClient('ws://127.0.0.1:3721/scene', {
  onScene: (scene) => shell.applyScene(scene),
  onStatus: (state) => {
    status.dataset.state = state
    statusText.textContent = { connecting: '连接中…', open: '已连接', closed: '已断开 · 重连中…' }[state] || state
  },
})

client.connect()

window.addEventListener('beforeunload', () => client.close())
```

--------------------------------

### Gatekeeper Warning Messages

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Example Gatekeeper warning messages.

```text
"Bailongma.app" cannot be opened because Apple cannot check it for malicious software.
```

```text
"Bailongma.app" is damaged and can't be opened. You should move it to the Trash.
```

--------------------------------

### JavaScript for startup progress UI and bridge integration

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/electron/startup.html

Initializes localization, renders startup progress steps, updates elapsed time, and subscribes to fullscreen and progress events from the bailongma bridge.

```javascript
import { localizeDom, observeDomLocalization, t, translateUiText } from '../src/ui/brain-ui/i18n/index.js' localizeDom(document) observeDomLocalization(document.body) const fallbackSteps = [ ['port', t('startup.port'), t('startup.portDetail')], ['core', t('startup.core'), t('startup.coreDetail')], ['resources', t('startup.resources'), t('startup.resourcesDetail')], ['tools', t('startup.tools'), t('startup.toolsDetail')], ['api', t('startup.api'), t('startup.apiDetail')], ]; const messageEl = document.getElementById('message'); const percentEl = document.getElementById('percent'); const fillEl = document.getElementById('fill'); const stepsEl = document.getElementById('steps'); const elapsedEl = document.getElementById('elapsed'); const versionEl = document.getElementById('version'); let startedAt = Date.now(); let latestState = { startedAt, percent: 0, message: t('startup.preparing'), steps: fallbackSteps.map(([id, label, detail]) => ({ id, label, detail, status: 'pending' })), }; function stateText(status) { if (status === 'done') return t('startup.done'); if (status === 'running') return t('startup.running'); if (status === 'error') return t('startup.failed'); return t('startup.waiting'); } function render(state) { if (!state) return; latestState = state; startedAt = state.startedAt || startedAt; const percent = Math.max(0, Math.min(100, Number(state.percent) || 0)); messageEl.textContent = translateUiText(state.message || t('startup.preparing')); percentEl.textContent = `${percent}%`; fillEl.style.width = `${percent}%`; stepsEl.replaceChildren(); for (const step of state.steps || []) { const item = document.createElement('div'); item.className = `step ${step.status || 'pending'}`; const dot = document.createElement('div'); dot.className = 'dot'; item.appendChild(dot); const copy = document.createElement('div'); copy.className = 'copy'; const label = document.createElement('div'); label.className = 'label'; label.textContent = translateUiText(step.label || step.id || ''); const detail = document.createElement('div'); detail.className = 'detail'; detail.textContent = translateUiText(step.detail || ''); copy.append(label, detail); item.appendChild(copy); const stateLabel = document.createElement('div'); stateLabel.className = 'state'; stateLabel.textContent = stateText(step.status); item.appendChild(stateLabel); stepsEl.appendChild(item); } updateElapsed(); } function updateElapsed() { const elapsed = Math.max(0, Date.now() - (latestState.startedAt || startedAt)); elapsedEl.textContent = `${(elapsed / 1000).toFixed(1)}s`; } render(latestState); setInterval(updateElapsed, 200); const bridge = window.bailongma; if (bridge) { const setFullScreenClass = (fullscreen) => { document.documentElement.classList.toggle('window-fullscreen', Boolean(fullscreen)); }; bridge.onFullScreenChange?.(setFullScreenClass); bridge.isFullScreen?.().then(setFullScreenClass).catch(() => {}); bridge.getVersion?.().then((version) => { if (version) versionEl.textContent = `Desktop Agent ${version}`; }).catch(() => {}); bridge.getStartupProgress?.().then(render).catch(() => {}); bridge.onStartupProgress?.(render); }
```

--------------------------------

### GET /social/wechat-clawbot/qr

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Retrieves the WeChat bridge QR code status.

```APIDOC
## GET /social/wechat-clawbot/qr

### Description
Retrieves the WeChat bridge QR code status.

### Method
GET

### Endpoint
/social/wechat-clawbot/qr

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### 构建 universal 语音 helper 命令

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

运行 `npm run build:mac:universal-speech` 会使用 `lipo` 创建 universal 的 `build/native-speech-recognizer`，但不会打包 universal `.app` 或 universal DMG。

```bash
npm run build:mac:universal-speech
```

--------------------------------

### Serve scene-shell for offline demo

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/scene-shell/README.md

Commands to serve the scene-shell directory for offline demo.

```powershell
npx serve src/ui/scene-shell        # 然后访问 http://localhost:3000/demo.html
```

```powershell
python -m http.server 8000 -d src/ui/scene-shell   # 访问 http://localhost:8000/demo.html
```

--------------------------------

### Build and Upload macOS Release

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-update-release.md

Build and upload macOS release for both architectures.

```bash
npm run release:mac
```

--------------------------------

### Run the Electron WebContentsView CDP integration spike

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/webcontentsview-playwright-mcp.md

Runs the real integration spike that launches an Electron app, creates a Brain UI BrowserWindow and a persistent WebContentsView, attaches through the loopback CDP endpoint, uses the production connectEmbeddedPlaywright connector, navigates to https://example.com, reparents the view between compact and large hosts, restarts Electron, and verifies a persistent cookie.

```sh
node scripts/spike-electron-webcontentsview-cdp.mjs
```

--------------------------------

### 模块边界图

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/Agent-驱动UI-设计方案.md

模块边界图,展示 Agent Core、SceneStore、UI Shell 之间的交互和职责划分。

```text
┌─────────────────────────────────────────────────────────┐
│  Agent Core(完全不知道 UI 长什么样)                       │
│                                                           │
│   ui.set(id, surface|null)  ──┐                           │
│                               ▼                           │
│   SceneStore  ── 唯一真相源:持有当前 scene + rev          │
│        │  发快照 / 补丁                ▲ 收意图            │
└────────┼──────────────────────────────┼──────────────────┘
         │   WebSocket(JSON 消息)        │
┌────────▼──────────────────────────────┼──────────────────┐
│  UI Shell(任意技术栈,可有多款)        │                  │
│                                        │                  │
│   transport ── applyScene(scene) ── kind 注册表           │
│                     │                                     │
│              电影级渲染器 / enter·exit·morph 动画          │
│                     │                                     │
│              用户侧只认 scene 状态和 intent 事件,与渲染技术无关。│
│  shell 侧只认协议消息,与业务逻辑无关。                      │
│  多款 UI = 多个 shell,共享同一份协议与同一个 SceneStore。   │
│  SceneStore 另派生一份紧凑 manifest 回注 Agent 上下文(见 §四),让 Agent 始终知道"屏上有什么"而碰不到像素。│
└─────────────────────────────────────────────────────────┘
```

--------------------------------

### Activation intro screen styles

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/activation.html

CSS for the activation intro screen: positions capability cards with custom properties, styles day cards, and disables animations for users who prefer reduced motion.

```css
.intro-capability-face, .intro-capability-back { min-height: 96px; padding: 12px; } .intro-capability h3 { margin-top: 10px; } .intro-capability:nth-child(1) { --mid-x:-22vw; --mid-y:-14vh; --over-x:-27vw; --over-y:-23vh; --corner-x:-25vw; --corner-y:-22vh; } .intro-capability:nth-child(2) { --mid-x:20vw; --mid-y:-12vh; --over-x:26vw; --over-y:-19vh; --corner-x:24vw; --corner-y:-18vh; } .intro-capability:nth-child(3) { --mid-x:-21vw; --mid-y:13vh; --over-x:-27vw; --over-y:21vh; --corner-x:-25vw; --corner-y:20vh; } .intro-capability:nth-child(4) { --mid-x:21vw; --mid-y:15vh; --over-x:26vw; --over-y:24vh; --corner-x:24vw; --corner-y:23vh; } .intro-day-card { width:min(430px,84vw); padding:18px; border-radius:14px; } .intro-day-index { margin-bottom:13px; } .intro-day-card::after { right:18px; bottom:18px; width:64px; } } @media (prefers-reduced-motion: reduce) { #activation-intro [data-intro-anim] { animation-duration: .01ms !important; } }
```

--------------------------------

### View Application Log

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Command to view the application log.

```bash
tail -n 200 "$HOME/Library/Application Support/Bailongma/logs/bailongma.log"
```

--------------------------------

### Default build command

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Command to run the default build script.

```bash
npm run build
```

--------------------------------

### 检查 Node 架构

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

在 Apple Silicon 上构建前，建议确认当前 Node 架构，避免混用 Rosetta 和原生 shell。

```bash
node -p "process.arch"
file "$(which node)"
```

--------------------------------

### Load Preview Data

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/systemPrompt.html

Fetches the system prompt preview data from the server and updates the UI with counts, messages, directions, conversation, action log, and the final prompt.

```javascript
async function loadPreview() { statusText.textContent = '正在刷新 heartbeat prompt…' statusText.className = '' refreshBtn.disabled = true try { const res = await fetch('/system-prompt-preview') const data = await res.json() if (!res.ok) throw new Error(data.error || 'load failed') conversationCount.textContent = String((data.injection?.conversationWindow || []).length) actionLogCount.textContent = String((data.injection?.actionLog || []).length) memoryCount.textContent = String((data.injection?.memories || []).length) taskKnowledgeCount.textContent = String((data.injection?.taskKnowledge || []).length) messageText.textContent = data.message || '-' directionsText.textContent = (data.injection?.directions || []).join('\n') || '无额外方向提示' conversationText.textContent = formatConversation(data.injection?.conversationWindow || []) actionLogText.textContent = formatActionLog(data.injection?.actionLog || []) promptText.textContent = data.systemPrompt || '' statusText.textContent = `已刷新：聊天 ${conversationCount.textContent} 条，日志 ${actionLogCount.textContent} 条` } catch (err) { promptText.textContent = '' statusText.textContent = `加载失败：${err.message}` statusText.className = 'error' } finally { refreshBtn.disabled = false } }
```

--------------------------------

### Event listeners for resize and boot/exit animations

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/brain-ui/worldcup-broadcast-v2.html

Event listeners for resize, boot animation, and exit message handling.

```javascript
window.addEventListener('resize', fit);
```

```javascript
document.body.classList.add('booting'); setTimeout(() => document.body.classList.remove('booting'), 2200);
```

```javascript
window.addEventListener('message', (event) => { if (event?.data?.type !== 'worldcup-exit') return; document.body.classList.remove('booting'); document.body.classList.add('exiting'); });
```

--------------------------------

### Default build script commands

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Actual commands executed by the default build script.

```text
node scripts/prebuild-clean.mjs
node scripts/build-macos-speech.mjs
node ./node_modules/@electron/rebuild/lib/cli.js -f -w better-sqlite3 -v 33.4.11
node ./node_modules/electron-builder/cli.js
```

--------------------------------

### 开发启动白龙马（macOS/Linux）

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/network-capture-guide.md

在仓库根目录使用 Electron 直接启动白龙马，适用于开发环境。

```sh
./node_modules/.bin/electron .
```

--------------------------------

### Build Artifact Locations and Filenames

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-remote-build-quickstart.md

Locations and typical filenames of build artifacts.

```text
dist/
```

```text
Bailongma-<version>-mac-arm64.dmg
Bailongma-<version>-mac-x64.dmg
*.blockmap
latest-mac.yml
```

--------------------------------

### Verify local tools

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to verify local toolchain before building on macOS.

```bash
node --version
npm --version
xcode-select -p
xcrun --sdk macosx swiftc --version
security find-identity -v -p codesigning
```

--------------------------------

### 支持的架构列表

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

列出 Bailongma 构建支持的架构：x64 和 arm64。

```text
x64
arm64
```

--------------------------------

### Loading Placeholder

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/systemPrompt.html

Placeholder text displayed while the system prompt is loading.

```text
加载中…
```

--------------------------------

### Audio Capture Initialization

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/electron/wake-probe.html

Main function that initializes microphone capture, creates an AudioContext, loads the AudioWorklet module, and connects the audio graph.

```javascript
async function start() { let stream; try { stream = await navigator.mediaDevices.getUserMedia({ // KWS 要原始音频:降噪/回声消除/自动增益都关掉,它们会扭曲语音、害识别 // (模型在干净音频上训练,样本能 100% 命中正因为干净)。 audio: { echoCancellation: false, noiseSuppression: false, autoGainControl: false, channelCount: 1 }, }); } catch (e) { report('mic-denied', e?.name || String(e)); // 麦克风未就绪,稍后重试(权限/设备可能晚到) setTimeout(start, 3000); return; } try { const actx = new AudioContext({ sampleRate: TARGET_SR }); if (actx.state === 'suspended') { try { await actx.resume(); } catch {} } const src = actx.createMediaStreamSource(stream); const blob = new Blob([WORKLET_SRC], { type: 'application/javascript' }); const url = URL.createObjectURL(blob); await actx.audioWorklet.addModule(url); const node = new AudioWorkletNode(actx, 'wake-capture', { numberOfInputs: 1, numberOfOutputs: 1, channelCount: 1, processorOptions: { chunk: CHUNK }, }); node.port.onmessage = (ev) => { // ev.data 是 Float32Array;把其底层 buffer 送主进程 const f32 = ev.data; window.wakeProbe?.sendPcm(f32.buffer); }; src.connect(node); node.connect(actx.destination); // 拉动音频图(输出静音) report('running', 'sr=' + actx.sampleRate); console.log('[wake-probe] 耳朵已开,采样率', actx.sampleRate); } catch (e) { report('error', e?.message || String(e)); console.error('[wake-probe] 启动失败', e); } } start();
```

--------------------------------

### 定时预热缓存流程

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/ACI-理念文档.md

场景 C：定时预热注入。通过 cron 定时任务周期性获取数据并存入 prefetch_cache，带不同有效期。当天唤醒时直接注入缓存结果，无需任何工具调用。确定性最高，不需要意图识别。

```text
每天 08:00 (cron)：
  → 查天气 → 存入 prefetch_cache（有效期 1h）
  → 查热点新闻 → 存入 prefetch_cache（有效期 30min）
  → 读日历 → 存入 prefetch_cache（有效期 24h）

当天任何时候 Jarvis 被唤醒：
  ↓ 注入器：今天的天气/新闻/日历已经在缓存里
  ↓ 直接注入
  ↓ 不需要任何工具调用
```

--------------------------------

### Build View Model

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/brain-ui/worldcup-broadcast-v2.html

Builds a view model from fetched data, categorizing matches into live, finished, upcoming, and today.

```javascript
function buildVM(data) { const ms = (data.matches || []).slice().sort((a, b) => (a.startMs || 0) - (b.startMs || 0)); const now = Date.now(); const live = ms.filter((m) => m.status === 'live'); const finished = ms.filter((m) => m.status === 'finished' && m.score); const upcoming = ms.filter((m) => m.status === 'scheduled' && (m.startMs || 0) > now); […] return { ms, live, finished, upcoming, today, focus, standings: data.standings || {}, news: data.news || [], fetchedAt: data.fetchedAt, stale: !!data.stale, }; […] }
```

--------------------------------

### Build macOS Speech Helper for Target Architectures

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to build the macOS speech helper for arm64 and x64 architectures.

```bash
node scripts/build-macos-speech.mjs arm64 --required
node scripts/build-macos-speech.mjs x64 --required
```

--------------------------------

### 注入器并行预判流程

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/ACI-理念文档.md

注入器新角色：并行执行语义检索、意图匹配和缓存读取，汇总后组装 injection 对象。关键设计是注入器有 1.5s 超时上限，超时则不等慢工具，直接用已有内容。

```text
消息到达
  ├─ [并行] 语义向量检索记忆
  ├─ [并行] 意图匹配 → 触发工具链预执行
  └─ [并行] 读取有效的 prefetch_cache

  ↓ 汇总（deadline = 注入器超时，默认 1.5s）
  ↓ 组装 injection 对象
  ↓ LLM 调用，上下文已就绪
```

--------------------------------

### Upload Only Built Artifacts

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-update-release.md

Upload only the already built artifacts.

```bash
npm run upload:mac
```

--------------------------------

### 置信度注入策略

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/ACI-理念文档.md

置信度机制：根据置信度决定注入方式。高置信度直接注入 system prompt，中等置信度轻提示，低置信度不注入。置信度来源包括模式匹配得分、定时任务（固定 1.0）和规则匹配（固定 0.9）。

```text
置信度 > 0.85  →  直接注入 system prompt（模型看到即用）
置信度 0.5~0.85 →  轻提示："可能需要以下信息，已备好，按需参考"
置信度 < 0.5   →  不注入（避免污染上下文）
```

--------------------------------

### VideoCard component and demo control panel

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/ACUI (Remix)/Video Component.html

JavaScript code for the VideoCard component and demo control panel. It builds a floating video card with close button, iframe embedding, and exposes show/dismiss/resize/setVolume methods. The demo panel wires up source, animation, position, volume, and dismiss controls, and auto-shows a YouTube video on load.

```javascript
alignItems:'center', justifyContent:'center', cursor:'pointer', color:'rgba(255,255,255,0.6)', fontSize:11, fontFamily:'Inter,sans-serif', transition:'all 0.15s', }); closeBtn.textContent = '✕'; closeBtn.onclick = () => dismiss(); closeBtn.onmouseenter = () => { closeBtn.style.background='rgba(0,0,0,0.9)'; closeBtn.style.color='#fff'; }; closeBtn.onmouseleave = () => { closeBtn.style.background='rgba(0,0,0,0.6)'; closeBtn.style.color='rgba(255,255,255,0.6)'; }; card.appendChild(closeBtn); // iframe iframe = document.createElement('iframe'); Object.assign(iframe.style, { width:'100%', height:'100%', border:'none', display:'block', background:'#000', }); iframe.src = p.embed(id, volume, autoplay); iframe.allow = 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture'; iframe.allowFullscreen = true; card.appendChild(iframe); document.getElementById('video-stage').appendChild(card); currentConfig = { ...cfg }; } function dismiss(animate=true) { if (!card) return; if (animate) { card.style.animation = `exitAnim 0.25s ease forwards`; setTimeout(() => { card?.remove(); card = null; iframe = null; }, 260); } else { card.remove(); card = null; iframe = null; } } function resize(preset) { if (!card) return; const ps = PRESETS[preset]; if (!ps) return; Object.assign(card.style, { width: ps.w, height: ps.h, left: ps.x, top: ps.y, transform: `translate(${ps.tx}, ${ps.ty})`, }); currentConfig.preset = preset; } function setVolume(vol) { // Volume control via postMessage for YouTube if (iframe && currentConfig.platform === 'youtube') { try { iframe.contentWindow.postMessage(JSON.stringify({ event:'command', func:'setVolume', args:[vol] }), '*'); } catch(e) {} } currentConfig.volume = vol; } // Expose public API return { show: buildCard, dismiss, resize, setVolume, presets: Object.keys(PRESETS), platforms: Object.keys(PLATFORMS) }; })(); window.VideoCard = VideoCard; /* ══════════════════════════════════════ Demo Control Panel ══════════════════════════════════════ */ const SOURCES = [ { label:'YouTube', platform:'youtube', id:'dQw4w9WgXcQ' }, { label:'YouTube 2', platform:'youtube', id:'jNQXAC9IVRw' }, { label:'bilibili', platform:'bilibili', id:'BV1GJ411x7h7' }, { label:'X 视频', platform:'twitter', id:'1897284610266546524' }, ]; const ANIMS = ['flash','slide-up','slide-right','fade','zoom','glitch']; const POSITIONS = [ { label:'居中', preset:'center' }, { label:'全屏', preset:'fullscreen' }, { label:'右上角', preset:'top-right' }, { label:'左下角', preset:'bottom-left' }, { label:'画中画', preset:'pip' }, ]; let curSrc = SOURCES[0]; let curAnim = 'flash'; let curVol = 80; function btn(text, onClick, active=false) { const b = document.createElement('button'); b.className = 'cbtn' + (active?' active':''); b.textContent = text; b.onclick = onClick; return b; } function setActive(container, clicked) { container.querySelectorAll('.cbtn').forEach(b => b.classList.remove('active')); clicked.classList.add('active'); } // Source buttons const srcC = document.getElementById('src-btns'); SOURCES.forEach((s, i) => { const b = btn(s.label, (e) => { curSrc = s; setActive(srcC, e.target); VideoCard.show({ platform:s.platform, id:s.id, anim:curAnim, preset:'center', volume:curVol, autoplay:true }); }, i===0); srcC.appendChild(b); }); // Anim buttons const animC = document.getElementById('anim-btns'); ANIMS.forEach((a, i) => { const b = btn(a, (e) => { curAnim = a; setActive(animC, e.target); VideoCard.show({ platform:curSrc.platform, id:curSrc.id, anim:a, preset:'center', volume:curVol, autoplay:true }); }, i===0); animC.appendChild(b); }); // Position buttons const posC = document.getElementById('pos-btns'); POSITIONS.forEach((p, i) => { const b = btn(p.label, (e) => { setActive(posC, e.target); if (document.getElementById('vc-card')) { VideoCard.resize(p.preset); } else { VideoCard.show({ platform:curSrc.platform, id:curSrc.id, anim:curAnim, preset:p.preset, volume:curVol, autoplay:true }); } }, i===0); posC.appendChild(b); }); // Volume const volSlider = document.getElementById('vol-slider'); const volLabel = document.getElementById('vol-label'); volSlider.oninput = () => { curVol = parseInt(volSlider.value); volLabel.textContent = curVol + '%'; VideoCard.setVolume(curVol); }; // Dismiss document.getElementById('btn-dismiss').onclick = () => VideoCard.dismiss(); // Auto-show on load setTimeout(() => { VideoCard.show({ platform:'youtube', id:'dQw4w9WgXcQ', anim:'flash', preset:'center', volume:80, autoplay:true }); }, 300);
```

--------------------------------

### macOS x64 build command

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Command to build only the Intel x64 version.

```bash
npm run build:mac:x64
```

--------------------------------

### scene: full snapshot message

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/SCENE-PROTOCOL.md

Core sends complete scene; shell must make screen exactly equal to it, removing extra surfaces and adding missing ones. Sent after handshake, on resync, or when core chooses full over patch.

```jsonc
{
  "v": 1,
  "type": "scene",
  "rev": 42,                 // 见 §4 版本语义
  "surfaces": [ Surface, ... ]   // 见 §5;顺序即「排序意图」,见 §5.2
}
```

--------------------------------

### Build Artifact Verification

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Commands to verify the build artifacts and run smoke checks.

```bash
ls -lh dist
```

```bash
npm run smoke:mac-artifacts
```

```bash
hdiutil attach -readonly -nobrowse dist/Bailongma-2.1.436-mac-arm64.dmg
lipo -archs "/Volumes/<mounted-volume>/Bailongma.app/Contents/MacOS/Bailongma"
lipo -archs "/Volumes/<mounted-volume>/Bailongma.app/Contents/Resources/app.asar"
lipo -archs "/Volumes/<mounted-volume>/Bailongma.app/Contents/Resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node"
```

--------------------------------

### Configure LLM provider via .env

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Provides environment variables to configure the LLM provider and API key instead of using the activation page.

```env
LLM_PROVIDER=minimax
MINIMAX_API_KEY=your_key
```

--------------------------------

### Set deployment target

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Environment variable controlling the default deployment target of 10.15.

```bash
MACOSX_DEPLOYMENT_TARGET=10.15
```

--------------------------------

### Build macOS Artifacts for Specific Architectures

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Build separate macOS artifacts for arm64 and x64 architectures.

```bash
npm run build:mac:arm64
npm run build:mac:x64
```

--------------------------------

### Expected DMG filenames

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

Expected DMG filenames for version 2.1.436 on arm64 and x64 architectures.

```text
dist/Bailongma-2.1.436-mac-arm64.dmg
dist/Bailongma-2.1.436-mac-x64.dmg
```

--------------------------------

### resync: request full scene

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/SCENE-PROTOCOL.md

Shell sends resync with reason when gap detected or on init/error; core must respond with full scene.

```jsonc
{ "v": 1, "type": "resync", "reason": "gap" }   // reason ∈ "gap" | "init" | "error"
```

--------------------------------

### POST /admin/restart

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/README.md

Restarts the application process.

```APIDOC
## POST /admin/restart

### Description
Restarts the application process.

### Method
POST

### Endpoint
/admin/restart

### Parameters
None

### Response
#### Success Response (200)
- (not specified in source)

```

--------------------------------

### API Base URLs

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/src/ui/brain-ui/worldcup-broadcast-v2.html

List of backend API base URLs to try in order.

```javascript
const API_BASES = ['http://localhost:3721', 'http://localhost:3722'];
```

--------------------------------

### electron-builder mac configuration

Source: https://github.com/xiaoyuanda666-ship-it/bailongma/blob/main/docs/mac-build.md

electron-builder macOS configuration with DMG target, forced code signing, hardened runtime, and explicit unpacked binary.

```json
"mac": {
  "forceCodeSigning": true,
  "hardenedRuntime": true,
  "binaries": ["Contents/Resources/app.asar.unpacked/build/native-speech-recognizer"],
  "target": ["dmg"],
  "category": "public.app-category.productivity",
  "artifactName": "${productName}-${version}-mac-${arch}.${ext}"
}
```