@lark-people/cli 0.0.0-beta.1

package/skills/people-corehr-employee/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: people-corehr-employee
+version: 1.0.0
+description: "飞书人事 - 员工信息查询：搜索员工、查询当前登录员工基本信息、查询员工可筛选字段、按条件筛选员工。触发词：员工搜索、按姓名找人、查我自己、员工列表、部门员工、职级员工、员工字段、employee search、employee filter。适用边界：仅处理 employee search、basic info、fields、filter，不覆盖待入职、异动、离职、任职历史、审批、导出。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli corehr --help"
+---
+
+# corehr employee
+
+## Scope
+
+只处理以下四类员工查询能力：
+
+1. `+employee-search`：按姓名、工号、邮箱搜索员工。
+2. `+employee-basic-info-query`：查询当前登录员工的基本信息。
+3. `+employee-fields-query`：查询员工字段元数据，确认哪些字段可筛选、可排序、可展示。
+4. `+employee-filter`：按字段条件筛选员工列表。
+
+不处理待入职、异动、离职、任职历史、审批/修改、导出文件、跨模块复杂统计。命中这些边界时，停止使用本 skill，改走对应 skill 或直接说明当前能力不覆盖。
+
+## Required Flow
+
+1. **意图判定**：先判断用户是在找人、查自己、问字段能力，还是要按条件筛人。不要把待入职、异动、离职、任职历史误判到本 skill。
+2. **最短路径执行**：
+   - 按姓名/工号/邮箱找员工：直接执行 `+employee-search`。
+   - 查我自己、查我的工号、查我的 `employment_id`：直接执行 `+employee-basic-info-query`。
+   - 问哪些字段可筛选/可排序/可展示：直接执行 `+employee-fields-query`，该命令本身就是终点。
+   - 按部门、职级、序列、工作地点、上级、团队等条件查员工：先执行 `+employee-fields-query` 校准字段，再执行 `+employee-filter`。
+3. **字段校准**：凡是要构造 `+employee-filter` 的 `--filters`、`--sort-fields`、`--display-fields`，字段名都必须来自本轮真实 `+employee-fields-query` 返回的 `api_name`，禁止猜字段、禁止省略命名空间前缀。
+4. **真实执行**：条件一旦可落地，必须执行对应的最终命令。不要停在字段解释、命令草稿或搜索预演。
+5. **完成态校验并回答**：答案必须来自最后一次真实命令返回。若结果分页，必须明确说明当前页数量和是否还有下一页；不要静默截断。
+
+## Route Templates
+
+| 意图 | 最短路径 |
+| --- | --- |
+| 按姓名、工号、邮箱找员工 | 直接 `+employee-search` |
+| 查我自己当前账号对应的员工信息 | 直接 `+employee-basic-info-query` |
+| 问哪些字段能筛选/排序/展示 | 直接 `+employee-fields-query` |
+| 查某部门、某职级、某序列、某地点的员工 | `+employee-fields-query` → `+employee-filter` |
+| 查我的团队 / 我的下级 | `+employee-basic-info-query` 取自己的 `employment_id` → `+employee-filter` |
+| 查某人的团队 / 某人的下级 | 先 `+employee-search` 取该人的 `employment_id` → `+employee-filter` |
+| 查直属上级是某人的员工 | 先 `+employee-search` 取该人的 `employment_id` → `+employee-filter` |
+
+## Hard Rules
+
+- 禁止用本 skill 处理待入职、异动、离职、任职历史、审批、导出文件；这些都不属于 employee 能力边界。
+- 对 `+employee-filter` 而言，所有 `field_api_name` 都必须来自 `+employee-fields-query` 返回结果，且必须使用完整字段名，例如 `employment.department`，禁止写成 `department`、`job_level`、`workforce_type` 这类省略前缀的形式。
+- 若用户要求的筛选字段不存在，或 `filterable=false`，必须停止并明确告知该字段不支持筛选；不要尝试其他接口、相邻字段、组合字段或本地兜底。
+- 若用户要求排序字段不存在，或 `sortable=false`，必须停止并重新按 `+employee-fields-query` 返回值校准；不要凭经验继续执行。
+- `+employee-filter` 的默认展示字段必须且仅能是 `["employment.person.preferred_name","employment.employee_number"]`。用户没有明确点名要展示其他属性时，禁止追加部门、职级、序列、工作地点等字段。
+- 只有当用户原话明确提出“显示部门”“带上职级”“把工作地点也列出来”之类诉求时，才允许把对应字段追加到 `--display-fields`。
+- 对以下字段，优先在 `+employee-filter` 的 filter 中使用 `value_names`，由命令内置名称转 ID 能力完成解析，禁止额外调用 `+query-id-by-name`：
+  - `employment.department`
+  - `employment.job_level`
+  - `employment.job_family`
+  - `employment.work_location`
+  - `employment.cost_center`
+  - `employment.workforce_type`
+  - `employment.employee_subtype`
+- `employment.direct_manager`、`employment.dotted_line_manager`、`employment.manage_relations_all` 这类“人”字段不能直接传姓名，必须先通过 `+employee-search` 找到对应人的 `employment_id`，再写入 `values`。
+- “XX 团队的员工”优先理解为“以 XX 为管理者的团队成员”，优先走 `employment.manage_relations_all`；不要把“团队”误写成部门字段。
+- `+employee-search` 命中多个同名员工时，不要擅自猜测具体对象。若后续动作依赖唯一 `employment_id`，先基于搜索结果让用户确认，或明确说明当前返回的是候选列表。
+- 查询结果出现分页提示时，必须告诉用户当前页结果和是否还有下一页。若 `Has more=true`，不能静默结束。
+- 普通结果回答里不要暴露命令构造过程、内部调试步骤或无关 CLI 细节；但如果用户明确在问字段 `api_name`、字段类型或操作符，则应直接基于 `+employee-fields-query` 返回说明。
+
+## Final Answer Contract
+
+- `+employee-search`：按 `姓名`、`工号`、`employment_id` 的顺序输出候选结果。
+- `+employee-basic-info-query`：输出 `常用姓名`、`工号`、`employment_id`、`邮箱`。
+- `+employee-fields-query`：保留字段元数据的核心列，至少包含 `name`、`api_name`、`type`、`filterable`、`sortable`、`displayable`、`operators`。
+- `+employee-filter`：
+  - 默认只展示姓名和工号。
+  - 用户显式要求的展示字段，按用户诉求追加。
+  - 若接口返回 `Count`、`Has more`、`Next page` 等分页信息，答复中必须体现当前已返回多少条，以及是否还能继续查看下一页。
+- 若命令报错、字段不支持、名称解析失败或结果不具备唯一性，必须清楚说明失败类型，禁止编造人数或员工名单。
+
+## Command Patterns
+
+```bash
+# 按姓名、工号、邮箱搜索员工
+people-cli corehr +employee-search --keyword <关键词>
+
+# 查询当前登录员工基本信息
+people-cli corehr +employee-basic-info-query --format json
+
+# 查询员工字段元数据
+people-cli corehr +employee-fields-query --format table
+
+# 默认场景：只返回姓名 + 工号
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.department","operator":"in","value_names":["技术部"],"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","value_names":["技术部"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.employee_number","employment.department","employment.job_level"]' \
+  --format table
+```
+
+## Minimal References
+
+- [people-corehr-employee-search.md](references/people-corehr-employee-search.md)：员工搜索的输入识别、输出字段顺序与基本示例。
+- [people-corehr-employee-basic-info-query.md](references/people-corehr-employee-basic-info-query.md)：当前登录员工基本信息查询与常见联动场景。
+- [people-corehr-employee-fields-list.md](references/people-corehr-employee-fields-list.md)：字段元数据、字段类型、可用操作符与筛选/排序/展示能力判断。
+- [people-corehr-employee-filter.md](references/people-corehr-employee-filter.md)：员工筛选、默认展示字段铁律、`value_names` 解析与分页约束。

