Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,14 @@ jobs:
with:
path: provider

# Loader 编译到契约;共享层不进 Loader 包(ADR-0036)。
# Loader 编译到契约;共享层不进 Loader 包(FX-0036)。
- name: 契约
uses: actions/checkout@v7
with:
repository: HosihikariFramework/PluginAbstractions
path: Plugin.Abstractions

# 打包器在核心仓;共享层清单由它统一给出(ADR-0036)。
# 打包器在核心仓;共享层清单由它统一给出(FX-0036)。
- name: 核心打包器
uses: actions/checkout@v7
with:
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The host expects sibling `PluginManager`, `Plugin.Abstractions`, and
- Cache keys cover source text, package-local DLLs, Roslyn version, and runtime version. Keep the
checksum check in sync.
- Operator-facing messages come from `src/Resources/LoaderStrings.resx` (neutral English) and
`LoaderStrings.zh.resx`; exception messages are English (ADR-0050).
`LoaderStrings.zh.resx`; exception messages are English (FX-0050).
- A failed load releases its ALC. After excluding abstract/interface types and implementations
without a public parameterless constructor, a package exposes exactly one `IPlugin` candidate.
- Public default branches are protected. Work on a branch, open a pull request, and squash merge.
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ to IL before the plugin runs, and the loader loads that IL into a collectible AL

**In-process .NET.** The framework keeps the assembly loader, this C# loader and the F# loader
in-process. Other languages go through the generic out-of-process loader
(`Hosihikari.PluginLoader.Rpc`, ADR-0031).
(`Hosihikari.PluginLoader.Rpc`, FX-0031).

## Templates

Expand Down Expand Up @@ -96,14 +96,14 @@ package carry different builds of the same dependency; shared framework assembli
existing identity.
Parsing passes an encoding, without which Roslyn refuses to emit debugging information (CS8055).

The output is cached by content (ADR-0029): `<data directory>/bin/<hash>/<name>.dll`, the hash covering
The output is cached by content (FX-0029): `<data directory>/bin/<hash>/<name>.dll`, the hash covering
the source text, package-local private DLL names and contents, the Roslyn version and the runtime version. A checksum sits next to it and is verified
before loading — a mismatch means recompile, never load anyway. Compilation goes into a staging
directory and is moved into place only on success, and a portable PDB is emitted alongside so logged
stacks carry `file:line`.

The checksum guards against accidents, not against a hostile plugin: plugins share this process and
are trusted (ADR-0011).
are trusted (FX-0011).

## Running it

Expand Down Expand Up @@ -137,8 +137,8 @@ pwsh ./pack.ps1 -Version 1.0.0 -OutputRoot artifacts

It assembles the loader DLL, its private dependencies and `hosihikari.json` into
`plugins/hosihikari-csharp/`; the packer generates the LeviLamina `manifest.json` envelope from it
(ADR-0058), and the shared layer is not copied. Pushing a `v*` tag attaches the zip
to the GitHub release (ADR-0044).
(FX-0058), and the shared layer is not copied. Pushing a `v*` tag attaches the zip
to the GitHub release (FX-0044).

The script invokes the core packager (`PluginManager/tools/Pack`), which owns the
shared-layer list. Check out the core repository alongside this one, or set
Expand Down
8 changes: 4 additions & 4 deletions README.zh_hans.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ C# 插件因此拿到与其他程序集插件一样的承诺:每插件的依
这是进程内加载器:在插件开始运行前把源码编译为 IL,加载器把 IL 装进 collectible ALC。

**进程内只留 .NET。** 框架在进程内保留程序集型、C# 与 F# 三个加载器;其他语言走
通用的进程外加载器(`Hosihikari.PluginLoader.Rpc`,ADR-0031)。
通用的进程外加载器(`Hosihikari.PluginLoader.Rpc`,FX-0031)。

## 模板

Expand Down Expand Up @@ -87,11 +87,11 @@ public sealed class HelloPlugin : IPlugin
宿主与包带同名依赖的不同版本时,编译与运行会选同一份;共享框架程序集仍保持原来的类型身份。
解析源码时要给编码,否则 Roslyn 拒绝发调试信息(CS8055)。

