meegle-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,215 +1,430 @@
-# meegle-cli (plugin-only)
+# meegle-cli
 
-基于 `project-oapi-sdk-typescript` 的命令行工具。  
-当前模式：仅支持 `plugin_access_token / virtual_plugin_token`，不支持 `user_access_token`。
+面向飞书项目（Meegle）的命令行工具。  
+当前版本运行在 `plugin-only` 模式：只支持 `plugin_access_token / virtual_plugin_token`，不支持 `user_access_token`。
 
-## 安装
+## 适用对象
+
+- 想在终端里查询空间、工作项、视图、评论、子任务
+- 想把 Meegle 调用接到脚本、Agent、CI 里
+- 已经有插件凭证：`pluginId / pluginSecret`
+
+不适用场景：
 
-对外用户安装：
+- 需要 `user_access_token` 的接口
+- 需要在 CLI 内做浏览器登录换 user token
+
+## 安装
 
 ```bash
 npm install -g meegle-cli
 meegle --help
 ```
 
-仓库内开发安装：
+如果安装后提示 `meegle: command not found`，先确认 npm 全局 bin 在 PATH 里：
 
 ```bash
-cd /Users/linmi/conductor/repos/meego-client/meegle-cli
-npm install
+npm bin -g
 ```
 
-## 构建
+## 你需要准备什么
 
-```bash
-npm run build
-```
+最少准备这几项：
+
+- `pluginId`
+- `pluginSecret`
+- `userKey`
+- `projectKey`
+
+可选：
 
-## 发布
+- `baseURL`
+  - 默认就是 `https://project.feishu.cn`
 
-发布说明见 [RELEASE.md](/Users/linmi/conductor/repos/meego-client/meegle-cli/RELEASE.md)。
+## 3 分钟上手
 
-## 初始化
+### 1. 初始化一个 profile
 
 ```bash
-node dist/index.js auth init \
+meegle auth init \
   --target-profile default \
-  --plugin-id MII_xxx \
-  --plugin-secret xxx \
-  --base-url https://project.feishu.cn \
-  --token-type 0 \
-  --default-user-key 123456
+  --plugin-id <PLUGIN_ID> \
+  --plugin-secret <PLUGIN_SECRET> \
+  --default-user-key <USER_KEY>
 ```
 
-也可以先放环境变量，再直接初始化：
+也可以先放环境变量，再执行初始化：
 
 ```bash
-export MEEGLE_PLUGIN_ID=MII_xxx
-export MEEGLE_PLUGIN_SECRET=xxx
-export MEEGLE_USER_KEY=123456
+export MEEGLE_PLUGIN_ID=<PLUGIN_ID>
+export MEEGLE_PLUGIN_SECRET=<PLUGIN_SECRET>
+export MEEGLE_USER_KEY=<USER_KEY>
 
-node dist/index.js auth init --target-profile default
+meegle auth init --target-profile default
 ```
 
-## 入参约定
+### 2. 校验凭证
 
-- 常用查询优先走直接参数，不再强制写 JSON 文件
-- 常用写操作也优先走直接参数，例如 `--name`、`--desc`、`--content`
-- 复杂请求体仍可使用 `--body <json>` 或 `--body-file <path>`
-- 复杂查询参数仍可使用 `--query-file <path>`
-- 大多数命令要求 `userKey`：`--user-key` 或 `auth init --default-user-key`
-- 如果 profile 里没存 `defaultUserKey`，运行时也会读取 `MEEGLE_USER_KEY`
-- 自定义字段统一使用 `--field field_key=value`；对象/数组值直接传 JSON
-- 排期参数统一支持 `--start/--end`，可传毫秒时间戳或可解析日期，如 `2025-01-01`
+```bash
+meegle --profile default auth status --json
+```
 
-## 命令总览
+成功时会返回：
 
