@lark-people/cli 0.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,324 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.0.1]
+
+商业化首发版本（commercial first release）。仅分发预编译二进制、`skills/` 目录与安装脚本，源代码不随包投递。
+
+### Changed
+
+- 元数据下发切换至公网网关，不再依赖内网地址。
+- Token 仅存储于系统钥匙串（keychain），移除工作目录明文落盘模式。
+- 配置仅识别全局 `~/.people-cli/` 目录，不再探测当前工作目录。
+
+### Removed
+
+- 移除内部沙箱鉴权集成与相关提示。
+- 移除内部运维命令（环境泳道、预发/BOE 主机覆盖、UAT 覆盖）。
+- 移除内部打点上报与数据导出管控逻辑。
+
+## [v1.0.11] - 2026-04-29
+
+### Features
+
+- **Hire 招聘域全面重构（Skill v2.0.0）**：从"面试 + 评估"两个查询场景扩展为 **8 大招聘查询场景**（评估任务、面试任务、招聘需求、职位、人才、投递、面试记录、评估记录）
+  - `skills/people-hire/SKILL.md` 重写（+282/-x），明确触发条件、禁用场景、字段来源（以 `people-cli schema hire.<resource>.<method>` 为准）
+  - 旧 reference 移除：`evaluation-task-list.md`、`interview-task-list.md`
+  - 新增 8 份按场景组织的 reference（均位于 `skills/people-hire/references/`）：
+    - `skills/people-hire/references/people-hire-application.md`（投递，+104）
+    - `skills/people-hire/references/people-hire-evaluation.md`（评估记录，+105）
+    - `skills/people-hire/references/people-hire-evaluation-task-list.md`（评估任务，+301）
+    - `skills/people-hire/references/people-hire-interview.md`（面试记录，+110）
+    - `skills/people-hire/references/people-hire-interview-task-list.md`（面试任务，+306）
+    - `skills/people-hire/references/people-hire-job.md`（职位，+185）
+    - `skills/people-hire/references/people-hire-job-requirement.md`（招聘需求，+137）
+    - `skills/people-hire/references/people-hire-talent.md`（人才，+92）
+  - `shortcuts/hire/helpers.go` 扩展（+181）支撑新场景
+- **QueryIDByName 重构为可复用公共能力**：从 shortcut 内聚功能提升为 `shortcuts/corehr/common` 包的公共 API
+  - 路径迁移（`git mv`，相似度 65%）：`shortcuts/corehr/query_id_by_name.go` → `shortcuts/corehr/common/query_id_by_name.go`
+  - 新增 `shortcuts/corehr/common/model.go` +86：对外暴露 `QueryRequest` / `QueryIDByNameInput` / `QueryIDByNameMatch` / `QueryIDByNameItem` 等模型，供 `job_change_search` / `offboarding_search` / `employee_search` 等 shortcut 批量并发查询 ID 使用
+  - 新增 `Language` 字段：支持 `zh-CN` / `en-US`，可自动检测或显式指定（name-to-id by language）
+
+### Security / Safety
+
+- **强约束：只能查询当前登录用户数据**：
+  - `skills/people-attendance/SKILL.md` 对"假期余额 / 请假记录 / 加班记录"三类场景增加 **"不支持查询其他人 / 只支持查询当前登录账号本人"** 的强提示
+  - Hire SKILL 同步强约束：`+interview-task-list` / `+evaluation-task-list` 禁止传入 `user_id` 等参数
+- **拒绝 leave 的 create / update / delete 操作**：Attendance Skill 明确只支持查询场景，遇到"提交 / 修改 / 删除 / 撤销请假"或"修改 / 更新 / 删除假期余额"等请求直接返回"不支持"，杜绝越权写操作路径
+
+### Changed
+
+- **Attendance 查询约束与示例扩写**：
+  - 加班查询：仅支持 2022-01-01 之后的数据；**仅按加班日期筛选**，不支持按发起/创建/更新时间；审批中/待审批通过数据暂不支持
+  - 假期余额查询 `--as-of-date` 日期必须为 `YYYY-MM-DD`（`YYYYMMDD` 会被拒），新增时区支持场景（如 `--time-zone=GMT-5`）与自然语言日期映射（"明年 / 国庆节 / 年底" 等）
+  - 请假记录状态枚举重写：`1=已通过`、`2=审批中`、`3=审批中(更正)`、`4=审批中(取消休假)`、`5=审批中(返岗)`、`8=已取消` 等更精细的状态分层
+- **CoreHR Skill references 大面积打磨**：
+  - `skills/people-corehr/references/people-corehr-job-change-search.md` 重写（+452/-?）
+  - `skills/people-corehr/references/people-corehr-offboarding-search.md` 精简重写（+271/-?）
+  - `skills/people-corehr/references/people-corehr-workforce-plan-detail-list.md` / `skills/people-corehr/references/people-corehr-workforce-plan-detail-summary.md` / `skills/people-corehr/references/people-corehr-workforce-plan.md` 全量刷新
+  - `employee-filter` / `employee` / `pre-hire-search` / `query-id-by-name` / `concepts` 同步调整，命令样例与字段语义统一
+  - 新增占位文件 `references/search-pre_hire.md`（预留后续合并）
+
+### Fixed
+
+- **`job_change_search` 命中 `query-id-by-name` 的逻辑修复**（多次 commit：`fix: fix job_change search skill query-id-by-name`、`fix: fix job_change search skill`）
+- **请假记录状态筛选兼容**：`feat: 兼容审批中的请假记录查询场景`、`feat: 兼容已通过的请假记录查询场景`
+- **CoreHR name-to-id 按语言自动切换**：`feat: name to id by language` / `feat: name to id params`
+- **过度简化回滚**：`Revert "feat: simplify offboarding search skills"`，恢复更完整的 offboarding 搜索能力
+
+### Technical
+
+- `shortcuts/register.go` / `shortcuts/corehr/shortcuts.go` 跟随 `common` 子包拆分调整注册
+- 统计：`38 files changed, 3148 insertions(+), 1081 deletions(-)`
+
+> 升级提示：
+> 1. 如果你之前基于 `shortcuts/corehr/query_id_by_name.go` 的内部符号做二次开发，现在应从 `shortcuts/corehr/common` 包 import。
+> 2. 请假记录状态枚举发生了变化（尤其是 `2=审批中` 与早期的 `2=已通过`），脚本/Skill 中硬编码状态值的场景请对照新表调整。
+> 3. 假期余额 `--as-of-date` 的日期格式由 `YYYYMMDD` 统一收紧为 `YYYY-MM-DD`。
+
+## [v1.0.10] - 2026-04-28
+
+### Security
+
+- **UAT 迁移至 OS 钥匙串**：`set_uat` / `clear_uat` 由"本地文件存储"改为"OS Keychain 存储"，配套 help 文案与错误提示同步更新
+  - `cmd/uat.go`：`Short` 描述改为 `Store/Clear UAT in/from OS keychain`，成功/失败提示改为 `UAT stored in OS keychain` / `UAT cleared from keychain`
+  - `internal/core/config.go`：`ResolveUATOverride` 的 source 从 `"file"` 更名为 `"keychain"`，新增 `manualUATAccount = "manual-uat:override"` 与 OAuth 账号区分
+- **`GetConfigDir` 越权/世界可写目录加固**：新增 `validateConfigDir`，对 `LARKSUITE_CLI_CONFIG_DIR` 做安全校验
+  - 拦截 `/proc`、`/sys`、`/dev` 等系统关键路径，出现即 fallback 回 `~/.people-cli` 并 stderr 告警
+  - 对 world-writable（权限位含 `0002`）目录给出"凭据可能泄露"警告（仍允许使用）
+- **Debug Transport 凭据脱敏增强**：`internal/cmdutil/debug_transport.go` 重写 `sanitizeTokenFields`
+  - 支持 `application/x-www-form-urlencoded` 形式的请求体：通过 `looksLikeFormURLEncoded` 启发式识别，识别后**整体替换 value 为 `***`**，防止 OAuth `client_secret` / `code` / `refresh_token` 意外打印
+  - 保留原 JSON 路径：继续按 key 黑名单做字段级脱敏
+  - `debug_transport_test.go` 同步重构（-151/+x）
+- **其他安全修复**：`.gitignore` 扩展 `*.zip` 与 `dist/*.zip`，避免本地打包产物被误提交；`internal/registry/remote.go` 相关安全点位调整
+
+### Features
+
+- **Skill 打包工具链（全新）**：交付可上架的 Skill zip 包生成链路
+  - `scripts/pack-skills.sh` +216：把 `skills/` 下每个业务 Skill 打包成 `dist/<skill-name>.zip`，支持 `--list` / `--dry-run` / 指定 Skill；在打包时会把 `people-shared/SKILL.md` 嵌入到各业务 Skill 的 `references/people-shared.md`
+  - `scripts/rewrite_shared_refs.py` +121：重写所有 `.md` 中对 `people-shared` 的引用路径（`SKILL.md` → `references/people-shared.md`；`references/*.md` → `people-shared.md`），并提供残留检测
+- **CoreHR Workforce Plan Detail List 新增**：新增 reference `skills/people-corehr/references/people-corehr-workforce-plan-detail-list.md` +233，配套 `skills/people-corehr/references/people-corehr-workforce-plan.md` 补充说明
+- **终端控制字符防御**：复用并扩充 `shortcuts/common/sanitize.go`（+39）
+  - 新增 `IsDangerousUnicode`：覆盖 ZWSP / ZWJ / ZWNJ / BOM、BiDi override（LRE/RLE/PDF/LRO/RLO/LRI/RLI/FSI/PDI）、LS / PS 等
+  - `SanitizeForPretty` / `SanitizeValueForPretty`：在 pretty 输出前递归清洗 string / []string / []interface{} / map[string]interface{}，**修复 `leave_request_history` pretty 模式未过滤终端控制字符的问题**
+
+### Fixed
+
+- **Leave Duration Unit 解析**：修复 `leave duration unit` 字段因 API 返回 `int` / `float64` 两种类型导致的解析失败（`shortcuts/attendance/leave_balances.go` +153、`shortcuts/attendance/leave_request_history.go` +285 大幅重构）
+- **请假记录状态枚举优化**：`leave_request_status` 枚举/展示更统一，新增提交时间范围约束与字段精简
+- **加班记录文档修正**：`skills/people-attendance/references/people-attendance-overtime.md` 同步更新
+
+### Changed
+
+- **CoreHR Skill references 大面积打磨**：`employee-filter` / `employee-search` / `employee-job-data-detail-query` / `employee-fields-list` / `job-change-search` / `offboarding-search` / `pre-hire-search` / `workforce-plan` 全量重审，命令样例与字段语义更一致
+- **Attendance Skill 主文档**：`skills/people-attendance/SKILL.md` +42，补充假勤能力说明
+- `shortcuts/corehr/pre_hire/pre_hire_search.go` 微调以契合 reference 规范
+
+### Technical
+
+- `go.mod` 依赖轻量更新
+- 统计：`29 files changed, 1433 insertions(+), 531 deletions(-)`
+
+> 升级提示：若之前依赖 `set_uat` 把 token 写到本地文件，升级到 1.0.10 后会改写入 OS Keychain；在 headless/无 keychain 环境（如部分 Linux CI）请确认依赖路径。
+
+## [v1.0.9] - 2026-04-28
+
+### Changed (Breaking)
+
+- **Leave 能力域归属调整：`corehr` → `attendance`**。假期余额与请假记录两个 Shortcut 从 CoreHR 迁移到 Attendance 域，业务归属更贴合"考勤/假期"场景。
+  - Shortcut 调用路径变化：
+    - `people-cli corehr +leave-balances` → `people-cli attendance +leave-balances`
+    - `people-cli corehr +leave-request-history` → `people-cli attendance +leave-request-history`
+  - 代码搬迁（`git mv`，保留 99% 相似度）：
+    - `shortcuts/corehr/leave_balances.go` → `shortcuts/attendance/leave_balances.go`
+    - `shortcuts/corehr/leave_request_history.go` → `shortcuts/attendance/leave_request_history.go`
+  - 文档随迁（相似度 92%）：
+    - `skills/people-corehr/references/people-corehr-leave-balances.md` → `skills/people-attendance/references/people-attendance-leave-balances.md`
+    - `skills/people-corehr/references/people-corehr-leave-request-history.md` → `skills/people-attendance/references/people-attendance-leave-request-history.md`
+  - 注册入口：新增 `shortcuts/attendance/shortcuts.go`，并在 `shortcuts/register.go` 接入；`shortcuts/corehr/shortcuts.go` 同步移除 `LeaveBalances` / `LeaveRequestHistory` 注册项
+  - README（中英）同步更新示例命令，把 `corehr +leave-balances` 改为 `attendance +leave-balances`
+
+### Features
+
+- **`people-attendance` Skill 大幅升级至 `v1.1.0`**：
+  - description 扩写：明确覆盖"加班、请假、休假、假期余额、年假、病假、调休"等关键词，保证 AI 路由更准确命中
+  - 场景示例 3 类：加班记录、假期余额（含 `--as-of-date` / `--include-offboard` / `--include-subtype`）、休假记录（含 `--leave-request-status` / `--leave-submit-date-min` / `--leave-type-id`）
+  - 新增"命令速查"表与"参考文档"索引，引导用户优先走 reference 文档
+- **加班记录返回值说明补强**：`people-attendance-overtime.md` 增加返回字段表，明确 `duration` / `unit`（1=天, 2=小时, 3=半天, 4=半小时）/ `start_time` / `end_time` 的语义，禁止用 `start_time - end_time` 计算时长
+
+### Technical
+
+- `shortcuts/corehr/shortcuts.go` 中 `LeaveBalances` / `LeaveRequestHistory` 两项引用清理
+- `shortcuts/register.go` 新增 `attendance` 域注册
+
+> 迁移提示：如果你的脚本或 SKILL 里硬编码了 `corehr +leave-balances` / `corehr +leave-request-history`，升级到 1.0.9 后需要替换为 `attendance +leave-balances` / `attendance +leave-request-history`。
+
+## [v1.0.8] - 2026-04-27
+
+### Features
+
+- **Hire 招聘域（全新）**：引入独立的 `people-hire` Skill 与顶层 `shortcuts/hire/*`，打通招聘面试 / 评估场景
+  - 新增 Shortcut：`+interview-task-list`（面试任务列表）、`+evaluation-task-list`（评估任务列表）
+  - 配套新增 `skills/people-hire/SKILL.md` 与 references：`skills/people-hire/references/interview-task-list.md` / `skills/people-hire/references/evaluation-task-list.md`
+  - 新增 `skill-template/domains/hire.md`，统一招聘域 skill 模板入口
+- **Attendance 加班查询文档化**：抽离 `references/people-attendance-overtime.md`，把参数规则、scope、分段查询等细节从 `SKILL.md` 里剥离到 reference，主文档更精简
+- **CoreHR 员工检索业务化重构**：`shortcuts/corehr/employee/employee_list.go` 大幅增强（+128 行），对接 `offboarding` / `job_change` / `employee-filter` 等业务场景；references 同步刷新：
+  - `skills/people-corehr/references/people-corehr-employee-filter.md`：扩展筛选字段与说明（+111）
+  - `skills/people-corehr/references/people-corehr-offboarding-search.md` / `skills/people-corehr/references/people-corehr-job-change-search.md`：大幅重写，参数说明和约束更清晰
+
+### Security
+
+- **`env --header_key` 屏蔽敏感 HTTP Header**：新增 `blockedHeaderKeys` 黑名单，禁止用户通过 `--header_key` 覆盖 `Authorization`、`Cookie`、`Set-Cookie`、`Host`、`Proxy-Authorization`、`WWW-Authenticate`、`X-Lark-Mcp-Uat`、`X-Lark-Mcp-Tat` 等安全敏感头，阻断凭据注入 / 请求劫持风险；命令 help 文案同步提示
+- **Debug Transport 安全增强**：`internal/cmdutil/debug_transport.go` 重写（+74/-x），新增单测 `debug_transport_test.go`（+66）与 `factory_default_test.go`（+64），修复 debug/header 相关安全风险
+
+### Changed
+
+- **README 重新定位**：`README.md` / `README.zh.md` 全面刷新，聚焦 People 业务域（CoreHR / Attendance / Hire）定位与能力描述
+- **shortcuts 目录结构扁平化**：删除中间层 `shortcuts/corehr/employee/shortcuts.go`、`shortcuts/corehr/pre_hire/shortcuts.go`，由 `shortcuts/corehr/shortcuts.go` 与 `shortcuts/register.go` 统一注册；`query_id_by_name.go` references 同步微调
+
+### Chore
+
+- **仓库清理**：删除历史备份与无用产物，合计约 **58,460 行删除**
+  - `people-cli.backup.20260405_185850` 本地二进制备份
+  - `skills/people-corehr.zip` 冗余压缩包（改由 `.gitignore` 忽略）
+  - `.backup/shortcuts_removed/` 下 base / task / vc / whiteboard / skill-template 等历史模块的遗留文件
+- `go.mod` 依赖微调
+
+### Technical
+
+- 新增测试：`internal/cmdutil/factory_default_test.go`、`internal/cmdutil/debug_transport_test.go`
+- `internal/core/config.go` / `internal/core/types.go` 扩展以配合 env header 的安全校验
+
+## [v1.0.7] - 2026-04-24
+
+### Features
+
+- **CoreHR 假期能力**：新增两个 Shortcut，打通"查余额 → 看记录"的完整链路
+  - `+leave-balances`：按员工查询假期余额，支持 `as_of_date`（截止日期，用于"月底还剩多少"场景）、`include_offboard`（离职折算）、`leave_duration_unit`（天 / 小时）、分页参数等，返回周期授予、已休、历史结转、审批中等多维度额度
+  - `+leave-request-history`：按员工查询请假记录，支持按状态（`leave_request_status`）、提交时间区间（`leave_submit_date_min/max`）、假期类型（`leave_type_id`）等维度过滤
+  - 新增对应 references 文档：`skills/people-corehr/references/people-corehr-leave-balances.md` / `skills/people-corehr/references/people-corehr-leave-request-history.md`
+- **Attendance 加班审批查询**：`people-attendance` Skill 明确支持"加班审批记录"场景，补充 `check_date_from` / `check_date_to` / `status` 参数说明与跨 30 天分段查询规则；所需 scope 更新为 `attendance:over_time:read`
+- **Pre-Hire 命令顶层化**：将 `shortcuts/corehr/pre_hire/*` 提升为独立的顶层 `shortcuts/pre_hire/*`，在 `shortcuts/register.go` 单独注册，结构更清晰
+- **Skill 说明补强**：`people-corehr` SKILL 新增"假期类型 / 假期余额 / 请假记录"三类核心概念，并补齐场景示例与查询要点
+
+### Changed
+
+- **Name → ID Shortcut 精简重构**：`shortcuts/corehr/query_id_by_name.go` 由 318 行精简至更小规模（净 -123 行），参数与输出形态调整，references 同步更新
+- **Pre-Hire Search 文档更新**：`references/search-pre_hire.md` 内容随命令路径迁移同步调整
+- **Extract 工具增强**：`shortcuts/common/extract.go` 扩展字段提取逻辑，服务于新增的假期相关 Shortcut
+
+### Technical
+
+- 新增单测覆盖：`shortcuts/pre_hire/pre_hire_search_test.go`
+- `shortcuts/register.go` 注册新的 `pre_hire` 顶层 shortcuts 分组
+
+## [v1.0.6] - 2026-04-23
+
+### Features
+
+- **Pre Host 环境支持**：新增 `people-cli pre-host` 命令与配置项，支持在预发环境与生产环境之间切换（OAuth 设备流、UAT Client、MCP Client 统一适配）
+- **CoreHR Name → ID 快捷命令**：新增 `shortcuts/corehr/query_id_by_name.go`，支持通过名称查询部门、员工、职级、职务等实体 ID，覆盖更完整的场景与参数
+- **Employee / Pre-Hire 快捷命令族**：
+  - 员工：`employee_list`、`employee_search`、`employee_basic_user_info`、`employee_job_data`、`employee_custom_column_settings`、`employee_perm_check`
+  - 待入职：`pre_hire_search` 及配套测试
+- **Workforce Plan 明细汇总**：新增 `workforce_plan_detail_summary` 快捷命令与完整测试集
+- **自定义请求 Header**：`env` 命令支持 `--header-key`，并在 Transport 层透传业务自定义头（含新增测试覆盖）
+- **Skill 文档增强**：补齐 `people-corehr` / `people-attendance` 技能说明与多份 references（基础信息、自定义列、员工列表、待入职搜索、Name→ID 查询、Workforce Plan 等）
+
+### Changed
+
+- **移除 `meta_data_url` 配置**：清理 `cmd/root.go`、`internal/registry` 中不再使用的元数据 URL 逻辑，收敛配置复杂度
+- Name→ID shortcut 重构，入参、输出格式与文档说明全面更新
+
+### Technical
+
+- 扩展 `internal/core/config.go`、`internal/core/types.go` 以承载 Pre Host 与 Header 配置
+- 新增 `env_header_transport_test.go` / `env_test.go` 等测试，保证 header 透传链路可回归
+
+## [v1.0.5] - 2026-04-16
+
+### Changed
+
+- **npm 包名调整**：发布包名从 `@larksuite/cli` 正式切换为 `@people/people-cli`，配套 `publishConfig.registry` 指向 `https://bnpm.byted.org`
+- **自动更新能力**：
+  - 新增 `disable_auto_update` 配置开关，允许在企业环境关闭自动更新
+  - 新增 `force update`、`env check` 相关能力，强化升级链路与环境诊断
+- **调试增强**：补充 debug 日志开关，便于排查 npm 安装与升级问题
+
+### Technical
+
+- 调整版本检查位置，避免重复触发
+- `.gitignore` 忽略 `package-lock.json`，统一发布产物
+
+## [v1.0.4] - 2026-04-14
+
+### Features
+
+- **上传能力**：新增 `upload shortcuts` 相关脚本，支撑发布流水线上传产物
+
+### Technical
+
+- npm 发布流程联调：多次 `feat: add test npm` 版本验证发布链路（1.0.3 / 1.0.4）
+
+## [v1.0.3] - 2026-04-14
+
+### Technical
+
+- npm 发布测试版本，验证 `push_beta.sh` 等脚本
+
+## [v1.0.2] - 2026-04-14
+
+### Features
+
+- **发布脚本**：新增 `publish.sh`，支持一键发布至内部 npm 镜像
+
+## [v1.0.1] - 2026-04-14
+
+### Features
+
+- **身份体系完善**：`cmdutil.factory` 支持更丰富的身份装配路径，便于 CI/机器人场景接入
+- **品牌切换**：项目命名与二进制从 `lark-cli` 切换为 `people-cli`，CLI 子命令、帮助文案、配置路径、keychain 命名全部同步更新
+- **People Metadata 支持**：`scripts/fetch_meta.py` 改造为拉取 People 平台元数据
+- **Skills 体系引入**：新增 `skill-template/`、`skills/people-corehr/`、`skills/people-shared/`、`skills/people-skill-maker/` 目录与模板，统一技能制作流程
+- **Mesh 支持**：元数据抓取脚本适配 Mesh 环境
+
+### Technical
+
+- `Makefile` 与 `build.sh` 适配新的构建/发布路径
+- `internal/core/config.go` 扩展配置字段以支撑新身份类型
+- `scripts/install.js` 精简安装流程
+- 大量重命名：`lark-cli` → `people-cli`（命令名、帮助文本、CI、skill 模板、e2e 测试等）
+
+## [v1.0.0] - 2026-04-05
+
+### Initial Release
+
+People CoreHR CLI — 飞书人事管理命令行工具
+
+### Features
+
+- **部门管理**：搜索、批量获取、列表查询、更新、树形结构查看
+- **CoreHR v2 API**：完整支持飞书人事部门和组织架构接口
+- **认证授权**：OAuth 2.0 设备流认证，支持用户和机器人身份
+- **配置管理**：应用配置、默认身份设置、多租户支持
+- **健康检查**：配置验证、令牌状态、API 连通性检查
+- **多种输出格式**：JSON、表格、CSV、NDJSON 等
+- **分页支持**：自动分页、分页大小控制、延迟控制
+
+### Removed
+
+- 移除非 CoreHR 业务模块（calendar, drive, im, mail, task, vc 等）
+- 专注于人事管理和组织架构查询
+
+### Documentation
+
+- 完整的命令行帮助文档
+- API 参数和类型查询（`schema` 命令）
+- 通用 API 调用接口（`api` 命令）
+
+### Technical
+
+- 基于 people-cli v1.0.4 进行精简和定制
+- 只保留 CoreHR 相关功能和基础能力
+- 编译后二进制大小约 10MB

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lark Technologies Pte. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# people-cli
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
+
+[中文](./README.zh.md) | [English](./README.md)
+
+The official CLI for Feishu People domain workflows. `people-cli` currently covers CoreHR, Attendance, and Hire APIs, and also provides a small set of workflow helper shortcuts such as Drive upload/download.
+
+[Install](#installation--quick-start) · [Auth](#authentication) · [Commands](#command-system) · [Advanced](#advanced-usage) · [Contributing](#contributing)
+
+## Why people-cli?
+
+- **Built for People domains** — one CLI for CoreHR, Attendance, Hire, and adjacent workflow helpers
+- **Shortcut-first, API-complete** — use high-level shortcuts for common tasks, or drop down to generated service commands and raw APIs when needed
+- **AI-friendly output** — structured output and stable command shapes work well for agents and automation
+- **Quick to adopt** — guided config, domain-based auth, and schema introspection shorten time to first successful call
+- **Secure by default** — injected input protection, filtered terminal output, and system keychain credential storage
+- **Open source** — MIT licensed and ready for local development or automation use
+
+## Features
+
+| Category | Capabilities |
+| --- | --- |
+| `corehr` | Department lookup, employee search, basic info, job data, pre-hire search, leave balances/history, workforce planning, name-to-ID shortcuts |
+| `attendance` | Attendance approval and overtime approval queries |
+| `hire` | Hiring data access for jobs, applications, interviews, evaluations, and talent resources |
+| Helpers | Drive file upload/download shortcuts for surrounding workflows |
+
+## Installation & Quick Start
+
+### Requirements
+
+Before you start, make sure you have:
+
+- Go `v1.23`+ and Python 3（required for building from source）
+
+### Quick Start
+
+#### Install
+
+Build from source:
+
+```bash
+# Clone repository
+git clone https://code.byted.org/people/cli.git
+cd cli
+
+# Build and install
+make install
+
+# Verify installation
+people-cli --version
+```
+
+#### Configure & Use
+
+```bash
+# 1. Configure app credentials (one-time, interactive guided setup)
+people-cli config init
+
+# 2. Authorize by People domain
+people-cli auth login --domain corehr --recommend
+
+# 3. Start using a shortcut
+people-cli corehr +prehire-search --format table
+```
+
+## Authentication
+
+| Command       | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `auth login`  | OAuth login with interactive selection or CLI flags for scopes |
+| `auth logout` | Sign out and remove stored credentials                         |
+| `auth status` | Show current login status and granted scopes                   |
+| `auth check`  | Verify a specific scope (exit 0 = ok, 1 = missing)            |
+| `auth scopes` | List all available scopes for the app                          |
+| `auth list`   | List all authenticated users                                   |
+
+```bash
+# Interactive login
+people-cli auth login
+
+# Authorize by People domain
+people-cli auth login --domain corehr --recommend
+people-cli auth login --domain attendance
+people-cli auth login --domain hire
+
+# Exact scope
+people-cli auth login --scope "corehr:department:read"
+
+# Agent mode: return verification URL immediately, non-blocking
+people-cli auth login --no-wait
+# Resume polling later
+people-cli auth login --device-code <DEVICE_CODE>
+
+# Identity switching: execute commands as user or bot
+people-cli attendance user_approval_over_time list --as user --params '{"check_date_from":"20260401","check_date_to":"20260430","status":"2"}'
+```
+
+## Command System
+
+The CLI provides three levels of granularity, covering everything from quick operations to fully custom API calls:
+
+### 1. Shortcuts
+
+Prefixed with `+`, designed to be friendly for both humans and AI, with smart defaults, table output, and dry-run previews.
+
+```bash
+# Search pre-hires
+people-cli corehr +prehire-search --format table
+
+# Query my leave balances
+people-cli attendance +leave-balances --format pretty
+```
+
+### 2. API Commands
+
+Auto-generated from Feishu OAPI metadata, curated through evaluation and quality gates.
+
+```bash
+# Search departments
+people-cli corehr department list --params '{"page_size":50}'
+
+# Query overtime approvals
+people-cli attendance user_approval_over_time list --params '{"check_date_from":"20260401","check_date_to":"20260430","status":"2"}'
+
+# Query hiring evaluation tasks
+people-cli hire evaluation_task list --params '{"page_size":10}'
+```
+
+### 3. Raw API Calls
+
+Call any Feishu Open Platform endpoint directly.
+
+```bash
+people-cli api POST /open-apis/corehr/v2/common/query_id_by_name --data '{"business_scene":"team","target_object_api_name":"department","query_name":"RD"}'
+```
+
+## Advanced Usage
+
+### Output Formats
+
+```bash
+--format json      # Full JSON response (default)
+--format pretty    # Human-friendly formatted output (supported by selected commands such as shortcuts/schema)
+--format table     # Readable table
+--format ndjson    # Newline-delimited JSON (for piping)
+--format csv       # Comma-separated values
+```
+
+### Pagination
+
+```bash
+--page-all                  # Auto-paginate through all pages
+--page-limit 5              # Max 5 pages
+--page-delay 500            # 500ms between page requests
+```
+
+### Dry Run
+
+For commands that may have side effects, preview the request with --dry-run first:
+
+```bash
+people-cli api POST /open-apis/corehr/v2/common/query_id_by_name --data '{"business_scene":"team","target_object_api_name":"department","query_name":"RD"}' --dry-run
+```
+
+### Schema Introspection
+
+Use schema to inspect any API method's parameters, request body, response structure, supported identities, and scopes:
+
+```bash
+people-cli schema
+people-cli schema corehr.job_change.search --format pretty
+people-cli schema attendance.user_approval_over_time.list
+people-cli schema hire.evaluation_task.list
+```
+
+### Configuration Management
+
+```bash
+# Initialize configuration
+people-cli config init
+
+# View current configuration
+people-cli config show
+
+# Set default identity
+people-cli config default-as user
+
+# Remove configuration
+people-cli config remove
+```
+
+### Health Check
+
+```bash
+# Check configuration, auth, and connectivity
+people-cli doctor
+
+# Offline check (skip network)
+people-cli doctor --offline
+```
+
+## Security & Risk Warnings
+
+This tool can be invoked by AI Agents to automate operations on the Feishu Open Platform, and carries inherent risks such as model hallucinations, unpredictable execution, and prompt injection. After you authorize Feishu permissions, the AI Agent will act under your user identity within the authorized scope, which may lead to high-risk consequences such as leakage of sensitive data or unauthorized operations. Please use with caution.
+
+To reduce these risks, the tool enables default security protections at multiple layers. However, these risks still exist. We strongly recommend that you do not proactively modify any default security settings; once relevant restrictions are relaxed, the risks will increase significantly, and you will bear the consequences.
+
+We recommend using the Feishu bot integrated with this tool as a private conversational assistant. Do not add it to group chats or allow other users to interact with it, to avoid abuse of permissions or data leakage.
+
+Please fully understand all usage risks. By using this tool, you are deemed to voluntarily assume all related responsibilities.
+
+## Contributing
+
+Community contributions are welcome! If you find a bug or have feature suggestions, please submit an [Issue](https://code.byted.org/people/cli/issues) or [Merge Request](https://code.byted.org/people/cli/merge_requests).
+
+For major changes, we recommend discussing with us first via an Issue.
+
+## Related Projects
+
+- [people-cli-registry](https://code.byted.org/people/people-cli-registry) — API registry generator that provides People domain metadata and generation config for `people-cli`
+
+## License
+
+This project is licensed under the **MIT License**.
+When running, it calls Feishu Open Platform APIs. To use these APIs, you must comply with the following agreements and privacy policies:
+
+- [飞书用户协议](https://www.feishu.cn/terms)
+- [飞书隐私政策](https://www.feishu.cn/privacy)
+- [飞书开放平台应用服务商安全管理办法](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)