Palm OpenAPI 服务端 Skill 使用指南

1. 产品概述

palm-openapi 是一个面向 Palm 开放平台服务端 API 的 AI Agent Skill。安装并完成租户环境配置后，你可以直接使用自然语言，让 AI 助手在你的租户中完成以下操作：

查询资源：查询用户、设备、场景、掌纹、核验记录等信息
管理资源：创建、修改或删除用户、设备、场景、核验规则等资源
管理掌纹：创建、绑定、注册、删除和查询掌纹，执行空中开掌检索与用户加验
使用扫码录掌能力：创建扫码录掌会话、通知扫码事件、绑定掌纹、查询扫码用户和会话状态
管理多个租户环境：在本地保存多个租户的连接信息，并在调用时指定需要操作的租户环境
查询接口说明：列出可用 API，并查看指定 Action 的必填参数、可选参数和使用说明

Skill 内置的 Python CLI 会自动处理签名、Token 获取、请求发送和结果解析。

2. 快速开始

首次使用需要依次完成以下操作：

下载并安装 Skill
确认 palm-openapi Skill 已生效
准备租户配置信息
配置租户环境
检查配置结果
完成第一次 API 调用

2.1 下载并安装 Skill

下载 palm-openapi.zip，然后解压：

unzip palm-openapi.zip

将解压后的整个 palm-openapi 文件夹放入 AI 助手的本地 Skills 目录。不同 AI 助手的 Skills 目录可能不同，请以对应产品的安装说明为准：

cp -R palm-openapi <AI_ASSISTANT_SKILLS_DIR>/

安装后的目录结构如下：

<AI_ASSISTANT_SKILLS_DIR>/
└── palm-openapi/
    ├── README.md                       # 用户安装与操作手册
    ├── SKILL.md                        # AI Agent 触发规则和工作流程
    ├── commands/
    │   └── palm-openapi.md             # 命令定义
    ├── references/
    │   └── api_doc.md                  # 完整 API 文档
    └── scripts/
        └── palm_openapi_cli.py         # Palm OpenAPI CLI 脚本

可以使用以下命令检查文件是否完整：

ls <AI_ASSISTANT_SKILLS_DIR>/palm-openapi

确认目录完整后，重新加载或重新打开 AI 助手，使其识别新安装的 Skill。

如果需要手动运行 CLI，请先进入 Skill 根目录并检查 Python 依赖：

cd <AI_ASSISTANT_SKILLS_DIR>/palm-openapi
python3 --version
python3 -c "import requests; print(requests.__version__)"

如果提示缺少 requests，可在当前 Python 环境中安装：

python3 -m pip install requests

2.2 确认 Skill 已生效

安装完成后，可以先询问 AI 助手：

请使用 palm-openapi Skill，告诉我你能帮我做什么？

也可以直接描述想要执行的操作：

帮我创建一个新用户。

帮我查询用户 user001 的信息。

帮我查询设备 device-001 的详情。

帮我列出所有可用的 Palm OpenAPI 接口。

如果尚未配置租户环境，AI 助手会先引导你准备并配置所需信息。

2.3 准备租户配置信息

2.3.1 需要你提供的信息

参数	说明	是否必填
租户环境名	由你自定义的本地配置名称，例如 `test`、`tenant-a` 或 `customer-prod`。仅用于区分不同租户环境，不会修改租户信息。不填写时默认使用 `test`	可选
APP_ID	租户的应用 ID。每个租户只有一个唯一的 `APP_ID`	必填
SECRET_ID	服务管理员凭证的密钥 ID。不同管理员生成的凭证可能不同	必填
SECRET_KEY	与 `SECRET_ID` 配套的密钥。不同管理员生成的凭证可能不同，请妥善保管	必填
HOST	当前客户系统的 Palm OpenAPI 服务域名，例如 `openapi.customer.example.com`。每套客户系统只有一个 `HOST`，不会随租户变化	必填

2.3.2 APP_ID、SECRET_ID 和 SECRET_KEY 在哪里获取？

在腾讯刷掌管理后台中依次进入：

系统管理 → 租户管理 → 租户详情 → 基本信息

在“基本信息”中查看对应租户的以下信息：

