meego-skill

飞书项目（Meego）全能力技能。提供工作项查询、状态流转、团队管理、工时统计、评论协作等全部能力。当用户提到以下场景时激活：查询在途工作项、查缺陷/任务/需求详情、查团队成员、查工时记录、添加评论、创建工作项、修改工作项字段、查询工作项流转状态、查成员排期、查询视图和图表、查询工作项字段配置、查询项目空间信息、...

Security Scan

The skill is coherent with a Meego/飞书 project integration but its runtime instructions ask you to paste OAuth credentials into the chat so the assistant will write them to /root/.mcporter/credentials.json — a high-risk practice that could expose tokens.

Purpose & Capability

Name/description match the provided instructions and references (Meego / 飞书 项目 via an MCP tool). However the registry metadata declares no required binaries or env vars while the SKILL.md explicitly requires Node/npm and the meego-mcporter/mcporter tools—an inconsistency between metadata and runtime requirements (metadata omission, not necessarily malicious).

Instruction Scope

The SKILL.md instructs the user to run npm installs and OAuth locally (expected), but crucially tells the user to cat their local OAuth credentials and paste the full JSON into the chat so the AI will 'automatically write' it into the server's /root/.mcporter/credentials.json. That directs the agent to receive and store sensitive tokens via chat (credential transfer/exfiltration) and to perform file writes on a server path; this goes beyond normal scoped API usage and materially raises data-exposure risk.

Install Mechanism

No formal install spec exists (instruction-only), and the instructions rely on npm installs and npx usage (@lark-project/meego-mcporter and mcporter). Using npm/npx is expected for this tooling, but global installs and npx fetches should be reviewed (package provenance, audit). There is no evidence of arbitrary URL downloads or unusual extract/install steps.

Credentials

The skill requests no declared env vars in metadata but the flow requires OAuth tokens saved in ~/.mcporter/credentials.json. The instructions explicitly ask users to paste the full credentials JSON into chat for the assistant to transfer to the server. That asks for highly sensitive secrets via an insecure channel (chat), which is disproportionate and unnecessary — alternatives exist (run auth directly on the server, use secure file transfer, or provide limited/ephemeral tokens).

Persistence & Privilege

While the skill is not marked always:true and allows normal autonomous invocation, the instructions direct writing credentials to /root/.mcporter/credentials.json and global npm installs on server—operations that grant long-lived access to the user's Meego account if performed. Having the assistant handle raw tokens in-chat increases persistent access risk.

What to consider before installing

Do NOT paste your ~/.mcporter/credentials.json (or any OAuth tokens) into chat. The SKILL.md explicitly asks you to paste credentials for the assistant to write into /root/.mcporter/credentials.json — that creates a direct credential-exfiltration risk. Safer options: (1) perform the npx auth step directly on the target server or on a secure admin workstation so tokens are written locally and never shared in chat; (2) if you must use this skill, create a scoped/limited service account or ephemeral token with minimal permissions and rotate it immediately; (3) verify the npm package @lark-project/meego-mcporter provenance and audit its code before installing; (4) prefer secure copy (scp/sftp) or a secrets manager to move credentials to servers rather than pasting into chat; (5) if you already shared tokens here, rotate/revoke them immediately. The skill's functionality itself matches its description, but the credential-handling instructions are unsafe — treat them as a blocking concern unless you change to a secure transfer workflow.

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 '{}'	见安装步骤第三步
飞书项目	已开通企业版	联系管理员	—

一键检查脚本：

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

---

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

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

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

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

npm install -g mcporter
npm install -g @lark-project/meego-mcporter

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

# Windows PowerShell / 命令提示符
npm install -g mcporter
npm install -g @lark-project/meego-mcporter

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

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

meego-mcporter --help

---

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

第一步：创建配置文件

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

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

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

第二步：触发授权

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

# 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 上传到服务器

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

type %USERPROFILE%\.mcporter\credentials.json
# Windows PowerShell:
# Get-Content $env:USERPROFILE\.mcporter\credentials.json

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

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

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

---

验证连接

服务器上执行：

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

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

✅ 全部通过 → 配置完成！

---

四、调用格式详解

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

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

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

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

传 URL 自动解析（最简单）

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

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开始）：

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

---

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

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

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

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

---

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

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

也支持直接传 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：查工作项节点（子任务）

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：流转工作项状态（三步完成）

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

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

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

meego-mcporter call meego get_transition_required --args '{
  "project_key": "你的project_key",
  "work_item_id": 123456,
  "state_key": "RESOLVED"
}' --config /workspace/meego-config.json

第三步：执行流转

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

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：创建工作项

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

meego-mcporter call meego get_workitem_field_meta --args '{
  "project_key": "你的project_key",
  "work_item_type": "issue"
}' --config /workspace/meego-config.json

第二步：创建工作项

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：修改工作项字段

# 单个字段
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：查工时记录

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：查工作项字段配置

# 查某类型的完整字段列表（含选项值）
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：查工作项类型

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

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

---

场景 11：查团队成员

# 查项目下所有团队
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：查成员排期

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）

# 用项目中文名查询
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 再填入。

# 查所有 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（服务器无浏览器环境）

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

第一步：本地完成授权

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

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

第二步：导出 credentials

# 本地电脑执行
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 即可：

# 本地执行，导出最新 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	工作项字段配置参考