# 09. 外部系统 Skill：ELK、SQL、模型迭代

![外部系统 Skill 接入模式](assets/09-external-skills.png)

## 1. 这类 Skill 的共同特征

外部系统 Skill 的核心不是复杂 prompt，而是把某个内部系统的调用方式、参数约定、依赖和输出格式打包起来。

典型形态：

```text
SKILL.md
  写清楚什么时候用、参数怎么选、哪些动作需要确认。

scripts/
  执行真实外部系统调用。

python_exec
  作为统一执行入口。

python_package
  处理依赖缺失。

output/
  查询结果或报表写入当前 session output。
```

## 2. elk-fetch

位置：

```text
skills/elk-fetch/SKILL.md
skills/elk-fetch/elk_query.py
```

定位：

```text
按 request id 或查询条件读取小米内网 ELK 日志。
```

实现方式：

- `SKILL.md` 写明支持的 profile 和查询方式。
- 实际执行必须使用 `python_exec.script_path`。
- 缺 `elasticsearch`、`urllib3` 时用 `python_package`。
- 不让模型用 bash 手写临时 Python 查询脚本。

典型价值：

```text
把“怎么查 ELK”这类个人经验变成团队共享能力。
```

和 `online-mining-v2` 的区别：

```text
elk-fetch
  更偏单次日志查询和调试。

online-mining-v2
  更偏批量挖掘、策略迭代、样本转换。
```

## 3. data-factory-sql

位置：

```text
skills/data-factory-sql/SKILL.md
skills/data-factory-sql/run_sql.py
```

定位：

```text
通过 Kyuubi HTTP API 执行数据工场 SQL，轮询状态并下载 CSV 结果。
```

实现方式：

- 用户直接给 SQL 时，可以确认后执行。
- 用户只给分析需求时，Agent 可以先生成 SQL 草稿，再让用户确认。
- 执行必须通过 `python_exec.script_path`。
- 输出默认写入当前 session output。

这个 Skill 的门禁重点是：

```text
SQL 执行前确认。
控制查询范围和 limit。
输出路径清晰。
失败时展示错误和可调整建议。
```

## 4. model-iteration

位置：

```text
skills/model-iteration/SKILL.md
skills/model-iteration/scripts/
```

定位：

```text
模型训练、评估、数据准备和迭代流程辅助。
```

这类 Skill 属于混合工程型：

- 有流程。
- 有脚本。
- 有配置。
- 可能调用外部训练平台。
- 高风险动作较多。

因此它更需要明确：

```text
哪些步骤只是分析。
哪些步骤会启动训练。
哪些步骤需要用户确认。
输出目录和实验记录在哪里。
```

## 5. 外部 Skill 的通用约定

### 5.1 调用方式

优先：

```json
{
  "script_path": "skills/<skill-name>/scripts/run.py",
  "stdin": "{...}",
  "timeout_seconds": 120
}
```

或者脚本在 Skill 根目录时：

```json
{
  "script_path": "skills/elk-fetch/elk_query.py",
  "args": ["..."]
}
```

### 5.2 依赖处理

依赖缺失时：

```text
python_package(action="install", packages=[...])
```

不要：

```text
bash pip install ...
bash python ...
```

### 5.3 输出处理

外部系统查询结果应该：

- stdout 给结构化摘要。
- 大结果写入 `output/` 或 `scratchpad/`。
- 返回实际文件路径。
- 避免把大量数据直接塞进最终回复。

### 5.4 安全和确认

需要确认的动作：

- 执行大范围 SQL。
- 启动训练。
- 写外部路径。
- 推送代码或数据仓库。
- 导出可能包含敏感字段的线上数据。

只读、小范围、用户明确指定 rid 或 SQL 的查询，可以直接执行，但仍要控制结果规模。