@lark-people/cli 0.0.0-beta.1

package/skills/people-corehr-employee/references/people-corehr-employee-filter.md

@@ -0,0 +1,403 @@
+# +employee-filter
+
+- 根据筛选条件查询符合要求的员工列表和员工信息。
+- 支持分页查询（search_after）。
+- 支持自定义显示字段。
+- 支持排序字段。
+
+## 前置流程（必须遵守！）
+
+### ⚠️ 默认展示字段铁律（与 SKILL.md D5 等价）
+
+**用户未明确指定要查看哪些属性时，`--display-fields` 必须且仅传：**
+
+```json
+["employment.person.preferred_name", "employment.employee_number"]
+```
+
+即默认只展示「姓名 + 工号」。
+
+- ❌ 严禁默认追加 `employment.department` / `employment.job_level` / `employment.job_family` / `employment.work_location` 等任何字段；
+- ❌ 严禁因为本文档下文示例里出现了 `department` / `job_level` 就把它们当成"默认推荐字段"；下文示例仅用于演示**用户已显式要求**这些字段时的写法；
+- ✅ 仅当用户在自然语言中**明确点名**某个属性（如"显示部门""带上职级""把工作地点也列出来"）时，才把对应 `api_name` 追加到 `--display-fields`。
+
+> 该规则在每次 `+employee-filter` 调用前必须复核一次，违反此规则等同于违反 SKILL.md D5。
+
+---
+
+在调用此命令前，必须先判断筛选条件中是否包含需要通过名称转换为ID的字段：
+
+### 必须先转换ID的字段类型
+
+| 字段类型 | 转换方法 | 业务场景 |
+|---------|---------|---------|
+| 部门名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 人员类型名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 职级名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 序列名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 工作地点名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 成本中心名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 人员子类型名称 | 直接在 filters 中使用 `value_names` | `team` |
+| 直属上级姓名 | 使用 `+employee-search` 换 `employment_id` | - |
+
+### 内置 value_names 自动解析
+
+`+employee-filter` 已内置名称→ID 解析能力（business_scene=team），**禁止再调用 `+query-id-by-name`**。在 filters 中：
+
+- 使用 `values: [<id>...]` 直接传 ID（与历史用法一致）；
+- 使用 `value_names: [<name>...]` 由命令自动解析为 ID 后再请求接口，**仅** 对以下字段有效：
+  - `employment.department`
+  - `employment.job_level`
+  - `employment.job_family`
+  - `employment.work_location`
+  - `employment.cost_center`
+  - `employment.workforce_type`
+  - `employment.employee_subtype`
+- `value_names` 与 `values` 可同时存在，最终取并集（自动去重）。
+- 解析多匹配 / 无匹配时命令直接报错列出候选，不会静默忽略。
+- **多匹配处理规则**：当某个 `value_names` 命中多条数据时，命令会按 `(id, name, name_path)` 成组列出全部候选，由**用户进一步甄别 / 指定更精确的查询名称**或**直接选取目标 id**。下一次重试时，必须将选定的 id 放入该 filter 的 `values` 字段，并**移除该 filter 上的 `value_names`**，禁止继续重复传 `value_names` 让命令再去解析。
+- 其他字段（如 `employment.direct_manager`、`employment.dotted_line_manager`、`employment.manage_relations_all`）仍需先通过 `+employee-search` 取得 `employment_id` 再传入 `values`。
+
+### field_api_name 命名规范
+- `field_api_name` **必须使用** `+employee-fields-query` 返回的完整 `api_name`（含命名空间前缀），禁止省略前缀。
+- 查询员工相关字段一律以 `employment.` 开头，例如：
+   - ✅ `employment.workforce_type`（人员类型）- 用于查询正式/实习/顾问等员工类型
+   - ✅ `employment.department`（部门）
+   - ✅ `employment.job_level`（职级）
+   - ✅ `employment.job_family`（序列）
+   - ✅ `employment.work_location`（工作地点）
+   - ✅ `employment.cost_center`（成本中心）
+   - ✅ `employment.employee_subtype`（人员子类型）- 需配合特定业务场景使用
+   - ✅ `employment.direct_manager`（直属上级）
+   - ❌ `workforce_type`（缺少 `employment.` 前缀，会导致 API 报 `config not found` 错误）
+   - ❌ `department`（缺少 `employment.` 前缀）
+   - ❌ `job_level`（缺少 `employment.` 前缀）
+
+### 转换流程示例
+
+#### 1. 部门名称筛选
+```bash
+people-cli corehr +employee-filter --filters '[{"field_api_name":"employment.department","operator":"in","value_names":["技术部"],"is_strand_id_in":true}]'
+```
+
+#### 2. 人员类型名称筛选
+```bash
+people-cli corehr +employee-filter --filters '[{"field_api_name":"employment.workforce_type","operator":"eq","value_names":["正式"],"is_strand_id_in":false}]'
+```
+
+## 基本用法
+
+```bash
+people-cli corehr +employee-filter [flags]
+```
+### 查看帮助信息
+
+```bash
+#查看所有命令行
+people-cli corehr--help
+
+# 查看帮助 +employee-filter信息
+people-cli corehr +employee-filter --help
+```
+
+## 所需权限
+
+| Scope |
+|-------|
+| `corehr:employment_info_filter:read` |
+
+
+## 查询参数说明
+
+| Flag | 类型      | 必填 | 默认值 | 说明                                                           |
+|------|---------|------|---|--------------------------------------------------------------|
+| `--filters` | string (JSON) | 否 | - | 筛选条件，JSON 数组格式                                               |
+| `--sort-fields` | string (JSON) | 否 | - | 排序字段，JSON 数组格式                                               |
+| `--display-fields` | string (JSON) | 否 | - | 展示字段，JSON 数组格式                                               |
+| `--limit` | int     | 否 | `30` | 返回结果数量上限（最大 100）                                             |
+| `--search_after` | string  | 否 | - | 分页游标，用于分页（首次请求为空，后续请求使用上次返回的 search_after 值,返回结果数量上限（最大 100） |
+| `--accept-language` | string  | 否 | `zh-CN` | 响应语言：`zh-CN`（中文）、`en-US`（英文）                                 |
+
+### accept-language 选择策略
+
+根据用户使用的语言自动选择：
+- 用户使用**中文**时 → 使用 `zh-CN`（默认）
+- 用户使用**英文**时 → 使用 `en-US`
+- 不确定时默认使用 `zh-CN`
+
+### filters 格式
+
+#### 严格约束（必须遵守）
+
+1. **字段名称必须来源于 `+employee-fields-query`**
+    - 所有 filters 中使用的字段 API 名称，必须与 `+employee-fields-query` 返回结果中的字段名称**严格一致**，不得自行拼写或猜测。
+
+2. **"XX 团队的员工"优先理解为"以 XX 为直属上级的员工"**
+    - 先通过 `+employee-search` 查询 XX 的 `employment_id`；
+    - 再以 `employment.manage_relations_all` 作为筛选条件，查询其下属员工。
+
+3. **不支持的筛选字段 → 直接拒绝并提示**
+    - 若用户要求的筛选条件在 `+employee-fields-query` 返回结果中**不存在**，或其 `filterable` 属性为 `false`：
+        - **禁止**尝试通过其他接口、字段组合或任何变通方式绕过此限制；
+        - **仅返回**当前所有支持筛选的字段name（以 JSON 数组格式），不附加额外说明或建议。
+    - 示例回复格式：该字段不支持筛选。当前支持的筛选字段：["人员类型","职级","序列","工作地点"]
+
+#### 示例
+```json
+[
+  {
+    "field_api_name": "employment.department",
+    "operator": "in",
+    "values": ["部门ID"],
+    "is_strand_id_in": true
+  }
+]
+```
+
+或者使用 `value_names` 让命令自动解析：
+```json
+[
+  {
+    "field_api_name": "employment.department",
+    "operator": "in",
+    "value_names": ["技术部"],
+    "is_strand_id_in": true
+  }
+]
+```
+#### 字段说明
+| 字段 | 说明                                                                                                                                                                     |
+|------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `field_api_name` | 字段API名称（可通过 `+employee-fields-query` 获取，仅 `filterable` 为 `true` 的字段才能参与筛选。**注意**：`field_api_name` 必须使用完整命名空间前缀，如 `employment.department`、`employment.workforce_type`，禁止省略前缀） |
+| `operator` | 操作符，与 `field_api_name` 配套使用（由 `+employee-fields-query` 返回的 `type` 决定可用操作符，`operators` 字段列出具体操作符） |
+| `values` | 筛选值数组（ID 列表）。传值方式由 `+employee-fields-query` 返回的 `type` 决定，详见 [`people-corehr-employee-fields-list.md`](./people-corehr-employee-fields-list.md) 的 type 字段类型说明 |
+| `value_names` | （可选）名称列表。命令会自动解析（business_scene=team）为 ID 后再请求接口，**禁止再调用 `+query-id-by-name`**。仅对 `employment.department / job_level / job_family / work_location / cost_center / workforce_type / employee_subtype` 生效；与 `values` 可同时存在，取并集 |
+| `is_strand_id_in` | 是否包含下级，详见下方 `is_strand_id_in` 说明 |
+
+### is_strand_id_in 说明
+
+`is_strand_id_in` 控制筛选时是否包含下级数据，取值规则如下：
+
+| `field_api_name` | `is_strand_id_in` 值 |
+|------------|---------------------|
+| `employment.department` | 可选：`true`（默认，包含下级）/ `false`（不包含下级） |
+| `employment.work_location` | 可选：`true`（默认，包含下级）/ `false`（不包含下级） |
+| `employment.cost_center` | 可选：`true`（默认，包含下级）/ `false`（不包含下级） |
+| `employment.job_family` | 可选：`true`（默认，包含下级）/ `false`（不包含下级） |
+| `employment.direct_manager` | 恒传 `true` |
+| `employment.dotted_line_manager` | 恒传 `true` |
+| 其他 `field_api_name` | 传 `false` |
+
+### 常用筛选字段示例
+
+#### 人员类型筛选
+```json
+[
+  {
+    "field_api_name": "employment.workforce_type",
+    "operator": "eq",
+    "values": ["正式员工ID"],
+    "is_strand_id_in": false
+  }
+]
+```
+
+#### 入职日期范围筛选
+```json
+[
+  {
+    "field_api_name": "employment.effective_time",
+    "operator": "gte",
+    "values": ["2024-10-01"],
+    "is_strand_id_in": false
+  }
+]
+```
+
+#### 组合筛选（正式员工 + 2024-10-01后入职）
+```json
+[
+  {
+    "field_api_name": "employment.effective_time",
+    "operator": "gte",
+    "values": ["2024-10-01"],
+    "is_strand_id_in": false
+  },
+  {
+    "field_api_name": "employment.workforce_type",
+    "operator": "eq",
+    "values": ["7186577930586457611"],
+    "is_strand_id_in": false
+  }
+]
+```
+
+### sort-fields 格式
+#### 严格约束（必须遵守！）
+**所有 sort-fields 中使用的字段API名称必须从 `+employee-fields-query` 命令返回的结果中获取，并且必须严格一致。如果出现不一致的情况，必须立即停止执行。询问用户是否继续。**
+
+
+| 字段 | 说明 |
+|------|------|
+| `field_api_name` | 字段 API 标识（可通过 `+employee-fields-query` 获取） |
+| `order` | 排序方向：`0` 升序、`1` 降序 |
+
+### 常用排序字段示例
+```json
+[
+  {
+    "field_api_name": "employment.job_level",
+    "order": 0
+  }
+]
+```
+
+### display-fields 格式
+
+#### 严格约束（必须遵守！）
+
+1. **默认值规则（与 SKILL.md D5 等价）**：用户未明确指定要查看哪些属性时，`--display-fields` 必须且仅传 `["employment.person.preferred_name", "employment.employee_number"]`（姓名 + 工号）。仅当用户在自然语言中显式点名某属性（如"显示部门""带上职级"）时，才将对应 `api_name` 追加进来。
+2. **所有 display-fields 中使用的字段API名称必须从 `+employee-fields-query` 命令返回的结果中获取，并且必须严格一致。如果出现不一致的情况，必须立即停止执行。询问用户是否继续。**
+
+#### 执行前自检（每次调用 `+employee-filter` 前必须逐条核对）
+
+> 以下三条任意一条不通过，**禁止追加任何业务字段**到 `--display-fields`，必须回退到默认最小集 `["employment.person.preferred_name","employment.employee_number"]`。
+
+- [ ] 用户**原话**是否包含"显示 / 查看 / 带上 / 列出 / 给我看 + 具体字段名（部门 / 职级 / 序列 / 工作地点 / 入职时间 等）"？
+- [ ] 我准备追加到 `--display-fields` 的每个字段，是否都能从用户原话中**直接引述**到对应词？
+- [ ] 是否存在"看着示例像就照搬"、"为了表格更丰富所以多加几个"、"用户问的是部门所以顺便显示部门"（**注意**：用户问"X 部门的员工"是**筛选条件**，不是要求**展示部门列**）等情形？若有，立即停止追加。
+
+#### 默认场景（用户未指定字段）：
+```bash
+# 用户："帮我查一下 XX 部门的员工" —— 未点名任何属性，使用默认最小集
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","value_names":["XX"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+```
+
+#### 用户显式要求字段时：
+```bash
+# 用户："帮我查 XX 部门员工，并显示部门和职级" —— 在最小集基础上追加用户点名的字段
+people-cli corehr +employee-filter --display-fields '["employment.person.preferred_name","employment.employee_number","employment.department","employment.job_level"]'
+```
+
+#### 错误示例：
+```bash
+# 错误 1：用户没要求看部门/职级，却默认追加了这些字段（违反 D5）
+people-cli corehr +employee-filter --display-fields '["employment.person.preferred_name","employment.department","employment.job_level"]'
+
+# 错误 2：用户问的是"XX 部门的实习生"，部门是筛选条件而非展示要求，仍然追加了 department 列（违反 D5）
+people-cli corehr +employee-filter --display-fields '["employment.person.preferred_name","employment.employee_number","employment.department"]'
+
+# 错误 3：使用了不存在的字段API名称
+people-cli corehr +employee-filter --display-fields '["employment.name"]'  # employment.name 不是有效的字段API名称
+```
+
+
+## 输出
+
+每条记录为固定列 + 动态列的结构：
+
+| 字段 | 说明 |
+|------|------|
+| `Employment ID` | 员工ID（固定列） |
+| `employment.xxx` | 由 `--display-fields` 指定的字段，列名为对应的 `api_name`，值为字段显示文本（无值时为 `null`） |
+
+### 严格约束（必须遵守！）
+#### 筛选结果数据获取逻辑，具体数据从控制台获取，控制台数据展示示例
+```text
+Next page: --search-after-key [{"larkmy":[1,"xuan hui he patsy ziemann","34216443","7628524534569944581"]},null]
+Has more: true
+Count: 33
+```
+
+#### 分页处理（强制），当用户请求查询数据详情时，必须检查接口返回的 Has more 字段：
+- 若 Has more 为 true，必须主动提示用户是否需要查看下一页数据，不得静默忽略。
+- 若 HasMore 为 false，正常结束输出即可。
+### 输出示例
+
+> 下例展示**默认场景**（用户未点名任何属性）的输出形态：仅包含姓名 + 工号。`employment.department` / `employment.job_level` 等业务字段**只有在用户显式要求时**才会出现。
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": [
+    {
+      "Employment ID": "7342393515664573996",
+      "employment.person.preferred_name": "张三",
+      "employment.employee_number": "10086"
+    }
+  ],
+  "meta": {
+    "count": 1
+  }
+}
+```
+
+## 示例
+
+> 以下示例中 `<...>` 为需替换的占位符，实际使用时请替换为具体值。
+>
+> **⚠️ 阅读示例时请注意**：下方示例中绝大多数 `--display-fields` 仅含 `["employment.person.preferred_name", "employment.employee_number"]`（默认最小集）。**仅有少数示例**显式标注了 `# ⚠️ 仅当用户原话包含「显示部门 / 带上职级 / 把工作地点也列出来」等明确要求时使用` 才会追加业务字段。如果你**不是**在响应这类显式要求，**禁止**照搬那少数示例的 `--display-fields`。
+
+```bash
+# 第一步：查看可筛选字段及其 type、operators
+people-cli corehr +employee-fields-query --format table
+
+# 第二步（默认场景，用户未点名属性）：按部门筛选员工，仅返回姓名+工号
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","values":["7519409170505483820"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+
+# ⚠️ 仅当用户原话包含「显示部门 / 序列 / 职级」等明确要求时使用：按部门筛选员工
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","values":["7519409170505483820"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number","employment.department","employment.job_family","employment.job_level"]' \
+  --format table
+
+# ⚠️ 仅当用户原话同时要求「按职级排序」并「显示职级」时使用：按部门筛选并按职级排序
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","values":["7519409170505483820"],"is_strand_id_in":true}]' \
+  --sort-fields '[{"field_api_name":"employment.job_level","order":0}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number","employment.job_level"]' \
+  --limit 100
+
+# 按人员类型筛选（默认场景，仅返回姓名+工号）
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.workforce_type","operator":"eq","values":["75194091705055483820"]}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+
+# 查询我的下级（默认场景：未点名属性 → 姓名+工号；manage_relations_all 恒传 is_strand_id_in 为 true，values 传当前用户 employment_id，可通过 +basic-user-info 获取）
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.manage_relations_all","operator":"in","values":["<employment_id，可通过 +basic-user-info 获取>"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+
+# 查询我的直线下级（默认场景：仅姓名+工号；direct_manager 恒传 is_strand_id_in 为 true）
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.direct_manager","operator":"in","values":["<employment_id，可通过 +basic-user-info 获取>"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+
+# 查询我的虚线下级（默认场景：仅姓名+工号；dotted_line_manager 恒传 is_strand_id_in 为 true）
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.dotted_line_manager","operator":"in","values":["<employment_id，可通过 +basic-user-info 获取>"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+
+# 翻页查询（默认场景：仅姓名+工号）
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","values":["7519409170505483820"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --search-after-key "上一次返回的key"
+
+# 查询 CIS 部门下职级为 L4 的员工（默认场景：仅姓名+工号；直接传 value_names，命令内部自动名称→ID 解析）
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","value_names":["CIS"],"is_strand_id_in":true},{"field_api_name":"employment.job_level","operator":"eq","value_names":["L4"]}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number"]' \
+  --format table
+```