产物按内容寻址缓存(ADR-0029):`<数据目录>/bin/<哈希>/<名字>.dll`,哈希覆盖源码内容、Roslyn 版本与
产物按内容寻址缓存(FX-0029):`<数据目录>/bin/<哈希>/<名字>.dll`,哈希覆盖源码内容、Roslyn 版本与
运行时版本,以及包内私有 DLL 的名字和内容。产物旁存一份校验和,加载前对一遍 —— 对不上就重编,绝不照跑。编译先落到临时目录、成功了才
改名进去;同时产出 portable PDB,日志里的栈因此带 `file:line`。

校验和防的是**事故**,不防**恶意**:插件与本框架同进程、且完全受信(ADR-0011)。
校验和防的是**事故**,不防**恶意**:插件与本框架同进程、且完全受信(FX-0011)。

## 跑一遍

Expand All @@ -117,7 +117,7 @@ dotnet run --project host/Hosihikari.PluginLoader.CSharp.Host.csproj -c Release
pwsh ./pack.ps1 -Version 1.0.0 -OutputRoot artifacts
```

它把加载器 DLL、私有依赖与 `hosihikari.json` 装进 `plugins/hosihikari-csharp/`,信封 `manifest.json` 由打包器生成(ADR-0058),共享层不随包走;打 `v*` 标签时 CI 把 zip 附到 release(ADR-0044)。
它把加载器 DLL、私有依赖与 `hosihikari.json` 装进 `plugins/hosihikari-csharp/`,信封 `manifest.json` 由打包器生成(FX-0058),共享层不随包走;打 `v*` 标签时 CI 把 zip 附到 release(FX-0044)。

打包脚本调用插件管理器打包器(`PluginManager/tools/Pack`),共享层清单由插件管理器统一给出;需要并列检出插件管理器仓,或设置 `HOSIHIKARI_PLUGINMANAGER`。

Expand Down
14 changes: 7 additions & 7 deletions host/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@
CultureInfo.DefaultThreadCurrentUICulture = CultureInfo.GetCultureInfo("zh-Hans");
CultureInfo.CurrentUICulture = CultureInfo.GetCultureInfo("zh-Hans");

// 载体中立检查(ADR-0015):普通 .NET 控制台驱动核心,不碰 BDS、Shim、任何载体。
// 载体中立检查(FX-0015):普通 .NET 控制台驱动核心,不碰 BDS、Shim、任何载体。
//
// 宿主不直接注册 C# 加载器 —— 它把加载器当成一个插件包装进去,由那个包在 OnLoad
// 里把自己登记给框架(ADR-0002)。第二步才是 C# 的本体:装载时用 Roslyn 编译,进 collectible ALC。
// 里把自己登记给框架(FX-0002)。第二步才是 C# 的本体:装载时用 Roslyn 编译,进 collectible ALC。
var stage = Path.Combine(Path.GetTempPath(), "hosihikari-csharp-spike");
if (Directory.Exists(stage))
{
Expand All @@ -27,7 +27,7 @@
StageProviderPackage();
var nativeStaged = StageScriptPackage();

// 运营方的覆盖放包外(ADR-0018)—— 脚本读到的应当是这一份。
// 运营方的覆盖放包外(FX-0018)—— 脚本读到的应当是这一份。
File.WriteAllText(Path.Combine(configRoot, "Hello.conf"), "greeting = \"overridden\"\n");

var collection = new ServiceCollection();
Expand All @@ -53,7 +53,7 @@
host.LoadAll();
Console.WriteLine($"已加载:{string.Join(", ", host.LoadedNames)}");

// 程序集这一侧发一条通道消息 —— 与 C# 脚本用的是同一个载荷类型(ADR-0026)。
// 程序集这一侧发一条通道消息 —— 与 C# 脚本用的是同一个载荷类型(FX-0026)。
host.Events.Publish(new ChannelMessage("ping", "\"from-host\""));
Thread.Sleep(200);

Expand Down Expand Up @@ -82,7 +82,7 @@
checks.Add(("包内自带的第三方依赖可用", Read("hash.txt") == expectedHash, Read("hash.txt")));
checks.Add(("宿主未引用的包内私有依赖可用", Read("private.txt") == "private-dependency", Read("private.txt")));

// 本机库按 RID 目录优先解析(ADR-0034);包根那份是 1,RID 那份是 42。
// 本机库按 RID 目录优先解析(FX-0034);包根那份是 1,RID 那份是 42。
checks.Add((
"本机库按 RID 目录解析",
!nativeStaged || Read("native.txt") == "42",
Expand Down Expand Up @@ -466,7 +466,7 @@ void StageProviderPackage()
}
""");

// 整个构建输出随包走,只把共享层剔掉(ADR-0004)。
// 整个构建输出随包走,只把共享层剔掉(FX-0004)。
var output = Path.Combine(RepoRoot(), "src", "bin", ConfigurationName(), "net10.0");
foreach (var file in Directory.EnumerateFiles(output, "*.dll"))
{
Expand Down Expand Up @@ -504,7 +504,7 @@ bool StageScriptPackage()
}
""");

// 作者给的默认值,随包更新(ADR-0018)。
// 作者给的默认值,随包更新(FX-0018)。
File.WriteAllText(Path.Combine(package, "Hello.conf"), "greeting = \"package\"\n");

// 包里自带的第三方依赖:不是框架的一部分,编译期与运行期都得从包里拿。
Expand Down
4 changes: 2 additions & 2 deletions pack.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

The package is a plugin package itself: loader DLL, private dependencies and
the author manifest. Shared-layer assemblies are excluded by the core packager
from its canonical list (ADR-0019 / 0026 / 0036). The LeviLamina envelope
(`manifest.json`) is generated by the packer, never written here (ADR-0058).
from its canonical list (FX-0019 / 0026 / 0036). The LeviLamina envelope
(`manifest.json`) is generated by the packer, never written here (FX-0058).

Requires a sibling PluginManager checkout, or HOSIHIKARI_PLUGINMANAGER.

Expand Down
18 changes: 9 additions & 9 deletions src/CSharpPluginLoader.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@
namespace Hosihikari.PluginLoader.CSharp;

/// <summary>
/// C# 型插件的加载器(ADR-0002 的扩展点)。
/// C# 型插件的加载器(FX-0002 的扩展点)。
///
/// 与 F# 那条同形:C# 直接跑在 CLR 上,所以这里**装载时编译** —— Roslyn 把 <c>.cs</c> 编成
/// 程序集,再交给一个 collectible ALC,拿到与其他程序集插件一样的隔离与卸载承诺。
///
/// 产物按**内容寻址**缓存(ADR-0029):目录名是脚本内容、Roslyn 版本与运行时版本的哈希,
/// 产物按**内容寻址**缓存(FX-0029):目录名是脚本内容、Roslyn 版本与运行时版本的哈希,
/// 所以脚本一改就换目录;产物旁另存一份校验和,加载前对一遍。
///
/// 入口靠约定:编出来的程序集里那个实现 <see cref="IPlugin"/>、有无参构造的类型(ADR-0008)。
/// 入口靠约定:编出来的程序集里那个实现 <see cref="IPlugin"/>、有无参构造的类型(FX-0008)。
/// </summary>
public sealed class CSharpPluginLoader : IPluginLoader
{
Expand Down Expand Up @@ -147,7 +147,7 @@
{
context.Logger.LogError(
"{Message}",
LoaderText.Get("EntryCreateFailed", candidates[0].FullName));

Check warning on line 150 in src/CSharpPluginLoader.cs

View workflow job for this annotation

GitHub Actions / assertions (ubuntu-latest)

Possible null reference argument for parameter 'arguments' in 'string LoaderText.Get(string key, params object[] arguments)'.

Check warning on line 150 in src/CSharpPluginLoader.cs

View workflow job for this annotation

GitHub Actions / assertions (windows-latest)

Possible null reference argument for parameter 'arguments' in 'string LoaderText.Get(string key, params object[] arguments)'.
loadContext.Unload();
return null;
}
Expand Down Expand Up @@ -385,15 +385,15 @@
return Convert.ToHexStringLower(hasher.GetCurrentHash());
}

/// <summary>插件目录里自带的依赖;框架已经有的那些不算(共享层,ADR-0004)。</summary>
/// <summary>插件目录里自带的依赖;框架已经有的那些不算(共享层,FX-0004)。</summary>
private static IReadOnlyList<string> LocalAssemblies(string packageDirectory) =>
Directory.EnumerateFiles(packageDirectory, "*.dll")
.Where(IsManagedAssembly)
.Where(path => !IsFrameworkAssembly(Path.GetFileNameWithoutExtension(path)))
.OrderBy(path => path, StringComparer.Ordinal)
.ToArray();

/// <summary>包根可以有本机库(ADR-0034);它们不能当 Roslyn 的元数据引用。</summary>
/// <summary>包根可以有本机库(FX-0034);它们不能当 Roslyn 的元数据引用。</summary>
private static bool IsManagedAssembly(string path)
{
try
Expand All @@ -407,7 +407,7 @@
}
}

// 共享层按契约的清单判(ADR-0019 / 0026),不看宿主恰好加载过什么:
// 共享层按契约的清单判(FX-0019 / 0026),不看宿主恰好加载过什么:
// 否则插件自带的同名库会被静默顶掉,还不进缓存键。
private static bool IsFrameworkAssembly(string name) =>
PluginContractInfo.BaseSharedAssemblyFileNames
Expand Down Expand Up @@ -479,7 +479,7 @@
}
catch (Exception ex)
{
// 编译期出错只让这一个插件倒下(ADR-0009)。
// 编译期出错只让这一个插件倒下(FX-0009)。
context.Logger.LogError(ex, "{Message}", LoaderText.Get("CompileFailed", scriptPath));
return false;
}
Expand Down Expand Up @@ -725,7 +725,7 @@

protected override IntPtr LoadUnmanagedDll(string unmanagedDllName)
{
// 本机库随进程存活;这里只负责按 RID → 包根的顺序找到它(ADR-0034)。
// 本机库随进程存活;这里只负责按 RID → 包根的顺序找到它(FX-0034)。
var path = FindNativeLibrary(_packageDirectory, unmanagedDllName);
return path is null ? IntPtr.Zero : LoadUnmanagedDllFromPath(path);
}
Expand Down Expand Up @@ -794,7 +794,7 @@

public override bool IsUnloaded => _weakContext is { IsAlive: false };

/// <summary>编出来的程序集就是搬运单元(ADR-0010):放下它,回收照常验证(ADR-0023)。</summary>
/// <summary>编出来的程序集就是搬运单元(FX-0010):放下它,回收照常验证(FX-0023)。</summary>
public override void Unload()
{
if (_loadContext is null)
Expand Down
6 changes: 3 additions & 3 deletions src/LoaderBootstrap.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,17 @@
namespace Hosihikari.PluginLoader.CSharp;

/// <summary>
/// 加载器本身就是一个插件包(ADR-0002):它在装载时把自己登记给框架,此后要路由给
/// 加载器本身就是一个插件包(FX-0002):它在装载时把自己登记给框架,此后要路由给
/// C# 的包才会被它接管。
///
/// 顺序靠依赖声明保证 —— 需要它的插件在清单里声明依赖本包(ADR-0006),依赖图会先排它。
/// 顺序靠依赖声明保证 —— 需要它的插件在清单里声明依赖本包(FX-0006),依赖图会先排它。
/// 登记之后不能撤销,所以本包装上就别指望能卸掉:它造出来的实例的类型住在它的装载上下文里。
/// </summary>
public sealed class LoaderBootstrap : IPlugin
{
public ValueTask OnLoad(IPluginContext context, CancellationToken cancellationToken)
{
// 加载器包按清单的 kind 拿到 ILoaderContext(ADR-0059);拿不到说明清单漏写了 kind。
// 加载器包按清单的 kind 拿到 ILoaderContext(FX-0059);拿不到说明清单漏写了 kind。
if (context is not ILoaderContext loaderContext)
{
throw new InvalidOperationException(
Expand Down