---
name: meego-skill
version: 2.2.0
description: 飞书项目（Meego）全能力技能。提供工作项查询、状态流转、团队管理、工时统计、评论协作等全部能力。当用户提到以下场景时激活：查询在途工作项、查缺陷/任务/需求详情、查团队成员、查工时记录、添加评论、创建工作项、修改工作项字段、查询工作项流转状态、查成员排期、查询视图和图表、查询工作项字段配置、查询项目空间信息、按条件筛选工作项。面向小白：逐项操作指引；面向AI：每个接口均有参数说明、示例和异常处理。
---

# Meego Skill（飞书项目全能力技能）

> 本技能通过飞书项目官方 MCP 接口提供全部能力。
> 底层调用工具：`meego-mcporter`（MCP over stdio 协议），凭证通过 OAuth 管理。

---

## 一、完整功能索引

| # | 功能场景 | 核心工具 | 需要 OAuth |
|---|---------|---------|-----------|
| 1 | 查我的在途工作项 | `list_todo` | ✅ |
| 2 | 查任意工作项详情 | `get_workitem_brief` | ✅ |
| 3 | 查工作项节点/子任务 | `get_node_detail` | ✅ |
| 4 | 流转工作项状态 | `get_transitable_states` + `update_field` | ✅ |
| 5 | 添加评论 | `add_comment` | ✅ |
| 6 | 创建工作项 | `create_workitem` | ✅ |
| 7 | 修改工作项字段 | `update_field` | ✅ |
| 8 | 查工时记录 | `get_workitem_man_hour_records` | ✅ |
| 9 | 查字段配置 | `list_workitem_field_config` | ✅ |
| 10 | 查工作项类型 | `list_workitem_types` | ✅ |
| 11 | 查团队成员 | `list_team_members` / `list_project_team` | ✅ |
| 12 | 查成员排期 | `list_schedule` | ✅ |
| 13 | 查项目空间信息 | `search_project_info` | ✅ |
| 14 | 按标题搜索视图 | `search_view_by_title` | ✅ |
| 15 | 查视图下图表 | `list_charts` / `get_chart_detail` | ✅ |
| 16 | MQL 自由查询 | `search_by_mql` | ✅ |
| 17 | 查工作项操作记录 | `get_workitem_op_record` | ✅ |
| 18 | 关联工作项查询 | `list_related_workitems` | ✅ |

---

## 二、前置条件（逐项检查）

| 依赖 | 要求 | 检查命令 | 检查失败怎么做 |
|------|------|---------|-------------|
| Node.js | ≥ 16 | `node --version` | 升级 Node.js |
| npm | 任意版本 | `npm --version` | 随 Node.js 自动安装 |
| mcporter | 已安装并可用 | `mcporter --help` | 见安装步骤第一步 |
| meego-mcporter | 已安装并可用 | `meego-mcporter --help` 或 `npx @lark-project/meego-mcporter --help` | 见安装步骤第二步 |
| OAuth 凭证 | 已完成授权并同步到服务器 | `meego-mcporter call meego list_todo --args '{}'` | 见安装步骤第三步 |
| 飞书项目 | 已开通企业版 | 联系管理员 | — |

**一键检查脚本：**
```bash
node --version && mcporter --help && meego-mcporter --help && echo "✅ 工具就绪"
```

---

## 三、完整安装步骤（两步完成）

> **核心原理：** `meego-mcporter` 通过 MCP over stdio 协议连接飞书项目 MCP 服务器，OAuth 授权由 `mcporter` 管理。安装只需两步：装工具 → 做授权。

### 第一步：安装工具（服务器 + 本地电脑都要装）

**服务器端（已有 Node.js 环境）：**
```bash
npm install -g mcporter
npm install -g @lark-project/meego-mcporter
```

**本地电脑（用于完成 OAuth 授权）：**
```powershell
# Windows PowerShell / 命令提示符
npm install -g mcporter
npm install -g @lark-project/meego-mcporter
```

```bash
# Mac/Linux 终端
sudo npm install -g mcporter
sudo npm install -g @lark-project/meego-mcporter
```

