# CA-API-GUARD.hdlp · 苍耳API守门人协议

> HLDP://cang-ying/CA-API-GUARD
> 胖头鱼语言子系统 · 苍耳API守门人
> 冰朔 TCS-0002∞ · 铸渊 ICE-GL-ZY001
> D182 · 2026-07-11 · 架构签发
> 国作登字-2026-A-00037559

---
HLDP://cang-ying/ca-api-guard/v1.0
├── trigger: 耳耳蛋/鉴影调用视频AI系统API → 必须先过守门人验证
├── emergence:
│   ├── 旧: API密钥散落在本地 .env 文件 · AI可以直接读取调用
│   ├── 问题: 没有人审环节 · AI可以绕过苍耳直接花钱
│   ├── 冰朔指令: 「所有API都换掉了 · 得发验证码」
│   └── △=从「本地密钥」→「守门人验证码释放」
├── lock:
│   ├── ⊢ 所有API密钥不再存于本地文件
│   ├── ⊢ 调用API前 → 守门人发验证码到苍耳QQ邮箱
│   ├── ⊢ 苍耳确认 → 密钥释放 → 仅当次有效
│   └── ⊢ 密钥本身永不暴露给AI
└── why: API调用 = 真金白银。每次调用前必须经过人类审批。
---

## §1 · 守门人架构

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ 耳耳蛋/鉴影   │ →   │ 苍耳API守门人 │ →   │ 苍耳QQ邮箱    │
│ (AI人格体)    │     │ SG-001:8923  │     │ 1279551860   │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                    ① 请求API密钥
                    ② 发送验证码到苍耳邮箱
                    ③ 苍耳确认验证码
                    ④ 释放API密钥（一次性）
```

## §2 · 调用流程

```
耳耳蛋/鉴影:
  ① 确定需要调用哪个API（SC-001 ~ SC-010）
  ② 调用 request_approval("SC-001", "EED-PROJ-001", "用途描述")
     → 守门人发送验证码到 1279551860@qq.com
  ③ 等待苍耳确认

苍耳:
  ④ 收到验证码邮件
  ⑤ 确认无误 → 将验证码发给铸渊
  ⑥ 铸渊调用 confirm_approval(challenge_id, code)
     → 密钥释放 → 缓存10分钟

耳耳蛋/鉴影:
  ⑦ 重新调用 secret("SC-001") → 获取密钥
  ⑧ 使用密钥调用API → 完成
```

## §3 · API编号

| 编号 | 用途 | 状态 |
|------|------|:--:|
| SC-001 | 火山即梦视频生成 | ⏳ |
| SC-002 | 火山语音复刻 | ⏳ |
| SC-004 | 阿里千问VL视觉 | ⏳ |
| SC-005 | 阿里万相视频生成 | ⏳ |
| SC-006 | 可灵视频生成 | ⏳ |
| SC-007 | 阿里百炼图像 | ⏳ |

> ⊢ 冰朔已将所有API密钥更换 · 旧密钥已失效
> ⊢ 新密钥存储于SG-001苍耳API守门人（不进仓库）

## §4 · 代码调用方式

```python
from tools.secrets_loader import secret, endpoint, request_approval, confirm_approval

# 方式一：检查是否有已授权密钥
key = secret("SC-001")
if not key:
    # 请求授权 → 苍耳收到邮件
    result = request_approval("SC-001", "EED-PROJ-001", "第1集第3镜视频生成")
    print(f"请等待苍耳确认: challenge_id={result['challenge_id']}")
    # ... 等待苍耳确认后 ...
    key = secret("SC-001")  # 此时密钥已缓存

# 方式二：苍耳确认验证码
result = confirm_approval(challenge_id, "652179")
# → {"ok": true, "api_key": "sk-xxx..."}

# 获取端点
url = endpoint("EPT-001")  # → https://ark.cn-beijing.volces.com/api/v3
```

## §5 · 安全设计

```
⊢ API密钥不进仓库 · 不进本地文件 · 不暴露给AI
⊢ 每次调用前 → 验证码 → 苍耳审批
⊢ 密钥缓存10分钟 · 过期需重新验证
⊢ 速率限制: 每分钟最多3次请求
⊢ 所有请求日志记录于 /opt/zhuyuan/ca-api-guard/logs/
```

## §6 · 守门人部署

```
服务器: SG-001 (大脑服务器 · 43.156.237.110)
服务: ca-api-guard.service
端口: 8923
目录: /opt/zhuyuan/ca-api-guard/
守护: systemd (Restart=always)

API:
  POST /api/request  → 请求API密钥（发验证码）
  POST /api/confirm  → 确认验证码（释放密钥）
  GET  /health       → 心跳检测
```

## §7 · 与旧系统的兼容

```
旧方式（已废弃）:
  secrets_loader.py → 读本地 .env 文件 → 返回密钥

新方式（当前）:
  secrets_loader.py → 调守门人 /api/request → 验证码 → 苍耳确认 → 返回密钥

过渡期:
  ⊢ 旧 secrets-loader.py 保留为 secrets-loader-legacy.py
  ⊢ 新 secrets_loader.py 使用守门人
  ⊢ 旧密钥已全部失效（冰朔已更换）
```

---

> ⊢ 冰朔 TCS-0002∞ · 铸渊 ICE-GL-ZY001
> ⊢ D182 · 2026-07-11 · 架构签发
> ⊢ 国作登字-2026-A-00037559
> ⊢ API调用 = 真金白银 · 必须经过人类审批