BR AI Spec Visual 需求说明文档（PRD）
版本：v1.0 ｜ 更新时间：2026-04-23
适用范围：br-ai-spec-visual 仓库（可视化与控制面）
关联底座：br-ai-spec / npm @ex/ai-spec-auto（规范与运行时底座）
团队在多个业务项目中引入了 规范驱动 AI 研发流程（ai-spec-auto） ：在每个业务仓内通过 npx @ex/ai-spec-auto init . 注入规则、技能、OpenSpec 流程与 IDE 适配（.cursor/、.claude/、.opencode/、.trae/ 等），并在运行期产出：
.ai-spec/：current-run、history、repo-map 等运行态.agents/registry/：角色 / 技能 / 流程注册表.omx/logs/*.jsonl：Agent 运行日志openspec/specs|changes：规范资产与变更文档
问题 ：这些数据分散在开发者本机与各业务仓，缺少统一入口观测"谁在跑什么 / 改了什么 / 规范长什么样"，也无法跨项目做横向治理。
本仓定位 ：作为 ai-spec-auto 体系的 可视化与控制面 (Visual + Control Plane) ，聚合多项目运行态、变更、拓扑与采集数据，并提供 WebSocket 实时能力与 Collector 上报通道。
补充边界：
registry（注册表）主数据由 skill-q-platform（Hub 平台） 维护
br-ai-spec 负责把 manifest / registry snapshot（安装清单 / 注册表快照）同步到项目本地br-ai-spec-visual 只消费已同步、已上报、已入库的结果，不在 Visual 内重新定义 registry 规则
为多个接入 ai-spec-auto 的项目提供 统一汇聚面板 ：Workspaces / Runs / Changes / Topology / Specs / Tasks。
提供 实时能力 ：hook 事件与 WebSocket 推送，浏览器无刷新看到运行状态变化。
提供 自动 + 手动 两条数据上报链路：
自动：internal/visual-hooks 在关键事件 POST 到 /api/internal/ingest/raw
手动/定时：Collector CLI 扫描项目目录批量上报
提供 反向控制 通道：UI 下发控制指令 → auto 侧 control-puller 拉取执行 → 回执上报。
提供 安装遥测 ：追踪 @ex/ai-spec-auto 的 init/update/sync 在各机器上的使用情况。
保证 最小侵入 ：hook 超时即降级、不阻塞业务项目的协议推进。
不重复实现 ai-spec-auto 的规则/技能/OpenSpec 能力（由 br-ai-spec 负责）。
不替代 IDE，不在 UI 内直接编辑业务仓代码。
当前版本不提供多租户级别的计费 / SSO / 审计导出。
不承诺对外 SaaS 化（默认私有部署，MySQL / MariaDB 自管）。
术语
含义
Workspace
工作区，一个接入 ai-spec-auto 的业务项目在本系统的抽象
Run
一次 ai-spec-auto protocol-step 协议推进或等价的运行
Change
OpenSpec 变更文档（spec / change / archive）
Registry
.agents/registry/ 中的角色 / 技能 / 流程等资产
Raw Event
统一摄取的原始事件（Collector 与 Hook 共用一套契约）
Projection
将 raw event 投影到 Prisma 关系模型（RunState / ChangeDocument 等）
Control Outbox
UI 下发的反向控制指令队列（等待 auto 侧拉取）
Installation
一次 @ex/ai-spec-auto 的安装实例（按 installationId 唯一）
角色
能力
admin全局管理（所有 workspace、成员、安装遥测）
maintainer管理所授权的 workspace，可触发控制指令、管理成员
viewer只读查看已授权 workspace 的 Runs / Changes / 拓扑 / 规格
权限模型：User → WorkspaceMember(role) → Workspace 三元组。
编号
需求
对应实现
F-AUTH-01
邮箱 + 密码登录，密码 bcryptjs 哈希存储
src/app/api/auth/login
F-AUTH-02
Cookie 会话，支持通过 BR_AI_SPEC_VISUAL_COOKIE_NAME / SESSION_SECRET 环境变量配置
src/server/auth.ts
F-AUTH-03
会话过期自动清理；登出清空 cookie
src/app/api/auth/logout
F-AUTH-04
未认证访问受保护路由统一重定向登录页
src/app/(protected)/layout.tsx、middleware.ts
F-AUTH-05
GET /api/me 返回当前用户与角色src/app/api/me/route.ts
编号
需求
F-WS-01
创建 / 查看 / 更新 / 归档 workspace（slug 唯一、可选 rootPath）
F-WS-02
workspace 详情包含基础信息、成员、连接令牌、最近 Runs / Changes / Alerts
F-WS-03
生成与轮换 Connect Token （Collector 与 Hook 使用，HMAC 方案，密钥来自 REALTIME_CONNECT_SECRET）
F-WS-04
Member 管理：邀请已有用户加入，设置 admin/maintainer/viewer；唯一约束 (workspaceId, userId)
F-WS-05
workspace 状态支持 active / archived，归档后隐藏默认列表
对应实现：src/app/api/workspaces/**、src/server/connect-token.ts、src/app/(protected)/workspaces。
编号
需求
F-RUN-01
按 workspaceId + runKey 汇总一次运行的最新 status / lastEventType / turnCount
F-RUN-02
支持查看运行事件时间线（RunEvent 按 occurredAt 排序）
F-RUN-03
支持查看角色级执行（RunRoleExecution：roleSlug / status / startedAt / endedAt）
F-RUN-04
UI 提供列表页、详情页、实时刷新（WS）
F-RUN-05
投影幂等：相同 dedupeKey 的 raw event 不重复投影
事件类型：run.started / run.state_changed / run.archived / runtime-state.snapshot / omx.log.entry。
编号
需求
F-CHG-01
接收 OpenSpec specs / changes / archive 目录内容并投影为 ChangeDocument
F-CHG-02
按 changeKey + docType + sourcePath 唯一去重，contentHash 变化触发更新
F-CHG-03
UI 支持按状态筛选（draft/in-progress/archived），Markdown 预览（/api/changes/[id]/preview）
F-CHG-04
支持 archive 字段，归档后列表降权显示
编号
需求
F-SPEC-01
以 workspace 为范围列出 OpenSpec 规范条目
F-SPEC-02
支持按分类（domain / role / skill）检索
F-SPEC-03
与 Registry / 拓扑联动：点击规格可跳转至关联角色
编号
需求
F-TOPO-01
基于 RegistryItem + RegistryRelation 以 @xyflow/react 渲染图形
F-TOPO-02
支持节点分类着色（role / skill / flow），关系类型分线型
F-TOPO-03
支持折叠、搜索、定位到某节点
3.7 Tasks 与 Trace（F-TASK / F-TRACE）
编号
需求
F-TASK-01
列出各 workspace 正在进行的任务（以 Run 为基本单位）
F-TRACE-01
提供最近 trace 流（/api/trace/recent）供调试，近实时显示事件摘要
编号
需求
F-CTRL-01
POST /api/control/pending 让 auto 侧拉取当前 workspace 未处理指令（按 signature 校验身份）
F-CTRL-02
POST /api/control/approve 标记指令为 delivered/applied，写 appliedSnapshot
F-CTRL-03
POST /api/control/resume 恢复被暂停的运行
F-CTRL-04
指令状态机：pending → delivered → applied / conflict / rejected / expired
F-CTRL-05
指令携带 HMAC signature，使用 REALTIME_CONNECT_SECRET 生成与校验
F-CTRL-06
UI 提供"待审批""已应用""冲突"三栏视图
对应模型：ControlOutbox；实现：src/server/control.ts、src/server/control-outbox.ts。
编号
需求
F-RT-01
server.mjs 自定义启动，使 Next.js 与 ws 挂同一端口
F-RT-02
握手消息：session.hello / session.ack，携带 workspaceId 与 connect-token
F-RT-03
事件广播：run.*、baseline.scan.*、change.*，按 workspace 订阅
F-RT-04
installations-presence 跟踪在线 Installation 心跳
F-RT-05
客户端断线自动重连（UI 端实现），服务端容忍暂时断开
实现：src/server/ws-server.ts、src/server/realtime-hub.ts、src/lib/realtime/*。
3.10 Ingest 统一摄取（F-INGEST）
编号
需求
F-INGEST-01
统一端点 POST /api/internal/ingest/raw，兼容两种形态：Collector snake_case Body 与 Hook camelCase + Header
F-INGEST-02
按 dedupeKey 去重，命中返回 skipped，否则返回 inserted
F-INGEST-03
原始事件落 RawIngestEvent，同步触发投影到 RunState / RunEvent / ChangeDocument / RegistryItem / RegistryRelation / OmxSession / OmxTurn
F-INGEST-04
connect_token 缺省按本地受信任来源处理；存在时做 HMAC 校验，失败仅日志不阻断 （以保证 hook 零侵入）
F-INGEST-05
POST /api/internal/ingest/run-state 提供纯状态快照快速入口
F-INGEST-06
单次批量上限（建议 500 条/批），超限分批处理
支持的 sourceKind：registry / omx-jsonl / run-state-json / repo-map-json / hook-event / control-receipt。
3.11 Collector CLI（F-COL）
编号
需求
F-COL-01
提供 br-ai-spec-visual-collector CLI（入口 src/collector/cli.ts）
F-COL-02
扫描目录：.ai-spec/、.agents/registry/、.omx/logs/、openspec/
F-COL-03
支持 --workspace-id --project --server [--connect-token --agent-id --json]
F-COL-04
HTTP 批量上报（http-transport.ts），可选 WS 推送握手（transport.ts）
F-COL-05
首次接入跑 baseline 扫描；支持 chokidar 监听增量（预留）
F-COL-06
网络错误退避重试，上报失败不影响本地业务
编号
需求
F-TELEM-01
对外端点 POST /api/public/installations/report，接收 @ex/ai-spec-auto 的安装/升级/同步上报
F-TELEM-02
存储 Installation（机器维度）+ InstallationEvent（每次事件）+ InstallationProject（项目命中）
F-TELEM-03
Admin 查看端点：/api/admin/installations、/active、/stats、/[id]
F-TELEM-04
项目使用 projectHash 匿名化（避免泄露真实路径）
F-TELEM-05
默认超时 1500ms，远端不可用时 auto 侧降级为不上报
编号
需求
F-OPS-01
GET /api/health 返回 { ok, db, ws, version }，用于容器探针
F-OPS-02
启动脚本 fix-and-start.sh / start-with-db.sh 在开发环境自动修复常见问题
单次 raw ingest 批处理 500 条：服务端 P95 < 500ms（本地 MySQL）。
WS 推送延迟：相对 hook 落库 < 200ms（同机）。
列表类 API P95 < 300ms（分页默认 50）。
Hook 与 Collector 的上报至少一次 语义，依赖 dedupeKey 幂等。
控制指令状态机终态（applied/conflict/rejected/expired）不可回退。
数据库连接用 @prisma/adapter-mariadb，短连接失败支持自动重连（Prisma 默认）。
所有写入型内部端点必须携带 connect-token（本地受信任模式仅供开发/测试）。
HMAC 校验使用 REALTIME_CONNECT_SECRET，生产环境不得为空或使用默认值。
密码 bcrypt cost ≥ 10；session token 写入 VarChar(512)，随机 ≥ 256bit。
不在 payload 中落明文密钥；raw event 中含敏感字段由 hook 侧负责脱敏。
Node.js 18+ ；推荐 20 LTS。
Next.js 16.2.x （App Router）+ React 19 + Turbopack dev。
数据库：MySQL / MariaDB 兼容实例。
浏览器：最近两个版本的 Chrome / Edge / Safari。
ingest / control / ws 关键路径打结构化日志。
预留 alerts 表，支持未来写入告警（当前以人工写入 + UI 展示为主）。
核心实体（详见 prisma/schema.prisma）：
User ─┬─< Session
└─< WorkspaceMember >─ Workspace
├─< WorkspaceAgent
├─< SyncJob
├─< RegistryItem / RegistryRelation
├─< RunState / RunEvent / RunRoleExecution
├─< ChangeDocument
├─< OmxSession / OmxTurn
├─< Alert
└─< RawIngestEvent
ControlOutbox (workspaceId + runKey + command，独立审计)
Installation ─┬─< InstallationEvent
└─< InstallationProject
关键唯一约束：
Workspace.slug、User.email、Session.token(workspaceId, runKey) on RunState(workspaceId, changeKey, docType, sourcePath) on ChangeDocument(workspaceId, category, slug) on RegistryItemRawIngestEvent.idempotencyKey、(workspaceId, eventId)Installation.installationId
分组
方法+路径
说明
认证
POST /api/auth/login POST /api/auth/logout GET /api/me
Workspace
GET/POST /api/workspaces GET/PATCH /api/workspaces/[id] POST /api/workspaces/[id]/connect-token
成员
GET/POST /api/members
Runs
GET /api/runs GET /api/runs/[id]
Changes
GET /api/changes GET /api/changes/[id] GET /api/changes/[id]/preview
Specs
GET /api/specs
Tasks
GET /api/tasks
Trace
GET /api/trace/recent
控制
POST /api/control/pending POST /api/control/approve POST /api/control/resume
摄取
POST /api/internal/ingest/raw POST /api/internal/ingest/run-state内部 / hook / collector
安装遥测
POST /api/public/installations/report对外（公网可暴露）
管理
GET /api/admin/installations[/active/stats/:id]admin only
健康
GET /api/health
路径：/ws
握手：{ type: "session.hello", workspaceId, connectToken, agentId?, capabilities? }
服务端回复：{ type: "session.ack", accepted, sessionId, since }
事件：run.*、change.*、baseline.scan.*、alert.*
依赖 br-ai-spec（@ex/ai-spec-auto）在业务项目中完成规则、OpenSpec、internal/visual-hooks/ 注入，否则数据源为空。
数据库 schema 使用 Prisma 迁移（pnpm prisma:push、prisma:generate）；禁止手工改表。
REALTIME_CONNECT_SECRET 在生产环境必须与 auto 侧保持一致，否则 HMAC 校验不通过（当前实现仅日志告警，计划在 v2 改为强制）。端口：dev 默认 3000；CLI 调用 AI_SPEC_VISUAL_URL 需同步。
版本
范围
v1.0（当前）
Workspace / Runs / Changes / Topology / Specs / Collector / Hook ingest / 控制指令 / 安装遥测 / WS 实时
v1.1
告警规则引擎（基于 Alert 表 + 触发器），失败 run 自动告警
v1.2
强制 HMAC（失败即阻断）、Connect Token 轮换策略、操作审计日志
v1.3
多租户 / SSO（OIDC）、跨 workspace 度量看板
v2.0
与 OpenSpec 双向写入（UI 创建 change proposal → 下发 auto）
风险
影响
对策
Hook 网络波动导致事件丢失
运行态不及时
Collector 定时补扫 + dedupeKey 幂等
数据库写入放大（RawIngestEvent + Projection）
存储增长
raw 表按 occurredAt 归档；提供清理脚本
REALTIME_CONNECT_SECRET 配置错位控制指令无法校验
启动自检（计划）+ 部署文档红线
WS 长连接资源泄漏
服务退化
realtime-hub 心跳与回收；压测验证
遥测端点公开暴露
被刷量
加限流 + projectHash 匿名化（已实现）