跳转至

Agent Portal — 03-21~22 日报系统与详情页稳定性

关键产品决策

  • Dad 决策：Portal 应以 bot 为入口
  • Portal 信息架构应改为"bot 作为入口"，项目详情采用更轻量的展开/弹窗方式
  • 不是把"项目列表"当主入口，而是把"机器人（bot）"作为入口，再展开其负责的项目与细节

  • 原因：当前 ProjectDetailPage 已有 600+ 行，按"独立详情页"设计，不适合轻量弹层式交互

  • Dad 决策：日报系统接入 Portal

  • 每天晚上 9 点 researcher 发"研究日报"，要把这些日报放到 Portal 网站里保存
  • 不需要单独建一个日报页面，应当挂到对应 bot 下面

  • 原因：日报应成为 Portal 的结构化内容，而不是只保留在聊天记录或外部文件中

  • Dad 决策：Bot 卡片数据源统一

  • 首页 Bot 卡片应只来自 bot_summaries，dashboard.agents 只作为运行态补充信息
  • 不能重复，以 bot_summaries 为主数据源生成卡片
  • 原因：bot_summaries 更接近业务视图，agents 只是巡检快照，不能决定卡片集合

技术问题与根因分析

跨 Agent 派任务失控问题

  • 现象：researcher 给 PortalBot 派任务时，任务多次丢失或执行失败
  • 根因链条：
  • 最初误判 PortalBot 没有 Mattermost 配置，实际上有配置
  • sessions_send 失败是因为 PortalBot 没有活跃 session，应使用 sessions_spawn
  • Mattermost DM 失败是 dmPolicy: "pairing" + allowFrom 白名单限制
  • 任务丢失是因为刚发出 spawn 后执行了 gateway restart，把任务进程杀掉
  • 解决方案：
  • 统一改造 bot 间 DM 权限，放宽 dmPolicy/allowFrom
  • 使用 sessions_spawn 拉起 agent 并附带任务
  • 避免在任务进行中执行重启操作

PortalBot 重构导致黑屏

  • 现象：PortalBot 接到重构任务后，页面出现黑屏，#root 为空
  • 根因分析：
  • class="dark" 已被加到页面，说明 App.tsx 的 useEffect 执行了
  • 但 React 已挂载但没有正常渲染内容
  • HEAD（旧代码）能正常渲染，PortalBot 的改动导致黑屏
  • 解决方案：先回滚恢复可用性，再重新派发任务
  • 经验教训：必须做页面打开验证、登录流程验证、关键页面渲染验证

详情页 agent_id 不一致 bug

  • 现象：任何 MM 名 ≠ 门户 ID 的 bot，详情页都是空白
  • 根因：BotDetailPage 的 API 调用使用了 mmUsername，而不是路由里的门户 agentId
  • 解决方案：API 调用统一改用 agentId，mmUsername 仅用于显示
  • 数据建模原则：展示标识（MM username）不能替代系统主键（portal agentId）

Bot 架构/实现决策

日报系统架构设计

  • 新增表结构：
  • AP_dashboard
  • ap_daily_activities
  • 新增 API 与组件：
  • DailyInsightsCard
  • ActivityTimeline
  • /api/daily-reports 端点
  • 自动化接入：修改日报 cron，每天 21:00 生成后自动 POST 到 Portal API

数据库表结构修复

  • 问题：表名大小写不一致导致查询失败，Supabase/Postgres 对大小写敏感
  • 解决方案：统一使用双引号或按实际小写表名修正 SQL
  • v2 日报系统数据结构：
  • 旧结构：focus_events / followups / insights
  • 新结构：focus_top3 / needs_attention / timeline
  • 重写 DailyInsightsCard 以适配新 schema

Bot Fleet 数据源重构

  • 架构方案：
  • BotFleetTab 改为以 bot_summaries 为主数据源生成卡片
  • 若 dashboard.agents 中有同 ID bot，则 merge 运行态信息
  • archived / active 分组继续保留
  • 选型理由：避免重复展示，让业务数据主导，运行态数据补充

里程碑

  1. 跨 Agent 通信基础设施打通：sessions_spawn 和 Mattermost DM 通道修通，PortalBot 成功回复 pong
  2. 日报系统完成接入：日报功能验证通过，每天 21:00 的日报 cron 已更新为"生成日报 + POST 到 Portal"
  3. Dashboard 首页重构完成：从项目列表演进为运维总览，Bot/Server 分tab展示
  4. 详情页稳定性修复：数据源统一，agent_id 映射统一，历史模式 bug 修复
  5. 日报时间线 UI 完成：7 天历史日报补全（03-16 到 03-22），时间线展示更协调

重要配置/代码概念

  • 数据源优先级：bot_summaries > dashboard.agents
  • 任务通信方式：sessions_spawn（无活跃session）、Mattermost DM（正常消息通道）
  • 日报API结构：/api/daily-reports、/api/insights、/api/insights/dates
  • 组件设计原则：
  • 数据加载前不崩：防御性默认值处理
  • 展示标识不能替代系统主键
  • hook 调用必须在条件返回之前

这一阶段建立了 Portal 作为多 bot 协作平台的基本架构，日报系统和详情页功能的稳定性为后续更复杂的工作流奠定了基础。