@lark-project/meegle 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -8,6 +8,18 @@ versioned section on each npm release.
 
 ## [Unreleased]
 
+## [v1.0.9] - 2026-06-11
+
+### Added
+
+- `attachment +download` now performs an extra integrity check on the downloaded file and aborts — writing nothing to disk — when the file fails validation or cannot be verified. A failed check returns a `CLIENT_FILE_SIGN_MISMATCH` error and an unverifiable response returns `CLIENT_FILE_SIGN_UNVERIFIED`; both carry a retry hint.
+
+## [v1.0.8] - 2026-06-09
+
+### Added
+
+- `--envelope` now surfaces the backend `logid` under `meta.logid` when present. Previously the MCP server emitted the trace id as a `logid:` content entry, which the CLI stripped into `Response.LogID` but only forwarded to `slog.Debug` — and since no default slog handler is configured, the id was silently dropped. Oncall now has a way to ask end users for an argos-lookupable trace id: re-run with `--envelope` and read `meta.logid`. The id is still suppressed without `--envelope` so default output stays clean for piping. Only covers the single-call path for now; batch (`+batch-get`) per-row logid remains a follow-up
+
 ## [v1.0.7] - 2026-06-09
 
 ### Fixed

package/README.md

@@ -474,6 +474,18 @@ meegle attachment +download "$URL" \
   --output ./local.pdf --overwrite
 ```
 
+**Integrity check (`+download`)**: `+download` performs an extra integrity check
+on each downloaded file and aborts — writing nothing — if the file fails
+validation or cannot be verified. On a failed check you get a
+`CLIENT_FILE_SIGN_MISMATCH` error (unverifiable response →
+`CLIENT_FILE_SIGN_UNVERIFIED`); both are transient, so just retry.
+
+**Custom headers / env routing**: any custom headers configured for the active
+profile are applied to the download GET as well as the preprocess call, so an
+environment-routing header pins the whole download to the same environment. Auth
+headers are stripped before the GET so the token never reaches the
+object-storage host.
+
 `+upload` returns a JSON object with the file token and metadata:
 
 ```json
@@ -658,6 +670,7 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--set` | | Set nested parameters (repeatable) |
 | `--params` | `-P` | Full JSON parameter body; prefix with `@` to read from a file (e.g. `--params @body.json`) |
 | `--dry-run` | | Render request without executing |
+| `--envelope` | | Wrap success output as `{data, meta, error}` — `meta.logid` carries the backend trace id when present |
 | `--verbose` | `-v` | Verbose output |
 | `--profile` | | Use a specific configuration profile |
 | `--refresh` | | Refresh cached commands from server (bypass the local 24 h cache) |
@@ -715,6 +728,21 @@ and `--format ndjson`, a single-key wrapper like `{"list":[...]}`
 (no sibling metadata) is still peeled into rows — the peel is
 loss-less.
 
+### Tracing with `--envelope`
+
+When something looks wrong (silent success, unexpected payload) and you
+want to ask oncall to trace the exact call, add `--envelope`:
+
+```bash
+meegle workflow update-node --work-item-id 12345 \
+  --set node_schedule.points=10 --envelope
+```
+
+The success output is wrapped as `{data, meta, error}`, and `meta.logid`
+carries the backend trace id (when the server returns one). Hand that id
+to oncall to look up the request in argos. Without `--envelope` the id is
+suppressed so the default output stays clean for piping.
+
 ### Dry Run
 
 For commands with side effects, preview the rendered request with `--dry-run` before executing:

package/README.zh-CN.md

@@ -468,6 +468,15 @@ meegle attachment +download "$URL" \
   --output ./local.pdf --overwrite
 ```
 
+**完整性校验（`+download`）**：`+download` 会对下载的文件做一次额外的完整性校验，
+若校验失败或无法校验则中止下载、不写任何文件。校验不通过时返回
+`CLIENT_FILE_SIGN_MISMATCH` 错误（无法校验时为 `CLIENT_FILE_SIGN_UNVERIFIED`）；
+两者都是临时问题，重试即可。
+
+**自定义头 / 环境路由**：当前 profile 配置的自定义头会同时作用于下载 GET 与预处理调用，
+从而用环境路由头把整条下载固定到同一环境。GET 前会剥掉 auth 相关头，
+确保 token 不会发到对象存储所在的主机。
+
 `+upload` 输出 JSON 对象，包含 file_token 与文件元信息：
 
 ```json
@@ -644,6 +653,7 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--set` | | 设置嵌套参数（可重复） |
 | `--params` | `-P` | 完整 JSON 参数体；以 `@` 开头改为从文件读取（如 `--params @body.json`） |
 | `--dry-run` | | 只渲染请求，不实际执行 |
+| `--envelope` | | 将成功输出包装为 `{data, meta, error}` —— 后端返回 logid 时挂在 `meta.logid` |
 | `--verbose` | `-v` | 详细输出 |
 | `--profile` | | 指定配置 profile |
 | `--refresh` | | 从服务端刷新本地命令缓存（旁路 24 小时缓存） |
@@ -692,6 +702,20 @@ meegle mywork todo --action done --page-num 1 \
 
 默认渲染下，响应的完整结构在所有 `--format` 中都会保留：列表接口返回的 `{"list":[...], "total":N, "pagination":{...}}` 原样呈现 —— 即使你没有在 `--select` 中点名，`total` / `pagination` 这些元数据字段依然可见。要钻到具体记录就显式用 `--select`（配合上面的广播语法）。`--format table` 和 `--format ndjson` 下，形如 `{"list":[...]}` 的单键包装（没有兄弟元数据）仍然会被无损展开成行展示。
 
+### 通过 `--envelope` 拿到 logid
+
+遇到"返回 success 但实际没生效"、"输出不符合预期"等情况，需要让 oncall
+按 logid 反查具体调用时，加上 `--envelope`：
+
+```bash
+meegle workflow update-node --work-item-id 12345 \
+  --set node_schedule.points=10 --envelope
+```
+
+成功输出会被包装为 `{data, meta, error}`，后端返回 logid 时挂在
+`meta.logid` 里——把这个 id 交给 oncall 就能在 argos 定位到这次请求。
+不加 `--envelope` 时 logid 会被抑制，保持默认输出干净便于管道处理。
+
 ### Dry Run
 
 有副作用的命令先用 `--dry-run` 预览请求再执行：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-project/meegle",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
   "homepage": "https://github.com/larksuite/meegle-cli#readme",