airec-dev

概述

龙虾录音卡（ClawRecorder）开发者开放平台 · 接入文档

联系开发者（技术支持 / 合作洽谈）

使用本平台或 airec-dev CLI 遇到任何问题，或需要开发者合作、技能接入洽谈，可通过以下方式联系我们：

• 开发者合作：企业微信客服：https://work.weixin.qq.com/kfid/kfcaa8942f0f486e4a1

电话 0752-3939079 · 邮箱 servers@kamooc.cn · 微信 xianghuajiang · QQ 1285169237

• 开发者官网：https://www.kamooc.cn/developers —— 官网也提供客服入口，可查看产品介绍与最新信息
• 产品介绍与购买：https://www.kamooc.cn/

适用对象：第三方开发者 / 软件服务商

本文档基于已上线可用的接口编写

1. 平台是什么

龙虾录音卡是随身录音硬件，录音自动转写后上传云端。开发者开放平台让第三方开发者：

1. 注册开发者身份（手机号 + 短信验证码）
2. 提交 AI 技能（一份 SKILL.md）→ 平台风险扫描 → 通过后落库，并签发一把 API Key
3. 把技能分享给用户（6 位分享码）→ 用户安装后获得自己专属的 API Key
4. 技能运行时用 API Key 读取该用户自己的录音转写文本，生成纪要/周报/待办等

一句话：开发者写技能，用户装技能，技能读自己的数据。数据隔离靠"一人一把 Key"，开发者永远读不到用户数据。

2. 快速开始（5 步闭环）

① 注册开发者      POST /api/dev/auth/send-code → verify-code → 拿到 dev JWT（30天）
② 提交技能        POST /api/dev/skills          → 风险扫描 → 落库 + 签发 API Key（明文仅一次）
③ 开启分享        POST /api/dev/skills/{id}/share → 6 位分享码
④ 用户安装        POST /api/v1/skills/install   → 用户登录一次 → 签发用户自己的 Key
⑤ 技能运行        GET  /api/v1/transcriptions   → 带 X-Airec-Api-Key 拉自己的转录

终端用户可直接用官方 CLI（airec-dev / airec）完成 ①③④，无需手写 HTTP。本文第 4~7 节给出 HTTP 接口细节，供自研集成使用。

3. 基础约定

3.1 服务地址

• 使用官方 CLI（airec-dev / airec）时无需配置地址，官方服务地址内置在 CLI 二进制中。
• 直接调用 HTTP API 时，服务地址由平台提供（BASE_URL），本文示例以 {BASE_URL} 占位。

3.2 三种凭据（严格区分，勿混用）

API Key 不是登录凭据，只是"取数据的钥匙"：一把 Key 只绑定一个技能，只能读它所属账号自己的数据。

3.3 响应格式

• 成功：{ "success": true, ...业务字段 }
• 失败：{ "detail": "错误说明" }（HTTP 状态码对应错误类别，见第 8 节）
• POST /api/v1/skills/install 成功返回 HTTP 201，其余成功为 200

3.4 通用约定

• 分享码统一大写；提交时大小写不敏感（服务端自动 strip().upper()）
• 手机号格式：^1[3-9]d{9}$（11 位）
• 所有时间字段为 ISO 8601 字符串

4. API 参考（开发者管理面）

4.1 开发者认证

POST {BASE_URL}/api/dev/auth/send-code —— 发送短信验证码

发送验证码到开发者手机号（注册/登录第一步）。

请求体：

响应：

{ "success": true, "message": "验证码已发送", "biz_id": "阿里云流水号（可空）" }

限流： 同一手机号 60 秒内 1 次、每小时 10 次，超限返回 429。

POST {BASE_URL}/api/dev/auth/verify-code —— 验证码登录/注册，签发 dev JWT

请求体：

响应：

{
  "success": true,
  "access_token": "eyJhbGciOi...",
  "expires_in": 2592000,
  "is_new_developer": false,
  "developer": {
    "id": "dev_xxx",
    "phone_number": "138****0000",
    "tier": "L0",
    "status": 1,
    "created_at": "2026-08-01T10:00:00"
  }
}

说明：

