人才给力能做 CLI 复刻,
难的不是接口,是审批流语义
用已登录的浏览器会话把站点跑了一遍,从网络请求和前端 bundle 两路交叉,还原出全站服务分层、接口清单、请求参数与数据模型。结论:这是一套规整的 REST + JSON 接口,没有 GraphQL、没有请求签名、没有前端加密,用 curl 加一个 token 就能跑通全流程。
00结论先说
三个判断,按确定性从高到低。
revision、targetStageCode、stageFields、stageMeta 去走 stage-transitions;阶段码、必填字段、流转约束都定义在 pipeline-templates 里。要做稳,必须先把这个模板结构吃透。01架构分层
站点是 Next.js(Turbopack)单页应用,前端只做渲染,所有业务能力都在四个后端前缀后面。
/api/proxy/api/atlas/v1 · 实体与元数据
全站的核心。管实体类型、JSON Schema、实体 CRUD、批量 lookup、标签、事件流水、活动日志、分析看板、列表配置、日历。所有业务对象(候选人 / 职位 / 客户 / 合同 / 账单 / 发票)都在这一层。
/api/proxy/api/workflow/v1 · 流程
项目(project)、申请(application,即"候选人投到某项目"这条记录)、阶段流转、流程模板、按阶段统计。职位项目页和流程进度页全靠它。
/api/user-proxy/api/v1 · 身份与权限
短信登录、token 刷新/吊销、当前用户与租户、成员、角色、权限点、团队树、通知。CLI 的登录态由这里签发。
/api/effex/v1 · 检索与查重
独立服务,不挂 proxy。负责跨实体检索(search / search:count)和重复检测(dedup)。注意它的鉴权路径和另外三个不一样,见下一节。
实体是有物理表的
GET /entity-types 直接暴露了存储结构:13 种实体全部是 dedicated_table 模式,落在 atlas_data 库的独立表里,schema 带版本号和 checksum。
| entityType | 物理表 | schema 版本 | CLI 里会用到 |
|---|---|---|---|
| candidate | atlas_data.entity_candidate | v3 | 人才库、寻访结果、推荐 |
| job | atlas_data.entity_job | v3 | 职位项目、JD 解析 |
| client | atlas_data.entity_client | v3 | 客户管理、客户树 |
| contract | atlas_data.entity_contract | v4 | 合同管理 |
| billing | atlas_data.entity_billing | v1 | 账单与业绩分成 |
| invoice | atlas_data.entity_invoice | v1 | 开票、回款、快递 |
| contact | atlas_data.entity_contact | v4 | 客户联系人 |
| company | atlas_data.entity_company | v1 | 公司主体 |
| user / team | atlas_data.entity_user / entity_team | — | 顾问、团队归属 |
| context / qa / bipo_employee | 同名表 | v1 | 边缘对象,本期不涉及 |
02鉴权链
登录态拆成两段:短命的 access token 在内存里,长命的 refresh token 在 HttpOnly cookie 里。CLI 只要照着这个模型做 cookie jar,就不需要无头浏览器。
# 1. 发短信验证码 POST /api/user-proxy/api/v1/auth/sms Content-Type: application/json { "phone": "1xxxxxxxxxx", "purpose": "login" } # 2. 登录:拿 accessToken,响应同时 Set-Cookie 下发 refresh token POST /api/user-proxy/api/v1/auth/web/login { "account": "1xxxxxxxxxx", "code": "123456" } → { "accessToken": "...", "expiresIn": ..., "user": {...} } # 3. 之后所有业务请求 Authorization: Bearer <accessToken> # 4. token 过期:cookie 还在,静默换新的(不需要人工) POST /api/user-proxy/api/v1/auth/web/token/refresh → { "accessToken": "..." } # 5. 退出 POST /api/user-proxy/api/v1/auth/web/token/revoke
前端 HTTP client 的逻辑也印证了这一点:createPlatformHttpClient 统一加 Authorization: Bearer 和 credentials:'include',遇到 401 自动调一次 refreshAccessToken() 再重试原请求。这套模式在 CLI 里就是一个拦截器,实现成本很低。
/api/effex/v1/search,返回的是 {"detail":"Authenticated tenant context required"}——不是 401,是 400 级别的一句话。也就是说 租户上下文是从 token 里解的,不是从 cookie 或 header 里拿的。CLI 如果只存 cookie 不存 token,会得到这个看起来很莫名的报错。
Tenant 切换
同一账号可能挂多个租户,切换走 POST /tenants/{id}/switch,之后 token 重签。CLI 建议把 tenantId 和 token 一起落地,并且在每次请求前校验 GET /users/me 里的当前租户,避免拿着 A 租户的 token 查 B 租户的数据。
03接口清单
下表按模块分组,是本次通过真实流量 + bundle 静态分析交叉验证得到的端点。带「实测」标记的是这一轮真的打到并返回 200 的;其余来自服务方法表,参数形态可信但未逐个回放。
| 方法 | 路径 | 参数 / 说明 |
|---|
共 0 条。列表随筛选实时更新。
04数据模型
所有实体共用同一个信封结构,业务字段按四个桶分类。这一点决定了 CLI 的序列化逻辑可以只写一次。
{
"id": "uuid",
"tenantId": "tnt_...",
"entityType": "candidate",
"status": "active",
"visibility": "tenant",
"accessControl": {},
"schemaVersion": 3,
"schemaChecksum": "...",
"data": {
"standardFields": {}, // 平台定义的业务字段
"customFields": {}, // 租户自定义字段
"functionFields": {}, // 计算字段(只读)
"rawData": {} // 原始数据,例如简历解析结果
},
"revision": 7, // 乐观锁,更新必须带
"createdBy": "...", "createdAt": "...",
"updatedBy": "...", "updatedAt": "..."
}
字段表分布在 JSON Schema 的 properties.standardFields.properties 里(注意不是 $defs,那个只有类型定义)。六个业务对象的字段规模差别很大:
GET /entity-schemas/{type}?format=schema 是运行时拿得到的,也就是说 CLI 不需要把字段表硬编码进去——启动时拉一次 schema,就能自动生成 --set 的可选键、类型校验和补全。字段变更时 CLI 不需要重新发版。另外几个复刻时容易踩的点:
- 更新必须带 revision。
PATCH /entities/{type}/{id}不带最新 revision 会被拒,这是并发保护,不是 bug。 - 写入要带数据源头。
POST /entities/{type}需要X-Data-Source: platform,缺了会被当成外部导入走另一条校验。 - 批量读用 lookup。详情页是
POST /entities/{type}/lookup带{ids, includeDeleted},一次拿一批,比拼 N 次单查划算得多。 - 字段值有引用类型。
userReference/clientReference/entityReference/fileReference存的是 id 而不是对象,CLI 输出时要自己做一次展开或留--expand开关。
05检索 DSL
所有列表页的筛选、排序、分页,最终都收敛到同一个接口,用的是自研的过滤器树,不是简单的 query string。
{
"entityType": "candidate",
"data": ["standardFields"], // 返回哪些数据桶
"pageSize": 50, // 1..200,默认 50
"filters": [ // 树形,最多 8 层 / 100 节点
{ "key": "standardFields.works.company", "values": ["字节跳动"], "operator": "=" },
{ "key": "standardFields.basicInfo.city", "values": ["上海", "北京"], "operator": "in" }
],
"relationOperator": "and",
"relationFilters": [], // 跨实体关联筛选
"sort": [{ "key": "updatedAt", "direction": "desc" }],
"cursor": null // 游标分页,不是 offset
}
→ { "results": [{ "document": {...} }], "nextCursor": "..." }
→ POST /search:count 同 body,返回 { "totalSize": 1234 }
可用的 operator 是一张白名单,直接决定 CLI 的 --where 语法怎么设计:
比较
= != > >= < <= between
集合
in eq neq gt gte lt lte
文本 / 存在性
like not like starts with ends with exists not exists
nextCursor,请求回传 cursor。这意味着 CLI 做「导出全量」时必须循环取游标,不能算 offset;同时要注意 pageSize 上限 200,全量拉取的请求数会比较多(1 万条 = 50 次请求),建议加并发与退避。06流程与看板
「职位项目」和「流程进度」不是实体 CRUD,是独立的 workflow 服务;业务洞察是另一套看板查询。
项目 / 申请 / 阶段
核心对象只有三个:project(项目,通常对应一个职位)、application(候选人进项目的申请单)、pipeline-template(流程模板,定义阶段码和流转规则)。
# 创建申请:把候选人挂到项目下 POST /api/proxy/api/workflow/v1/applications { "projectId": "...", "primaryRefEntityType": "candidate", "primaryRefEntityId": "..." } # 阶段流转:注意 revision 与 stageFields 都是必填 POST /api/proxy/api/workflow/v1/applications/{id}/stage-transitions { "revision": 3, "targetStageCode": "client_interview", "stageFields": { ... }, // 该阶段的必填字段 "stageMeta": { ... } } // 阶段附加信息
两个列表接口的过滤参数相当丰富,基本覆盖了页面上所有筛选器的组合:
GET /projects:pipelineTemplateKey、stageCode、groupCode、ownerUserId*、participantUserId*、status、q、primaryRefEntityType/Id(s)、includeTotal、cursor。GET /applications:limit、projectId、ownerUserId*、participantUserId*、search、joinedAtFrom/To、statGroup、stageCode、status、cursor。GET /applications/stats:按阶段聚合计数,对应「流程进度」页的面包屑数字。
rcgl pipeline move <app-id> --to <stage> 这种命令,价值远大于把列表查询包一层——因为顾问真正讨厌的操作是「一次性把 20 个候选人推进到同一阶段」,而这个动作在 Web 上要点 20 次。目前模板里已捕获到一个真实模板 id:46efffdd-c410-472c-a05e-92548ab030d1。业务洞察看板
看板不是固定报表,是「配置 + 查询」两段式:先 GET /analytics/dashboards 拿到可用看板列表(已知两个:cgl_team_overview 团队总览、workbench_standard_overview 个人工作台),再 POST /analytics/dashboards/{key}/query 按参数查数。看板自己声明支持哪些筛选维度,页面上那句 invalid analytics configuration: dashboard does not expose a team filter 就是前端照抄后端的校验文案。
07实测与边界
哪些确认了,哪些没测,为什么没测。这一节是为了让后面接手的人不重复踩坑。
| 能力 | 状态 | 说明 |
|---|---|---|
| 登录态与租户识别 | 已验证 | Bearer + HttpOnly cookie 双段模型,前端 401 自动刷新一次 |
| 实体 schema 读取 | 已验证 | 六个业务对象字段表全部取到,字段数与字段名逐项核对 |
| 实体类型与物理表 | 已验证 | 13 类实体、atlas_data 独立表、schema 版本 |
| 列表 / 详情 / 关联数据 | 已验证 | 职位、候选人详情页的实体、标签、事件流水都命中 |
| 流程模板与申请列表 | 已验证 | 模板详情可读,参数形态完整 |
| 检索 search / count | 部分 | DSL 结构从前端 bundle 读出且完整;用纯 cookie 回放时被租户上下文拦下,需带 Bearer 才能实测 |
| 创建 / 更新 / 删除 | 未实测 | 方法、路径、请求头已确认;故意没有在真实租户里写入,避免污染生产数据 |
| 阶段流转 | 未实测 | 同上,属于写操作,只做了结构确认 |
| 导出 | 未捕获 | 页面有导出按钮,但触发后没有观察到导出接口,需单独补测 |
| 文件下载 | 已验证 | 简历是 HTML 渲染件,路径 /files/tenants/{tenantId}/files/candidates/resumes/{uuid}.html;下载前先换 URL |
| 权限 / 角色 / 团队 | 已验证 | 设置弹窗里的四个标签页接口全部命中 |
方法上的两条弯路
采集本身也踩了坑,记下来省得下次重来:
- 不能跨路由累加网络记录。整页加载会重置 performance 资源表,所以必须「一个路由一次完整加载 + 立即 drain」,跨页累加只会拿到一堆外壳 chunk、零个业务端点。
- 拿不到请求体。浏览器自动化接口只给 url / method / status / request_id,没有 postData;CDP 取
Network.getRequestPostData会报 session not found;往页面里注入 fetch/XHR 钩子也捕不到(模块初始化时已经持有原生引用)。真正有效的是直接读前端 chunk 做静态分析——参数名、body 结构、鉴权拦截器都是这么还原的。
08CLI 复刻方案
如果要真做,命令树大致是这样。设计取向是「实体层通用 + 业务层薄封装」,不追求把每个页面都翻译成命令。
实现要点
- 一个 HTTP 客户端管全部。Base 分四个前缀,但 header、401 重试、错误映射共用一套。建议把
{"detail":"Authenticated tenant context required"}显式映射成「token 缺失或租户不匹配」的提示。 - token 存两处。refresh token 用 cookie jar 落地(
~/.config/rcgl/cookies,权限 600),access token 存内存并在进程内按过期时间刷新。别把 access token 写进明文配置。 - 写操作强制 dry-run。
create / update / delete / move默认打印将要发送的 body,加--yes才执行;写之前自动拉一次revision,避免手填。 - schema 驱动校验。启动拉 schema 做本地校验,字段拼错在客户端就拦住,不用等服务端 400。
- 分页统一封装。
cursor循环、pageSize上限 200、并发 3~5、429/5xx 指数退避。
activity-events 里,且账号就是个人账号。建议:默认只读、写操作强制人工确认、导出走脱敏字段白名单、不在 CI 里存 cookie。09还没做的部分
按投入产出排,下面这些是下一步真正要补的。
- 导出接口。点一次导出并抓一次流量,确认是前端生成还是异步任务;如果是
jobs/{id}轮询模式,CLI 要额外做等待逻辑。 - 写入回放。在测试租户里完整跑一次 create → update → stage-transition,确认
stageFields的必填约束和报错形态。 - 列表列配置。
resolved-configs/entity_list/{type}和workflow_task_list/{key}会带 query 参数,本次直接 GET 返回 400,需要照页面实际请求补齐。 - 限流。没有观察到 429,也没有
RateLimit-*响应头;高频翻页前建议先小批量试。 - 审批流。账单和发票里出现
approvalFlowName/approvalCurrentHandler等字段,说明背后有审批引擎,但这次没有进入审批节点操作,接口形态未知。