APP_ID：对应当前租户，每个租户只有一个唯一值
SECRET_ID：服务管理员凭证的密钥 ID
SECRET_KEY：与 SECRET_ID 配套的密钥

同一个租户可以由不同服务管理员生成不同凭证，因此不同管理员获取到的 SECRET_ID 和 SECRET_KEY 可能不同。调用时必须使用相互配套的一组 SECRET_ID 和 SECRET_KEY。

2.3.3 HOST 在哪里获取？

其他管理员：请联系超级管理员或运维人员获取当前客户系统的 Open Domain。
超级管理员：在腾讯刷掌管理后台中依次进入：

系统管理 → 系统设置 → 服务端点 → Open Domain

Open Domain 对应需要配置的 HOST。每套客户系统只有一个域名，不会随租户变化。

2.4 配置租户环境

2.4.1 让 AI 助手完成配置

在受信任的本地 AI 会话中发送以下信息，将示例值替换为你的真实配置：

请使用 palm-openapi Skill 配置租户环境：
租户环境名：tenant-a
APP_ID：你的租户应用 ID
SECRET_ID：你的服务管理员密钥 ID
SECRET_KEY：与 SECRET_ID 配套的密钥
HOST：openapi.customer.example.com

AI 助手会调用内置 CLI 保存并验证租户环境。对应的 CLI 命令如下：

python3 scripts/palm_openapi_cli.py \
  --save-env tenant-a \
  --app-id <APP_ID> \
  --secret-id "<SECRET_ID>" \
  --secret-key "<SECRET_KEY>" \
  --host <HOST>

--save-env 后面的值就是租户环境名。配置会保存到本地 ~/.palm_openapi.json，文件权限设置为 600，仅当前系统用户可读写。

~/.palm_openapi.json 中的凭证是本地明文配置，并非加密存储。请仅在受信任的设备上使用，不要上传、分享或提交到代码仓库。

2.4.2 在本地终端交互式配置

如果不希望把凭证直接写在命令参数中，可以在本地终端运行：

python3 scripts/palm_openapi_cli.py --setup-env

根据提示依次填写租户环境名、HOST、APP_ID、SECRET_ID 和 SECRET_KEY。该方式依赖终端交互，适合用户手动操作，不适合由 AI Agent 自动执行。

2.5 检查租户环境

配置完成后，运行以下命令查看已配置的租户环境：

python3 scripts/palm_openapi_cli.py --list-envs

确认输出中的租户环境名、HOST、APP_ID 和凭证来源符合预期。脚本不会直接显示完整的 SECRET_KEY。

也可以直接让 AI 助手检查：

请使用 palm-openapi Skill，列出我已经配置的租户环境。

2.6 完成第一次 API 调用

建议第一次先执行只读查询，确认租户环境和凭证可以正常使用。例如：

请使用租户环境 tenant-a，查询用户列表，返回前 10 条。

对应的 CLI 命令如下：

python3 scripts/palm_openapi_cli.py DescribeUserList \
  '{"Offset": 0, "Limit": 10}' \
  --env tenant-a

如果接口正常返回数据或空列表，说明 Skill、租户环境和凭证已配置成功。如果返回认证或连接错误，请依次检查：

APP_ID 是否属于当前租户
SECRET_ID 和 SECRET_KEY 是否为相互配套的一组凭证
HOST 是否为当前客户系统的 Open Domain
当前设备是否可以访问该服务域名
系统时间是否准确

3. 自然语言使用

完成首次配置后，直接用自然语言说明要执行的操作和相关参数即可。例如：

你能帮我做什么？

帮我查询用户 user001 的信息。

帮我创建一个新用户，用户 ID 是 test001，用户名是测试用户，手机号是 (+86)13800138000。

帮我查询设备 device-001 的详情。

CreateUser 接口有哪些必填参数和可选参数？

帮我列出所有可用的 Palm OpenAPI 接口。

默认使用 test 租户环境。只有配置了多个租户环境或需要切换租户时，才需要明确说明：

请使用 tenant-a 租户环境，查询用户 user001 的信息。

AI 助手会自动：

将自然语言需求匹配到对应的 API Action
查询接口所需的必填参数和可选参数
在缺少必要信息时向你询问
使用当前租户环境获取 Token 并完成签名
调用 API，并解析返回结果或错误信息

