chore(release): merge dev into main for v0.0.66

BAKAOLC · BAKAOLC · commit 4160017dde90 · 2026-04-20T18:32:06.000+08:00
diff --git a/Const.cs b/Const.cs
@@ -18,7 +18,7 @@ public static class Const
         /// <summary>
         ///     Assembly / manifest version string.
         /// </summary>
-        public const string Version = "0.0.65";
+        public const string Version = "0.0.66";
 
         /// <summary>
         ///     Root key for RitsuLib JSON settings under the mod’s user folder.
diff --git a/Docs/en/ContentAuthoringToolkit.md b/Docs/en/ContentAuthoringToolkit.md
@@ -31,7 +31,7 @@ RitsuLibFramework.CreateContentPack("MyMod")
     .Character<MyCharacter>()
     .Card<MyCardPool, MyCard>()
     .Relic<MyRelicPool, MyRelic>()
-    .CardKeyword("my_keyword", locKeyPrefix: "my_mod_my_keyword", iconPath: "res://MyMod/art/kw.png")
+    .CardKeywordOwnedByLocNamespace("my_keyword", iconPath: "res://MyMod/art/kw.png")
     .Story<MyStory>()
     .Epoch<MyEpoch>()
     .RequireEpoch<MyCard, MyEpoch>()
diff --git a/Docs/en/ContentPacksAndRegistries.md b/Docs/en/ContentPacksAndRegistries.md
@@ -36,7 +36,7 @@ RitsuLibFramework.CreateContentPack("MyMod")
     .Character<MyCharacter>()
     .Card<MyCardPool, MyCard>()
     .Relic<MyRelicPool, MyRelic>()
-    .CardKeyword("brew", locKeyPrefix: "my_mod_brew")
+    .CardKeywordOwnedByLocNamespace("brew")
     .Epoch<MyCharacterEpoch>()
     .Story<MyStory>()
     .RequireEpoch<MyLateCard, MyCharacterEpoch>()
@@ -219,7 +219,7 @@ var contentEntries = new IContentRegistrationEntry[]
 
 var keywordEntries = new[]
 {
-    KeywordRegistrationEntry.Card("brew", "my_mod_brew"),
+    KeywordRegistrationEntry.OwnedCardByLocNamespace("MyMod", "brew"),
 };
 
 RitsuLibFramework.CreateContentPack("MyMod")
diff --git a/Docs/en/LocalizationAndKeywords.md b/Docs/en/LocalizationAndKeywords.md
@@ -107,16 +107,35 @@ Use `ModKeywordRegistry` when you want reusable keyword definitions and hover ti
 ```csharp
 var keywords = RitsuLibFramework.GetKeywordRegistry("MyMod");
 
-keywords.RegisterCardKeyword(
-    id: "brew",
-    locKeyPrefix: "my_mod_brew",
+keywords.RegisterCardKeywordOwnedByLocNamespace(
+    localKeywordStem: "brew",
     iconPath: "res://MyMod/ui/keywords/brew.png");
 ```
 
 This creates a normalized keyword id and binds it to title / description localization keys.
 
 ---
 
+## Automatic keyword registration (optional: CLR attributes)
+
+If you already use `ModTypeDiscoveryHub.RegisterModAssembly(...)` to let RitsuLib scan your assemblies, you can declare keyword registration with CLR attributes:
+
+```csharp
+using STS2RitsuLib.Interop.AutoRegistration;
+
+[RegisterOwnedCardKeyword("brew", LocNamespace = "my_mod", IconPath = "res://MyMod/ui/keywords/brew.png")]
+public sealed class BrewKeywordMarker;
+```
+
+`LocNamespace` only affects the localization namespace (the `modid` portion). The keyword stem (`brew`) participates in the default rule `<namespace>_<keyword>`, producing:
+
+- `<namespace>_<keyword>.title`
+- `<namespace>_<keyword>.description`
+
+> Compatibility note: the legacy `LocKeyPrefix` / `locKeyPrefix` historically represents the **full stem** and is easy to misread as a prefix + keyword composition, so it is now obsolete. Use `LocNamespace` for new code.
+
+---
+
 ## Using Keywords In Code
 
 Common helpers:
diff --git a/Docs/zh/ContentAuthoringToolkit.md b/Docs/zh/ContentAuthoringToolkit.md
@@ -31,7 +31,7 @@ RitsuLibFramework.CreateContentPack("MyMod")
     .Character<MyCharacter>()
     .Card<MyCardPool, MyCard>()
     .Relic<MyRelicPool, MyRelic>()
-    .CardKeyword("my_keyword", locKeyPrefix: "my_mod_my_keyword", iconPath: "res://MyMod/art/kw.png")
+    .CardKeywordOwnedByLocNamespace("my_keyword", iconPath: "res://MyMod/art/kw.png")
     .Story<MyStory>()
     .Epoch<MyEpoch>()
     .RequireEpoch<MyCard, MyEpoch>()