-- `auth`: `init`, `status`
-- `space`: `list`, `get`, `types`, `team-members`
-- `workitem`: `get`, `meta`, `create`, `update`, `remove`, `freeze`, `unfreeze`, `abort`, `restore`, `op-records`, `update-compound`
-- `workitem search`: `filter`, `filter-across`, `by-params`, `by-relation`, `compositive`, `universal`
-- `workflow`: `query`, `state-change`, `node-operate`, `node-update`, `required-info`, `wbs`
-- `comment`: `list`, `add`, `update`, `remove`
-- `subtask`: `list`, `search`, `create`, `update`, `remove`, `operate`
-- `attachment`: `upload-file`, `upload`, `download`, `delete`
-- `workhour`: `list`, `create`, `update`, `delete`
-- `view`: `list`, `fix-items`, `panoramic-items`, `create-fix`, `update-fix`, `delete`, `create-condition`, `update-condition`
-- `measure`: `charts`, `chart-data`
-- `tenant`: `info`, `entitlement`, `spaces`
-- `user`: `query`, `search`（会被拒绝）
-- `user group`: `create`, `update-members`, `query-members`（会被拒绝）
+- `profile`
+- `baseURL`
+- `tokenType`
+- `tokenPreview`
+- `ok: true`
+
+### 3. 列出你能看到的空间
 
-## 真实环境 Smoke（可选）
+```bash
+meegle --profile default space list --json
+```
 
-执行：
+### 4. 查询自己
 
 ```bash
-npm run test:smoke:real
+meegle --profile default user query --self --json
 ```
 
-必填环境变量：
+## 核心概念
 
-- `MEEGLE_SMOKE_PLUGIN_ID`
-- `MEEGLE_SMOKE_PLUGIN_SECRET`
-- `MEEGLE_SMOKE_USER_KEY`
-- `MEEGLE_SMOKE_PROJECT_KEY`
+### profile
 
-可选环境变量：
+一套 CLI 配置，通常对应一套环境或一组凭证。
 
-- `MEEGLE_SMOKE_BASE_URL`（默认 `https://project.feishu.cn`）
-- `MEEGLE_SMOKE_WORK_ITEM_TYPE_KEY`（不填时自动取 `space types` 第一项）
-- `MEEGLE_SMOKE_WORK_ITEM_ID`（填了会额外做 `workitem get`）
+例如：
 
-测试链路：
+- `default`
+- `test`
+- `prod`
 
-- `auth init -> auth status -> space list -> space get -> user query --self -> space types -> workitem meta`
-- 若提供 `MEEGLE_SMOKE_WORK_ITEM_ID`，再执行 `workitem get`
-- 最后验证 user-only 接口在 plugin-only 下被拒绝
+切换方式：
 
-`MEEGLE_SMOKE_USER_KEY` 获取建议：
+```bash
+meegle --profile prod space list
+```
 
-- 文档建议可在飞书项目空间双击头像获取 `user_key`
-- 如果你在插件前端里调试，JS SDK 文档里有 `window.JSSDK.utils.getAuthCode()`；虽然该方法用于 user token 流程，但同一套文档章节也包含用户身份相关取值指引
+### userKey
 
-## plugin-only 拒绝列表（denylist）
+`plugin-only` 模式下，大多数命令都需要 `userKey`。
 
-- `POST /open_api/user/search`
-- `POST /open_api/:project_key/user_group`
-- `PATCH /open_api/:project_key/user_group/members`
-- `POST /open_api/:project_key/user_groups/members/page`
+来源优先级：
 
-## 示例
+1. 命令行 `--user-key`
+2. profile 里的 `defaultUserKey`
+3. 环境变量 `MEEGLE_USER_KEY`
 
-```bash
-# 1) 校验凭证
-node dist/index.js --profile default auth status --json
+### projectKey
 
-# 2) 列出空间
-node dist/index.js --profile default space list --json
+空间 ID，通常就是接口里的 `project_key`。  
+很多命令也支持空间域名 `simple_name`，例如 `69zyer`。
 
-# 3) 获取空间详情
-node dist/index.js --profile default space get \
-  --project-key your_project \
+## 常见任务
+
+### 查空间详情
+
+```bash
+meegle --profile default space get \
+  --project-key <PROJECT_KEY> \
   --json
+```
 
-# 4) 查询当前 userKey 对应的用户
-node dist/index.js --profile default user query \
-  --self \
+### 查工作项
+
+查单个工作项：
+
+```bash
+meegle --profile default workitem get \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --id 6300034462 \
   --json
