@tingwillforever/meegle-cli 1.0.0-dev.20260519131637322

package/README.zh-CN.md

@@ -0,0 +1,753 @@
+# Meegle CLI
+
+[![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/)
+[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` 预览
+- **覆盖完整** — 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--空间域)                        | 按关键词搜索空间                                                                         |
+| 🔐 [认证与配置](#认证)                             | 远端 MCP SSO 配置、多 profile 配置、环境变量注入                                       |
+| 🤖 [Agent Skill](#ai-agent-skill)                  | 内置 skill 供 Trae / Claude Code / Cursor / Windsurf / Gemini / Copilot 使用             |
+
+## 安装
+
+### 前置条件
+
+- Node.js >= 16（自带 `npm` / `npx`）
+
+### 安装命令
+
+使用具备 package 读取权限的 GitHub token 安装已发布的包：
+
+```bash
+npm config set @tingwillforever:registry https://npm.pkg.github.com
+npm config set //npm.pkg.github.com/:_authToken <github_pat_with_read_packages>
+npm install -g @tingwillforever/meegle-cli@latest
+```
+
+## 快速开始
+
+对于普通用户，CLI 只是已部署 Meegle MCP Server 的轻量客户端。你不需要配置
+plugin 凭据、project 凭据，也不需要在本机启动 MCP runtime。
+
+```bash
+# 1. 发起普通用户远端 MCP SSO 登录
+meegle auth login
+
+# 2. 查看服务端返回的当前授权摘要
+meegle auth whoami --format table
+
+# 3. 验证安装结果和运行时状态
+meegle version
+meegle doctor --format json
+```
+
+`auth login` 会拉起浏览器完成企业 SSO，再把 SSO ticket 交换成由 MCP
+Server 管理的本地可刷新会话。正式安装包应内置生产 MCP 地址。只有本地调试、
+预发验证或临时引导时，才需要设置 `mcp_server_url` 或显式传
+`--mcp-server-url ...`。
+
+`auth whoami` 会展示当前登录域账号、Meegle user key，以及服务端下发的项目和业务线授权范围。
+
+如果登录提示需要申请或审批访问权限，说明 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：
+
+```bash
+npx -y skills add tingwillforever/meegle-cli --skill meegle -y -g
+```
+
+私有仓库安装前提：
+
+- 机器本身必须已经有 `tingwillforever/meegle-cli` 的访问权限
+- `skills add` 会 clone 私有 GitHub 仓库，因此用户应先完成 GitHub 认证，例如 `gh auth login`，或确保本机 git/SSH 已能访问该仓库
+
+### 覆盖内容
+
+- **私有运行时指引** — remote MCP SSO 的配置与验活
+- **已验证命令面** — 默认安全命令和条件命令的边界
+- **当前命令配方** — 与 installed CLI schema 对齐的示例
+- **字段值规则** — 私有化写入路径下的安全传参方式
+- **SOP** — 创建、更新、workflow 操作的轻量剧本
+- **安装包 E2E** — 面向普通用户的维护中回归路径
+
+完整内容见 [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) 和 [skills/meegle/references/](./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` | 查看工作项概况 |
+| `workitem +batch-get` | 按 ID 批量读取工作项（客户端侧在 `workitem get` 之上做扇出；`+` 前缀代表场景/语法糖命令） |
+| `workitem update` | 修改工作项字段 |
+| `workitem search-by-params` | 使用结构化字段条件搜索工作项 |
+| `workitem search-filter` | 按标题 / 名称过滤搜索工作项 |
+| `workitem list-op-records` | 查看操作记录 |
+| `workitem meta-types` | 查看工作项类型列表 |
+| `workitem meta-create-fields` | 查看创建时可用字段 |
+| `workitem meta-fields` | 查看字段配置 |
+| `workitem meta-roles` | 查看角色配置 |
+
+### workflow — 工作流域
+
+| 命令 | 说明 |
+|------|------|
+| `workflow transition` | 流转或回滚节点 |
+| `workflow transition-state` | 流转状态流状态 |
+| `workflow update-node` | 修改节点 |
+| `workflow list-state-transitions` | 查看可流转状态 |
+| `workflow list-state-required` | 查看流转必填信息 |
+
+### subtask — 子任务
+
+| 命令 | 说明 |
+|------|------|
+| `subtask update` | 创建/修改/完成/回滚子任务 |
+
+### comment — 评论域
+
+| 命令 | 说明 |
+|------|------|
+| `comment add` | 添加评论 |
+| `comment list` | 查看评论列表 |
+
+### workhour — 工时域
+
+| 命令 | 说明 |
+|------|------|
+| `workhour list-records` | 查看工时登记记录 |
+| `workhour list-schedule` | 查看人员排期 |
+
+### relation — 关系域
+
+| 命令 | 说明 |
+|------|------|
+
+### view — 视图域
+
+| 命令 | 说明 |
+|------|------|
+| `view create-fixed` | 创建固定视图 |
+| `view get` | 查看视图详情 |
+| `view update-fixed` | 更新固定视图 |
+| `view search` | 按名称搜索视图 |
+
+### chart — 度量域
+
+| 命令 | 说明 |
+|------|------|
+| `chart get` | 查看图表详情 |
+| `chart list` | 查看视图下的图表列表 |
+
+### team / user — 人员域
+
+| 命令 | 说明 |
+|------|------|
+| `team list-members` | 查看团队成员 |
+| `user me` | 查看当前登录用户信息 |
+| `user query` | 查询用户信息 |
+
+### space — 空间域
+
+| 命令 | 说明 |
+|------|------|
+| `space list` | 列出空间信息 |
+
+### auth — 认证域
+
+| 命令 | 说明 |
+|------|------|
+| `auth login` | 发起远端 MCP SSO 登录 |
+| `auth logout` | 登出，并在可达时撤销远端会话 |
+| `auth status` | 查看登录状态 |
+| `auth whoami` | 查看当前登录身份和授权摘要 |
+
+### config — 配置域
+
+| 命令 | 说明 |
+|------|------|
+| `config init` | 初始化配置 |
+| `config show` | 查看当前配置 |
+| `config set` | 设置配置项 |
+| `config get` | 读取配置项 |
+| `config profile create\|list\|use\|current\|delete` | 管理多环境 profile |
+
+### 其他命令
+
+| 命令 | 说明 |
+|------|------|
+| `inspect [command]` | 查看命令参数详情 |
+| `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`
+- `integration kubelink-app-catalog-resolve`
+
+这些是 `verified`，可以作为默认安全的首选入口。
+
+- `release deploy-task-create`
+- `release deploy-task-execute`
+- `release deploy-task-apply-white-list`
+- `release deploy-task-verify`
+- `integration kubelink-deploy-task-create`
+- `integration kubelink-deploy-task-upgrade`
+- `integration kubelink-deploy-task-verify`
+- `integration kubelink-deploy-task-apply-white-list`
+- `integration kubelink-deploy-task-inspect`
+
+这些是 `conditional`。如果参数形状不明确，先执行 `meegle inspect <resource>.<method>`，不要在 Agent 场景里盲跑。
+
+高级降级入口：
+
+- 常规发布任务优先使用 `release` 资源组
+- 只有在你已经持有精确 Kubelink payload / record ID，或 release 层命令无法表达目标动作时，才退回 `integration`
+
+## 常用示例
+
+### 查询工作项
+
+```bash
+# 查看工作项概况
+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` 之
+上组合出批量语义。
+
+```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
+# 通过 --params 传 fields[]
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[
+    {"field_key":"name","field_value":"优化登录流程"},
+    {"field_key":"priority","field_value":"P1"}
+  ]}'
+
+# 复杂字段值（数组、嵌套 JSON）也走 --params
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[
+    {"field_key":"name","field_value":"排期任务"},
+    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
+  ]}'
+```
+
+### 修改字段
+
+```bash
+# 修改工作项名称
+meegle workitem update --work-item-id 12345 \
+  --params '{"fields":[{"field_key":"name","field_value":"新标题"}]}'
+
+# 同时修改多个字段
+meegle workitem update --work-item-id 12345 \
+  --params '{"fields":[
+    {"field_key":"name","field_value":"新标题"},
+    {"field_key":"priority","field_value":"P0"}
+  ]}'
+```
+
+### 工作项搜索
+
+```bash
+# 按标题 / 名称过滤查询空间下的 P0 需求
+meegle workitem search-filter --project-key PROJ \
+  --work-item-type-key STORY_TYPE_KEY \
+  --name P0
+```
+
+### 查看排期
+
+```bash
+# 查看团队成员排期
+meegle workhour list-schedule --project-key PROJ \
+  --start-time 2026-03-01 --end-time 2026-03-31 \
+  --user-keys "张三,李四,王五"
+```
+
+### 查看用户信息
+
+```bash
+meegle user query --user-keys "张三,李四"
+```
+
+### 部署任务
+
+```bash
+# 从发布单上下文准备 deploy-task payload
+meegle release deploy-task-prepare \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --appName APP_NAME \
+  --format json
+
+# 查看一个发布单下的 deploy tasks
+meegle release deploy-task-list \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --format json
+
+# 结合发布单上下文检查单个 deploy task
+meegle release deploy-task-inspect \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --recordID RECORD_ID \
+  --format json
+
+# 用户确认后，从 release 层申请加白
+meegle release deploy-task-apply-white-list \
+  --project-key PROJ \
+  --release-id RELEASE_ID \
+  --recordIDs RECORD_ID \
+  --format json
+
+# 在高级 Kubelink 层解析可部署应用和 chart
+meegle integration kubelink-app-catalog-resolve \
+  --appName APP_NAME \
+  --format json
+```
+
+## 参数传递
+
+### 基本 flag
+
+每个命令的参数通过 `--flag-name` 传递：
+
+```bash
+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）。
+
+```bash
+# 下面两种等价：
+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 参数：
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"标题"}]}'
+```
+
+### 优先级
+
+当 `--set`、`--params` 和普通 flag 同时使用时：
+
+1. 普通 CLI flag 覆盖 `--params` / `--set` 中同名顶层 key
+2. `--set` 覆盖 `--params` 中同名顶层 key
+
+### 数组参数
+
+多个值用逗号分隔：
+
+```bash
+--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 |
+
+## 进阶用法
+
+### 输出格式
+
+```bash
+# 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"}}}`（数字段按索引） |
+
+```bash
+# 顶层选择
+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` 预览请求再执行：
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"测试"}]}' --dry-run
+```
+
+### 命令内省
+
+用 `inspect` 查看任意命令的完整参数信息：
+
+```bash
+# 列出所有命令
+meegle inspect
+
+# 查看特定命令的参数详情
+meegle inspect workitem.create
+```
+
+## 认证
+
+对于本仓库的私有化部署，普通用户默认走前面[快速开始](#快速开始)里的远端
+MCP SSO 路径：
+
+- 执行 `meegle auth login`
+- 正式安装包默认使用内置的生产 MCP 地址
+- 仅本地调试或预发覆盖时使用 `meegle config set mcp_server_url ...`
+- 然后用 `meegle auth whoami` 查看当前身份和授权范围
+
+完成登录后，先执行 `meegle doctor --format json`。如果 `doctor`
+没过，先修配置，再跑业务命令。
+
+普通用户远端 MCP SSO 登录示例：
+
+```bash
+meegle auth login
+meegle auth whoami --format table
+```
+
+首次引导 / 单次覆盖示例：
+
+```bash
+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 whoami --format table
+```
+
+### 通用 OAuth / Device Code 流程
+
+仓库仍然保留 `meegle auth login` 和
+`meegle auth login --device-code`，但这不是当前私有化部署的默认文档路径。
+这些流程在显式传入 `--project-key` 时也可以持久化默认空间，但当前私有化部署默认仍应使用 remote MCP SSO。
+
+## 配置
+
+### 配置文件
+
+配置存储在 `~/.meegle/config.json`：
+
+```bash
+# 初始化配置
+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 meegle-cli` 构建 CLI 包
+- 在干净 shell 中安装 staged 或已发布包，执行 `meegle auth login`
+- 确认 `meegle auth whoami --format table` 展示正确账号、Meegle user key、项目和业务线
+- 普通用户侧保持 `mcp_server_url` 未配置；该配置只用于本地或预发覆盖
+
+### 沙盒 / CI：直接注入环境变量
+
+若是通用 token 型 CI，也支持下面这组环境变量：
+
+```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
+
+支持管理多个环境配置（不同站点、不同账号），每个 profile 独立存储 host 和认证信息。
+
+```bash
+# 创建新环境（交互式引导 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 地址和登录态已经就绪：
+
+```bash
+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
+
+[![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/飞书开放平台的 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)