# 数字大脑

**Repository Path**: tabl/digital-brain

## Basic Information

- **Project Name**: 数字大脑
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数字大脑（Digital Brain）· 项目总入口

> **一句话**：给业务系统装上一个"能听、能说、能动手"的 AI 助手——用户对着网页按住说话，助手听懂后直接操作页面（点击、填表、勾选）或回答页面问题，全程语音播报。
>
> 你现在看到这句话能想象出画面，就已经理解了这个项目 80% 的定位。剩下的 20% 是工程细节，往下看。

---

## 1. 目录导览（先看哪里、别碰哪里）

```
202608数字大脑/
├── README.md                  ← 本文件，新人从这里开始
├── 设计文档/                   ← ★ 产品与架构的权威设计（V0.4，14 份）
│   ├── 10-数字大脑总体设计-总览.md       （建议第一份读：产品定位、分期规划）
│   ├── 数字大脑-技术方案（核心关键点与落地边界）.md
│   └── 20-数字大脑测试用例与验证案例.md
├── 03-mvp/                    ← ★ 代码都在这里，日常开发的主战场
│   ├── README.md              ← 技术总入口（现状/架构/接口/契约/已知限制）
│   ├── docs/quickstart.md     ← 5 分钟跑通教程
│   ├── docs/                  ← 架构、插件开发、SDK 接入等专题文档
│   ├── packages/              ← 6 个子包（见下表）
│   ├── scripts/               ← 冒烟测试、门禁测试、基准脚本
│   └── TODO-*.md              ← 滚动的实施项跟踪
├── 02-数字大脑-过时的/          ← ⛔ 历史归档（早期 demo/POC），只读参考，勿在此开发
└── 参考-UI模板-*/              ← ⛔ 外部参考资料，与本项目代码无关
```

> 后两个目录已加入 `.gitignore` 且取消 git 跟踪——**它们不会上传到远程仓库**，本地保留仅为备查。

## 2. 项目是什么：一分钟版

**产品形态**：服务端（NestJS）+ 浏览器 SDK + 配置后台 + 示例业务页面。

**一次典型交互**：

```
用户按住说话 "点击保存订单"
  → 麦克风音频经 WebSocket 增量推流到服务端
  → 百炼 ASR 转写文本（~0.23s）
  → LLM（qwen3.8-27b）输出严格 JSON：{commands, reply}
  → Router 纯代码分发：
      commands 非空 → 下发 DOM 指令，页面 SDK 真实执行（点击/勾选/填写）
      reply 非空   → 流式 TTS 合成语音 → 经 WS 下发播放（首音频 ~1.3s）
```

**关键设计思想——插件化**：宿主只提供 5 个永不改变的 API（注册/获取/列表/健康/销毁），LLM/ASR/TTS/路由/页面操控全部是可替换插件。换云厂商、换模型，业务代码不动。

**多业务隔离**：一个"脑（brain）"= 一个业务系统 = 多个业务页面。规则、场景、模型设置按脑隔离，接入靠三要素（token + endpointId + brainUuid）鉴权。

## 3. 新人上手（按顺序做，每步都有验证点）

### 准备：环境要求

| 需要 | 版本 | 说明 |
|---|---|---|
| Node.js | ≥ 20（实测 22/24 均可） | 唯一硬依赖 |
| npm | 随 Node | 所有命令走根 `package.json` 的 npm script |
| 百炼 API Key | 一个 | 不配也能启动，只是云端能力降级 |

### 第 1 步：安装依赖并构建

```bash
cd 03-mvp
npm ci          # 按 package-lock.json 严格安装（约 2 分钟，509 个包）
npm run build   # 依次构建 core → server → sdk → admin → cli
```

> ⚠️ `node_modules` 不入库，首次拉代码**必须**先 `npm ci`。
> 若失败：删掉 `node_modules` 和 `package-lock.json`，改用 `npm install` 重新解析。

### 第 2 步：配置百炼密钥（只需一次，密钥不进代码库）

```powershell
# Windows（设置后必须重开终端）
[Environment]::SetEnvironmentVariable('shuzidanao_apikey', '<你的百炼API-Key>', 'User')
```

> 没配 Key 服务端也能起，会自动降级到规则实现并明确告警——适合先跑通再说。

### 第 3 步：启动（开 3 个终端）

