Meegle CLI

English | 简体中文

飞书项目（Meegle / Lark Project）命令行工具。在终端中管理工作项、查看排期、搜索数据，无需打开浏览器。

安装 · 快速开始 · Agent Skill · 命令 · 认证 · 配置 · 安全 · 贡献

为什么选择 Meegle CLI？

• Agent 友好 — 附带一份 AI Agent Skill，一条命令即可把 Meegle 操作手册喂给 Trae、Claude Code、Cursor、Windsurf、Gemini CLI 等主流 Agent。CLI 命令同时面向人类和 Agent 设计，结构化 JSON 输出、--dry-run 预览
• 覆盖完整 — 12 个业务域（工作项、工作流、子任务、评论、工时、视图、度量、团队、用户、空间、附件、发布 / 部署任务、URL 解析），40+ 命令映射到私有化部署面
• 两层参数模型 — 日常用 --flag-name 轻便直接，复杂载荷（如 fields[]）用 --params <json> 兜底 —— 按场景选择合适粒度
• 输出格式灵活 — 支持 json / table / ndjson / raw，配合 --select 点路径投影可直接 pipe 给其他工具
• 默认安全 — 凭证存进系统 keychain、${VAR} 环境变量模板让 secret 不落地到 config 文件、多 profile 分离 staging / prod

功能概览

| 域 | 能力 | | -------------------------------------------------- | ---------------------------------------------------------------------------------------- | | 📋 工作项 | 创建、查看、更新、批量读、按字段/标题搜索、查看操作记录、读字段元数据 | | 🔀 工作流 | 节点和状态流转、更新节点字段、列出可用流转和必填字段 | | ✅ 子任务 | 在工作流节点下创建、列出、更新、完成、回滚子任务 | | 💬 评论 | 添加、列出、更新工作项评论 | | ⏱️ 工时 | 列出工时登记记录 | | 👁️ 视图 | 列出、读取、创建、更新、删除视图，支持固定视图和条件视图 | | 📊 度量 | 列出视图下的图表、查看图表详情 | | 👥 团队与用户 | 查看团队成员、搜索用户、查看当前登录身份 | | 🗂️ 空间 | 列出空间、查看空间详情、查看业务线 | | 📎 附件 | 上传文件到工作项字段、按 UUID 下载、删除 | | 🚀 发布 | release-first 部署任务面 —— list / inspect / prepare / create / execute / verify / apply-whitelist | | 🔗 URL 解析 | 离线解析飞书项目 / Meegle URL，输出 url_kind + 结构化字段 | | 🔐 认证与配置 | 远端 MCP SSO 登录、状态、多 profile 配置、环境变量注入 | | 🩺 Doctor | 当前 profile 只读诊断（运行时、网络、会话） | | 🤖 Agent Skill | 内置 skill 供 Trae / Claude Code / Cursor / Windsurf / Gemini / Copilot 使用 |

安装

前置条件

• Node.js >= 16（自带 npm / npx）

安装命令

npm install -g @tingwillforever/meegle-cli

快速开始

对于普通用户，CLI 只是已部署 Meegle MCP Server 的轻量客户端。你不需要配置 plugin 凭据、project 凭据，也不需要在本机启动 MCP runtime —— auth login 会拉起浏览器完成企业 SSO，再把 SSO ticket 交换成由 MCP Server 管理的可刷新 本地会话。

# 1. 安装 CLI
npm install -g @tingwillforever/meegle-cli

# 2. 远端 MCP SSO 登录（自动拉起浏览器）
meegle auth login

# 3. 验证会话与运行时
meegle auth status
meegle doctor --format json

如果 auth login 提示需要申请或审批访问权限，说明 SSO 已确认你的身份，但 MCP Server 还没有找到你的 active access grant。请联系管理员通过 MCP Server 的 access-request / access-grant API 审批或维护权限。

如果 doctor 没过，先把运行时/配置补齐，不要直接跑业务命令。

AI Agent Skill

skills/meegle/ 是一份可直接加载的 skill，用来教 AI Agent —— Trae、Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot CLI —— 通过已安装的 meegle CLI 操作你当前这套私有化 Meegle 部署。它已经对齐到当前验证过的私有运行时：普通用户和管理员统一通过远端 MCP Server + SSO 建立会话。

