CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载本文面向使用 lark-cli 进行妙搭Spark/Miaoda应用开发与 AI 能力集成的开发者与 AI Agent系统讲解lark-cli apps plugin-list命令的适用场景、运行前提、输出契约与源码实现原理。读完本文你将掌握如何快速核对项目已声明的插件包及其实装状态并能在declared_not_installed状态下正确衔接plugin-install完成安装。lark-cli apps plugin-list是飞书官方 CLI 工具 lark-cli 中apps域下用于列出已声明插件包及安装状态的本地命令。它属于妙搭应用「外部能力AI 模型能力与飞书平台能力集成」命令族plugin-install/plugin-list/plugin-uninstall中的只读查询成员其完整行为以lark-cli apps plugin-list --help输出的运行时命令事实为准。本文档以仓库中的 skills/lark-apps/references/lark-apps-plugin-list.md 为骨架结合 shortcuts/apps/apps_plugin_list.go 与配套测试展开说明。一、命令定位本地命令不是远端 API 命令使用plugin-list前必须建立的第一认知是它的执行模式它是一个本地命令直接读取当前目录的package.json在项目根目录下运行即可和npm的使用习惯一致无需指定任何路径参数。它不接受--app-id这一点与apps域下绝大多数命令如get、env-list、release-get等需要--app-id的远端 API 命令完全不同。plugin-list不访问任何远端接口仅做本地文件系统核验。这一差异在源码中体现得十分清晰shortcuts/apps/apps_plugin_list.go 中AppsPluginList的定义显示其Scopes为空不申请任何 scope、Risk为read只读并且命令名在路由表中被注册为plugin-list归属appsService。从 skills/lark-apps/SKILL.md 的意图路由表可以看到plugin-list与plugin-install、plugin-uninstall共同服务于「外部能力AI 模型能力和飞书平台能力集成 / 插件 / Plugin / Capability」这一用户意图是本命令族中负责「查询现状」的一环。二、何时使用核验插件声明与安装状态当出现以下场景时应优先使用plugin-list想查看当前项目声明了哪些插件包即package.json的actionPlugins字段想确认这些插件是否已实际安装即是否已存在于node_modules发现某个插件的状态为declared_not_installed需要据此判断下一步是否要执行plugin-install完成安装。换句话说plugin-list是连接「插件声明」与「插件安装」之间的状态检查工具声明发生在package.json的actionPlugins中安装发生在node_modules目录中plugin-list负责把这两处信息交叉比对后统一呈现。三、命令骨架与运行前提在项目根目录下直接运行和 npm 一样无需指定路径lark-cli apps plugin-list3.1 运行前提plugin-list的Validate阶段见 shortcuts/apps/apps_plugin_list.go做了两步前置校验解析项目路径调用pluginResolveProjectPath()当未显式传路径时默认取当前工作目录cwd。从源码shortcuts/apps/plugin_common.go可以看出该函数仅在传入非空字符串时才做控制字符校验与路径清理。校验项目目录调用pluginCheckProjectDirshortcuts/apps/plugin_common.go检查目标目录下是否存在package.json且为常规文件。若文件不存在命令会报前置条件错误并给出修复提示run lark-cli apps init to initialize the project first这意味着只有已经初始化的妙搭应用项目存在package.json才能运行本命令。尚未初始化的目录会直接收到引导提示而不是空跑一遍。3.2 命令参数plugin-list是纯查询命令注册的Flags为空见 shortcuts/apps/apps_plugin_list.go即没有业务参数。可用的参数主要是 lark-cli 的通用输出格式参数例如--format用于切换输出格式如json/pretty等表格形式。四、完整示例4.1 JSON 格式输出lark-cli apps plugin-list --format json这是官方 reference 中给出的标准示例输出结构稳定、适合脚本与 Agent 程序化解析详细契约见下一节。4.2 表格pretty格式输出lark-cli apps plugin-list --format pretty该形式将插件列表渲染为表格行实现见 shortcuts/apps/apps_plugin_list.go 的output.PrintTable调用适合人类开发者快速浏览。4.3 空声明场景当项目package.json中没有声明任何actionPlugins时命令不会报错而是输出提示信息No plugins declared in package.json actionPlugins.对应源码分支见 shortcuts/apps/apps_plugin_list.go。五、输出契约data.plugins 数组详解plugin-list的输出契约如下与 reference 文档一致并可从源码 shortcuts/apps/apps_plugin_list.go 印证data.plugins[]插件列表数组每个元素包含三个字段字段类型说明keystring插件包 key即package.json中actionPlugins的键名如test/my-pluginversionstring声明版本即actionPlugins中对应的版本值如1.0.0statusstring安装状态枚举值为installed或declared_not_installed5.1 status 两种状态的含义installed该插件包既已在package.json的actionPlugins中声明也已在node_modules中找到对应安装目录node_modules/key/package.json可读取到版本号。declared_not_installed插件包已声明但尚未安装到node_modules此时需要运行plugin-install完成安装后才能创建插件实例。状态判定逻辑在源码中非常直白shortcuts/apps/apps_plugin_list.goinstalled : pluginInstalledVersion(projectPath, key) status : declared_not_installed if installed ! { status installed }其中pluginInstalledVersionshortcuts/apps/plugin_common.go读取node_modules/key/package.json的version字段读不到或解析失败即返回空字符串从而判定为未安装。六、源码级原理插件声明与安装如何被核验plugin-list的完整执行链路Execute见 shortcuts/apps/apps_plugin_list.go可以拆解为四步解析项目路径pluginResolveProjectPath()默认取 cwd读取 package.jsonpluginReadPackageJSON(projectPath)读取并 JSON 解析项目根目录的package.json解析失败会报校验类错误invalid package.json提取 actionPluginspluginGetActionPlugins(pkg)shortcuts/apps/plugin_common.go从package.json中提取actionPlugins字段得到一个key → version的映射表该字段不存在或类型不对时返回空映射逐一比对安装状态对每个key调用pluginInstalledVersion检查node_modules中是否存在对应包据此生成status最终组装为data.plugins数组返回。6.1 插件包 ≠ npm 包这里需要特别强调一个易混淆点详见 skills/lark-apps/references/lark-apps-plugin-install.md 的说明插件包 ≠ npm 包。插件包写入package.json的actionPlugins字段由plugin-install/plugin-uninstall/plugin-list这一命令族管理npm 依赖写入package.json的dependencies字段由npm install管理。两套机制相互独立禁止用npm install代替plugin-install来安装插件包。因此plugin-list只读取actionPlugins而不关心dependencies——这也解释了为什么它的输出以actionPlugins声明为唯一数据源。6.2 Dry-Run 行为作为只读查询命令plugin-list的DryRun实现shortcuts/apps/apps_plugin_list.go会输出action: listsource: package.json actionPlugins node_modules即明确告知本次操作的数据来源便于在审计场景下确认命令不会产生任何写副作用。七、测试验证三种典型场景仓库在 shortcuts/apps/apps_plugin_list_test.go 中为plugin-list提供了三个针对性测试覆盖了命令的核心行为TestPluginList_Emptypackage.json不含actionPlugins时data.plugins返回空数组长度为 0命令不报错TestPluginList_Installed声明test/my-plugin: 1.0.0且node_modules/test/my-plugin/package.json存在时状态为installedTestPluginList_DeclaredNotInstalled声明test/missing: 1.0.0但node_modules中无对应包时状态为declared_not_installed。测试通过chdirTest临时切换工作目录并使用--format json断言输出结构恰好验证了「项目根目录运行 JSON 输出契约」这两条核心使用规则可直接作为理解命令行为的可执行文档参考。八、与相关命令配合从核验到安装的完整闭环plugin-list不是孤立命令它与命令族内其他成员构成完整工作流意图路由见 skills/lark-apps/SKILL.md命令职责plugin-list列出已声明插件包及安装状态只读核验plugin-install安装插件包--name key指定安装--version ver指定版本不传--name则批量安装actionPlugins中声明的全部插件plugin-uninstall卸载插件包典型操作闭环# 1. 查看当前声明与安装状态 lark-cli apps plugin-list --format json # 2. 发现 declared_not_installed 后安装安装后才能创建插件实例 lark-cli apps plugin-install --name plugin-key --version 1.0.0 # 3. 再次核验状态已变为 installed lark-cli apps plugin-list --format json关于具体可选插件及选型reference 建议读取应用仓库内的 Skill 文档.agents/skills/plugin-guide/SKILL.md本命令仅负责状态核验不承担选型职责。九、常见问题排查现象原因与处理报错提示package.json not found当前目录不是已初始化的妙搭应用项目按提示运行lark-cli apps init初始化或先cd到项目根目录再执行输出No plugins declared in package.json actionPlugins.项目尚未声明任何插件这是正常空态不代表命令失败状态恒为declared_not_installednode_modules中缺少对应包运行plugin-install不带--name可批量安装全部声明插件想查询远端应用数据却传了--app-idplugin-list是本地命令不接收--app-id需要查询远端应用信息请改用get --app-id app_id等远端命令十、总结lark-cli apps plugin-list以「本地文件核验」为设计核心它把package.json的actionPlugins声明与node_modules的实际安装结果交叉比对用installed/declared_not_installed两个状态直观呈现每个插件包的实装情况输出契约data.plugins[]的key/version/status稳定可解析是妙搭应用集成 AI 能力与飞书平台能力时最可靠的「现状检查」入口。配合plugin-install/plugin-uninstall即可完成插件从核验、安装到卸载的完整闭环管理。进一步深入可阅读 shortcuts/apps/apps_plugin_list.go、shortcuts/apps/plugin_common.go 及其测试 shortcuts/apps/apps_plugin_list_test.go。赞分享CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载相关推荐lark-cli 妙搭应用发布状态查询apps release-get 命令完整使用指南lark cli 妙搭应用发布状态查询 apps release get 命令完整使用指南 lark cli apps release get 是官方 LCLIAI 技能Lark CLI 插件包安装实战lark-cli apps plugin-install 命令深度指南Lark CLI 插件包安装实战 lark cli apps plugin install 命令深度指南 本指南以 Lark/飞书官方 CLIlarksuCLIAI 技能lark-cli apps plugin-uninstall 实战指南妙搭应用插件包的本地卸载命令与源码实现lark cli apps plugin uninstall 实战指南妙搭应用插件包的本地卸载命令与源码实现 本文以 Lark/飞书官方 CLI larkCLIAI 技能上一篇cpp-httplib1 个头文件里的完整 C HTTP/HTTPS 库下一篇Frappe CRM部署与运维指南生产环境最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考