```bash
npm run start:server   # 终端1：服务端，端口 8820
npm run start:site     # 终端2：示例业务页 A（营销订单），端口 8810
npm run start:admin    # 终端3：配置后台，端口 8821
```

### 第 4 步：体验闭环

1. 浏览器打开 `http://localhost:8810`，右下角有助手面板，**按住麦克风说话**："点击保存订单" / "页面上有哪些按钮"；
2. 打开 `http://localhost:8821` 看配置后台：操控规则、业务场景、模型切换、系统状态、审计日志都在这里。

### 第 5 步：跑测试，确认环境是好的

```bash
npm run verify    # 回归门：构建 core+server → 契约校验 → 门禁测试（96 用例）
npm run smoke     # 端到端冒烟（162 项，需服务端已启动；未配 Key 会显式 SKIP 并非 0 退出）
```

## 4. 端口一览

| 服务 | 端口 |
|---|---|
| 服务端（NestJS，REST + WebSocket） | 8820 |
| 配置后台（Vue3） | 8821 |
| 示例业务页 A（营销订单） | 8810 |
| 示例业务页 B（库存管理） | 8811 |

## 5. 日常开发常用命令速查

| 命令 | 用途 |
|---|---|
| `npm run verify` | **开工/交码前的唯一门槛**：构建 + 契约校验 + 门禁测试 |
| `npm test` | 只跑门禁单测（96 用例 / 10 文件） |
| `npm run check:contract` | 契约一致性单跑（改指令协议后必跑） |
| `npm run dev:server` / `dev:admin` | 开发模式（watch 热编译） |
| `npm run smoke` | 端到端冒烟 |
| `npm run bench:latency` | 意图链路延迟基准（改提示词/换模型前后对比用） |
| `npm run demo:reset` | 一键恢复干净演示数据 |
| `node packages/cli/bin/brain.js health` | CLI 健康检查 |

## 6. 新人最容易踩的坑（先记住这四条）

1. **改了指令协议必须跑 `npm run check:contract`**。动作/类型枚举只在 `packages/core/src/command.ts` 定义一次，提示词、Router 白名单、JSON Schema、SDK `execL0` 全部引用它——契约不可漂移。
2. **管理台前端禁止硬编码枚举**，下拉选项一律从 `GET /admin/contract` 拉取。
3. **TTS 音色与模型必须匹配**（混用报 `InvalidParameter/411`）；opus 音频跨句不能简单拼接，要按 `segmentIndex` 分段解码。
4. **这是 Demo，不是生产系统**：内存存储（重启丢数据）、管理台无登录、无多租户。交底/演示前先读 `03-mvp/docs/engineering-baseline-demo.md` 的"明确不做"清单。

## 7. 深入文档地图（按需取用）

| 想了解什么 | 去哪里 |
|---|---|
| 产品定位、为什么这么做 | `设计文档/10-数字大脑总体设计-总览.md` |
| 系统架构、执行链路、数据模型（**文本权威**） | `03-mvp/docs/architecture.md` |
| 5 分钟跑通 + 常见问题 | `03-mvp/docs/quickstart.md` |
| 怎么开发一个新插件 | `03-mvp/docs/plugin-development.md` |
| 业务系统怎么接入 SDK | `03-mvp/docs/sdk-integration.md` |
| 环境变量与密钥（权威） | `03-mvp/docs/env-and-secrets.md` |
| 技术全貌：接口表、契约要点、已知限制、测试矩阵 | `03-mvp/README.md`（随代码同步） |
| 最近在做什么 / 遗留什么 | `03-mvp/TODO-*.md` |

## 8. Git 与仓库约定

- 远程：`gitee`（https://gitee.com/tabl/digital-brain.git），主分支 `master`
- **不入库**（已 gitignore + 取消跟踪）：`02-数字大脑-过时的/`、`参考-*`、`node_modules`、`dist`、`.env*`（模板 `.env.example` 例外）、密钥文件、`runtime-*-settings.json` 等运行时本地状态
- 密钥纪律：API Key 只放操作系统环境变量 `shuzidanao_apikey`，**任何密钥不得写入代码或配置入库**
- 文档同步纪律：契约类改动必须同时更新 `03-mvp/README.md` 的「契约要点」与 `docs/architecture.md`