跳转至

Dora Wiki

Agent Portal — 03-31~04-01 项目操作台与对话入口统一

Agent Portal — 03-31~04-01 项目操作台与对话入口统一¶

关键产品决策¶

Dad 决策：Portal 新增 Projects 视图作为新主功能
门户从"bot 状态展示"扩展为"项目管理 + 服务器监控 + 健康检查"
项目看板成为首页默认视图，按"进行中 / 近期完成 / 其他"分组
原因：Portal 需要承载项目决策和推进能力，不只是状态展示
Dad 决策：操作按钮统一改为对话模式
砍掉所有审核、合并等操作按钮，统一改成"对话模式"
项目卡片与项目详情的操作入口统一收敛到对话
原因：按钮式操作"不像人用的"，自然语言指令更灵活高效
Dad 决策：Portal 内部聊天统一化
项目卡片/Bot 点击统一接入门户内部 CommandBar 聊天
不再跳外部 Mattermost DM，交互保持在门户内
可在聊天窗口中显示 bot pill + project pill，next action 可自动预填

技术问题与根因分析¶

项目数据源混乱问题¶

现象：现有 /api/projects 仍基于旧 AP_projects 结构，新表结构尚未完成填充
解决方案：
前端先用 mock/空数据搭框架，避免阻塞 UI 开发
后端从 AP_projects 读取，将 metadata JSON flatten 成前端可消费字段
结果：19 个真实项目成功展示，从空壳切换为真实数据驱动

Bot 点击行为不一致¶

现象：部分点击会跳外部 Mattermost DM，交互割裂
根因：
项目中的 responsible_bot / involved_bots 使用 mm_username
Dashboard agents 使用 agent_id
agents.find(a => a.id === botId) 匹配失败，触发 fallback
解决方案：
建立 mm_username -> agent_id 映射（含 ottor -> otter 等补充映射）
所有 bot 点击统一调用 handleToggleTarget，在门户内部打开 CommandBar
扩展 CommandTarget 支持 prefill 与 projectContext

项目看板性能问题¶

现象：项目列表加载超时
根因：列表接口返回过重，包含大量不必要字段与项目
解决方案：
新增 slim flatten/list 逻辑
API 侧提前过滤 dismissed/merged 等无关项目
前端减少重复过滤
结果：从 561KB / 100 个项目 降到 13.5KB / 18 个项目，体积下降 97.6%

Bot 架构/实现决策¶

Projects 视图架构设计¶

架构方案：
新建独立组件 APProjectsTab，避免膨胀 DashboardPage
新增 APProjectDetailPage，在 App.tsx 中加入 ap-project route
Dashboard 增加 Projects tab 与跳转回调 onOpenAPProject
选型理由：模块化拆分，降低巨型页面维护成本

项目看板功能完整化¶

核心功能：
新增 ProjectKanbanTab 作为首页默认视图
新增 POST /api/ap-projects/:id/message，支持项目对话
数据策略：先从现有 metadata 推导 UI，后端补齐后自动升级
状态管理：看板按"进行中 / 近期完成 / 其他"分组渲染

项目拖拽排序实现¶

技术选型：使用 dnd-kit 实现拖拽
数据存储：使用 metadata.sort_order，避免改表结构
关键修复：
flattenAPProject 未返回 metadata，前端永远读不到 sort_order
移动端拖拽难触发，调整 TouchSensor 参数
恢复拖拽手柄上的 touch-none，放大手柄点击区域

CommandBar 统一聊天架构¶

核心改造：
重写 CommandBar，支持直接与 Ottor 对话
选中目标后自动加载历史，显示引用消息记录
Markdown 渲染升级：改用 react-markdown + remark-gfm

技术要点：

type CommandTarget = {
  id: string
  label: string
  mmUserId?: string
  prefill?: string
  projectContext?: ProjectContext
}

里程碑¶

Projects 视图上线：19 个项目数据驱动，从空壳升级为真实业务
项目看板成为首页默认：按状态分组，支持项目对话入口
Bot 详情页关联项目：可从 bot 维度反查参与项目
聊天入口统一化：所有 bot/项目点击统一走门户内 CommandBar
项目拖拽排序上线：支持自定义项目展示顺序，移动端友好
性能优化完成：项目列表体积下降 97.6%，加载速度显著提升

重要配置/代码线索¶

新增路由：ap-project route，APProjectDetailPage
新增 API：POST /api/ap-projects/:id/message
核心组件：ProjectKanbanTab、APProjectsTab、统一 CommandBar
数据模型：metadata.sort_order、responsible_bot、involved_bots 映射
性能优化：slim API、数据过滤、前端去重

关键架构转换¶

从状态展示 → 项目操作台：Portal 承载决策能力，不只是展示
从按钮操作 → 对话驱动：自然语言替代表单，交互更灵活
从外部跳转 → 内部统一：聊天、项目、bot 交互保持在同一界面
从静态列表 → 动态看板：支持拖拽排序、状态分组、性能优化

这一阶段标志着 Portal 从"控制台"升级为"工作台"，具备了项目管理、决策支持和统一交互的完整能力。