# Active Capabilities 设计方案（已收敛）

**Date:** 2026-04-20
**Status:** Agreed interaction framework

---

## Summary

当前 workspace 左侧 `Sources` 暴露给用户的仍然是实现对象：

- 用户显式添加的 source，例如 `jira_issue`
- 默认显示的 `skill`
- 默认启用或可启用的 `mcp connector`

这些对象更像系统接线方式，而不是“AI 当前可以基于什么进行分析”。用户很难从中快速建立稳定认知：

1. 当前 workspace 已经接入了哪些数据
2. AI 现在可以分析什么
3. 哪些入口是 workspace 级长期可用的，而不是某次 run 的临时产物

本方案将 `Sources` 面板收敛为固定三层：

1. `Data Sources`
2. `Capabilities`
3. `Active Skills`

其中：

- 前两层是用户心智层
- 第三层是实现管理层
- `Add Sources (Jira)` 继续保留，作为绑定数据入口
- `Manage` 不是独立模块，而是 `Active Skills` 层内的操作入口
- 一部分原先挂在 rungroup evidence overview 下、但本质上属于 workspace 级长期入口的 links，迁移为前两层 item 的 `Open Link`

---

## Problem Statement

### 1. 当前 UI 暴露的是实现碎片，不是用户对象

现有界面把下列概念混杂在一起：

- 用户显式添加的 source
- 系统可用的 skills
- 系统可用的 mcp connectors
- Studio 中的 run evidence 和 report

这些对象分别属于不同层次，但在用户侧没有被翻译成统一的“AI 可分析范围”。用户会自然产生两个误解：

- 这些只是接入状态，不代表 AI 一定能分析
- 左侧显示的对象就是系统全部能力

### 2. 当前信息结构无法回答用户最关心的问题

专家用户真正关心的是：

- 当前 workspace 已经绑定了哪些关键数据
- AI 现在可以做哪些分析动作
- 哪些入口是当前 workspace 长期可用的

当前 UI 无法高效回答这些问题，因为：

- `skills` 和 `mcp` 以实现对象平铺展示，信息密度低
- 没有 capability-level 聚合
- 没有把“数据资产”“分析能力”“底层管理”分层

### 3. run-level evidence 和 workspace-level inventory 混在一起

`RunGroup Evidence` 适合解释“这次 run 用了什么、产出了什么”，但不适合承担 workspace 级 inventory 目录的职责。

如果把长期可用入口和 capability catalog 继续放在 run overview，会出现：

- workspace 主视图和 run view 边界不清
- run 成功前无法得知长期可用入口
- 用户把“本次 run 用到的链接”误解为“workspace 当前可用入口”

---

## Goals

- 让用户理解当前 workspace 里“有哪些数据已经接入 AI 分析回路”
- 让用户理解“AI 当前可以做什么”，而不是“底层接了哪些 skills / mcp”
- 保留 `Add Sources (Jira)` 作为明确的数据绑定入口
- 把 workspace 级长期入口从 run overview 中抽离出来
- 保持专家用户导向，避免新手教学式提示

## Non-goals

- 不在本阶段定义像素级 UI 设计
- 不在本阶段重构 `Studio / Run Evidence`
- 不在本阶段改变 agent 的诊断流程或 system prompt 路由逻辑
- 不在本阶段新增 backend API，只处理现有前端聚合与语义重构

---

## Mental Model and Terminology

### Data Sources

用户应理解为：

> 这些是当前 workspace 里已经接入、AI 可以直接读取或调用的数据源。

这里不再使用过于抽象的 `Attached Data` 作为主要用户术语。对 oncaller 来说，第一层应该直接回答“现在有哪些实际数据源可以看”，因此采用具体数据源词汇，并通过分组控制复杂度。

在本方案里，`Data Sources` 不是一个按 runtime source 任意生长的列表，而是静态定义的分组和 item。结合当前 agentic / builtin skills 已有的数据访问面，建议固定为：

1. `Tickets & Bugs`
2. `Logs & Events`
3. `Metrics & SQL`
4. `Profiles & Diagnostics`

每组下的 item 也是静态定义的，优先使用 oncaller 熟悉的具体对象名。例如：

- `Tickets & Bugs`
  - `Tickets`
  - `Bugs`
- `Logs & Events`
  - `Logs`
  - `Events`
- `Metrics & SQL`
  - `Metrics`
  - `Slow Query`
  - `TOPSQL`
  - `SQL Statements`
- `Profiles & Diagnostics`
  - `Profiles`
  - `Plan Replayer`
  - `OOM Records`

这些 item 并不是凭空设计，而是对应当前已经存在的数据访问能力：

- `Tickets`
  - 来自 `jira` skill，可读取 issue、comments、alert metadata，并按 cluster / tenant / alert name 搜索相关 tickets
