ChimdumebiNebolisa/stadium-sentinel

# Stadium Sentinel Stadium Sentinel 旨在帮助场馆工作人员在活动期间了解并处理实时的事件更新。 ## 解决的问题 现场活动的运营部门会接收到来自宾客服务、安保、设施以及无线电频道的碎片化更新。工作人员需要了解发生了什么、由谁负责处理、发生了哪些变化以及下一步需要做什么——而无需在互不关联的工具中来回查找。 Stadium Sentinel 将现场报告和指挥中心更新转化为可操作的事件上下文：优先排序的调度队列、丰富的证据、时间轴、工作人员话术，以及基于 Elastic 运营记忆的语音引导后续步骤。 它不是 CRM、票务系统、分析仪表板、地图产品、座位图产品或通用仪表板。 ## 演示 **在线演示：** https://stadium-sentinel-726236175501.us-central1.run.app | 资源 | 路径 | |----------|------| | 首页 | [`artifacts/screenshot-landing.png`](artifacts/screenshot-landing.png) | | 指挥中心 | [`artifacts/screenshot-command.png`](artifacts/screenshot-command.png) | | 场馆上下文示意图 | [`artifacts/venue-schematic-1440.png`](artifacts/venue-schematic-1440.png) | | 工作台布局 | [`artifacts/workbench-1440-final.png`](artifacts/workbench-1440-final.png) | **演示视频：** _录制后添加链接。_ **快速开始：** 打开在线 URL → **打开运营录入** → **连接运营数据** → **打开指挥中心** → **拉取最新报告**。 ## 功能 - **基于 Elastic 的事件拉取** — 连接运营数据，引导种子健康状况，并从运营记忆中拉取当前的事件包 - **丰富的运营上下文** — 为每个事件组装调度时间轴、员工花名册、证据和事件详情 - **调度队列** — 按优先级排序的事件卡片（紧急、高、中、监控） - **队列完成行为** — 已完成的事件会移至未解决工作下方，并保持可查看状态 - **场馆上下文示意图** — 紧凑的场馆参考图，事件标记映射到实际的队列事件 - **响应清单** — 针对每个事件执行保持联系、确认结果和调度操作 - **实用工具抽屉** — 证据、员工更新、事件日志、报告和来源日志面板 - **Sentinel 语音代理** — 询问 Sentinel，基于实时上下文进行自然的事件问答 - **受保护的草稿 / 审查 / 提交** — 员工更新、报告、后续行动和调度需要明确的语音批准 - **批准的写回** — 在操作员批准后更新时间轴和运营记忆 - **生产级 Cloud Run 部署** — 通过 Cloud Build 使用所需的 `NEXT_PUBLIC_*` 构建参数预构建镜像 ## 技术栈 | 层级 | 技术 | |-------|------------| | 框架 | Next.js 16 (App Router), React 19, TypeScript | | 样式 | Tailwind CSS 4 | | 计算 | Google Cloud Run | | 构建 / 部署 | Cloud Build, Docker (独立输出) | | 运营记忆 | Elasticsearch (事件、证据、调度时间轴、事件记忆) | | Sentinel 后端 | `AGENT_BACKEND_ENABLED=true` 时使用 Vertex AI (Gemini) | | 单元测试 | Vitest | | E2E 测试 | Playwright | ## 架构 应用运行时使用**直接的 Elastic 检索和写入路径**。MCP 不是应用内语音或命令循环的一部分。外部 MCP 验证产物可能会单独存在于 `artifacts/batch9-mcp-proof/` 下，仅供附录演示使用。 ``` flowchart LR operator[Staff / command operator] workbench[Command workbench] pull[Pull latest reports] elastic[Elastic operational memory] sentinel[Sentinel API / Vertex Gemini] drawers[Evidence timeline source log] writeback[Approved write-back] operator --> workbench workbench --> pull pull --> elastic elastic --> workbench operator --> sentinel sentinel --> elastic sentinel --> workbench workbench --> drawers operator --> writeback writeback --> elastic writeback --> drawers ``` ## 设置 ### 安装 ``` npm ci cp .env.example .env.local ``` ### 环境变量 将 `.env.example` 复制到 `.env.local`。仅使用占位符名称——切勿提交密钥。 **构建时客户端标志**（在 `npm run build` 期间内联）： - `NEXT_PUBLIC_REAL_DEMO_FLOW` - `NEXT_PUBLIC_ENABLE_ELASTIC_PULL` - `NEXT_PUBLIC_ENABLE_SENTINEL_AGENT` - `NEXT_PUBLIC_ENABLE_SENTINEL_VOICE` - `NEXT_PUBLIC_SHOW_VENUE_ORIENTATION` - `NEXT_PUBLIC_SHOW_RADIO_TRANSCRIPT` **运行时服务器**（仅限 Cloud Run 或本地服务器）： - `ELASTICSEARCH_URL`, `ELASTICSEARCH_API_KEY` - `AGENT_BACKEND_ENABLED`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `VERTEX_MODEL` - 可选的索引覆盖——参见 `.env.example` 本地 Elastic 填充：`npm run index:elastic`（仅限开发设置）。 ### 开发 ``` npm run dev ``` 打开 http://localhost:3000 ### 测试与构建 ``` npm test npm run test:e2e npm run build npm run verify:real-demo ``` ### 部署 参见 [docs/INGESTION_DEPLOY_CHECKLIST.md](docs/INGESTION_DEPLOY_CHECKLIST.md) 和 [docs/STADIUM_SENTINEL_FINAL_EXECUTION_PLAN.md](docs/STADIUM_SENTINEL_FINAL_EXECUTION_PLAN.md)。使用带有预构建镜像标签的 Cloud Build——在生产环境标志下，不要单独依赖 `gcloud run deploy --source .`。 ## 使用方法 1. 打开应用（首页或 `/command`）。 2. 如果指挥中心处于断开连接状态，请在 `/demo/intake` **连接运营数据**。 3. 打开**指挥中心** (`/command`)。 4. 点击**拉取最新报告**以加载基于 Elastic 的事件。 5. 从调度队列中选择一个事件。 6. 查看场馆上下文、响应清单、团队分配和运营时间轴。 7. 打开抽屉标签页：证据、员工更新、事件日志、报告、来源日志。 8. 点击 **Ask Sentinel** 对所选事件进行语音问答。 9. 在出现提示时，批准草拟的员工更新、报告、后续行动或调度。 10. 批准后确认时间轴和来源日志更新。 演示脚本：[docs/real-demo-script.md](docs/real-demo-script.md) 录制清单：[docs/demo-recording-checklist.md](docs/demo-recording-checklist.md) ## 关键技术决策 - **直接的 Elastic 运营记忆** — 在应用运行时直接使用 Elasticsearch 进行拉取、上下文组装和批准的写回 - **无应用内 MCP 声明** — MCP 桥接和 Agent Platform 验证仅限外部使用；参见 `artifacts/batch9-mcp-proof/` 和 [docs/ELASTIC_BUILDER_MCP_SETUP.md](docs/ELASTIC_BUILDER_MCP_SETUP.md) - **语音优先的 Sentinel 及受保护的批准** — 持续监听循环；若无待批准的验证关卡，随意的确认不会进行提交 - **已完成事件置于活动工作下方** — 已解决的项目保持可选择状态以供审查，而不会阻碍调度焦点 - **仅限媒体元数据** — 证据引用媒体 ID 和描述；无媒体文件存储或渲染 pipeline - **仅限分类优先级** — 紧急、高、中、监控；产品文案中不使用数字评分 ## 限制 - **浏览器语音**依赖于 Web Speech API 和麦克风权限；行为因浏览器而异 - **无线电转录面板**在生产构建中处于关闭状态（`NEXT_PUBLIC_SHOW_RADIO_TRANSCRIPT=false`）；相关的 e2e 测试是可选路径 - **MCP 不是应用内的运行时功能**，除非以后明确实现；外部验证独立于 `/command` - **演示数据**是用于黑客松和录制流程的合成运营种子数据 - **建议**在生产 Cloud Run 上录制演示**之前进行手动麦克风冒烟测试** ## 许可证 MIT 许可证 本仓库目前不包含单独的 `LICENSE` 文件。 ## 文档 | 文档 | 用途 | |-----|---------| | [docs/STADIUM_SENTINEL_FINAL_EXECUTION_PLAN.md](docs/STADIUM_SENTINEL_FINAL_EXECUTION_PLAN.md) | 阶段、批次和防护准则的真实来源 | | [docs/INGESTION_DEPLOY_CHECKLIST.md](docs/INGESTION_DEPLOY_CHECKLIST.md) | 数据接入和 Cloud Run 部署清单 | | [docs/real-demo-script.md](docs/real-demo-script.md) | 在线演示旁白 | | [docs/demo-recording-checklist.md](docs/demo-recording-checklist.md) | 录制前冒烟测试清单 | | [docs/devpost-talking-points.md](docs/devpost-talking-points.md) | 提交说明要点 | | [docs/ELASTIC_BUILDER_MCP_SETUP.md](docs/ELASTIC_BUILDER_MCP_SETUP.md) | 仅限外部 MCP 设置 | | [artifacts/batch9-mcp-proof/README.md](artifacts/batch9-mcp-proof/README.md) | 外部 MCP 验证产物 |

标签：AI助手, Elasticsearch, 事件管理, 指挥调度, 智慧场馆, 特征检测, 自动化攻击, 语音交互, 请求拦截