diff --git a/Docs/zh/ContentPacksAndRegistries.md b/Docs/zh/ContentPacksAndRegistries.md
@@ -36,7 +36,7 @@ RitsuLibFramework.CreateContentPack("MyMod")
     .Character<MyCharacter>()
     .Card<MyCardPool, MyCard>()
     .Relic<MyRelicPool, MyRelic>()
-    .CardKeyword("brew", locKeyPrefix: "my_mod_brew")
+    .CardKeywordOwnedByLocNamespace("brew")
     .Epoch<MyCharacterEpoch>()
     .Story<MyStory>()
     .RequireEpoch<MyLateCard, MyCharacterEpoch>()
@@ -219,7 +219,7 @@ var contentEntries = new IContentRegistrationEntry[]
 
 var keywordEntries = new[]
 {
-    KeywordRegistrationEntry.Card("brew", "my_mod_brew"),
+    KeywordRegistrationEntry.OwnedCardByLocNamespace("MyMod", "brew"),
 };
 
 RitsuLibFramework.CreateContentPack("MyMod")
diff --git a/Docs/zh/LocalizationAndKeywords.md b/Docs/zh/LocalizationAndKeywords.md
@@ -102,16 +102,35 @@ user://mod-configs/<modId>/localization
 ```csharp
 var keywords = RitsuLibFramework.GetKeywordRegistry("MyMod");
 
-keywords.RegisterCardKeyword(
-    id: "brew",
-    locKeyPrefix: "my_mod_brew",
+keywords.RegisterCardKeywordOwnedByLocNamespace(
+    localKeywordStem: "brew",
     iconPath: "res://MyMod/ui/keywords/brew.png");
 ```
 
 注册后会生成规范化标识，并绑定标题/描述的本地化键。
 
 ---
 
+## 自动注册关键词（可选：CLR 特性）
+
+如果你已经使用 `ModTypeDiscoveryHub.RegisterModAssembly(...)` 让 RitsuLib 扫描你的程序集，也可以用特性声明关键词注册：
+
+```csharp
+using STS2RitsuLib.Interop.AutoRegistration;
+
+[RegisterOwnedCardKeyword("brew", LocNamespace = "my_mod", IconPath = "res://MyMod/ui/keywords/brew.png")]
+public sealed class BrewKeywordMarker;
+```
+
+这里 `LocNamespace` 只影响本地化键的 namespace（即 `modid` 部分）。关键词 stem（`brew`）会自动参与默认生成规则：`<namespace>_<keyword>`，并形成：
+
+- `<namespace>_<keyword>.title`
+- `<namespace>_<keyword>.description`
+
+> 兼容性说明：旧字段 `LocKeyPrefix`/`locKeyPrefix` 历史上实际代表“完整 stem”，容易误解为 prefix + keyword，已标记为过时；新代码请使用 `LocNamespace`。
+
+---
+
 ## 在代码里使用关键词
 
 常用辅助方法：
diff --git a/Interop/AutoRegistration/AttributeAutoRegistrationTypeDiscoveryContributor.cs b/Interop/AutoRegistration/AttributeAutoRegistrationTypeDiscoveryContributor.cs
@@ -440,13 +440,44 @@ void Append(Attribute attribute, bool inherited)
                                     ownedCardKeyword.Order,
                                     $"RegisterOwnedCardKeyword:{ownedCardKeyword.LocalKeywordStem}:{type.FullName}",
                                     nameof(RegisterOwnedCardKeywordAttribute),
-                                    () => keywordRegistry.RegisterCardKeywordOwned(
-                                        ValidateNonEmpty(ownedCardKeyword.LocalKeywordStem,
-                                            nameof(ownedCardKeyword.LocalKeywordStem)),
-                                        ownedCardKeyword.LocKeyPrefix,
-                                        ownedCardKeyword.IconPath,
-                                        ownedCardKeyword.CardDescriptionPlacement,
-                                        ownedCardKeyword.IncludeInCardHoverTip)));
+                                    () =>
+                                    {
+                                        var localStem = ValidateNonEmpty(ownedCardKeyword.LocalKeywordStem,
+                                            nameof(ownedCardKeyword.LocalKeywordStem));
+
+                                        if (!string.IsNullOrWhiteSpace(ownedCardKeyword.LocNamespace))
+                                        {
+                                            keywordRegistry.RegisterCardKeywordOwnedByLocNamespace(
+                                                localStem,
+                                                ownedCardKeyword.LocNamespace,
+                                                ownedCardKeyword.IconPath,
+                                                ownedCardKeyword.CardDescriptionPlacement,
+                                                ownedCardKeyword.IncludeInCardHoverTip);
+                                            return;
+                                        }
+
+#pragma warning disable CS0618
+                                        if (!string.IsNullOrWhiteSpace(ownedCardKeyword.LocKeyPrefix))
+                                        {
+                                            keywordRegistry.RegisterCardKeywordOwned(
+                                                localStem,
+                                                ownedCardKeyword.LocKeyPrefix,
+                                                ownedCardKeyword.IconPath,
+                                                ownedCardKeyword.CardDescriptionPlacement,
+                                                ownedCardKeyword.IncludeInCardHoverTip);
+                                            return;
+                                        }
+#pragma warning restore CS0618
+
+#pragma warning disable CS0618
+                                        keywordRegistry.RegisterCardKeywordOwned(
+                                            localStem,
+                                            null,
+                                            ownedCardKeyword.IconPath,
+                                            ownedCardKeyword.CardDescriptionPlacement,
+                                            ownedCardKeyword.IncludeInCardHoverTip);
+#pragma warning restore CS0618
+                                    }));
                             });
                         break;
                     case AutoTimelineSlotAttribute autoTimelineSlot:
