【飞书项目（Meegle）CLI 配置指南与踩坑总结】

背景为了让 AI Agent 能直接读取飞书项目中分配给自己的 bug 并自动修复我们配置了 meego-cli 工具。本文档记录完整的配置流程、注意事项和踩坑经验。一、工具说明|工具|用途|认证方式|lark-cli|飞书文档/消息/日历等开放平台能力|OAuth 用户授权|meego-cli|飞书项目Meegle工作项/视图/工作流|Plugin ID/Secret|重要认知lark-cli 和 meego-cli 是两套独立的认证体系。飞书项目的 API 在project.feishu.cn域名下lark-cli 的 OAuth Token 无法调用必须用 meego-cli Plugin 认证。二、前置准备环境要求Node.jsv16实测 v20.14.0npm / npx需要获取的三要素|要素|获取方式|示例|Plugin ID|飞书项目后台创建插件|MII_6A8BA…(保密|Plugin Secret|创建插件后生成|B61DD…保密|User Key|飞书项目个人中心 / 成员管理|权限角色要求创建插件需要飞书项目的空间管理员权限不是飞书租户管理员。普通项目成员无法创建插件需要找空间管理员。三、安装步骤1. 安装 CLI# 注意旧包名 meegle-cli 已废弃新包名是 meego-clinpminstall-gmeego-cli2. 初始化认证配置meego.cmd auth init --target-profile default ^ --plugin-id你的PluginID^ --plugin-secret你的PluginSecret^ --default-user-key你的UserKey3. 验证认证# 检查 Token 是否可获取meego.cmd--profiledefault auth status# 查询当前用户信息验证 UserKey 正确性meego.cmd--profiledefault user query--self四、插件端配置关键步骤插件创建后不能直接使用必须完成以下 4 步缺一不可步骤 1开通 API 权限进入插件管理 → 权限管理按需开通必须开通读取 bug 场景获取空间信息project:project.v2.info:read获取工作项实例信息work_item:work_item.v2.info:read获取空间下的基础配置settings:settings.v2.basic.info:read按需开通获取评论 / 更新评论更新工作项实例数据写操作获取视图度量数据view_measure步骤 2设置数据范围插件管理 → 数据范围 → 添加目标空间如AI设计部。调试阶段数据范围只对虚拟 Token 生效正式使用必须走发布流程。步骤 3发布插件插件管理 → 发布。发布后插件才能被空间安装。步骤 4空间安装插件最容易遗漏进入目标空间 → 空间配置 → 集成管理 → 安装已发布的插件 → 完成空间数据授权。官方说明正式获取数据前提 插件发布上架 空间管理员安装插件 完成空间数据授权。五、常用命令基础查询# 列出工作项类型确认 bug 类型 keymeego.cmd--profiledefault space types --project-key项目key# 列出视图meego.cmd--profiledefault view list --project-key项目key--type-key issue# 查询当前用户meego.cmd--profiledefault user query--self查询我的 bug核心用法# 语义搜索推荐Agent 首选入口meego.cmd--profiledefault workitem search smart\--query你的姓名\--project-key项目key\--type-key issue\--all--json# 查询某个 bug 的详情含状态、描述meego.cmd--profiledefault workitem get\--project-key项目key\--type-key issue\--idbug ID--jsonbug 状态字段说明workitem get 返回的sub_stage字段OPEN待处理RESOLVED已解决待验证CLOSED已关闭六、踩坑总结重点坑 1空间 key 有两个部分 API 只认真实 key现象浏览器 URL 中的是c71jg1simple_name但部分 API如 workitem search universal、workitem meta报Project Not Exist。原因飞书项目有两套标识URL 简称c7***浏览器地址栏看到的真实 key67b6f5717b7a2*******API 需要的解决先调workitem search filter拿到任意一条数据其中project_key字段就是真实 key或看simple_name字段反查。坑 2Project Not Exist ≠ 项目不存在现象明明空间存在API 却报Project Not Exist (1000052063)或Check Token Perm Failed (10301)。原因这个错误实际是权限问题的伪装常见于插件数据范围没设置目标空间插件未发布 / 空间未安装插件API 权限未开通解决按第四章的 4 步逐项检查特别是空间安装插件这步最容易被遗漏。坑 3Windows PowerShell 执行策略阻止 .ps1 脚本现象直接运行meego报无法加载文件…因为在此系统上禁止运行脚本。解决使用.cmd后缀调用meego.cmdlark-cli 同理用lark-cli.cmd。或修改执行策略不推荐。坑 4CLI 输出包含 ANSI 颜色码无法直接解析现象输出中混入\u001b[32m之类的颜色控制符正则解析失败。解决设置环境变量NO_COLOR1后再调用execSync(meego.cmd ...,{env:{...process.env,NO_COLOR:1}})坑 5PowerShell 管道导致中文乱码现象| Out-File或管道处理后中文全部变成乱码GBK/UTF-8 转换问题且 Out-File 默认写入 BOM。解决用 Node.js 的execSync直接执行命令并写文件绕过 PowerShell 编码转换constoutexecSync(meego.cmd ... --json,{encoding:utf8});fs.writeFileSync(result.json,out);坑 6旧包名 meegle-cli 已废弃现象npx meegle-cli提示 deprecated。解决改用npm install -g meego-cli命令名是meego。坑 7workitem search filter 的参数 bug现象--type提示已移除请用--type-key但传--type-key又提示 unknown option。解决用workitem search smart语义搜索或by-params替代这是 CLI 自身的参数 bug。坑 8查询结果不含 owner 字段过滤现象workitem search filter --owner的 owner 过滤不生效返回全部数据。解决用workitem search smart --query 姓名做语义搜索SearchHit 中包含owners即为负责人匹配。七、AI Agent 集成建议推荐调用方式由于上述 PowerShell 编码坑AI Agent如 Qoder/Claude调用时建议统一用 Node.js 包装const{execSync}require(child_process);functioncallMeego(args){returnJSON.parse(execSync(meego.cmd --profile default${args},{encoding:utf8,maxBuffer:10*1024*1024,env:{...process.env,NO_COLOR:1}}));}批量查 bug 状态的效率提示workitem search smart返回列表不含状态字段需要逐个调workitem get查状态。批量查询时控制范围如最新 60 条避免 API 调用过多。