zk-data-agent/docs/technical-architecture/09-external-skills.md

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

1. 这类 Skill 的共同特征

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

典型形态：

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

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

python_exec
  作为统一执行入口。

python_package
  处理依赖缺失。

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

2. elk-fetch

位置：

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

定位：

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

实现方式：

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

典型价值：

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

和 online-mining-v2 的区别：

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

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

3. data-factory-sql

位置：

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

定位：

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

实现方式：

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

这个 Skill 的门禁重点是：

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

4. model-iteration

位置：

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

定位：

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

这类 Skill 属于混合工程型：

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

因此它更需要明确：

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

5. 外部 Skill 的通用约定

5.1 调用方式

优先：

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

或者脚本在 Skill 根目录时：

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

5.2 依赖处理

依赖缺失时：

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

不要：

bash pip install ...
bash python ...

5.3 输出处理

外部系统查询结果应该：

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

5.4 安全和确认

需要确认的动作：

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

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