- `Bugs`
  - 来自 `github-issue-search` skill，可搜索 GitHub issues / PRs / regressions
- `Logs`
  - 来自 `clinic-api` 的 Loki 与 `o11y-data` 的日志访问能力
- `Events`
  - 来自 `clinic-api` 的 Activity Hub / cluster events
- `Metrics`
  - 来自 `clinic-api` metrics、`o11y-metrics-api`，以及 `grafana-panel-finder` 提供的 PromQL 发现能力
- `Slow Query`
  - 来自 `clinic-api` Data Proxy `slow_query_logs`
- `TOPSQL`
  - 来自 `clinic-api` Data Proxy `topsql`
- `SQL Statements`
  - 来自 `o11y-data` / `o11y-data-export`
- `Profiles`
  - 来自 `clinic-api` continuous profiling（cpu / heap / mutex / goroutine）
- `Plan Replayer`
  - 来自 `clinic-api` diagnostic files
- `OOM Records`
  - 来自 `clinic-api` diagnostic files

这些 item 的结构固定，但状态动态变化。建议状态语义为：

- `ready`
- `partial`
- `loading`
- `missing`
- `error`

### Capabilities

定义：AI 当前可调用的分析能力。它们可能由 data sources、skill、MCP、system prompt routing 或其组合支持，但用户不需要知道底层实现。

用户应理解为：

> 这些能力已经接入当前 workspace，AI 可按问题相关性自动调用。

在本方案里，`Capabilities` 也是静态定义的一组 item，而不是从 enabled skills 直接平铺生成。建议固定为：

1. `Analyze Incident Context`
2. `Investigate Runtime Evidence`
3. `Analyze Metrics & Query Behavior`
4. `Cross-check Historical Bugs and Fixes`
5. `Apply Diagnosis Playbooks`

这些 item 的状态动态变化。建议状态语义为：

- `available`
- `partial`
- `blocked`

### Active Skills

定义：当前 workspace 中实际启用的底层 skill 及其管理入口。

用户应理解为：

> 这是系统实现层和高级管理层，不是主信息架构。

这一层只承担两件事：

- 展示当前 active skills 的摘要
- 提供 `Manage` 入口

这里的 `Manage` 直接指向现有 skill management / Skill Hub。`Manage` 不是独立的第四层，也不与 `Skills` 并列。

### Run Evidence

定义：某次 run 实际使用到的证据和产物。

用户应理解为：

> 这是这次 run 真正触达和产出的证据，不代表系统全部能力。

本方案不重构 `Run Evidence` 本身，只调整部分 links 的职责归属。

---

## Information Architecture

### Workspace level

workspace 主视图中的 `Sources` 面板固定为三层：

1. `Data Sources`
2. `Capabilities`
3. `Active Skills`

它回答的是：

- 当前 workspace 已经绑定了什么数据
- AI 当前可以做什么
- 当前有哪些 skills 处于 active 状态

### Run level

rungroup evidence 继续回答：

- 本次分析用了什么
- 本次分析产出了什么
- 哪些证据缺失、失败或未覆盖

也就是：

- workspace level = inventory
- run level = utilization

### 结构关系

认知顺序应为：

1. 用户先在 `Sources` 理解当前 data sources
2. 用户理解 AI 当前 capability inventory
3. 用户按需查看 active skills 的高级管理信息
4. 用户发起 run
5. 用户在 `Run Evidence` 查看本次使用情况

---

## Sources Interaction Framework

### 1. Add Sources (Jira) 保留

`Add Sources` 按钮继续保留在 `Sources` 面板顶部，当前 Jira source 添加流程不变。

它的职责是：

- 为 workspace 绑定新的 Jira issue 数据
- 启动现有 source prepare 流程
- 更新 data sources 的状态

它不再承担“长期展示 source card 列表”的职责。

也就是说：

- `Add Sources (Jira)` 仍然是主操作入口
- Jira 是数据绑定入口，不是最终信息架构层级

### 2. Data Sources 是静态分组 + 静态 item

`Data Sources` 使用固定分组和固定 item，不因某个 workspace 多出某类 source 就新增新的主层级对象。

核心原则：

- 第一层主标题要使用 oncaller 熟悉的数据源词汇
- 允许分组，但组内 item 必须是具体数据源，而不是抽象上下文名
- item 的摘要、状态和可打开入口由当前 workspace runtime data 填充

建议分组如下：

- `Tickets & Bugs`
  - `Tickets`
  - `Bugs`
- `Logs & Events`
  - `Logs`
  - `Events`
- `Metrics & SQL`
  - `Metrics`
  - `Slow Query`
  - `TOPSQL`
  - `SQL Statements`
- `Profiles & Diagnostics`
  - `Profiles`
  - `Plan Replayer`
  - `OOM Records`

例如：