+```
+
+只取部分字段：
 
-# 5) 查询工作项，常见场景直接传 ID
-node dist/index.js --profile default workitem get \
-  --project-key your_project \
+```bash
+meegle --profile default workitem get \
+  --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
+  --fields name,priority,owner,description \
   --json
+```
+
+### 创建工作项
 
-# 6) 创建工作项，常见字段直接写
-node dist/index.js --profile default workitem create \
-  --project-key your_project \
+```bash
+meegle --profile default workitem create \
+  --project-key <PROJECT_KEY> \
   --type story \
   --name "登录优化" \
   --desc "补齐错误提示" \
-  --owner your_user_key \
+  --owner <USER_KEY> \
   --priority P2 \
   --json
+```
+
+### 更新工作项
 
-# 7) 更新工作项，改单个字段不需要写 update_fields
-node dist/index.js --profile default workitem update \
-  --project-key your_project \
+```bash
+meegle --profile default workitem update \
+  --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
   --name "登录优化（已排期）" \
   --json
+```
 
-# 8) 添加评论，支持直接写文本或从文件读
-node dist/index.js --profile default comment add \
-  --project-key your_project \
+### 添加评论
+
+```bash
+meegle --profile default comment add \
+  --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
   --content "收到，开始处理" \
   --json
+```
+
+如果评论内容很长，改用文件：
 
-# 9) 创建子任务
-node dist/index.js --profile default subtask create \
-  --project-key your_project \
+```bash
+meegle --profile default comment add \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --id 6300034462 \
+  --content-file ./comment.txt \
+  --json
+```
+
+### 创建子任务
+
+```bash
+meegle --profile default subtask create \
+  --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
   --node-id doing \
   --name "需求分析" \
   --note "补齐边界条件" \
-  --assignee your_user_key \
+  --assignee <USER_KEY> \
   --points 3 \
   --start 2025-01-01 \
   --end 2025-01-02 \
   --json
+```
 
-# 10) 状态流转
-node dist/index.js --profile default workflow state-change \
-  --project-key your_project \
+### 状态流转
+
+```bash
+meegle --profile default workflow state-change \
+  --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
   --transition-id 12345 \
   --field description="流转补充说明" \
   --json
+```
 
-# 11) 节点完成/回滚
-node dist/index.js --profile default workflow node-operate \
-  --project-key your_project \
+### 节点完成 / 回滚
+
+```bash
+meegle --profile default workflow node-operate \
+  --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
   --node-id dev \
   --action rollback \
   --rollback-reason "需要返工" \
   --json
+```
 
-# 12) 复杂场景再回退到原始请求体
-node dist/index.js --profile default workitem get \
-  --project-key your_project \
-  --type story \
-  --body '{"work_item_ids":[6300034462],"fields":["name","priority"]}' \
+## 视图使用
+
+### 先查视图配置，再决定调哪个接口
+
+固定视图和全景视图不是一个接口。  
+先查 `view_type`，再调后续命令，别从 URL 结构直接猜。
+
+查指定视图：
+
+```bash
+cat > /tmp/view-list.json <<'JSON'
+{
+  "work_item_type_key": "story",
+  "view_ids": ["sypbi-z60"],
+  "is_query_quick_filter": true,
+  "page_size": 10,
+  "page_num": 1
+}
+JSON
+
+meegle --profile default view list \
+  --project-key 69zyer \
+  --body-file /tmp/view-list.json \
   --json