安装

先完成安装，然后注册 skill：

# 自动检测本机已安装的 Agent CLI 并逐个注册
npx -y skills add https://github.com/tingwillforever/meegle-cli-skill --skill meegle -y -g

npx skills add 会读取公开的 meegle-cli-skill mirror。该仓库由本仓库的 skills/meegle/ 目录手工同步而来，并会把 skill 注册到本机所有受支持的 Agent CLI（Trae、Claude Code、Cursor、Windsurf、Gemini CLI、Copilot CLI）。 后续 skill 同步更新后，只需重跑同一条命令。

覆盖内容

• 私有运行时指引 — remote MCP SSO 的配置与验活
• 已验证命令面 — 默认安全命令和条件命令的边界
• 当前命令配方 — 与 installed CLI schema 对齐的示例
• 字段值规则 — 私有化写入路径下的安全传参方式
• SOP — 创建、更新、workflow 操作的轻量剧本
• 安装包 E2E — 面向普通用户的维护中回归路径

完整内容见 skills/meegle/SKILL.md 和 skills/meegle/references/。

这个 skill 被刻意收敛为“私有化 installed CLI 维护工作流”。它不重新定义普通用户登录契约；普通用户默认仍应通过 meegle auth login 走 remote MCP SSO。

使用方式

安装后直接用自然语言和 Agent 对话。例如 Trae：

帮我看一下 PROJ 空间本周待办里的 P0 需求

Agent 会参考 skill，必要时先跑 meegle doctor，再自动选择合适的私有化 meegle 命令执行。配合 --dry-run（见 安全）可以在 Agent 真正执行副作用前先预览请求。

小提示：skill 的名字 meegle 和 CLI 二进制同名。文档里提到 meegle skill 时指 skills/meegle/ 里的文件；提到 meegle CLI 时指你 PATH 上的 meegle 命令。

命令一览

workitem — 工作项域

| 命令 | 说明 | |------|------| | workitem create | 创建新工作项 | | workitem get | 按 ID 查询工作项 —— 返回字段、工作流状态、元数据 | | workitem +batch-get | 按 ID 批量读取（客户端侧在 workitem get 之上做扇出；+ 前缀代表场景/语法糖命令） | | workitem update | 修改工作项字段 | | workitem search-by-params | 在空间内按字段级条件做高级搜索 | | workitem search-filter | 在空间内按名称/标题过滤搜索 | | workitem search-filter-across | 跨多个空间按名称过滤搜索 | | workitem list-op-records | 查看操作历史 / 审计记录 | | workitem meta-types | 列出空间下的工作项类型 | | workitem meta-create-fields | 列出创建时可用的字段元数据 | | workitem meta-fields | 列出空间的字段配置 | | workitem meta-roles | 列出工作项类型的流程角色 | | workitem abort | 终止工作项（⚠️ destructive） | | workitem restore | 恢复已终止的工作项 | | workitem freeze | 冻结工作项，禁止修改（⚠️ destructive） | | workitem unfreeze | 解冻已冻结的工作项 | | workitem remove | 永久删除工作项（⚠️ 不可逆） |

workflow — 工作流域

| 命令 | 说明 | |------|------| | workflow transition | 节点流转或回滚（节点流） | | workflow transition-state | 状态流模式下流转工作项到新状态 | | workflow update-node | 更新节点元数据 —— 排期、负责人、字段 | | workflow list-state-transitions | 查询工作项的节点、状态、负责人和可执行流转 | | workflow list-state-required | 查看流转所需的必填字段 |

subtask — 子任务

| 命令 | 说明 | |------|------| | subtask create | 在工作流节点下创建子任务 | | subtask list | 列出节点下的子任务 | | subtask update | 修改子任务名称、负责人、排期、备注 | | subtask operate | 确认（完成）或回滚一个子任务 | | subtask search | 跨空间搜索子任务 |

comment — 评论域

| 命令 | 说明 | |------|------| | comment add | 添加评论（纯文本或富文本） | | comment list | 查看工作项评论列表 | | comment update | 修改已存在的评论 | | comment remove | 删除评论（⚠️ destructive） |

workhour — 工时域

