@lark-people/cli 0.0.3 → 0.0.4-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-people/cli",
-  "version": "0.0.3",
+  "version": "0.0.4-beta.3",
   "description": "The official CLI for People open platform",
   "bin": {
     "people-cli": "scripts/run.js"

package/scripts/install-wizard.js

@@ -476,19 +476,37 @@ function listBundledSkills(skillsDir = DEFAULT_SKILLS_DIR) {
     return [];
   }
 
-  return fs
+  const skillsByName = new Map();
+  const addSkill = (name, dir) => {
+    if (EXCLUDED_BUNDLED_SKILLS.has(name)) {
+      return;
+    }
+    const skillFile = path.join(dir, "SKILL.md");
+    if (!fs.existsSync(skillFile)) {
+      return;
+    }
+    skillsByName.set(name, { name, dir, skillFile });
+  };
+
+  fs
     .readdirSync(skillsDir, { withFileTypes: true })
     .filter(entry => entry.isDirectory())
-    .map(entry => {
+    .forEach(entry => {
       const dir = path.join(skillsDir, entry.name);
-      return {
-        name: entry.name,
-        dir,
-        skillFile: path.join(dir, "SKILL.md"),
-      };
-    })
-    .filter(skill => !EXCLUDED_BUNDLED_SKILLS.has(skill.name))
-    .filter(skill => fs.existsSync(skill.skillFile))
+      addSkill(entry.name, dir);
+    });
+
+  const embeddedRoot = path.join(skillsDir, "people-cli", "references");
+  if (fs.existsSync(embeddedRoot)) {
+    fs
+      .readdirSync(embeddedRoot, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .forEach(entry => {
+        addSkill(entry.name, path.join(embeddedRoot, entry.name));
+      });
+  }
+
+  return Array.from(skillsByName.values())
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 

package/skills/people-cli/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: people-cli
+version: 1.0.0
+description: "当用户需要通过 people-cli/People CLI 处理飞书人事或招聘数据时使用；覆盖 CoreHR 员工、部门组织、待入职、异动、离职、续约/续签、编制/HC，以及 Hire 职位、招需、投递、候选人、面试、评估、人才查询；也适用于 CLI 安装、升级、登录授权、Permission denied 和 scope 权限问题。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli --help"
+---
+
+# People CLI
+
+飞书 People 全能套件，通过 `people-cli` 命令行工具查询飞书人事、CoreHR 和招聘数据。
+
+主入口只做标准化前置检查、用户身份合规约束和业务域分发。下方 Step 5 是路由表：判断用户意图属于哪个业务域，然后读取该域对应的嵌入子 Skill，再按子 Skill 的参数规范构造命令。重点关注：
+1. 嵌入子 Skill 要求继续加载 reference 时，必须加载该子 Skill 自己目录下的 reference。
+2. 严禁凭路由表描述或自身记忆猜测参数、字段、分页、元数据校准或输出格式。
+
+## ⚠️ 标准执行流程 - 使用任何业务命令前必须执行
+
+### Step 1: 检查 CLI 是否安装和可用
+
+先执行：
+
+```bash
+people-cli --version
+```
+
+如果命令不存在、报错或没有有效版本输出，执行安装：
+
+```bash
+npx @lark-people/cli install
+```
+
+安装流程会安装 `people-cli` 二进制命令、People 官方 Skills，并引导配置飞书应用和用户授权。安装完成后必须重新执行 `people-cli --version`；仍失败时停止业务操作并把错误告知用户。
+
+如 npm registry 导致无法安装，可先执行：
+
+```bash
+npm config set registry https://registry.npmjs.org
+npx @lark-people/cli install
+```
+
+### Step 2: 检查版本并处理更新
+
+检查是否有更新：
+
+```bash
+people-cli update --check
+```
+
+如果提示有新版本，或任意 `people-cli` JSON 输出中包含 `_notice.update` / `_notice.skills`，执行：
+
+```bash
+people-cli update
+```
+
+更新完成后重新执行 `people-cli --version`。如果更新同步了 Skills，提醒用户退出并重新打开 AI Agent，让新 Skills 生效。
+
+### Step 3: 检查用户身份和授权
+
+执行：
+
+```bash
+people-cli auth status --verify
+```
+
+只有确认用户身份可用后，才能继续业务命令。判断规则：
+
+- 输出 `identity=user`，且没有 token 不存在、过期或 server rejected 等错误：继续。
+- 未配置应用：执行 `people-cli config init --new`，把命令输出的配置链接原样发给用户，等待用户完成。
+- 未登录、token 不存在、token 过期或服务端拒绝：先根据业务域执行用户授权。
+
+用户授权命令必须指定范围：
+
+```bash
+people-cli auth login --domain corehr
+people-cli auth login --domain hire
+people-cli auth login --scope "<missing_scope>"
+```
+
+优先使用错误中的缺失 scope 做最小权限授权；不知道具体 scope 但已确定业务域时，才用 `--domain`。授权链接必须原样转发给用户，不要改写、解码、截断或补全。
+
+### Step 4: 严禁 bot 身份
+
+People CLI 在本 Skill 体系中只能使用用户身份。
+
+- 业务命令必须使用或保持 `--as user`。
+- 严禁使用 `--as bot`。
+- 严禁建议用户申请 bot scope、配置 bot 权限或切换到应用身份来解决业务查询失败。
+- 如果命令输出显示 `[identity: bot]` 或等价信息，立即停止业务操作，改用用户身份重新处理。
+- Permission denied 只能按用户身份补授权；不能切换到 bot。
+
+### Step 5: 根据用户 query 确认实际业务域
+
+必须先根据用户本次 query 选择一个业务域，再读取对应子 Skill 的 `SKILL.md`；不要在主入口里拼业务命令。
+
+#### 👤 员工信息查询 (employee)
+
+搜索员工、查询当前登录员工基本信息、查询员工可筛选字段、按条件筛选员工。适用于员工搜索、按姓名找人、查我自己、员工列表、部门员工、职级员工、员工字段、`employee search`、`employee filter`。不覆盖待入职、异动、离职、任职历史、审批、导出。
+
+→ 详见 [people-corehr-employee](references/people-corehr-employee/SKILL.md)
+
+#### 🔁 异动管理 (job-change)
+
+搜索员工异动记录、按员工/部门/状态/时间/异动类型/异动原因筛选异动、获取异动筛选项与字段信息。适用于异动、调动、转岗、晋升、异动查询、异动记录、人员异动、`job change`。不覆盖离职、编制、员工信息、审批操作、数据导出。
+
+→ 详见 [people-corehr-job-change](references/people-corehr-job-change/SKILL.md)
+
+#### 🚪 离职查询 (offboarding)
+
+查询授权范围内离职单与可筛选档案字段。适用于离职/offboarding、期望离职/申请/发起/流转日期、申请/审批/流转/交接/合同状态、离职原因/标注、部门离职人员、任职公司/合同主体/工作地点/职务/序列/职级/职等、竞业启动、司龄等离职相关筛选。
+
+→ 详见 [people-corehr-offboarding](references/people-corehr-offboarding/SKILL.md)
+
+#### 🏢 组织查询 (organization)
+
+查询 CoreHR 部门、成本中心或自定义组织的字段、节点、上下级关系、组织树或聚合。仅当组织本身是查询对象时走这里；如果部门只是离职、异动、续约、编制、员工筛选条件，走对应业务域。
+
+→ 详见 [people-corehr-organization](references/people-corehr-organization/SKILL.md)
+
+#### 🧾 待入职查询 (prehire)
+
+查询 CoreHR 待入职数据。适用于待入职、入职前、pre-hire、onboarding candidate、入职阶段、预入职筛选字段。招聘候选人、投递、面试、评估走招聘域；已入职员工信息走员工域。
+
+→ 详见 [people-corehr-prehire](references/people-corehr-prehire/SKILL.md)
+
+#### 🧭 名称换 ID (query-id-by-name)
+
+把 CoreHR 对象名称解析为下游业务命令需要的 ID，例如部门、地点、职级、序列等。通常不是用户业务查询的主入口，只在用户明确要求名称换 ID，或选定的业务子 Skill 明确需要先解析 ID 时使用。
+
+→ 详见 [people-corehr-query-id-by-name](references/people-corehr-query-id-by-name/SKILL.md)
+
+#### 📄 续约/续签 (renewal)
+
+查询续约/续签记录与字段，覆盖合同到期名单、续约状态与流程进展、签署状态、续延、原合同与续签后合同对比、异常冲突排查、数量与分布统计。用户提到续约、续签、不续签、续延、合同到期、合同快到期、到期名单、签署状态、续签评估、`renewal` 时走这里。
+
+→ 详见 [people-corehr-renewal](references/people-corehr-renewal/SKILL.md)
+
+#### 📊 编制规划 (workforce-plan)
+
+查询 CoreHR 编制规划：编制方案、当前生效方案、编制 HC、在职人数、预增、预减、缺编数、满编率、编制汇总、维度分组、Top N、编制明细和原始行数据。普通员工人数走员工；涉及计划、预算、HC 口径才走这里。
+
+→ 详见 [people-corehr-workforce-plan](references/people-corehr-workforce-plan/SKILL.md)
+
+#### 🎯 招聘查询 (hire)
+
+查询飞书招聘数据，包括职位、招聘需求/招需、投递、面试、评估、人才、招聘流程与进度。CoreHR 待入职信息走待入职域；已入职员工信息走员工域。
+
+→ 详见 [people-hire](references/people-hire/SKILL.md)
+
+#### 特殊说明
+
+- 优先使用用户明确说出的业务词：续约、异动、离职、编制、待入职、招聘、组织、员工。
+- 如果两个业务域都会查不同数据源且无法判断，问一个简短澄清问题。
+- 每次用户新的 query 都要重新判断业务域，不能沿用上一轮路由。
+- 子 Skill 的命令结构互不通用。不能把 A Skill 的命令、字段、分页、search-option、schema 或元数据流程套到 B Skill。
+- 选定业务域后读取对应子 Skill 的 `SKILL.md`，再按该子 Skill 执行。如果对应子 Skill 不可用，停止并说明缺失，不要自行拼接命令。
+- 读取嵌入子 Skill 后，子 Skill 内的相对 reference 路径必须以该子 Skill 的 `SKILL.md` 所在目录为基准解析。例如 `references/foo.md` 应解析为 `references/<child-skill>/references/foo.md`，不是主 Skill 的 `references/foo.md`。
+- 嵌入子 Skill 要求读取 reference 时，必须读取该子 Skill 自己的 reference 文件。例如 `people-corehr-employee/SKILL.md` 中的 `references/people-corehr-employee-search.md` 必须解析到 `people-corehr-employee/references/people-corehr-employee-search.md`。
+
+## 输出约束
+
+- 禁止输出 appSecret、access token、refresh token、authorization header 或本地凭证内容。
+- 默认不向用户暴露内部 ID，例如 employee_id、department_id、job_id、application_id、talent_id、cursor、next_cursor；优先展示姓名、部门名、职位名、状态、日期、数量和可读链接。
+- 如果 CLI 返回 `log_id`，可以保留用于排障。
+- 写入、更新、删除、提交申请或发起流程前必须向用户确认关键字段；能 dry-run 时先 dry-run。
+- 工具、登录、授权、权限或网络失败时，如实说明失败类型和下一步动作，不编造 People 数据。
+
+## 不覆盖
+
+- 本阶段不从主入口路由到出勤、加班或其他未列出的 People Skill。
+- 不处理薪酬、身份证、银行账户、完整档案、跨部门/全公司导出、绕过审批或绕过授权的请求。