+```
+
+返回中重点看：
 
-# 13) user-only 接口会被直接拒绝
-node dist/index.js user search --query test
+- `view_id`
+- `name`
+- `view_type`
+  - `1` = 条件视图
+  - `2` = 固定视图
+
+### 固定视图
+
+固定视图用：
+
+```bash
+cat > /tmp/fix.json <<'JSON'
+{
+  "page_size": 50,
+  "page_num": 1
+}
+JSON
+
+meegle --profile default view fix-items \
+  --project-key 69zyer \
+  --view-id sypbi-z60 \
+  --query-file /tmp/fix.json \
+  --json
 ```
+
+### 全景视图
+
+全景视图用：
+
+```bash
+cat > /tmp/panoramic.json <<'JSON'
+{
+  "page_size": 50,
+  "page_num": 1
+}
+JSON
+
+meegle --profile default view panoramic-items \
+  --project-key 69zyer \
+  --view-id <VIEW_ID> \
+  --body-file /tmp/panoramic.json \
+  --json
+```
+
+### PMO 视角的正确用法
+
+如果你要做 PMO 基线分析，推荐链路是：
+
+1. `view list` 确认视图类型
+2. `view fix-items` 或 `view panoramic-items` 拉视图内工作项 ID
+3. `workitem get --ids ... --fields ...` 拉详情字段
+4. 再在脚本里统计：
+   - 状态分布
+   - 负责人分布
+   - 优先级分布
+   - 到期时间完整度
+   - 超期 / 逾期 / 老化
+
+不要直接拿整个空间总池代替“这个视图”的口径。
+
+## 参数约定
+
+- 常用查询优先走直接参数，不强制写 JSON 文件
+- 常用写操作优先走直接参数，例如 `--name`、`--desc`、`--content`
+- 复杂请求体可使用 `--body <json>` 或 `--body-file <path>`
+- 复杂查询参数可使用 `--query-file <path>`
+- 自定义字段统一使用 `--field field_key=value`
+- 对象 / 数组值直接传 JSON
+- 排期参数统一支持 `--start/--end`
+  - 可传毫秒时间戳
+  - 也可传可解析日期，例如 `2025-01-01`
+
+## 当前限制
+
+### plugin-only
+
+当前 CLI 不支持 `user_access_token`。  
+所以这类命令会被直接拒绝：
+
+- `user search`
+- `user group create`
+- `user group update-members`
+- `user group query-members`
+
+这是设计行为，不是故障。
+
+## 排错
+
+### 1. `meegle: command not found`
+
+先看 npm 全局 bin：
+
+```bash
+npm bin -g
+```
+
+### 2. 缺少 `userKey`
+
+报错通常类似：
+
+- `缺少 userKey`
+- `命令 ... 需要 userKey`
+
+处理方式：
+
+```bash
+meegle --profile default space list --user-key <USER_KEY>
+```
+
+或者重新初始化：
+
+```bash
+meegle auth init \
+  --target-profile default \
+  --plugin-id <PLUGIN_ID> \
+  --plugin-secret <PLUGIN_SECRET> \
+  --default-user-key <USER_KEY>
+```
+
+### 3. `user search` 被拒绝
+
+这是正常行为。  
+当前版本是 `plugin-only`，该命令依赖 `user_access_token`。
+
+### 4. 固定视图 / 全景视图调用报错
+
+先回到 `view list` 看 `view_type`。  
+不要只凭页面 URL 去猜视图类型。
+
+## 命令总览
+
+- `auth`: `init`, `status`
+- `space`: `list`, `get`, `types`, `team-members`
+- `workitem`: `get`, `meta`, `create`, `update`, `remove`, `freeze`, `unfreeze`, `abort`, `restore`, `op-records`, `update-compound`
+- `workitem search`: `filter`, `filter-across`, `by-params`, `by-relation`, `compositive`, `universal`
+- `workflow`: `query`, `state-change`, `node-operate`, `node-update`, `required-info`, `wbs`
+- `comment`: `list`, `add`, `update`, `remove`
+- `subtask`: `list`, `search`, `create`, `update`, `remove`, `operate`
+- `attachment`: `upload-file`, `upload`, `download`, `delete`
+- `workhour`: `list`, `create`, `update`, `delete`
+- `view`: `list`, `fix-items`, `panoramic-items`, `create-fix`, `update-fix`, `delete`, `create-condition`, `update-condition`
+- `measure`: `charts`, `chart-data`
+- `tenant`: `info`, `entitlement`, `spaces`
+- `user`: `query`, `search`（会被拒绝）
+- `user group`: `create`, `update-members`, `query-members`（会被拒绝）
+
+## 开发与发布
+
+仓库内开发：
+
+```bash
+cd meegle-cli
+npm install
+npm test
+```
+
+发布说明见 [RELEASE.md](./RELEASE.md)。

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "meegle-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Plugin-only CLI for Feishu Project (Meegle) based on meeglesdk",
   "type": "module",
   "bin": {
-    "meegle": "./dist/index.js"
+    "meegle": "dist/index.js"
   },
   "files": [
     "dist",