DeepSeek-Reasonix 插件/运行时 v2 时空组合性设计全解：EffectScope、依赖图与原子发布

DeepSeek-Reasonix 插件/运行时 v2 时空组合性设计全解EffectScope、依赖图与原子发布【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix导读DeepSeek-Reasonix 的扩展内核已经具备Contribution → RuntimeSnapshot的贡献模型、RuntimeSet的逆向幂等清理、Builder 冻结与激活阶段以及失败时保留旧控制器的Rebuild机制。本篇技术指南围绕 docs/superpowers/specs/2026-08-07-spatiotemporal-composability-v2.md 展开系统讲解该设计如何在不引入外部运行时、不更换实现语言的前提下把四类成熟的运行时组合机制——统一运行时效果作用域EffectScope、类型化响应式依赖图、代Generation/Epoch组件生命周期、可验证的原子重载build → activate → publish → drain——移植进既有扩展内核。读完本文你将掌握 v2 清单的校验规则、依赖图与 RuntimePlan 的构建流程、原子发布/排空时序、效果收据Effect Receipts的恢复边界以及对应的仓库源码实现路径能够直接用于排查插件安装失败、组件 Inactive 诊断和运行时热重载问题。一、设计背景为什么需要 v2 组合性1.1 已有扩展内核的能力基线Reasonix 的扩展内核在 v2 之前已经具备以下能力它们是本设计的地基Contribution → RuntimeSnapshot静态配置以不可变快照形式呈现RuntimeSet一代运行时持有的活动资源集合提供逆向/幂等清理与代际守卫Builder 的 freeze 与 activate 两阶段Rebuild在失败时保留旧控制器。这些机制保证了配置不可变、资源可清理、重建不炸场但面对真实的组合需求仍显不足sidecar 进程、MCP 客户端、provider 流、watcher、事件订阅、UI hub 绑定、后台 goroutine、会话临时资源、控制器清理回调等大量活句柄缺少统一的作用域管理组件之间的能力依赖没有类型化、可验证的图热重载无法做到只重载受影响子图外部副作用没有可追溯的收据。1.2 v2 设计移植的四类机制本设计把四类业界成熟的运行时组合机制移植进内核见原文档Context一节统一运行时效果作用域Unified runtime effect scopes类型化、响应式依赖图Typed, reactive dependency graph代Generation/ 纪元Epoch组件生命周期可验证的原子重载Verifiable atomic reloadbuild → activate → publish → drain实现语言保持 Go不引入外部运行时依赖也不重写 stdio/HTTP 传输层。1.3 固定决策Fixed decisions原文档明确了 v2 的边界这些决策直接决定了后续所有实现路径原生插件升级到reasonix.io/plugin/v2拒绝 v1 与旧式原生清单无 apiVersion在 install、doctor、boot 三处入口都拒绝保留既有 stdio/HTTP 传输不重写传输层不引入外部运行时依赖不可逆的外部工作使用效果收据effect receipts绝不伪造回滚收据恢复是进程本地的、有界的不承诺崩溃恢复保持系统提示词、工具 schema 与记忆前缀缓存prefix cache优先的约束Claude 兼容插件路径不在 v2 原生运行时改动范围内。二、组件生命周期状态机v2 设计中一个组件的生命周期状态如下原文档Lifecycle一节Inactive → Preparing → Active → Draining → Inactive Failed (activation or cleanup failure; retains error receipts)在仓库源码 internal/extension/dependency.go 中这五个状态被实现为ComponentState常量ComponentInactive、ComponentPreparing、ComponentActive、ComponentDraining、ComponentFailed。v1 版本设计的组件粒度是一个原生 v2 sidecar 运行时包 一个组件节点。Host 拥有的 provider、interceptor、UI 绑定都是该节点的子贡献child contributions。单个工具tool暂时还不是独立的生命周期节点。三、EffectScope统一运行时效果作用域3.1 核心思想活句柄只在作用域里存在RuntimeSnapshot保持不可变配置活句柄进程、连接、watcher、回调、goroutine只能存在于EffectScope中默认实现由RuntimeSet持有。这句话是整个 v2 架构的宪法配置与资源彻底分离快照可以任意拷贝、比较、哈希而不会意外夹带会过期的指针。3.2 效果分类Effect Class原文档给出了四类效果及其语义Class含义ReversibleDispose 可以完全撤销该效果CancelableCancel 停止后续工作Dispose 时等待其完成CompensatableDispose 时可能运行补偿compensate函数Irreversible只记录收据绝不声称回滚成功源码 internal/extension/effectscope.go 用EffectClass枚举精确实现了这四个类别每个类别都附带清晰的注释约定例如Irreversible的语义是只记录收据绝不声称回滚成功。Effect结构体internal/extension/effectscope.go携带ID、Owner、Component、Class、Dispose、Compensate字段EffectReceipt则记录ID、Owner、Generation、Component、Class、StartedAt、CompletedAt、CompensationStatus、Errorinternal/extension/effectscope.go是后续收据账本的数据原型。3.3 作用域规则与实现细节原文档规定的规则在LiveScopeEffectScope的默认实现见 internal/extension/effectscope.go中逐条落地每个效果最多 dispose 一次Dispose通过closed标志实现幂等重复调用直接返回 nilinternal/extension/effectscope.go组件内按注册逆序清理Dispose使用slices.Backward(effects)从后往前遍历跨组件按逆拓扑排空顺序由依赖图的DrainOrder()提供见第五节独立组件可并行激活/清理互不依赖的节点无共享可变状态激活中途失败自动 dispose 已跟踪效果Track发现 scope 已关闭时会立即执行disposeNow避免激活竞态泄漏资源internal/extension/effectscope.goDispose 等待可取消的后台工作Dispose(ctx)接收调用方 contextcancelable 效果可以等待后台完成清理错误变成诊断绝不跳过剩余 dispose所有错误通过errors.Join聚合后统一返回。3.4 必须跟踪到 EffectScope 的资源清单原文档明确列出的资源类型包括sidecar 进程、MCP client/transport、provider 流、watcher、事件订阅、UI hub 绑定、goroutine/后台任务、会话临时资源、控制器清理回调。RuntimeSet提供两个便捷入口internal/extension/runtimeset.goAdd(closers ...io.Closer)把io.Closer注册为 Reversible 效果Track(e Effect)注册带类型的完整效果。值得注意的防泄漏细节RuntimeSet.Add对已关闭 set 上再注册 closer会立即关闭该 closer——注释明确指出如果不这样做sidecar 进程就会活过它的会话internal/extension/runtimeset.go。CloseIfGeneration(gen)internal/extension/runtimeset.go是代际守卫的关键只有代号匹配时才关闭防止旧代清理误关新一代运行时资源。四、Snapshot / Plan / Controller 边界原文档用一张表划清了四个概念RuntimeSnapshot immutable configuration and dependency view RuntimeSet live resources owned by one generation (EffectScope) RuntimePlan transition from old snapshot to new snapshot Controller owner of the published generationRuntimeSnapshot不可变配置与依赖视图RuntimeSet某一代拥有的活动资源内含 EffectScopeRuntimePlan从旧快照到新快照的迁移计划Controller已发布代的所有者。活句柄进程、连接、watcher、回调、goroutine永远不允许进入RuntimeSnapshot。这与ComponentDescriptor必须不携带活句柄的实现注释相呼应internal/extension/dependency.go。五、Capability 契约类型化依赖的身份基础5.1 叶子包 extensioncontractinternal/extensioncontract是一个叶子包被pluginpkg与internal/extension共同依赖必须保持零业务导入以保证两侧都能依赖它而不产生环见 internal/extensioncontract/capability.go 的包注释。核心类型internal/extensioncontract/capability.goCapabilityKey{Namespace, Kind, ID}始终带命名空间的三元组String()输出namespace/kind/id的规范线格式Validate()拒绝空段与含空白符的段Capability{Key, Version, SchemaHash}provider/tool/UI 类能力必须提供稳定 schema hashrequiresSchemaHash对provider、tool、ui、uiaction强制要求Requirement在 Capability 基础上扩展VersionRange与Optional。5.2 版本语义与规范哈希版本统一使用golang.org/x/mod/semver。normalizeVersion会自动补v前缀以适配 semver 库validateVersionRange支持逗号分隔的比较子句如1.0.0,2.0.0matchVersionRange实现了、、、、、以及裸版本精确匹配的求值。Capability.CanonicalHash()对 namespace、kind、id、version、schemaHash 做 SHA-256 指纹输出sha256:...形式。Key、kind、version、schema hash 全部参与规范哈希这直接服务于后续的纪元Epoch判定与快照缓存元数据。六、Manifest v2清单格式与校验规则6.1 清单结构原生reasonix-plugin.json需要如下结构原文档Manifest v2一节{ apiVersion: reasonix.io/plugin/v2, name: example, version: 2.0.0, requires: [...], provides: [...], runtime: { command: ..., intercepts: [], replaces: [], capabilities: [] } }仓库还提供了一份 golden fixturedocs/superpowers/specs/fixtures/spatiotemporal-v2/manifest.v2.golden.json可用于对照校验解析器输出。6.2 校验规则原文档给出的完整校验矩阵缺失 / v1 / 未知主版本 apiVersion →硬拒绝hard rejectprovides是握手的能力上限capability ceiling握手不得声明清单之外的 capability声明了但实际缺失的能力 → 标记为Unavailable不伪造非可选依赖缺失 → 组件保持Inactive可选依赖缺失 → 允许激活但附带诊断必选依赖成环 → 拒绝并给出完整环路径同一(namespace, kind, id)出现多个 provider → 需要显式选择否则报告冲突替换槽replacement slots保持单一所有者拦截器interceptors按优先级可加性叠加。Claude/Codex 兼容清单不受影响。七、依赖图与 RuntimePlan构建流程与子图隔离7.1 构建流水线原文档给出的 build flowDiscover → Parse → Validate → Resolve capabilities → Validate versions/schema → Detect cycles → Topological activate order → Reverse drain order在源码中BuildDependencyGraphinternal/extension/dependency.go实现了从 Validate 到 Detect cycles 的整段逻辑校验每个 descriptor空 ID、重复组件、非法 capability/requirement 都会以GraphError返回invalid_component、duplicate_component、invalid_capability、invalid_requirement建立Providerscapability key → 提供者组件列表并排序保证确定性逐条解析 requirementSatisfiedBy做 key 匹配、schema hash 钉住与 semver 范围求值找不到匹配时可选依赖写入Diagnostics非可选依赖返回dependency_unsatisfied多个匹配且未显式选择时返回duplicate_provider最后用三色 DFSwhite/gray/black检测必选环命中即返回带完整环路径的dependency_cycleinternal/extension/dependency.go。7.2 确定性排序排序键sort keys为依赖秩dependency rank、作用域秩scope rank、优先级priority、规范组件 ID。componentLessinternal/extension/dependency.go实现了这一顺序依赖秩用传递 provider 深度近似更深依赖先激活作用域秩让项目拥有的节点可预测地赢平局。拓扑排序采用 Kahn 算法 确定性就绪集排序internal/extension/dependency.goActivateOrder()与DrainOrder()逆转置由同一实现派生。7.3 Epoch什么变化才触发重载消费者consumer的纪元身份epoch [capability key, provider component ID, provider version, provider schema hash]源码中的ComponentEpochinternal/extension/dependency.go正是这个四元组EpochFor为消费者的每个 requirement 解析出对应 provider 的纪元。epochsChangedinternal/extension/runtimeplan.go在计划生成时对比新旧图只有纪元变化才强制消费者重载——provider 换了实现但 key/version/schema 没变消费者无需重建。7.4 RuntimePlan计划数据结构RuntimePlaninternal/extension/runtimeplan.go携带Added/Removed/Reloaded/Unchanged四类组件列表ActivateOrder与DrainOrderPrefixChanged只有在比较新旧快照CacheHash之后才记录的诊断事实图形 diff 本身无法证明 provider 可见字节是否变化所以由 boot 在两个快照都冻结后对比CacheHash设置ProviderChanged独立记录 provider 能力的新增/移除/重载Kind子图分类结果SubgraphKind。DiffRuntimePlaninternal/extension/runtimeplan.go比较两个图生成确定性的计划组件身份componentIdentityChanged或纪元变化 →Reloaded排空集合 移除 重载按旧图的逆拓扑DrainOrder排列。7.5 子图分类只重载受影响的部分SubgraphKindinternal/extension/runtimeplan.go把计划分为SubgraphNone完全 no-op、SubgraphInterceptorOnly、SubgraphProviderOnly、SubgraphUIOnly、SubgraphMCPOnly、SubgraphSidecar无单一类型的原生运行时包变化、SubgraphFull混合或宿主级变化需要完整重建。classifySubgraphinternal/extension/runtimeplan.go扫描变更组件的Intercepts/Replaces与Provides的 kind得出最窄重建子图。两个关键细节MCP schema 变化保守升级为 Full只要 MCP 后端的能力 schema 形状key → schemaHash 映射变了就返回SubgraphFull避免 provider 可见的工具字节残留过期空provides的插件组件仍算 sidecar 变化。RuntimePlan还提供MayChangePrefix()interceptor-only 与 UI-only 计划按契约不改变 CacheHash、AffectsSidecars()、AffectsInterceptors()、AffectsUI()、AffectsProviders()等谓词供 Rebuild 精确决策跳过哪些工作。No-op 计划不得改变CacheHash且变更应只影响相关子图provider、MCP server、interceptor 链、UI hub。八、原子发布与排空Atomic publish / drain8.1 时序原文档给出的发布流水线Discover → ResolveGraph → CreatePlan → Preflight → ActivateNewGeneration → AwaitReady → PublishController → DrainOldGeneration8.2 不变量Preflight 失败旧运行时保持原样不动分毫新代激活失败整个新代 scope 全部 dispose保证不泄漏新代资源新运行时未进入 Active 之前绝不发布发布是单次原子指针交换atomic pointer swap发布后旧 controller 进入 Draining不再接受新回合只让在途请求完成排空超时取消剩余工作并记录收据过期代的 UI / provider 流 / 事件输出静默丢弃。实现状态表中对应的落地项包括PublishGate 过期 UI/provider chunk 丢弃、ScheduleDrainWatch/SweepAndForceExpire排空超时的产品路径、Controller 在PublishGate上的准入turnDroppedDraining即 Draining 状态下新回合被丢弃。九、效果收据Effect Receipts9.1 记录内容不可逆与可补偿效果会记录owner、generation、component、class、时间戳、收据 id、补偿状态。三个关键的诚实性约束已经提交给 provider 的请求绝不能被报告为已回滚文件写入必须有先前状态或补偿函数已发送的消息要记录收据并具备防重复发送保护取消只停止后续工作。9.2 账本边界账本最多保留32 个代、每代256 条收据逐出eviction会标记恢复证据不完整、释放关联的文件先前状态并阻止干净回滚的声明账本不持久化进程崩溃恢复明确不在本设计范围内——这正是Receipt recovery is process-local, bounded, and does not promise crash recovery决策的落地。实现上对应internal/extension/receipt_store.go与DecideResume doctor/desktop provider-submit receipts 的收据驱动恢复/检查点路径。十、权限边界依赖图回答的是组件可以获取哪些能力它不替代沙箱受信任的宿主组件、原生 sidecar进程边界与不可信插件在调用时依然要面对权限拦截器permission interceptors。即图解决能不能依赖拦截器解决调用时允不允许。十一、扩展协议新增错误原因在既有冻结错误表之外v2 新增原文档Error reasons一节dependency_unsatisfied依赖未满足dependency_cycle依赖成环schema_mismatchschema 不匹配activation_failed激活失败stale_generation过期代cleanup_failed清理失败unsupported_version已存在。这些错误原因与GraphError的Reason字段一一对应dependency_unsatisfied、dependency_cycle、duplicate_provider等均可见于 internal/extension/dependency.go。十二、迁移路径reasonix plugin migrate name --to-v2只重写省略apiVersion的旧式原生清单备份原文件对无法推断的依赖直接报错不接受 Manifest v1reasonix plugin doctor报告依赖与协议错误并解释组件为何 Inactive对应LifecycleRegistry FormatRuntimeStatus与 doctor runtime / desktopRuntimeDoctor的实现项v1 / 无 apiVersion 的原生清单在install、doctor、boot三处一律失败。十三、验收标准与实现状态13.1 十项验收标准原文档的 Acceptance 清单实现是否达标的判定依据每个 v2 组件资源都有明确 owner 与 EffectScope激活失败绝不泄漏新代资源缺失依赖变成带诊断的 Inactive绝不 panic依赖替换只重载受影响子图发布/排空顺序可测试不可逆工作绝不标记为回滚成功v1 原生清单被拒绝不双读、不迁移提示词/工具缓存稳定性守卫通过Doctor 能解释组件为何 Inactive无外部运行时或语言依赖。13.2 仓库实现状态原文档末表确认了全部实现项已完成与源码对应关系摘要如下设计项仓库实现落点EffectScope / LiveScope / RuntimeSetinternal/extension/effectscope.go、internal/extension/runtimeset.goextensioncontract DependencyGraph RuntimePlaninternal/extensioncontract/capability.go、internal/extension/dependency.go、internal/extension/runtimeplan.goManifest v2 拒绝 v1golden fixture 见 docs/superpowers/specs/fixtures/spatiotemporal-v2/manifest.v2.golden.json生命周期状态与诊断internal/extension/dependency.go、LifecycleRegistry FormatRuntimeStatus收据驱动的恢复/检查点internal/extension/receipt_store.go、DecideResume排空超时产品路径ScheduleDrainWatch/SweepAndForceExpire全子图 BuildRuntime跳过 tools/promptRuntimePlan.Kind分类 ReuseAssemblyrediscovery skip CacheHashreuse集成矩阵快速重载、provider 分类、准入internal/extension/runtimeplan_classify_test.go、internal/extension/runtimeplan_test.go、internal/extension/dependency_test.go 等测试佐证十四、实践排查速查基于上述设计当你在 DeepSeek-Reasonix 中遇到插件/运行时问题时可按以下线索定位组件 Inactive运行reasonix plugin doctor查看dependency_unsatisfied必选依赖缺失或诊断中的 optional-missing 条目缺依赖的非可选组件保持 Inactive 是预期行为不是崩溃v1 清单被拒检查reasonix-plugin.json是否包含apiVersion: reasonix.io/plugin/v2缺失或 v1 会在 install、doctor、boot 三处被硬拒绝需用reasonix plugin migrate name --to-v2迁移旧式无 apiVersion 清单热重载范围失控查看RuntimePlan.Kind分类——provider 只动 provider 子图、interceptor 只动 interceptor 链、UI 只动 UI hub、MCP schema 形状变了才会升级为 Full怀疑资源泄漏核对资源是否全部注册进EffectScope进程、MCP transport、provider 流、watcher、事件订阅、UI 绑定、goroutine、会话临时资源激活中途失败时 scope 会自动 dispose 已跟踪效果发布时序问题确认Preflight → ActivateNew → AwaitReady → PublishController → DrainOld五步的顺序没有被绕过发布是单次原子指针交换排空超时由ScheduleDrainWatch/SweepAndForceExpire兜底。结语Spatiotemporal Composability v2 设计把配置不可变、资源可回收、依赖可解析、发布可原子四条原则落到了 DeepSeek-Reasonix 的原生插件运行时上EffectScope统一了活句柄的登记与清理extensioncontract提供了类型化的能力身份DependencyGraph RuntimePlan让热重载精确到子图收据账本则在不承诺崩溃恢复的前提下保证了不可逆工作的诚实性。整份设计与 internal/extension 下的源码实现、internal/extensioncontract 的契约类型以及 docs/superpowers/specs/fixtures/spatiotemporal-v2 的 golden fixture 相互印证是理解 Reasonix 插件运行时内核的最佳入口。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考