release: bump version to 0.28.1

2026-04-20 15:14:53 +08:00
parent 4c21973197
commit 75cb214f23
42 changed files with 8556 additions and 89 deletions
--- a/docs/frontend/ai-playground-development-plan.md
+++ b/docs/frontend/ai-playground-development-plan.md
@@ -0,0 +1,361 @@
+# AI Playground Development Plan
+
+## 目标
+
+这份计划用于统一 `aiprovider`、`backend AI facade`、`Playground` 页面，以及后续 `BGP / 告警 / 数据源健康` 等 AI 入口的演进方向。
+
+当前原则：
+
+- `aiprovider` 继续作为独立模型网关
+- `backend` 继续作为稳定业务入口
+- `frontend` 负责测试台和业务 UI
+- 先做“可控、可验证、可解释”的 AI 能力，再逐步引入 agent/tool calling
+
+## 当前已完成
+
+### 1. AI 网关基础层
+
+已完成：
+
+- 独立 `aiprovider` 服务
+- `backend -> aiprovider -> model provider` 调用链
+- `provider/status` 与 `situational-awareness/analyze` 稳定接口
+- `X-Request-ID` 透传
+- 轻量超时与重试
+- MiniMax / Anthropic-compatible / OpenAI-compatible / Ollama 适配
+
+相关文件：
+
+- [backend/app/api/v1/ai.py](/home/ray/dev/linkong/planet/backend/app/api/v1/ai.py)
+- [backend/app/services/ai_client.py](/home/ray/dev/linkong/planet/backend/app/services/ai_client.py)
+- [aiprovider/main.py](/home/ray/dev/linkong/planet/aiprovider/main.py)
+- [aiprovider/provider_service.py](/home/ray/dev/linkong/planet/aiprovider/provider_service.py)
+- [docs/agents/aiprovider.md](/home/ray/dev/linkong/planet/docs/agents/aiprovider.md)
+
+### 2. 本地运行与配置打通
+
+已完成：
+
+- `planet.sh` 启动链路纳入 `aiprovider`
+- `planet.sh` 启动完成后输出 Playground 入口
+- `docker-compose.yml` 为 `aiprovider` 加入 `env_file`
+- `backend/.env` 与 `aiprovider/.env` 两侧 service token 对齐
+- `Playground` 状态缓存，避免页面切换时每次都重新请求 provider 状态
+
+相关文件：
+
+- [planet.sh](/home/ray/dev/linkong/planet/planet.sh)
+- [docker-compose.yml](/home/ray/dev/linkong/planet/docker-compose.yml)
+- [backend/.env.example](/home/ray/dev/linkong/planet/backend/.env.example)
+- [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)
+
+### 3. Playground UI 基础版
+
+已完成：
+
+- 新增前端路由 `/playground`
+- 左侧 `Provider 状态 + 测试说明`
+- 右侧 `请求 / 结果` Tabs
+- `Provider 状态` 支持手动刷新
+- `测试说明` 支持折叠
+- 内部区域采用细滚动条
+- 页面布局开始遵循“单屏工作区 + 模块内部滚动”规范
+
+相关文件：
+
+- [frontend/src/pages/Playground/Playground.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Playground/Playground.tsx)
+- [frontend/src/App.tsx](/home/ray/dev/linkong/planet/frontend/src/App.tsx)
+- [frontend/src/components/AppLayout/AppLayout.tsx](/home/ray/dev/linkong/planet/frontend/src/components/AppLayout/AppLayout.tsx)
+- [frontend/src/index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)
+
+### 4. 前端布局规范沉淀
+
+已完成：
+
+- 把“一屏工作区、主模块优先、模块内部滚动”的规范文档化
+- 明确 `BGP` 页面为当前参考实现
+
+相关文件：
+
+- [docs/frontend/frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/frontend/frontend-layout-guidelines.md)
+- [frontend/src/pages/BGP/BGP.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/BGP/BGP.tsx)
+
+## 当前限制
+
+### 1. Playground 还是 prompt playground，不是 agent playground
+
+当前 `Playground` 的 `观察项 / 目标 / 约束条件` 都是人工输入。
+
+模型现在拿到的是：
+
+- 你手工输入的结构化字段
+- 后端传递的少量静态上下文
+
+模型现在拿不到：
+
+- 实时 BGP 事件
+- 真实告警列表
+- 数据源健康状态
+- 自动检索结果
+- tool calling / skills / 自主取数
+
+### 2. `situational-awareness/analyze` 还是通用提示词接口
+
+当前更适合：
+
+- 测试链路
+- 测试模型输出风格
+- 验证不同 provider 是否正常返回
+
+当前还不适合：
+
+- 直接当真实态势系统主入口
+- 让用户手工维护长期分析模板
+- 代替专用业务研判接口
+
+### 3. 还没有可验证的真实业务输入注入
+
+目前最缺的是：
+
+- 从业务系统自动整理“事实输入”
+- 再把这些事实喂给 AI
+
+而不是继续让用户在 Playground 手工输入真实事件摘要。
+
+## 短期计划
+
+### Phase A: Playground 收敛为稳定测试台
+
+目标：
+
+- 保持 Playground 简洁可用
+- 不再继续堆“高级参数”
+
+工作项：
+
+- 继续微调左侧 `Provider 状态` 与 `测试说明` 的空间策略
+- 保持 `请求 / 结果` 为单一主工作区
+- 不引入盲填式高级字段
+- 统一滚动条、卡片、溢出行为
+
+完成标准：
+
+- 笔记本视口下依然可用
+- 各模块标题可见
+- 主要阅读区始终是右侧 Tabs
+
+### Phase B: BGP AI 简报
+
+目标：
+
+- 不再依赖手工填写“观察项”
+- 让系统自动把真实 BGP 数据注入 AI
+- 让 BGP 页面逐步从“摘要汇总”升级为“证据驱动的区域态势分析”
+
+建议实现：
+
+- 新增专用后端接口，例如：
+  - `POST /api/v1/ai/bgp/brief`
+- 后端自动读取：
+  - incidents summary
+  - anomalies
+  - recent events
+  - collector coverage summary
+- 后端将结构化事实注入 `context / observations`
+- 前端在 BGP 页面增加“生成 AI 简报”
+
+当前阶段说明：
+
+- 第一版 `BGP AI 简报` 允许先落地为“值班摘要生成器”
+- 也就是先把 incidents / anomalies / events / collector coverage 自动注入
+- 允许模型先做事实摘要、风险归纳、建议动作
+
+但这不应被视为 Phase B 的最终形态。
+
+Phase B 后续还需要补齐：
+
+- prefix geography 证据注入
+  - `iptoasn`
+  - `opengeofeed`
+  - `nro_delegated`
+- 基于 `affected_regions` 与 prefix geography 的区域聚合
+- 区分“真实区域热度”与“collector coverage 偏差”
+- 对高风险 prefix / ASN 给出更明确的国家、城市、运营商归属线索
+- 让 AI 输出明确回答：
+  - 哪些区域正在异常升温
+  - 哪些结论只是观测站偏差
+  - 当前还缺哪些区域证据
+
+完成标准：
+
+- 用户不需要手工录入 BGP 观察项
+- AI 输出能明确区分“事实”和“研判”
+- AI 不只是复述总量和最近几条事件，还能利用 prefix geography 与 affected regions 做区域态势判断
+- 输出中能明确指出：
+  - 高风险区域
+  - 区域证据来源
+  - collector coverage 偏差对判断的影响
+
+### Phase C: 告警 / 数据源健康 AI 简报
+
+目标：
+
+- 复用同样模式，扩展到其他模块
+
+建议入口：
+
+- `Alerts` 页面：异常与告警摘要
+- `DataSources` 页面：采集失败与健康状态总结
+
+原则：
+
+- 每个业务页优先做“专用 AI 简报”
+- 不优先做“万能大聊天框”
+
+## 中期计划
+
+### 1. Assessment Layer
+
+目标：
+
+- 不只返回自由文本
+- 返回结构化的 assessment
+
+建议输出字段：
+
+- summary
+- key_risks
+- evidence
+- recommendations
+- confidence
+- missing_data
+
+这样后续才能：
+
+- 持久化
+- 回看
+- 对比不同时间的 AI 结论
+- 在 Earth / Dashboard / BGP 页面稳定展示
+
+### 2. Evidence-first Runtime
+
+目标：
+
+- 所有 AI 分析先取真实数据，再调模型
+
+原则：
+
+- 先 evidence
+- 再 prompt
+- 最后才是自由生成
+
+优先要做的不是更强聊天，而是：
+
+- 更稳定的数据注入
+- 更一致的事实模板
+- 更清晰的结果结构
+
+### 3. 按页面提供专用入口
+
+目标：
+
+- 让 AI 成为业务视图的一部分，而不是孤立 playground
+
+优先顺序建议：
+
+1. `BGP` AI 简报
+2. `Alerts` AI 简报
+3. `DataSources` 健康研判
+4. `Dashboard` 总览总结
+
+## 长期计划
+
+### 1. Tool Calling / Agent Runtime
+
+只有在以下基础稳定后再推进：
+
+- 数据源健康信号稳定
+- BGP / Alerts / Datasource evidence 注入稳定
+- assessment 结构稳定
+
+长期可做能力：
+
+- AI 调用受控工具查询业务数据
+- AI 调用检索/web search 做外部验证
+- AI 生成建议而不是直接修改系统
+- 审核后触发受控动作
+
+### 2. 受控动作与闭环
+
+潜在方向：
+
+- 根据健康异常生成修复建议
+- 根据态势变化生成处理建议
+- 进入 review queue
+- 审批后执行
+- 验证结果并形成闭环
+
+### 3. 多模块统一 AI 体验
+
+长期目标不是一个孤立 Playground，而是：
+
+- 每个业务页都有自己的 AI 入口
+- 共享统一的 backend AI facade
+- 共享统一的 assessment 结构
+- 共享统一的 evidence 注入与审计链路
+
+## 设计决策总结
+
+### 为什么保留 `aiprovider`
+
+因为它已经很好地承担了：
+
+- provider 适配
+- 协议兼容
+- service token 边界
+- 独立重启与部署
+
+因此短期内不建议把它并回 `backend`。
+
+### 为什么 Playground 不做成万能聊天页
+
+因为当前更需要的是：
+
+- 稳定测试链路
+- 可验证业务输入
+- 专用分析入口
+
+而不是一个泛化但没有真实数据支撑的聊天框。
+
+### 为什么优先做专用 AI 简报
+
+因为：
+
+- 数据可以自动注入
+- 用户心智更清晰
+- 输出更容易结构化
+- 更容易校验事实与研判是否一致
+
+## 下一步建议
+
+按优先级建议接下来这样做：
+
+1. 稳住 `Playground` 当前布局，不再大幅重做
+2. 在 `BGP` 页面新增专用 “AI 简报” 入口
+3. 后端新增 `BGP brief` 专用接口，自动注入真实数据
+4. 补齐 `BGP brief` 的区域态势证据层
+5. 把 AI 输出逐步从自由文本升级为结构化 assessment
+
+### BGP Brief 后续子项
+
+为避免把“已有 AI 简报”误判成“区域分析已完成”，这里单独记录 `BGP brief` 的后续 backlog：
+
+1. 把高风险 prefix 命中的 `iptoasn / opengeofeed / nro_delegated` 结果注入 brief context
+2. 按国家/城市聚合 active incidents、anomalies、affected prefixes，生成区域热点事实层
+3. 把 collector coverage 与区域热点并排注入，避免模型把观测偏差误判成区域风险
+4. 对高风险 ASN / prefix 追加归属线索，如国家、城市、可能运营商或注册区域
+5. 在输出结构中单独增加：
+   - 区域态势
+   - 证据来源
+   - 观测偏差说明
+   - 缺失区域证据
--- a/docs/frontend/frontend-layout-guidelines.md
+++ b/docs/frontend/frontend-layout-guidelines.md
@@ -0,0 +1,309 @@
+# Frontend Layout Guidelines
+
+本项目后台页面默认遵循“单屏工作区”布局规范。目标不是让页面永远不溢出，而是确保在常见桌面视口下：
+
+- 页面主结构能在一屏内看清
+- 用户能同时看到页头、摘要区和主工作区
+- 超出的内容在模块内部滚动，而不是把整页纵向撑爆
+
+当前推荐参考实现：
+
+- [frontend/src/pages/BGP/BGP.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/BGP/BGP.tsx)
+- [frontend/src/index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)
+
+## 核心原则
+
+### 1. 页面优先保证一屏工作区
+
+管理页默认采用：
+
+- 页头：标题、说明、主要操作
+- 主工作区：统计卡、表格、图表、列表、标签页
+
+推荐结构：
+
+```tsx
+<AppLayout>
+  <div className="page-shell">
+    <div className="page-shell__header">...</div>
+    <div className="page-shell__body">...</div>
+  </div>
+</AppLayout>
+```
+
+页面总高度应被限制在 `AppLayout` 内容区内，而不是继续让整个页面自然向下增长。
+
+### 2. 滚动优先发生在模块内部
+
+如果表格、日志、长列表、图表明细超出空间：
+
+- 让卡片内部滚动
+- 让表格内部滚动
+- 让标签页内容区内部滚动
+
+不要默认依赖整个页面滚动去“解决”空间问题。
+
+### 3. 主工作区必须拿到主要空间
+
+页面里最重要的模块必须是视觉和空间上的主角。通常应保证：
+
+- 页头始终可见
+- 摘要区高度被控制
+- 主表格 / 主图表 / 主分析区占据 50% 以上可视高度
+
+如果一个页面有多个大模块，优先顺序是：
+
+1. 先压缩说明区和摘要区
+2. 再把次级模块收进标签页或切换视图
+3. 最后才考虑继续增加整页滚动
+
+### 4. 小屏幕和高缩放必须进入紧凑模式
+
+在窗口高度较低、宽度较窄、或系统缩放较高时，应主动切换紧凑布局，例如：
+
+- 缩小卡片 padding
+- 缩小表头和单元格间距
+- 将摘要区改为更紧凑的单行/横向滚动布局
+- 将次级模块移入标签页、抽屉、折叠区
+
+紧凑模式的目标是保持可用，不是单纯把文字和控件一股脑缩小。
+
+### 5. overflow 责任必须明确
+
+页面中的大块内容必须明确：
+
+- 谁负责占满剩余高度
+- 谁负责裁剪
+- 谁负责滚动
+
+常见要求：
+
+- 父容器链路需要 `min-height: 0`
+- 工作区容器通常需要 `display: flex`
+- 真正的滚动节点要显式 `overflow: auto`
+
+### 6. 卡片不能被压到不可读
+
+历史上我们反复踩到的问题不是“没有滚动条”，而是：
+
+- 卡片被 `flex` 压缩得只剩一小条可视区域
+- 文字能渲染，但读不完整
+- 内容其实存在，却被 `overflow: hidden` 裁掉
+
+因此后续约束是：
+
+- 先保证卡片有可读的最小高度
+- 如果继续压缩会影响阅读，就切换成内部滚动
+- 不要为了“保持一屏”而把正文、表格、描述区压成无法阅读的条状区域
+
+### 7. Tabs 不是天然安全的布局容器
+
+历史上 Tabs 相关回归非常多，典型问题包括：
+
+- 隐藏 tab pane 因为自定义 `display: flex` 而重新露出来
+- 所有 tab 被强行套用同一套高度/overflow 规则
+- 表格 tab 能工作，但 markdown / help / diagnostics tab 被压坏
+
+因此约束是：
+
+- `Tabs` 里的每类内容都要单独定义自己的布局策略
+- 表格 tab 可以是“固定高度 + 内部滚动”
+- 文档/Markdown tab 更适合“tab pane 自身滚动 + 内容正常文档流”
+- 如果覆盖组件库样式，必须同时检查 hidden 状态是否仍然成立
+
+### 8. 摘要区优先进入紧凑模式，而不是挤压正文
+
+历史经验表明，最容易被误处理的是顶部摘要卡：
+
+- 它们经常为了“都放下”被强行压窄
+- 然后正文、表格、AI 结果区一起失去主空间
+
+后续统一约束：
+
+- 小屏或高缩放时，摘要卡优先：
+  - 降低 padding
+  - 改成横向滚动
+  - 改成更紧凑的网格
+- 不要优先牺牲主工作区的可视面积
+
+### 9. 长文档类内容优先保证阅读体验
+
+像下面这些内容，不能直接套用“表格工作区”的逻辑：
+
+- AI 简报
+- 运行日志
+- 原始 JSON
+- 帮助说明
+- 多段描述性文本
+
+这些区域应该优先满足：
+
+- 标题和元信息稳定可见
+- 正文有明确的最小可读高度
+- 正文滚动策略单独定义
+- 支持 Markdown 表格、分隔线、引用、代码块等结构
+
+### 10. 高度关键路径要少包一层
+
+历史上不少滚动问题不是组件本身错，而是多包了一层之后：
+
+- 高度链路断掉
+- `min-height: 0` 没传下去
+- `overflow` 责任被吃掉
+
+因此：
+
+- 对高度关键区域，优先使用最直接的 DOM 结构
+- 使用 `Space`、额外包装 `div`、第三方布局容器时，要确认它们不会改变滚动和高度语义
+- 如果一个区域已经出现“内容明明有，但只剩一条缝”，优先怀疑中间包装层
+
+## 历史坑位总结
+
+从 Earth、Playground、BGP、DataSources 这些页面的 bugfix 可以归纳出几类高频坑：
+
+### 1. 用 `overflow: hidden` 掩盖布局问题
+
+表面上看页面“整齐了”，实际上会导致：
+
+- 内容被裁掉
+- tab 内容只剩一条缝
+- 面板明明渲染成功，但用户看不见
+
+正确做法：
+
+- 让真正的内容节点滚动
+- 不要让上层容器无差别裁剪所有子内容
+
+### 2. 把所有 tab 当成同一种内容
+
+表格、Markdown、帮助卡、日志流的空间需求完全不同。
+
+正确做法：
+
+- 表格：固定工作区 + 内部滚动
+- 文档：普通流式内容 + pane 级滚动
+- 侧边说明：内容驱动高度，不强行拉满
+
+### 3. 只做视觉缩小，不做空间重分配
+
+这会导致：
+
+- 卡片文字被截断
+- 表格只剩 1 到 2 行
+- 按钮和筛选区挤成一团
+
+正确做法：
+
+- 紧凑模式优先重排
+- 横向滚动摘要区
+- 折叠/收纳次级模块
+
+### 4. 父容器高度链不完整
+
+这是最常见的内部滚动失效原因。
+
+检查顺序：
+
+1. 外层是否真的有确定高度
+2. flex 父容器是否带了 `min-height: 0`
+3. 真正滚动节点是否明确 `overflow: auto`
+4. 中间包装层是否偷偷改了布局语义
+
+### 5. UI 状态和显示状态不同步
+
+Earth 相关改动里反复出现：
+
+- 图层隐藏了，但 hover/lock 还在
+- tooltip 还在显示旧对象
+- legend 没跟着切换
+
+这类约束同样适用于后台页面：
+
+- 被隐藏、卸载、切换出视图的内容，不应继续保留活跃交互状态
+
+## 推荐实现模式
+
+### 页面骨架
+
+优先复用项目里已有的通用结构：
+
+- `.dashboard-content-inner`
+- `.page-shell`
+- `.page-shell__header`
+- `.page-shell__body`
+- `.table-scroll-region`
+
+不要每个页面都重新发明一套完全不同的高度和滚动语义。
+
+### 表格工作区
+
+推荐模式：
+
+```tsx
+<Card>
+  <div className="table-scroll-region" ref={tableRegionRef}>
+    <Table
+      pagination={false}
+      scroll={{ x: 1200, y: tableHeight }}
+    />
+  </div>
+</Card>
+```
+
+要求：
+
+- 表格尽量在卡片内部滚动
+- `scroll.y` 应来自实际可用高度估算，而不是完全静态的魔法数字
+- 父容器链路要保证 header、body、content 的 overflow 都在表格内部闭合
+
+### 多模块页面
+
+如果一个页面同时有：
+
+- 摘要卡
+- 表格
+- 异常明细
+- 最近事件
+
+不建议简单纵向堆叠全部模块。优先使用：
+
+- 顶部摘要 + 底部单一主工作区
+- 标签页切换多个次级数据视图
+- 左右分栏，并保证每栏内部独立滚动
+
+## 不推荐的做法
+
+以下模式默认视为不符合本项目页面规范：
+
+- 依赖整页纵向滚动来显示主要工作区
+- 一个页面纵向堆 3 到 4 个大卡片，每个都想完整展示
+- 表格没有内部滚动，导致缩放后只能看到 1 到 2 行数据
+- 父容器缺少 `min-height: 0`，导致内部滚动失效
+- 只做视觉缩小，不处理真正的空间分配
+
+## 页面验收检查清单
+
+提交前至少检查：
+
+- 页头、摘要区、主工作区能否同时出现
+- 主工作区是否拿到了页面中最多的高度
+- 表格或明细溢出时，滚动条是否出现在模块内部
+- 卡片是否被压缩到文字显示不完整；如果会，是否已经切换为内部滚动
+- 浏览器缩放到 `125%` / `150%` 时是否仍可用
+- 低高度窗口下是否还保有合理的可见内容行数
+- Tabs、Card、Table 在 overflow 时是否仍可操作
+- 非表格 tab（Markdown、帮助说明、日志）是否有独立且合理的滚动策略
+
+## 落地顺序
+
+后续新增或重构后台页时，优先按这个顺序设计：
+
+1. 先定义主工作区
+2. 再确定哪些模块必须常驻可见
+3. 最后再做样式和视觉层次
+
+简单说：
+
+- 先保证空间分配正确
+- 再处理滚动边界
+- 最后再做美化