字段说明测试

.gitea/checker/comparator.py

@@ -35,33 +35,66 @@ class ParameterChange:
     old_description: Optional[str] = None
     source: str = "query"
 
-    def _escape_cell(self, text: str) -> str:
-        """表格单元格转义。"""
-        return text.replace("|", "\\|").replace("\n", " ")
+    def _change_tag(self) -> str:
+        """变更类型标签（企微颜色）。"""
+        tags = {
+            ChangeType.ADDED: '<font color="info">**新增**</font>',
+            ChangeType.REMOVED: '<font color="warning">**删除**</font>',
+            ChangeType.RENAMED: '<font color="comment">**重命名**</font>',
+            ChangeType.MODIFIED: '<font color="warning">**修改**</font>',
+        }
+        return tags.get(self.change_type, "")
+
+    def _required_tag(self) -> str:
+        """必填/可选标签。"""
+        if self.required is True:
+            return '<font color="warning">必填</font>'
+        if self.required is False:
+            return '<font color="comment">可选</font>'
+        return ""
+
+    def to_markdown_block(self, index: int = 1) -> str:
+        """格式化为企微友好的参数变更卡片（列表式，非表格）。"""
+        lines: List[str] = []
+        desc = self.description or self.old_description
 
-    def _change_label(self) -> str:
-        """变更列文案，对齐 model.md。"""
-        if self.change_type == ChangeType.ADDED:
-            if self.required is False:
-                return "新增可选"
-            return "新增必填"
-        if self.change_type == ChangeType.REMOVED:
-            return "删除"
         if self.change_type == ChangeType.RENAMED:
-            return f"重命名 {self.old_name} → {self.param_name}"
-        if self.change_type == ChangeType.MODIFIED:
-            return self.detail or "修改"
-        return "-"
+            lines.append(f"**{index}. `{self.param_name}`**  {self._change_tag()}")
+            lines.append(f"> `{self.old_name}` → `{self.param_name}`")
+            if desc:
+                lines.append(f"> 说明：{desc}")
+            return "\n".join(lines)
+
+        if self.change_type == ChangeType.ADDED:
+            type_part = f" · `{self.param_type}`" if self.param_type else ""
+            req_part = f" · {self._required_tag()}" if self._required_tag() else ""
+            lines.append(
+                f"**{index}. `{self.param_name}`**{type_part}{req_part}  {self._change_tag()}"
+            )
+            if desc:
+                lines.append(f"> 说明：{desc}")
+            return "\n".join(lines)
+
+        if self.change_type == ChangeType.REMOVED:
+            type_part = f" · `{self.param_type}`" if self.param_type else ""
+            lines.append(
+                f"**{index}. `{self.param_name}`**{type_part}  {self._change_tag()}"
+            )
+            if desc:
+                lines.append(f"> 说明：{desc}")
+            return "\n".join(lines)
+
+        # MODIFIED
+        lines.append(f"**{index}. `{self.param_name}`**  {self._change_tag()}")
+        if desc:
+            lines.append(f"> 说明：{desc}")
+        if self.detail:
+            lines.append(f"> 变更：{self.detail}")
+        return "\n".join(lines)
 
     def to_table_row(self) -> str:
-        """格式化为 model.md 参数变更表格行。"""
-        desc = self._escape_cell(self.description or "-")
-        change = self._escape_cell(self._change_label())
-        return f"| `{self.param_name}` | {desc} | {change} |"
-
-    def to_markdown_line(self, *, plain: bool = False) -> str:
-        """兼容旧调用，委托至表格行。"""
-        return self.to_table_row()
+        """兼容旧调用，委托至卡片块。"""
+        return self.to_markdown_block(1)
 
 
 @dataclass