员工画像 Pipeline 与数据连接对齐指南

表述：本文面向 工作区管理员，说明如何让「员工画像」技能的固定取数清单（pipeline）与 HR 数据连接里的预定义查询 对上号，以及 在消息里对工作智能体说什么 完成一次性配置。日常用户只需说「生成某某的员工画像」，不必了解 pipeline 或 query_id。实现对照见文末 实现对照。

日期：2026-07-12 前置阅读：对话生成员工画像操作指南 CareTop / 日隆补充：docs/data-connection-templates/caretop-employee-profile/ 查询模板 JSON：examples/employee-profile-pipeline/data-connection/query-defs.example.json

结论

员工画像技能的 取数顺序真源 是技能附属文件 references/pipeline.json，其中每一步写死了规范 query_id（如 employee_by_name）。

若 HR 数据连接（例如 slug 为 rilong）里只有 eaemp_by_name、eacontactinfo_by_empid 等 另一套 id，智能体仍会读 pipeline，但执行时会 现场脑补映射、散装多查、甚至用手写 HTML 兜底——用户能拿到报表，却不是理想固定流程。

推荐对齐方式（路径 A）：不改 pipeline，由管理员在对话中把 pipeline 需要的规范查询 写入数据连接（query.upsert），再逐条验证。

不推荐（路径 B）：把 pipeline 改成 rilong 原生零散 query_id——对话工具 无法一键改 references/pipeline.json，且会破坏「一步一 save_as」设计。

1. 不对齐时会发生什么

以真实会话「吴静荣员工画像」为例（工作智能体 3e30250e-…）：

对齐完成后，同类对话应呈现：

1. query.run 使用 employee_by_name → employee_contact_by_emp_id → …（与 pipeline 一致）
2. run_script + assemble_profile.py 产出固定版式 HTML
3. 不再依赖智能体临场映射 rilong 原生 id

2. pipeline 需要哪些 query_id

技能 references/pipeline.json 的 steps 与规范查询对应关系如下（完整 SQL 见示例 JSON）：

其中 eaemp_photo_by_id、mostayentryphoto_by_empname 常与 rilong 已有查询重名；缺的是带 employee_ 前缀 的几条「画像专用」聚合查询。

3. 推荐路径 A：对话写入规范查询（管理员）

3.1 权限与环境

• 须 工作区管理员（query.upsert）
• 在 已选工作区 的 工作智能体 会话中操作
• 已知 HR 连接 slug（下文以 rilong 为例，请替换为你们工作区实际 slug）

3.2 一键话术（可直接粘贴）

主话术——写入 + 验证（平台会识别并直接执行 upsert，无需智能体读取仓库里的 JSON 文件）：

帮我把员工画像 pipeline 需要的预定义查询写入 rilong 数据连接。

请按内置 query-defs 清单逐条 query.upsert（若已存在则更新）。

写完后 query.list 确认至少存在：
employee_by_name、employee_contact_by_emp_id、employee_org_by_emp_id、
employee_contract_by_emp_id、employee_salary_by_emp_id、
eaemp_photo_by_id、mostayentryphoto_by_empname。

然后用「吴静荣」和「赵江」对各 step 对应 query_id 逐条 query.run 验证；
把验证结果列表告诉我（count、是否 ok）。

说明：若话术含「员工画像 pipeline + 预定义查询 + query.upsert」，平台会走 批量写入快路径（内置 CareTop 适配 SQL），并返回验证表。勿与「当前有几个数据连接」类列举问题混在同一句里——后者只会列出连接。

旧版话术（引用仓库路径，仅作开发对照；对话智能体读不到 examples/... 路径时曾会卡住）：

请读取 examples/employee-profile-pipeline/data-connection/query-defs.example.json …

CareTop / 日隆库 SQL 校正——内置模板已含 superiorLeader、eacontactinfo 等适配；若现场仍有差异，补一句：

