@@ -140,18 +140,52 @@ generic contracts; Plan Mode can use them, but so can approval workflows,
140140workspace policy gates, background monitors, setup wizards, and UI companion
141141plugins.
142142143-| Method | Contract it owns |
144-| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
145-| `api.registerSessionExtension(...)` | Plugin-owned, JSON-compatible session state projected through Gateway sessions |
146-| `api.enqueueNextTurnInjection(...)` | Durable exactly-once context injected into the next agent turn for one session |
147-| `api.registerTrustedToolPolicy(...)` | Bundled/trusted pre-plugin tool policy that can block or rewrite tool params |
148-| `api.registerToolMetadata(...)` | Tool catalog display metadata without changing the tool implementation |
149-| `api.registerCommand(...)` | Scoped plugin commands; command results can set `continueAgent: true`; Discord native commands support `descriptionLocalizations` |
150-| `api.registerControlUiDescriptor(...)` | Control UI contribution descriptors for session, tool, run, or settings surfaces |
151-| `api.registerRuntimeLifecycle(...)` | Cleanup callbacks for plugin-owned runtime resources on reset/delete/reload paths |
152-| `api.registerAgentEventSubscription(...)` | Sanitized event subscriptions for workflow state and monitors |
153-| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Per-run plugin scratch state cleared on terminal run lifecycle |
154-| `api.registerSessionSchedulerJob(...)` | Plugin-owned session scheduler job records with deterministic cleanup |
143+| Method | Contract it owns |
144+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
145+| `api.session.state.registerSessionExtension(...)` | Plugin-owned, JSON-compatible session state projected through Gateway sessions |
146+| `api.session.workflow.enqueueNextTurnInjection(...)` | Durable exactly-once context injected into the next agent turn for one session |
147+| `api.registerTrustedToolPolicy(...)` | Bundled/trusted pre-plugin tool policy that can block or rewrite tool params |
148+| `api.registerToolMetadata(...)` | Tool catalog display metadata without changing the tool implementation |
149+| `api.registerCommand(...)` | Scoped plugin commands; command results can set `continueAgent: true`; Discord native commands support `descriptionLocalizations` |
150+| `api.session.controls.registerControlUiDescriptor(...)` | Control UI contribution descriptors for session, tool, run, or settings surfaces |
151+| `api.lifecycle.registerRuntimeLifecycle(...)` | Cleanup callbacks for plugin-owned runtime resources on reset/delete/reload paths |
152+| `api.agent.events.registerAgentEventSubscription(...)` | Sanitized event subscriptions for workflow state and monitors |
153+| `api.runContext.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Per-run plugin scratch state cleared on terminal run lifecycle |
154+| `api.session.workflow.registerSessionSchedulerJob(...)` | Cleanup metadata for plugin-owned scheduler jobs; does not schedule work or create task records |
155+| `api.session.workflow.sendSessionAttachment(...)` | Bundled-only host-mediated file attachment delivery to the active direct-outbound session route |
156+| `api.session.workflow.scheduleSessionTurn(...)` / `unscheduleSessionTurnsByTag(...)` | Bundled-only Cron-backed scheduled session turns plus tag-based cleanup |
157+| `api.session.controls.registerSessionAction(...)` | Typed session actions clients can dispatch through the Gateway |
158+159+Use the grouped namespaces for new plugin code:
160+161+- `api.session.state.registerSessionExtension(...)`
162+- `api.session.workflow.enqueueNextTurnInjection(...)`
163+- `api.session.workflow.registerSessionSchedulerJob(...)`
164+- `api.session.workflow.sendSessionAttachment(...)`
165+- `api.session.workflow.scheduleSessionTurn(...)`
166+- `api.session.workflow.unscheduleSessionTurnsByTag(...)`
167+- `api.session.controls.registerSessionAction(...)`
168+- `api.session.controls.registerControlUiDescriptor(...)`
169+- `api.agent.events.registerAgentEventSubscription(...)`
170+- `api.agent.events.emitAgentEvent(...)`
171+- `api.runContext.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)`
172+- `api.lifecycle.registerRuntimeLifecycle(...)`
173+174+The equivalent flat methods remain available as deprecated compatibility
175+aliases for existing plugins. Do not add new plugin code that calls
176+`api.registerSessionExtension`, `api.enqueueNextTurnInjection`,
177+`api.registerControlUiDescriptor`, `api.registerRuntimeLifecycle`,
178+`api.registerAgentEventSubscription`, `api.emitAgentEvent`,
179+`api.setRunContext`, `api.getRunContext`, `api.clearRunContext`,
180+`api.registerSessionSchedulerJob`, `api.registerSessionAction`,
181+`api.sendSessionAttachment`, `api.scheduleSessionTurn`, or
182+`api.unscheduleSessionTurnsByTag` directly.
183+184+`scheduleSessionTurn(...)` is a session-scoped convenience over the Gateway
185+Cron scheduler. Cron owns timing and creates the background task record when the
186+turn runs; the Plugin SDK only constrains the target session, plugin-owned
187+naming, and cleanup. Use `api.runtime.tasks.managedFlows` inside the scheduled
188+turn when the work itself needs durable multi-step Task Flow state.
155189156190The contracts intentionally split authority:
157191此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。