| 命令 | 说明 | |------|------| | workhour list-records | 查看工时登记记录 |

view — 视图域

| 命令 | 说明 | |------|------| | view list | 列出空间下的视图配置；返回 view_type（0=系统列表，1=条件/全景，2=固定） | | view items | 读取系统/固定列表视图条目（通常 view_type=0 或 2） | | view create-fixed | 创建固定视图 | | view update-fixed | 更新固定视图 | | view delete | 删除固定视图或条件视图 | | view create-condition | 创建条件视图，支持指定筛选条件 | | view update-condition | 更新条件视图的名称或筛选条件 |

chart — 度量域

| 命令 | 说明 | |------|------| | chart list | 列出视图下的图表 | | chart get | 查看图表详情 |

team / user — 人员域

| 命令 | 说明 | |------|------| | team list-members | 查看空间团队成员 | | user me | 查看当前登录用户信息 | | user query | 按 user_key / out_id / email 查询用户详情 | | user resolve | 把用户标识符解析为显示名 | | whoami | 查看当前登录身份（顶层快捷命令） |

space — 空间域

| 命令 | 说明 | |------|------| | space list | 列出当前用户可访问的所有空间 | | space detail | 按 key 查询指定空间的详细信息 | | space business-lines | 查看空间下的业务线 |

attachment — 附件域

| 命令 | 说明 | |------|------| | attachment upload | 上传文件并附加到工作项字段 | | attachment upload-file | 上传通用文件（富文本图片、附件字段） | | attachment download | 按 UUID 下载附件 | | attachment delete | 删除附件（destructive） |

release — 发布部署任务

| 命令 | 说明 | |------|------| | release deploy-task-list | 列出发布单下的部署任务 | | release deploy-task-inspect | 查看部署任务详情，包含 pod 状态和不一致告警 | | release deploy-task-prepare | 基于 appName / iBuildId 准备 Kubelink 部署任务创建载荷 | | release deploy-task-create | 创建 release-oriented 部署任务 | | release deploy-task-execute | 执行部署 | | release deploy-task-verify | 执行部署校验 | | release deploy-task-apply-white-list | 在用户显式确认后应用白名单 |

url — URL 解析

| 命令 | 说明 | |------|------| | url decode | 离线解析飞书项目 / Meegle URL，返回 url_kind + 结构化字段 |

auth — 认证域

| 命令 | 说明 | |------|------| | auth login | 发起远端 MCP SSO 登录（基于浏览器） | | auth status | 查看登录状态 | | auth logout | 登出，并在可达时撤销远端会话 |

config — 配置域

| 命令 | 说明 | |------|------| | config init | 初始化配置 | | config show | 查看当前配置 | | config set | 设置配置项 | | config get | 读取配置项 | | config profile create\|list\|use\|current\|delete | 管理多环境 profile |

其他命令

| 命令 | 说明 | |------|------| | doctor | 当前 profile 只读诊断 | | inspect [command] | 查看命令参数详情（如 inspect workitem.create） | | version | 打印 CLI 版本号 | | completion bash\|zsh\|fish | 生成 Shell 补全脚本 | | completion install | 自动安装 Shell 补全 |

部署任务

部署任务能力采用 release-first 命令面，普通用户和 AI Agent 都应先走发布单语义层，再在必要时下降到 Kubelink 原子工具层。

推荐流程：

1. meegle doctor --format json
2. meegle release deploy-task-list --project-key PROJ --release-id RELEASE_ID --format json
3. 如果需要确认某个具体任务或 Pod 状态，再执行 meegle release deploy-task-inspect --project-key PROJ --release-id RELEASE_ID --recordID RECORD_ID --format json
4. meegle release deploy-task-prepare ... --format json
5. 只有在上下文明确后，才进入 release deploy-task-create、release deploy-task-execute、release deploy-task-verify
6. 如果 execute 返回加白指引，先和用户确认，再执行 release deploy-task-apply-white-list，等审批完成后重试 execute

命令状态建议：

• release deploy-task-prepare
• release deploy-task-list
• release deploy-task-inspect

这些是 verified，可以作为默认安全的首选入口。

• release deploy-task-create
• release deploy-task-execute
• release deploy-task-apply-white-list
• release deploy-task-verify

