From 4e2abab504d46fc53e562afca07cb659a45a5466 Mon Sep 17 00:00:00 2001 From: zhangli Date: Thu, 25 Jun 2026 21:42:50 +0800 Subject: [PATCH] refactor(plugin): hide instance commands, delegate to repo Skill Hide +plugin-instance-create/update/delete/get/list from CLI help. Remove instance reference files from lark-apps skill. Route instance CRUD and call code generation to project repo plugin-guide skill. Go instance code preserved, just hidden. --- shortcuts/apps/plugin_instance_create.go | 2 +- shortcuts/apps/plugin_instance_delete.go | 2 +- shortcuts/apps/plugin_instance_get.go | 2 +- shortcuts/apps/plugin_instance_list.go | 2 +- shortcuts/apps/plugin_instance_update.go | 2 +- skills/lark-apps/SKILL.md | 2 +- .../lark-apps-plugin-instance-create.md | 54 ------------------- .../lark-apps-plugin-instance-delete.md | 26 --------- .../lark-apps-plugin-instance-get.md | 23 -------- .../lark-apps-plugin-instance-list.md | 25 --------- .../lark-apps-plugin-instance-update.md | 42 --------------- 11 files changed, 6 insertions(+), 176 deletions(-) delete mode 100644 skills/lark-apps/references/lark-apps-plugin-instance-create.md delete mode 100644 skills/lark-apps/references/lark-apps-plugin-instance-delete.md delete mode 100644 skills/lark-apps/references/lark-apps-plugin-instance-get.md delete mode 100644 skills/lark-apps/references/lark-apps-plugin-instance-list.md delete mode 100644 skills/lark-apps/references/lark-apps-plugin-instance-update.md diff --git a/shortcuts/apps/plugin_instance_create.go b/shortcuts/apps/plugin_instance_create.go index f40cdb8b5..29c75b30a 100644 --- a/shortcuts/apps/plugin_instance_create.go +++ b/shortcuts/apps/plugin_instance_create.go @@ -22,7 +22,7 @@ var AppsPluginInstanceCreate = common.Shortcut{ Service: appsService, Command: "+plugin-instance-create", Description: "Create a plugin instance (write capability JSON)", - Risk: "write", + Risk: "write", Hidden: true, Flags: []common.Flag{ {Name: "id", Desc: "semantic instance id (lowercase + hyphens); auto-derived from plugin key if omitted"}, {Name: "plugin", Desc: "plugin key (e.g. @official-plugins/ai-text-generate); version is resolved from package.json actionPlugins", Required: true}, diff --git a/shortcuts/apps/plugin_instance_delete.go b/shortcuts/apps/plugin_instance_delete.go index 4bc428140..88ee07151 100644 --- a/shortcuts/apps/plugin_instance_delete.go +++ b/shortcuts/apps/plugin_instance_delete.go @@ -20,7 +20,7 @@ var AppsPluginInstanceDelete = common.Shortcut{ Service: appsService, Command: "+plugin-instance-delete", Description: "Delete a plugin instance", - Risk: "write", + Risk: "write", Hidden: true, Flags: []common.Flag{ {Name: "id", Desc: "instance id", Required: true}, {Name: "project-path", Desc: "project root path (defaults to current directory)"}, diff --git a/shortcuts/apps/plugin_instance_get.go b/shortcuts/apps/plugin_instance_get.go index 64b0d3186..27eeff3df 100644 --- a/shortcuts/apps/plugin_instance_get.go +++ b/shortcuts/apps/plugin_instance_get.go @@ -19,7 +19,7 @@ var AppsPluginInstanceGet = common.Shortcut{ Service: appsService, Command: "+plugin-instance-get", Description: "Get a plugin instance by id", - Risk: "read", + Risk: "read", Hidden: true, Flags: []common.Flag{ {Name: "id", Desc: "instance id (filename without .json in capabilities/)", Required: true}, {Name: "project-path", Desc: "project root path (defaults to current directory)"}, diff --git a/shortcuts/apps/plugin_instance_list.go b/shortcuts/apps/plugin_instance_list.go index c298a5209..4c1d8d3eb 100644 --- a/shortcuts/apps/plugin_instance_list.go +++ b/shortcuts/apps/plugin_instance_list.go @@ -18,7 +18,7 @@ var AppsPluginInstanceList = common.Shortcut{ Service: appsService, Command: "+plugin-instance-list", Description: "List all plugin instances in the project", - Risk: "read", + Risk: "read", Hidden: true, Flags: []common.Flag{ {Name: "summary", Type: "bool", Desc: "show only id and name"}, {Name: "project-path", Desc: "project root path (defaults to current directory)"}, diff --git a/shortcuts/apps/plugin_instance_update.go b/shortcuts/apps/plugin_instance_update.go index 3b0723da0..9a4cf667e 100644 --- a/shortcuts/apps/plugin_instance_update.go +++ b/shortcuts/apps/plugin_instance_update.go @@ -21,7 +21,7 @@ var AppsPluginInstanceUpdate = common.Shortcut{ Service: appsService, Command: "+plugin-instance-update", Description: "Update a plugin instance (modify capability JSON)", - Risk: "write", + Risk: "write", Hidden: true, Flags: []common.Flag{ {Name: "id", Desc: "instance id", Required: true}, {Name: "name", Desc: "new display name"}, diff --git a/skills/lark-apps/SKILL.md b/skills/lark-apps/SKILL.md index 36263b3a7..8970b2147 100644 --- a/skills/lark-apps/SKILL.md +++ b/skills/lark-apps/SKILL.md @@ -29,7 +29,7 @@ metadata: | 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference | | 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) | | 查看某次会话某一轮（turn）的回复消息（含仍在生成中的本轮）/ 导出上一轮模型回复（"这一轮回复了什么""上一轮的回复""导出某轮消息"） | 先 `+session-get`（取 `latest_turn.turn_id`）-> `+session-messages-list --turn-id `（仅 user 身份；分页用 `--page-token`） | [`lark-apps-session-messages-list.md`](references/lark-apps-session-messages-list.md) | -| 插件集成 — 用户需求涉及外部能力或提到插件/Plugin/Capability。**判断规则**：(1) AI 模型服务能力（文本生成、图片理解、语音识别等）**必须**通过插件接入，禁止自行编写替代实现；(2) 飞书平台能力（操作多维表格、发送消息等）**优先**查看是否有对应插件，插件不支持时再考虑自行通过飞书 OpenAPI 实现 | **⚠️ 必须先读仓库 Skill** `/.agents/skills/plugin-guide/SKILL.md`（插件目录、Schema 规则、CRUD 流程、调用代码生成等完整指引）。CLI 命令参考见各 `lark-apps-plugin-*.md` reference | 仓库 Skill | +| 插件集成 — 用户需求涉及外部能力或提到插件/Plugin/Capability。**判断规则**：(1) AI 模型服务能力（文本生成、图片理解、语音识别等）**必须**通过插件接入，禁止自行编写替代实现；(2) 飞书平台能力（操作多维表格、发送消息等）**优先**查看是否有对应插件，插件不支持时再考虑自行通过飞书 OpenAPI 实现 | **⚠️ 必须先读仓库 Skill** `/.agents/skills/plugin-guide/SKILL.md`（插件目录、Schema 规则、实例 CRUD、调用代码生成等完整指引）。插件包管理（安装/卸载/查看）参考 [`lark-apps-plugin-install.md`](references/lark-apps-plugin-install.md) / [`lark-apps-plugin-uninstall.md`](references/lark-apps-plugin-uninstall.md) / [`lark-apps-plugin-list.md`](references/lark-apps-plugin-list.md) | 仓库 Skill | ## 选择开发路径（进意图路由前先判这步） diff --git a/skills/lark-apps/references/lark-apps-plugin-instance-create.md b/skills/lark-apps/references/lark-apps-plugin-instance-create.md deleted file mode 100644 index a16e3090c..000000000 --- a/skills/lark-apps/references/lark-apps-plugin-instance-create.md +++ /dev/null @@ -1,54 +0,0 @@ -# apps +plugin-instance-create - -创建插件实例。运行时命令事实以 `lark-cli apps +plugin-instance-create --help` 为准。 - -## 前置条件 - -本命令的 `--plugin`、`--form-value`、`--params-schema` 参数取值均依赖仓库 Skill 中的规则。未读 `/.agents/skills/plugin-guide/SKILL.md` 直接执行会导致参数错误。 - -## 何时用 - -用户要接入某个 AI 能力或飞书平台能力，插件包已安装后，创建对应的插件实例。 - -## 命令骨架 - -- `--id`：语义化 ID，小写+短横线。 -- `--plugin`：插件包 key（从仓库 Skill 的「AI 插件目录」获取）。 -- `--name`：实例显示名称。 -- `--description`：实例描述（可选）。 -- `--form-value`：formValue JSON，或 `@file.json` 从文件读取。 -- `--params-schema`：paramsSchema JSON，或 `@file.json` 从文件读取。 -- `--project-path`：妙搭应用根目录。 -- `--force`：覆盖已存在的同 ID 实例（可选）。 - -## 示例 - -```bash -# plugin-key、formValue、paramsSchema 的设计规则见仓库 Skill -lark-cli apps +plugin-instance-create \ - --id <语义化ID> \ - --plugin \ - --name <名称> \ - --form-value \ - --params-schema \ - --project-path --format json - -# 大 JSON 场景用 @file 传入 -lark-cli apps +plugin-instance-create \ - --id <语义化ID> \ - --plugin \ - --name <名称> \ - --form-value @form.json --params-schema @schema.json \ - --project-path --format json -``` - -## 输出契约 - -- 成功返回 `ok: true` + 创建的实例配置。 -- 校验失败返回 `ok: false` + `error.hint`，按仓库 Skill 中的重试协议处理（max 3 次，create 重试加 `--force`）。 - -## Agent 规则 - -- 创建前必须先 `+plugin-install` 安装插件包。 -- formValue / paramsSchema 的设计规则在仓库 Skill 中，不要凭记忆猜测。 -- 创建成功后，读 manifest + capability JSON，再按仓库 Skill 生成调用代码。 diff --git a/skills/lark-apps/references/lark-apps-plugin-instance-delete.md b/skills/lark-apps/references/lark-apps-plugin-instance-delete.md deleted file mode 100644 index fcb134101..000000000 --- a/skills/lark-apps/references/lark-apps-plugin-instance-delete.md +++ /dev/null @@ -1,26 +0,0 @@ -# apps +plugin-instance-delete - -删除插件实例。运行时命令事实以 `lark-cli apps +plugin-instance-delete --help` 为准。 - -## 何时用 - -用户不再需要某个插件实例时删除。删除前应先清理代码中对该实例的引用。 - -## 命令骨架 - -- `--id`：要删除的实例 ID。 -- `--project-path`：妙搭应用根目录。 - -## 示例 - -```bash -# 先扫描代码引用 -grep -rn "load('task-text-summary')" ./my-app/client/ ./my-app/server/ - -# 确认无引用或已清理后删除 -lark-cli apps +plugin-instance-delete --id task-text-summary --project-path ./my-app --format json -``` - -## 输出契约 - -- 幂等操作，文件不存在也返回 `deleted: true`。 diff --git a/skills/lark-apps/references/lark-apps-plugin-instance-get.md b/skills/lark-apps/references/lark-apps-plugin-instance-get.md deleted file mode 100644 index 1361dbda8..000000000 --- a/skills/lark-apps/references/lark-apps-plugin-instance-get.md +++ /dev/null @@ -1,23 +0,0 @@ -# apps +plugin-instance-get - -查询单个插件实例的完整配置。运行时命令事实以 `lark-cli apps +plugin-instance-get --help` 为准。 - -## 何时用 - -需要查看某个插件实例的当前 paramsSchema、formValue 等配置时。也用于生成调用代码前获取实例信息。 - -## 命令骨架 - -- `--id`：实例 ID。 -- `--project-path`：妙搭应用根目录。 - -## 示例 - -```bash -lark-cli apps +plugin-instance-get --id task-text-summary --project-path ./my-app --format json -``` - -## 输出契约 - -- 返回实例的完整 JSON 配置（id、pluginKey、pluginVersion、name、description、paramsSchema、formValue 等）。 -- 实例不存在时返回 `instance not found`。 diff --git a/skills/lark-apps/references/lark-apps-plugin-instance-list.md b/skills/lark-apps/references/lark-apps-plugin-instance-list.md deleted file mode 100644 index 3839cac67..000000000 --- a/skills/lark-apps/references/lark-apps-plugin-instance-list.md +++ /dev/null @@ -1,25 +0,0 @@ -# apps +plugin-instance-list - -列出当前项目的所有插件实例。运行时命令事实以 `lark-cli apps +plugin-instance-list --help` 为准。 - -## 何时用 - -查看项目中已创建了哪些插件实例，判断是否需要新建或可以复用已有实例。 - -## 命令骨架 - -- `--summary`：仅输出 id + name（可选）。 -- `--project-path`：妙搭应用根目录。 - -## 示例 - -```bash -lark-cli apps +plugin-instance-list --project-path ./my-app --format json - -# 仅看 id 和 name -lark-cli apps +plugin-instance-list --summary --project-path ./my-app -``` - -## 输出契约 - -- 返回所有实例的配置列表。`--summary` 时仅返回 id 和 name。 diff --git a/skills/lark-apps/references/lark-apps-plugin-instance-update.md b/skills/lark-apps/references/lark-apps-plugin-instance-update.md deleted file mode 100644 index 9662687d1..000000000 --- a/skills/lark-apps/references/lark-apps-plugin-instance-update.md +++ /dev/null @@ -1,42 +0,0 @@ -# apps +plugin-instance-update - -更新已有插件实例的配置。运行时命令事实以 `lark-cli apps +plugin-instance-update --help` 为准。 - -## 前置条件 - -`--form-value`、`--params-schema` 的设计规则在仓库 Skill 中。未读 `/.agents/skills/plugin-guide/SKILL.md` 直接修改会导致参数错误。 - -## 何时用 - -用户要修改已有插件实例的 name、formValue 或 paramsSchema（如改 prompt、换参数）。 - -## 命令骨架 - -- `--id`：要更新的实例 ID。 -- `--name`：新名称（可选）。 -- `--form-value`：新 formValue JSON 或 `@file.json`（可选）。 -- `--params-schema`：新 paramsSchema JSON 或 `@file.json`（可选）。 -- `--project-path`：妙搭应用根目录。 - -只传需要修改的字段，CLI 自动保留不可变字段（id / pluginKey / pluginVersion / createdAt）。 - -## 示例 - -```bash -# 只改名 -lark-cli apps +plugin-instance-update --id --name <新名称> --project-path - -# 改 formValue + paramsSchema -lark-cli apps +plugin-instance-update --id \ - --form-value @form.json --params-schema @schema.json \ - --project-path --format json -``` - -## 输出契约 - -- 成功返回 `ok: true` + 更新后的实例配置。 -- 校验失败返回 `ok: false` + `error.hint`，按仓库 Skill 中的重试协议处理。 - -## Agent 规则 - -- paramsSchema 变化时，需扫描代码引用（`grep -rn "load('${id}')" /`）并更新调用代码。