feat(pkuxkx): 为〔HP摘要〕撰写文档并允许手动调用

mud/pkuxkx/plugins/basic/char/hp.tin

@@ -339,16 +339,69 @@ hp -neili 格式：
     #line gag;
 } {2.0};
 
-#nop char.HPSummarize.Echo 有三种选择: 从不、自动、总是
+///=== {
+// ## char.HPSummarize [<总是|自动>]
+//    显示〔HP摘要〕提示条。
+//
+//    注意 HP 摘要提示条并不一定总是会显示，实际上会受到变量 char.HPSummarize.Echo 的控制。
+//    char.HPSummarize.Echo 可以在 ui-settings.tin 配置中进行修改，它有三种选择: 从不、自动、总是。
+//      - 从不: 无论如何都不会显示 HP 摘要。
+//      - 总是: 只要有 GMCP.Status 事件则必然显示。
+//      - 自动: 只有 #var gmcp-name-map[HP主要] 里的数值发生变化时才会显示。
+//
+//    可选的参数用来说明要进行何种程度的显示。
+//      - 总是: 只有 char.HPSummarize.Echo 设置为「总是」时，才会显示。
+//      - 自动: 不论 char.HPSummarize.Echo 设置为「总是」还是「自动」，都会显示。
+//      - 如果省略该参数，则不论 char.HPSummarize.Echo 如何设置，都会显示。
+//
+//    HP 摘要被设计成了响应式布局的，它会根据屏幕的宽度，自动隐藏相对次要的数据，确保最终显示不会折行。
+//
+//    下面是 HP 摘要的全部字段说明：
+//      - HP摘要: HP摘要是个固定的头部，但整个HP摘要条的颜色会根据 ID 的当前状态有不同的表示，并可通过 char.HPSummarize.Theme 进行定制：
+//          - 平常（不忙）: 显示样式：$char.HPSummarize.Theme[背景][平常]$char.HPSummarize.Theme[前景][平常]〔HP摘要〕<299>
+//          - 忙（非战斗）: 显示样式：$char.HPSummarize.Theme[背景][正忙]$char.HPSummarize.Theme[前景][正忙]〔HP摘要〕<299>
+//          - 忙（战斗中）: 显示样式：$char.HPSummarize.Theme[背景][战忙]$char.HPSummarize.Theme[前景][战忙]〔HP摘要〕<299>
+//          - 战斗（一般）: 显示样式：$char.HPSummarize.Theme[背景][战斗]$char.HPSummarize.Theme[前景][战斗]〔HP摘要〕<299>
+//          - 战斗（安全）: 显示样式：$char.HPSummarize.Theme[背景][战安]$char.HPSummarize.Theme[前景][战安]〔HP摘要〕<299>
+//          - 战斗（危险）: 显示样式：$char.HPSummarize.Theme[背景][战危]$char.HPSummarize.Theme[前景][战危]〔HP摘要〕<299>
+//          - 战斗（危急）: 显示样式：$char.HPSummarize.Theme[背景][危急]$char.HPSummarize.Theme[前景][危急]〔HP摘要〕<299>
+//          - 其中战斗状态下的「安全」、「危险」、「危急」的判断标准分别为
+//              - 安全: 气血百分比 > 80% 并且精神百分比 > 95%
+//              - 危险: 气血百分比 < 30% 或者精神百分比 < 70%
+//              - 危急: 危险并且被 busy
+//      - 气血: 由三个数组成，显示样式为：气血百分比(每秒气血变化)/气血健康度
+//          - 气血百分比: 展示为当前气血占最大气血的比例，注意这里并没有采用有效气血。
+//          - 每秒气血变化: 正数展示为绿色，负数展示为红色，如果没有变化，则自动隐藏。
+//          - 气血健康度: 展示为有效气血占最大气血的比例。
+//      - 内力: 由两个数组成，显示样式为：内力百分比(每秒内力变化)
+//          - 内力百分比: 以最大内力的两倍为百分之百展示。
+//          - 每秒内力变化: 正数展示为绿色，负数展示为红色，如果没有变化，则自动隐藏。
+//      - 回气: 由两个数组成，显示样式为为：气血恢复/气血治疗
+//          - 气血恢复: 展示为每分钟可以恢复的最大血量的比例（以百分比形式）
+//          - 气血治疗: 展示为每分钟可以治疗的最大血量的比例（以百分比形式）
+//      - 精神: 由三个数组成，显示样式为为：精神百分比(每秒精神变化)/精神健康度
+//          - 精神百分比: 展示为当前精神占最大精神的比例，注意这里并没有采用有效精神。
+//          - 每秒精神变化: 正数展示为绿色，负数展示为红色，如果没有变化，则自动隐藏。
+//          - 精神健康度: 展示为有效精神占最大精神的比例。
+//      - 精力: 由两个数组成，显示样式为：精力百分比(每秒精力变化)
+//          - 精力百分比: 以最大精力的两倍为百分之百展示。
+//          - 每秒精力变化: 正数展示为绿色，负数展示为红色，如果没有变化，则自动隐藏。
+//      - 食水: 由四个数组成，显示样式为：当前食物/当前饮水(每分钟食物变化/每分钟饮水变化)
+//      - 战斗标志: 如果角色处于战斗状态，则显示「战」。
+//      - 气势: 如果在战斗中捕获到气势数据，则会在「战」标志后，展示当前气势。
+//      - 安危标志: 战斗状态下，会自动根据 ID 状态，显示「安」或「危」标志。
+//      - 忙标志: 如果角色处于忙状态，则显示「忙」。
+// };
 #alias {char.HPSummarize} {
-    #local level {%1};
-
-    #if { "$char.HPSummarize.Echo" == "从不" } {
-        #return;
-    };
+    #local level {@default{%1;强制}};
 
-    #if { "$char.HPSummarize.Echo" == "自动" && "$level" != "自动" } {
-        #return;
+    #if { "$level" != "强制" } {
+        #if { "$char.HPSummarize.Echo" == "从不" } {
+            #return;
+        };
+        #if { "$char.HPSummarize.Echo" == "自动" && "$level" != "自动" } {
+            #return;
+        };
     };
 
     #local head     {};