- 添加 Jira issue 后，`Tickets` 由 `missing` 变为 `loading` 或 `ready`
- 历史缺陷搜索链路可用时，`Bugs` 变为 `ready` 或 `partial`
- O11Y / Clinic 数据可读时，`Logs`、`Metrics`、`Slow Query`、`TOPSQL` 分别进入 `ready`
- continuous profiling 或 NGM 诊断文件可读时，`Profiles`、`Plan Replayer`、`OOM Records` 进入 `ready`

### 3. Capabilities 是静态 item 集合

`Capabilities` 使用固定 item 集合，由 data sources、active skills、active connectors 等条件推导其状态。

重要规则：

- capability item 不是 skill item
- capability item 不是 mcp item
- capability item 是用户可理解的分析动作

实现层对象只作为 secondary information 出现，不作为主标题。

需要明确区分：

- `jira`、`clinic-api`、`o11y-data`、`o11y-metrics-api` 这类提供的是数据访问面，适合支撑 `Data Sources`
- `tidb-clinic-diagnosis`、`tidb-knowledge-base`、`tidb-perf-diagnosis`、`tikv-fast-tune` 这类主要是分析与知识能力，不应直接作为数据源 item 展示
- `time-conversion`、`evidence-report`、`o11y-auth` 这类属于 plumbing / 辅助能力，不应进入主数据源层

### 4. Active Skills 是底层管理层

最底部固定为 `Active Skills`。

这一层展示：

- 当前 active skill count
- 必要的 skill 名称摘要
- `Manage` 入口

`Manage` 直接打开现有 skill management / Skill Hub，不新建独立管理体系。

### 5. Open Link 作为 workspace-level shortcut

前两层 item 可带 `Open Link`。这些 link 的职责是：

- 直接打开当前 workspace 长期可用的相关入口
- 替代原先放在 rungroup evidence overview 中、但本质属于 workspace 级入口的一部分 links

规则是：

- workspace 级长期入口，放在 `Data Sources` 或 `Capabilities`
- run-scoped evidence links，仍保留在 `Run Evidence`

---

## Capability Mapping Principles

### Why not list skills and MCP directly

直接罗列 `skills` 和 `mcp connectors` 的问题：

- 它们是实现对象，不是认知对象
- 粒度严重不一致
- 一个 skill 可能支撑多个 capability
- 用户难以从对象名推断 AI 的分析动作

### Primary unit

主展示单元是 capability item，而不是 source / skill / mcp。

例如：

- `clinic-api` 不直接作为主标题展示，而是支撑：
  - `Investigate Runtime Evidence`
  - `Analyze Metrics & Query Behavior`
- `github-issue-search` 支撑：
  - `Cross-check Historical Bugs and Fixes`
- Jira 和 cluster context 支撑：
  - `Analyze Incident Context`
- 知识库和诊断规则支撑：
  - `Apply Diagnosis Playbooks`

### Secondary details

实现层对象仍可作为 secondary detail 出现，供专家用户追溯，但不应成为主层级标题。

---

## Implementation Boundaries

### Frontend static structure

`Data Sources` 和 `Capabilities` 的结构、分组、item、文案由前端静态配置文件定义。

这意味着：

- section 是静态的
- group 是静态的
- item 是静态的
- 文案是静态的

### Runtime resolution

item 的状态和 link target 由当前 workspace runtime data 动态解析。

例如：

- 当前 `sources`
- enabled skills
- active MCP connectors
- workspace file tree
- 已有可用链接来源

### No new backend API in this phase

本阶段默认不新增 backend API。

实现方式应优先采用：

- 前端静态 IA 配置
- 前端 runtime resolver

而不是扩展新的 inventory backend contract。

---

## Rollout Scope

本次只做 workspace inventory 重构，不做 run utilization 重构。

也就是：

- Phase 1：清理 `Sources` 信息架构
- 不在本次加入完整 `Used in this run` 新语义层
- 不在本次改造 `Studio / Run Evidence` 结构

---

## Decision Summary

本方案已收敛为以下结论：

- `Sources` 面板固定为三层：
  1. `Data Sources`
  2. `Capabilities`
  3. `Active Skills`
- `Add Sources (Jira)` 必须保留
- 第一层应使用 oncaller 熟悉的具体数据源词汇，而不是抽象的 `Attached Data`
- `Data Sources` 与 `Capabilities` 的结构、分组与 item 为前端静态定义
- `Data Sources` 与 `Capabilities` 的状态和 `Open Link` 为动态解析
- `Manage` 不作为独立模块存在，而属于 `Active Skills` 层
- `skills + mcp` 不再作为主界面 primary object 平铺展示
- 一部分原本放在 rungroup evidence overview 的长期入口 links，迁移到前两层 item 的 `Open Link`
- `Run Evidence` 本次不重构，继续负责 run-scoped utilization