@lark-project/meegle 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project will be documented in this file.
 
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+post-release changes accumulate under `[Unreleased]` and graduate to a
+versioned section on each npm release.
+
+## [Unreleased]
+
+## [v1.0.2] - 2026-05-14
+
+### Added
+
+- New `view list-multi-project-workitems` command exposing the upstream `list_multi_project_view_workitems` MCP tool — lists work items the caller can access under a multi-project ("panoramic") view, identified by a `multiProjectView` URL's `view_id`; takes `--project-key`, `--view-id`, and an optional `--page-num` (50 items per page, 1-based)
+- Top-level parameters merged via `--params` / `--set` are now validated against the tool's declared flag set. Unknown arguments emit a one-line stderr warning at run time and appear under `validation.unknown_params` in `--dry-run` output, pointing users at `--params '{"fields":[...]}'` for work-item field values. Validation is advisory: unknown keys are still forwarded to the backend so a stale local tool-schema cache cannot block legitimate calls (refresh with `--refresh`)
+
+### Changed
+
+- Clarified `--params` documentation: the built-in flag's `--help` description and the README now state that top-level keys are merged as CLI flags (not a free-form payload), with a common-pitfall example showing that work-item field values must be wrapped in `fields[]`
+
+## [v1.0.1] - 2026-04-28
+
+### Added
+
+- New `attachment` domain exposing Lark project's two-stage attachment protocol — basic `attachment prepare-upload` / `attachment prepare-download` for raw signed-URL preprocess payloads, and end-to-end shortcuts `attachment +upload` / `attachment +download` that chain the preprocess with the signed HTTP transfer client-side. Supports four resource types via `--resource-type`: `15` (workitem attachment field), `16` (rich-text field image), `13` (comment attachment), `14` (comment image); use `--work-item-id` for existing workitems and `--work-item-type` for the create-with-attachment path
+- `meegle url decode` subcommand for parsing Meego URLs into structured fields, including trailing-wildcard URL rules and a `setting_other` fallback for unknown views
+- `--params @file.json` syntax on every dynamic command so complex JSON payloads can be loaded from a file instead of a shell-escaped string
+- `--refresh` global flag forces a fresh tool-schema discovery, bypassing the `~/.meegle/cache/tools.json` cache; `auth login` now also invalidates the cache so the next invocation picks up the new identity's command set
+
+### Fixed
+
+- Tool-schema cache now honors its 24h `DefaultTTL`. Previously `resolveTools` returned any cache hit regardless of age, so server-side schema changes (new flags, renamed parameters, new commands) only surfaced after manually deleting `~/.meegle/cache/tools.json`. A stale cache now triggers a fresh discovery, falling back to the stale snapshot only when the server is unreachable so offline users keep their last-known command set
+- `meegle auth status` and the first-run auth check now route through the same `ResolveIdentity` path as runtime commands, so config-file tokens, env-var tokens, and store-backed tokens are treated consistently
+- The OS-native credential store (macOS keychain, Linux `secret-tool`, Windows DPAPI) is now wrapped in a `FallbackStore` that transparently switches to the encrypted file store on the first runtime Save/Load failure — fixes the silent token-loss in sandboxed macOS, locked-keychain SSH sessions, and headless Linux containers reported in [larksuite/meegle-cli#3](https://github.com/larksuite/meegle-cli/issues/3) without writing a sentinel probe entry to the user's keychain on every CLI invocation
+- `SecretToolStore.Load` no longer treats libsecret's "item absent from keyring" exit (exit 1, empty stdout, empty stderr) as a primary-store failure, so a fresh Linux user's first CLI run no longer permanently flips `FallbackStore` to the encrypted file store
+- Failed token-store writes after a successful refresh are no longer silently dropped — a stderr warning is emitted so the next CLI invocation does not silently re-trigger a 401 / re-login loop
+
 ## [v1.0.0] - 2026-04-22
 
 Initial public release of Meegle CLI, published on npm as `@lark-project/meegle`.

package/README.md

@@ -13,7 +13,7 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 ## 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
+- **Broad Coverage** — 13 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project, attachments) 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
@@ -33,7 +33,9 @@ Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=r
 | 📊 [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                                                                     |
+| 📎 [Attachments](#attachment--attachments)         | Two-stage upload/download protocol — `prepare-*` basic commands plus `+upload` / `+download` end-to-end shortcuts |
 | 🔐 [Auth & Config](#authentication)                | OAuth login, device-code flow, multi-profile config, env-var injection                         |
+| 🔗 [URL Parsing](#url--url-parsing)                | Offline decode of Meegle / Feishu Project URLs into `url_kind` + structured fields             |
 | 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
 
 ## Installation
@@ -219,6 +221,7 @@ The agent consults the skill, picks the right `meegle` commands, and runs them f
 | `view get` | View details of a view |
 | `view update-fixed` | Update a fixed view |
 | `view search` | Search views by name |
+| `view list-multi-project-workitems` | List work items under a multi-project (panoramic) view |
 
 ### chart — Charts
 
@@ -242,6 +245,15 @@ The agent consults the skill, picks the right `meegle` commands, and runs them f
 |---------|-------------|
 | `project search` | Search projects |
 
+### attachment — Attachments
+
+| Command | Description |
+|---------|-------------|
+| `attachment prepare-upload` | Upload preprocess — returns the signed object-storage URL and multipart plan |
+| `attachment prepare-download` | Download preprocess — returns the signed object-storage URL and multipart plan |
+| `attachment +upload` | End-to-end upload: preprocess + signed HTTP POST(s); returns the resulting `file_token` and file metadata |
+| `attachment +download` | End-to-end download: preprocess + signed HTTP GET(s) + atomic write — for `file_url`s embedded in `workitem get` / `comment list` responses |
+
 ### auth — Authentication
 
 | Command | Description |
@@ -260,6 +272,14 @@ The agent consults the skill, picks the right `meegle` commands, and runs them f
 | `config get` | Get a configuration value |
 | `config profile create\|list\|use\|current\|delete` | Manage configuration profiles |
 
+### url — URL Parsing
+
+Offline, no-network utility for parsing Meegle / Feishu Project URLs into structured fields. Skills and pipelines branch on the returned `url_kind` instead of guessing from raw paths.
+
+| Command | Description |
+|---------|-------------|
+| `url decode --url <URL>` | Decode a URL into `url_kind` + `simple_name` / `work_item_type` / `work_item_id` / `view_id` / `chart_id` / `query` / `redirected_from` etc. Unrecognised URLs return `url_kind: "unknown"`. |
+
 ### Other Commands
 
 | Command | Description |
@@ -297,8 +317,9 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 
 `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.
+per-item call. The `+` prefix marks it as a scenario/sugar command — the CLI
+composes multiple `get` calls client-side instead of mapping to a single
+backend endpoint.
 
 ```bash
 # Comma-separated IDs in one invocation
@@ -361,6 +382,102 @@ meegle workitem update --work-item-id 12345 \
   ]}'
 ```
 
+### Attachments
+
+The `attachment` domain exposes Lark project's two-stage attachment protocol
+in two layers:
+
+- **Basic commands** (`attachment prepare-upload`, `attachment prepare-download`)
+  return the raw signed-URL preprocess payload — handy for scripting your own
+  HTTP transfer or inspecting the multipart plan.
+- **Shortcuts** (`attachment +upload`, `attachment +download`) chain the basic
+  preprocess with the signed HTTP POST/GET to object storage end-to-end. The
+  `+` prefix marks them as scenario commands — the CLI orchestrates the
+  preprocess output plus the out-of-band byte transfer client-side.
+
+`--resource-type` tells the backend what the file will be attached to:
+
+| `--resource-type` | Target |
+|-------------------|--------|
+| `15` | Workitem attachment field |
+| `16` | Image embedded in a workitem rich-text field |
+| `13` | Attachment on a comment |
+| `14` | Image embedded in a comment |
+
+**Scoping the preprocess**: every upload needs either `--work-item-id` or
+`--work-item-type`. **Always prefer `--work-item-id`** when the target workitem
+exists (update / comment scenarios); only use `--work-item-type` for the
+create-with-attachment path where the workitem hasn't been created yet. If
+both are supplied, `--work-item-id` wins and `--work-item-type` is ignored.
+
+```bash
+# Upload a file for a workitem attachment field (resource-type 15)
+meegle attachment +upload ./a.pdf \
+  --resource-type 15 \
+  --project-key PROJ --work-item-id 12345 --field-key files_field
+
+# Create-with-attachment path — workitem doesn't exist yet, pass --work-item-type
+meegle attachment +upload ./a.pdf \
+  --resource-type 15 \
+  --project-key PROJ --work-item-type story --field-key files_field
+
+# Upload an image for a rich-text field (resource-type 16)
+meegle attachment +upload ./diagram.png \
+  --resource-type 16 \
+  --project-key PROJ --work-item-id 12345 --field-key spec_field
+
+# Upload a comment attachment (resource-type 13)
+meegle attachment +upload ./report.pdf \
+  --resource-type 13 \
+  --project-key PROJ --work-item-id 12345
+
+# Upload a comment image (resource-type 14)
+meegle attachment +upload ./screen.png \
+  --resource-type 14 \
+  --project-key PROJ --work-item-id 12345
+
+# Download: pass the opaque file_url from another command's response.
+URL=$(meegle workitem get --project-key PROJ --work-item-id 12345 \
+        --fields files_field --format json \
+      | jq -r '.fields.files_field[0].url')
+meegle attachment +download "$URL" \
+  --project-key PROJ --work-item-id 12345 \
+  --output ./local.pdf --overwrite
+```
+
+`+upload` returns a JSON object with the file token and metadata:
+
+```json
+{
+  "file_token": "...",
+  "file_url": "https://...",
+  "name": "a.pdf",
+  "size": 12345,
+  "mime_type": "application/pdf"
+}
+```
+
+To wire the result into a downstream command, parse the response with `jq`
+or your scripting language of choice:
+
+```bash
+# Comment attachment — comment add takes file_token directly
+TOKEN=$(meegle attachment +upload ./report.pdf --resource-type 13 \
+        --project-key PROJ --work-item-id 12345 | jq -r '.file_token')
+meegle comment add --work-item-id 12345 --content "See attached" --file-token "$TOKEN"
+```
+
+**Field-level attachment formats** (how to assemble `--fields` payloads):
+
+- **Workitem attachment field** (`--resource-type 15`) — `field_value` is a
+  JSON *string* whose parsed form is `[{"name","type","size","fileToken"}]`.
+  Note: `fileToken` is camelCase (other backend fields are snake_case) and
+  `size` is a string, not a number.
+- **Rich-text field / comment image** (`--resource-type 16` / `14`) — embed
+  images as `![name](file_url) <!-- file_token -->`.
+- **Comment attachment** (`--resource-type 13`) — `comment add --file-token`
+  takes `file_token` directly.
+
 ### MQL Search
 
 ```bash
@@ -394,17 +511,6 @@ Each command takes parameters via `--flag-name`:
 meegle workitem get --work-item-id 12345 --project-key PROJ
 ```
 
-### Writing `fields[]` (Write Commands)
-
-`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` expect the `fields[]` payload. Pass it through `--params`:
-
-```bash
---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).
@@ -420,15 +526,76 @@ meegle mywork todo --set action=this_week --set page_num=1
 
 `--set` only writes **top-level** parameters. To write a work item's `fields[]`, use `--params '{"fields":[...]}'` (see below).
 
-### --params JSON (Fallback)
+### --params JSON
 
-All commands support `--params` to pass a full JSON parameter body:
+`--params` takes a JSON object; **each top-level key is merged in as a CLI flag**.
+The key must be a valid flag of the current command — it is not a free-form payload.
+
+```bash
+# These two are equivalent:
+meegle workitem get --work-item-id 12345 --project-key PROJ
+meegle workitem get --params '{"work_item_id":12345,"project_key":"PROJ"}'
+```
+
+Use `--params` when:
+
+- the value is a nested object or array (`fields[]`, `schedule{}`) — too awkward to inline as a flag
+- you want to set many parameters at once, or feed a payload from a file (see `@file.json` below)
 
 ```bash
 meegle workitem create --project-key PROJ --work-item-type story \
   --params '{"fields":[{"field_key":"name","field_value":"Title"}]}'
 ```
 
+#### Common pitfall: not every name is a top-level flag
+
+Some values that *look* like top-level fields are actually work-item field
+values, and must be wrapped in `fields[]` rather than placed at the top
+level. For example, on `workitem update` the `priority` value belongs to
+the work item's fields, not to the command's flags:
+
+```bash
+# ❌ "priority" is not a flag of workitem update — CLI prints a stderr warning, backend ignores it
+meegle workitem update --work-item-id 12345 --params '{"priority":"P1"}'
+
+# ✓ Wrap field values inside fields[]
+meegle workitem update --work-item-id 12345 \
+  --params '{"fields":[{"field_key":"priority","field_value":"P1"}]}'
+```
+
+The CLI surfaces unknown top-level keys as a `validation.unknown_params`
+list under `--dry-run`, and as a one-line stderr warning at run time. They
+are still forwarded to the backend (in case your local tool-schema cache
+is stale — refresh with `--refresh`).
+
+Run `meegle workitem meta-fields --project-key PK --work-item-type TK`
+to look up valid `field_key`s for a work item type.
+
+#### Reading from a file (`@file.json`)
+
+Inline JSON is unergonomic on Windows because CMD requires `\"` escaping
+and PowerShell mangles backslashes when forwarding native-command arguments.
+Prefix the value with `@` to load the JSON from a file instead — works
+identically on macOS, Linux, and Windows shells:
+
+```bash
+# body.json:
+# {"fields":[{"field_key":"name","field_value":"Optimize login flow"}]}
+
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params @body.json
+
+# Absolute path also works
+meegle workitem update --work-item-id 12345 --params @/tmp/patch.json
+
+# PowerShell — same syntax, no escaping headaches
+meegle workitem create --project-key PROJ --work-item-type story --params '@body.json'
+```
+
+The path is read with the OS's default encoding; both relative and absolute
+paths are accepted. A missing file fails with `PARAM_INVALID`; a file whose
+contents are not valid JSON fails with `INVALID_PARAMS_JSON`.
+
 ### Priority
 
 When `--set`, `--params`, and regular flags are used together:
@@ -460,10 +627,11 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--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 |
+| `--params` | `-P` | Full JSON parameter body; prefix with `@` to read from a file (e.g. `--params @body.json`) |
 | `--dry-run` | | Render request without executing |
 | `--verbose` | `-v` | Verbose output |
 | `--profile` | | Use a specific configuration profile |
+| `--refresh` | | Refresh cached commands from server (bypass the local 24 h cache) |
 
 ## Advanced Usage
 
@@ -604,10 +772,10 @@ Two well-known environment variables are read directly at CLI startup and overri
 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
+meegle workitem get --work-item-id 123
 ```
 
-Either variable may be set independently. When this path is taken, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value.
+Either variable may be set independently. When `MEEGLE_USER_ACCESS_TOKEN` is set, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value. Setting only `MEEGLE_HOST` (without a token) still uses the keychain-stored credentials.
 
 ### Custom Auth Header
 

package/README.zh-CN.md

@@ -13,7 +13,7 @@
 ## 为什么选择 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 核心能力
+- **覆盖完整** — 13 个业务域（工作项、工作流、子任务、评论、工时、关联、我的工作、视图、图表、团队、用户、空间、附件），40+ 命令映射到 Meegle 核心能力
 - **两层参数模型** — 日常用 `--flag-name` 轻便直接，复杂载荷（如 `fields[]`）用 `--params <json>` 兜底 —— 按场景选择合适粒度
 - **输出格式灵活** — 支持 `json` / `table` / `ndjson` / `raw`，配合 `--select` 点路径投影可直接 pipe 给其他工具
 - **默认安全** — 凭证存进系统 keychain、`${VAR}` 环境变量模板让 secret 不落地到 config 文件、多 profile 分离 staging / prod
@@ -33,7 +33,9 @@
 | 📊 [图表](#chart--度量域)                          | 列出视图下的图表、查看图表详情                                                           |
 | 👥 [团队与用户](#team--user--人员域)               | 列出团队、团队成员、搜索用户、查看当前登录身份                                           |
 | 🗂️ [空间](#project--空间域)                        | 按关键词搜索空间                                                                         |
+| 📎 [附件](#attachment--附件域)                     | 两段式上传/下载协议 —— `prepare-*` 基础命令 + `+upload` / `+download` 端到端快捷命令     |
 | 🔐 [认证与配置](#认证)                             | OAuth 登录、Device Code 流程、多 profile 配置、环境变量注入                              |
+| 🔗 [URL 解析](#url--url-解析)                      | 离线解析飞书项目 / Meegle URL，输出 `url_kind` + 结构化字段                              |
 | 🤖 [Agent Skill](#ai-agent-skill)                  | 内置 skill 供 Trae / Claude Code / Cursor / Windsurf / Gemini / Copilot 使用             |
 
 ## 安装
@@ -219,6 +221,7 @@ Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--
 | `view get` | 查看视图详情 |
 | `view update-fixed` | 更新固定视图 |
 | `view search` | 按名称搜索视图 |
+| `view list-multi-project-workitems` | 查看全景视图（multiProjectView）下的工作项列表 |
 
 ### chart — 度量域
 
@@ -242,6 +245,15 @@ Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--
 |------|------|
 | `project search` | 搜索空间信息 |
 
+### attachment — 附件域
+
+| 命令 | 说明 |
+|------|------|
+| `attachment prepare-upload` | 上传预处理 —— 返回带签名的对象存储 URL 与分片计划 |
+| `attachment prepare-download` | 下载预处理 —— 返回带签名的对象存储 URL 与分片计划 |
+| `attachment +upload` | 端到端上传：预处理 + 签名 HTTP POST，返回 `file_token` 与文件元信息 |
+| `attachment +download` | 端到端下载：预处理 + 签名 HTTP GET + 原子写文件，用于消费 `workitem get` / `comment list` 返回的 `file_url` |
+
 ### auth — 认证域
 
 | 命令 | 说明 |
@@ -260,6 +272,14 @@ Agent 会参考 skill，自动选择合适的 `meegle` 命令执行。配合 `--
 | `config get` | 读取配置项 |
 | `config profile create\|list\|use\|current\|delete` | 管理多环境 profile |
 
+### url — URL 解析
+
+离线、纯本地的 URL 解析工具，不发起任何网络调用。Skill 或 pipeline 解析飞书项目/Meegle URL 时优先走本命令，拿 `url_kind` 做分支，避免从原始路径猜字段。
+
+| 命令 | 说明 |
+|------|------|
+| `url decode --url <URL>` | 将 URL 解析为 `url_kind` + `simple_name` / `work_item_type` / `work_item_id` / `view_id` / `chart_id` / `query` / `redirected_from` 等字段；未识别的 URL 返回 `url_kind: "unknown"`。 |
+
 ### 其他命令
 
 | 命令 | 说明 |
@@ -297,8 +317,8 @@ 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` 之
-上组合出批量语义。
+表示它是客户端侧的场景/语法糖命令，CLI 在 `get` 之上组合出批量语义，没有对应的
+单一后端接口。
 
 ```bash
 # 在一次调用里传入逗号分隔的多个 ID
@@ -360,6 +380,96 @@ meegle workitem update --work-item-id 12345 \
   ]}'
 ```
 
+### 附件上传 / 下载
+
+`attachment` 域把飞书项目的两段式附件协议拆成两层暴露：
+
+- **基础命令**（`attachment prepare-upload` / `attachment prepare-download`）
+  返回带签名的 URL 预处理结果——适合自己写脚本做 HTTP 传输或调试分片计划。
+- **快捷命令**（`attachment +upload` / `attachment +download`）把基础预处理与
+  签名后的对象存储 HTTP POST/GET 在客户端组合成端到端流程。`+` 前缀表示这是
+  场景命令——CLI 在客户端把预处理输出与字节传输串起来。
+
+`--resource-type` 告诉后端这次上传/下载是给什么场景用：
+
+| `--resource-type` | 用途 |
+|-------------------|------|
+| `15` | 工作项附件字段 |
+| `16` | 工作项富文本字段里的图片 |
+| `13` | 评论附件 |
+| `14` | 评论正文里的图片 |
+
+**上传作用域**：每次上传需要 `--work-item-id` 或 `--work-item-type` 之一。
+**只要工作项已经存在，就优先用 `--work-item-id`**（update / comment 场景）；
+只有创建时带附件这种"工作项还不存在"的场景才用 `--work-item-type`。两者都传时，
+`--work-item-id` 胜出，`--work-item-type` 被静默丢弃。
+
+```bash
+# 为工作项附件字段上传文件 (resource-type 15)
+meegle attachment +upload ./a.pdf \
+  --resource-type 15 \
+  --project-key PROJ --work-item-id 12345 --field-key files_field
+
+# 创建时带附件场景 —— 工作项还不存在，用 --work-item-type
+meegle attachment +upload ./a.pdf \
+  --resource-type 15 \
+  --project-key PROJ --work-item-type story --field-key files_field
+
+# 为富文本字段上传图片 (resource-type 16)
+meegle attachment +upload ./diagram.png \
+  --resource-type 16 \
+  --project-key PROJ --work-item-id 12345 --field-key spec_field
+
+# 为评论上传附件 (resource-type 13)
+meegle attachment +upload ./report.pdf \
+  --resource-type 13 \
+  --project-key PROJ --work-item-id 12345
+
+# 为评论上传图片 (resource-type 14)
+meegle attachment +upload ./screen.png \
+  --resource-type 14 \
+  --project-key PROJ --work-item-id 12345
+
+# 下载：把其他命令响应里的 opaque file_url 直接传进来。
+URL=$(meegle workitem get --project-key PROJ --work-item-id 12345 \
+        --fields files_field --format json \
+      | jq -r '.fields.files_field[0].url')
+meegle attachment +download "$URL" \
+  --project-key PROJ --work-item-id 12345 \
+  --output ./local.pdf --overwrite
+```
+
+`+upload` 输出 JSON 对象，包含 file_token 与文件元信息：
+
+```json
+{
+  "file_token": "...",
+  "file_url": "https://...",
+  "name": "a.pdf",
+  "size": 12345,
+  "mime_type": "application/pdf"
+}
+```
+
+要把结果拼到下游命令里，用 `jq` 或脚本语言提取所需字段：
+
+```bash
+# 评论附件 —— comment add 直接接收 file_token
+TOKEN=$(meegle attachment +upload ./report.pdf --resource-type 13 \
+        --project-key PROJ --work-item-id 12345 | jq -r '.file_token')
+meegle comment add --work-item-id 12345 --content "看附件" --file-token "$TOKEN"
+```
+
+**字段级回灌格式**（拼接 `--fields` 时参考）：
+
+- **工作项附件字段** (`--resource-type 15`) —— `field_value` 是 JSON *字符串*，
+  解析后是 `[{"name","type","size","fileToken"}]`。注意：`fileToken` 是驼峰（其他
+  后端字段都是蛇形），`size` 是字符串不是数字。
+- **富文本字段 / 评论图片** (`--resource-type 16` / `14`) —— 图片用
+  `![name](file_url) <!-- file_token -->` 的 markdown 嵌入。
+- **评论附件** (`--resource-type 13`) —— `comment add --file-token` 直接接收
+  `file_token`。
+
 ### MQL 搜索
 
 ```bash
