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 ``` 这个命令会： 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 | 工作项字段配置参考 |