AIDAWORK / SEQUENCE

Plugin V2 三仓全链路：从 C0 广告摘要冻结、PluginCallJournal 栅栏到 6 表回执结算

独立图页 ↗

机制说明（SoT）图是辅读 · 结论以说明与证据为准

Host 只为允许、平台支持且不处于调试状态的 Bundle 广告投影。调用通过 Worker MCP 与 Host 能力代理协作，PluginCallJournal 参与记录执行回执。包身份、协议与结果引用需遵循同一 V2 合同。

本页可直接往下读完整机制说明，不需要「演示 / 播放故事」。术语不熟先看术语表。

先读机制说明，结论以说明与证据为准 · 基于固定代码版本核验 · 部署状态另行确认

机制说明（全文）

Plugin Host V2 运行时

从包到可调用 Worker

该信任模型面向可信插件。Worker 是普通用户进程，Host 能力代理负责合同范围内的能力访问，不能被解释成能够隔离恶意代码的操作系统沙箱。

迟到回执（Plugins 658df7f）：Host 已取消或超时后，handler 若返回带 executionState 的失败 ToolResult，SDK 仍把它作为该调用回执送达（保留部分结果与已提交 artifact，经 _meta.aida.executionState 透传，不被 CALL_CANCELLED 覆盖）；其他迟到返回仍转为取消/超时错误。

证据与范围

aida-desktop · apps/desktop/electron/plugin-host/plugin-host.ts L659–689 · listProjections · 4346d79eb364
aida-plugins · docs/plugin-v2-contract.md L1–44 · a33ce3733365
aida-desktop · apps/desktop/electron/plugin-host/plugin-host.ts L1–59 · 4346d79eb364
aida-desktop · apps/desktop/electron/plugin-host/plugin-host.ts L59–100 · 4346d79eb364

结论来自固定版本的静态源码与合同阅读；实现存在、默认开关和生产启用分别判断。本站代码证据面板列出声明状态与具体限制。

aida-plugins · packages/sdk-js/src/server.mjs L177–217 · executionState · a33ce3733365

条件产物：Host 独立核对（Desktop 2026-10-29）

plugin-runtime.ts 不仅接受 Worker 声明：assertConditionalArtifactResult 将 structuredContent 的 conditionalArtifact 与返回 artifact refs、Main PluginCallLease.committedArtifacts() 三方核对。produced 必须完整列出本调用所有 committed IDs；非 produced 要求零产物；declaration 的 scope binding、inputMatch 与输出 schema 也校验。不能把 Worker 返回成功等同于产物业务完成。校验失败进入 result-invalid 分支；派发后的非 read effect 若无法确认 completed，结果可为 unknown，不声称无副作用。

Plugin/已安装 Skill 的执行信任由 Main authorizeInstalledCapability 提供，不再有通用逐次批准或 always-allow store；身份/请求/实例/原任务检查和独立资源授权仍保留。Worker 是普通 OS 用户进程，并非沙箱。

证据：aida-desktop · apps/desktop/electron/plugin-host/plugin-runtime.ts L139–220 · assertConditionalArtifactResult · 4346d79eb364；apps/desktop/electron/plugin-host/plugin-call-lease.ts L1–12 · 4346d79eb364；apps/desktop/shared/generated/plugin-v2/semantics.mjs L80–129 · 4346d79eb364。
Report 四个合同场景已回默认 System；它验证 Desktop 冻结 fixture 的专用 report_export producer，不代表所有官方业务包已采用声明或通过验收。证据：docs/testing/system-payroll-packages.md L1–25 · 4346d79eb364。

三仓（Agent ↔ Desktop ↔ Plugins SDK）插件调用全链路微追踪（视图 `plugin-end-to-end-trace`）

对应交互图 /topics/plugin-v2-host-runtime/plugin-end-to-end-trace/（analyses/aidawork/plugin-v2-host-runtime/plugin-end-to-end-trace.sequence.json），一次 Plugin V2 工具调用横跨三个仓库的完整状态机与数据表核验链如下：

