@lark-people/cli 0.0.0-beta.1

package/README.zh.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)
+
+飞书 People 域官方 CLI 工具。`people-cli` 当前覆盖 CoreHR、Attendance、Hire 等 People 域能力，并提供少量配套工作流辅助命令，例如 Drive 文件上传下载。
+
+[安装](#安装与快速开始) · [认证](#认证) · [命令](#命令调用体系) · [进阶用法](#进阶用法) · [贡献](#贡献)
+
+## 为什么选 people-cli？
+
+- **聚焦 People 域** — 一套 CLI 覆盖 CoreHR、Attendance、Hire，以及周边工作流辅助能力
+- **Shortcut 优先，API 完整** — 常见场景优先走高级快捷命令，复杂需求可下钻到服务命令和通用 API
+- **AI 友好** — 结构化输出和稳定命令形态，适合 AI Agent 与自动化集成
+- **上手快** — 引导式配置、按域授权、Schema 自省，缩短从安装到首次成功调用的路径
+- **安全可控** — 输入防注入、终端输出净化、系统原生密钥链存储凭证
+- **开源可扩展** — MIT 协议，适合本地开发、自动化脚本和二次封装
+
+## 功能
+
+| 类别 | 能力 |
+| --- | --- |
+| `corehr` | 部门查询、员工搜索、员工基本信息、任职信息、待入职查询、假期余额/休假记录、编制查询、名称转 ID 快捷命令 |
+| `attendance` | 考勤审批与加班审批记录查询 |
+| `hire` | 招聘职位、投递、面试、评估、人才等招聘数据查询 |
+| 辅助能力 | Drive 文件上传下载等周边工作流辅助命令 |
+
+## 安装与快速开始
+
+### 环境要求
+
+开始之前，请确保具备以下条件：
+
+- Go `v1.23`+ 和 Python 3（源码构建需要）
+
+### 快速开始
+
+#### 安装
+
+从源码编译安装：
+
+```bash
+# Clone 仓库
+git clone https://code.byted.org/people/cli.git
+cd cli
+
+# 编译并安装
+make install
+
+# 验证安装
+people-cli --version
+```
+
+#### 配置与使用
+
+```bash
+# 1. 配置应用凭证（仅需一次，交互式引导完成）
+people-cli config init
+
+# 2. 按 People 域登录授权
+people-cli auth login --domain corehr --recommend
+
+# 3. 开始使用快捷命令
+people-cli corehr +prehire-search --format table
+```
+
+## 认证
+
+| 命令          | 说明                                             |
+| --------------- | -------------------------------------------------- |
+| `auth login`  | OAuth 登录，支持交互式选择或命令行参数指定 scope |
+| `auth logout` | 登出并删除已存储的凭证                           |
+| `auth status` | 查看当前登录状态和已授权的 scope                 |
+| `auth check`  | 校验指定 scope（exit 0 = 有权限，1 = 缺失）      |
+| `auth scopes` | 列出应用的所有可用 scope                         |
+| `auth list`   | 列出所有已认证的用户                             |
+
+```bash
+# 交互式登录
+people-cli auth login
+
+# 按 People 域授权
+people-cli auth login --domain corehr --recommend
+people-cli auth login --domain attendance
+people-cli auth login --domain hire
+
+# 精确 scope
+people-cli auth login --scope "corehr:department:read"
+
+# Agent 模式：立即返回验证 URL，不阻塞
+people-cli auth login --no-wait
+# 稍后恢复轮询
+people-cli auth login --device-code <DEVICE_CODE>
+
+# 身份切换：以用户或机器人身份执行命令
+people-cli attendance user_approval_over_time list --as user --params '{"check_date_from":"20260401","check_date_to":"20260430","status":"2"}'
+```
+
+## 命令调用体系
+
+CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义的全部场景：
+
+### 1. 快捷命令（Shortcuts）
+
+以 `+` 为前缀，对人类与 AI 友好化封装，内置智能默认值、表格输出和 dry-run 预览。
+
+```bash
+# 搜索待入职员工
+people-cli corehr +prehire-search --format table
+
+# 查询当前员工的假期余额
+people-cli attendance +leave-balances --format pretty
+```
+
+### 2. API 命令
+
+从飞书 OAPI 元数据自动生成，经过评测与准入筛选。
+
+```bash
+# 获取部门列表
+people-cli corehr department list --params '{"page_size":50}'
+
+# 查询加班审批记录
+people-cli attendance user_approval_over_time list --params '{"check_date_from":"20260401","check_date_to":"20260430","status":"2"}'
+
+# 查询招聘评估任务
+people-cli hire evaluation_task list --params '{"page_size":10}'
+```
+
+### 3. 通用 API 调用
+
+直接调用任意飞书开放平台端点。
+
+```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":"研发部"}'
+```
+
+## 进阶用法
+
+### 输出格式
+
+```bash
+--format json      # 完整 JSON 响应（默认）
+--format pretty    # 人性化格式输出（适用于部分命令，如 shortcuts / schema）
+--format table     # 易读表格
+--format ndjson    # 换行分隔 JSON（适合管道处理）
+--format csv       # 逗号分隔值
+```
+
+### 分页
+
+```bash
+--page-all                  # 自动翻页获取所有数据
+--page-limit 5              # 最多获取 5 页
+--page-delay 500            # 每页请求间隔 500ms
+```
+
+### Dry Run
+
+对可能产生副作用的命令，建议先用 --dry-run 预览请求：
+
+```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":"研发部"}' --dry-run
+```
+
+### Schema 自省
+
+使用 schema 查看任意 API 方法的参数、请求体、响应结构、支持身份和 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
+```
+
+### 配置管理
+
+```bash
+# 初始化配置
+people-cli config init
+
+# 查看当前配置
+people-cli config show
+
+# 设置默认身份
+people-cli config default-as user
+
+# 删除配置
+people-cli config remove
+```
+
+### 健康检查
+
+```bash
+# 检查配置、认证和连通性
+people-cli doctor
+
+# 离线检查（跳过网络）
+people-cli doctor --offline
+```
+
+## 安全与风险提示（使用前必读）
+
+本工具可供 AI Agent 调用以自动化操作飞书开放平台，存在模型幻觉、执行不可控、提示词注入等固有风险；授权飞书权限后，AI Agent 将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。
+
+为降低上述风险，工具已在多个层面启用默认安全保护，但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。
+
+我们建议您将对接本工具的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。
+
+请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。
+
+## 贡献
+
+欢迎社区贡献！如果你发现 bug 或有功能建议，请提交 [Issue](https://code.byted.org/people/cli/issues) 或 [Merge Request](https://code.byted.org/people/cli/merge_requests)。
+
+对于较大的改动，建议先通过 Issue 与我们讨论。
+
+## 相关项目
+
+- [people-cli-registry](https://code.byted.org/people/people-cli-registry) — API 注册表生成器，为 `people-cli` 提供 People 域 API 元数据和命令生成配置
+
+## 许可证
+
+本项目基于 **MIT 许可证** 开源。
+该软件运行时会调用飞书开放平台的 API，使用这些 API 需要遵守如下协议和隐私政策：
+
+- [飞书用户服务协议](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)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@lark-people/cli",
+  "version": "0.0.0-beta.1",
+  "description": "The official CLI for People open platform",
+  "bin": {
+    "people-cli": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "author": "People Team",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "bin/people-cli_*",
+    "skills/",
+    "!skills/people-skill-maker/",
+    "scripts/install.js",
+    "scripts/install-wizard.js",
+    "scripts/run.js",
+    "CHANGELOG.md"
+  ]
+}