这些是 conditional。如果参数形状不明确，先执行 meegle inspect <resource>.<method>，不要在 Agent 场景里盲跑。

高级降级入口：

• 发布相关动作统一走 release 资源组 —— 它已经覆盖完整的发布部署任务面
• 如果出现 release 层无法表达的后端 Kubelink 动作，应反馈给维护者而不是寻找未上线的 integration 命令

常用示例

查询工作项

# 查看工作项概况
meegle workitem get \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --work-item-ids 12345

# 查看工作流当前状态、节点、负责人和可执行流转
meegle workflow list-state-transitions \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --work-item-id 12345

批量读取工作项

workitem +batch-get 会对每个 ID 分别调用 workitem get 并把结果聚合成一条响应。 共享 flag（如 --project-key）会应用到每一次 per-item 调用上。命令以 + 开头， 表示它是客户端侧的场景/语法糖命令，没有 1:1 对应的 MCP 工具，CLI 会在 get 之 上组合出批量语义。

# 在一次调用里传入逗号分隔的多个 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）：

{
  "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 会终止整批。

创建工作项

# 必填 flag + 通过 --params 追加 fields[]
meegle workitem create \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --name "优化登录流程" \
  --params '{"fields":[
    {"field_key":"priority","field_value":"P1"}
  ]}'

# 复杂字段值（数组、嵌套 JSON）也走 --params
meegle workitem create \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --name "排期任务" \
  --params '{"fields":[
    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
  ]}'

修改字段

workitem update 必填 --work-item-id、--project-key、--work-item-type-key。 字段值通过 --update-fields（每条 key=value）或 --params 传复杂载荷。

# 通过 --update-fields 修改单个字段
meegle workitem update \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --work-item-id 12345 \
  --update-fields 'name=新标题'

# 通过 JSON 同时修改多个字段
meegle workitem update \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --work-item-id 12345 \
  --params '{"update_fields":[
    {"field_key":"name","field_value":"新标题"},
    {"field_key":"priority","field_value":"P0"}
  ]}'

工作项搜索

# 在空间内按名称过滤一个或多个工作项类型
meegle workitem search-filter \
  --project-key PROJ \
  --work-item-type-keys STORY_TYPE_KEY \
  --work-item-name "登录"

# 按字段级条件做高级搜索
meegle workitem search-by-params \
  --project-key PROJ \
  --work-item-type-key STORY_TYPE_KEY \
  --params '{"search_params":{"conditions":[
    {"field_key":"priority","operator":"=","value":"P0"}
  ]}}'

查看用户信息

# 查看当前登录用户
meegle user query --user-keys "current_login_user()"

# 按邮箱查询
meegle user query --emails "[email protected],[email protected]"

部署任务

# 1. 先验证运行时
meegle doctor --format json

# 2. 列出发布单下的 deploy tasks
meegle release deploy-task-list \
  --project-key PROJ \
  --release-id RELEASE_ID \
  --format json

# 3. 查看单个 deploy task 详情（含 pod 状态）
meegle release deploy-task-inspect \
  --recordID RECORD_ID \
  --format json

# 4. 准备 deploy-task 创建载荷
meegle release deploy-task-prepare \
  --project-key PROJ \
  --release-id RELEASE_ID \
  --appName APP_NAME \
  --format json

# 5. 用户确认后申请加白
meegle release deploy-task-apply-white-list \
  --project-key PROJ \
  --release-id RELEASE_ID \
  --recordIDs RECORD_ID \
  --format json

参数传递

基本 flag

每个命令的参数通过 --flag-name 传递：

meegle workitem get --work-item-id 12345 --project-key PROJ

写 fields[]（写入命令）

workitem create、workitem update、workflow update-node、subtask update 需要传 fields[]，通过 --params 走：

--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）。

# 下面两种等价：
meegle workitem search-filter --project-key PROJ --work-item-type-keys WORK_ITEM_TYPE_KEY --work-item-name 测试
meegle workitem search-filter --set project_key=PROJ --set work_item_type_keys=WORK_ITEM_TYPE_KEY --set work_item_name=测试

# dot-path 嵌套（Meegle 很少用到，但支持）：
--set extra.flag=true          # 变成 {"extra":{"flag":true}}