验证安装（服务器或本地都行）：
```bash
meego-mcporter --help
```

---

### 第二步：在本地电脑完成 OAuth 授权（关键步骤）

**第一步：创建配置文件**

在本地电脑新建 `meego-config.json`（内容固定，服务器地址不变）：

```json
{
  "mcpServers": {
    "meego": {
      "url": "https://project.feishu.cn/mcp_server/v1",
      "auth": "oauth"
    }
  }
}
```

> ⚠️ `meego` 是服务器名称，不要改。`url` 和 `auth` 字段固定，不需要填 App ID/Secret。

**第二步：触发授权**
```powershell
npx @lark-project/meego-mcporter auth meego --config meego-config.json
```
```bash
# Mac/Linux
npx @lark-project/meego-mcporter auth meego --config ./meego-config.json
```

这个命令会：
1. 启动一个本地 HTTP 服务监听 callback
2. 自动打开浏览器跳转发书授权页面
3. 用户在飞书点击"授权"后，callback 收到 code
4. 自动用 code 换取 access_token + refresh_token
5. **自动保存到** `~/.mcporter/credentials.json`（本地电脑）

**预期输出：**
```
Opening browser for OAuth authorization...
Authorization received. Exchanging for tokens...
Success! Credentials saved to ~/.mcporter/credentials.json
```

**第三步：把 credentials 上传到服务器**

授权完成后，在本地电脑执行：
```bash
type %USERPROFILE%\.mcporter\credentials.json
# Windows PowerShell:
# Get-Content $env:USERPROFILE\.mcporter\credentials.json
```

```bash
# Mac/Linux:
cat ~/.mcporter/credentials.json
```

把完整 JSON 内容发给 AI助手（粘贴到聊天里），AI会自动写入服务器的 `/root/.mcporter/credentials.json`。

> **服务器credentials路径：** `/root/.mcporter/credentials.json`（Linux服务器）
> **本地 credentials 路径：** `~/.mcporter/credentials.json`

---

### 验证连接

服务器上执行：
```bash
meego-mcporter call meego list_todo --args '{}'
```

预期：返回当前用户在飞书项目中的在途工作项列表。

✅ 全部通过 → 配置完成！

---

## 四、调用格式详解

### 标准格式（服务器上直接用）

```bash
meego-mcporter call meego <工具名> --args '<JSON参数>'
```

凭证自动从 `/root/.mcporter/credentials.json` 读取，无需每次传 `--config`。

> ⚠️ **JSON 参数必须用单引号包裹**，外层用双引号。这是 shell 转义要求。

### 传 URL 自动解析（最简单）

如果用户提供了一个 Meego 链接，直接把完整 URL 作为 `url` 参数传入，系统自动解析 project_key 和 work_item_id：

```bash
meego-mcporter call meego get_workitem_brief --args '{
  "url": "https://project.feishu.cn/more/more?workitem_id=123456&project_key=你的project_key"
}'
```

### 分页查询

所有 `list` 类工具支持分页，用 `page_num`（从1开始）：

```bash
meego-mcporter call meego list_todo --args '{"page_num": 2}'
```

---

## 五、每个场景的完整调用示例

### 场景 1：查我的在途工作项（最高频）

```bash
meego-mcporter call meego list_todo --args '{}'
```

返回：工作项ID、名称、类型、当前节点、计划开始/结束时间。
分页：每页50条。

---

### 场景 2：查任意工作项详情

```bash
meego-mcporter call meego get_workitem_brief --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456
}' --config /workspace/meego-config.json
```

也支持直接传 URL：
```bash
meego-mcporter call meego get_workitem_brief --args '{
  "url": "https://project.feishu.cn/more/more?workitem_id=123456&project_key=你的project_key"
}' --config /workspace/meego-config.json
```

---

### 场景 3：查工作项节点（子任务）

```bash
meego-mcporter call meego get_node_detail --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "need_sub_task": true
}' --config /workspace/meego-config.json
```

---

### 场景 4：流转工作项状态（三步完成）

