From 116b75a0246ecf9c3721fc40eb7e66336b281964 Mon Sep 17 00:00:00 2001 From: Blomios Date: Sat, 12 Sep 2026 14:05:52 +0200 Subject: [PATCH] =?UTF-8?q?docs(sdk):=20contrat=20commandes/menus=20apres?= =?UTF-8?q?=20reload=20=E2=80=94=20handler=20manquant=20=3D=20erreur=20ret?= =?UTF-8?q?ryable=20jamais=20no-op=20silencieux,=20feedback=20skipped/fail?= =?UTF-8?q?ed=20host-owned,=20pas=20de=20contributes.commands=20separe,=20?= =?UTF-8?q?reload=20sans=20refresh=20auto=20par=20le=20plugin=20=E2=80=94?= =?UTF-8?q?=20#336=20(docs=20only,=20aucun=20push)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/commands-and-feedback.md | 13 +++++++------ docs/manifest.md | 4 +++- docs/menus.md | 8 +++++--- docs/project-plugin-assignments.md | 2 ++ 4 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/commands-and-feedback.md b/docs/commands-and-feedback.md index 7787086..41819ed 100644 --- a/docs/commands-and-feedback.md +++ b/docs/commands-and-feedback.md @@ -25,9 +25,10 @@ manifest contribution -> command id -> registered command handler -> optional ta not by a fake task. - Feedback objects must be stable enough for agents and programmatic callers to parse, and their messages must be readable by humans. -- The current human menu-click UI does not guarantee display of a command - handler return value. When a human must see feedback from a menu action, open - or focus a plugin layout/window from the handler with +- The human menu-click UI presents minimal host-owned feedback for `skipped` + and `failed` results. It intentionally does not expose the raw result payload. + For successful actions and richer status, open or focus a plugin layout/window + from the handler with `ctx.services.windows.open({ layoutType, state })`. ## Preconditions @@ -78,9 +79,9 @@ Use the same `status` vocabulary consistently: Visible surfaces are intentionally distinct: -- Command return value: immediate feedback for programmatic callers, agents and - future host surfaces. It is not a guaranteed visible UI surface for current - human menu clicks. +- Command return value: immediate feedback for programmatic callers and agents. + The human menu host maps `skipped` and `failed` results to concise feedback; + plugin-specific fields and messages are not displayed verbatim. - Plugin layout/window: the normative visible feedback surface for menu actions that need to show status, results or next steps to a human. The layout must be declared in `idea-plugin.json` and registered during activation. diff --git a/docs/manifest.md b/docs/manifest.md index daee634..bac8bbb 100644 --- a/docs/manifest.md +++ b/docs/manifest.md @@ -243,7 +243,9 @@ public id used by both `ctx.layouts.register({ type, component })` and Contribution ids are part of the runtime contract: -- commands can only register ids declared by `contributes.menuItems[*].command`; +- there is no separate `contributes.commands` collection; commands can only + register ids declared by `contributes.menuItems[*].command` or + `contributes.slashCommands[*].command`; - layouts can only register `type` values declared by `contributes.layouts`; - `services.windows.open({ layoutType })` only accepts a layout type declared by the calling plugin. diff --git a/docs/menus.md b/docs/menus.md index 19b638c..606687d 100644 --- a/docs/menus.md +++ b/docs/menus.md @@ -41,9 +41,11 @@ export function activate(ctx: ActivateContext): void { ## Rules -- A command can only be registered if at least one manifest menu item declares - that exact `command` id. -- Missing command handlers are a no-op when the user clicks the menu item. +- There is no separate `contributes.commands` collection. A command can only be + registered if at least one manifest `menuItems[].command` or + `slashCommands[].command` entry declares that exact id. +- A missing command handler is surfaced by the host as a retryable reload error; + menu clicks must never fail silently. - A handler owns precondition checks and feedback. See [Commands And Feedback](commands-and-feedback.md). - Menu item `when` expressions are evaluated by the host; unsupported or false diff --git a/docs/project-plugin-assignments.md b/docs/project-plugin-assignments.md index d88835f..c87410c 100644 --- a/docs/project-plugin-assignments.md +++ b/docs/project-plugin-assignments.md @@ -150,6 +150,8 @@ These actions solve different problems: - Reload the plugin after rebuilding or replacing its installed package. Reload refreshes the plugin manifest, runtime bundle, contributions, and packaged skill Markdown. It does not change project activation or agent assignments. + Plugins do not call a contribution-refresh API themselves: rebuild or replace + the installed package, then use the host reload action. - Relaunch the agent after enabling or disabling a project plugin, changing its skill/tool assignments, or manually editing `.ideai/project-plugins.json`. Agent capabilities are resolved into a launch-time snapshot, so an already