@lark-project/meegle 0.0.16 → 1.0.0

package/README.zh-CN.md

@@ -1,21 +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. 查看本周待办
@@ -29,6 +70,85 @@ meegle workitem --help
 meegle inspect workitem.create
 ```
 
+## 快速开始（AI Agent / CI / 无头环境）
+
+`meegle auth login` 默认走上下选择菜单 + 浏览器 OAuth 回调，依赖真实 TTY，在 CI Runner、管道、Claude Code 这类没有 TTY 的环境里会挂起或报错。这些场景请改用 Device Code 流程 —— 命令会输出授权 URL，让用户在浏览器里完成授权。
+
+**Step 1 — 安装 CLI**
+
+```bash
+npm install -g @lark-project/meegle
+```
+
+**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，也可以每次显式传入：
+
+```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` 命令。
+
 ## 命令一览
 
 ### workitem — 工作项域
@@ -37,6 +157,7 @@ meegle inspect workitem.create
 |------|------|
 | `workitem create` | 创建工作项 |
 | `workitem get` | 查看工作项概况 |
+| `workitem +batch-get` | 按 ID 批量读取工作项（客户端侧在 `workitem get` 之上做扇出；`+` 前缀代表场景/语法糖命令） |
 | `workitem update` | 修改工作项字段 |
 | `workitem query` | 使用 MQL 搜索工作项 |
 | `workitem list-op-records` | 查看操作记录 |
@@ -172,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]}
+  ]}'
 ```
 
 ### 修改字段
@@ -191,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 搜索
@@ -232,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` 可重复使用，一次设置多个字段。
+### --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` 只写**顶层参数**，**不会**写到工作项的 `fields[]`。写 `fields[]` 请用 `--params '{"fields":[...]}'`（见下）。
 
 ### --params JSON（兜底）
 
@@ -259,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
 
 ### 数组参数
 
@@ -283,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 参数体 |
@@ -291,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
 
-# 混合顶层和嵌套
---select "total,list.work_item_info.work_item_name"
+有副作用的命令先用 `--dry-run` 预览请求再执行：
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"测试"}]}' --dry-run
 ```
 
-## 命令内省
+### 命令内省
 
-使用 `inspect` 查看命令的完整参数信息：
+用 `inspect` 查看任意命令的完整参数信息：
 
 ```bash
 # 列出所有命令
@@ -394,6 +582,57 @@ 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：直接注入环境变量
+
+`MEEGLE_HOST` 和 `MEEGLE_USER_ACCESS_TOKEN` 两个约定名环境变量会在 CLI 启动时被直接读取，覆盖 profile 中的同名字段，无需任何 `config set`：
+
+```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
+```
+
+任一变量可以单独设置。走这个路径时 CLI 不访问 keychain，401 错误不会自动 refresh，由调用方自行轮转。
+
+### 自定义 Auth Header
+
+默认情况下 token 通过标准 `Authorization: Bearer <token>` 发送。若后端要求把 token 放到别的 header 里（且不允许带 `Authorization`），用 `access_token_header` 切换：
+
+```bash
+meegle config set access_token_header x-meegle-auth
+```
+
+或通过环境变量临时覆盖：
+
+```bash
+export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth
+```
+
+启用后 CLI 会以 `<header>: <token>` 发送裸值（无 `Bearer ` 前缀），并且**完全不发送** `Authorization` header —— 适用于对两种 header 共存敏感的后端。
+
+### 环境变量模板
+
+如果平台使用的环境变量名不是 `MEEGLE_*`，可以在 config.json 中用 `${VAR}` 占位符绑定任意字符串字段，运行时会用同名环境变量的值替换。这样既能避免在 config.json 里明文写敏感值，也能适配不同容器/CI 平台各自的变量命名习惯。
+
+```json
+{
+  "current": "prod",
+  "profiles": {
+    "prod":    { "host": "project.feishu.cn", "user_access_token": "${PROD_CI_TOKEN}" },
+    "staging": { "host": "staging.feishu.cn", "user_access_token": "${STAGING_CI_TOKEN}" }
+  }
+}
+```
+
+规则：
+- 仅识别**整串形态**的占位符。`"${X}"` 会被展开；`"Bearer ${X}"` 按字面量处理，不展开。
+- 引用的环境变量未设置或为空时 CLI **fail fast**，错误信息会带上字段路径和变量名。
+- 当配置了 `user_access_token` 时，它会覆盖 `meegle auth login` 在本地 keychain 里写入的令牌。由于这种模式下没有本地 refresh 能力，服务端返回 401 时需要自行轮转环境变量值。
 
 ### 多环境 Profile
 
