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:
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