跳点	所属仓与核心函数	校验规则 / 持久化状态跳变（`BEFORE -> AFTER`）
P1 · C0 广告摘要冻结与派发前校验	`aida-agent` · `assertWorkPluginSource` (`run-work-plugin-source.ts` L39–73)	1) 校验 `canonicalJsonSha256(continuationContext.pluginTools) === command.payload.ingress.pluginToolsDigest`（严防运行中途篡改可用插件列表）；<br>2) 核对五元身份 `pluginId + pluginVersion + toolId + contractDigest + runtimeRevision` 及 `inputSchema / outputSchema / maxResultBytes / computerCapabilities / effectClass`；<br>3) 若工具标记 `userActionOnly` 或携带 `userActionReceipt`，强制校验已结算的 `SettledPluginAction`（`stepId === action.receipt.settlementId` 且参数 SHA-256 一致）。
P2 · Desktop 原工作权威与 Journal 准入	`aida-desktop` · `PluginHost.settle` (`plugin-host.ts` L684–732) → `PluginCallJournal.perform` (`plugin-call-journal.ts` L227–310)	1) `assertOriginalPluginWorkAuthority` 校验原工作授权，检查内存 `flights` 与 `uncertain` 映射防并发重入；<br>2) `privateDirectory` 强制校验 `<root>/<scope>/` 为 `0o700` 无软链目录且 `dev + ino` 未变；<br>3) 若发现历史记录处于 `phase === 'dispatched'`（说明上次派发后崩溃），绝不重跑，直接落盘 `phase = 'settled'` 并返回 `outcome = 'unknown'`；<br>4) 首次执行先原子写入 `phase: null -> 'admitted'`，并在 `diagnostic-index/` 下写入仅含 `{ interactionId }` 的指针文件。
P3 · 包完整性、安装级授权与 `dispatched` 栅栏	`aida-desktop` · `PluginHost.invokeForRequest` (`plugin-host.ts` L936–1006) → `createMcpStdioRuntime` (`plugin-runtime.ts` L162–195)	1) 匹配活跃或 `retainedBundles` 中的精确 `(version, contractDigest, runtimeRevision)`，调 `verifyBundle(bundle)` 验签；<br>2) 校验 `pluginToolAllowsOrigin(tool, userAction ? 'ui' : 'agent')`（阻止 Agent 直接调仅限视图的 `stateToolId`）；<br>3) 调 `authorizeResource` 走安装即信任（`authorizeInstalledCapability`）并记录 `recordResourceAuthorization`；<br>4) 若声明了 `manifest.data`，校验 `capabilities.data.readActivation` 的 `packageIdentity === runtimeRevision`；<br>5) `capabilities.begin` 创建 `PluginCallLease`（生成 32 字节随机 `token`）；在 `onDispatched` 回调中先把 `PluginCallJournal` 推进至 `phase: 'admitted' -> 'dispatched'` 并 `fsync`，随后才真正向 Worker 发送请求。
P4 · Worker MCP 执行与合作式取消回执	`aida-plugins` · `packages/sdk-js/src/server.mjs` (`#invoke` L150–228)	1) 校验 `params._meta.aida` 符合 V2 `CallContext` 契约，且 `(pluginId, pluginVersion, contractDigest)` 与 Worker 自身 `#manifest` 完全一致（单 Worker 并发上限 16，Host 子请求上限 64）；<br>2) 执行 `tool.handler(args, context)` 并用输出校验器核验 `result.data` 及 `maxResultBytes`；<br>3) 迟到/取消合作回执（L197–207）：若 handler 返回 `isError && result.executionState !== undefined`（`completed` 或 `unknown`），即使调用已超时或取消，仍保留其 `structuredContent` 与 `context._verifiedArtifacts` 通过 `_meta.aida.executionState` 送回 Host。
P5 · Host 三方产物核对与 `settled` 落盘	`aida-desktop` · `plugin-runtime.ts` (L196–220) → `PluginCallJournal.settle` (`plugin-call-journal.ts` L582–618)	1) 若工具声明了 `conditionalArtifactOutput`，调 `assertConditionalArtifactResult(tool, structuredContent, artifacts, lease.committedArtifacts())` 对 Worker 结构化声明、返回 artifact refs、以及 Main `PluginCallLease` 实际提交的 `committedArtifacts()` 做三方比对，不一致直接抛 `PLUGIN_TOOL_RESULT_INVALID`；<br>2) 异常捕获分流：只要 `dispatched === true` 且 `pluginToolEffect(tool) !== 'read'` 且 `failure.executionState !== 'completed'`，一律将 `outcome` 置为 `'unknown'`（绝不谎报未发生副作用）；<br>3) `PluginCallJournal` 原子写入 `phase: 'dispatched' -> 'settled'`（含完整 `reply`）；若尚未派发（`!dispatched`）且答复与兜底答复均未能落盘，直接抛 `PLUGIN_CALL_JOURNAL_UNAVAILABLE`（不返回伪“未执行”回执，防止日志仍留 `admitted` 时被后续投递重复执行，经 `PluginCallOnce.tla` 形式化核验）。
P6 · 服务端 6 表 Join 验真与唤醒/挂起分流	`aida-agent` · `settleRuntimeWorkPluginReceiptInTx` (`run-work-control.ts` L2725–2859) + `parseBoundPluginReply` (`plugin-tool-receipt.ts` L35–80)	1) 6 表 Join：`continuation_requests c` ⋈ `pending_interactions p` ⋈ `agent_runs r` ⋈ `runtime_invocations i` ⋈ `chat_submission_idempotency sub` ⋈ `interaction_receipts receipt`；<br>2) `parseBoundPluginReply` 校验回执的五元身份、`outputSchema`、`maxResultBytes`，若含 `computerObservations` 则调 `verifyComputerObservation` 与 `computerObservationMatchesResult`；<br>3) `recordRuntimeWorkDomainFactInTx` 写入 `plugin_effect:<work_step_ref>` 事实，若绑定了业务任务则调 `PgBusinessTaskOperationCoordinator.projectPluginReceiptInTransaction`；<br>4) 终态/续跑分流：<br> - 若 `reply.outcome === 'unknown'`：调 `parkRuntimeWorkCarrierInTx` 将载体置为 `status = 'manual_recovery', error_code = 'RUNTIME_WORK_PLUGIN_OUTCOME_UNKNOWN'` 并返回 `'held'`；<br> - 若 `reply.outcome === 'cancelled'`：写入 `messages (role='tool')` 并将载体置为 `manual_recovery (PLUGIN_TOOL_CANCELLED)`；<br> - 若 `reply.outcome === 'succeeded'`：写入 `messages (role='tool', metadata={source:'runtime_work_plugin_receipt', receiptId, responseDigest})`、置 `continuation_requests.status = 'completed'`，并将 `agent_runs / runtime_invocations` 置回 `'pending'`、`run_checkpoints` 置回 `'active' (resume_point = 'plugin_receipt:<continuationId>')` 唤醒下一轮 ReAct！

Windows Python 路径预算、服务连接预填与本地工作台双键空间（2026-11-03）

Windows 路径预算预检与准备失败分类：assertPluginPythonPathBudget（plugin-python-path-budget.ts L12–51）在创建全新 Python 环境前按实际 wheel 条目检查 Windows 路径上限（文件 259 / 目录 247），并将准备失败归类为 path_too_long / dependency_install_failed / executable_missing（PluginPreparationError），诊断不外泄安装输出或本机路径。
连接默认地址与已认可 HTTP 来源复用：协议 connections 支持 suggestedBaseUrl；register-plugin-host-ipc.ts 用声明的默认地址预填未保存连接，plugin-connection-target.ts 在保存服务连接时复用已认可的 HTTP 来源并拦截二次编码或路径穿越（PLUGIN_CONNECTION_PATH_DENIED）。
远端 v1 与本地 v2 调用日志隔离：PluginCallJournal 同时支持 schemaVersion: 1 | 2，远端 Work 保持 v1 键空间，Local Workbench 通过 PluginHost.executeLocal 以 local:executionId 隔离 v2 键空间，重启恢复通过 register-local-plugin-workbench.ts 从原日志关联可靠回执且不重放副作用。

Plugin Host V2 运行时

从包到可调用 Worker

该信任模型面向可信插件。Worker 是普通用户进程，Host 能力代理负责合同范围内的能力访问，不能被解释成能够隔离恶意代码的操作系统沙箱。

证据与范围

aida-desktop · apps/desktop/electron/plugin-host/plugin-host.ts L659–689 · listProjections · 4346d79eb364
aida-plugins · docs/plugin-v2-contract.md L1–44 · a33ce3733365
aida-desktop · apps/desktop/electron/plugin-host/plugin-host.ts L1–59 · 4346d79eb364
aida-desktop · apps/desktop/electron/plugin-host/plugin-host.ts L59–100 · 4346d79eb364

结论来自固定版本的静态源码与合同阅读；实现存在、默认开关和生产启用分别判断。本站代码证据面板列出声明状态与具体限制。

aida-plugins · packages/sdk-js/src/server.mjs L177–217 · executionState · a33ce3733365

条件产物：Host 独立核对（Desktop 2026-10-29）

证据：aida-desktop · apps/desktop/electron/plugin-host/plugin-runtime.ts L139–220 · assertConditionalArtifactResult · 4346d79eb364；apps/desktop/electron/plugin-host/plugin-call-lease.ts L1–12 · 4346d79eb364；apps/desktop/shared/generated/plugin-v2/semantics.mjs L80–129 · 4346d79eb364。
Report 四个合同场景已回默认 System；它验证 Desktop 冻结 fixture 的专用 report_export producer，不代表所有官方业务包已采用声明或通过验收。证据：docs/testing/system-payroll-packages.md L1–25 · 4346d79eb364。

三仓（Agent ↔ Desktop ↔ Plugins SDK）插件调用全链路微追踪（视图 `plugin-end-to-end-trace`）