@@ -431,6 +670,34 @@ 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 © Lark Technologies Pte. Ltd.
+本项目基于 **MIT 许可证** 开源。
+
+该软件运行时会调用 Lark/飞书开放平台的 API，使用这些 API 需要遵守如下协议和隐私政策：
+
+- [飞书用户服务协议](https://www.feishu.cn/terms)
+- [飞书隐私政策](https://www.feishu.cn/privacy)
+- [飞书开放平台应用服务商安全管理规范](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+- [Lark User Terms of Service](https://www.larksuite.com/user-terms-of-service)
+- [Lark Privacy Policy](https://www.larksuite.com/privacy-policy)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,76 @@
+# Third-Party Notices
+
+This product — the `meegle` CLI distributed via the `@lark-project/meegle`
+npm package and the standalone Go binaries under `dist/` — includes third-party
+open-source software. Each component is listed below with its project URL,
+license type, copyright holder, and the path to the full license text shipped
+in the `third_party_licenses/` directory.
+
+If you redistribute this product, you must retain this file and the
+`third_party_licenses/` directory.
+
+Inventory was generated with `go-licenses report ./cmd/meegle` against the
+module graph pinned by `go.mod` / `go.sum`.
+
+---
+
+## Components
+
+### Direct dependencies
+
+| Component | Version | License | Copyright | License file |
+|---|---|---|---|---|
+| [github.com/spf13/cobra](https://github.com/spf13/cobra) | v1.9.1 | Apache-2.0 | The Cobra Authors | [third_party_licenses/github.com/spf13/cobra/LICENSE.txt](third_party_licenses/github.com/spf13/cobra/LICENSE.txt) |
+| [github.com/spf13/pflag](https://github.com/spf13/pflag) | v1.0.6 | BSD-3-Clause | (c) 2012 Alex Ogier; (c) 2012 The Go Authors | [third_party_licenses/github.com/spf13/pflag/LICENSE](third_party_licenses/github.com/spf13/pflag/LICENSE) |
+| [github.com/olekukonko/tablewriter](https://github.com/olekukonko/tablewriter) | v1.1.4 | MIT | (C) 2014 Oleku Konko | [third_party_licenses/github.com/olekukonko/tablewriter/LICENSE.md](third_party_licenses/github.com/olekukonko/tablewriter/LICENSE.md) |
+| [github.com/mdp/qrterminal/v3](https://github.com/mdp/qrterminal) | v3.2.1 | MIT | (c) 2019 Mark Percival | [third_party_licenses/github.com/mdp/qrterminal/v3/LICENSE](third_party_licenses/github.com/mdp/qrterminal/v3/LICENSE) |
+| [github.com/pkg/browser](https://github.com/pkg/browser) | v0.0.0-20240102092130-5ac0b6a4141c | BSD-2-Clause | (c) 2014 Dave Cheney | [third_party_licenses/github.com/pkg/browser/LICENSE](third_party_licenses/github.com/pkg/browser/LICENSE) |
+| [golang.org/x/crypto](https://cs.opensource.google/go/x/crypto) | v0.33.0 | BSD-3-Clause | (c) 2009 The Go Authors | [third_party_licenses/golang.org/x/crypto/pbkdf2/LICENSE](third_party_licenses/golang.org/x/crypto/pbkdf2/LICENSE) |
+| [golang.org/x/sys](https://cs.opensource.google/go/x/sys) | v0.30.0 | BSD-3-Clause | (c) 2009 The Go Authors | [third_party_licenses/golang.org/x/sys/unix/LICENSE](third_party_licenses/golang.org/x/sys/unix/LICENSE) |
+| [golang.org/x/term](https://cs.opensource.google/go/x/term) | v0.29.0 | BSD-3-Clause | (c) 2009 The Go Authors | [third_party_licenses/golang.org/x/term/LICENSE](third_party_licenses/golang.org/x/term/LICENSE) |
+| [gopkg.in/yaml.v3](https://github.com/go-yaml/yaml) | v3.0.1 | MIT + Apache-2.0 | (c) 2011-2016 Canonical Ltd; (c) 2006-2011 Kirill Simonov | [third_party_licenses/gopkg.in/yaml.v3/LICENSE](third_party_licenses/gopkg.in/yaml.v3/LICENSE) · [NOTICE](third_party_licenses/gopkg.in/yaml.v3/NOTICE) |
+
+### Transitive dependencies
+
+| Component | Version | License | Copyright | License file |
+|---|---|---|---|---|
+| [github.com/cespare/xxhash/v2](https://github.com/cespare/xxhash) | v2.3.0 | MIT | (c) 2016 Caleb Spare | [third_party_licenses/github.com/cespare/xxhash/v2/LICENSE.txt](third_party_licenses/github.com/cespare/xxhash/v2/LICENSE.txt) |
+| [github.com/clipperhouse/displaywidth](https://github.com/clipperhouse/displaywidth) | v0.10.0 | MIT | (c) 2025 Matt Sherman | [third_party_licenses/github.com/clipperhouse/displaywidth/LICENSE](third_party_licenses/github.com/clipperhouse/displaywidth/LICENSE) |
+| [github.com/clipperhouse/uax29/v2](https://github.com/clipperhouse/uax29) | v2.6.0 | MIT | (c) 2020 Matt Sherman | [third_party_licenses/github.com/clipperhouse/uax29/v2/graphemes/LICENSE](third_party_licenses/github.com/clipperhouse/uax29/v2/graphemes/LICENSE) |
+| [github.com/fatih/color](https://github.com/fatih/color) | v1.18.0 | MIT | (c) 2013 Fatih Arslan | [third_party_licenses/github.com/fatih/color/LICENSE.md](third_party_licenses/github.com/fatih/color/LICENSE.md) |
+| [github.com/mattn/go-colorable](https://github.com/mattn/go-colorable) | v0.1.14 | MIT | (c) 2016 Yasuhiro Matsumoto | [third_party_licenses/github.com/mattn/go-colorable/LICENSE](third_party_licenses/github.com/mattn/go-colorable/LICENSE) |
+| [github.com/mattn/go-isatty](https://github.com/mattn/go-isatty) | v0.0.20 | MIT | (c) Yasuhiro Matsumoto | [third_party_licenses/github.com/mattn/go-isatty/LICENSE](third_party_licenses/github.com/mattn/go-isatty/LICENSE) |
+| [github.com/mattn/go-runewidth](https://github.com/mattn/go-runewidth) | v0.0.19 | MIT | (c) 2016 Yasuhiro Matsumoto | [third_party_licenses/github.com/mattn/go-runewidth/LICENSE](third_party_licenses/github.com/mattn/go-runewidth/LICENSE) |
+| [github.com/olekukonko/cat](https://github.com/olekukonko/cat) | v0.0.0-20250911104152-50322a0618f6 | MIT | (c) 2025 Oleku Konko | [third_party_licenses/github.com/olekukonko/cat/LICENSE](third_party_licenses/github.com/olekukonko/cat/LICENSE) |
+| [github.com/olekukonko/errors](https://github.com/olekukonko/errors) | v1.2.0 | MIT | (c) 2025 Oleku Konko | [third_party_licenses/github.com/olekukonko/errors/LICENSE](third_party_licenses/github.com/olekukonko/errors/LICENSE) |
+| [github.com/olekukonko/ll](https://github.com/olekukonko/ll) | v0.1.6 | MIT | (c) 2025 Oleku Konko | [third_party_licenses/github.com/olekukonko/ll/LICENSE](third_party_licenses/github.com/olekukonko/ll/LICENSE) |
+| [rsc.io/qr](https://github.com/rsc/qr) | v0.2.0 | BSD-3-Clause | (c) 2009 The Go Authors | [third_party_licenses/rsc.io/qr/LICENSE](third_party_licenses/rsc.io/qr/LICENSE) |
+
+> `github.com/inconshreveable/mousetrap` v1.1.0 (Apache-2.0) is a transitive
+> dependency of `cobra` that is only compiled into the Windows binary. Its
+> license text is bundled with the `win32-*` distributions when applicable.
+
+---
+
+## Go standard library
+
+The Go standard library, runtime, and toolchain-provided packages are
+distributed under the BSD-3-Clause license (© The Go Authors). See
+<https://go.dev/LICENSE>. These are not enumerated individually above.
+
+---
+
+## How to refresh this file
+
+```bash
+go install github.com/google/go-licenses@latest
+
+# Inventory (CSV)
+go-licenses report ./cmd/meegle
+
+# Full license texts on disk
+go-licenses save ./cmd/meegle --save_path=./third_party_licenses --force
+
+# Supply-chain safety gate
+go-licenses check ./cmd/meegle --disallowed_types=forbidden,restricted
+```

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.16",
+  "version": "1.0.0",
   "description": "Agent-First CLI for Meegle (Lark Project)",
   "license": "MIT",
   "bin": {
@@ -23,13 +23,13 @@
     "bin/meegle-*",
     "README.md",
     "README.zh-CN.md",
-    "LICENSE"
+    "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 ../../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",