npm - @birthday8/doc-mcp - Versions diffs - 1.0.2 → 1.0.3 - Mend

@birthday8/doc-mcp 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +2 -2
package/index.js +61 -56
package/install.js +45 -35
package/package.json +1 -1
package/python/docx_converter.py +15 -83
package/python/html_rules.py +570 -0
package/python/html_validator.py +59 -274
package/python/html_validator_strict.py +428 -0
package/python/sample/html_schema.py +283 -0
package/python/server.py +112 -75
package/python/test_strict_validation.py +118 -0

package/python/html_validator_strict.py ADDED Viewed

@@ -0,0 +1,428 @@
+"""
+严格HTML验证器
+基于规则引擎的严格验证，提供结构化JSON输出
+"""
+from bs4 import BeautifulSoup, Tag, NavigableString
+from typing import Dict, List, Set, Optional, Any
+from html_rules import RuleEngine, ValidationResult
+class StrictHTMLValidator:
+    """严格HTML验证器"""
+    def __init__(self, rule_engine: RuleEngine = None):
+        self.rule_engine = rule_engine or RuleEngine()
+    def validate(self, html_content: str, strict_mode: bool = True) -> ValidationResult:
+        """
+        验证HTML内容
+        Args:
+            html_content: HTML内容
+            strict_mode: 严格模式，True时遇到错误立即返回，False时收集所有错误
+        Returns:
+            ValidationResult: 验证结果
+        """
+        result = ValidationResult(is_valid=True)
+        try:
+            soup = BeautifulSoup(html_content, "html.parser")
+            # 检查基本结构
+            self._validate_structure(soup, result, strict_mode)
+            # 检查标签
+            self._validate_tags(soup, result, strict_mode)
+            # 检查属性
+            self._validate_attributes(soup, result, strict_mode)
+            # 检查样式
+            self._validate_styles(soup, result, strict_mode)
+            # 检查嵌套
+            self._validate_nesting(soup, result, strict_mode)
+            # 检查自闭合标签
+            self._validate_self_closing(soup, result, strict_mode)
+            # 收集统计信息
+            self._collect_stats(soup, result)
+        except Exception as e:
+            result.add_error(
+                code="PARSE_ERROR",
+                message=f"HTML解析错误: {str(e)}",
+                details={"error": str(e)},
+            )
+        return result
+    def _validate_structure(
+        self, soup: BeautifulSoup, result: ValidationResult, strict_mode: bool
+    ):
+        """验证HTML基本结构"""
+        html_tag = soup.find("html")
+        if not html_tag:
+            result.add_error(
+                code="MISSING_HTML_TAG",
+                message="缺少 <html> 根标签",
+                details={"tag": "html"},
+            )
+            if strict_mode:
+                return
+        head_tag = soup.find("head")
+        if not head_tag:
+            result.add_warning(code="MISSING_HEAD_TAG", message="缺少 <head> 标签")
+        body_tag = soup.find("body")
+        if not body_tag:
+            result.add_error(
+                code="MISSING_BODY_TAG",
+                message="缺少 <body> 标签",
+                details={"tag": "body"},
+            )
+            if strict_mode:
+                return
+        # 检查编码
+        charset = soup.find("meta", {"charset": True})
+        if not charset or charset.get("charset") != "UTF-8":
+            result.add_warning(
+                code="CHARSET_WARNING",
+                message="建议使用 UTF-8 编码",
+                details={"current": charset.get("charset") if charset else "None"},
+            )
+        # 检查语言
+        if html_tag and html_tag.get("lang") != "zh-CN":
+            result.add_warning(
+                code="LANG_WARNING",
+                message="建议设置 lang='zh-CN'",
+                details={"current": html_tag.get("lang", "None")},
+            )
+    def _validate_tags(
+        self, soup: BeautifulSoup, result: ValidationResult, strict_mode: bool
+    ):
+        """验证标签"""
+        for element in soup.find_all(True):
+            if not isinstance(element, Tag):
+                continue
+            tag_name = element.name
+            # 检查标签是否允许
+            if not self.rule_engine.is_tag_allowed(tag_name):
+                result.add_error(
+                    code="DISALLOWED_TAG",
+                    message=f"标签 <{tag_name}> 不在允许列表中",
+                    details={
+                        "tag": tag_name,
+                        "position": str(element)[:100],
+                        "allowed_tags": list(self.rule_engine.tag_rules.keys()),
+                    },
+                )
+                if strict_mode:
+                    continue
+            # 检查必需属性
+            tag_rule = self.rule_engine.get_tag_rule(tag_name)
+            if tag_rule and tag_rule.required_attrs:
+                for required_attr in tag_rule.required_attrs:
+                    if required_attr not in element.attrs:
+                        result.add_error(
+                            code="MISSING_REQUIRED_ATTR",
+                            message=f"标签 <{tag_name}> 缺少必需属性 '{required_attr}'",
+                            details={
+                                "tag": tag_name,
+                                "missing_attr": required_attr,
+                                "required_attrs": list(tag_rule.required_attrs),
+                            },
+                        )
+    def _validate_attributes(
+        self, soup: BeautifulSoup, result: ValidationResult, strict_mode: bool
+    ):
+        """验证属性"""
+        for element in soup.find_all(True):
+            if not isinstance(element, Tag):
+                continue
+            tag_name = element.name
+            for attr_name, attr_value in element.attrs.items():
+                # 跳过特殊属性
+                if attr_name in ["class", "style"]:
+                    continue
+                # 检查属性是否允许
+                if not self.rule_engine.is_attribute_allowed(attr_name, tag_name):
+                    result.add_error(
+                        code="DISALLOWED_ATTR",
+                        message=f"标签 <{tag_name}> 的属性 '{attr_name}' 不在允许列表中",
+                        details={
+                            "tag": tag_name,
+                            "attr": attr_name,
+                            "value": str(attr_value)[:100],
+                            "allowed_attrs_for_tag": self._get_allowed_attrs_for_tag(
+                                tag_name
+                            ),
+                        },
+                    )
+                    if strict_mode:
+                        continue
+                # 验证属性值
+                attr_rule = self.rule_engine.get_attribute_rule(attr_name)
+                if attr_rule and attr_rule.validator and attr_value:
+                    if not attr_rule.validator(str(attr_value)):
+                        result.add_error(
+                            code="INVALID_ATTR_VALUE",
+                            message=f"标签 <{tag_name}> 的属性 '{attr_name}' 值 '{attr_value}' 无效",
+                            details={
+                                "tag": tag_name,
+                                "attr": attr_name,
+                                "value": str(attr_value),
+                            },
+                        )
+    def _validate_styles(
+        self, soup: BeautifulSoup, result: ValidationResult, strict_mode: bool
+    ):
+        """验证样式"""
+        for element in soup.find_all(style=True):
+            if not isinstance(element, Tag):
+                continue
+            tag_name = element.name
+            style_str = element.get("style", "")
+            styles = self._parse_style(style_str)
+            for style_name, style_value in styles.items():
+                # 检查样式是否允许
+                if not self.rule_engine.is_style_allowed(style_name, tag_name):
+                    result.add_error(
+                        code="DISALLOWED_STYLE",
+                        message=f"标签 <{tag_name}> 的样式 '{style_name}' 不在允许列表中",
+                        details={
+                            "tag": tag_name,
+                            "style": style_name,
+                            "value": style_value,
+                            "allowed_styles_for_tag": self._get_allowed_styles_for_tag(
+                                tag_name
+                            ),
+                        },
+                    )
+                    if strict_mode:
+                        continue
+                # 验证样式值
+                style_rule = self.rule_engine.get_style_rule(style_name)
+                if style_rule and style_value:
+                    is_valid, error_msg = style_rule.validate_value(style_value)
+                    if not is_valid:
+                        result.add_error(
+                            code="INVALID_STYLE_VALUE",
+                            message=f"标签 <{tag_name}> 的样式 '{style_name}' 值 '{style_value}' 无效: {error_msg}",
+                            details={
+                                "tag": tag_name,
+                                "style": style_name,
+                                "value": style_value,
+                                "error": error_msg,
+                            },
+                        )
+    def _validate_nesting(
+        self, soup: BeautifulSoup, result: ValidationResult, strict_mode: bool
+    ):
+        """验证嵌套规则"""
+        for element in soup.find_all(True):
+            if not isinstance(element, Tag):
+                continue
+            tag_name = element.name
+            parent = element.parent
+            if parent and isinstance(parent, Tag):
+                parent_name = parent.name
+                # 检查是否可以是父元素的子元素
+                tag_rule = self.rule_engine.get_tag_rule(tag_name)
+                parent_rule = self.rule_engine.get_tag_rule(parent_name)
+                if tag_rule and not tag_rule.can_be_child_of(parent_name):
+                    result.add_error(
+                        code="INVALID_NESTING",
+                        message=f"标签 <{tag_name}> 不能作为 <{parent_name}> 的子元素",
+                        details={
+                            "child_tag": tag_name,
+                            "parent_tag": parent_name,
+                            "allowed_parents": (
+                                list(tag_rule.allowed_parents)
+                                if tag_rule.allowed_parents
+                                else ["任意"]
+                            ),
+                        },
+                    )
+                    if strict_mode:
+                        continue
+                # 检查父元素是否可以包含此元素
+                if parent_rule and not parent_rule.can_contain(tag_name):
+                    result.add_error(
+                        code="INVALID_CONTAINMENT",
+                        message=f"标签 <{parent_name}> 不能包含 <{tag_name}>",
+                        details={
+                            "parent_tag": parent_name,
+                            "child_tag": tag_name,
+                            "allowed_children": (
+                                list(parent_rule.allowed_children)
+                                if parent_rule.allowed_children
+                                else ["任意"]
+                            ),
+                        },
+                    )
+    def _validate_self_closing(
+        self, soup: BeautifulSoup, result: ValidationResult, strict_mode: bool
+    ):
+        """验证自闭合标签"""
+        for element in soup.find_all(True):
+            if not isinstance(element, Tag):
+                continue
+            tag_name = element.name
+            tag_rule = self.rule_engine.get_tag_rule(tag_name)
+            if tag_rule and tag_rule.must_be_self_closing:
+                # 检查是否有内容
+                if element.contents and not all(
+                    isinstance(c, NavigableString) and not c.strip()
+                    for c in element.contents
+                ):
+                    result.add_warning(
+                        code="SELF_CLOSING_WARNING",
+                        message=f"标签 <{tag_name}> 应该是自闭合标签，但包含内容",
+                        details={"tag": tag_name, "content": str(element)[:100]},
+                    )
+    def _collect_stats(self, soup: BeautifulSoup, result: ValidationResult):
+        """收集统计信息"""
+        stats = {}
+        # 标签统计
+        tag_counts = {}
+        for element in soup.find_all(True):
+            if isinstance(element, Tag):
+                tag_counts[element.name] = tag_counts.get(element.name, 0) + 1
+        stats["tag_counts"] = tag_counts
+        stats["total_tags"] = sum(tag_counts.values())
+        stats["text_length"] = len(soup.get_text())
+        stats["total_errors"] = len(result.errors)
+        stats["total_warnings"] = len(result.warnings)
+        # 添加到结果中
+        result.details = stats
+    def _parse_style(self, style_str: str) -> Dict[str, str]:
+        """解析样式字符串"""
+        styles = {}
+        for item in style_str.split(";"):
+            if ":" in item:
+                key, value = item.split(":", 1)
+                styles[key.strip()] = value.strip()
+        return styles
+    def _get_allowed_attrs_for_tag(self, tag_name: str) -> List[str]:
+        """获取标签允许的属性列表"""
+        allowed = []
+        for attr_name, attr_rule in self.rule_engine.attr_rules.items():
+            if attr_rule.allowed and attr_rule.is_applicable_to(tag_name):
+                allowed.append(attr_name)
+        return allowed
+    def _get_allowed_styles_for_tag(self, tag_name: str) -> List[str]:
+        """获取标签允许的样式列表"""
+        allowed = []
+        for style_name, style_rule in self.rule_engine.style_rules.items():
+            if style_rule.allowed and style_rule.is_applicable_to(tag_name):
+                allowed.append(style_name)
+        return allowed
+    def get_validation_report(self, result: ValidationResult) -> str:
+        """生成验证报告"""
+        report = []
+        report.append("=== HTML 验证报告 ===\n")
+        # 验证结果
+        status = "✅ 通过" if result.is_valid else "❌ 失败"
+        report.append(f"验证状态: {status}")
+        report.append(f"错误数: {len(result.errors)}")
+        report.append(f"警告数: {len(result.warnings)}\n")
+        # 错误
+        if result.errors:
+            report.append("❌ 错误:")
+            for i, error in enumerate(result.errors, 1):
+                report.append(f"\n{i}. [{error['code']}] {error['message']}")
+                if error.get("details"):
+                    report.append(f"   详情: {error['details']}")
+            report.append("")
+        # 警告
+        if result.warnings:
+            report.append("⚠️  警告:")
+            for i, warning in enumerate(result.warnings, 1):
+                report.append(f"\n{i}. [{warning['code']}] {warning['message']}")
+                if warning.get("details"):
+                    report.append(f"   详情: {warning['details']}")
+            report.append("")
+        # 统计信息
+        if hasattr(result, "details") and result.details:
+            report.append("📊 统计信息:")
+            for key, value in result.details.items():
+                report.append(f"  - {key}: {value}")
+            report.append("")
+        if not result.errors and not result.warnings:
+            report.append("🎉 完美！没有发现任何问题。")
+        return "\n".join(report)
+class ValidationError(Exception):
+    """验证错误异常"""
+    def __init__(self, result: ValidationResult):
+        self.result = result
+        message = (
+            f"HTML验证失败: {len(result.errors)} 个错误, {len(result.warnings)} 个警告"
+        )
+        super().__init__(message)
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典"""
+        return self.result.to_json()
+# 延迟创建全局实例
+_strict_validator_instance = None
+def get_strict_validator():
+    """获取严格验证器单例"""
+    global _strict_validator_instance
+    if _strict_validator_instance is None:
+        _strict_validator_instance = StrictHTMLValidator()
+    return _strict_validator_instance
+# 向后兼容的全局实例
+strict_validator = get_strict_validator()