# ISS-0082 Plan: 诊断技能不支持 TiDB Operator（OP）客户的 Clinic 数据接入

## Background

**Source**: GitHub issue #514 (Lark workspace `lark-ws-c07ef671-e0c8-4f18-bc96-ae5fdb1850bd`)
**User feedback**: "这个是 op 客户，需要支持一下基于 op clinic 进行分析"

The user reported that a customer is running TiDB on TiDB Operator (self-hosted Kubernetes, "OP" / on-premise) and wants to use Investibook's diagnosis capabilities. The current system only supports TiDB Cloud clusters via the PingCAP Clinic SaaS API.

## Problem

The current `clinic-cli` skill is designed exclusively for TiDB Cloud clusters:
- Uses TiDB Cloud Clinic API (`CLINIC_API_KEY`, `CLINIC_ENV`, `CLINIC_ENDPOINT`)
- Cluster IDs are TiDB Cloud-format (e.g., `1234567890`)
- `tidb-clinic-diagnosis` SKILL.md assumes Cloud cluster context

OP customers run PingCAP Clinic on their own infrastructure. The OP Clinic has:
- A different API endpoint (customer-hosted or `clinic.pingcap.com` upload → retrieval)
- Different auth mechanism (OP Clinic token)
- Different cluster identification (org + cluster name, not Cloud cluster ID)
- Potentially different API surface (some endpoints may be unavailable or have different schemas)

## Root Cause

The `clinic-cli` skill and `tidb-clinic-diagnosis` workflow were built solely with TiDB Cloud in mind. There is no routing logic for OP environments, no documentation on how to obtain OP Clinic credentials, and no tested query patterns for OP Clinic data.

## Fix Plan

### Step 1: Clarify OP Clinic API surface

Determine what API endpoints OP Clinic exposes versus Cloud Clinic:
- Does OP Clinic support the same `/api/v1/clusters`, `/api/v1/metrics`, `/api/v1/slow-query`, `/api/v1/log` endpoints?
- What authentication scheme does OP Clinic use?
- How are cluster IDs formatted in OP Clinic?

**Owner**: Platform/Clinic team — needs API documentation for OP Clinic.

### Step 2: Add CLINIC_ENV routing in clinic-cli

Extend `agentkit/skills/builtin/clinic-cli/SKILL.md` to document:
- `CLINIC_ENV=op` or a new env var `CLINIC_OP_ENDPOINT` for OP Clinic endpoint
- Auth: `CLINIC_OP_API_KEY` or equivalent
- Note differences in cluster ID format and any endpoint availability gaps

```markdown
## OP Clinic (TiDB Operator) Support

Set the following env vars for OP customers:
- `CLINIC_ENDPOINT=<op-clinic-base-url>` (e.g., `https://clinic.example.com`)
- `CLINIC_API_KEY=<op-clinic-token>`
- `CLINIC_ENV=op`

Known limitations for OP Clinic:
- Activity Hub events may not be available (depends on version)
- Cluster ID format: `<org>/<cluster-name>` instead of numeric Cloud ID
```

### Step 3: Add OP detection in tidb-clinic-diagnosis

In `agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md`, add an early routing step:

```
## A0: Detect deployment type
- If Jira ticket or user context mentions "op" / "operator" / "on-prem" / "自建":
  - Set CLINIC_ENV=op, ask user for OP Clinic endpoint and token
  - Note OP-specific limitations (Activity Hub may be unavailable)
- Otherwise: proceed with Cloud Clinic (default)
```

### Step 4: Handle workspace sources for OP

The workspace currently requires a `jira_issue` source type. For OP customers:
- May need a new source type for OP cluster context
- Or extend `jira_issue` to carry OP Clinic connection info in metadata

### Step 5: Test with a real OP workspace

Once API documentation is available, test with a real OP Clinic endpoint:
1. Create a test workspace with an OP Jira ticket
2. Run `tidb-clinic-diagnosis` with OP Clinic env vars
3. Verify metrics, slow query, and log queries work correctly

## Verification

The fix is complete when:
1. A workspace for an OP customer can successfully run `clinic-cli` against the OP Clinic API
2. `tidb-clinic-diagnosis` correctly routes to OP Clinic when the ticket/context indicates OP deployment
3. The SKILL.md documents OP Clinic env var setup clearly

## Notes

- This is a cross-cutting change affecting both `clinic-cli` and `tidb-clinic-diagnosis`
- The platform team needs to provide OP Clinic API documentation before implementation
- Consider whether OP Clinic auth should be stored in workspace sources (similar to how Jira issues are stored) or passed as env vars