@@ -393,17 +503,6 @@ meegle user search --user-keys "张三,李四" --project-key PROJ
 meegle workitem get --work-item-id 12345 --project-key PROJ
 ```
 
-### 写 `fields[]`（写入命令）
-
-`workitem create`、`workitem update`、`workflow update-node`、`subtask update` 需要传 `fields[]`，通过 `--params` 走：
-
-```bash
---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）。
@@ -419,15 +518,70 @@ meegle mywork todo --set action=this_week --set page_num=1
 
 `--set` 只写**顶层参数**，**不会**写到工作项的 `fields[]`。写 `fields[]` 请用 `--params '{"fields":[...]}'`（见下）。
 
-### --params JSON（兜底）
+### --params JSON
+
+`--params` 接收一个 JSON 对象，**每个顶层 key 都会作为 CLI flag 合并进来**。
+顶层 key 必须是当前命令的合法 flag —— 它不是一份自由结构的载荷。
 
-所有命令都支持 `--params` 传入完整 JSON 参数：
+```bash
+# 下面两条等价：
+meegle workitem get --work-item-id 12345 --project-key PROJ
+meegle workitem get --params '{"work_item_id":12345,"project_key":"PROJ"}'
+```
+
+什么时候用 `--params`：
+
+- 值是嵌套对象或数组（`fields[]`、`schedule{}`），直接写 flag 太别扭
+- 想一次性批量传多个参数，或者从文件加载载荷（见下方 `@file.json`）
 
 ```bash
 meegle workitem create --project-key PROJ --work-item-type story \
   --params '{"fields":[{"field_key":"name","field_value":"标题"}]}'
 ```
 
