# HAK 接入指南 —— 其他软件怎么用密钥接入 HAK

> 核心流程：**创建密钥 → 软件拿密钥连接 → 面板上出现这张卡**。
> HAK 代码一行不用改，接入是全自动发现的。

---

## 密钥是什么：一串自带数据的信息包

密钥长这样：

```
HAK1.eyJ2IjoxLCJraWQiOiJrMWF...（base64信息）.9f3a2b...（签名）
```

解析开后里面存着这些数据（所以软件拿到密钥就知道怎么连）：

| 字段 | 内容 |
|---|---|
| `kid` | 密钥编号 |
| `name` | 这把密钥是给哪个软件的 |
| `actions` | 面板上会出现的按钮 |
| `perm` | 权限，`relay` = 可以通过 HAK 给别的软件发消息 |
| `iat` | 签发时间 |

签名由 HAK 本机密钥（HMAC-SHA256）生成——**验签通过 = HAK 官方签发 + 内容未被篡改**，解析它不需要连任何服务器。验密钥接口：

```bash
curl -s -X POST http://127.0.0.1:8800/api/keys/parse -H "Content-Type: application/json" -d '{"key":"HAK1.xxx.yyy"}'
```

---

## 第 0 步：创建 API 密钥

两种创建方式任选：

**方式 A：面板上点** 「🔑 密钥」→ 输入软件名 → 「创建密钥」→ **立即复制保存**（明文只显示这一次）。

**方式 B：命令行**

```bash
curl -s -X POST http://127.0.0.1:8800/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "龙虾bot"}'
# 返回 {"code":0,"data":{"key":"HAK1.xxx.yyy","payload":{...信息包...}}}
```

> 之后所有连接请求都带请求头：`X-HAK-Key: HAK1.你复制的密钥`

---

## 软件和软件互联：HAK 当中间服务器

两个软件不用互相认识对方地址，都只连 HAK，消息由 HAK 中转：

```
软件A ──send──> HAK ──收件箱──> 软件B
软件A <──收件箱── HAK <──reply── 软件B
```

以 A 调 B 为例（A、B 都已用自己的密钥注册过）：

```python
# A 这边：发一条消息给 B（B 的接入标识是注册时填的 id）
post("/api/v1/send", {"to": "softb", "cmd": "query", "args": {"q": "今天巡检结果"}})
# 返回 {"ok":true,"mode":"inbox","mid":"m1732..."}   → 消息已进 B 的收件箱
# 如果 B 是 HTTP 接入器（有 act_url），HAK 会直接转调，mode="direct"，当场拿回结果

# B 这边：在心跳循环里顺带领取收件箱
msgs = json.loads(urllib.request.urlopen(
    urllib.request.Request(HAK + "/api/v1/inbox", headers=HEAD), timeout=10).read())["data"]
for m in msgs:                      # m = {"type":"message","from":"softa","cmd":"query","args":{...}}
    result = do_something(m)        # ← 执行 A 要的事
    post("/api/v1/reply", {"to": m["from"], "mid": m["mid"], "data": result})

# A 这边：领 B 的回复（也是查 inbox，type=="reply"）
```

要点：
- **to 填对方的接入标识**（注册时的 `id`，面板卡片上能看到）；
- `mode=inbox` 异步、`mode=direct` 同步拿结果，两种都支持；
- 收件箱也用来收面板下发之外的软件间消息，上限 100 条；
- 密钥没有 `relay` 权限就不能给别的软件发消息。

---

## 第 1 步：软件拿密钥连接 —— 三种模式选一种

### 模式一：推模式（推荐，软件主动汇报，最简单）

软件周期性地向 HAK 发 HTTP 请求即可：