--set 只写顶层参数，不会写到工作项的 fields[]。写 fields[] 请用 --params '{"fields":[...]}'（见下）。

--params JSON（兜底）

所有命令都支持 --params 传入完整 JSON 参数：

meegle workitem create \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --name "标题" \
  --params '{"fields":[{"field_key":"priority","field_value":"P1"}]}'

优先级

当 --set、--params 和普通 flag 同时使用时：

1. 普通 CLI flag 覆盖 --params / --set 中同名顶层 key
2. --set 覆盖 --params 中同名顶层 key

数组参数

多个值用逗号分隔：

--user-keys "张三,李四,王五"
--field-keys "name,status,priority"

全局 Flag

| Flag | 缩写 | 说明 | |------|------|------| | --format | -o | 输出格式：json（默认）、table、ndjson、raw | | --select | | 字段投影（支持 dot path） | | --set | | 设置嵌套参数（可重复） | | --params | -P | 完整 JSON 参数体 | | --dry-run | | 只渲染请求，不实际执行 | | --verbose | -v | 详细输出 | | --profile | | 指定配置 profile |

进阶用法

输出格式

# JSON（默认）
meegle workitem get --project-key PROJ --work-item-type-key WORK_ITEM_TYPE_KEY --work-item-ids 12345

# NDJSON（适合管道处理）
meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson

# 表格
meegle workitem search-filter --project-key PROJ --work-item-type-keys WORK_ITEM_TYPE_KEY --work-item-name 测试 -o table

--select 字段投影

--select 按 . 分段做字段投影；数组之后的下一段会对数组中每个元素广播（broadcast）剩余路径，并保留原来的嵌套结构。

| 表达式 | 响应 | 投影结果 | |---|---|---| | 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"}}}（数字段按索引） |

# 顶层选择
meegle workitem get \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --work-item-ids 12345 \
  --select "data.id,data.name,data.current_nodes"

# 跨数组广播 —— 从嵌套记录里提取字段
meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" \
  --select "results.work_item_id,results.data.name"

# 顶层元数据 + 广播混合
meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" \
  --select "summary.total,results.data.name"

元数据保留

默认渲染下，响应的完整结构在所有 --format 中都会保留：列表接口返回的 {"list":[...], "total":N, "pagination":{...}} 原样呈现 —— 即使你没有在 --select 中点名，total / pagination 这些元数据字段依然可见。要钻到具体记录就显式用 --select（配合上面的广播语法）。--format table 和 --format ndjson 下，形如 {"list":[...]} 的单键包装（没有兄弟元数据）仍然会被无损展开成行展示。

Dry Run

有副作用的命令先用 --dry-run 预览请求再执行：

meegle workitem create \
  --project-key PROJ \
  --work-item-type-key WORK_ITEM_TYPE_KEY \
  --name "测试" \
  --params '{"fields":[{"field_key":"priority","field_value":"P2"}]}' \
  --dry-run

命令内省

用 inspect 查看任意命令的完整参数信息：

# 列出所有命令
meegle inspect

# 查看特定命令的参数详情
meegle inspect workitem.create

认证

对于本仓库的私有化部署，普通用户默认走前面快速开始里的远端 MCP SSO 路径：

• 执行 meegle auth login
• 正式安装包默认使用内置的生产 MCP 地址
• 仅本地调试或预发覆盖时使用 meegle config set mcp_server_url ...
• 用 meegle auth status 查看当前会话状态

完成登录后，先执行 meegle doctor --format json。如果 doctor 没过，先修配置，再跑业务命令。

普通用户远端 MCP SSO 登录示例：

meegle auth login
meegle auth status

首次引导 / 单次覆盖示例：

meegle config set mcp_server_url http://127.0.0.1:62059/mcp
meegle auth login

# 或者仅单次覆盖 endpoint
meegle auth login --mcp-server-url https://mcp.example.com/mcp
meegle auth status

通用 OAuth / Device Code 流程

仓库仍然保留 meegle auth login 和 meegle auth login --device-code，但这不是当前私有化部署的默认文档路径。 这些流程在显式传入 --project-key 时也可以持久化默认空间，但当前私有化部署默认仍应使用 remote MCP SSO。

