@lark-project/meegle 0.0.4 → 0.0.5

package/README.md

@@ -0,0 +1,411 @@
+# Meegle CLI
+
+> **DEV** — 当前处于开发预览阶段，API 和命令可能发生变更。
+
+飞书项目（Meegle）命令行工具。在终端中管理工作项、查看排期、搜索数据，无需打开浏览器。
+
+## 安装
+
+```bash
+npm install -g @lark-project/meegle
+```
+
+要求 Node.js >= 18。
+
+## 快速开始
+
+```bash
+# 1. 登录
+meegle auth login
+
+# 2. 查看本周待办
+meegle mywork todo --action this_week --page-num 1
+
+# 3. 查看帮助
+meegle --help
+meegle workitem --help
+
+# 4. 查看命令参数详情
+meegle inspect workitem.create
+```
+
+## 命令一览
+
+### workitem — 工作项域
+
+| 命令 | 说明 |
+|------|------|
+| `workitem create` | 创建工作项 |
+| `workitem get` | 查看工作项概况 |
+| `workitem update` | 修改工作项字段 |
+| `workitem query` | 使用 MQL 搜索工作项 |
+| `workitem list-op-records` | 查看操作记录 |
+| `workitem meta-types` | 查看工作项类型列表 |
+| `workitem meta-create-fields` | 查看创建时可用字段 |
+| `workitem meta-fields` | 查看字段配置 |
+| `workitem meta-roles` | 查看角色配置 |
+
+### workflow — 工作流域
+
+| 命令 | 说明 |
+|------|------|
+| `workflow transition` | 流转或回滚节点 |
+| `workflow get-node` | 查看节点详情 |
+| `workflow update-node` | 修改节点 |
+| `workflow meta-node-fields` | 查看节点字段配置 |
+| `workflow list-state-transitions` | 查看可流转状态 |
+| `workflow list-state-required` | 查看流转必填信息 |
+
+### subtask — 子任务
+
+| 命令 | 说明 |
+|------|------|
+| `subtask update` | 创建/修改/完成/回滚子任务 |
+
+### comment — 评论域
+
+| 命令 | 说明 |
+|------|------|
+| `comment add` | 添加评论 |
+| `comment list` | 查看评论列表 |
+
+### workhour — 工时域
+
+| 命令 | 说明 |
+|------|------|
+| `workhour list-records` | 查看工时登记记录 |
+| `workhour list-schedule` | 查看人员排期 |
+
+### relation — 关系域
+
+| 命令 | 说明 |
+|------|------|
+| `relation list` | 查看关联的工作项 |
+| `relation meta-definitions` | 查看关联关系定义 |
+
+### mywork — 工作台域
+
+| 命令 | 说明 |
+|------|------|
+| `mywork todo` | 查看我的待办/已办 |
+
+### view — 视图域
+
+| 命令 | 说明 |
+|------|------|
+| `view create-fixed` | 创建固定视图 |
+| `view get` | 查看视图详情 |
+| `view update-fixed` | 更新固定视图 |
+| `view search` | 按名称搜索视图 |
+
+### chart — 度量域
+
+| 命令 | 说明 |
+|------|------|
+| `chart get` | 查看图表详情 |
+| `chart list` | 查看视图下的图表列表 |
+
+### team / user — 人员域
+
+| 命令 | 说明 |
+|------|------|
+| `team list` | 查看空间下的团队列表 |
+| `team list-members` | 查看团队成员 |
+| `user search` | 搜索用户信息 |
+
+### project — 空间域
+
+| 命令 | 说明 |
+|------|------|
+| `project search` | 搜索空间信息 |
+
+### 其他命令
+
+| 命令 | 说明 |
+|------|------|
+| `inspect [command]` | 查看命令参数详情 |
+
+## 常用示例
+
+### 查看待办
+
+```bash
+# 本周待办
+meegle mywork todo --action this_week --page-num 1
+
+# 已办事项
+meegle mywork todo --action done --page-num 1
+
+# 逾期事项
+meegle mywork todo --action overdue --page-num 1
+```
+
+### 查询工作项
+
+```bash
+# 查看工作项概况
+meegle workitem get --work-item-id 12345
+
+# 查看工作项的节点详情
+meegle workflow get-node --work-item-id 12345 --need-sub-task
+```
+
+### 创建工作项
+
+```bash
+# 使用 --set 设置字段
+meegle workitem create --project-key PROJ --work-item-type story \
+  --set name=优化登录流程 \
+  --set priority=P1
+
+# 复杂字段传 JSON 值
+meegle workitem create --project-key PROJ --work-item-type story \
+  --set name=排期任务 \
+  --set schedule='[1722182400000,1722355199999]'
+```
+
+### 修改字段
+
+```bash
+# 修改工作项名称
+meegle workitem update --work-item-id 12345 \
+  --set name=新标题
+
+# 同时修改多个字段
+meegle workitem update --work-item-id 12345 \
+  --set name=新标题 \
+  --set priority=P0
+```
+
+### MQL 搜索
+
+```bash
+# 查询空间下的 P0 需求
+meegle workitem query --project-key PROJ \
+  --mql "SELECT \`name\`, \`priority\` FROM \`空间名\`.\`需求\` WHERE \`priority\` = 'P0'"
+```
+
+### 查看排期
+
+```bash
+# 查看团队成员排期
+meegle workhour list-schedule --project-key PROJ \
+  --start-time 2026-03-01 --end-time 2026-03-31 \
+  --user-keys "张三,李四,王五"
+```
+
+### 查看用户信息
+
+```bash
+meegle user search --user-keys "张三,李四" --project-key PROJ
+```
+
+## 参数传递
+
+### 基本 flag
+
+每个命令的参数通过 `--flag-name` 传递：
+
+```bash
+meegle workitem get --work-item-id 12345 --project-key PROJ
+```
+
+### --set key=value（写入命令）
+
+`workitem create`、`workitem update`、`workflow update-node`、`subtask update` 支持 `--set` 简便设置字段：
+
+```bash
+--set name=标题              # 字符串
+--set points=5               # 数字
+--set is_urgent=true         # 布尔
+--set schedule='[1,2]'       # JSON 数组
+--set role='{"role":"RD"}'   # JSON 对象
+```
+
+`--set` 可重复使用，一次设置多个字段。
+
+### --params JSON（兜底）
+
+所有命令都支持 `--params` 传入完整 JSON 参数：
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"标题"}]}'
+```
+
+### 优先级
+
+当 `--set`、`--params` 和普通 flag 同时使用时：
+
+1. `--set` 覆盖 `--params` 中同名字段
+2. 普通 flag（如 `--project-key`）覆盖 `--params` 中同名顶层 key
+
+### 数组参数
+
+多个值用逗号分隔：
+
+```bash
+--user-keys "张三,李四,王五"
+--field-keys "name,status,priority"
+```
+
+### 布尔参数
+
+直接加 flag 即为 true，不加即为 false：
+
+```bash
+meegle workflow get-node --work-item-id 12345 --need-sub-task
+```
+
+## 输出格式
+
+```bash
+# JSON（默认）
+meegle workitem get --work-item-id 12345
+
+# 选取输出属性（支持 dot path）
+meegle workitem get --work-item-id 12345 --select "id,name,status"
+meegle mywork todo --action done --page-num 1 --select "list.work_item_info.work_item_name"
+
+# NDJSON（适合管道处理）
+meegle mywork todo --action this_week --page-num 1 --format ndjson
+
+# 表格
+meegle mywork todo --action this_week --page-num 1 --format table
+```
+
+### --select dot path
+
+`--select` 支持用 `.` 访问嵌套属性，遇到数组时自动穿透：
+
+```bash
+# 从嵌套结构中提取字段
+--select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+
+# 混合顶层和嵌套
+--select "total,list.work_item_info.work_item_name"
+```
+
+## 命令内省
+
+使用 `inspect` 查看命令的完整参数信息：
+
+```bash
+# 列出所有命令
+meegle inspect
+
+# 查看特定命令的参数详情
+meegle inspect workitem.create
+```
+
+## 认证
+
+### 浏览器登录（默认）
+
+```bash
+meegle auth login
+```
+
+自动打开浏览器完成 OAuth 授权。如果浏览器未打开，终端会显示授权地址，手动复制即可。
+
+### Device Code 登录（无浏览器环境）
+
+```bash
+meegle auth login --device-code
+```
+
+终端显示二维码和授权码，使用手机扫码授权。适用于 SSH 远程服务器等无浏览器环境。
+
+### 其他认证命令
+
+```bash
+# 查看登录状态
+meegle auth status
+
+# 登出
+meegle auth logout
+```
+
+## 配置
+
+### 配置文件
+
+配置存储在 `~/.meegle/config.json`：
+
+```bash
+# 初始化配置
+meegle config init
+
+# 查看当前配置
+meegle config show
+
+# 修改单个配置项
+meegle config set host project.feishu.cn
+
+# 查看单个配置项
+meegle config get host
+```
+
+主要配置项：
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `host` | 站点域名 | `project.feishu.cn`、`meegle.com` |
+
+### 多环境 Profile
+
+支持管理多个环境配置（不同站点、不同账号），每个 profile 独立存储 host 和认证信息。
+
+```bash
+# 创建新环境（交互式引导 host 选择 + 登录）
+meegle config profile create staging
+
+# 查看所有环境
+meegle config profile list
+
+# 切换默认环境
+meegle config profile use staging
+
+# 查看当前环境
+meegle config profile current
+
+# 临时使用其他环境（不改变默认）
+meegle mywork todo --action this_week --page-num 1 --profile staging
+
+# 删除环境
+meegle config profile delete staging
+```
+
+### 环境变量
+
+环境变量优先级高于配置文件：
+
+| 变量 | 说明 |
+|------|------|
+| `MEEGLE_HOST` | 站点域名 |
+| `MEEGLE_USER_ACCESS_TOKEN` | 直接传入 token（CI 场景） |
+
+## 常见问题
+
+### 命令列表为空
+
+CLI 启动时会从服务端获取可用命令列表。如果网络不通或未登录，动态命令不会注册。请先确保已登录：
+
+```bash
+meegle auth login
+```
+
+命令列表会自动缓存，过期后在后台静默刷新，不影响使用。
+
+### CI/CD 环境使用
+
+通过环境变量传入 token，跳过交互式登录：
+
+```bash
+export MEEGLE_USER_ACCESS_TOKEN="your-token"
+meegle mywork todo --action this_week --page-num 1
+```
+
+## License
+
+[ISC](LICENSE) © Lark Technologies Pte. Ltd.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-project/meegle",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "ISC",
   "bin": {