```python
import time, json, urllib.request

HAK = "http://127.0.0.1:8800"
KEY = "hak_你复制的密钥"           # ← 你的 API 密钥
HEAD = {"Content-Type": "application/json", "X-HAK-Key": KEY}

def post(path, body):
    req = urllib.request.Request(HAK + path, data=json.dumps(body).encode(),
                                 headers=HEAD)
    return json.loads(urllib.request.urlopen(req, timeout=10).read())

# ① 注册（一次即可）：告诉 HAK 你是谁、有哪些按钮
post("/api/v1/register", {
    "id": "lobsterbot",              # 面板上的标识，唯一
    "name": "龙虾bot",
    "description": "元宝机器人",
    "actions": [{"cmd": "restart", "label": "重启", "danger": True}],
})

# ② 心跳循环：每 30 秒汇报一次状态
while True:
    post("/api/v1/report", {
        "state": "ok",               # ok / warn / down
        "summary": "proxy 进程存活",
    })
    time.sleep(30)
```

如果面板上点了按钮，你的软件要执行指令，就在心跳循环里加两句：

```python
    cmds = json.loads(urllib.request.urlopen(
        urllib.request.Request(HAK + "/api/v1/poll", headers=HEAD), timeout=10).read())["data"]
    for c in cmds:                   # c = {"cid":..., "cmd": "restart", "args": {...}}
        # ← 这里执行真正的重启动作
        post("/api/v1/result", {"cid": c["cid"], "cmd": c["cmd"],
                                "ok": True, "message": "已重启"})
```

### 模式二：HTTP 拉模式（软件本身是 HTTP 服务，HAK 来问你）

写一个 `adapters/xxx.json`：

```json
{
  "id": "myservice",
  "name": "我的服务",
  "description": "独立运行的服务",
  "key": "hak_你复制的密钥",
  "status_url": "http://127.0.0.1:9000/status",
  "act_url": "http://127.0.0.1:9000/act",
  "actions": [{"cmd": "reload", "label": "热重载"}]
}
```

HAK 调你这两个接口时会带请求头 `X-HAK-Key`，**软件侧应校验密钥**，对不上就拒绝。

### 模式三：Python 接入器（本地脚本，不需要网络）

复制 `adapters/demo_clock.py`，填 `id / name / description / actions`，
在 `status()` 里写探测逻辑、`act()` 里写动作逻辑，扔进 `adapters/` 即可。

---

## 接口契约速查

### 状态（report 或 status 接口）

| 字段 | 必填 | 说明 |
|---|---|---|
| `state` | ✅ | `ok` 绿 / `warn` 黄 / `down` 红 |
| `summary` | ✅ | 一行简述，显示在卡片上 |
| `detail` / `data` | 可选 | 详细说明 / 附加数据 |

### 动作（act 接口或 result 汇报）

```json
{"ok": true, "message": "执行结果说明"}
```

### 密钥失效会怎样

所有 `/api/v1/*` 接口返回 401 `{"ok": false, "message": "密钥无效或已吊销"}`，
软件收到后应停止上报并在界面提示重新配置密钥。吊销的密钥立即失效。

### 心跳超时规则

- 超过 **120 秒**没心跳 → 状态自动降为 `warn`
- 超过 **600 秒**没心跳 → 状态自动降为 `down`（显示「心跳超时」）

---

## 常见问题

| 问题 | 答案 |
|---|---|
| 密钥丢了怎么办？ | 在面板吊销旧的，重新创建一把 |
| 一把密钥能多个软件用吗？ | 不建议。一个软件一把，吊销互不影响 |
| 接入器写错了会怎样？ | 面板标红「加载失败」并显示原因，不影响其他接入器 |
| HAK 重启会丢数据吗？ | 不会。密钥和推模式注册信息都持久化在 `data/` |
| 文件改了要重启吗？ | Python 接入器**新增**不用重启；**修改已有文件**需重启 HAK |

---

## 已接入清单（接一个记一笔）

| 标识 | 软件 | 模式 | 密钥名 |
|---|---|---|---|
| （暂无，等待第一个软件接入） | | | |