diff --git a/Interop/AutoRegistration/RegistrationAttributes.cs b/Interop/AutoRegistration/RegistrationAttributes.cs
@@ -319,9 +319,17 @@ public sealed class RegisterOwnedCardKeywordAttribute(string localKeywordStem)
         /// </summary>
         public string LocalKeywordStem { get; } = localKeywordStem;
 
+        /// <summary>
+        ///     Optional localization namespace used to form the default <c>card_keywords</c> entry stem
+        ///     <c>"{namespace}_{keyword}"</c>.
+        /// </summary>
+        public string? LocNamespace { get; set; }
+
         /// <summary>
         ///     Optional explicit localization key prefix.
         /// </summary>
+        [Obsolete(
+            "Pitfall: LocKeyPrefix is NOT a prefix that affects only the modid/namespace portion. It is the full card_keywords entry stem used to form '{stem}.title' and '{stem}.description'. Prefer LocNamespace.")]
         public string? LocKeyPrefix { get; set; }
 
         /// <summary>
diff --git a/Keywords/KeywordRegistrationEntry.cs b/Keywords/KeywordRegistrationEntry.cs
@@ -1,3 +1,4 @@
+using MegaCrit.Sts2.Core.Helpers;
 using STS2RitsuLib.Content;
 
 namespace STS2RitsuLib.Keywords
@@ -112,6 +113,55 @@ public void Register(ModKeywordRegistry registry)
         /// <summary>
         ///     <c>card_keywords</c> row with an id from <see cref="ModContentRegistry.GetQualifiedKeywordId" />.
         /// </summary>
