docs(sdk): schéma project-plugins.json v1 + assignation skills/tools agents — #283 (project-plugin-assignments: workflow install→enable→assign→relaunch, schéma complet plugins/agents/skills/tools camelCase, ordre d'injection natif puis plugin, tombstones inertes uninstall/reinstall, validation UI/API idempotente vs édition manuelle, reload plugin ≠ relance agent; liens croisés manifest/codex-skills/README; QA verte: npm run build, liens docs vérifiés)
This commit is contained in:
@ -17,6 +17,7 @@ exports `activate(ctx)`.
|
||||
- [Services](docs/services.md): workspace, tasks, tooling, events, config, terminal and windows facades.
|
||||
- [Packaging And Distribution](docs/packaging-distribution.md): build output, archive layout, hot reload and dependency rules.
|
||||
- [Codex Skills And IdeA Plugins](docs/codex-skills-and-idea-plugins.md): separate IdeA-native plugin skills from Codex plugin discovery.
|
||||
- [Project Plugin Assignments](docs/project-plugin-assignments.md): enable plugins per project and assign skills and MCP tools to agents.
|
||||
|
||||
The installable example lives in [`examples/hello-plugin`](examples/hello-plugin).
|
||||
It demonstrates a menu command, storage, background-task feedback, a React layout
|
||||
|
||||
@ -40,7 +40,9 @@ loading.
|
||||
For multi-harness IdeA agent skills, declare `contributes.skills` in
|
||||
`idea-plugin.json`, ship the referenced Markdown files inside the package,
|
||||
install the plugin in IdeA, enable it in the target project, and assign the
|
||||
skills to the target agents.
|
||||
skills to the target agents. See
|
||||
[Project Plugin Assignments](project-plugin-assignments.md) for the project
|
||||
settings schema and the complete install, enable, assign, and relaunch workflow.
|
||||
|
||||
For Codex-specific plugin skills, install the Codex plugin through the Codex
|
||||
plugin mechanism for the intended scope, then assign or enable those skills
|
||||
|
||||
@ -177,6 +177,10 @@ Skill contribution rules:
|
||||
- Installing a plugin globally is not enough: a project must enable the plugin,
|
||||
then assign the skill to the target agent.
|
||||
|
||||
See [Project Plugin Assignments](project-plugin-assignments.md) for the
|
||||
`.ideai/project-plugins.json` schema, validation rules, assignment order, and
|
||||
agent relaunch requirements.
|
||||
|
||||
`contributes.layouts` is the only surface for plugin layouts. The same layout
|
||||
contribution can be mounted inside an IdeA layout cell or opened in a detached OS
|
||||
window. Do not add a separate manifest contribution type for windows.
|
||||
|
||||
154
docs/project-plugin-assignments.md
Normal file
154
docs/project-plugin-assignments.md
Normal file
@ -0,0 +1,154 @@
|
||||
# Project Plugin Assignments
|
||||
|
||||
IdeA installs plugin packages globally, but enables their capabilities per
|
||||
project and assigns agent-facing capabilities per agent. Project choices are
|
||||
stored in the project-owned `.ideai/project-plugins.json` file.
|
||||
|
||||
The normal workflow is:
|
||||
|
||||
1. Install the plugin globally in IdeA.
|
||||
2. Enable the installed plugin for the target project.
|
||||
3. Assign selected plugin skills and MCP tools to each target agent.
|
||||
4. Relaunch the agent so its capability snapshot includes the new assignments.
|
||||
|
||||
Installation alone does not enable a plugin in a project. Enabling a plugin does
|
||||
not automatically grant all of its capabilities to every agent.
|
||||
|
||||
## Version 1 Schema
|
||||
|
||||
The current schema version is `1`. A complete example is:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"plugins": [
|
||||
{
|
||||
"pluginId": "com.example.unity-plugin",
|
||||
"enabled": true
|
||||
}
|
||||
],
|
||||
"agents": [
|
||||
{
|
||||
"agentId": "2a0e42e2-3c5f-4f30-a679-034b460cd59e",
|
||||
"skills": [
|
||||
{
|
||||
"pluginId": "com.example.unity-plugin",
|
||||
"skillId": "unity.build-debug"
|
||||
}
|
||||
],
|
||||
"tools": [
|
||||
{
|
||||
"pluginId": "com.example.unity-plugin",
|
||||
"serverId": "unity-editor",
|
||||
"toolName": "unity_build"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The top-level fields are:
|
||||
|
||||
- `version`: required schema version. It must currently be `1`; unsupported
|
||||
versions are rejected.
|
||||
- `plugins`: project activation entries. Each entry contains the stable global
|
||||
`pluginId` and an `enabled` boolean.
|
||||
- `agents`: per-agent assignments. Each entry identifies an IdeA project agent
|
||||
by `agentId` and contains ordered `skills` and `tools` arrays.
|
||||
|
||||
An agent skill reference contains:
|
||||
|
||||
- `pluginId`: the id from the owning plugin's `idea-plugin.json`.
|
||||
- `skillId`: the stable `contributes.skills[].id` within that plugin.
|
||||
|
||||
An agent MCP tool reference contains:
|
||||
|
||||
- `pluginId`: the id from the owning plugin's `idea-plugin.json`.
|
||||
- `serverId`: the stable `contributes.mcpServers[].id` within that plugin.
|
||||
- `toolName`: the exact tool name advertised by that MCP server. The UI accepts
|
||||
this name as text because a dynamic MCP tool catalogue is not yet available.
|
||||
|
||||
Missing `plugins`, `agents`, `skills`, or `tools` arrays default to empty arrays
|
||||
when IdeA reads the document. Prefer writing them explicitly for clarity and
|
||||
forward-compatible review.
|
||||
|
||||
## Assignment And Injection Order
|
||||
|
||||
Array order is significant. IdeA keeps plugin skill assignments in the order in
|
||||
which they were added. At agent launch, IdeA resolves the agent's native skills
|
||||
first, in agent-manifest order, then its plugin skills in the order stored in
|
||||
`agents[].skills`. Unavailable assignments are skipped without reordering the
|
||||
remaining skills.
|
||||
|
||||
The resolved skill catalogue is injected into the agent's orchestration context
|
||||
before the agent persona. Each supported harness receives the same ordered
|
||||
IdeA-native capability snapshot. The skill body remains read-only package
|
||||
content and is available through `idea_skill_read` only when that skill was
|
||||
resolved for the launched agent.
|
||||
|
||||
## Tombstones
|
||||
|
||||
Plugin activation entries and agent assignments are intentionally retained when
|
||||
a plugin, skill, or MCP server is temporarily missing. These dangling entries
|
||||
are tombstones: they preserve project intent across uninstall/reinstall or a
|
||||
temporary manifest change.
|
||||
|
||||
A tombstone is inert. IdeA skips it when resolving capabilities, and the project
|
||||
settings UI marks stale skill or server references as missing or obsolete. The
|
||||
UI lets users remove those references explicitly. Reinstalling and activating a
|
||||
matching plugin makes a retained assignment resolvable again.
|
||||
|
||||
Disabling a plugin also keeps its assignments. They become effective again only
|
||||
after the plugin is enabled and runtime-active for the project.
|
||||
|
||||
## UI And API Validation
|
||||
|
||||
Prefer the project plugin settings UI or its backing API commands over manual
|
||||
editing. They apply the following rules:
|
||||
|
||||
- Enabling requires the plugin package to be installed globally. Disabling a
|
||||
missing plugin is allowed so a retained activation can be cleared.
|
||||
- Assigning a skill requires an existing project agent, an enabled and
|
||||
runtime-active plugin, and a matching `contributes.skills[].id`.
|
||||
- Assigning a tool requires an existing project agent, an enabled and
|
||||
runtime-active plugin, a matching `contributes.mcpServers[].id`, and a
|
||||
non-empty `toolName`.
|
||||
- Assign and unassign operations are idempotent. Assigning an existing reference
|
||||
does not duplicate it; unassigning a missing reference is harmless.
|
||||
- Unassign operations remain available for tombstones, so stale references can
|
||||
be removed even when their plugin capability no longer resolves.
|
||||
|
||||
The project settings read API returns both the persisted document and the
|
||||
currently installed plugin manifests. The UI uses this catalogue to offer only
|
||||
skills and MCP servers from plugins enabled for the project, while still
|
||||
surfacing persisted tombstones.
|
||||
|
||||
## Manual Editing
|
||||
|
||||
The file is project-owned and may be edited manually, for example in version
|
||||
control or automation. Stop or relaunch affected agents around the edit, keep
|
||||
the document valid JSON, preserve `version: 1`, use the real project agent UUID,
|
||||
and copy plugin, skill, and server ids exactly from the plugin manifest.
|
||||
|
||||
Manual editing bypasses the mutation checks described above. A syntactically
|
||||
valid document may therefore contain duplicates, unknown agents, disabled or
|
||||
missing plugins, unknown capability ids, or an invalid tool name. Such entries
|
||||
may remain inert or fail later operations. Use the UI/API whenever possible to
|
||||
receive immediate validation and idempotent updates.
|
||||
|
||||
## Reloading Plugins And Relaunching Agents
|
||||
|
||||
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.
|
||||
- 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
|
||||
running agent does not acquire assignment changes retroactively.
|
||||
|
||||
When both package content and assignments changed, reload the plugin first,
|
||||
confirm it is enabled for the project, update the assignments, then relaunch the
|
||||
agent.
|
||||
Reference in New Issue
Block a user