涉及创建、修改、删除、绑定等会改变租户数据的操作时，请在执行前确认租户环境和参数，避免操作错误的租户。

4. CLI 使用

你也可以直接使用 Skill 内置的 Python CLI。

4.1 基本调用

# 使用默认租户环境 test
python3 scripts/palm_openapi_cli.py <Action> '<JSON 参数>'

# 使用指定租户环境
python3 scripts/palm_openapi_cli.py <Action> '<JSON 参数>' --env <租户环境名>

4.2 调用示例

# 查询用户
python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --env tenant-a

# 创建用户
python3 scripts/palm_openapi_cli.py CreateUser \
  '{"UserId": "test001", "UserName": "测试用户", "PhoneNo": "(+86)13800138000"}' \
  --env tenant-a

# 查询设备
python3 scripts/palm_openapi_cli.py DescribeDevice \
  '{"DeviceSn": "device-001"}' \
  --env tenant-a

4.3 常用辅助命令

# 列出 CLI 支持主动调用的 Action
python3 scripts/palm_openapi_cli.py --list-actions

# 查看指定 Action 的参数说明
python3 scripts/palm_openapi_cli.py --help-action <Action>

# 列出已配置的租户环境
python3 scripts/palm_openapi_cli.py --list-envs

# 交互式配置租户环境
python3 scripts/palm_openapi_cli.py --setup-env

# 非交互式保存租户环境
python3 scripts/palm_openapi_cli.py \
  --save-env <租户环境名> \
  --app-id <APP_ID> \
  --secret-id "<SECRET_ID>" \
  --secret-key "<SECRET_KEY>" \
  --host <HOST>

# 查看 CLI 完整帮助
python3 scripts/palm_openapi_cli.py --help

4.4 切换租户环境

每次调用时通过 --env 指定租户环境名：

python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --env tenant-a

python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --env tenant-b

租户环境名只是本地配置标识。切换 --env 不会修改任何租户信息，只会决定本次调用使用哪一组 APP_ID、SECRET_ID、SECRET_KEY 和 HOST。

4.5 临时指定租户连接信息

如果不需要保存配置，可以在单次调用中传入完整信息：

python3 scripts/palm_openapi_cli.py DescribeUser \
  '{"UserId": "user001"}' \
  --host openapi.customer.example.com \
  --app-id <APP_ID> \
  --secret-id "<SECRET_ID>" \
  --secret-key "<SECRET_KEY>"

命令行参数可能被终端历史或本机进程列表记录。请只在受信任的本地设备中使用，不要将包含真实凭证的命令粘贴到工单、文档、群聊或公开日志中。

5. 租户环境配置

5.1 配置保存位置

默认配置文件：

~/.palm_openapi.json

脚本会将文件权限设置为 600。也可以通过以下方式指定其他配置文件：

# 命令行指定配置文件
python3 scripts/palm_openapi_cli.py \
  --config /path/to/palm_openapi.json \
  DescribeUser '{"UserId": "user001"}' \
  --env tenant-a

# 使用环境变量指定配置文件
export PALM_CONFIG_FILE=/path/to/palm_openapi.json

5.2 配置读取优先级

租户环境配置按以下优先级读取，高优先级会覆盖低优先级：

命令行参数：--secret-id、--secret-key、--app-id、--host
环境变量：PALM_{租户环境名}_{KEY}
配置文件：--config、PALM_CONFIG_FILE 或 ~/.palm_openapi.json

例如，租户环境名为 tenant-a 时，环境变量名称中的连字符需要按当前终端支持的变量命名方式调整。建议租户环境名使用字母、数字和下划线，例如 tenant_a：

export PALM_TENANT_A_APP_ID="<APP_ID>"
export PALM_TENANT_A_SECRET_ID="<SECRET_ID>"
export PALM_TENANT_A_SECRET_KEY="<SECRET_KEY>"
export PALM_TENANT_A_HOST="openapi.customer.example.com"

python3 scripts/palm_openapi_cli.py DescribeUserList \
  '{"Offset": 0, "Limit": 10}' \
  --env tenant_a

6. 图片接口

涉及掌纹图片的接口必须通过文件路径传入图片，由脚本读取并完成 base64 编码。不要手动读取图片，也不要把 base64 图片数据直接写入 JSON 参数。

