meegle-cli 0.1.1 → 0.1.2

package/README-en.md

@@ -0,0 +1,193 @@
+# meegle-cli
+
+CLI for Feishu Project (Meegle).  
+Current mode is `plugin-only`: it supports `plugin_access_token / virtual_plugin_token`, but not `user_access_token`.
+
+## Install
+
+```bash
+npm install -g meegle-cli
+meegle --help
+```
+
+## What You Need
+
+- `pluginId`
+- `pluginSecret`
+- `userKey`
+- `projectKey`
+
+Optional:
+
+- `baseURL`
+  - default: `https://project.feishu.cn`
+
+## Quick Start
+
+### 1. Initialize a profile
+
+```bash
+meegle auth init \
+  --target-profile default \
+  --plugin-id <PLUGIN_ID> \
+  --plugin-secret <PLUGIN_SECRET> \
+  --default-user-key <USER_KEY>
+```
+
+Or use environment variables:
+
+```bash
+export MEEGLE_PLUGIN_ID=<PLUGIN_ID>
+export MEEGLE_PLUGIN_SECRET=<PLUGIN_SECRET>
+export MEEGLE_USER_KEY=<USER_KEY>
+
+meegle auth init --target-profile default
+```
+
+### 2. Verify credentials
+
+```bash
+meegle --profile default auth status --json
+```
+
+### 3. List spaces
+
+```bash
+meegle --profile default space list --json
+```
+
+### 4. Query yourself
+
+```bash
+meegle --profile default user query --self --json
+```
+
+## Common Tasks
+
+### Get a work item
+
+```bash
+meegle --profile default workitem get \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --id 6300034462 \
+  --json
+```
+
+### Create a work item
+
+```bash
+meegle --profile default workitem create \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --name "Login improvement" \
+  --desc "Improve error messages" \
+  --owner <USER_KEY> \
+  --priority P2 \
+  --json
+```
+
+### Add a comment
+
+```bash
+meegle --profile default comment add \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --id 6300034462 \
+  --content "Received, starting now" \
+  --json
+```
+
+## View Usage
+
+Do not infer view type from the page URL.  
+Always call `view list` first, then choose the correct API.
+
+### Resolve a view
+
+```bash
+meegle --profile default view list \
+  --project-key 69zyer \
+  --body-file ./examples/view-list.json \
+  --json
+```
+
+Check:
+
+- `view_id`
+- `name`
+- `view_type`
+  - `1` = condition view
+  - `2` = fixed view
+
+### Fixed view items
+
+```bash
+meegle --profile default view fix-items \
+  --project-key 69zyer \
+  --view-id sypbi-z60 \
+  --query-file ./examples/view-fix-items.json \
+  --json
+```
+
+## Related Field Filtering
+
+For related fields such as `planning_version`, do not use:
+
+- `workitem search filter` with `field_value_pairs`
+
+Use this flow instead:
+
+1. find the related work item ID
+2. run `workitem search by-params`
+3. pass the related work item **ID list**, not the display name
+
+### Example: find stories by planning version
+
+Step 1: search the `version` work item:
+
+```bash
+meegle --profile default workitem search filter \
+  --project-key 69zyer \
+  --body-file ./examples/version-search-filter.json \
+  --json
+```
+
+Step 2: use the returned version `id` in `planning_version`:
+
+```bash
+meegle --profile default workitem search by-params \
+  --project-key 69zyer \
+  --type story \
+  --body-file ./examples/story-by-planning-version.json \
+  --json
+```
+
+Replace `1234567890` in the example file with the real version work item ID.
+
+## Agent Notes
+
+If you use this CLI from an AI agent or automation:
+
+1. run `meegle --help` or subcommand `--help` first
+2. do not guess request shapes from web URLs
+3. use `workitem search by-params` for custom fields and related fields
+4. `field_value_pairs` is for create/update, not for search
+
+## Examples
+
+- `examples/view-list.json`
+- `examples/view-fix-items.json`
+- `examples/version-search-filter.json`
+- `examples/story-by-planning-version.json`
+
+## Limits
+
+This CLI currently rejects user-token-only commands such as:
+
+- `user search`
+- `user group create`
+- `user group update-members`
+- `user group query-members`
+
+That is expected behavior in `plugin-only` mode.

package/README.md

@@ -331,6 +331,91 @@ meegle --profile default view panoramic-items \
 
 不要直接拿整个空间总池代替“这个视图”的口径。
 
+## 关联字段筛选
+
+### 结论先说
+
+像 `planning_version` 这类字段，不要用：
+
+- `workitem search filter` + `field_value_pairs`
+
+正确做法是：
+
+1. 先找到被关联工作项的实例 ID
+2. 再用 `workitem search by-params`
+3. 对关联字段传 **ID 列表**，不要传名称
+
+### 为什么
+
+`planning_version` 的字段类型是：
+
+- `work_item_related_multi_select`
+
+这类字段的筛选值格式是：
+
+- `list<int64>`，也就是关联工作项 ID 列表
+
+不是：
+
+- 版本名称字符串
+- `field_value_pairs`
+
+### 典型例子：按“规划版本”筛需求
+
+目标：找出 `planning_version` 关联到某个版本实例的全部 story。
+
+#### 第一步：先找版本实例
+
+先在 `version` 类型里按名称查候选：
+
+```bash
+meegle --profile default workitem search filter \
+  --project-key 69zyer \
+  --body-file ./examples/version-search-filter.json \
+  --json
+```
+
+示例文件：
+
+- [examples/version-search-filter.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/version-search-filter.json)
+
+你要从返回结果里拿到真正的版本实例 `id`。
+
+#### 第二步：再按 `planning_version` 查 story
+
+```bash
+meegle --profile default workitem search by-params \
+  --project-key 69zyer \
+  --type story \
+  --body-file ./examples/story-by-planning-version.json \
+  --json
+```
+
+示例文件：
+
+- [examples/story-by-planning-version.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/story-by-planning-version.json)
+
+重点：
+
+- 把 `1234567890` 替换成真实版本实例 ID
+- 不要直接写版本名称
+
+### 常见误用
+
+错误方向：
+
+1. 用 `workitem search filter` 查自定义关联字段
+2. 在筛选请求体里传 `field_value_pairs`
+3. 直接把版本名称塞给 `planning_version`
+
+这些场景下，接口常见表现是：
+
+- 条件被忽略
+- 返回全部需求
+- 让人误以为 CLI 不支持
+
+根因通常不是 CLI 丢参，而是请求体结构不符合接口契约。
+
 ## 参数约定
 
 - 常用查询优先走直接参数，不强制写 JSON 文件
@@ -400,6 +485,18 @@ meegle auth init \
 先回到 `view list` 看 `view_type`。  
 不要只凭页面 URL 去猜视图类型。
 
+### 5. 明明传了条件，结果返回全部数据
+
+优先检查三件事：
+
+1. 用的命令是不是对
+   - 内置字段简单筛选：`workitem search filter`
+   - 自定义字段 / 关联字段：`workitem search by-params`
+2. 值格式是不是对
+   - 关联工作项字段通常要传实例 ID，不是名称
+3. 请求体键是不是对
+   - `field_value_pairs` 用于创建 / 更新，不是搜索条件
+
 ## 命令总览
 
 - `auth`: `init`, `status`
@@ -428,3 +525,22 @@ npm test
 ```
 
 发布说明见 [RELEASE.md](./RELEASE.md)。
+
+## Examples
+
+可直接复制修改的模板在：
+
+- [examples/view-list.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/view-list.json)
+- [examples/view-fix-items.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/view-fix-items.json)
+- [examples/version-search-filter.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/version-search-filter.json)
+- [examples/story-by-planning-version.json](/Users/linmi/conductor/repos/meego-client/meegle-cli/examples/story-by-planning-version.json)
+
+## AI / Agent 提示
+
+如果你在 Agent、Openclaw、脚本平台里调用 `meegle-cli`，建议遵守这几条：
+
+1. 先跑 `meegle --help` 或子命令 `--help`，不要凭印象猜参数名
+2. 不要从页面 URL 直接猜视图类型；先调用 `view list`
+3. 自定义字段和关联字段优先走 `workitem search by-params`
+4. `planning_version` 这类关联字段，先查出被关联工作项的 `id`，再筛主工作项
+5. `field_value_pairs` 是写操作格式，不是搜索格式

package/examples/story-by-planning-version.json

@@ -0,0 +1,23 @@
+{
+  "search_group": {
+    "conjunction": "AND",
+    "search_params": [
+      {
+        "param_key": "planning_version",
+        "operator": "CONTAINS",
+        "value": [
+          1234567890
+        ]
+      }
+    ]
+  },
+  "page_size": 200,
+  "page_num": 1,
+  "fields": [
+    "name",
+    "owner",
+    "priority",
+    "planning_version",
+    "work_item_status"
+  ]
+}

package/examples/version-search-filter.json

@@ -0,0 +1,8 @@
+{
+  "work_item_type_keys": [
+    "version"
+  ],
+  "work_item_name": "260312",
+  "page_size": 50,
+  "page_num": 1
+}

package/examples/view-fix-items.json

@@ -0,0 +1,4 @@
+{
+  "page_size": 50,
+  "page_num": 1
+}

package/examples/view-list.json

@@ -0,0 +1,9 @@
+{
+  "work_item_type_key": "story",
+  "view_ids": [
+    "sypbi-z60"
+  ],
+  "is_query_quick_filter": true,
+  "page_size": 10,
+  "page_num": 1
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meegle-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Plugin-only CLI for Feishu Project (Meegle) based on meeglesdk",
   "type": "module",
   "bin": {
@@ -9,7 +9,9 @@
   "files": [
     "dist",
     "README.md",
-    "RELEASE.md"
+    "README-en.md",
+    "RELEASE.md",
+    "examples"
   ],
   "scripts": {
     "clean": "rm -rf dist",