企业官网建设流程全解析

背景：为了让 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.js（v16+，实测 v20.14.0）
• npm / npx

需要获取的三要素

|
要素
|
获取方式
|
示例
|
Plugin ID
|
飞书项目后台创建插件
|
MII_6A8BA…(保密）
|
Plugin Secret
|
创建插件后生成
|
B61DD…（保密）
|
User Key
|
飞书项目个人中心 / 成员管理
|
权限角色要求：创建插件需要飞书项目的空间管理员权限（不是飞书租户管理员）。普通项目成员无法创建插件，需要找空间管理员。

三、安装步骤

1. 安装 CLI

# 注意：旧包名 meegle-cli 已废弃，新包名是 meego-clinpminstall-gmeego-cli

2. 初始化认证配置

meego.cmd auth init --target-profile default ^ --plugin-id<你的PluginID>^ --plugin-secret<你的PluginSecret>^ --default-user-key<你的UserKey>

3. 验证认证

# 检查 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 类型 key）meego.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\--id<bug ID>--json

bug 状态字段说明

workitem get 返回的sub_stage字段：

• OPEN：待处理
• RESOLVED：已解决（待验证）
• CLOSED：已关闭

六、踩坑总结（重点）

坑 1：空间 key 有两个，部分 API 只认真实 key

现象：浏览器 URL 中的是c71jg1（simple_name），但部分 API（如 workitem search universal、workitem meta）报Project Not Exist。

原因：飞书项目有两套标识：

• URL 简称：c7***（浏览器地址栏看到的）
• 真实 key：67b6f5717b7a2*******（API 需要的）

解决：先调workitem search filter拿到任意一条数据，其中project_key字段就是真实 key；或看simple_name字段反查。

坑 2：Project Not Exist ≠ 项目不存在

现象：明明空间存在，API 却报Project Not Exist (1000052063)或Check Token Perm Failed (10301)。

原因：这个错误实际是权限问题的伪装，常见于：

• 插件数据范围没设置目标空间
• 插件未发布 / 空间未安装插件
• API 权限未开通

解决：按第四章的 4 步逐项检查，特别是"空间安装插件"这步最容易被遗漏。

坑 3：Windows PowerShell 执行策略阻止 .ps1 脚本

现象：直接运行meego报"无法加载文件…因为在此系统上禁止运行脚本"。

解决：使用.cmd后缀调用：meego.cmd（lark-cli 同理用lark-cli.cmd）。或修改执行策略（不推荐）。

坑 4：CLI 输出包含 ANSI 颜色码，无法直接解析

现象：输出中混入\u001b[32m之类的颜色控制符，正则解析失败。

解决：设置环境变量NO_COLOR=1后再调用：

execSync('meego.cmd ...',{env:{...process.env,NO_COLOR:'1'}})

坑 5：PowerShell 管道导致中文乱码

现象：| Out-File或管道处理后中文全部变成乱码（GBK/UTF-8 转换问题），且 Out-File 默认写入 BOM。

解决：用 Node.js 的execSync直接执行命令并写文件，绕过 PowerShell 编码转换：

constout=execSync('meego.cmd ... --json',{encoding:'utf8'});fs.writeFileSync('result.json',out);

坑 6：旧包名 meegle-cli 已废弃

现象：npx meegle-cli提示 deprecated。

解决：改用npm install -g meego-cli，命令名是meego。

坑 7：workitem 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 调用过多。