Quick start
5 分钟跑起来
# Node 22.19+ · pnpm 10 git clone https://github.com/ITC-cloud-soft/biz-ai.git cd biz-ai pnpm install pnpm test # every workspace package pnpm validate # OpenAPI lint + bundled manifests # the sample business system (PostgreSQL) pnpm --filter @dsh-bridge/example-equipment-inspection start → http://127.0.0.1:19730
import { createBridgeApp, createPool, createPostgresStore } from '@dsh-bridge/server-kit' const store = createPostgresStore({ pool: await createPool(DB_URL) }) await store.migrate() // bridge_* tables const bridge = await createBridgeApp({ manifest: { file: './bridge.manifest.yaml' }, store, serviceToken, bffSecret, hooks: { employees, authenticate, isSessionLive, recipientsFor, approvals, proposalKinds, reports, piiScan }, }) createServer(bridge.handler).listen(8080)
Hooks
业务系统只需编写 hooks
| hook | 返回值 · 必须遵守 |
|---|---|
employees | { id, role, active }。停用的员工立即失去所有令牌 |
authenticate | 现有会话 → { user: { id, role }, sessionId }。不另建登录 |
recipientsFor | null ／ { stale } ／ { users, paramsFor, link, dedupeKey }。确定范围，并用 Web 授权逐人确认 |
approvals | get · approvers · card · mayDecide · decide。Web 与聊天使用同一规则 |
proposalKinds | { roles, validate, apply }。apply 只在人采纳时，于同一事务中执行 |
reports | compute(viewer) → 只有件数的分节 |
piiScan | 命中名册中的姓名时只返回类别（不返回文字） |
API reference · Bridge v1
接口
所有响应都带 bridge-protocol: 1。错误为 { ok: false, error: <lower_snake_case> }。v1 内只做增加。
| 类别 | 操作 | 主体 |
|---|---|---|
| 基础 | GET /health · GET /manifest | — · 服务 |
| 身份 | GET /identity · POST /identities/link · /me/link-codes · /me/identities | 服务 · 本人 |
| 委托 | POST /delegations · /assistant/tickets · /assistant/delegations | 服务 · BFF |
| 事件 · 通知 | GET /events?after= · /notifications/for-event/{id} · /notifications/deliveries | 服务 |
| 审批 | /approvals/{id}/deliveries · /approvals/{id}/im-decision · /approvals/im-decisions | 服务 |
| 提案 | POST /proposals · /proposals/{id}/accept · /reject | 委托 · 本人 |
| 报告 | GET /reports/latest · POST /reports/run | 本人 · 委托 |
| 可选 | /help/* · /pii-scan · /ai-profile · /document-reads · /connectors/* | — |
Conformance suite
五个不变量，52 项检查
| 不变量 | 检查项 |
|---|---|
| 1 只有本人能绑定 | L2–L9 · B1–B4 · N3 |
| 2 委托 = 允许列表 ∩ 角色 | L1 · D1–D7 · S1–S5 · R2 |
| 3 AI 提案，人来决定 | D3 · D5 · PR1–PR3 · A2–A4 · R3 |
| 4 不携带个人信息 | E1–E4 · N1 · N2 · A1 · R2 · L10 |
| 5 身份只来自业务系统 | L3 · D1 · D2 · S2 · A2 · N3 |
| 协议规范 | P1–P6 · M1–M3 |
BRIDGE_BASE_URL=http://127.0.0.1:8080 \
BRIDGE_FIXTURES=./test/fixtures.mjs \
BRIDGE_MANIFEST_FILE=./bridge.manifest.yaml \
node --test packages/protocol/conformance/http.test.mjs
52 passed, 0 known gaps, 0 skipped变异测试：在故意破坏不变量的模拟实现上，对应的检查会失败——证明测试真的有效。
Packages
组件包
@dsh-bridge/protocol
OpenAPI · JSON Schema · 校验 · bridge-validate · 一致性测试
@dsh-bridge/server-kit
业务系统侧的 Bridge v1 实现（Node.js · PostgreSQL）
@dsh-bridge/dsh-core
AI 面核心：应用注册 · 委托 · 工具 · 消息框架
plugins/* (9)
identity · tools · events · notify · approvals · assistant · memory · persona · reader
@dsh-bridge/web-kit
React 画面组件：聊天绑定 · 通知设置 · AI 员工设置 · 外部连接
@dsh-bridge/gateway
从 BFF 到 AI 面的认证网关（RPC 白名单）