+#### 常见误用：不是所有名字都是顶层 flag
+
+有些**看起来像**顶层字段的值，其实是工作项的字段值，必须包在 `fields[]`
+里，而不是放在顶层。比如 `workitem update` 时，`priority` 属于工作项字段，
+不是命令的 flag：
+
+```bash
+# ❌ "priority" 不是 workitem update 的合法 flag —— CLI 会在 stderr 输出 warning，后端忽略
+meegle workitem update --work-item-id 12345 --params '{"priority":"P1"}'
+
+# ✓ 字段值要包在 fields[] 里
+meegle workitem update --work-item-id 12345 \
+  --params '{"fields":[{"field_key":"priority","field_value":"P1"}]}'
+```
+
+不在工具声明 flag 列表里的顶层 key，在 `--dry-run` 输出里会以
+`validation.unknown_params` 列出，运行时则会向 stderr 打一行
+warning。它们仍然会被原样转发给后端（防止本地工具 schema 缓存陈旧
+误判，需要时用 `--refresh` 刷新）。
+
+通过 `meegle workitem meta-fields --project-key PK --work-item-type TK`
+查询某种工作项类型下合法的 `field_key`。
+
+#### 从文件读取（`@file.json`）
+
+Windows 上内联 JSON 体验很糟：CMD 必须把 `"` 写成 `\"`，PowerShell 把转义反斜杠传给原生命令时还会再吞一层。给 `--params` 加 `@` 前缀即可改为从文件读取，macOS、Linux、Windows 各种 shell 都能一致工作：
+
+```bash
+# body.json:
+# {"fields":[{"field_key":"name","field_value":"优化登录流程"}]}
+
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params @body.json
+
+# 绝对路径同样支持
+meegle workitem update --work-item-id 12345 --params @/tmp/patch.json
+
+# PowerShell 用法相同，无需任何转义
+meegle workitem create --project-key PROJ --work-item-type story --params '@body.json'
+```
+
+读取走系统默认编码，相对路径与绝对路径都接受。文件不存在会返回 `PARAM_INVALID`；文件内容不是合法 JSON 会返回 `INVALID_PARAMS_JSON`。
+
 ### 优先级
 
 当 `--set`、`--params` 和普通 flag 同时使用时：
