Actoviq Agent SDK 1.0 实施与端到端验收报告

验收日期：2026-07-12（Asia/Shanghai）

对应方案：08 SDK 架构审计与 Runtime 优化规划

结论：当前工作树已完成 Phase 0–6 的代码、测试、文档与发布门禁实施；本地 Windows x64 上 Node 22.20.0 与 Node 24.18.0 全套测试均通过。npm 发布、远端 GitHub Linux/Windows/macOS runner 和真实生产 session cutover 仍必须按各自 release/change 流程取得环境证据，不能由本地报告替代。

1. 环境与事实边界

项目	验收值
package	actoviq-agent-sdk@1.0.0
OS / arch	Windows x64
Node 22	v22.20.0
Node 24	v24.18.0，使用真实 node.exe；未使用会污染 PATH 的 npx shim
Node 最低版本边界	22.13.0 / 24.0.0 exact-minimum CI；真实 22.5.0 负向 probe 证明默认 node:sqlite 不可用
npm	10.9.3
TypeScript	5.8.3
Vitest	4.1.2
package manager state	npm install --package-lock-only --ignore-scripts 后 lockfile 一致
网络	contract、profile、migration、benchmark 与 E2E 使用 deterministic fake，无模型/MCP 网络请求

历史审计以 0.4.6 / df04baac... 为基线；方案正文中的旧版本、旧缺陷和路径证据是历史输入，不应被改写成当前事实。本报告记录实施后的状态。

2. Phase 0–6 完成矩阵

Phase 0：生产止血与可测基线

已完成：

• 同 session turn coordinator、revision/CAS 与 schema validation；
• runtime 顶层 run 使用公平、abort-aware semaphore；1000 个独立 session 不超过配置并发上限，same-session 等锁不占全局 permit；
• 有界 async queue、priority reserve、delta coalescing、cancel / iterator return / throw；
• model/tool/MCP/hook/run deadline 与 signal 传播；
• side-effect tool 不做不安全自动重放；
• MCP 完整配置指纹、凭据不明文入 key、catalog TTL/cache、并行 list、关闭清理；
• runtime-owned AgentPool、fanout/context 清理、team permission 继承、run retry 收紧；
• workDir 持久化、workflow trust 文案/边界、全 run usage 聚合；
• Windows direct executable version probe 使用有限超时和合并的 process-tree cleanup；.cmd/.bat shim 不再为 best-effort 版本显示而执行，避免受限 host 拒绝 taskkill /T 时遗留后代进程。

主要证据：

• tests/session-concurrency.spec.ts
• tests/async-queue.spec.ts
• tests/deadline.spec.ts
• tests/mcp-connection-manager.spec.ts
• tests/long-run-hardening.spec.ts
• tests/actoviq-bridge-providers.spec.ts
• tests/core-usage.spec.ts

Phase 1：Core contract 与 Provider v2

已完成：

• /core：canonical input/output items、不可变 AgentSpec、RunContext/RunResult/RunError、JSON guard、UsageAccumulator；
• /providers：ModelProvider、capabilities、registry、transport、stream；
• OpenAI Responses、OpenAI Chat-compatible、Anthropic adapters；
• text/image/document/tool/reasoning/raw/structured mapping 与 unsupported capability preflight；
• LegacyModelApiProvider 与 ModelProviderLegacyAdapter 双向过渡。

主要证据：

• tests/core-contracts.spec.ts
• tests/provider-v2-contract.spec.ts
• tests/provider-v2-registry.spec.ts
• tests/provider-v2-legacy.spec.ts
• tests/provider-v2-runtime.spec.ts
• tests/compat-provider-runtime.spec.ts

Phase 2：AgentRuntime 与 Middleware

已完成：

• /runtime 的 AgentRuntime、RuntimeServices、ToolRegistry/ToolRunner/ToolPolicy；
• fixed stage middleware 与 invariant/error stage，registry reference 可检查/打印；安全关键的 model/tool terminal 必须成功执行 next()，恶意 short-circuit fail closed；model rewrite 后置校验，ToolRunner output parser 只执行一次并冻结结果、拒绝 wrapper 替换；
• lazy service initialization；最小 agent 不加载 session/memory/skills/team/GUI；
• streaming/run/resume/close 生命周期、active settlement、close/cancel race 修复；
• structured output、input/output guardrail、approval/interruption、checkpoint state；
• 旧 createAgentSdk 作为 1.x compat façade 保留，新代码不向 root 扩张 symbol。

