@lark-project/meegle 0.0.17 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v1.0.0] - 2026-04-22
+
+Initial public release of Meegle CLI, published on npm as `@lark-project/meegle`.
+
+### Highlights
+
+- **Broad coverage** — 12 business domains and 40+ commands across work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, and project
+- **Agent-native** — bundled AI Agent Skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI, and Copilot; structured JSON output designed for both humans and agents
+- **Two-layer parameters** — ergonomic `--flag-name` for everyday use, with a `--params <json>` fallback for complex payloads
+- **Flexible output** — `json` / `table` / `ndjson` / `raw` formats, with `--select` dot-path projection for piping to other tools
+- **Non-interactive auth** — OAuth browser login plus a `--device-code` flow for CI and agent shells
+- **Dry-run previews** — `--dry-run` on mutation commands to inspect the exact payload before sending
+- **Secure by default** — OS keychain credential storage, `${VAR}` env-var templating so secrets stay out of config files, and multi-profile switching for staging / production

package/README.md

@@ -1,22 +1,62 @@
 # Meegle CLI
 
-> **DEV** — Currently in developer preview. APIs and commands may change.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@lark-project/meegle.svg)](https://www.npmjs.com/package/@lark-project/meegle)
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
 
 Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) ([Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)). Manage work items, schedules, and data from your terminal — no browser needed.
 
