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

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

---

一、完整功能索引

#	功能场景	核心工具	需要 OAuth
1	查我的在途工作项	INLINECODE1	✅
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	INLINECODE22	升级 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 '{}' | 见安装步骤第三步 | | 飞书项目 | 已开通企业版 | 联系管理员 | — |

一键检查脚本：

node --version && mcporter --help && meego-mcporter --help && echo "✅ 工具就绪"

---

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

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

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

服务器端（已有 Node.js 环境）：
CODEBLOCK1

本地电脑（用于完成 OAuth 授权）：
CODEBLOCK2

CODEBLOCK3

验证安装（服务器或本地都行）：

meego-mcporter --help

---

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

第一步：创建配置文件

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

CODEBLOCK5

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

第二步：触发授权

npx @lark-project/meego-mcporter auth meego --config meego-config.json

CODEBLOCK7

这个命令会：

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

预期输出：
CODEBLOCK8

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

授权完成后，在本地电脑执行：
CODEBLOCK9

CODEBLOCK10

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

服务器credentials路径： /root/.mcporter/credentials.json（Linux服务器）
本地 credentials 路径： INLINECODE37

---

验证连接

服务器上执行：
CODEBLOCK11

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

✅ 全部通过 → 配置完成！

---

四、调用格式详解

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

CODEBLOCK12

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

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

传 URL 自动解析（最简单）

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

CODEBLOCK13

分页查询

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

CODEBLOCK14

---

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

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

CODEBLOCK15

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

---

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

CODEBLOCK16

也支持直接传 URL：

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：查工作项节点（子任务）

CODEBLOCK18

---

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

第一步：查可流转到哪些状态
CODEBLOCK19

第二步：查目标状态需要填哪些必填字段
CODEBLOCK20

第三步：执行流转

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：添加评论

CODEBLOCK22

评论内容支持 Markdown。

---

场景 6：创建工作项

第一步：查该类型的必填字段（必须先做）
CODEBLOCK23

第二步：创建工作项
CODEBLOCK24

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

---

场景 7：修改工作项字段

CODEBLOCK25

---

场景 8：查工时记录

CODEBLOCK26

---

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

CODEBLOCK27

---

场景 10：查工作项类型

CODEBLOCK28

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

---

场景 11：查团队成员

CODEBLOCK29

---

场景 12：查成员排期

CODEBLOCK30

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

---

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

CODEBLOCK31

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

---

场景 14：MQL 自由查询

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

CODEBLOCK32

issue（缺陷）状态值：

状态 key	含义
INLINECODE59	开始
INLINECODE60

待确认 |
| REPAIRING | 待修复 |
| IN REPAIRING | 修复中 |
| RESOLVED | 已修复 |
| VERIFYING | 验证中 |
| REOPENED | 重新打开 |
| CLOSED | 已关闭 |
| REJECTED | 拒绝 |
| ABONDONED | 废弃 |

常用字段速查：

字段	key	示例值
名称	INLINECODE69	字符串
状态

work_item_status | 见上方状态值 |
| 优先级 | priority | 0（最高）/ 1（高）/ 2（中）/ 99（低）|
| 严重程度 | severity | 1（致命）/ 2（严重）/ 3（一般）/ 4（轻微）|
| 当前负责人 | current_status_operator | user_key 字符串 |
| 创建者 | owner | user_key 字符串 |

---

六、异常处理（完整版）

运行时错误速查

错误现象	第一步排查	解决方案
INLINECODE83 / INLINECODE84	服务器无浏览器，OAuth 授权未完成	见下方「授权异常」专项处理
INLINECODE85

token 过期 | 见下方「token 刷新」专项处理 | | 403 Forbidden | 应用权限不足 | 飞书开放平台 → 权限管理申请权限 → 重新发版 | | 404 Not Found | projectkey 或 workitem_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（服务器无浏览器环境）

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

第一步：本地完成授权

# 本地电脑执行（Windows）
npx @lark-project/meego-mcporter auth meego --config meego-config.json

CODEBLOCK34

第二步：导出 credentials
CODEBLOCK35

第三步：发给 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 accesstoken 有效期 2 小时，refreshtoken 有效期 30 天。

自动刷新（推荐）：

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

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

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

CODEBLOCK36

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

---

专项三：权限类错误

错误信息	原因	解决方法
INLINECODE102	应用未开通飞书项目权限	飞书开放平台 → 权限管理 → 申请 project 权限 → 重新发版
INLINECODE104

应用未被加入项目空间 | 项目管理员 → 设置 → 成员管理 → 添加应用 |
| workflow:invalid_state | 流转到不合法的状态 | 先用 get_transitable_states 查可流转状态 |

---

专项四：网络与连接错误

错误信息	原因	解决方法
INLINECODE107	网络超时	确认服务器可访问 INLINECODE108
INLINECODE109

IP 白名单限制 | 飞书后台 → 安全设置 → 关闭 IP 白名单 |
| HTTP 429 | 请求过快 | 降低调用频率，加 sleep 1 延时 |

---

七、调试与排障流程图

CODEBLOCK37

---

八、凭证与权限体系

凭证文件

环境	文件路径	用途
服务器（Linux）	INLINECODE112	OAuth token（AI助手写入）
本地电脑

~/.mcporter/credentials.json | OAuth token（auth 命令自动写入） |

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

权限申请检查表

需要的功能	必须申请的权限	是否需重新发版
工作项读写	INLINECODE115	✅
状态流转

project:workflowstatus | ✅ | | 评论 | project:comment | ✅ | | 成员查询 | project:member | ✅ | | 排期查询 | project:schedule | ✅ | | 视图查询 | project:view | ✅ | | 基础读写 | project | ✅ |

---

九、参考文件索引

文件	内容
references/tools.md	所有工具完整清单（40+ 接口）
references/mql.md

MQL 查询语法与完整示例 | | references/fields.md | 工作项字段配置参考 |