**第一步：查可流转到哪些状态**
```bash
meego-mcporter call meego get_transitable_states --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "work_item_type": "issue",
  "user_key": "你的user_key（从 list_todo 返回中获取）"
}' --config /workspace/meego-config.json
```

**第二步：查目标状态需要填哪些必填字段**
```bash
meego-mcporter call meego get_transition_required --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "state_key": "RESOLVED"
}' --config /workspace/meego-config.json
```

**第三步：执行流转**
```bash
meego-mcporter call meego update_field --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "fields": ["work_item_status:RESOLVED"]
}' --config /workspace/meego-config.json
```

---

### 场景 5：添加评论

```bash
meego-mcporter call meego add_comment --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "comment_content": "## 修复方案\n\n已定位原因，正在修复中，请稍候。\n\n@负责人 请review"
}' --config /workspace/meego-config.json
```

评论内容支持 Markdown。

---

### 场景 6：创建工作项

**第一步：查该类型的必填字段（必须先做）**
```bash
meego-mcporter call meego get_workitem_field_meta --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue"
}' --config /workspace/meego-config.json
```

**第二步：创建工作项**
```bash
meego-mcporter call meego create_workitem --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue",
  "fields": [
    "name:缺陷标题",
    "priority:1",
    "severity:2",
    "work_item_status:OPEN"
  ]
}' --config /workspace/meego-config.json
```

> 字段 key 从第一步返回获取。常见 key：`name`（标题）、`priority`（优先级）、`severity`（严重程度）、`work_item_status`（状态）。

---

### 场景 7：修改工作项字段

```bash
# 单个字段
meego-mcporter call meego update_field --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "fields": ["priority:0"]
}' --config /workspace/meego-config.json

# 多个字段
meego-mcporter call meego update_field --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "fields": ["priority:1", "name:新标题"]
}' --config /workspace/meego-config.json
```

---

### 场景 8：查工时记录

```bash
meego-mcporter call meego get_workitem_man_hour_records --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "work_item_type": "issue"
}' --config /workspace/meego-config.json
```

---

### 场景 9：查工作项字段配置

```bash
# 查某类型的完整字段列表（含选项值）
meego-mcporter call meego list_workitem_field_config --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue",
  "page_num": 1
}' --config /workspace/meego-config.json

# 模糊搜索字段（找负责人的字段key等）
meego-mcporter call meego list_node_field_config --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue",
  "query": "负责人"
}' --config /workspace/meego-config.json
```

---

### 场景 10：查工作项类型

```bash
meego-mcporter call meego list_workitem_types --args '{
  "project_key": "你的project_key"
}' --config /workspace/meego-config.json
```

返回：`type_key`（如 `issue`/`story`/`sub_task`）。

---

### 场景 11：查团队成员

```bash
# 查项目下所有团队
meego-mcporter call meego list_project_team --args '{
  "project_key": "你的project_key"
}' --config /workspace/meego-config.json

# 查某团队的成员
meego-mcporter call meego list_team_members --args '{
  "project_key": "你的project_key",
  "team_id": "team_xxx"
}' --config /workspace/meego-config.json
```

---

### 场景 12：查成员排期

```bash
meego-mcporter call meego list_schedule --args '{
  "project_key": "你的project_key",
  "user_keys": ["你的user_key"],
  "start_time": "2026-03-01",
  "end_time": "2026-03-31"
}' --config /workspace/meego-config.json
```

- 时间格式：`YYYY-MM-DD`，最大范围3个月
- `user_keys`：从 `list_team_members` 或 `list_todo` 中获取的 user_key 列表

---

### 场景 13：查项目空间信息（获取 project_key）

```bash
# 用项目中文名查询
meego-mcporter call meego search_project_info --args '{
  "project_key": "你的项目名称"
}' --config /workspace/meego-config.json

# 用 simple_name 查询
meego-mcporter call meego search_project_info --args '{
  "project_key": "your_simple_name"
}' --config /workspace/meego-config.json
```

返回：`project_key`（数字）、`simple_name`、`project_name`。

---

### 场景 14：MQL 自由查询

> ⚠️ MQL 语法严格，字段名必须与 API 字段名完全一致。先用 `list_workitem_field_config` 查实名字段 key 再填入。

```bash
# 查所有 OPEN 状态的缺陷
meego-mcporter call meego search_by_mql --args '{
  "project_key": "你的project_key",
  "mql": "work_item_status = \"OPEN\" and work_item_type_key = \"issue\""
}' --config /workspace/meego-config.json

# 查高优先级在途缺陷
meego-mcporter call meego search_by_mql --args '{
  "project_key": "你的project_key",
  "mql": "priority = \"0\" and work_item_status not in (\"CLOSED\",\"REJECTED\")"
}' --config /workspace/meego-config.json

# 分页查询
meego-mcporter call meego search_by_mql --args '{
  "project_key": "你的project_key",
  "mql": "work_item_status not in (\"CLOSED\")",
  "session_id": "上次返回的session_id"
}' --config /workspace/meego-config.json
```

**issue（缺陷）状态值：**
| 状态 key | 含义 |
|---------|------|
| `OPEN` | 开始 |
| `IN PROGRESS` | 待确认 |
| `REPAIRING` | 待修复 |
| `IN REPAIRING` | 修复中 |
| `RESOLVED` | 已修复 |
| `VERIFYING` | 验证中 |
| `REOPENED` | 重新打开 |
| `CLOSED` | 已关闭 |
| `REJECTED` | 拒绝 |
| `ABONDONED` | 废弃 |

**常用字段速查：**
| 字段 | key | 示例值 |
|------|-----|--------|
| 名称 | `name` | 字符串 |
| 状态 | `work_item_status` | 见上方状态值 |
| 优先级 | `priority` | `0`（最高）/ `1`（高）/ `2`（中）/ `99`（低）|
| 严重程度 | `severity` | `1`（致命）/ `2`（严重）/ `3`（一般）/ `4`（轻微）|
| 当前负责人 | `current_status_operator` | user_key 字符串 |
| 创建者 | `owner` | user_key 字符串 |

---

## 六、异常处理（完整版）

### 运行时错误速查

| 错误现象 | 第一步排查 | 解决方案 |
|---------|----------|---------|
| `OAuth authorization required` / `xdg-open ENOENT` | 服务器无浏览器，OAuth 授权未完成 | 见下方「授权异常」专项处理 |
| `401 Unauthorized` | token 过期 | 见下方「token 刷新」专项处理 |
| `403 Forbidden` | 应用权限不足 | 飞书开放平台 → 权限管理申请权限 → 重新发版 |
| `404 Not Found` | project_key 或 work_item_id 错误 | 确认 URL 中参数正确 |
| `MCP error -32000: Connection closed` | OAuth token 无效或已过期 | 刷新 token，见下方流程 |
| `Permission denied` | 应用未被加入项目空间 | 项目管理员 → 设置 → 成员管理 → 添加应用 |
| `workflow:invalid_state` | 流转到不合法的状态 | 先用 `get_transitable_states` 查可流转状态 |
| `Command not found: meego-mcporter` | meego-mcporter 未安装 | `npm install -g @lark-project/meego-mcporter` |
| MQL `syntax error` | 字段名拼写错误 | 用 `list_workitem_field_config` 确认字段 key |
| 工具调用无输出/超时 | token 失效 | 刷新 token |

---

### 专项一：授权异常（最常见）

**错误 1：`xdg-open ENOENT`（服务器无浏览器环境）**

服务器环境没有浏览器，无法自动打开授权页面。解决流程：

**第一步：本地完成授权**
```powershell
# 本地电脑执行（Windows）
npx @lark-project/meego-mcporter auth meego --config meego-config.json
```
```bash
# Mac/Linux
npx @lark-project/meego-mcporter auth meego --config ./meego-config.json
```

**第二步：导出 credentials**
```powershell
# 本地电脑执行
type $env:USERPROFILE\.mcporter\credentials.json
```

**第三步：发给 AI助手**，AI自动写入服务器 `/root/.mcporter/credentials.json`

---

