meego-skill

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

LONGSASASASASA@longsasasasasa

Install

openclaw skills install @longsasasasasa/meego-skill

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

这个命令会：

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

预期输出：

text

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` 延时

七、调试与排障流程图

text

工具调用报错
  │
  ├─ 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	工作项字段配置参考

meego-skill

Install

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

一、完整功能索引

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

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

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

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

验证连接

四、调用格式详解

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

传 URL 自动解析（最简单）

分页查询

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

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

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

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

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

场景 5：添加评论

场景 6：创建工作项

场景 7：修改工作项字段

场景 8：查工时记录

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

场景 10：查工作项类型

场景 11：查团队成员

场景 12：查成员排期

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

场景 14：MQL 自由查询

六、异常处理（完整版）

运行时错误速查

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

专项二：Token 过期处理

专项三：权限类错误

专项四：网络与连接错误

七、调试与排障流程图

八、凭证与权限体系

凭证文件

权限申请检查表

九、参考文件索引

Related skills