# 创建掌纹
python3 scripts/palm_openapi_cli.py CreatePalm \
  '{"PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --ir-image ./ir.jpg \
  --env tenant-a

# 注册掌纹
python3 scripts/palm_openapi_cli.py RegisterPalm \
  '{"UserId": "user001", "PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --ir-image ./ir.jpg \
  --env tenant-a

# 空中开掌检索
python3 scripts/palm_openapi_cli.py SearchMobilePalm \
  '{"PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --env tenant-a

如需传入图片三点数据：

python3 scripts/palm_openapi_cli.py CreatePalm \
  '{"PalmDirection": 1}' \
  --rgb-image ./rgb.jpg \
  --rgb-three-points "365.29,193.33,285.36,196.08,212.50,241.93" \
  --ir-image ./ir.jpg \
  --ir-three-points ./threepoints.txt \
  --env tenant-a

7. 支持的 API 能力

模块	能力
鉴权管理	自动获取访问凭证、查询授权信息
掌纹管理	创建、绑定、注册、删除和查询掌纹，空中开掌检索、用户加验、同步掌纹特征、查询产品版本
用户管理	创建、修改、删除和查询用户，查询用户列表
用户标签	创建、修改、删除和查询用户标签，查询标签列表和标签树
用户手掌	删除和查询用户手掌信息，查询用户通行范围及摘要
设备管理	创建、修改、删除和查询设备，查询设备列表
场景管理	创建、修改、删除和查询场景及场景组
核验记录	创建和查询核验记录
核验规则	创建、修改、删除和查询核验规则
扫码录掌	创建和查询扫码录掌会话、通知扫码事件、绑定掌纹、查询扫码用户
PalmMa 登录	发送短信验证码、使用短信验证码登录

功能持续更新中，具体功能以最新版本的 Skill 为准。安装后，可以直接使用自然语言询问 AI 助手：

这个 Skill 支持哪些功能？

掌纹管理支持哪些操作？

也可以通过 CLI 查看完整 Action 列表：

python3 scripts/palm_openapi_cli.py --list-actions

查看指定接口的参数：

python3 scripts/palm_openapi_cli.py --help-action <Action>

8. 注意事项

确认租户环境：执行创建、修改、删除或绑定操作前，必须确认 --env 指向正确的租户环境。
保护凭证：不要在公开聊天、截图、日志、文档或代码仓库中暴露真实的 SECRET_ID、SECRET_KEY 或 AccessToken。
HOST 必须准确：普通管理员应向超级管理员或运维人员获取；超级管理员应从“系统管理 → 系统设置 → 服务端点 → Open Domain”查看。
不要手动获取 Token：脚本会自动调用 CreateAccessToken，无需手动计算 SecretKeyHash 或维护 Token。
ModifyUser 是全量更新：未传入的可选字段可能被清空，调用前应先查询并确认需要保留的字段。
图片使用文件路径：CreatePalm、RegisterPalm、SearchMobilePalm 等图片接口应使用 --rgb-image 和 --ir-image。
推送和回调接口不能主动拉取：DescribeVerificationRecord 和 CheckAccessPermission 由平台主动调用。
不要随意关闭 TLS 校验：正式租户环境应使用可信服务域名和有效证书。

1. 产品概述​

2. 快速开始​

2.1 下载并安装 Skill​

2.2 确认 Skill 已生效​

2.3 准备租户配置信息​

2.3.1 需要你提供的信息​

2.3.2 APP_ID、SECRET_ID 和 SECRET_KEY 在哪里获取？​

2.3.3 HOST 在哪里获取？​

2.4 配置租户环境​

2.4.1 让 AI 助手完成配置​

2.4.2 在本地终端交互式配置​

2.5 检查租户环境​

2.6 完成第一次 API 调用​

3. 自然语言使用​

4. CLI 使用​

4.1 基本调用​

4.2 调用示例​

4.3 常用辅助命令​

4.4 切换租户环境​

4.5 临时指定租户连接信息​

5. 租户环境配置​

5.1 配置保存位置​

5.2 配置读取优先级​

6. 图片接口​

7. 支持的 API 能力​

8. 注意事项​