@zax360/openapi-skills 1.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "zhianxin-openapi",
+  "version": "0.1.0",
+  "description": "面向 AI Agent 的职安心开放能力说明：HTTP 签名校验、线索与岗位查询等 Skills（每能力一份 SKILL.md）。",
+  "keywords": ["zhianxin", "openapi", "职安心", "leads", "signing"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "职安心开放平台",
+    "shortDescription": "开放 API 签约与调用的 Agent Skills",
+    "longDescription": "为本仓库开放网关与 /openapi 业务接口提供可复用的 SKILL.md。Agent 在取得商户授权的 AccessKey / SecretKey 后，按文档生成 Cw-Signature 并调用 HTTP 接口。详细 HTTP 契约与模型参见 Apifox。",
+    "developerName": "职安心",
+    "category": "Developer Tools",
+    "capabilities": ["Interactive", "Write"],
+    "defaultPrompt": ["根据职安心开放平台文档代用户构造签名并调用 API（密钥由用户配置，勿写入仓库）"]
+  }
+}

package/bin/install.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * 将本包目录作为 Skill 源安装到各 Agent（封装 npx skills add … -y -g）
+ */
+const { execFileSync } = require('child_process')
+const path = require('path')
+
+const pkgRoot = path.resolve(__dirname, '..')
+const passThrough = process.argv.slice(2)
+const args = ['skills', 'add', pkgRoot, '-y', '-g', ...passThrough]
+
+try {
+  execFileSync('npx', args, { stdio: 'inherit', env: process.env })
+} catch {
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@zax360/openapi-skills",
+  "version": "1.0.0",
+  "description": "职安心开放平台 Agent Skills（签名、只读查询、线索 ingest），供 npx skills / Cursor / Codex 等加载",
+  "license": "MIT",
+  "keywords": [
+    "zhianxin",
+    "zax360",
+    "openapi",
+    "skills",
+    "职安心",
+    "cursor",
+    "codex"
+  ],
+  "bin": {
+    "zax360-openapi-skills": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    ".codex-plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/zhianxin-openapi-leads/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: zhianxin-openapi-leads
+version: 1.0.0
+description: "职安心开放平台线索写入与查询：POST /v1/leads/ingest、GET /v1/leads/staging/:id。当用户要通过 Agent 提交报名线索或查询暂存状态时使用。"
+metadata:
+  requires:
+    bins: ["curl", "openssl"]
+---
+
+# 线索 API（Agent）
+
+> **前置条件：** 先阅读 [`../zhianxin-openapi-shared/SKILL.md`](../zhianxin-openapi-shared/SKILL.md)（签名与环境变量）。
+
+## 写入暂存 · POST /v1/leads/ingest
+
+Body 为 JSON，至少包含业务约定的 `content`；可选 `campaign` 等字段以实际上线为准。
+
+```bash
+# 设置 BASE、ACCESS_KEY、SECRET_KEY 后：
+TS=$(date +%s)
+BODY='{"content":"用户意向描述","campaign":"渠道活动名"}'
+SIGN_STRING="${ACCESS_KEY}"$'\n'"${SECRET_KEY}"$'\n'"${TS}"$'\n'"${BODY}"
+SIG=$(printf '%s' "$SIGN_STRING" | openssl dgst -sha1 -hmac "$SECRET_KEY" -binary | openssl base64)
+curl -sS -X POST "$BASE/v1/leads/ingest" \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -H "Cw-Access-Key: $ACCESS_KEY" \
+  -H "Cw-Timestamp: $TS" \
+  -H "Cw-Signature: $SIG" \
+  --data-binary "$BODY"
+```
+
+成功时响应体通常包含 `code`、`msg`、记录 `id` 等（与历史契约一致）。
+
+## 查询暂存 · GET /v1/leads/staging/:id
+
+将 `:id` 换为上一步返回的 id；签名为 **GET 三行串**（无 body）。
+
+```bash
+TS=$(date +%s)
+SIGN_STRING="${ACCESS_KEY}"$'\n'"${SECRET_KEY}"$'\n'"${TS}"
+SIG=$(printf '%s' "$SIGN_STRING" | openssl dgst -sha1 -hmac "$SECRET_KEY" -binary | openssl base64)
+curl -sS "$BASE/v1/leads/staging/线索记录ID" \
+  -H "Cw-Access-Key: $ACCESS_KEY" \
+  -H "Cw-Timestamp: $TS" \
+  -H "Cw-Signature: $SIG"
+```
+
+## 原则
+
+- 写入前向用户确认内容与合规要求；避免重复提交同一线索 unless 用户明确要求。
+- 密钥仅通过环境变量或用户本地配置注入，不出现在仓库与截图中。

package/skills/zhianxin-openapi-readonly/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: zhianxin-openapi-readonly
+version: 1.1.0
+description: "职安心开放平台只读：CLI zax360 openapi（company-list、company-find-by-name、job-info、job-types、info、dict-degree）与 GET /v1/jobs、/v1/jobs/:id、/v1/companies、/v1/account/*、/v1/catalog/services。用户要拉企业列表、岗位详情、目录、用量或让 Agent 用 openapi 子命令时触发。"
+metadata:
+  requires:
+    bins: ["curl", "openssl"]
+---
+
+# 只读查询（v1，Agent）
+
+> **前置条件：** [`../zhianxin-openapi-shared/SKILL.md`](../zhianxin-openapi-shared/SKILL.md)。
+
+## CLI `zax360 openapi` 与 HTTP 一一对照
+
+Base URL = Rust 开放网关（与 `auth login` 一致）。签名头：`Cw-Access-Key`、`Cw-Timestamp`、`Cw-Signature`。
+
+| 能力说明 | CLI | 实际请求 |
+|----------|-----|----------|
+| **企业列表** | `zax360 openapi company-list` | `GET /v1/companies?page=1&page_size=100` |
+| **企业按名称**（全字匹配，无单独接口） | `zax360 openapi company-find-by-name --name "<名称>"` | 循环 `GET /v1/companies?page=1…30&page_size=100`，在 `data.list` 中找 `company_name === 参数` |
+| **岗位详情** | `zax360 openapi job-info --id "<岗位ID>"` | `GET /v1/jobs/{id}` |
+| **快照：企业 + 在招岗位 + 能力目录** | `zax360 openapi info` | **并行** `GET /v1/companies?page=1&page_size=50`、`GET /v1/jobs?page=1&page_size=20`、`GET /v1/catalog/services` |
+| **工种标签**（首屏去重，非字典表） | `zax360 openapi job-types` | `GET /v1/jobs?page=1&page_size=100`，对 `job_type` 去重输出 |
+| **学历字典** | `zax360 openapi dict-degree` | **不请求 Rust**；需 Java `GET /openapi/dict/degree` 或 Apifox |
+
+**汇总（非 openapi 子命令）**：`zax360 account info` 并行调用 `GET /v1/account/quota`、`/v1/account/usage`、`/v1/catalog/services`、`/v1/companies?page=1&page_size=10`、`/v1/jobs?page=1&page_size=10`。
+
+**任意路径**：`zax360 request get /v1/...`（path 以 `/` 开头）。
+
+---
+
+## REST 路径速查（自建客户端 / cURL）
+
+以下为 **GET**，签名字符串均为三行：`accessKey\nsecretKey\ntimestamp`。
+
+### 岗位列表
+
+```text
+GET $BASE/v1/jobs?page=1&page_size=20
+```
+
+### 岗位详情
+
+```text
+GET $BASE/v1/jobs/{id}
+```
+
+### 企业列表 / 详情
+
+```text
+GET $BASE/v1/companies?page=1&page_size=20
+GET $BASE/v1/companies/{id}
+```
+
+### 用量与配额
+
+```text
+GET $BASE/v1/account/usage
+GET $BASE/v1/account/quota
+```
+
+### 能力目录
+
+```text
+GET $BASE/v1/catalog/services
+```
+
+## cURL 示例（岗位列表）
+
+```bash
+TS=$(date +%s)
+SIGN_STRING="${ACCESS_KEY}"$'\n'"${SECRET_KEY}"$'\n'"${TS}"
+SIG=$(printf '%s' "$SIGN_STRING" | openssl dgst -sha1 -hmac "$SECRET_KEY" -binary | openssl base64)
+curl -sS "$BASE/v1/jobs?page=1&page_size=20" \
+  -H "Cw-Access-Key: $ACCESS_KEY" \
+  -H "Cw-Timestamp: $TS" \
+  -H "Cw-Signature: $SIG"
+```
+
+查询参数 **必须** 参与 URL；若网关要求固定查询顺序，按实际上线文档拼接（与 `curl` 发出的完整 path+query 一致即可）。
+
+## Apifox 业务接口
+
+企业维护、岗位发布、字典等 **`/openapi/...`** 路径的请求体与示例见 [Apifox](https://alwrbsqeg9.apifox.cn/)，签名规则与本 Skill 相同（POST 时追加 body）。

package/skills/zhianxin-openapi-shared/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: zhianxin-openapi-shared
+version: 1.0.0
+description: "职安心开放平台通用约定：签名字符串、cURL 模板、环境与安全。当用户要用 Agent 调用职安心开放 HTTP API（任意路径）时应先读本 Skill。"
+metadata:
+  requires:
+    bins: ["curl", "openssl"]
+---
+
+# 职安心开放平台 · 共享约定（Agent）
+
+> 每个能力对应一份 `SKILL.md`，由 frontmatter 的 `description` 供 Agent 触发匹配；具体 HTTP 路径与 body 模型以 **Apifox** 及仓库根目录 **README /docs** 为准。
+
+## 前置条件
+
+1. **Base URL**：运营提供的网关根地址（可与开放控制台同源，也可能单独域名）。下文记为 `BASE`（无尾部 `/`）。
+2. **密钥**：`ACCESS_KEY`、`SECRET_KEY` 由商户在 **开放控制台 → API 密钥** 获取。**禁止**写入仓库、日志或提交到模型训练可见的明文库；由用户在环境变量或密钥管理中配置。
+3. **时间戳**：`TIMESTAMP` 为 Unix 秒（字符串）。
+
+## 签名（与控制台文档一致）
+
+请求头固定包含：
+
+- `Cw-Access-Key`: ACCESS_KEY  
+- `Cw-Timestamp`: TIMESTAMP  
+- `Cw-Signature`: Base64( HMAC-SHA1(SECRET_KEY, signString) )
+
+**签名字符串 `signString`：**
+
+- **GET**（或无 body 的 DELETE 等）：  
+  `ACCESS_KEY + "\n" + SECRET_KEY + "\n" + TIMESTAMP`
+- **POST / PUT**（有 body）：  
+  在上述末尾追加 `+ "\n" + rawBody`，`rawBody` 为实际发送的 **UTF-8 原始字节**对应的字符串（与 `curl --data-binary` 一致）。
+
+## 用 OpenSSL 计算签名（便于 Agent 单步脚本）
+
+```bash
+# signString 写入文件 sign.txt，SECRET_KEY 作 HMAC key
+printf '%s' "$SIGN_STRING" > /tmp/zx-sign.txt
+openssl dgst -sha1 -hmac "$SECRET_KEY" -binary /tmp/zx-sign.txt | openssl base64
+# 输出即为 Cw-Signature（无换行）
+```
+
+## cURL 模板 · GET
+
+```bash
+TS=$(date +%s)
+SIGN_STRING="${ACCESS_KEY}"$'\n'"${SECRET_KEY}"$'\n'"${TS}"
+SIG=$(printf '%s' "$SIGN_STRING" | openssl dgst -sha1 -hmac "$SECRET_KEY" -binary | openssl base64)
+curl -sS "$BASE/v1/account/usage" \
+  -H "Cw-Access-Key: $ACCESS_KEY" \
+  -H "Cw-Timestamp: $TS" \
+  -H "Cw-Signature: $SIG"
+```
+
+## cURL 模板 · POST（JSON）
+
+```bash
+TS=$(date +%s)
+BODY='{"content":"示例线索","campaign":"活动A"}'
+SIGN_STRING="${ACCESS_KEY}"$'\n'"${SECRET_KEY}"$'\n'"${TS}"$'\n'"${BODY}"
+SIG=$(printf '%s' "$SIGN_STRING" | openssl dgst -sha1 -hmac "$SECRET_KEY" -binary | openssl base64)
+curl -sS -X POST "$BASE/v1/leads/ingest" \
+  -H "Content-Type: application/json; charset=utf-8" \
+  -H "Cw-Access-Key: $ACCESS_KEY" \
+  -H "Cw-Timestamp: $TS" \
+  -H "Cw-Signature: $SIG" \
+  --data-binary "$BODY"
+```
+
+## 路由前缀
+
+| 前缀 | 说明 |
+|------|------|
+| `/openapi` | 企业、岗位、字典等，见 Apifox |
+| `/v1` | 扩展能力（线索、只读岗位/企业、用量等），README 表格 |
+
+两套接口 **共用同一套** AK/SK 与签名规则。
+
+## 官方 CLI（Node 18+）
+
+npm 包 **`@zax360/openapi-cli`**：例如 `npx @zax360/openapi-cli lead push --base-url ... --access-key ... --secret-key ... --content "..."`。详见 README「命令行」一节。
+
+## 进一步阅读
+
+- 人类可读完整说明：开放控制台 **接口文档**，或仓库根目录 `README.md`。
+- 在线调试与模型定义：[职安心开放平台 Apifox](https://alwrbsqeg9.apifox.cn/)。