配置

配置文件

配置存储在 ~/.meegle/config.json：

# 初始化配置
meegle config init

# 查看当前配置
meegle config show

# 修改单个配置项
meegle config set host project.feishu.cn

# 查看单个配置项
meegle config get host

主要配置项：

| 字段 | 说明 | 示例 | |------|------|------| | mcp_server_url | 可选的远端 MCP 地址覆盖项，供 SSO / session 流程使用。正式包内置生产地址时，普通用户应保持未配置。 | https://mcp.example.com/mcp | | project_key | 默认协作空间；当后续命令省略 --project-key 时会自动注入 | cbg_product_develop | | 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 |

维护者发包检查项

发布普通用户安装包前：

• 将 internal/products/meegle/config.go 里的 DefaultRemoteMCPServerURL 改为生产 /mcp 地址
• 使用 make publish PRIVATE_NPM_PACKAGE_NAME=@tingwillforever/meegle-cli 发包
• 在干净 shell 中安装 staged 或已发布包，执行 meegle auth login
• 确认 meegle auth status 显示活跃会话和正确账号 / 范围
• 普通用户侧保持 mcp_server_url 未配置；该配置只用于本地或预发覆盖
• 需要完整维护者流程和发版时覆盖项时，查看 docs/maintenance/private-npm-release.md

沙盒 / CI：直接注入环境变量

若是通用 token 型 CI，也支持下面这组环境变量：

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 切换：

meegle config set access_token_header x-meegle-auth

或通过环境变量临时覆盖：

export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth

启用后 CLI 会以 <header>: <token> 发送裸值（无 Bearer 前缀），并且完全不发送 Authorization header —— 适用于对两种 header 共存敏感的后端。

环境变量模板

如果平台使用的环境变量名不是 MEEGLE_*，可以在 config.json 中用 ${VAR} 占位符绑定任意字符串字段，运行时会用同名环境变量的值替换。这样既能避免在 config.json 里明文写敏感值，也能适配不同容器/CI 平台各自的变量命名习惯。

{
  "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

支持管理多个环境配置（不同站点、不同账号），每个 profile 独立存储 host 和认证信息。

# 创建新环境（交互式引导 host 选择 + 登录）
meegle config profile create staging

# 查看所有环境
meegle config profile list

# 切换默认环境
meegle config profile use staging

# 查看当前环境
meegle config profile current

# 临时使用其他环境（不改变默认）
meegle workitem search-filter --project-key PROJ --work-item-type-keys WORK_ITEM_TYPE_KEY --work-item-name 测试 --profile staging

# 删除环境
meegle config profile delete staging

常见问题

命令列表为空

CLI 启动时会从服务端获取可用命令列表。如果网络不通或私有化运行时没配完整，动态命令不会注册。请先确认远端 MCP 地址和登录态已经就绪：

meegle doctor --format json

命令列表会自动缓存，过期后在后台静默刷新，不影响使用。

安全与风险提示

本工具被设计为可由 AI Agent 调用来自动化 Meegle 操作，这本身就带有模型幻觉、执行不可控、提示词注入等固有风险。一旦你授予了 Meegle 访问权限，Agent 就会在授权范围内以你的用户身份行事，可能完成字段更新、状态流转、工作项创建等高影响操作，使用前请充分评估。

推荐的风险控制手段：

• 有副作用的命令先用 --dry-run 预览请求再正式执行
• 给 Agent 专用 profile（meegle config profile create），便于单独审计和吊销
• CI 或共享环境优先使用短期环境变量 token（MEEGLE_USER_ACCESS_TOKEN），401 时自行轮换；不要放松默认安全设置

使用本工具即视为你自愿承担由此带来的全部相关责任。

Star History

贡献

欢迎社区贡献。Bug 反馈或功能建议请提 Issue 或 Pull Request。对于较大改动，建议先通过 Issue 讨论。

License

本项目基于 MIT 许可证 开源。

该软件运行时会调用 Lark/飞书开放平台的 API，使用这些 API 需要遵守如下协议和隐私政策：

• 飞书用户服务协议
• 飞书隐私政策
• 飞书开放平台应用服务商安全管理规范
• Lark User Terms of Service
• Lark Privacy Policy