主要证据：

• tests/agent-runtime-v2.spec.ts
• tests/runtime-services-v2.spec.ts
• tests/runtime-tools-v2.spec.ts
• tests/middleware-v2.spec.ts
• tests/runtime-v2-boundaries.spec.ts
• tests/runtime-boundary-coverage.spec.ts

Phase 3：Durable state、HITL 与事件

已完成：

• tenant-scoped SQLite Session/Checkpoint/Memory/Artifact store；append/CAS/snapshot；
• SerializedRunState、pending side-effect state、interruption decision、resume/reconciliation；
• backup-first JSON v1 migration、ledger/idempotency、transaction rollback；
• legacy message → canonical converter；legacy run 仅审计、legacy raw durable 但不跨 provider replay；
• migrate → SQLite adapter → 下一轮 AgentRuntime.run() cutover E2E；
• versioned RunEvent、per-run monotonic sequence、parent/child trace、redaction、sink failure policy、OTel-compatible exporter。

主要证据：

• tests/storage-v2.spec.ts
• tests/storage-v2-migration.spec.ts
• tests/legacy-session-cutover.spec.ts
• tests/runtime-session-v2.spec.ts
• tests/node-checkpoint-adapter.spec.ts
• tests/run-events.spec.ts

Phase 4：统一多 Agent 与 Workflow

已完成：

• agent-as-tool 与 handoff 的 conversation ownership 分离；显式 handoff 在 child run/ownership transfer 前执行 source runtime 的 beforeHandoff stage；
• child scope 继承 services、budget、concurrency、deadline、policy、tenant/workspace、trace；
• run-tree cancel、fail-fast/collect/retry-safe failure policy；
• durable background spawn/query/resume/cancel 与 SQLite child store；
• WorkflowGraph + reducer、agent workflow node、panel/team/reviewer/router/swarm presets；
• trusted compatibility executor、local isolated process executor、host-supplied remote/container sandbox contract；
• DurableAgentScheduler 将旧 scheduler task 映射为 durable background child；GUI manager/issue dispatch 通过 DurableIssueCoordinator + SqliteDurableChildStore 接入同一 spawn/checkpoint 生命周期，旧 session engine 仅作为 OrchestrationRuntime 兼容 executor，不创建第二套 SDK/runtime。

主要证据：

• tests/orchestration-v2.spec.ts
• tests/orchestration-coverage.spec.ts
• tests/sqlite-durable-child-store.spec.ts
• tests/durable-agent-scheduler.spec.ts
• tests/durable-issue-coordinator.spec.ts
• tests/workflow-executor-v2-security.spec.ts
• tests/model-team.spec.ts
• tests/manager-issues.spec.ts

Phase 5：Agent profiles 与产品表面

已完成：

• chat/coding/research/workflow/supervisor/background 六类 profile，共享一个 AgentRuntime；
• deterministic 无网络示例 examples/profiles/all-profiles.ts；
• CLI/TUI/GUI/legacy Bridge 接入 AgentEvent → RunEvent → SharedSurfaceSemanticEvent；
• native AgentRuntimeBridgeAdapter 只包装传入 runtime/agent，不创建/关闭 runtime 或 services；
• GUI issue worker 的实际产品路径先持久化 durable child/checkpoint，再由 compat executor 执行；SQLite 上可跨 coordinator restart 查询和 resume；
• legacy event forward/reverse adapters、redaction、sequence/trace/terminal/usage 语义；
• compat diagnostic 可关闭、仅进程内、不联网；当前明确统计 createAgentSdk；
• 1.0 迁移指南 列出仓库全部旧 TypeScript 示例到新 API/compat 的对照。

主要证据：

• tests/profiles-v2.spec.ts
• tests/surface-run-events.spec.ts
• tests/surface-product-wiring.spec.ts
• tests/durable-issue-coordinator.spec.ts
• tests/runtime-bridge-adapter.spec.ts
• tests/compat-diagnostics.spec.ts