跳点	所属仓与核心函数	校验规则 / 持久化状态跳变（`BEFORE -> AFTER`）
P1 · C0 广告摘要冻结与派发前校验	`aida-agent` · `assertWorkPluginSource` (`run-work-plugin-source.ts` L39–73)	1) 校验 `canonicalJsonSha256(continuationContext.pluginTools) === command.payload.ingress.pluginToolsDigest`（严防运行中途篡改可用插件列表）；<br>2) 核对五元身份 `pluginId + pluginVersion + toolId + contractDigest + runtimeRevision` 及 `inputSchema / outputSchema / maxResultBytes / computerCapabilities / effectClass`；<br>3) 若工具标记 `userActionOnly` 或携带 `userActionReceipt`，强制校验已结算的 `SettledPluginAction`（`stepId === action.receipt.settlementId` 且参数 SHA-256 一致）。
P2 · Desktop 原工作权威与 Journal 准入	`aida-desktop` · `PluginHost.settle` (`plugin-host.ts` L684–732) → `PluginCallJournal.perform` (`plugin-call-journal.ts` L227–310)	1) `assertOriginalPluginWorkAuthority` 校验原工作授权，检查内存 `flights` 与 `uncertain` 映射防并发重入；<br>2) `privateDirectory` 强制校验 `<root>/<scope>/` 为 `0o700` 无软链目录且 `dev + ino` 未变；<br>3) 若发现历史记录处于 `phase === 'dispatched'`（说明上次派发后崩溃），绝不重跑，直接落盘 `phase = 'settled'` 并返回 `outcome = 'unknown'`；<br>4) 首次执行先原子写入 `phase: null -> 'admitted'`，并在 `diagnostic-index/` 下写入仅含 `{ interactionId }` 的指针文件。
P3 · 包完整性、安装级授权与 `dispatched` 栅栏	`aida-desktop` · `PluginHost.invokeForRequest` (`plugin-host.ts` L936–1006) → `createMcpStdioRuntime` (`plugin-runtime.ts` L162–195)	1) 匹配活跃或 `retainedBundles` 中的精确 `(version, contractDigest, runtimeRevision)`，调 `verifyBundle(bundle)` 验签；<br>2) 校验 `pluginToolAllowsOrigin(tool, userAction ? 'ui' : 'agent')`（阻止 Agent 直接调仅限视图的 `stateToolId`）；<br>3) 调 `authorizeResource` 走安装即信任（`authorizeInstalledCapability`）并记录 `recordResourceAuthorization`；<br>4) 若声明了 `manifest.data`，校验 `capabilities.data.readActivation` 的 `packageIdentity === runtimeRevision`；<br>5) `capabilities.begin` 创建 `PluginCallLease`（生成 32 字节随机 `token`）；在 `onDispatched` 回调中先把 `PluginCallJournal` 推进至 `phase: 'admitted' -> 'dispatched'` 并 `fsync`，随后才真正向 Worker 发送请求。
P4 · Worker MCP 执行与合作式取消回执	`aida-plugins` · `packages/sdk-js/src/server.mjs` (`#invoke` L150–228)	1) 校验 `params._meta.aida` 符合 V2 `CallContext` 契约，且 `(pluginId, pluginVersion, contractDigest)` 与 Worker 自身 `#manifest` 完全一致（单 Worker 并发上限 16，Host 子请求上限 64）；<br>2) 执行 `tool.handler(args, context)` 并用输出校验器核验 `result.data` 及 `maxResultBytes`；<br>3) 迟到/取消合作回执（L197–207）：若 handler 返回 `isError && result.executionState !== undefined`（`completed` 或 `unknown`），即使调用已超时或取消，仍保留其 `structuredContent` 与 `context._verifiedArtifacts` 通过 `_meta.aida.executionState` 送回 Host。
P5 · Host 三方产物核对与 `settled` 落盘	`aida-desktop` · `plugin-runtime.ts` (L196–220) → `PluginCallJournal.settle` (`plugin-call-journal.ts` L582–618)	1) 若工具声明了 `conditionalArtifactOutput`，调 `assertConditionalArtifactResult(tool, structuredContent, artifacts, lease.committedArtifacts())` 对 Worker 结构化声明、返回 artifact refs、以及 Main `PluginCallLease` 实际提交的 `committedArtifacts()` 做三方比对，不一致直接抛 `PLUGIN_TOOL_RESULT_INVALID`；<br>2) 异常捕获分流：只要 `dispatched === true` 且 `pluginToolEffect(tool) !== 'read'` 且 `failure.executionState !== 'completed'`，一律将 `outcome` 置为 `'unknown'`（绝不谎报未发生副作用）；<br>3) `PluginCallJournal` 原子写入 `phase: 'dispatched' -> 'settled'`（含完整 `reply`）；若尚未派发（`!dispatched`）且答复与兜底答复均未能落盘，直接抛 `PLUGIN_CALL_JOURNAL_UNAVAILABLE`（不返回伪“未执行”回执，防止日志仍留 `admitted` 时被后续投递重复执行，经 `PluginCallOnce.tla` 形式化核验）。
P6 · 服务端 6 表 Join 验真与唤醒/挂起分流	`aida-agent` · `settleRuntimeWorkPluginReceiptInTx` (`run-work-control.ts` L2725–2859) + `parseBoundPluginReply` (`plugin-tool-receipt.ts` L35–80)	1) 6 表 Join：`continuation_requests c` ⋈ `pending_interactions p` ⋈ `agent_runs r` ⋈ `runtime_invocations i` ⋈ `chat_submission_idempotency sub` ⋈ `interaction_receipts receipt`；<br>2) `parseBoundPluginReply` 校验回执的五元身份、`outputSchema`、`maxResultBytes`，若含 `computerObservations` 则调 `verifyComputerObservation` 与 `computerObservationMatchesResult`；<br>3) `recordRuntimeWorkDomainFactInTx` 写入 `plugin_effect:<work_step_ref>` 事实，若绑定了业务任务则调 `PgBusinessTaskOperationCoordinator.projectPluginReceiptInTransaction`；<br>4) 终态/续跑分流：<br> - 若 `reply.outcome === 'unknown'`：调 `parkRuntimeWorkCarrierInTx` 将载体置为 `status = 'manual_recovery', error_code = 'RUNTIME_WORK_PLUGIN_OUTCOME_UNKNOWN'` 并返回 `'held'`；<br> - 若 `reply.outcome === 'cancelled'`：写入 `messages (role='tool')` 并将载体置为 `manual_recovery (PLUGIN_TOOL_CANCELLED)`；<br> - 若 `reply.outcome === 'succeeded'`：写入 `messages (role='tool', metadata={source:'runtime_work_plugin_receipt', receiptId, responseDigest})`、置 `continuation_requests.status = 'completed'`，并将 `agent_runs / runtime_invocations` 置回 `'pending'`、`run_checkpoints` 置回 `'active' (resume_point = 'plugin_receipt:<continuationId>')` 唤醒下一轮 ReAct！

