docs(sdk): clarify pluginRoot scope for runtime plugins — #285 (activation-context: ActivateContext n'expose ni répertoire d'installation ni racine package ni file URL; commands-and-feedback + services: runCommand project/workspace-scoped, aucune résolution package-relative des scripts packagés; manifest: substitution ${pluginRoot}/${appDataDir} étendue par l'hôte uniquement dans contributes.mcpServers command/args/env/cwd; QA verte: npm run build, cohérence champs vs types SDK vérifiée)

This commit is contained in:
2026-09-08 17:19:57 +02:00
parent 7db819c647
commit 5f9c2f9193
4 changed files with 46 additions and 1 deletions

View File

@ -43,6 +43,9 @@ Check preconditions before calling `runCommand()`:
- `ownerAgentId` is a real agent id when the work is owned by an agent workflow.
Do not use all-zero placeholders in production.
- `cwd` is relative to the project root.
- `command`, `args` and `cwd` do not resolve package-relative plugin resources.
Do not use `runCommand()` to launch scripts shipped inside the plugin package;
there is no public runtime `pluginRoot` path in `activate(ctx)`.
- `command` and `args` are separate values. Do not shell-join user input.
If any required precondition fails, return a skipped result:
@ -196,3 +199,20 @@ await ctx.services?.tasks.runCommand({
This creates misleading Work history, uses a placeholder owner and turns a
precondition failure into a fake task. Return `status: "skipped"` instead.
Do not try to reach packaged plugin scripts through workspace-relative paths:
```ts
await ctx.services?.tasks.runCommand({
projectId: project.id,
ownerAgentId,
label: "Run packaged tests",
command: "scripts/run-unity-tests.sh",
cwd: "."
});
```
`scripts/run-unity-tests.sh` above is resolved like any other executable visible
from the project task environment; it is not resolved relative to the plugin
package. Use a project-owned script or an executable available on `PATH` until a
dedicated packaged-resource API exists.