继承接口面

本页汇总每个插件天然可见、但不属于某个 Tether 产品能力的框架接口：Cordis 核心 Context、 生命周期事件，以及 dsh 中由 loader / hmr / timer 混入的成员。它也是 TS 声明合并与 C# Type-keyed seam 的对照表。

对照基准是 dsh dsh-v0.1.1-rc.1 的 Inherited Cordis API。 该上游页面由 vendored Cordis、loader、hmr 和 timer 源码生成；本页记录当前 C# 实际公开面，不伪造同名成员。 对应的固定源码包括 events.ts、 loader/index.ts、 hmr/index.ts 与 timer/index.ts。

Inherited ctx members

各核心成员的完整签名见 Context、Events、 Fiber 与 Plugin Registry。

C# Context 默认公开面

下面是插件收到的 Context 上可直接调用的类别级清单；泛型 overload 在所属参考页逐项列出。

这些不是从多个服务动态 mixin 出来的代理属性，而是 Context 的真实公开成员。直接使用 ctx.Events.On(...) 或其它底层对象时，要重新承担生命周期所有权；插件日常代码应优先调用 Context 转发。

Inherited events：TS → C#

dsh inherited 页面列出的 core / loader / hmr 事件，与 C# 当前事件面并非一一同名：

“无公开事件”表示当前 C# 调用方没有同层 hook；不应通过猜测字符串事件名来依赖内部实现。

C# 核心生命周期事件

C# 把插件作者确实需要的框架事件集中在 LifecycleEvents：

public static class LifecycleEvents
{
    public const string Ready = "ready";
    public const string Dispose = "dispose";
    public const string Fork = "fork";
    public const string Service = "service";
    public const string Error = "internal/error";
}

ctx.On<Type>(LifecycleEvents.Service, key =>
{
    Console.WriteLine($"service changed: {key.FullName}");
});

ctx.On<Exception, string>(LifecycleEvents.Error, (error, source) =>
{
    logger.LogError(error, "Contained Cordis failure from {Source}", source);
});

Loader、HMR 与 timer 为什么不混入 ctx

Loader

CompositionLoader 是显式对象：宿主提供 PluginCatalog，调用 Render* / Load*， 并持有返回的 MountedComposition。组合替换、回滚与 disposal 因此有明确 owner，不依赖 ambient ctx.loader。

HMR

HotReloadWatcher 显式接收 Context、源码目录和 ScriptCompiler。调用方持有 watcher， 可查询 IsRunning / MountedFiles，调用 StartAsync、ReloadAsync、UnmountAsync、DisposeAsync。 它还有 .NET Error event，同时把失败 contained 到 Cordis internal/error；没有 ctx.hmr 或 hmr 字符串事件协议。

Timer

C# 直接使用 BCL timer，并把它绑定到 scope：

var timer = new PeriodicTimer(TimeSpan.FromSeconds(5));
ctx.Effect(timer.Dispose);

async Task RefreshLoopAsync()
{
    try
    {
        while (await timer.WaitForNextTickAsync(ctx.Scope.Cancellation))
        {
            await RefreshAsync();
        }
    }
    catch (OperationCanceledException) when (ctx.Scope.Cancellation.IsCancellationRequested)
    {
    }
}

若长期循环由 apply 启动，插件不能在 apply 中直接 await RefreshLoopAsync()；通常启动后台任务、监听 scope cancellation， 并登记一个可等待 disposer 来 join 该任务。核心不提供 interval / timeout / throttle / debounce mixin。

在 C# 中扩展插件可见接口

TS 通过 declare module 扩展 Context / Events 接口，再依靠字符串键和 proxy 注入实现。C# 使用两条显式 seam。

服务：接口 Type

public interface IIndexService
{
    ValueTask RebuildAsync(CancellationToken cancellationToken = default);
}

// provider
ctx.Provide<IIndexService>(new LocalIndexService());

// consumer
[Inject(typeof(IIndexService))]
public sealed class SearchPlugin : Plugin
{
    protected override void Apply(Context ctx)
        => _ = ctx.Require<IIndexService>();
}

Service Definition 程序集只放接口；Provider 和 Consumer 都引用它。更换 preset 时只换实现，不换消费方引用。

事件：常量 + 泛型调用点

public static class IndexEvents
{
    public const string Rebuilt = "index/rebuilt";
}

ctx.On<int>(IndexEvents.Rebuilt, documentCount => { /* ... */ });
await ctx.EmitAsync(IndexEvents.Rebuilt, 42);

事件名仍是运行时字符串，泛型只约束当前 listener 的参数形状；发布包应集中声明常量和约定，不在各处散写 literal。 需要编译期更强的契约时，优先把交互建模为 Service Definition 接口。