package/skills/people-corehr-employee/references/people-corehr-employee-search.md

@@ -0,0 +1,73 @@
+# +employee-search
+
+通过关键词搜索员工，支持按姓名、工号、邮箱搜索。
+
+## 用法
+
+```bash
+people-cli corehr +employee-search --keyword <关键词> [flags]
+```
+
+## 参数
+
+| Flag                | 类型     | 必填 | 默认值     | 说明                           |
+| ------------------- | ------ | -- | ------- | ---------------------------- |
+| `--keyword`         | string | 是  | -       | 搜索关键词（员工姓名、工号或邮箱）            |
+| `--accept-language` | string | 否  | `zh-CN` | 响应语言：`zh-CN`（中文）、`en-US`（英文） |
+
+### accept-language 选择策略
+
+根据用户使用的语言自动选择：
+
+- 用户使用**中文**时 → 使用 `zh-CN`（默认）
+- 用户使用**英文**时 → 使用 `en-US`
+- 不确定时默认使用 `zh-CN`
+
+### 自动识别的规则
+
+- 手机号：数字
+- 工号：4-10位字符（英文 数字 下划线）
+- 姓名：其他情况，默认按姓名搜索
+
+## 所需权限
+
+| Scope                                  |
+| -------------------------------------- |
+| `corehr:employment_info_search:read` |
+
+## 输出
+
+### 强制按照这个字段顺序拼成表格进行输出
+
+| 字段                | 说明    |
+| ----------------- |-------|
+| `name`            | 员工姓名  |
+| `employee_number` | 工号    |
+| `employment_id`   | 雇佣 ID |
+
+## 基本用法
+
+```bash
+# 搜索姓名包含"李"的员工
+people-cli corehr +employee-search --keyword 李
+
+# 搜索工号
+people-cli corehr +employee-search --keyword 5916335
+
+# 按邮箱搜索
+people-cli corehr +employee-search --keyword user@example.com
+# 按邮箱搜索 可不带后缀
+people-cli corehr +employee-search --keyword user
+
+# 英文输出
+people-cli corehr +employee-search --keyword 李 --accept-language en-US
+```
+### 查看帮助
+
+```bash
+# 查看corehr所有命令
+people-cli corehr --help
+# 查看+employee-search命令帮助
+people-cli corehr +employee-search --help
+
+```