@zax360/openapi-skills 1.0.1 → 1.0.2

package/.codex-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "zhianxin-openapi",
-  "version": "0.1.0",
-  "description": "面向 AI Agent 的职安心开放能力说明：HTTP 签名校验、线索与岗位查询等 Skills（每能力一份 SKILL.md）。",
-  "keywords": ["zhianxin", "openapi", "职安心", "leads", "signing"],
+  "version": "0.1.1",
+  "description": "面向 AI Agent 的职安心开放能力说明：HTTP 签名校验、线索、岗位查询、同步、合作方暂存、事件订阅等 Skills（每能力一份 SKILL.md）。",
+  "keywords": ["zhianxin", "openapi", "职安心", "leads", "signing", "sync", "webhook"],
   "skills": "./skills/",
   "interface": {
     "displayName": "职安心开放平台",
-    "shortDescription": "开放 API 签约与调用的 Agent Skills",
-    "longDescription": "为本仓库开放网关与 /openapi 业务接口提供可复用的 SKILL.md。Agent 在取得商户授权的 AccessKey / SecretKey 后，按文档生成 Cw-Signature 并调用 HTTP 接口。详细 HTTP 契约与模型参见 Apifox。",
+    "shortDescription": "开放 API 签约、查询、写入与事件调用的 Agent Skills",
+    "longDescription": "为本仓库开放网关与 /openapi 业务接口提供可复用的 SKILL.md。Agent 在取得商户授权的 AccessKey / SecretKey 后，按文档生成 Cw-Signature 并调用 HTTP 接口。详细 HTTP 契约与模型参见 Apifox 与开放控制台。",
     "developerName": "职安心",
     "category": "Developer Tools",
     "capabilities": ["Interactive", "Write"],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zax360/openapi-skills",
-  "version": "1.0.1",
-  "description": "职安心开放平台 Agent Skills（签名、只读查询、线索 ingest），供 npx skills / Cursor / Codex 等加载",
+  "version": "1.0.2",
+  "description": "职安心开放平台 Agent Skills（签名、只读查询、线索、同步、合作方与事件接口），供 npx skills / Cursor / Codex 等加载",
   "license": "MIT",
   "keywords": [
     "zhianxin",

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

@@ -1,7 +1,7 @@
 ---
 name: zhianxin-openapi-leads
 version: 1.0.0
-description: "职安心开放平台线索写入与查询：POST /v1/leads/ingest、GET /v1/leads/staging/:id。当用户要通过 Agent 提交报名线索或查询暂存状态时使用。"
+description: "职安心开放平台线索写入与查询：POST /v1/leads/ingest、GET /v1/leads、GET /v1/leads/staging/:id。当用户要通过 Agent 提交报名线索、查询线索列表或查询暂存状态时使用。"
 metadata:
   requires:
     bins: ["curl", "openssl"]
@@ -45,6 +45,22 @@ curl -sS "$BASE/v1/leads/staging/线索记录ID" \
   -H "Cw-Signature: $SIG"
 ```
 
+## 查询线索列表 · GET /v1/leads
+
+```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?page=1&page_size=100" \
+  -H "Cw-Access-Key: $ACCESS_KEY" \
+  -H "Cw-Timestamp: $TS" \
+  -H "Cw-Signature: $SIG"
+```
+
+CLI 等价：`zax360 lead list [--page 1] [--page-size 100]`
+
+响应结构：`data.list`（数组）+ `data.total`（总数）。
+
 ## 原则
 
 - 写入前向用户确认内容与合规要求；避免重复提交同一线索 unless 用户明确要求。

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

@@ -0,0 +1,60 @@
+---
+name: zhianxin-openapi-ops
+version: 1.0.0
+description: "职安心开放平台通用开放能力：合作方 payroll/labor/insurance 暂存、事件订阅与投递日志、闲鱼经营接口、触达回写、AI 报告、access token、静态 token、scope 申请。当用户要调用这些 /v1 扩展接口或用 zax360 request get/post 访问任意路径时使用。"
+metadata:
+  requires:
+    bins: ["curl", "openssl"]
+---
+
+# 通用开放能力（Agent）
+
+> 前置条件：先阅读 `../zhianxin-openapi-shared/SKILL.md`。本 Skill 只给路由、scope 与调用边界；请求/响应字段以开放控制台、Apifox 和仓库 README 为准。
+
+## 建议调用方式
+
+- 任意 GET：`npx @zax360/openapi-cli request get /v1/...`
+- 任意 POST JSON：`npx @zax360/openapi-cli request post /v1/... --data '{...}'`
+- 直接 cURL 时，GET 用三行签名，POST 用四行签名并追加原始 JSON body。
+
+## 路由速查
+
+| 能力 | 路径 | scope/认证 |
+|------|------|------------|
+| 发薪暂存 | `POST /v1/partner/payroll/batches` | `partner.payroll:write` |
+| 连续劳务暂存 | `POST /v1/partner/labor/records` | `partner.labor:write` |
+| 保险暂存 | `POST /v1/partner/insurance/records` | `partner.insurance:write` |
+| 查询暂存单 | `GET /v1/partner/staging/:id` | `partner.staging:read` |
+| 事件订阅 | `POST /v1/event/subscriptions`、`GET /v1/event/subscriptions`、`POST /v1/event/subscriptions/:id/disable` | `event.subscription:manage` |
+| 事件日志 | `GET /v1/event/logs`、`GET /v1/event/deliveries` | `event.log:read` |
+| 投递重试 | `POST /v1/event/deliveries/:id/retry` | `event.subscription:manage` |
+| 闲鱼写入 | `POST /v1/xianyu/publish/precheck`、`/address/standardize`、`/fission`、`/content/risk-check`、`/post/result-callback`、`/metrics/account`、`/metrics/job`、`/penalty/callback` | `xianyu:write` |
+| 闲鱼查询 | `GET /v1/xianyu/dashboard`、`GET /v1/xianyu/reconciliation` | `xianyu:read` |
+| 触达 | `POST /v1/lead/touch/callback`、`GET /v1/lead/touch/route` | `touch.callback:write` / `touch.route:read` |
+| AI 报告 | `POST /v1/ai/report/generate`、`GET /v1/ai/report/:task_no`、`POST /v1/ai/report/:task_no/refresh` | `ai.report:write` / `ai.report:read` |
+| 短期 access token | `POST /v1/auth/token` | AK/SK 签名 |
+| 静态 token | `POST /v1/account/static-tokens`、`POST /v1/account/static-tokens/:id/revoke` | 账号管理权限 |
+| scope 申请 | `POST /v1/account/scope-applications` | 商户账号 |
+
+合作方暂存写入建议带 `Idempotency-Key`，长度不超过 128 字符。
+
+## POST 模板
+
+```bash
+TS=$(date +%s)
+BODY='{"event_types":["lead.ingested"],"callback_url":"https://example.com/webhook"}'
+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/event/subscriptions" \
+  -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"
+```
+
+## 安全边界
+
+- 高风险写入、投递重试、token 创建/吊销、scope 申请前必须让用户确认。
+- 不要猜测业务 payload；缺字段时先查看 Apifox/控制台或让用户提供样例。
+- 不处理 `/admin/*`、内部 code-search 管理接口或本地服务器配置；这些不是外部合作方 Agent 默认能力。

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

@@ -1,7 +1,7 @@
 ---
 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 子命令时触发。"
+description: "职安心开放平台只读：CLI zax360 openapi（company-list、company-find-by-name、job-info、job-types、info、dict-degree、consultant-list）与 GET /v1/jobs、/v1/jobs/:id、/v1/job/list、/v1/job/status、/v1/companies、/v1/consultants、/v1/account/*、/v1/catalog/services。用户要拉企业列表、岗位详情、顾问、目录、用量或让 Agent 用 openapi 子命令时触发。"
 metadata:
   requires:
     bins: ["curl", "openssl"]
@@ -13,7 +13,7 @@ metadata:
 
 ## CLI `zax360 openapi` 与 HTTP 一一对照
 
-Base URL = Rust 开放网关（与 `auth login` 一致）。签名头：`Cw-Access-Key`、`Cw-Timestamp`、`Cw-Signature`。
+Base URL = 开放平台 **`/v1`** 所用网关根（与 `auth login` 一致）。签名头：`Cw-Access-Key`、`Cw-Timestamp`、`Cw-Signature`。
 
 | 能力说明 | CLI | 实际请求 |
 |----------|-----|----------|
@@ -22,7 +22,8 @@ Base URL = Rust 开放网关（与 `auth login` 一致）。签名头：`Cw-Acce
 | **岗位详情** | `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 |
+| **顾问列表** | `zax360 openapi consultant-list` | `GET /v1/consultants?page=1&page_size=100` |
+| **学历字典** | `zax360 openapi dict-degree` | **不请求 `/v1`**；需 `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`。
 
@@ -46,6 +47,13 @@ GET $BASE/v1/jobs?page=1&page_size=20
 GET $BASE/v1/jobs/{id}
 ```
 
+### 岗位别名与状态
+
+```text
+GET $BASE/v1/job/list?page=1&page_size=20
+GET $BASE/v1/job/status?job_id={job_id}
+```
+
 ### 企业列表 / 详情
 
 ```text
@@ -53,6 +61,12 @@ GET $BASE/v1/companies?page=1&page_size=20
 GET $BASE/v1/companies/{id}
 ```
 
+### 顾问列表
+
+```text
+GET $BASE/v1/consultants?page=1&page_size=100
+```
+
 ### 用量与配额
 
 ```text

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

@@ -0,0 +1,63 @@
+---
+name: zhianxin-openapi-sync
+version: 1.0.0
+description: "职安心开放平台同步写入：CLI zax360 company/job sync 与 POST /v1/sync/companies、/v1/sync/jobs、/v1/sync/jobs/recruit-status。当合作方要同步企业、岗位或招聘状态时使用。"
+metadata:
+  requires:
+    bins: ["curl", "openssl"]
+---
+
+# 企业与岗位同步（Agent）
+
+> 前置条件：先阅读 `../zhianxin-openapi-shared/SKILL.md`。写接口必须确认用户拥有对应 AK/SK 与写入 scope。
+
+## 优先用 CLI
+
+```bash
+npx @zax360/openapi-cli company sync \
+  --source-code PARTNER_A \
+  --external-company-id ext-001 \
+  --company-name "示例企业"
+
+npx @zax360/openapi-cli job sync \
+  --source-code PARTNER_A \
+  --external-job-id ext-j-001 \
+  --name "普工" \
+  --company-id "<企业ID>"
+
+npx @zax360/openapi-cli job recruit-status \
+  --source-code PARTNER_A \
+  --external-job-id ext-j-001 \
+  --recruit-status Pause
+```
+
+## HTTP 路径
+
+| 场景 | 路径 | scope |
+|------|------|-------|
+| 企业 upsert | `POST /v1/sync/companies` | `recruit.customer:write`（旧 `partner:write` 兼容） |
+| 岗位 upsert | `POST /v1/sync/jobs` | `recruit.job:write`（旧 `partner:write` 兼容） |
+| 招聘状态 | `POST /v1/sync/jobs/recruit-status` | `recruit.job:write`（旧 `partner:write` 兼容） |
+
+## 通用 POST 模板
+
+POST 签名字符串为四行：`accessKey\nsecretKey\ntimestamp\nrawBody`。`rawBody` 必须与实际发送字节一致。
+
+```bash
+TS=$(date +%s)
+BODY='{"source_code":"PARTNER_A","external_company_id":"ext-001","company_name":"示例企业"}'
+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/sync/companies" \
+  -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"
+```
+
+## 操作原则
+
+- 写入前复述将要同步的 `source_code`、外部 ID、企业/岗位名称和状态。
+- 同一外部 ID 视为 upsert；重复提交前确认是否覆盖。
+- 字段模型以开放控制台、Apifox 或仓库 README 的最新契约为准。