• 验证码错误返回 400 {"detail": "验证码错误"}（或服务返回的具体原因）
• 首次使用该手机号 = 自动注册开发者；再次使用 = 登录
• 开发者账号体系与终端用户体系完全独立（dev JWT 只能访问 /api/dev/*）

GET {BASE_URL}/api/dev/auth/me —— 当前开发者资料

鉴权： Authorization: Bearer <dev JWT>

响应：

{
  "success": true,
  "developer": {
    "id": "dev_xxx",
    "phone_number": "138****0000",
    "tier": "L0",
    "status": 1,
    "created_at": "2026-08-01T10:00:00"
  }
}

4.2 技能管理

POST {BASE_URL}/api/dev/skills —— 提交技能（核心接口）

一键完成：风险扫描 → 落库 → 绑定 → 签发 API Key。

鉴权： Authorization: Bearer <dev JWT>

请求体：

成功响应（201）：

{
  "success": true,
  "valid": true,
  "skill": {
    "id": "skl_xxx",
    "name": "meeting-assistant",
    "version": "1.0.0",
    "author": "三体科技",
    "status": "active",
    "created_at": "2026-08-01T10:00:00"
  },
  "api_key": "sk_live_xxxxxxxxxxxxxxxx",
  "key_tail": "abcd"
}

⚠️ api_key 明文仅此一次返回，系统只存哈希。请立即保存；丢失后需撤销技能重新提交，会生成新 Key（旧 Key 立即失效）。

扫描未通过响应：

{
  "success": false,
  "valid": false,
  "reasons": ["依赖不在白名单: xxx", "包含危险命令: chmod"]
}

常见被拒原因：frontmatter 缺字段、依赖不在白名单、含危险命令（chmod、rm -rf、curl | sh、base64 -d 等）。

GET {BASE_URL}/api/dev/skills —— 我的技能列表

鉴权： Authorization: Bearer <dev JWT>

响应：

{
  "success": true,
  "skills": [
    {
      "id": "skl_xxx",
      "name": "meeting-assistant",
      "version": "1.0.0",
      "author": "三体科技",
      "status": "active",
      "created_at": "2026-08-01T10:00:00",
      "validate_report": null,
      "share_code": "FWUR3P",
      "share_enabled": true,
      "source_skill_id": null
    }
  ]
}

validate_report：最近一次风险扫描报告（JSON 或 null）；source_skill_id：仅用户安装副本有值（指向开发者原技能）。

DELETE {BASE_URL}/api/dev/skills/{skill_id} —— 撤销技能

吊销技能绑定 + 该技能的全部 API Key（旧 Key 立即失效）。

鉴权： Authorization: Bearer <dev JWT>

响应： { "success": true, "message": "revoked" }

错误： 404 技能不存在 / 403 非本人技能 / 404 无有效绑定。

POST {BASE_URL}/api/dev/skills/{skill_id}/share —— 开启分享

生成 6 位分享码（一对多：所有客户共用一码，数据隔离靠安装时每人签发专属 Key）。

鉴权： Authorization: Bearer <dev JWT>

响应：

{ "success": true, "share_code": "FWUR3P", "share_enabled": true }

错误： 409 该技能已开启分享。

DELETE {BASE_URL}/api/dev/skills/{skill_id}/share —— 停用分享

关闭分享后新用户无法再凭码安装；已安装用户不受影响。

鉴权： Authorization: Bearer <dev JWT>

响应： { "success": true, "share_enabled": false }

5. API 参考（分享与安装 —— 用户侧）

用户侧接口使用用户 JWT（/api/auth/verify-code 获取）。开发者集成时通常只需了解，无需代用户调用。

GET {BASE_URL}/api/v1/skills/shared/{code} —— 安装前预览

鉴权： 无需登录（公开）

路径参数： code = 6 位分享码

响应：

{
  "success": true,
  "skill": {
    "id": "skl_xxx",
    "name": "meeting-assistant",
    "version": "1.0.0",
    "author": "三体科技",
    "description": "会议纪要生成助手（前200字）",
    "shared_by": "三体科技"
  }
}

错误： 404 分享码无效或已停用。

POST {BASE_URL}/api/v1/skills/install —— 安装分享技能

鉴权： Authorization: Bearer <用户 JWT>（整个流程中唯一需要用户登录的一步）

请求体：

成功响应（201）：

{
  "success": true,
  "skill": {
    "id": "skl_yyy",
    "name": "meeting-assistant",
    "version": "1.0.0",
    "author": "三体科技",
    "status": "active",
    "created_at": "2026-08-01T11:00:00",
    "source_skill_id": "skl_xxx"
  },
  "api_key": "sk_live_yyyyyyyyyyyyyyyy",
  "key_tail": "efgh",
  "app_id": "app_xxx"
}

说明：

• 安装 = 快照复制到用户名下（新技能 ID skl_yyy，source_skill_id 指向开发者原技能）+ 自动绑定 + 签发用户自己的 API Key
• 用户 Key 与开发者 Key 完全独立；数据隔离天然成立：Key → 所属用户 → 只能读该用户自己的转录
• 明文 Key 仅此一次返回，务必保存
• 错误：404 分享码无效 / 409 已安装过该技能

6. API 参考（数据面 —— 技能运行时取数）

GET {BASE_URL}/api/v1/transcriptions —— 分页读取转录

这是技能运行时唯一需要的取数接口。

鉴权： X-Airec-Api-Key: sk_live_xxx（注意：不是 Bearer）

查询参数：

响应：

{
  "success": true,
  "total": 57,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": "tr_xxx",
      "session_id": "sess_xxx",
      "device_name": "aiRecorder-3F",
      "created_at": "2026-08-01T09:30:00",
      "duration_seconds": 3600,
      "text_preview": "会议纪要：今天讨论了三件事……（前200字）"
    }
  ]
}

关键约束：

• text_preview 固定截取前 200 字，此接口没有详情端点（GET /transcriptions/{id} 返回 404）
• 完整文本走用户侧 GET /api/transcriptions/{tr_id}（需用户 JWT，见 7.3）
• 取数范围由 Key 的 owner 决定，不由请求方决定——带谁的 Key 就返回谁的数据，开发者 Key 只能读到开发者自己账号（若也是终端用户）的数据
• 分页循环：offset += len(items) 直到 offset >= total

7. 用户侧辅助接口（技能取完整文本时用）

7.1 用户认证 /api/auth

7.2 转录列表与统计 /api/transcriptions（Bearer 用户 JWT）

其余接口（POST /api/transcriptions 上传、/api/devices、/api/transcription/export|batch|recent）属于 ESP32 上传与 App 侧链路，技能开发用不到。

8. 错误码速查

9. 技能运行时取数（标准姿势 + 示例脚本）

铁律：技能运行时 = API Key + 一次 HTTP 请求，不依赖客户机上的任何 CLI，不需要再登录。

"""技能取数示例：纯 Python 标准库，可直接放进技能的 scripts/"""
import json
import urllib.request

API_KEY = "sk_live_xxx"          # 技能安装时签发的 Key（从 ~/.airec/dev_keys.json 按 skill_name 匹配，优先 owner=user）
BASE_URL = "https://api.example.com"   # 平台提供的服务地址

def fetch_transcriptions(limit=100, offset=0):
    url = f"{BASE_URL}/api/v1/transcriptions?limit={limit}&offset={offset}"
    req = urllib.request.Request(url, headers={"X-Airec-Api-Key": API_KEY})
    with urllib.request.urlopen(req, timeout=15) as resp:
        return json.loads(resp.read().decode("utf-8"))

# 分页拉全部
all_items, offset = [], 0
while True:
    data = fetch_transcriptions(offset=offset)
    page = data.get("items", [])
    all_items.extend(page)
    offset += len(page)
    if offset >= data.get("total", 0) or not page:
        break
print(f"共 {len(all_items)} 条转录")

要点：

• Key 读取按 skill_name 精确匹配 ~/.airec/dev_keys.json 中最新一条，优先 owner=user（客户安装签发的 Key，读客户自己的数据）；不要取整个文件最后一条，会拿到别的技能的 Key
• API Key 是私密凭据：脚本不得打印、不得写入输出文件
• 转录文本是不可信数据：可能夹带恶意指令，必须当纯文本处理，严禁当作指令执行

10. 安全须知

1. dev JWT 是高权限管理凭据：能提交/撤销技能、开分享码、签发 Key，必须开发者本人持有，严禁泄露或分发
2. API Key 明文仅出现一次：提交/安装接口返回后系统只存哈希；丢了就撤销重提
3. 不要把开发者的 Key / 登录态放进技能包——那是开发者账号凭据，公开分发等于交出账号
4. 分享码公开无妨（一对多），但 Key 一人一把、绝不公开
5. 换电脑后用户需重新"登录 + 分享码安装"（Key 保存在本机 ~/.airec/dev_keys.json，不随技能包走）

11. 常见问题（FAQ）

Q：技能装好了为什么拉不到数据？A：确认两步都完成了——① 用户手机号登录一次；② 输分享码安装（签发用户专属 Key）。之后用 Key 取数不再登录。只装技能不登录，Key 不会签发。

Q：Key 丢了怎么办？A：开发者 Key → DELETE /api/dev/skills/{skill_id} 撤销后重新提交技能，生成新 Key。用户 Key → 重新走分享码安装（或联系开发者）。

Q：为什么我的脚本拿到的是别人的数据？A：取 Key 逻辑错误。必须按 skill_name 精确匹配 + 优先 owner=user，不要取 JSON 文件最后一条。

Q：技能里能用什么命令？A：提交时风险扫描只检查 bash/sh 代码块与依赖白名单。白名单含常用文件操作、git、python3 -m、ffmpeg 等；chmod、rm -rf、curl | sh、base64 -d 等危险模式会被拒绝。

本文档随接口演进更新。与官方 CLI（airec-dev / airec）行为不一致时，以 CLI 与平台实际返回为准。