hrmax-cli

HRmax 开放平台命令行工具。把开放平台的签名、加密、异步轮询、错误码全部封装掉， 让本地或客户的 OpenClaw agent 用一行命令完成"建面试 → 邀候选人 → 拉报告"。

• 服务地址：生产 https://open-api.hrmax.jp，QA https://open-api.qa.hrmax.jp
• 所有输出为中文 + JSON，便于人读和 Agent 解析
• 本地无公网回调地址，报告获取采用轮询（report watch）代替事件回调

1. 环境要求

• Node.js >= 18（自带 fetch / crypto，无需额外依赖）

2. 构建

npm install
npm run build

产物在 dist/。可执行入口：node dist/cli.js 或 npx hrmax-cli（本地 link 后）。

3. 配置凭证（HRmax 线下提供 5 个）

| 凭证 | 说明 | |-|-| | appKey | 客户唯一标识 | | appSecret | 签名密钥（HmacSHA256） | | privateKey | AES-256 密钥（base64 编码的 32 字节） | | uniqueCode | 企业唯一识别码 | | openId | HR 登录账号标识 |

两种配置方式（优先级：环境变量 > 配置文件）：

方式一：环境变量

export HRMAX_APP_KEY=...
export HRMAX_APP_SECRET=...
export HRMAX_PRIVATE_KEY=...
export HRMAX_UNIQUE_CODE=...
export HRMAX_OPEN_ID=...
export HRMAX_ENV=prod   # prod | qa，默认 prod

方式二：写入本地文件 ~/.hrmax/config.json（权限 600）

node dist/cli.js config set \
  --app-key ... --app-secret ... --private-key ... \
  --unique-code ... --open-id ... --env prod
node dist/cli.js config list   # 查看概览，不显示密钥明文

4. 安全提示

• 写操作（建面试、邀约）默认被拦截，需显式加 --yes 才执行；生产环境会创建真实面试、给真实候选人发邮件。
• 任何命令都可加 --dry-run 先预览将要发送的请求（含明文业务参数，不含密钥），不发起真实调用。
• 报告 PDF、人脸图片链接10 分钟过期，report get/watch 支持 --download-pdf 即时落盘。
• 报告含候选人个人信息/面部/评测结果，导出后生命周期由客户自行管理。

5. 命令参考

商品套餐

node dist/cli.js commodity list                  # 获取套餐/冰山/维度/题目（只读）

自定义题目

node dist/cli.js question add --memo "自己紹介してください" --yes
node dist/cli.js question list --cur-page 0 --page-size 20

创建面试（异步）

# 用推荐维度和题目，--wait 自动轮询直到拿到 interviewId
node dist/cli.js interview create \
  --commodity-id <商品ID> --job-name "上級プログラマー" \
  --job-category-code N000009 --wait --yes

# 自选维度/题目（不使用推荐）
node dist/cli.js interview create --commodity-id <ID> --job-name X \
  --job-category-code N000009 --no-use-recommend \
  --select-dimensions-json '[{"dimensionId":"..","weightRatio":"0.5","selectQuestionList":[{"questionId":".."}]}]' \
  --yes

node dist/cli.js interview create-status --task-id <taskId>
node dist/cli.js interview list --cur-page 0 --page-size 20

邀约

# 邮箱邀请（可重复 --candidate，最多 50 个）
node dist/cli.js invite candidate --interview-id <ID> \
  --begin 202606071400 --end 202606091500 \
  --candidate "name=山田,[email protected]" --yes

# 公开报名链接
node dist/cli.js invite public --interview-id <ID> \
  --begin 202606071400 --end 202606091500 --count 100 --yes

# 【开发中】唯一标识邀请（无邮箱场景，需先 invite public）
node dist/cli.js invite by-unique-id --interview-id <ID> --unique-id dym-0001 --yes

报告（本地无回调，用轮询）

# 单次查询
node dist/cli.js report get --interview-id <ID> --candidate-email [email protected] --download-pdf ./报告.pdf

# 轮询直到报告生成（interviewStatusCode=6），替代事件回调
node dist/cli.js report watch --interview-id <ID> --candidate-email [email protected] \
  --interval 30 --timeout 3600 --download-pdf ./报告.pdf

字典

node dist/cli.js dict job-category --search "ゲーム"   # 查 jobCategoryCode（level3_code）

事件回调解密（可选，本地验证用）

node dist/cli.js events decrypt --notify-contents '<ContentDto 的 JSON>'

6. 给 OpenClaw agent 的典型编排

因为客户电脑没有公网回调地址，标准流程是"建面试 → 邀约 → 轮询报告"：

# 1) 建面试并等到 interviewId
node dist/cli.js interview create --commodity-id C --job-name "岗位" \
  --job-category-code N000009 --wait --yes

# 2) 邀请候选人
node dist/cli.js invite candidate --interview-id I \
  --begin 202606071400 --end 202606091500 --candidate "name=X,[email protected]" --yes

# 3) 盯着报告，生成后自动下载 PDF（阻塞直到出结果）
node dist/cli.js report watch --interview-id I --candidate-email [email protected] --download-pdf ./x.pdf

Agent 直接读命令的 stdout JSON 即可拿到 interviewId / 作答链接 / 报告数据。

7. 拷贝到客户 OpenClaw 电脑

本工具无运行时第三方依赖（仅构建期需要 typescript）。两种方式：

1. 拷贝构建产物：把 dist/、package.json、dict/ 拷到客户机，客户机执行 node dist/cli.js ...。
2. 拷贝整个目录：拷贝仓库后在客户机 npm install && npm run build。

凭证不要打进包里，由客户机通过环境变量或 config set 配置。

8. 已知事项 / 待验证

• 候选人字段名：文档字段表用 candidateEmail，示例 JSON 用 email。本 CLI 按字段表发送 {name, candidateEmail}；若线上校验不通过，可用 --candidates-json 显式传参对齐。
• invite by-unique-id（API-007-01）平台侧标注开发中。
• privateKey 按官方 SDK 作为 base64 编码的 32 字节密钥处理；若 HRmax 实际下发格式不同，CLI 会尝试 utf8/hex 兜底并报错提示。
• 加签/加密逻辑已与官方 Java/Python SDK（reference-sdk/）逐项对拍一致，但真实调用需拿到生产凭证后最终确认。