Bailongma

https://github.com/xiaoyuanda666-ship-it/bailongma
Admin
Bailongma is a continuously running desktop AI agent framework driven by a persistent main loop that...
Tokens:93,228
Snippets:552
Trust Score:6.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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  ← 焦点
```

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

### 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
```

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

### 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。缺省不提供
}
```

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

### 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)

```

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

### 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/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)

```

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

### 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
```

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

### 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" }
```

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

### 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)

```

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

### 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)

```

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

### 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)

```

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

### 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)

```

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

### 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)

```

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

### 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())
```

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

### 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)

```

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

### 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.
```
Tokens:
Raw