Windows Python 路径预算、服务连接预填与本地工作台双键空间（2026-11-03）

Windows 路径预算预检与准备失败分类：assertPluginPythonPathBudget（plugin-python-path-budget.ts L12–51）在创建全新 Python 环境前按实际 wheel 条目检查 Windows 路径上限（文件 259 / 目录 247），并将准备失败归类为 path_too_long / dependency_install_failed / executable_missing（PluginPreparationError），诊断不外泄安装输出或本机路径。
连接默认地址与已认可 HTTP 来源复用：协议 connections 支持 suggestedBaseUrl；register-plugin-host-ipc.ts 用声明的默认地址预填未保存连接，plugin-connection-target.ts 在保存服务连接时复用已认可的 HTTP 来源并拦截二次编码或路径穿越（PLUGIN_CONNECTION_PATH_DENIED）。
远端 v1 与本地 v2 调用日志隔离：PluginCallJournal 同时支持 schemaVersion: 1 | 2，远端 Work 保持 v1 键空间，Local Workbench 通过 PluginHost.executeLocal 以 local:executionId 隔离 v2 键空间，重启恢复通过 register-local-plugin-workbench.ts 从原日志关联可靠回执且不重放副作用。

Plugin V2 三仓全链路：从 C0 广告摘要冻结、PluginCallJournal 栅栏到 6 表回执结算

机制说明（全文）

Plugin Host V2 运行时

从包到可调用 Worker

证据与范围

条件产物：Host 独立核对（Desktop 2026-10-29）

三仓（Agent ↔ Desktop ↔ Plugins SDK）插件调用全链路微追踪（视图 `plugin-end-to-end-trace`）

Windows Python 路径预算、服务连接预填与本地工作台双键空间（2026-11-03）

机制说明

Plugin Host V2 运行时

从包到可调用 Worker

证据与范围

条件产物：Host 独立核对（Desktop 2026-10-29）

三仓（Agent ↔ Desktop ↔ Plugins SDK）插件调用全链路微追踪（视图 `plugin-end-to-end-trace`）

Windows Python 路径预算、服务连接预填与本地工作台双键空间（2026-11-03）

代码证据

Host 从允许、支持且非调试的 Bundle 生成投影，执行回执经过 PluginCallJournal。

协议、Worker MCP、Host 能力代理和包身份遵循同一 V2 合同。

可信 Worker 是普通用户进程，能力代理不是恶意代码的 OS 沙箱。

SDK 取消/超时迟到回执：Host 已取消或超时后，handler 返回带 executionState 的失败 ToolResult 仍作为该调用回执送达（保留部分结果与已提交 artifact，_meta.aida.executionState 透传）；其他迟到返回仍为取消/超时错误。

Plugin V2 三仓全链路：从 C0 广告摘要冻结、PluginCallJournal 栅栏到 6 表回执结算

机制说明（全文）

Plugin Host V2 运行时

从包到可调用 Worker

证据与范围

条件产物：Host 独立核对（Desktop 2026-10-29）

三仓（Agent ↔ Desktop ↔ Plugins SDK）插件调用全链路微追踪（视图 plugin-end-to-end-trace）

Windows Python 路径预算、服务连接预填与本地工作台双键空间（2026-11-03）

三仓（Agent ↔ Desktop ↔ Plugins SDK）插件调用全链路微追踪（视图 `plugin-end-to-end-trace`）