写入时按我们 CareTop 库表校正 SQL：
- employee_org_by_emp_id：上级关联用 eaemp.superiorLeader，不要用 superiorId；
- employee_contact_by_emp_id：联系方式优先查 eacontactinfo（mobileNo 等），不要只查 eaemp；
- employee_contract_by_emp_id：合同表 eacontract，字段含 affectedDate、ctYears、endDate；
- employee_salary_by_emp_id：查 `srfixedsalaryreadjustrec`（typeId=1 基本工资、typeId=2 绩效），**不要**用常为空的 `srbasicsalary` / `eaemp_salary_view`；
- eaemp_photo_by_id / mostayentryphoto_by_empname：证件照在 **`eaphoto`**（`photo`、`citizenIDPhoto`），**不要** `SELECT photo FROM eaemp` 或 `mostayentryphoto`（会报 Unknown column 'photo'）。
WHERE 绑定列名用真实列名（emp_id / emp_name），占位符只用 ?，不要用 @empName。

列名批量修复（针对连接里 已有 的零散查询，非 employee_* 专用条）：

请对 rilong 连接执行预定义查询智能检查校正，
把 WHERE 里的 empId 改成 emp_id、empName 改成 emp_name。
参考 docs/data-connection-templates/caretop-employee-profile/query-defs-sql-fixes.json。
修完后用 empId=1980（吴静荣）对关键 query 各 query.run 一次。

3.3 验证话术

对齐是否成功，可在同一会话追问：

query.list 看一下 rilong 是否已有 employee_by_name 到 employee_salary_by_emp_id；
有的话用 employee_by_name 查「吴静荣」，应返回 1 条且 empId=1980。

3.4 单条修补（示例）

4. 不推荐路径 B：改 pipeline 迁就 rilong

若短期无法 upsert，智能体 仍能 用 rilong 原生 id 出报表，但属于 探索/兜底，不应作为生产标准。

5. 跟智能体怎么说：速查表

5.1 应对场景

5.2 避免说法

6. 对齐完成的判据

在 消息 里发起一次「生成吴静荣的员工画像」，观察工具轨迹（或调试镜像）应满足：

sequenceDiagram
  participant U as 用户
  participant A as 工作智能体
  participant DS as rilong 数据连接
  participant S as assemble_profile.py

  U->>A: 生成吴静荣的员工画像
  A->>A: 读 references/pipeline.json
  loop pipeline steps
    A->>DS: query.run employee_* / eaemp_photo_by_id
    DS-->>A: 行数据 / 照片 upload_id
  end
  A->>S: run_script 组装
  S-->>A: 员工画像-吴静荣-日期.html
  A->>U: mindlink://upload 下载链接

检查清单：

• [ ] query.run 的 query_id 以 employee_ 开头（照片 step 除外）
• [ ] 未 大量散装 eaemp_by_name、eadepart_by_id 等替代 pipeline 步骤
• [ ] run_script 成功，output_files 含 .html
• [ ] 未 用 file_write 手写大段 HTML 作为主交付物
• [ ] HTML 版式与技能 assets/profile.html 一致（非即兴 CSS）

7. 与 rilong 原生查询的关系

对齐 不是 删除 rilong 上已有的 eaemp_by_name、eacontactinfo_by_empid 等查询。它们是日常 HR 问数的存量资产。

对齐是 新增或更新 一组 画像 pipeline 专用 的规范 id，使智能体 不必每次映射。两套 id 可并存：

参数键名仍以连接 query.list 为准；rilong 常见对照见 docs/data-connection-templates/caretop-employee-profile/PARAMS-REFERENCE.md。

8. 常见问题

8.1 智能体仍用 eaemp_by_name 不用 employee_by_name

• 先 query.list 确认 employee_by_name 是否存在；不存在则智能体只能映射。
• 执行 §3.2 主话术 后重试。

8.2 upsert 后 query.run 报 Unknown column

• 管理端 数据连接 → 预定义查询 → 智能检查校正（须选该连接），或对话中使用 §3.2 列名批量修复 话术。
• 机制说明见 预定义查询智能检查校正机制解析。

8.3 run_script 报不允许 .html

• 平台默认脚本产出白名单已包含 .html / .htm（2026-07-12 起）；重启 backend 后生效。
• 若工作区自定义了 allowed_output_ext 且未含 .html，须在能力包中放开。

8.4 说「更新 pipeline」却变成说明书

• 须同时包含：更新/修改 + pipeline（或固定取数） + 脚本组装 + 员工画像/HTML。
• 详见 对话生成员工画像操作指南 §2b。

9. 实现对照

延伸阅读

• 对话生成员工画像操作指南 — 端到端五步与用户话术
• 预定义查询智能检查校正机制解析 — 列名校正与 AI 审查
• examples/employee-profile-pipeline/README.md — 示例仓库架构说明