+        public static KeywordRegistrationEntry OwnedCardByLocNamespace(
+            string modId,
+            string localKeywordStem,
+            string? locNamespace,
+            string? iconPath,
+            ModKeywordCardDescriptionPlacement cardDescriptionPlacement,
+            bool includeInCardHoverTip)
+        {
+            var ns = string.IsNullOrWhiteSpace(locNamespace)
+                ? StringHelper.Slugify(modId)
+                : locNamespace;
+
+            var stem = StringHelper.Slugify(ns) + "_" + StringHelper.Slugify(localKeywordStem);
+            var id = ModContentRegistry.GetQualifiedKeywordId(modId, localKeywordStem);
+
+            return new(
+                id,
+                "card_keywords",
+                $"{stem}.title",
+                "card_keywords",
+                $"{stem}.description",
+                iconPath,
+                cardDescriptionPlacement,
+                includeInCardHoverTip);
+        }
+
+        /// <summary>
+        ///     <c>OwnedCardByLocNamespace</c> overload with legacy hover defaults.
+        /// </summary>
+        public static KeywordRegistrationEntry OwnedCardByLocNamespace(
+            string modId,
+            string localKeywordStem,
+            string? locNamespace = null,
+            string? iconPath = null)
+        {
+            return OwnedCardByLocNamespace(
+                modId,
+                localKeywordStem,
+                locNamespace,
+                iconPath,
+                ModKeywordCardDescriptionPlacement.None,
+                true);
+        }
+
+        /// <summary>
+        ///     <c>card_keywords</c> row with an id from <see cref="ModContentRegistry.GetQualifiedKeywordId" />.
+        /// </summary>
+        [Obsolete(
+            "Pitfall: locKeyPrefix is NOT a prefix that affects only the modid/namespace portion. It is the full card_keywords entry stem used to form '{stem}.title' and '{stem}.description'. Prefer OwnedCardByLocNamespace (default stem: '<modid>_<keyword>').")]
         public static KeywordRegistrationEntry OwnedCard(
             string modId,
             string localKeywordStem,
@@ -135,6 +185,8 @@ public static KeywordRegistrationEntry OwnedCard(
         /// <summary>
         ///     <c>OwnedCard</c> overload with legacy hover defaults.
         /// </summary>
+        [Obsolete(
+            "Pitfall: locKeyPrefix is NOT a prefix that affects only the modid/namespace portion. It is the full card_keywords entry stem used to form '{stem}.title' and '{stem}.description'. Prefer OwnedCardByLocNamespace (default stem: '<modid>_<keyword>').")]
         public static KeywordRegistrationEntry OwnedCard(
             string modId,
             string localKeywordStem,
diff --git a/Keywords/ModKeywordRegistry.cs b/Keywords/ModKeywordRegistry.cs
@@ -155,6 +155,54 @@ public ModKeywordDefinition RegisterOwned(
         /// <summary>
         ///     Registers a <c>card_keywords</c> entry whose id is mod-qualified from <paramref name="localKeywordStem" />.
         /// </summary>
+        public ModKeywordDefinition RegisterCardKeywordOwnedByLocNamespace(
+            string localKeywordStem,
+            string? locNamespace,
+            string? iconPath,
+            ModKeywordCardDescriptionPlacement cardDescriptionPlacement,
+            bool includeInCardHoverTip)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(localKeywordStem);
+
+            var ns = string.IsNullOrWhiteSpace(locNamespace)
+                ? StringHelper.Slugify(_modId)
+                : locNamespace;
+
+            var stem = StringHelper.Slugify(ns) + "_" + StringHelper.Slugify(localKeywordStem);
+            var id = ModContentRegistry.GetQualifiedKeywordId(_modId, localKeywordStem);
+
+            return RegisterCore(
+                id,
+                "card_keywords",
+                $"{stem}.title",
+                "card_keywords",
+                $"{stem}.description",
+                iconPath,
+                cardDescriptionPlacement,
+                includeInCardHoverTip);
+        }
+
+        /// <summary>
+        ///     <c>RegisterCardKeywordOwnedByLocNamespace</c> with legacy hover defaults.
+        /// </summary>
+        public ModKeywordDefinition RegisterCardKeywordOwnedByLocNamespace(
+            string localKeywordStem,
+            string? locNamespace = null,
+            string? iconPath = null)
+        {
+            return RegisterCardKeywordOwnedByLocNamespace(
+                localKeywordStem,
+                locNamespace,
+                iconPath,
+                ModKeywordCardDescriptionPlacement.None,
+                true);
+        }
+
+        /// <summary>
+        ///     Registers a <c>card_keywords</c> entry whose id is mod-qualified from <paramref name="localKeywordStem" />.
+        /// </summary>
+        [Obsolete(
+            "Pitfall: locKeyPrefix is NOT a prefix that affects only the modid/namespace portion. It is the full card_keywords entry stem used to form '{stem}.title' and '{stem}.description'. Prefer RegisterCardKeywordOwnedByLocNamespace (default stem: '<modid>_<keyword>').")]
         public ModKeywordDefinition RegisterCardKeywordOwned(
             string localKeywordStem,
             string? locKeyPrefix,
@@ -183,6 +231,8 @@ public ModKeywordDefinition RegisterCardKeywordOwned(
         /// <summary>
         ///     <c>RegisterCardKeywordOwned</c> with legacy hover defaults.
         /// </summary>
+        [Obsolete(
+            "Pitfall: locKeyPrefix is NOT a prefix that affects only the modid/namespace portion. It is the full card_keywords entry stem used to form '{stem}.title' and '{stem}.description'. Prefer RegisterCardKeywordOwnedByLocNamespace (default stem: '<modid>_<keyword>').")]
         public ModKeywordDefinition RegisterCardKeywordOwned(
             string localKeywordStem,
             string? locKeyPrefix = null,
diff --git a/STS2-RitsuLib.csproj b/STS2-RitsuLib.csproj
@@ -11,7 +11,7 @@
         <NoWarn>$(NoWarn);CS0436</NoWarn>
         <IsPackable>true</IsPackable>
         <PackageId>STS2.RitsuLib</PackageId>
-        <Version>0.0.65</Version>
+        <Version>0.0.66</Version>
         <Authors>OLC</Authors>
         <Description>Shared framework library for Slay the Spire 2 mods.</Description>
         <PackageReadmeFile>README.md</PackageReadmeFile>
diff --git a/Scaffolding/Content/ModContentPackBuilder.cs b/Scaffolding/Content/ModContentPackBuilder.cs
diff --git a/Scaffolding/Content/Patches/ContentAssetOverridePatches.cs b/Scaffolding/Content/Patches/ContentAssetOverridePatches.cs
diff --git a/Scaffolding/Content/Patches/ModCharacterOwnedRelicVisualOverrideHelper.cs b/Scaffolding/Content/Patches/ModCharacterOwnedRelicVisualOverrideHelper.cs
diff --git a/mod_manifest.json b/mod_manifest.json
