docs: add technical architecture guide

docs/technical-architecture/09-external-skills.md

@@ -0,0 +1,186 @@
+# 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 的查询，可以直接执行，但仍要控制结果规模。