Phase 6：1.0 稳定化

已完成：

• package version 1.0.0、Node engine ^22.13.0 || ^24.0.0；
• 14 个 package subpath exports 与 public API JSON snapshot；
• clean tarball 临时安装并省略 optional dependency 后逐 subpath import；
• core/provider/runtime/orchestration 分层 coverage gate；
• runtime smoke/full benchmark、10% comparator、CI smoke invariant；
• 精确最低 Node 22.13.0/24.0.0 Linux blocking gate、Node 22/24 Linux/Windows blocking CI、macOS nightly/manual workflow；
• threat/failure/SemVer/support policy、SECURITY.md、迁移 runbook；
• ADR-001–ADR-010；
• README、CHANGELOG、package、Node support 与实现事实对齐。

主要证据：

• vitest.sdk-v2.config.ts
• scripts/public-api.mjs
• scripts/verify-package-exports.mjs
• scripts/verify-packed-package.mjs
• bench/runtime/README.md
• .github/workflows/ci.yml
• SECURITY.md
• docs/adr

3. 最终 Definition of Done 审计

#	要求	结论	直接证据
1	六类 profile 共用 AgentRuntime	通过	profile acceptance + full example
2	provider 统一 contract，能力不靠 hostname	通过	三 adapter contract suite + capability preflight
3	structured/guardrail/asTool/handoff/spawn/workflow 一等 API	通过	core/runtime/orchestration exports + handoff lifecycle E2E
4	session 并发无丢失，run 可暂停/恢复	通过	100 concurrent turn、CAS、checkpoint/resume/reconciliation
5	stream/tool/MCP/hook/child 有界且统一取消	通过	bounded queue、deadline、MCP cleanup、run-tree cancel tests
6	team 不创建 N 套 SDK、不绕过权限	通过	shared services benchmark/invariant + team policy tests
7	workflow trust 明确，node:vm 不宣称 sandbox	通过	executor router/security suite + policy/docs
8	event version/sequence/parent-child trace	通过	RunEvent + surface acceptance
9	最小 agent 不加载可选能力	通过	runtime boundary/service lazy-init tests
10	旧 createAgentSdk 有无损迁移路径和稳定兼容窗	通过	/compat、双向 provider/event adapter、session migration/runtime adapter、1.x policy、迁移指南
11	性能/故障/安全/迁移进入 CI	通过	CI workflow + benchmark/coverage/security/migration tests
12	README/CHANGELOG/version/Node support/实现一致	通过	1.0.0、22.13+/24、exact-minimum CI、docs build、package gates

4. 最终执行结果

命令 / 环境	结果
Node 22 npm test	122/122 files；923 passed；1 skipped；0 unhandled errors；HOME 位于工作区临时目录
Node 24 vitest run（真实 v24.18.0 binary）	122/122 files；923 passed；1 skipped；0 unhandled errors；HOME 位于工作区临时目录
Node 22 npm run typecheck	通过
Node 24 TypeScript noEmit + build	通过
Node 22.5.0 negative floor probe	typecheck 通过；默认 SQLite 场景以 ERR_UNKNOWN_BUILTIN_MODULE 失败，engine 下限据此修正到官方 unflagged 版本 22.13.0
npm run test:sdk-v2:coverage	20 files / 158 tests；lines 97.10%；branches 86.24%；随后执行分层 verifier
分层 branch coverage	core 87.01%；runtime 85.19%；providers 85.57%；orchestration 89.29%；均 ≥ 85%
npm run bench:runtime:smoke	passed；32 invariants；0 failed
npm run bench:runtime	passed；10k/100k SQLite、1M delta、1/4/8/16 children；35 invariants
full report self-compare，threshold 10%	29 metrics；0 missing；0 regressions
npm run example:profiles	六类 profile 全部执行通过，无网络
npm run docs:build	通过，无 dead link
npm run verify:package	14 subpaths；API snapshot match
npm run verify:packed	tarball clean install；omit optional；14 subpaths import
npm pack --dry-run	actoviq-agent-sdk@1.0.0 内容校验通过
git diff --check	通过（仅 Git 的 LF→CRLF 提示，无 whitespace error）