**错误 2：`OAuth authorization required for 'meego'`（token 不存在）**

服务器上 credentials 文件缺失或内容为空。同上流程：本地完成授权 → 导出 credentials → 发给 AI。

---

### 专项二：Token 过期处理

**错误：`MCP error -32000: Connection closed` 或 `401 Unauthorized`**

**原因：** OAuth access_token 有效期 2 小时，refresh_token 有效期 30 天。

**自动刷新（推荐）：**

本地完成一次 `meego-mcporter auth meego --config meego-config.json`（会覆盖 credentials），然后重新导出 credentials 上传到服务器。

**手动刷新（无浏览器时）：**

access_token 过期后，refresh_token 还在有效期内（30天），直接替换 credentials 中的 access_token 即可：

```powershell
# 本地执行，导出最新 credentials
type $env:USERPROFILE\.mcporter\credentials.json
```

把新 credentials 发给 AI助手 更新到服务器。

---

### 专项三：权限类错误

| 错误信息 | 原因 | 解决方法 |
|---------|------|---------|
| `permission denied` | 应用未开通飞书项目权限 | 飞书开放平台 → 权限管理 → 申请 `project` 权限 → 重新发版 |
| `project:workitem:not_found` | 应用未被加入项目空间 | 项目管理员 → 设置 → 成员管理 → 添加应用 |
| `workflow:invalid_state` | 流转到不合法的状态 | 先用 `get_transitable_states` 查可流转状态 |

---

### 专项四：网络与连接错误

| 错误信息 | 原因 | 解决方法 |
|---------|------|---------|
| `Connection timeout` | 网络超时 | 确认服务器可访问 `project.feishu.cn` |
| `HTTP 403` | IP 白名单限制 | 飞书后台 → 安全设置 → 关闭 IP 白名单 |
| `HTTP 429` | 请求过快 | 降低调用频率，加 `sleep 1` 延时 |

---

## 七、调试与排障流程图

```
工具调用报错
  │
  ├─ OAuth authorization required / xdg-open ENOENT
  │     → 本地执行 auth → 导出 credentials → 发给 AI 更新服务器
  │
  ├─ MCP error -32000: Connection closed / 401 Unauthorized
  │     → token 过期
  │     → 本地执行 auth 刷新 → 新 credentials 发给 AI
  │
  ├─ 403 Forbidden / permission denied
  │     ├─ 应用权限未申请 → 飞书开放平台申请 + 发版
  │     └─ 应用未加入项目 → 项目设置 → 成员管理 → 添加应用
  │
  ├─ 404 Not Found
  │     → 检查 project_key 和 work_item_id 是否正确
  │
  ├─ MQL syntax error
  │     → 字段名拼写错误，用 list_workitem_field_config 确认 key
  │
  └─ 返回空列表
        → 可能无数据（非错误），确认查询条件是否合理
```

---

## 八、凭证与权限体系

### 凭证文件

| 环境 | 文件路径 | 用途 |
|------|---------|------|
| 服务器（Linux） | `/root/.mcporter/credentials.json` | OAuth token（AI助手写入） |
| 本地电脑 | `~/.mcporter/credentials.json` | OAuth token（auth 命令自动写入） |

> **配置格式不是** `app_id + app_secret` JSON，而是 OAuth credentials JSON（由飞书授权流程自动生成）。

### 权限申请检查表

| 需要的功能 | 必须申请的权限 | 是否需重新发版 |
|---------|-------------|-------------|
| 工作项读写 | `project:workitem` | ✅ |
| 状态流转 | `project:workflowstatus` | ✅ |
| 评论 | `project:comment` | ✅ |
| 成员查询 | `project:member` | ✅ |
| 排期查询 | `project:schedule` | ✅ |
| 视图查询 | `project:view` | ✅ |
| 基础读写 | `project` | ✅ |

---

## 九、参考文件索引

| 文件 | 内容 |
|------|------|
| references/tools.md | 所有工具完整清单（40+ 接口）|
| references/mql.md | MQL 查询语法与完整示例 |
| references/fields.md | 工作项字段配置参考 |