@@ -459,10 +613,11 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--format` | `-o` | 输出格式：`json`（默认）、`table`、`ndjson`、`raw` |
 | `--select` | | 字段投影（支持 dot path） |
 | `--set` | | 设置嵌套参数（可重复） |
-| `--params` | `-P` | 完整 JSON 参数体 |
+| `--params` | `-P` | 完整 JSON 参数体；以 `@` 开头改为从文件读取（如 `--params @body.json`） |
 | `--dry-run` | | 只渲染请求，不实际执行 |
 | `--verbose` | `-v` | 详细输出 |
 | `--profile` | | 指定配置 profile |
+| `--refresh` | | 从服务端刷新本地命令缓存（旁路 24 小时缓存） |
 
 ## 进阶用法
 
@@ -594,10 +749,10 @@ meegle config get host
 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
+meegle workitem get --work-item-id 123
 ```
 
-任一变量可以单独设置。走这个路径时 CLI 不访问 keychain，401 错误不会自动 refresh，由调用方自行轮转。
+任一变量可以单独设置。当 `MEEGLE_USER_ACCESS_TOKEN` 设置时，CLI 不访问 keychain，401 错误不会自动 refresh，由调用方自行轮转。仅设置 `MEEGLE_HOST`（不带 token）时仍走 keychain 中存储的凭证。
 
 ### 自定义 Auth Header
 

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@lark-project/meegle",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
+  "homepage": "https://github.com/larksuite/meegle-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/larksuite/meegle-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/larksuite/meegle-cli/issues"
+  },
   "bin": {
     "meegle": "bin/meegle.js"
   },