# Skill Factory 调用指南

skill-factory 运行时根据此文件决定每个步骤该调用哪个 AI，以及调用失败时如何降级。

> **说明**：这是一个配置模板，请根据你自己的 AI 服务填写具体的密钥和地址。

---

## 一、AI 服务配置

你可以配置多组 AI 服务，通过不同密钥访问不同模型族：

| 密钥组 | 覆盖模型（示例） | 用途 |
|--------|---------|------|
| GPT 系列 | gpt-4o, gpt-4-turbo 等 | 写作、代码 |
| Google Gemini | gemini-pro, gemini-flash 等 | 深度研究、快速生成 |
| Claude 系列 | claude-sonnet, claude-opus 等 | 高质量输出 |

**所有外部 AI 统一走 OpenAI 兼容格式**，具体密钥和 endpoint 见 `tech-library.md`。

---

## 二、Fallback 三级降级链

```
调用请求进来
│
├─ 1. 主用 AI（你配置的首选 AI 服务）
│     ├─ 成功 → 返回结果
│     └─ 失败（连续 2 次）→ 记录原因
│           │
│           ├─ 2. 备用 AI（你配置的备用 AI 服务）
│           │     ├─ 成功 → 返回结果
│           │     └─ 失败（连续 2 次）→ 记录原因
│           │           │
│           │           └─ 3. 降级保险：AI 自身执行
│           │                 └─ 无需 API，直接在上下文中完成
│           │
│           └─ 备用 AI 未配置 → 直接进入降级保险
│
└─ 主用 AI 未配置 → 直接使用 AI 自身
```

### 降级规则

| 规则 | 说明 |
|------|------|
| **失败判定** | 同一 AI 连续失败 2 次才触发降级（单次失败先重试） |
| **失败类型** | HTTP 错误、超时（30s）、空响应、JSON 解析失败、内容明显异常 |
| **记录日志** | 每次降级记录：日期、AI、失败原因、降级到谁 |
| **下次重试** | 降级不是永久的——下一个新任务仍先尝试主用 AI |
| **评审不外包** | 评审验收步骤始终由规划层 AI 执行，不走降级链 |

### 终止条件

当所有 AI（含自身）都无法产出合理结果时：

- 终止当前迭代
- 向用户报告："所有 AI 执行层均无法满足要求"
- 列出各 AI 的失败原因
- 建议：调整需求 / 更换 API / 降低质量标准

---

## 三、场景-AI 对照表

| 任务类型 | 推荐模型类型 | 原因 |
|---------|------------|------|
| 长文写作 | GPT 系列（通用型） | 文本生成能力强 |
| 素材整理/摘要 | Gemini 系列 | 长上下文处理能力 |
| 快速草稿 | 轻量模型（如 GPT mini/flash） | 速度优先 |
| 翻译 | GPT 系列 | 多语言能力 |
| 创意发散 | GPT 系列 | 创意输出 |
| 代码生成 | 代码专用模型（如 Codex） | 代码质量 |
| 深度推理 | 思考链模型（如 thinking 系列） | 复杂推理 |
| 最高质量输出 | 旗舰模型（如 Opus/GPT-4） | 综合能力 |
| 素材搜集+事实核查 | 搜索增强模型 | 联网能力 |
| 结构化分析 | AI 自身 | 逻辑推理强，不需外部 |
| 评审验收 | AI 自身 | **必须自身执行，不可外包** |

**使用说明**：
- 根据你的实际 AI 服务配置，填入对应的模型名称
- 主用失败时先切备用同类模型，再降级到 AI 自身
- 评审验收是唯一不走外部 AI 的环节

---

## 四、统一调用模板

所有第三方 API 使用 OpenAI 兼容格式：

```bash
curl -s <你的API地址>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的API密钥>" \
  -d '{
    "model": "<模型名称>",
    "messages": [
      {"role": "system", "content": "<系统提示>"},
      {"role": "user", "content": "<用户提示>"}
    ],
    "max_tokens": 4096,
    "temperature": 0.7
  }'
```

### 响应解析

```bash
# 1. 调用并存储响应
RESPONSE=$(curl -s -m 30 <你的API地址>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的API密钥>" \
  -d "${REQUEST_BODY}")

# 2. 检查错误
# 如果响应包含 error 字段 或 没有 choices 字段 → 重试/降级

# 3. 提取内容
# 从 choices[0].message.content 获取 AI 输出
```

---

## 五、踩坑记录

> 每次降级和异常记录在此，方便追踪和优化。

| 日期 | 层级 | AI 服务 | 问题 | 降级到 | 备注 |
|------|------|---------|------|--------|------|
| - | - | - | （暂无记录） | - | - |

---

## 六、参考文档

- 技术库配置：[tech-library.md](tech-library.md)
- Skill Factory 本体：[SKILL.md](SKILL.md)