package/skills/people-corehr-employee/references/people-corehr-employee-basic-info-query.md

@@ -0,0 +1,97 @@
+# +employee-basic-info-query
+
+查询当前登录员工的基本信息。
+
+## 用法
+
+```bash
+people-cli corehr +employee-basic-info-query [flags]
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--accept-language` | string | 否 | `zh-CN` | 响应语言：`zh-CN`（中文）、`en-US`（英文） |
+
+### accept-language 选择策略
+
+根据用户使用的语言自动选择：
+- 用户使用**中文**时 → 使用 `zh-CN`（默认）
+- 用户使用**英文**时 → 使用 `en-US`
+- 不确定时默认使用 `zh-CN`
+
+## 所需权限
+
+| Scope |
+|-------|
+| `corehr:employment_basic_info_query:read` |
+
+## 输出
+
+| 字段 | 说明 |
+|------|------|
+| `preferred_name` | 员工常用姓名 |
+| `employee_number` | 工号 |
+| `employment_id` | 员工 ID 员工的唯一标识符 |
+| `email` | 邮箱 |
+
+### 输出示例
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": [
+    {
+      "email": "gggLKH@testbytedance.test",
+      "employee_number": "15312",
+      "employment_id": "7332108003012527660",
+      "preferred_name": "李庆举"
+    }
+  ],
+  "meta": {
+    "count": 1
+  }
+}
+```
+
+## 示例
+
+```bash
+# 查询当前员工基本信息
+people-cli corehr +employee-basic-info-query
+
+# 表格格式输出
+people-cli corehr +employee-basic-info-query --format table
+
+# 英文响应
+people-cli corehr +employee-basic-info-query --accept-language en-US
+```
+
+## 常用流程
+
+`+employee-basic-info-query` 主要用于获取当前登录员工的 `employment_id`，作为后续命令的入参：
+
+**查询我的任职记录**
+
+```bash
+# 1. 获取当前用户的 employment_id
+people-cli corehr +employee-basic-info-query --format json
+
+# 2. 用返回的 employment_id 查询任职记录
+people-cli corehr +employee-job-data-query --employment-id <employment_id> --format table
+```
+
+**查询我的下级**
+
+```bash
+# 1. 获取当前用户信息
+people-cli corehr +employee-basic-info-query --format json
+
+# 2. 用返回的 employment_id 作为 values 查询直线下级
+people-cli corehr +employee-filter \
+  --filters '[{"field_api_name":"employment.direct_manager","operator":"in","values":["<employment_id>"],"is_strand_id_in":true}]' \
+  --display-fields '["employment.person.preferred_name","employment.department","employment.job_level"]' \
+  --format table
+```

package/skills/people-corehr-employee/references/people-corehr-employee-fields-list.md

@@ -0,0 +1,87 @@
+# +employee-fields-query
+
+查询员工自定义列设置，返回可用的自定义字段列表及其属性。
+
+## 用法
+
+```bash
+people-cli corehr +employee-fields-query [flags]
+```
+
+## 参数
+
+| Flag | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--accept-language` | string | 否 | `zh-CN` | 响应语言：`zh-CN`（中文）、`en-US`（英文） |
+
+### accept-language 选择策略
+
+根据用户使用的语言自动选择：
+- 用户使用**中文**时 → 使用 `zh-CN`（默认）
+- 用户使用**英文**时 → 使用 `en-US`
+- 不确定时默认使用 `zh-CN`
+
+## 所需权限
+
+| Scope |
+|-------|
+| `corehr:employment_column_list_query:read` |
+
+## 输出
+
+| 字段 | 说明 |
+|------|------|
+| `name` | 字段名称 |
+| `api_name` | 字段 API 标识 |
+| `type` | 字段类型，决定筛选时 `values` 的传值方式和可用操作符，详见下方 type 说明 |
+| `filterable` | 是否可筛选（true 可筛选 / false 不可筛选，仅 `filterable` 为 `true` 的字段才能用于 `--filters`） |
+| `sortable` | 是否可排序（true 可排序 / false 不可排序，仅 `sortable` 为 `true` 的字段才能用于 `--sort-fields`） |
+| `displayable` | 是否可展示（true 可展示 / false 不可展示，仅 `displayable` 为 `true` 的字段才能用于 `--display-fields`） |
+| `operators` | 支持的操作符，与 `type` 配套使用，详见下方 operators 说明 |
+
+### type 字段类型说明
+
+`type` 决定了 `+employee-filter` 筛选时 `values` 的传值方式和可用的 `operators`。
+
+| 类型 | 说明 | 筛选值要求 |
+|------|------|-----------|
+| `input` | 单行文本 | 可直接传文本值 |
+| `text` | 多行文本 | 可直接传文本值 |
+| `number` | 数字 | 可直接传数值 |
+| `date` | 日期 | 可直接传日期值（如 `"2024-01-01"`） |
+| `bool` | 布尔值 | 传 `true` / `false` |
+| `select` | 单选/下拉选择 | **需传选项 ID**，不可直接传文本 |
+| `multiUser` | 多人选择 | **需传用户 ID**，不可直接传姓名 |
+| `position` | 岗位 | **需传岗位 ID**，不可直接传岗位名称 |
+| `lookup` | 关联引用 | **需传关联记录 ID** |
+| `attachment` | 附件 | **需传附件 ID** |
+| `hyperlink` | 超链接 | 可直接传 URL 文本 |
+| `phone` | 电话号码 | 可直接传电话号码文本 |
+| `email` | 邮箱 | 可直接传邮箱地址文本 |
+
+> **关键规则**：`select`、`multiUser`、`position`、`lookup`、`attachment` 等引用类型字段，`values` 必须传对应的 ID，不能传显示文本。每种类型可用的操作符以接口返回的 `operators` 字段为准。
+
+### operators 操作符说明
+
+| 操作符 | 说明 |
+|--------|------|
+| `in` | 包含 |
+| `not_in` | 不包含 |
+| `eq` | 等于 |
+| `ne` | 不等于 |
+| `gt` | 大于 |
+| `gte` | 大于等于 |
+| `lt` | 小于 |
+| `lte` | 小于等于 |
+| `is_blank` | 为空 |
+| `not_blank` | 不为空 |
+
+## 示例
+
+```bash
+# 查询自定义列设置
+people-cli corehr +employee-fields-query
+
+# 表格格式输出
+people-cli corehr +employee-fields-query --format table
+```