node:sqlite 在 Node 22 输出 ExperimentalWarning，这是上游 Node 22 状态提示，不是测试失败；Node 24 路径使用稳定的 --permission flag，Node 22 使用兼容的 --experimental-permission alias。

5. Acceptance 场景清单

Contract

• provider：text、stream、tool、parallel、structured、image/document、reasoning opaque、usage、abort、transport error、unsupported capability；
• tool：schema、permission、read/side-effect、timeout、abort、idempotency/reconciliation；
• session：create/load/append/CAS/snapshot、same-session 1/10/100、tenant isolation、corrupt schema；
• checkpoint：pending approval、resume、config digest、side-effect commit state；
• event：sequence、identity collision/dedupe、trace parentage、redaction、sink failure、backpressure。

并发与故障

• same-session 1/10/100 serial/CAS conflict；1000 独立 session 受 runtime semaphore 限制；bounded 100k/1M delta；consumer return/throw；runtime close race；
• provider 建连阶段（headers 前）可安全重试、stream 可见后断线不在 transport 层重放、tool commit 后靠 checkpoint/reconciliation 防止 side-effect 重放；abort/deadline；MCP restart/timeout/catalog/config/credential change；Windows process-tree cleanup；
• migration parse/conflict/source change/backup/transaction rollback/idempotency；SQLite ENOSPC partial-write rollback 与 corrupt snapshot fail-closed；
• parent/child cancel、budget/deadline、fail-fast/collect/retry-safe；reducer synchronous/async failure；
• middleware/hook timeout/error、model/tool terminal bypass fail-closed、beforeHandoff lifecycle；team partial failure；scheduler durable child failure。

安全

• permission/no-bypass、child inherit-stricter、side-effect approval/reconciliation；
• workspace traversal、profile/host symlinkEscape: deny contract、safe recursive removal、worktree resume/isolation；
• untrusted workflow 的 env/process/require/fs/net/child_process/worker/addon/WASI 边界；
• event/surface secret、reasoning signature、Error stack redaction；
• MCP credential/config fingerprint 不明文暴露；
• prompt/tool output 作为不可信数据时，不能替换 provider/ToolRunner terminal，也不能绕过显式 policy denial；
• tenant session/memory/artifact isolation；
• local process 明确不提供 adversarial multi-tenant sandbox 保证。

迁移

• dry-run 不写 target/backup；backup-first；source hash 不变；
• canonical conversion、tool id、reasoning credential stripping、unknown raw durable；
• legacy run/raw 不进入 active provider transcript；
• migrate → load → next Runtime run；early preview verbatim message reader；
• conflict 整批 rollback、ledger idempotency、失败保留原 JSON。

6. 仍需由发布/生产流程完成的外部证据

以下不是当前代码实施缺口，也不能被本地测试冒充为已完成的外部操作：

1. 对目标 commit 实际运行 GitHub exact-minimum Node 22.13.0/24.0.0、Linux/Windows Node 22/24 blocking jobs 与 macOS nightly/manual；
2. npm publish provenance、registry install smoke、tarball hash 和 release note；
3. 对真实 JSON v1 数据执行 Runbook 的 dry-run、shadow/canary、单 writer 和环境级 restore drill；
4. 对真实 provider/MCP/sandbox backend 执行 credential、quota、network 与 retention 审批；
5. 若未来 2.0 考虑删除 root façade，先扩大 compat diagnostic 覆盖并收集真实迁移数据。

7. 参考项目

架构选择、适配/拒绝理由与完整本地路径保留在 方案第 7–8、18 节：

• OpenAI Agents SDK Python；
• CrewAI：E:\BaiduSyncdisk\research\Programming_Development\procontributor\claude_\crewAI；
• DeerFlow：E:\BaiduSyncdisk\research\Programming_Development\procontributor\claude_\deer-flow；
• DeepAgents：E:\BaiduSyncdisk\research\Programming_Development\procontributor\claude_\deepagents；
• OpenAI Agents Python 本地快照：E:\BaiduSyncdisk\research\Programming_Development\procontributor\claude_\openai-agents-python。

参考项目用于验证 contract、ownership、durability、event 与 orchestration 语义；没有直接复制 Python 实现，也没有把参考 framework 设为 runtime 强依赖。