+[Install](#installation) · [Quick Start](#quick-start-human-users) · [Agent Skill](#ai-agent-skill) · [Commands](#commands) · [Auth](#authentication) · [Config](#configuration) · [Security](#security--risk-warnings) · [Contributing](#contributing)
+
+## Why Meegle CLI?
+
+- **Agent-Native** — Ships a bundled [AI Agent Skill](#ai-agent-skill) that teaches Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents how to drive Meegle with one command. Every CLI command is designed for both humans and agents, with structured JSON output, `--dry-run` previews, and `--device-code` flows for non-TTY environments
+- **Broad Coverage** — 12 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project) and 40+ commands mapping to Meegle's core capabilities
+- **Two-Layer Parameters** — Ergonomic `--flag-name` for everyday use, fallback `--params <json>` for complex payloads like `fields[]` — pick the right granularity per call
+- **Flexible Output** — `json` / `table` / `ndjson` / `raw`, with `--select` dot-path projection for piping to other tools
+- **Secure by Default** — OS keychain credential storage, `${VAR}` env-var templating so secrets never land in config files, multi-profile switching for staging / prod
+
+## Features
+
+| Category                                           | Capabilities                                                                                   |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 📋 [Work Items](#workitem--work-items)             | Create, read, update, batch-read, query (MQL), list operation records, inspect metadata        |
+| 🔀 [Workflow](#workflow--workflow)                 | Transition nodes & states, update node fields, list available transitions and required fields |
+| ✅ [Subtasks](#subtask--subtasks)                  | Create, update, complete, rollback subtasks                                                    |
+| 💬 [Comments](#comment--comments)                  | Add and list comments on work items                                                            |
+| ⏱️ [Work Hours](#workhour--work-hours)             | List work hour records, view team-member schedules                                             |
+| 🔗 [Relations](#relation--relations)               | List related work items, inspect relation-type definitions                                     |
+| 📌 [My Work](#mywork--my-work)                     | View this week / overdue / completed to-dos                                                    |
+| 👁️ [Views](#view--views)                           | Create and update fixed views, search views by name                                            |
+| 📊 [Charts](#chart--charts)                        | List charts under a view, fetch chart details                                                  |
+| 👥 [Team & User](#team--user--people)              | List teams, team members, search users, view current login                                     |
+| 🗂️ [Projects](#project--projects)                  | Search projects by keyword                                                                     |
+| 🔐 [Auth & Config](#authentication)                | OAuth login, device-code flow, multi-profile config, env-var injection                         |
+| 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
 
 ## Installation
 
+### Requirements
+
+- Node.js >= 16 (ships with `npm` / `npx`)
+
+### Install
+
 ```bash
 npm install -g @lark-project/meegle
 ```
 
-Requires Node.js >= 16.
+## Quick Start (Human Users)
 
-## Quick Start
+> **Note for AI assistants:** if you are an AI Agent helping the user set this up, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent--ci--headless) — it contains the non-interactive steps you need.
 
 ```bash
-# 1. Log in
+# (Optional) Persist the host so future logins skip the arrow-key picker
+meegle config set host <host>
+
+# 1. Log in (arrow-key host picker + browser OAuth)
 meegle auth login
 
 # 2. View this week's to-dos
@@ -30,27 +70,84 @@ meegle workitem --help
 meegle inspect workitem.create
 ```
 
-## Non-interactive setup (CI / agent shells / Claude Code)
+## Quick Start (AI Agent / CI / Headless)
 
-`meegle auth login` defaults to an arrow-key host picker plus the
-Authorization Code OAuth flow. Both require a real TTY and a local browser
-callback, so they will fail or hang in environments such as CI runners,
-pipes, or agent shells like Claude Code.
+The default `meegle auth login` uses an arrow-key host picker plus a browser OAuth callback — both require a real TTY, so they will hang or fail in CI runners, pipes, and agent shells like Claude Code. Use the Device Code flow instead: it prints an authorization URL that the user opens in any browser.
 
-In those environments use the Device Code flow instead — it prints a URL
-that the operator opens in any browser to grant access:
+**Step 1 — Install the CLI**
 
 ```bash
-# Option A: pass the host inline each time
-meegle auth login --device-code --host <host>
+npm install -g @lark-project/meegle
+```
 
-# Option B: persist the host once, then log in
+**Step 2 — Persist the host**
+
+```bash
 meegle config set host <host>
+```
+
+Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your self-hosted tenant domain such as `your-tenant.example.com`.
+
+**Step 3 — Log in with Device Code**
+
+> Run this command in the background. It prints an authorization URL — extract it and send it to the user. The command exits automatically once the user completes authorization in the browser.
+
+```bash
 meegle auth login --device-code
 ```
 
-Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your
-self-hosted tenant domain such as `your-tenant.example.com`.
+Alternatively, pass the host inline each time without persisting it:
+
+```bash
+meegle auth login --device-code --host <host>
+```
+
+**Step 4 — Verify**
+
+```bash
+meegle auth status
+```
+
+For fully unattended CI (no human-in-the-loop), inject a token via environment variables instead — see [Sandbox / CI](#sandbox--ci-direct-environment-variable-injection).
+
+## AI Agent Skill
+
+`skills/meegle/` is a drop-in **skill** that teaches AI Agents — Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI — how to operate Meegle through this CLI. It bundles the command catalog, MQL syntax, field-value conventions, rich-text Markdown rules, and standard operating procedures for common write flows.
+
+### Install
+
+```bash
+# Install the CLI first (the skill calls `meegle` under the hood)
+npm install -g @lark-project/meegle
+
+# Then add the skill — auto-detects installed agents and registers in each
+npx skills add larksuite/meegle-cli -y -g
+```
+
+`npx skills add` reads `skills/meegle/SKILL.md` from the repo and drops it into the skill directory of every agent CLI it finds on the machine. Re-run any time to pick up updates.
+
+### What it covers
+
+- **Command reference** — every `meegle` resource / method with required parameters and examples
+- **MQL search** — syntax for `workitem query`, operators, scope keywords
+- **Field values** — how to shape complex field payloads (arrays, nested JSON, date ranges)
+- **Rich text** — Markdown subset supported by Meegle's rich-text editor
+- **SOPs** — step-by-step playbooks for creating work items, transitioning nodes, transitioning states, and updating fields
+- **Auth guard** — the skill refuses to run business commands until `meegle auth status` succeeds
+
+See [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) and [skills/meegle/references/](./skills/meegle/references/) for the full contents.
+
+### Usage
+
+Once installed, just ask the agent in natural language. For example, in Trae:
+
+```
+Show me this week's P0 stories in the PROJ space.
+```
+
+The agent consults the skill, picks the right `meegle` commands, and runs them for you. Pair with `--dry-run` (see [Security](#security--risk-warnings)) to preview side-effectful operations before the agent commits them.
+
+> Heads up: the skill name `meegle` is the same string as the CLI binary. When documentation refers to "the **`meegle` skill**" it means the files in `skills/meegle/`; when it refers to "the **`meegle` CLI**" it means the `meegle` command on your PATH.
 
 ## Commands
 
@@ -60,6 +157,7 @@ self-hosted tenant domain such as `your-tenant.example.com`.
 |---------|-------------|
 | `workitem create` | Create a work item |
 | `workitem get` | View work item details |
+| `workitem +batch-get` | Batch-read work items by IDs (client-side fan-out over `workitem get`; `+` marks scenario/sugar commands) |
 | `workitem update` | Update work item fields |
 | `workitem query` | Search work items using MQL |
 | `workitem list-op-records` | View operation records |
@@ -195,18 +293,57 @@ meegle workitem get --work-item-id 12345
 meegle workflow get-node --work-item-id 12345 --need-sub-task
 ```
 
+### Batch Reading Work Items
+
+`workitem +batch-get` fans out to `workitem get` for each ID and aggregates the
+results into one response. Shared flags (e.g. `--project-key`) apply to every
+per-item call. The `+` prefix marks it as a scenario/sugar command with no 1:1
+MCP tool behind it — the CLI composes multiple `get` calls client-side.
+
+```bash
+# Comma-separated IDs in one invocation
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346,12347"
+
+# Read IDs from a file (one per line; lines starting with '#' are comments)
+meegle workitem +batch-get --project-key PROJ --ids-file ./ids.txt
+
+# Stream one JSON row per item; summary row is emitted last
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson
+```
+
+Response envelope (JSON):
+
+```json
+{
+  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
+  "results": [
+    { "work_item_id": 12345, "data": { /* ... */ } },
+    { "work_item_id": 12346, "data": { /* ... */ } },
+    { "work_item_id": 12347, "error": { "code": "...", "message": "..." } }
+  ]
+}
+```
+
+Constraints: up to 200 IDs per invocation, 3 concurrent workers (fixed).
+Partial failures do **not** abort the batch — check `summary.failed` or the
+per-item `error` field. A 401 from the server aborts the whole run.
+
 ### Creating Work Items
 
 ```bash
-# Use --set to set fields
+# Pass fields[] via --params (JSON)
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name="Optimize login flow" \
-  --set priority=P1
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Optimize login flow"},
+    {"field_key":"priority","field_value":"P1"}
+  ]}'
 
-# Pass JSON values for complex fields
+# Complex field values (arrays, nested JSON) also go through --params
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name="Scheduled task" \
-  --set schedule='[1722182400000,1722355199999]'
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Scheduled task"},
+    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
+  ]}'
 ```
 
 ### Updating Fields
@@ -214,12 +351,14 @@ meegle workitem create --project-key PROJ --work-item-type story \
 ```bash
 # Update work item name
 meegle workitem update --work-item-id 12345 \
-  --set name="New title"
+  --params '{"fields":[{"field_key":"name","field_value":"New title"}]}'
 
 # Update multiple fields at once
 meegle workitem update --work-item-id 12345 \
-  --set name="New title" \
-  --set priority=P0
+  --params '{"fields":[
+    {"field_key":"name","field_value":"New title"},
+    {"field_key":"priority","field_value":"P0"}
+  ]}'
 ```
 
 ### MQL Search
@@ -255,19 +394,31 @@ Each command takes parameters via `--flag-name`:
 meegle workitem get --work-item-id 12345 --project-key PROJ
 ```
 
-### --set key=value (Write Commands)
+### Writing `fields[]` (Write Commands)
 
-`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` support `--set` for convenient field assignment:
+`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` expect the `fields[]` payload. Pass it through `--params`:
 
 ```bash
---set name="Title"              # String
---set points=5                  # Number
---set is_urgent=true            # Boolean
---set schedule='[1,2]'          # JSON array
---set role='{"role":"RD"}'      # JSON object
+--params '{"fields":[
+  {"field_key":"name","field_value":"Title"},
+  {"field_key":"priority","field_value":"P1"}
+]}'
+```
+
+### --set key=value (Generic)
+
+`--set` is an alternate syntax for writing **top-level** parameters — `--set key=value` is equivalent to typing `--key value`. Useful when scripting with a uniform `key=value` form, or for writing nested top-level params via dot-path. Values are auto-typed (int / float / bool / string).
+
+```bash
+# These two are equivalent:
+meegle mywork todo --action this_week --page-num 1
+meegle mywork todo --set action=this_week --set page_num=1
+
+# Dot-path builds nested maps (rarely used in Meegle, but supported):
+--set extra.flag=true          # becomes {"extra":{"flag":true}}
 ```
 
-`--set` can be repeated to set multiple fields at once.
+`--set` only writes **top-level** parameters. To write a work item's `fields[]`, use `--params '{"fields":[...]}'` (see below).
 
 ### --params JSON (Fallback)
 
@@ -282,8 +433,8 @@ meegle workitem create --project-key PROJ --work-item-type story \
 
 When `--set`, `--params`, and regular flags are used together:
 
-1. `--set` overrides fields with the same name in `--params`
-2. Regular flags (e.g. `--project-key`) override top-level keys in `--params`
+1. Regular CLI flags beat `--params` / `--set` for the same top-level key
+2. `--set` overrides the same top-level key from `--params`
 
 ### Array Parameters
 
@@ -306,7 +457,7 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `yaml`, `markdown`, `raw` |
+| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `raw` |
 | `--select` | | Field projection with dot paths |
 | `--set` | | Set nested parameters (repeatable) |
 | `--params` | `-P` | Full JSON parameter body |
@@ -314,47 +465,71 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--verbose` | `-v` | Verbose output |
 | `--profile` | | Use a specific configuration profile |
 
-## Output Formats
+## Advanced Usage
+
+### Output Formats
 
 ```bash
 # JSON (default)
 meegle workitem get --work-item-id 12345
 
-# Select output properties (supports dot paths)
-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 (suitable for piping)
 meegle mywork todo --action this_week --page-num 1 -o ndjson
 
 # Table
 meegle mywork todo --action this_week --page-num 1 -o table
+```
+
+### Field Projection with `--select`
 
-# YAML
-meegle workitem get --work-item-id 12345 -o yaml
+`--select` projects fields using `.` notation. A segment after an array
+broadcasts the remaining path over every record of the array and
+collects the results while preserving the enclosing structure.
 
-# Markdown table
-meegle mywork todo --action this_week --page-num 1 -o markdown
+| Expression | Response | Projection |
+|---|---|---|
+| `list` | `{"list":[{"a":1}], "total":1}` | `{"list":[{"a":1}]}` |
+| `list.a` | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` | `{"list":[{"a":1},{"a":3}]}` |
+| `list.a,list.b` | same as above | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` (merged per index) |
+| `list.work_item_info.work_item_name` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` |
+| `nodes.0` | `{"nodes":[{"id":"a"},{"id":"b"}]}` | `{"nodes":{"0":{"id":"a"}}}` (numeric = index) |
 
-# Dry run (preview request without sending)
-meegle workitem create --project-key PROJ --work-item-type story --set name="Test" --dry-run
+```bash
+# Top-level selection
+meegle workitem get --work-item-id 12345 --select "id,name,status"
+
+# Broadcast across arrays — extract fields from nested records
+meegle mywork todo --action done --page-num 1 \
+  --select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+
+# Mix top-level metadata with broadcast — total is retained alongside projected list items
+meegle mywork todo --action done --page-num 1 \
+  --select "total,list.work_item_info.work_item_name"
 ```
 
-### --select Dot Paths
+### Metadata preservation
 
-`--select` supports `.` notation for nested properties, automatically traversing arrays:
+The default render preserves the full response shape across every
+`--format`: list endpoints return `{"list":[...], "total":N,
+"pagination":{...}}` verbatim — you see `total` / `pagination` even
+when you do not project them. Drill into records explicitly via
+`--select` (and the broadcast syntax above). Under `--format table`
+and `--format ndjson`, a single-key wrapper like `{"list":[...]}`
+(no sibling metadata) is still peeled into rows — the peel is
+loss-less.
 
-```bash
-# Extract fields from nested structures
---select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+### Dry Run
+
+For commands with side effects, preview the rendered request with `--dry-run` before executing:
 
-# Mix top-level and nested
---select "total,list.work_item_info.work_item_name"
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"Test"}]}' --dry-run
 ```
 
-## Command Introspection
+### Command Introspection
 
-Use `inspect` to view full parameter information for a command:
+Use `inspect` to view full parameter information for any command:
 
 ```bash
 # List all commands
@@ -419,6 +594,7 @@ Main config options:
 | `host` | Site domain | `project.feishu.cn`, `meegle.com` |
 | `user_access_token` | User access token; use `${VAR}` to read from an environment variable | `${CI_MEEGLE_TOKEN}` |
 | `access_token_header` | Custom HTTP header name that carries the token; empty falls back to default `Authorization: Bearer <token>` | `x-meegle-auth` |
+| `user_agent` | Caller suffix appended to the default `User-Agent` (form: `meegle-cli/<ver> <user_agent>`); supports `${VAR}` template; overridden by the `MEEGLE_USER_AGENT` env var | `my-service/1.0` |
 
 ### Sandbox / CI: Direct Environment-Variable Injection
 
@@ -427,6 +603,7 @@ Two well-known environment variables are read directly at CLI startup and overri
 ```bash
 export MEEGLE_HOST=project.feishu.cn
 export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
+export MEEGLE_USER_AGENT=ci-runner  # optional; appended to User-Agent, highest priority over config.user_agent
 meegle workitem get-brief --work_item_id 123
 ```
 
@@ -503,6 +680,26 @@ meegle auth login
 
 The command list is cached automatically and refreshed silently in the background when expired.
 
+## Security & Risk Warnings
+
+This tool is designed to be called by AI Agents to automate Meegle operations, which carries inherent risks — model hallucinations, unpredictable execution, and prompt injection. Once you authorize Meegle permissions, the Agent will act under your user identity within the granted scope, and may perform high-impact actions (field updates, status transitions, work item creation) on your behalf. Use with care.
+
+Recommended safeguards:
+
+- Preview side-effectful commands with `--dry-run` before running them
+- Use a dedicated profile (`meegle config profile create`) for Agent-driven sessions so you can audit and revoke independently
+- For CI / shared environments, prefer short-lived env-var token injection (`MEEGLE_USER_ACCESS_TOKEN`) and rotate on 401 — do not relax default security settings
+
+By using this tool you are deemed to voluntarily assume all related responsibilities.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/meegle-cli&type=Date)](https://star-history.com/#larksuite/meegle-cli&Date)
+
+## Contributing
+
+Community contributions are welcome. For bugs and feature requests, open an [Issue](https://github.com/larksuite/meegle-cli/issues) or [Pull Request](https://github.com/larksuite/meegle-cli/pulls). For major changes, please start a discussion via an Issue first.
+
 ## License
 
 This project is licensed under the **MIT License**.

package/README.zh-CN.md

@@ -1,22 +1,62 @@
 # Meegle CLI
 
-> **DEV** — 当前处于开发预览阶段，API 和命令可能发生变更。
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@lark-project/meegle.svg)](https://www.npmjs.com/package/@lark-project/meegle)
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
 
 飞书项目（[Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) / [Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)）命令行工具。在终端中管理工作项、查看排期、搜索数据，无需打开浏览器。
 
+[安装](#安装) · [快速开始](#快速开始人类用户) · [Agent Skill](#ai-agent-skill) · [命令](#命令一览) · [认证](#认证) · [配置](#配置) · [安全](#安全与风险提示) · [贡献](#贡献)
+
+## 为什么选择 Meegle CLI？
+
+- **Agent 友好** — 附带一份 [AI Agent Skill](#ai-agent-skill)，一条命令即可把 Meegle 操作手册喂给 Trae、Claude Code、Cursor、Windsurf、Gemini CLI 等主流 Agent。CLI 命令同时面向人类和 Agent 设计，结构化 JSON 输出、`--dry-run` 预览、`--device-code` 无 TTY 流程
+- **覆盖完整** — 12 个业务域（工作项、工作流、子任务、评论、工时、关联、我的工作、视图、图表、团队、用户、空间），40+ 命令映射到 Meegle 核心能力
+- **两层参数模型** — 日常用 `--flag-name` 轻便直接，复杂载荷（如 `fields[]`）用 `--params <json>` 兜底 —— 按场景选择合适粒度
+- **输出格式灵活** — 支持 `json` / `table` / `ndjson` / `raw`，配合 `--select` 点路径投影可直接 pipe 给其他工具
+- **默认安全** — 凭证存进系统 keychain、`${VAR}` 环境变量模板让 secret 不落地到 config 文件、多 profile 分离 staging / prod
+
+## 功能概览
+
+| 域                                                 | 能力                                                                                     |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| 📋 [工作项](#workitem--工作项域)                   | 创建、查看、更新、批量读、MQL 查询、查看操作记录、读元数据                               |
+| 🔀 [工作流](#workflow--工作流域)                   | 节点和状态流转、更新节点字段、列出可用流转和必填字段                                     |
+| ✅ [子任务](#subtask--子任务)                      | 创建、更新、完成、回滚子任务                                                             |
+| 💬 [评论](#comment--评论域)                        | 在工作项上添加和列出评论                                                                 |
+| ⏱️ [工时](#workhour--工时域)                       | 列出工时记录、查看团队成员排期                                                           |
+| 🔗 [关联](#relation--关系域)                       | 列出关联工作项、查看关联类型定义                                                         |
+| 📌 [我的工作](#mywork--工作台域)                   | 查看本周 / 已完成 / 逾期待办                                                             |
+| 👁️ [视图](#view--视图域)                           | 创建和更新固定视图、按名称搜索视图                                                       |
+| 📊 [图表](#chart--度量域)                          | 列出视图下的图表、查看图表详情                                                           |
+| 👥 [团队与用户](#team--user--人员域)               | 列出团队、团队成员、搜索用户、查看当前登录身份                                           |
+| 🗂️ [空间](#project--空间域)                        | 按关键词搜索空间                                                                         |
+| 🔐 [认证与配置](#认证)                             | OAuth 登录、Device Code 流程、多 profile 配置、环境变量注入                              |
+| 🤖 [Agent Skill](#ai-agent-skill)                  | 内置 skill 供 Trae / Claude Code / Cursor / Windsurf / Gemini / Copilot 使用             |
 
 ## 安装
 
+### 前置条件
+
+- Node.js >= 16（自带 `npm` / `npx`）
+
+### 安装命令
+
 ```bash
 npm install -g @lark-project/meegle
 ```
 
-要求 Node.js >= 16。
+## 快速开始（人类用户）
 
-## 快速开始
+> **给 AI Agent 的提示：** 如果你是在替用户完成这套安装的 AI Agent，请直接跳到 [快速开始（AI Agent）](#快速开始ai-agent--ci--无头环境) —— 那里有你需要的非交互步骤。
 
 ```bash
-# 1. 登录
+# （可选）持久化 host，后续登录就不用再选菜单
+meegle config set host <host>
+
+# 1. 登录（上下选择 host + 浏览器 OAuth）
 meegle auth login
 
 # 2. 查看本周待办
@@ -30,26 +70,84 @@ meegle workitem --help
 meegle inspect workitem.create
 ```
 
-## 非交互环境下的初始化（CI / Agent / Claude Code）
+## 快速开始（AI Agent / CI / 无头环境）
 
-`meegle auth login` 默认使用上下选择菜单 + Authorization Code OAuth 流程，
-两者都依赖真实终端和本地浏览器回调。在 CI Runner、管道、Claude Code 这类
-没有 TTY 的环境里会直接报错或挂起。
+`meegle auth login` 默认走上下选择菜单 + 浏览器 OAuth 回调，依赖真实 TTY，在 CI Runner、管道、Claude Code 这类没有 TTY 的环境里会挂起或报错。这些场景请改用 Device Code 流程 —— 命令会输出授权 URL，让用户在浏览器里完成授权。
 
-这些场景请改用 Device Code 流程 —— 命令会输出一个 URL，让操作者在任意浏览
-器里完成授权：
+**Step 1 — 安装 CLI**
 
 ```bash
-# 方式 A：每次显式传入 host
-meegle auth login --device-code --host <host>
+npm install -g @lark-project/meegle
+```
 
-# 方式 B：先持久化 host，再登录
+**Step 2 — 持久化 host**
+
+```bash
 meegle config set host <host>
+```
+
+`<host>` 示例：`project.feishu.cn`、`meegle.com`，或自建租户域名（如 `your-tenant.example.com`）。
+
+**Step 3 — Device Code 登录**
+
+> 建议后台执行。命令会输出授权 URL —— 提取后发给用户，用户在浏览器完成授权后命令自动退出。
+
+```bash
 meegle auth login --device-code
 ```
 
-`<host>` 示例：`project.feishu.cn`、`meegle.com`，或你的自建租户域名
-（如 `your-tenant.example.com`）。
+如不想持久化 host，也可以每次显式传入：
+
+```bash
+meegle auth login --device-code --host <host>
+```
+
+**Step 4 — 验证**
+
+```bash
+meegle auth status
+```
+
+完全无人值守的 CI（没有真人参与）请改用环境变量注入 token，参见 [沙盒 / CI](#沙盒--ci直接注入环境变量)。
+
+## AI Agent Skill
+
+`skills/meegle/` 是一份可直接加载的 **skill**，用来教 AI Agent —— Trae、Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot CLI —— 通过本 CLI 操作 Meegle。它把命令目录、MQL 语法、字段值写法、富文本 Markdown 规则，以及常见写入流程的 SOP 全部打包好。
+
+### 安装
+
+```bash
+# 先装 CLI（skill 底层会调用 meegle 命令）
+npm install -g @lark-project/meegle
+
+# 再加载 skill —— 会自动探测已装的 Agent，并在各自的 skill 目录里登记
+npx skills add larksuite/meegle-cli -y -g
+```
+
+`npx skills add` 会从仓库读取 `skills/meegle/SKILL.md`，写入本机所有 Agent CLI 的 skill 目录。每次升级重跑一遍即可拉取最新内容。
+
+### 覆盖内容
+
+- **命令参考** — 每个 `meegle` resource / method 的必填参数与示例
+- **MQL 搜索** — `workitem query` 的语法、运算符、作用域关键字
+- **字段值** — 复杂字段载荷（数组、嵌套 JSON、日期区间）的写法
+- **富文本** — Meegle 富文本编辑器支持的 Markdown 子集
+- **SOP** — 创建工作项、节点流转、状态流转、更新字段等场景的分步剧本
+- **授权守护** — 所有业务命令前强制先过 `meegle auth status`
+
+完整内容见 [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) 和 [skills/meegle/references/](./skills/meegle/references/)。
+
+### 使用方式
+
+安装后直接用自然语言和 Agent 对话。例如 Trae：
+
+```
+帮我看一下 PROJ 空间本周待办里的 P0 需求
+```
+
+Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--dry-run`（见 [安全](#安全与风险提示)）可以在 Agent 真正执行副作用前先预览请求。
+
+> 小提示：skill 的名字 `meegle` 和 CLI 二进制同名。文档里提到 **`meegle` skill** 时指 `skills/meegle/` 里的文件；提到 **`meegle` CLI** 时指你 PATH 上的 `meegle` 命令。
 
 ## 命令一览
 
@@ -59,6 +157,7 @@ meegle auth login --device-code
 |------|------|
 | `workitem create` | 创建工作项 |
 | `workitem get` | 查看工作项概况 |
+| `workitem +batch-get` | 按 ID 批量读取工作项（客户端侧在 `workitem get` 之上做扇出；`+` 前缀代表场景/语法糖命令） |
 | `workitem update` | 修改工作项字段 |
 | `workitem query` | 使用 MQL 搜索工作项 |
 | `workitem list-op-records` | 查看操作记录 |
@@ -194,18 +293,56 @@ meegle workitem get --work-item-id 12345
 meegle workflow get-node --work-item-id 12345 --need-sub-task
 ```
 
+### 批量读取工作项
+
+`workitem +batch-get` 会对每个 ID 分别调用 `workitem get` 并把结果聚合成一条响应。
+共享 flag（如 `--project-key`）会应用到每一次 per-item 调用上。命令以 `+` 开头，
+表示它是客户端侧的场景/语法糖命令，没有 1:1 对应的 MCP 工具，CLI 会在 `get` 之
+上组合出批量语义。
+
+```bash
+# 在一次调用里传入逗号分隔的多个 ID
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346,12347"
+
+# 从文件读取 ID（每行一个，以 '#' 开头的行视为注释）
+meegle workitem +batch-get --project-key PROJ --ids-file ./ids.txt
+
+# 每个 item 输出一行 JSON，summary 作为最后一行
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson
+```
+
+响应结构（JSON）：
+
+```json
+{
+  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
+  "results": [
+    { "work_item_id": 12345, "data": { /* ... */ } },
+    { "work_item_id": 12346, "data": { /* ... */ } },
+    { "work_item_id": 12347, "error": { "code": "...", "message": "..." } }
+  ]
+}
+```
+
+约束：单次调用最多 200 个 ID，固定 3 worker 并发。部分失败**不会**中断整批——
+请通过 `summary.failed` 或 per-item 的 `error` 字段判断；服务端返回 401 会终止整批。
+
 ### 创建工作项
 
 ```bash
-# 使用 --set 设置字段
+# 通过 --params 传 fields[]
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name=优化登录流程 \
-  --set priority=P1
+  --params '{"fields":[
+    {"field_key":"name","field_value":"优化登录流程"},
+    {"field_key":"priority","field_value":"P1"}
+  ]}'
 
-# 复杂字段传 JSON 值
+# 复杂字段值（数组、嵌套 JSON）也走 --params
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name=排期任务 \
-  --set schedule='[1722182400000,1722355199999]'
+  --params '{"fields":[
+    {"field_key":"name","field_value":"排期任务"},
+    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
+  ]}'
 ```
 
 ### 修改字段
@@ -213,12 +350,14 @@ meegle workitem create --project-key PROJ --work-item-type story \
 ```bash
 # 修改工作项名称
 meegle workitem update --work-item-id 12345 \
-  --set name=新标题
+  --params '{"fields":[{"field_key":"name","field_value":"新标题"}]}'
 
 # 同时修改多个字段
 meegle workitem update --work-item-id 12345 \
-  --set name=新标题 \
-  --set priority=P0
+  --params '{"fields":[
+    {"field_key":"name","field_value":"新标题"},
+    {"field_key":"priority","field_value":"P0"}
+  ]}'
 ```
 
 ### MQL 搜索
@@ -254,19 +393,31 @@ meegle user search --user-keys "张三,李四" --project-key PROJ
 meegle workitem get --work-item-id 12345 --project-key PROJ
 ```
 
-### --set key=value（写入命令）
+### 写 `fields[]`（写入命令）
 
-`workitem create`、`workitem update`、`workflow update-node`、`subtask update` 支持 `--set` 简便设置字段：
+`workitem create`、`workitem update`、`workflow update-node`、`subtask update` 需要传 `fields[]`，通过 `--params` 走：
 
 ```bash
---set name=标题              # 字符串
---set points=5               # 数字
---set is_urgent=true         # 布尔
---set schedule='[1,2]'       # JSON 数组
---set role='{"role":"RD"}'   # JSON 对象
+--params '{"fields":[
+  {"field_key":"name","field_value":"标题"},
+  {"field_key":"priority","field_value":"P1"}
+]}'
+```
+
+### --set key=value（通用）
+
+`--set` 是普通 flag 的**替代写法**，只影响**顶层参数**：`--set key=value` 等价于 `--key value`。适合在脚本里用统一的 key=value 语法，或通过 dot-path 写嵌套顶层对象。值自动类型推断（int / float / bool / string）。
+
+```bash
+# 下面两种等价：
+meegle mywork todo --action this_week --page-num 1
+meegle mywork todo --set action=this_week --set page_num=1
+
+# dot-path 嵌套（Meegle 很少用到，但支持）：
+--set extra.flag=true          # 变成 {"extra":{"flag":true}}
 ```
 
-`--set` 可重复使用，一次设置多个字段。
+`--set` 只写**顶层参数**，**不会**写到工作项的 `fields[]`。写 `fields[]` 请用 `--params '{"fields":[...]}'`（见下）。
 
 ### --params JSON（兜底）
 
@@ -281,8 +432,8 @@ meegle workitem create --project-key PROJ --work-item-type story \
 
 当 `--set`、`--params` 和普通 flag 同时使用时：
 
-1. `--set` 覆盖 `--params` 中同名字段
-2. 普通 flag（如 `--project-key`）覆盖 `--params` 中同名顶层 key
+1. 普通 CLI flag 覆盖 `--params` / `--set` 中同名顶层 key
+2. `--set` 覆盖 `--params` 中同名顶层 key
 
 ### 数组参数
 
@@ -305,7 +456,7 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 
 | Flag | 缩写 | 说明 |
 |------|------|------|
-| `--format` | `-o` | 输出格式：`json`（默认）、`table`、`ndjson`、`yaml`、`markdown`、`raw` |
+| `--format` | `-o` | 输出格式：`json`（默认）、`table`、`ndjson`、`raw` |
 | `--select` | | 字段投影（支持 dot path） |
 | `--set` | | 设置嵌套参数（可重复） |
 | `--params` | `-P` | 完整 JSON 参数体 |
@@ -313,47 +464,62 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--verbose` | `-v` | 详细输出 |
 | `--profile` | | 指定配置 profile |
 
-## 输出格式
+## 进阶用法
+
+### 输出格式
 
 ```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 -o ndjson
 
 # 表格
 meegle mywork todo --action this_week --page-num 1 -o table
+```
+
+### `--select` 字段投影
 
-# YAML
-meegle workitem get --work-item-id 12345 -o yaml
+`--select` 按 `.` 分段做字段投影；数组之后的下一段会对数组中每个元素广播（broadcast）剩余路径，并保留原来的嵌套结构。
 
-# Markdown 表格
-meegle mywork todo --action this_week --page-num 1 -o markdown
+| 表达式 | 响应 | 投影结果 |
+|---|---|---|
+| `list` | `{"list":[{"a":1}], "total":1}` | `{"list":[{"a":1}]}` |
+| `list.a` | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` | `{"list":[{"a":1},{"a":3}]}` |
+| `list.a,list.b` | 同上 | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}`（多路径按下标合并） |
+| `list.work_item_info.work_item_name` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` |
+| `nodes.0` | `{"nodes":[{"id":"a"},{"id":"b"}]}` | `{"nodes":{"0":{"id":"a"}}}`（数字段按索引） |
 
-# Dry run（预览请求，不实际发送）
-meegle workitem create --project-key PROJ --work-item-type story --set name="测试" --dry-run
+```bash
+# 顶层选择
+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,list.state_info.end_state_key_name"
+
+# 顶层元数据 + 广播混合 —— total 和投影后的 list 记录会同时保留
+meegle mywork todo --action done --page-num 1 \
+  --select "total,list.work_item_info.work_item_name"
 ```
 
-### --select dot path
+### 元数据保留
 
-`--select` 支持用 `.` 访问嵌套属性，遇到数组时自动穿透：
+默认渲染下，响应的完整结构在所有 `--format` 中都会保留：列表接口返回的 `{"list":[...], "total":N, "pagination":{...}}` 原样呈现 —— 即使你没有在 `--select` 中点名，`total` / `pagination` 这些元数据字段依然可见。要钻到具体记录就显式用 `--select`（配合上面的广播语法）。`--format table` 和 `--format ndjson` 下，形如 `{"list":[...]}` 的单键包装（没有兄弟元数据）仍然会被无损展开成行展示。
 
-```bash
-# 从嵌套结构中提取字段
---select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+### Dry Run
+
+有副作用的命令先用 `--dry-run` 预览请求再执行：
 
-# 混合顶层和嵌套
---select "total,list.work_item_info.work_item_name"
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"测试"}]}' --dry-run
 ```
 
-## 命令内省
+### 命令内省
 
-使用 `inspect` 查看命令的完整参数信息：
+用 `inspect` 查看任意命令的完整参数信息：
 
 ```bash
 # 列出所有命令
@@ -418,6 +584,7 @@ meegle config get host
 | `host` | 站点域名 | `project.feishu.cn`、`meegle.com` |
 | `user_access_token` | 用户访问令牌，支持 `${VAR}` 从环境变量读取 | `${CI_MEEGLE_TOKEN}` |
 | `access_token_header` | 自定义承载 token 的 HTTP header 名；置空则用默认的 `Authorization: Bearer <token>` | `x-meegle-auth` |
+| `user_agent` | 追加到 `User-Agent` 的 caller 段（形如 `meegle-cli/<ver> <user_agent>`）；支持 `${VAR}` 模板；被环境变量 `MEEGLE_USER_AGENT` 覆盖 | `my-service/1.0` |
 
 ### 沙盒 / CI：直接注入环境变量
 
@@ -426,6 +593,7 @@ meegle config get host
 ```bash
 export MEEGLE_HOST=project.feishu.cn
 export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
+export MEEGLE_USER_AGENT=ci-runner  # 可选；追加到 User-Agent，优先级高于 config.user_agent
 meegle workitem get-brief --work_item_id 123
 ```
 
@@ -502,6 +670,26 @@ meegle auth login
 
 命令列表会自动缓存，过期后在后台静默刷新，不影响使用。
 
+## 安全与风险提示
+
+本工具被设计为可由 AI Agent 调用来自动化 Meegle 操作，这本身就带有模型幻觉、执行不可控、提示词注入等固有风险。一旦你授予了 Meegle 访问权限，Agent 就会在授权范围内以你的用户身份行事，可能完成字段更新、状态流转、工作项创建等高影响操作，使用前请充分评估。
+
+推荐的风险控制手段：
+
+- 有副作用的命令先用 `--dry-run` 预览请求再正式执行
+- 给 Agent 专用 profile（`meegle config profile create`），便于单独审计和吊销
+- CI 或共享环境优先使用短期环境变量 token（`MEEGLE_USER_ACCESS_TOKEN`），401 时自行轮换；不要放松默认安全设置
+
+使用本工具即视为你自愿承担由此带来的全部相关责任。
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/meegle-cli&type=Date)](https://star-history.com/#larksuite/meegle-cli&Date)
+
+## 贡献
+
+欢迎社区贡献。Bug 反馈或功能建议请提 [Issue](https://github.com/larksuite/meegle-cli/issues) 或 [Pull Request](https://github.com/larksuite/meegle-cli/pulls)。对于较大改动，建议先通过 Issue 讨论。
+
 ## License
 
 本项目基于 **MIT 许可证** 开源。

package/bin/meegle.js

@@ -1,8 +1,15 @@
 #!/usr/bin/env node
 const { spawnSync } = require("child_process");
+const fs = require("fs");
 const os = require("os");
 const path = require("path");
 
+const SUPPORTED = [
+  "darwin-arm64", "darwin-x64",
+  "linux-arm64", "linux-x64",
+  "win32-arm64", "win32-x64",
+];
+
 const platform = os.platform();
 const arch = os.arch();
 const ext = platform === "win32" ? ".exe" : "";
@@ -10,15 +17,28 @@ const binName = `meegle-${platform}-${arch}${ext}`;
 const binPath = path.join(__dirname, binName);
 
 try {
-  require("fs").accessSync(binPath, require("fs").constants.X_OK);
+  fs.accessSync(binPath, fs.constants.X_OK);
 } catch {
+  const detected = `${platform}-${arch}`;
+  const isSupported = SUPPORTED.includes(detected);
   console.error(
-    `Unsupported platform: ${platform}-${arch}\n` +
-    `Expected binary at: ${binPath}\n` +
-    `Supported: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-x64, win32-arm64`
+    isSupported
+      ? `meegle binary is missing or not executable.\n` +
+        `Detected platform: ${detected}\n` +
+        `Expected binary at: ${binPath}\n` +
+        `Try reinstalling: npm i -g @lark-project/meegle\n` +
+        `If the problem persists, please file an issue with the output of: node -v && npm -v`
+      : `Unsupported platform: ${detected}\n` +
+        `Supported platforms: ${SUPPORTED.join(", ")}`
   );
   process.exit(1);
 }
 
 const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+
+// Re-raise the signal so parent shells see the real cause (e.g. 130 for SIGINT)
+// instead of a generic exit 1.
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
 process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-project/meegle",
-  "version": "0.0.17",
+  "version": "1.0.0",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
   "bin": {
@@ -23,15 +23,13 @@
     "bin/meegle-*",
     "README.md",
     "README.zh-CN.md",
+    "CHANGELOG.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
     "third_party_licenses/**"
   ],
-  "publishConfig": {
-    "tag": "beta"
-  },
   "scripts": {
-    "prepublishOnly": "cp ../../README.zh-CN.md ./README.zh-CN.md && cp ../../LICENSE ./LICENSE && cp ../../THIRD_PARTY_NOTICES.md ./THIRD_PARTY_NOTICES.md && rm -rf ./third_party_licenses && cp -R ../../third_party_licenses ./third_party_licenses && cp ../../README.md ./README.md"
+    "prepublishOnly": "cp ../../README.zh-CN.md ./README.zh-CN.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && cp ../../THIRD_PARTY_NOTICES.md ./THIRD_PARTY_NOTICES.md && rm -rf ./third_party_licenses && cp -R ../../third_party_licenses ./third_party_licenses && cp ../../README.md ./README.md"
   },
   "keywords": [
     "meegle",