From 89068e93a6a8d54c9f4e4503b2d51a7686e1ea08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BA=88=E7=BA=BE?= Date: Thu, 19 Nov 2026 13:44:27 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20ADR=20=E5=BC=95=E7=94=A8=E6=94=B9?= =?UTF-8?q?=E7=94=A8=E5=B7=A5=E4=BD=9C=E5=8C=BA=E5=89=8D=E7=BC=80=20FX-NNN?= =?UTF-8?q?N?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 跨工作区引用分得清是哪个序号;纯替换,不动代码与文件名。 --- AGENTS.md | 2 +- README.md | 10 +++++----- README.zh_hans.md | 8 ++++---- host/Program.cs | 14 +++++++------- pack.ps1 | 4 ++-- src/CSharpPluginLoader.cs | 18 +++++++++--------- src/LoaderBootstrap.cs | 6 +++--- 7 files changed, 31 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 06f1b42..19691ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index b254ce8..9fa1840 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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): `/bin//.dll`, the hash covering +The output is cached by content (FX-0029): `/bin//.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 @@ -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 diff --git a/README.zh_hans.md b/README.zh_hans.md index bd431ee..ff39f26 100644 --- a/README.zh_hans.md +++ b/README.zh_hans.md @@ -9,7 +9,7 @@ C# 插件因此拿到与其他程序集插件一样的承诺:每插件的依 这是进程内加载器:在插件开始运行前把源码编译为 IL,加载器把 IL 装进 collectible ALC。 **进程内只留 .NET。** 框架在进程内保留程序集型、C# 与 F# 三个加载器;其他语言走 -通用的进程外加载器(`Hosihikari.PluginLoader.Rpc`,ADR-0031)。 +通用的进程外加载器(`Hosihikari.PluginLoader.Rpc`,FX-0031)。 ## 模板 @@ -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)。 ## 跑一遍 @@ -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`。 diff --git a/host/Program.cs b/host/Program.cs index 5daaaa3..e17a4e6 100644 --- a/host/Program.cs +++ b/host/Program.cs @@ -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)) { @@ -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(); @@ -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); @@ -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", @@ -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")) { @@ -504,7 +504,7 @@ bool StageScriptPackage() } """); - // 作者给的默认值,随包更新(ADR-0018)。 + // 作者给的默认值,随包更新(FX-0018)。 File.WriteAllText(Path.Combine(package, "Hello.conf"), "greeting = \"package\"\n"); // 包里自带的第三方依赖:不是框架的一部分,编译期与运行期都得从包里拿。 diff --git a/pack.ps1 b/pack.ps1 index 5fa1f00..42dc9c6 100644 --- a/pack.ps1 +++ b/pack.ps1 @@ -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. diff --git a/src/CSharpPluginLoader.cs b/src/CSharpPluginLoader.cs index 4195c32..3c4b6e5 100644 --- a/src/CSharpPluginLoader.cs +++ b/src/CSharpPluginLoader.cs @@ -13,15 +13,15 @@ namespace Hosihikari.PluginLoader.CSharp; /// -/// C# 型插件的加载器(ADR-0002 的扩展点)。 +/// C# 型插件的加载器(FX-0002 的扩展点)。 /// /// 与 F# 那条同形:C# 直接跑在 CLR 上,所以这里**装载时编译** —— Roslyn 把 .cs 编成 /// 程序集,再交给一个 collectible ALC,拿到与其他程序集插件一样的隔离与卸载承诺。 /// -/// 产物按**内容寻址**缓存(ADR-0029):目录名是脚本内容、Roslyn 版本与运行时版本的哈希, +/// 产物按**内容寻址**缓存(FX-0029):目录名是脚本内容、Roslyn 版本与运行时版本的哈希, /// 所以脚本一改就换目录;产物旁另存一份校验和,加载前对一遍。 /// -/// 入口靠约定:编出来的程序集里那个实现 、有无参构造的类型(ADR-0008)。 +/// 入口靠约定:编出来的程序集里那个实现 、有无参构造的类型(FX-0008)。 /// public sealed class CSharpPluginLoader : IPluginLoader { @@ -385,7 +385,7 @@ private static string CacheKey(IReadOnlyList sources, string package return Convert.ToHexStringLower(hasher.GetCurrentHash()); } - /// 插件目录里自带的依赖;框架已经有的那些不算(共享层,ADR-0004)。 + /// 插件目录里自带的依赖;框架已经有的那些不算(共享层,FX-0004)。 private static IReadOnlyList LocalAssemblies(string packageDirectory) => Directory.EnumerateFiles(packageDirectory, "*.dll") .Where(IsManagedAssembly) @@ -393,7 +393,7 @@ private static IReadOnlyList LocalAssemblies(string packageDirectory) => .OrderBy(path => path, StringComparer.Ordinal) .ToArray(); - /// 包根可以有本机库(ADR-0034);它们不能当 Roslyn 的元数据引用。 + /// 包根可以有本机库(FX-0034);它们不能当 Roslyn 的元数据引用。 private static bool IsManagedAssembly(string path) { try @@ -407,7 +407,7 @@ private static bool IsManagedAssembly(string path) } } - // 共享层按契约的清单判(ADR-0019 / 0026),不看宿主恰好加载过什么: + // 共享层按契约的清单判(FX-0019 / 0026),不看宿主恰好加载过什么: // 否则插件自带的同名库会被静默顶掉,还不进缓存键。 private static bool IsFrameworkAssembly(string name) => PluginContractInfo.BaseSharedAssemblyFileNames @@ -479,7 +479,7 @@ private bool Compile( } catch (Exception ex) { - // 编译期出错只让这一个插件倒下(ADR-0009)。 + // 编译期出错只让这一个插件倒下(FX-0009)。 context.Logger.LogError(ex, "{Message}", LoaderText.Get("CompileFailed", scriptPath)); return false; } @@ -725,7 +725,7 @@ public ScriptLoadContext( 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); } @@ -794,7 +794,7 @@ internal sealed class CompiledPluginHandle(IPlugin plugin, AssemblyLoadContext l public override bool IsUnloaded => _weakContext is { IsAlive: false }; - /// 编出来的程序集就是搬运单元(ADR-0010):放下它,回收照常验证(ADR-0023)。 + /// 编出来的程序集就是搬运单元(FX-0010):放下它,回收照常验证(FX-0023)。 public override void Unload() { if (_loadContext is null) diff --git a/src/LoaderBootstrap.cs b/src/LoaderBootstrap.cs index 43d6017..04560de 100644 --- a/src/LoaderBootstrap.cs +++ b/src/LoaderBootstrap.cs @@ -5,17 +5,17 @@ namespace Hosihikari.PluginLoader.CSharp; /// -/// 加载器本身就是一个插件包(ADR-0002):它在装载时把自己登记给框架,此后要路由给 +/// 加载器本身就是一个插件包(FX-0002):它在装载时把自己登记给框架,此后要路由给 /// C# 的包才会被它接管。 /// -/// 顺序靠依赖声明保证 —— 需要它的插件在清单里声明依赖本包(ADR-0006),依赖图会先排它。 +/// 顺序靠依赖声明保证 —— 需要它的插件在清单里声明依赖本包(FX-0006),依赖图会先排它。 /// 登记之后不能撤销,所以本包装上就别指望能卸掉:它造出来的实例的类型住在它的装载上下文里。 /// 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( From 822a80f9b9eeb21d8192844461a54e69ad77d78a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BA=88=E7=BA=BE?= Date: Thu, 19 Nov 2026 14:30:04 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20ADR=20=E5=BC=95=E7=94=A8=E6=94=B9?= =?UTF-8?q?=E7=94=A8=E5=B7=A5=E4=BD=9C=E5=8C=BA=E5=89=8D=E7=BC=80=20FX-NNN?= =?UTF-8?q?N?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 纯替换,不动代码、文件名与行文。 --- .github/workflows/release.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8d8ca09..ab81cdf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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: