from __future__ import annotations

import importlib.util
import json
import sys
import tempfile
import unittest
from contextlib import redirect_stdout
from io import StringIO
from pathlib import Path
from unittest.mock import patch


SCRIPT = Path(__file__).resolve().parents[1] / 'scripts' / 'validate_links.py'
SPEC = importlib.util.spec_from_file_location('validate_links', SCRIPT)
assert SPEC and SPEC.loader
MODULE = importlib.util.module_from_spec(SPEC)
sys.modules[SPEC.name] = MODULE
SPEC.loader.exec_module(MODULE)


class AnchorAndGetFallbackTests(unittest.TestCase):
    def test_relative_document_link_is_checked_as_local_file(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            root = Path(directory)
            (root / "docs").mkdir()
            (root / "docs" / "guide.md").write_text("# Install\n", encoding="utf-8")
            refs = MODULE.extract_references("[guide](docs/guide.md#install)")
            results = MODULE.validate_references(refs, {}, "", root)
            self.assertTrue(results[0]["validation"]["valid"])
    def test_local_anchor_is_validated_against_heading_and_html_id(self) -> None:
        content = '# 使用方法\n\n<a id="custom-anchor"></a>\n[标题](#使用方法) [显式](#custom-anchor) [缺失](#missing)'
        refs = MODULE.extract_references(content)
        results = MODULE.validate_references(refs, {}, content)
        self.assertEqual([item['validation']['valid'] for item in results], [True, True, False])
        self.assertTrue(all(item['validation'].get('local_anchor') for item in results))

    def test_head_405_falls_back_to_limited_get(self) -> None:
        with patch.object(MODULE.subprocess, 'check_output', side_effect=['405\nhttps://example.test', '200\nhttps://example.test']) as call:
            result = MODULE.validate_url('https://example.test')
        self.assertTrue(result['valid'])
        self.assertEqual(result['status_code'], 200)
        self.assertEqual(call.call_count, 2)
        self.assertIn('-I', call.call_args_list[0].args[0])
        self.assertIn('--range', call.call_args_list[1].args[0])

    def test_runtime_events_use_kernel_command(self) -> None:
        from bensz_skill_kernel import EventLog

        with tempfile.TemporaryDirectory() as directory:
            events = Path(directory) / 'events.ndjson'
            result = MODULE.record_runtime_events(
                str(events),
                [{'verifier_id': 'bensz.evidence.citation-truth-fit', 'verifier_version': '1.0.0', 'verdict': 'unchecked', 'execution_status': 'unchecked', 'evidence_refs': ['subject_context']}],
                {'decision': 'manual_review', 'reason': 'verification gap or semantic uncertainty'},
                'run-test',
            )
            self.assertTrue(result['recorded'])
            projection = EventLog(events).projection()
            self.assertEqual(projection['verifications'][0]['request_id'], 'run-test')
            self.assertEqual(projection['gate_decisions'][0]['decision'], 'wait')
            self.assertEqual(projection['gate_decisions'][0]['computed_by'], 'kernel')

    def test_skill_state_declaration_uses_indexed_state_pack(self) -> None:
        from bensz_skill_kernel import SkillStateDeclaration

        skill_root = SCRIPT.parents[1]
        declaration = SkillStateDeclaration.from_skill_root(skill_root)
        self.assertEqual(declaration.source.name, 'config.yaml')
        self.assertEqual(
            {item.id for item in declaration.registry().definitions(kind='skill')},
            {
                'bensz.validate-md-ref.input-ready',
                'bensz.validate-md-ref.checking',
                'bensz.validate-md-ref.reported',
            },
        )
        self.assertEqual(
            declaration.registry().resolve('validate-md-ref.input-ready').id,
            'bensz.validate-md-ref.input-ready',
        )

    def test_cli_uses_kernel_facts_instead_of_legacy_network_adapter(self) -> None:
        with tempfile.TemporaryDirectory() as directory:
            document = Path(directory) / 'README.md'
            document.write_text('# Guide\n\n[local](#guide)\n', encoding='utf-8')
            output = StringIO()
            with patch.object(MODULE, 'validate_references', side_effect=AssertionError('legacy adapter called')):
                with redirect_stdout(output):
                    self.assertEqual(MODULE.main([str(document)]), 0)
            payload = json.loads(output.getvalue())
            self.assertEqual(payload['summary']['total'], 1)
            self.assertTrue(payload['references'][0]['validation']['valid'])
            self.assertEqual(payload['verification']['results'][0]['facts']['summary'], payload['summary'])

    def test_generate_summary_keeps_network_unknown_separate_from_invalid(self) -> None:
        results = [
            {'validation': {'valid': True, 'validation_status': 'valid'}},
            {'validation': {'valid': False, 'validation_status': 'unresolved'}},
            {'validation': {'valid': False, 'validation_status': 'timed_out'}},
            {'validation': {'valid': False, 'validation_status': 'invalid'}},
            {'validation': {'valid': False, 'validation_status': 'skipped', 'skipped': True}},
        ]

        summary = MODULE.generate_summary(results)

        self.assertEqual(summary['valid'], 1)
        self.assertEqual(summary['invalid'], 1)
        self.assertEqual(summary['unresolved'], 2)
        self.assertEqual(summary['timed_out'], 1)
        self.assertEqual(summary['skipped'], 1)


if __name__ == '__main__':
    unittest.main()

# 引用真实性与适切性契约

`bensz.evidence.citation-truth-fit` 是格式无关的语义验证能力，不负责解析 Markdown、LaTeX、Word 或其它载体。各格式适配器先把引用归一化，再提交以下证据：

- `subject_context`：被引用支持的目标论断、必要上下文和引用位置。
- `source_metadata`：来源标题、作者、发布日期、标识符及可追溯位置。
- `source_excerpt`：与目标论断直接相关的来源摘录；只有 URL 或书目信息不够。

验证结果分别回答：

- `evidence.identity`：来源身份与元数据能否被可靠确认。
- `semantic.entailment`：来源证据是否支持目标论断，还是仅与主题相关。
- `semantic.appropriateness`：引用位置、表述强度、时效性和来源类型是否恰当。

缺少必需证据、来源无法获取、判断引擎不可用或证据存在冲突时，返回 `unchecked`、`uncertain` 或 `manual_review`，不得因为链接可访问就判定通过。

当前 `validate-md-ref` 提供 Markdown 输入适配，并调用该通用 Pack。其它格式适配器也应提交同样的三类证据；kernel 只负责版本、证据引用、结果格式和 Gate 语义。

# 输入与输出

## 输入

目标是一个 Markdown 文件。工具会识别常见 Markdown 行内链接、HTML `<a href>` 链接和 `#anchor` 站内锚点。

站内锚点在当前文档中检查；HTTP(S) 链接进行网络可达性检查。输入文件按只读处理。

## 输出

结果为 JSON，常用字段：

- `summary.total`、`summary.valid`、`summary.invalid`、`summary.unresolved`、`summary.skipped`
- `references[*].validation.validation_status`：`valid`、`invalid`、`unresolved`、`timed_out` 或 `skipped`；网络不可观测不等同于链接失效。
- `references[*].url`、`references[*].line_number`、`references[*].validation`
- `verification`（直接命令也提供顶层 `results` 和 `gate`）
- `verification.metrics`：Kernel 汇总的 Verifier 覆盖率、未知/不确定比例、Gate 放行率、assurance tier 与耗时指标。
- `verification.requirements`：运行时声明的 required/advisory Verifier 及版本；Gate 仅对 required 的确定性失败拒绝。
- `verification.runtime`：本次运行使用的 Kernel 名称/版本/来源与规范化 Pack 版本；同一元数据会随事件结果记录，便于审计环境漂移。

可达性通过不代表网页内容支持正文论断；被安全策略跳过的地址也不等于链接失效。

本 Skill 将 Markdown 事实适配到格式无关的 `bensz.evidence.citation-truth-fit` 契约；不要从 URL `valid: true` 推导语义结论。

# 状态机契约

状态机是本 Skill 的强制运行治理层，不替代 Markdown 检查流程。每次执行都必须通过 kernel 命令读取契约、执行合法转移并保存元状态快照；不得自行猜测状态含义、伪造快照或跳过状态机。

## 状态包

Skill 根目录的 [`config.yaml`](../config.yaml) 的 `runtime` 节声明状态根和状态列表。旧版
[`state-machine.json`](../state-machine.json) 仅作为兼容读取入口。`bensz.workspace.ready` 是强制初始状态，Skill 阶段按顺序为：
同一节的 `kernel.name/version` 固定本 Skill 运行所需的 Kernel；事件记录发现版本不匹配时必须失败，不能静默使用 PATH 中的旧 `bsk`。

`references/states/index.json` 是当前状态包的目录清单，采用 kernel 的
`bensz-pack-index-v1` 协议；它集中声明 canonical ID、版本、alias 和入口脚本，
`STATE.md` 保留状态契约正文。没有索引的旧目录仍由 kernel 兼容读取。

`bensz.validate-md-ref.input-ready` → `bensz.validate-md-ref.checking` → `bensz.validate-md-ref.reported`

各状态的入口条件、不变量和允许转移分别记录在 [`input-ready`](states/input-ready/STATE.md)、[`checking`](states/checking/STATE.md) 和 [`reported`](states/reported/STATE.md) 的 `STATE.md` 中。`input-ready` 只接受现有且可读的 Markdown 文件；`checking` 要求保留规范化验证结果；`reported` 要求向用户披露不确定性并保持原文档不变。

其中 `checking` 的 `verifier-result-recorded` 是 Kernel 可执行的不变量：离开该状态前，任务级 `events.ndjson` 必须同时存在同一 `run_id/attempt_id` 下的 `verification.result` 和 `verification.gate`；运行身份必须成对提供，禁止只传其中一个，且 Gate 的 `result_refs` 还必须覆盖该运行的全部结果。该检查只证明结果已记录，不代表 Gate 一定放行。其余自然语言不变量仍由本 Skill 的 helper 或人工复核负责。

## 必经 Kernel 操作

```bash
bsk workspace status TASK_ROOT
bsk state list --skill-root SKILL_ROOT
bsk state describe bensz.validate-md-ref.input-ready --skill-root SKILL_ROOT
bsk state transition TASK_ROOT validate-md-ref bensz.validate-md-ref.input-ready \
  --skill-root SKILL_ROOT --context-json '{"document":"DOCUMENT.md"}'
bsk state transition TASK_ROOT validate-md-ref bensz.validate-md-ref.checking \
  --skill-root SKILL_ROOT --context-json '{"document":"DOCUMENT.md"}'
bsk state transition TASK_ROOT validate-md-ref bensz.validate-md-ref.reported \
  --skill-root SKILL_ROOT --context-json '{"document":"DOCUMENT.md"}'
```

按 `input-ready`、`checking`、`reported` 顺序执行。每次转移成功后检查返回的标准 `bensz-meta-state-v1` JSON；状态快照写入任务工作区中 Skill 的 `log/meta-state.json`。任一转移失败即停止，不得把源 Markdown 复制进工作区，也不得在状态转移中写回原文档。
成功转移还会追加带 `state_domain: skill`、前后 canonical 状态、运行身份和快照哈希的 `state.transition` 事件；可用 `bsk rebuild` 从事件账本重放 `skill_states`，快照仅作缓存。

# 工具包与命令

## 脚本

```bash
python3 scripts/validate_links.py DOCUMENT.md [CONFIG.yaml]
```

脚本负责加载配置并调用公共检查工具。默认配置来自 Skill 目录的 `config.yaml`。

## 直接命令

Verifier 的命令、版本和结果边界集中记录在 [`verifiers.md`](verifiers.md)。直接调用时需要自行传入配置参数，例如 `--timeout 10`、重复的 `--blacklist DOMAIN` 或 `--whitelist DOMAIN`；需要审计时追加 `--events EVENTS.ndjson --run-id RUN_ID`。

脚本写入事件时会将 `run_id` 同时传给 Kernel 事件 Envelope，便于按运行 ID 离线检索审计轨迹。

## 配置

```yaml
validation:
  timeout: 10
domain_whitelist: []
domain_blacklist: []
```

黑名单用于跳过不应访问的域名；白名单非空时只检查其中的域名。默认会避开本地、回环和内部地址。

# Verifier 契约与边界

本 Skill 只负责 Markdown 输入适配和链接事实采集；目录化 Verifier 负责按统一协议执行规则或语义判断。每次执行必须运行链接完整性 Verifier 并保留语义 Verifier 状态；不要在 Skill 侧复制 Verifier 注册表、规则或 Gate 逻辑。

## 可用 Verifier

- `bensz.document.markdown-link-integrity@1.0.0`：检查 Markdown 链接、HTML `href` 和站内锚点的完整性与可达性；旧 ID `markdown.link-integrity`、`markdown.references` 作为 alias。
- `bensz.evidence.citation-truth-fit@1.0.0`：格式无关的引用真实性与适切性 Verifier。它接收适配器提交的论断上下文、来源元数据和来源摘录，不直接解析 Markdown、LaTeX 或 Word；旧 ID `citation.truth-and-fit` 作为 alias。

Markdown 解析、URL 请求和锚点检查产生的是输入事实，不能直接被解释为“来源支持正文论断”的语义结论。

## 强制调用

查看目录与契约：

```bash
bsk verifier describe bensz.document.markdown-link-integrity --version 1.0.0
bsk verifier describe bensz.evidence.citation-truth-fit --version 1.0.0
```

每次运行均须执行链接完整性 Verifier，并向任务事件账本写入标准化结果。推荐由脚本一次完成链接事实与语义状态：

```bash
python3 scripts/validate_links.py DOCUMENT.md config.yaml \
  --events TASK_ROOT/log/events.ndjson --run-id RUN_ID
```

脚本会用同一请求执行 `bensz.document.markdown-link-integrity@1.0.0` 与
`bensz.evidence.citation-truth-fit@1.0.0`，并按 Kernel Gate 合并结果。直接调用
`bsk verifier run` 时不会自动读取 Skill 的 `config.yaml`；超时、白名单和黑名单必须
通过 CLI 参数显式传入。任何 Verifier、Gate 或事件写入失败都必须终止本次检查，不得降级为仅脚本或手工检查。

## 结果解释

保留 Verifier 返回的 `verification.results` 与 `verification.gate`。链接事实通常用 `allow` 或 `reject` 表达；缺少语义证据、来源不可获取、判断引擎不可用或证据冲突时，应保留 `unchecked`、`uncertain` 或 `manual_review`，不得为了通过门禁而猜测。

`bensz.evidence.citation-truth-fit` 的证据字段和语义判断详见 [`citation-truth-and-fit.md`](citation-truth-and-fit.md)。
链接完整性 Verifier 将 HTTP 明确错误、本地 anchor 缺失和越界文件标为 `invalid/fail`；DNS、连接失败和超时标为 `unresolved`/`timed_out`，结果为 `unchecked` 或 `timed_out`，交由 Gate 进入人工复核，不把环境不可观测误判为链接失效。

#!/usr/bin/env python3
"""
Markdown 引用验证脚本

功能：
1. 提取 Markdown 文档中的所有 URL 引用
2. 验证 URL 可达性
3. 返回验证结果供 AI 进一步处理
"""

import re
import sys
import json
import argparse
import hashlib
import shutil
from pathlib import Path
from urllib.parse import unquote, urlparse
from typing import List, Dict
import subprocess
import os


def _load_verifier_runtime():
    """Load the repository kernel without requiring an editable install."""
    kernel_src = Path(__file__).resolve().parents[4] / 'packages' / 'bensz-skill-kernel' / 'src'
    if str(kernel_src) not in sys.path:
        sys.path.insert(0, str(kernel_src))
    from bensz_skill_kernel import Evidence, VerificationRequest, FilesystemVerifierRegistry, builtin_verifier_root, normalize_result, apply_gate, summarize_metrics
    return Evidence, VerificationRequest, FilesystemVerifierRegistry, builtin_verifier_root, normalize_result, apply_gate, summarize_metrics


def get_skill_root() -> Path:
    """
    获取技能根目录的绝对路径。

    无论脚本从哪里调用，都能正确定位到技能根目录（包含 SKILL.md 的目录）。

    工作原理：
    1. 首先尝试从 __file__ 定位（脚本自身的绝对路径）
    2. 如果 __file__ 不可用（如某些执行环境），回退到环境变量
    3. 最后回退到当前工作目录下的 .claude/skills/{skill_name}

    Returns:
        技能根目录的绝对路径
    """
    # 方法1：通过 __file__ 定位（最可靠）
    if '__file__' in globals():
        # scripts/validate_links.py -> skills/{skill_name}/
        script_path = Path(__file__).resolve()
        # scripts/validate_links.py -> scripts/ -> {skill_name}/
        skill_root = script_path.parents[1]
        # 验证是否是有效的技能目录（包含 SKILL.md）
        if (skill_root / "SKILL.md").exists():
            return skill_root

    # 方法2：通过环境变量定位（备用方案，支持自定义安装路径）
    env_skill_path = os.environ.get('VALIDATE_MD_REF Skill_PATH')
    if env_skill_path:
        skill_root = Path(env_skill_path).resolve()
        if (skill_root / "SKILL.md").exists():
            return skill_root

    # 方法3：尝试从常见安装路径定位（回退方案）
    # 依次检查：用户级技能目录、项目级技能目录
    possible_paths = [
        Path.home() / ".claude" / "skills" / "validate-md-ref",
        Path.home() / ".codex" / "skills" / "validate-md-ref",
        Path.cwd() / ".claude" / "skills" / "validate-md-ref",
    ]

    for path in possible_paths:
        if (path / "SKILL.md").exists():
            return path.resolve()

    # 方法4：如果都失败了，抛出错误并提供有用的诊断信息
    raise RuntimeError(
        f"无法定位 validate-md-ref 技能根目录。\n"
        f"请确认技能已正确安装到 ~/.claude/skills/ 或 ~/.codex/skills/\n"
        f"当前工作目录: {Path.cwd()}\n"
        f"__file__: {globals().get('__file__', '未定义')}\n"
        f"环境变量 VALIDATE_MD_REF Skill_PATH: {env_skill_path or '未设置'}"
    )


# 预计算技能根目录（模块加载时执行一次）
_skill_root = None


def get_skill_root_cached() -> Path:
    """获取技能根目录（带缓存，避免重复计算）"""
    global _skill_root
    if _skill_root is None:
        _skill_root = get_skill_root()
    return _skill_root


def get_config_path() -> Path:
    """获取默认配置文件的绝对路径"""
    return get_skill_root_cached() / "config.yaml"


def validate_path(file_path: Path, base_dir: Path = None) -> bool:
    """
    验证文件路径是否安全（防止路径遍历攻击）

    注意：对于 URL 验证工具，允许验证任意可访问的文件，
    只需确保路径不包含明显的恶意模式（如 ../.. 逃逸）。

    Args:
        file_path: 用户指定的文件路径
        base_dir: 允许的基目录（默认为当前工作目录，但此处不强制限制）

    Returns:
        True 表示路径安全
    """
    try:
        # 规范化路径
        resolved = file_path.resolve()

        # 检查路径是否包含明显的路径遍历模式
        path_str = str(file_path)
        dangerous_patterns = ['../..', '../../', '..\\..']
        if any(pattern in path_str for pattern in dangerous_patterns):
            return False

        # 检查路径是否尝试访问系统敏感目录
        resolved_str = str(resolved)
        sensitive_paths = ['/etc/', '/sys/', '/proc/', 'C:\\Windows\\System32']
        if any(resolved_str.startswith(sensitive) for sensitive in sensitive_paths):
            return False

        # 确保文件存在
        if not resolved.exists():
            return False

        return True
    except Exception:
        return False


def _curl_probe(url: str, timeout: int, method: str) -> tuple[int, str]:
    cmd = ['curl', '-s', '-L', '-o', os.devnull, '-w', '%{http_code}\n%{url_effective}']
    if method == 'HEAD':
        cmd.append('-I')
    else:
        cmd.extend(['--range', '0-0'])
    cmd.extend(['--', url])
    output = subprocess.check_output(
        cmd,
        stderr=subprocess.DEVNULL,
        text=True,
        timeout=timeout,
    ).strip().split('\n')
    if not output or not output[0].isdigit():
        raise ValueError(f"无法解析 curl 响应: {output}")
    return int(output[0]), output[1] if len(output) > 1 and output[1] else url


def validate_url(url: str, timeout: int = 10) -> Dict[str, any]:
    """
    验证单个 URL 的可达性

    Args:
        url: 要验证的 URL
        timeout: 超时时间（秒）

    Returns:
        包含验证结果的字典：
        {
            'url': str,
            'valid': bool,
            'status_code': int,
            'redirected': bool,
            'final_url': str,
            'error': str
        }
    """
    result = {
        'url': url,
        'valid': False,
        'status_code': None,
        'redirected': False,
        'final_url': url,
        'error': None
    }

    # 安全验证：确保 URL 格式合法，不包含 curl 选项
    try:
        parsed = urlparse(url)
        if not parsed.scheme or not parsed.netloc:
            result['error'] = 'URL 格式非法'
            return result
        if parsed.scheme not in ['http', 'https']:
            result['error'] = '不支持的协议'
            return result
        # 检查 URL 是否包含可疑的 curl 选项特征
        if '--' in url or url.startswith('-'):
            result['error'] = 'URL 包含非法字符'
            return result
    except Exception as e:
        result['error'] = f'URL 解析失败: {e}'
        return result

    try:
        status_code, final_url = _curl_probe(url, timeout, 'HEAD')
        if status_code in (403, 405):
            status_code, final_url = _curl_probe(url, timeout, 'GET')
        result['status_code'] = status_code
        result['final_url'] = final_url
        result['redirected'] = final_url != url
        if 200 <= status_code < 400:
            result['valid'] = True
        else:
            result['error'] = f"HTTP {status_code}"

    except subprocess.CalledProcessError as e:
        result['error'] = f"执行失败: {e}"
    except subprocess.TimeoutExpired:
        result['error'] = f"超时（>{timeout}秒）"
    except Exception as e:
        result['error'] = str(e)

    return result


def _markdown_anchor_ids(content: str) -> set[str]:
    anchors = set()
    for match in re.finditer(r'<(?:a|span|div)\b[^>]*(?:id|name)=["\']([^"\']+)["\']', content, re.IGNORECASE):
        anchors.add(match.group(1))
    seen_headings: Dict[str, int] = {}
    for line in content.splitlines():
        match = re.match(r'^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$', line)
        if not match:
            continue
        heading = re.sub(r'<[^>]+>', '', match.group(1)).strip().lower()
        slug = re.sub(r'[^\w\- ]', '', heading, flags=re.UNICODE)
        slug = re.sub(r'[\s\-]+', '-', slug).strip('-')
        if not slug:
            continue
        count = seen_headings.get(slug, 0)
        anchors.add(slug if count == 0 else f"{slug}-{count}")
        seen_headings[slug] = count + 1
    return anchors


def validate_anchor(url: str, content: str) -> Dict[str, any]:
    anchor = unquote(url[1:])
    valid = anchor in _markdown_anchor_ids(content)
    return {
        'url': url,
        'valid': valid,
        'status_code': None,
        'redirected': False,
        'final_url': url,
        'error': None if valid else f'站内 anchor 不存在: {anchor}',
        'local_anchor': True,
    }


def extract_references(content: str) -> List[Dict[str, any]]:
    """
    从 Markdown 内容中提取引用

    Args:
        content: Markdown 文件内容

    Returns:
        引用列表，每个引用包含：
        {
            'index': int,           # 在文档中的位置
            'type': str,            # 引用类型
            'url': str,             # URL
            'text': str,            # 链接文本或描述
            'line_number': int,     # 行号
            'full_match': str       # 完整匹配的文本
        }
    """
    references = []

    # 引用模式
    patterns = [
        # 标准链接: [文本](URL)
        {
            'name': 'standard_link',
            'pattern': r'\[([^\]]+)\]\(([^)]+)\)'
        },
        # HTML <a> 标签: <a href="URL">文本</a> 或 <a href='URL'>文本</a>
        {
            'name': 'html_tag',
            'pattern': r'<a\s+href=(["\'])([^"\']+)\1[^>]*>(.*?)</a>'
        },
        # 参考文献样式: [编号]: URL "描述"
        {
            'name': 'bibliography',
            'pattern': r'^\[(\d+)\]:\s*(\S+)\s*"?(.*?)"?$'
        },
        # 脚注样式: [^编号]: URL "描述"
        {
            'name': 'footnote',
            'pattern': r'^\^\[(\d+)\]:\s*(\S+)\s*"?(.*?)"?$'
        }
    ]

    lines = content.split('\n')

    for line_num, line in enumerate(lines, 1):
        for pattern_info in patterns:
            pattern = pattern_info['pattern']
            type_name = pattern_info['name']

            if type_name in ('standard_link', 'html_tag'):
                # 标准链接和 HTML 标签可能一行有多个
                matches = re.finditer(pattern, line, re.IGNORECASE if type_name == 'html_tag' else 0)
                for match in matches:
                    url = match.group(2).strip()
                    text = match.group(1).strip() if type_name == 'standard_link' else match.group(3).strip()
                    references.append({
                        'index': len(references),
                        'type': type_name,
                        'url': url,
                        'text': text,
                        'line_number': line_num,
                        'full_match': match.group(0)
                    })
            else:
                # 参考文献样式每行最多一个
                match = re.match(pattern, line, re.MULTILINE)
                if match:
                    ref_num = match.group(1)
                    url = match.group(2).strip()
                    desc = match.group(3).strip() if len(match.groups()) >= 3 else ''

                    references.append({
                        'index': len(references),
                        'type': type_name,
                        'reference_number': ref_num,
                        'url': url,
                        'text': desc,
                        'line_number': line_num,
                        'full_match': match.group(0)
                    })

    return references


def should_skip_domain(url: str, whitelist: List[str], blacklist: List[str]) -> bool:
    """
    检查 URL 是否应该被跳过（基于域名白名单/黑名单）

    Args:
        url: 要检查的 URL
        whitelist: 域名白名单
        blacklist: 域名黑名单

    Returns:
        True 表示应该跳过验证
    """
    try:
        parsed = urlparse(url)
        domain = parsed.netloc.lower()

        # 检查黑名单
        for blocked in blacklist:
            if blocked.startswith('*.'):
                # 通配符匹配
                suffix = blocked[2:]
                if domain.endswith(suffix):
                    return True
            else:
                if domain == blocked.lower():
                    return True

        # 检查白名单
        if whitelist:
            allowed = False
            for allowed_domain in whitelist:
                if domain == allowed_domain.lower() or domain.endswith('.' + allowed_domain.lower()):
                    allowed = True
                    break
            return not allowed

        return False
    except Exception:
        return False


def validate_references(references: List[Dict], config: Dict, content: str = '', base_dir: Path = None) -> List[Dict]:
    """
    批量验证引用

    Args:
        references: 引用列表
        config: 配置字典

    Returns:
        包含验证结果的引用列表
    """
    results = []

    whitelist = config.get('domain_whitelist', [])
    blacklist = config.get('domain_blacklist', [])
    timeout = config.get('validation', {}).get('timeout', 10)
    base_dir = Path(base_dir or Path.cwd()).expanduser().resolve()

    for ref in references:
        url = ref['url']

        if url.startswith('#'):
            results.append({**ref, 'validation': validate_anchor(url, content)})
            continue

        parsed = urlparse(url)
        if not parsed.scheme and not parsed.netloc:
            relative_path = (base_dir / unquote(parsed.path)).resolve()
            try:
                relative_path.relative_to(base_dir)
                in_scope = True
            except ValueError:
                in_scope = False
            if not in_scope or not relative_path.is_file():
                validation = {'url': url, 'valid': False, 'error': f'相对文件不存在或越界: {parsed.path}'}
            elif parsed.fragment:
                linked_content = relative_path.read_text(encoding='utf-8')
                anchor_result = validate_anchor(f'#{parsed.fragment}', linked_content)
                validation = {**anchor_result, 'url': url}
            else:
                validation = {'url': url, 'valid': True, 'local_file': True, 'error': None}
            results.append({**ref, 'validation': validation})
            continue

        # 检查是否应该跳过
        if should_skip_domain(url, whitelist, blacklist):
            results.append({
                **ref,
                'validation': {
                    'skipped': True,
                    'reason': '域名在黑名单或不在白名单中'
                }
            })
            continue

        # 验证 URL
        validation = validate_url(url, timeout)
        results.append({
            **ref,
            'validation': validation
        })

    return results


def generate_summary(results: List[Dict]) -> Dict:
    """
    生成验证结果摘要

    Args:
        results: 验证结果列表

    Returns:
        摘要统计信息
    """
    total = len(results)
    valid = invalid = unresolved = timed_out = skipped = 0
    for item in results:
        validation = item.get('validation', {})
        status = validation.get('validation_status')
        if status == 'valid' or (status is None and validation.get('valid', False)):
            valid += 1
        elif status == 'invalid' or (status is None and not validation.get('valid', False) and not validation.get('skipped', False)):
            invalid += 1
        elif status in {'unresolved', 'timed_out'}:
            unresolved += 1
            timed_out += status == 'timed_out'
        elif status == 'skipped' or (status is None and validation.get('skipped', False)):
            skipped += 1

    return {
        'total': total,
        'valid': valid,
        'invalid': invalid,
        'unresolved': unresolved,
        'timed_out': timed_out,
        'skipped': skipped,
        'valid_rate': f"{(valid / total * 100):.1f}%" if total > 0 else "0%"
    }


def _kernel_command() -> tuple[list[str], dict[str, str]]:
    """Resolve a version-compatible kernel CLI without silently using stale ``bsk``."""
    script_root = Path(__file__).resolve()
    kernel_src = script_root.parents[4] / 'packages' / 'bensz-skill-kernel' / 'src'
    if kernel_src.is_dir() and (kernel_src / 'bensz_skill_kernel' / '__init__.py').is_file():
        env = os.environ.copy()
        env['PYTHONPATH'] = str(kernel_src) + (os.pathsep + env['PYTHONPATH'] if env.get('PYTHONPATH') else '')
        return [sys.executable, '-m', 'bensz_skill_kernel.cli'], env

    executable = shutil.which('bsk')
    if executable:
        probe = subprocess.run([executable, '--version'], capture_output=True, text=True, check=False)
        expected = None
        try:
            config_text = get_config_path().read_text(encoding='utf-8')
            match = re.search(r'(?ms)^runtime:\s*\n\s+kernel:\s*\n\s+name:\s*[^\n]+\n\s+version:\s*([0-9]+\.[0-9]+\.[0-9]+)\s*$', config_text)
            expected = match.group(1) if match else None
        except (OSError, RuntimeError):
            pass
        actual = probe.stdout.strip().splitlines()[-1].strip() if probe.stdout.strip() else ''
        if probe.returncode == 0 and (expected is None or actual == expected):
            return [executable], os.environ.copy()
        detail = f'kernel CLI version mismatch (expected {expected or "declared"}, got {actual or "unknown"})'
        raise RuntimeError(detail)
    raise RuntimeError('bensz-skill-kernel CLI is unavailable; install a matching bsk or run from the source tree')


def record_runtime_events(events_path: str, results: List[Dict], gate: Dict, request_id: str, attempt_id: str = 'default') -> Dict:
    """Compatibility helper for callers that already have normalized results."""
    command, env = _kernel_command()
    result_payload = [{**item, 'request_id': request_id} for item in results]
    gate_payload = {**gate, 'request_id': request_id}
    args = command + [
        'verification', events_path,
        '--result-json', json.dumps(result_payload, ensure_ascii=False, separators=(',', ':')),
        '--gate-json', json.dumps(gate_payload, ensure_ascii=False, separators=(',', ':')),
        '--scope', 'skill',
        '--actor', 'validate-md-ref',
        '--attempt-id', attempt_id,
        '--idempotency-key', request_id,
        '--run-id', request_id,
    ]
    completed = subprocess.run(args, capture_output=True, text=True, env=env, check=False)
    if completed.returncode != 0:
        detail = completed.stderr.strip() or 'bsk verification failed'
        raise RuntimeError(detail)
    return {'recorded': True, 'events': json.loads(completed.stdout)}


def run_kernel_verifier(args) -> int:
    """Explain that generic citation verification needs normalized evidence."""
    print(json.dumps({
        'error': 'bensz.evidence.citation-truth-fit requires normalized subject_context, source_metadata and source_excerpt evidence; use this Markdown adapter without --kernel mode',
    }, ensure_ascii=False))
    return 2


def main(argv=None):
    """主函数"""
    parser = argparse.ArgumentParser(description='验证 Markdown 引用并输出结构化结果')
    parser.add_argument('markdown_file')
    parser.add_argument('config_file', nargs='?')
    parser.add_argument('--events', help='通过 bsk verifier run 追加到指定 events.ndjson')
    parser.add_argument('--run-id', help='本次验证的稳定运行 ID')
    parser.add_argument('--attempt-id', default='default')
    parser.add_argument('--legacy-local', action='store_true', help=argparse.SUPPRESS)
    args = parser.parse_args(argv)

    if not args.markdown_file:
        print(json.dumps({
            'error': '用法: validate_links.py <markdown_file> [config_file]'
        }))
        return 1

    md_file = Path(args.markdown_file)

    # 路径安全验证（防止路径遍历攻击）
    if not validate_path(md_file):
        print(json.dumps({
            'error': f'路径不安全或超出允许范围: {md_file}'
        }))
        return 1

    if not md_file.exists():
        print(json.dumps({
            'error': f'文件不存在: {md_file}'
        }))
        return 1

    # 读取 Markdown 内容
    content = md_file.read_text(encoding='utf-8')

    # 加载配置（自动使用默认配置或用户指定的配置）
    config = {}
    config_path = None

    if args.config_file:
        # 用户提供了配置文件路径
        config_path = Path(args.config_file)
    else:
        # 自动使用技能默认配置文件
        try:
            config_path = get_config_path()
        except RuntimeError:
            # 无法定位技能根目录时，使用空配置（不影响基本功能）
            config = {}
            config_path = None

    # 只有在配置文件路径存在时才加载
    if config_path:
        try:
            import yaml
        except ImportError:
            print(json.dumps({
                'error': '未安装 yaml 库，请先安装：pip install pyyaml'
            }))
            return 1

        try:
            if not config_path.exists():
                print(json.dumps({
                    'error': f'配置文件不存在: {config_path}'
                }))
                return 1

            with open(config_path, 'r', encoding='utf-8') as f:
                config = yaml.safe_load(f) or {}
        except Exception as e:
            print(json.dumps({
                'error': f'加载配置失败: {e}'
            }))
            return 1

    # The kernel Markdown verifier is the single source of truth for collected
    # references and validation facts.  The legacy ``validate_references``
    # helper remains available for callers that imported it directly, but the
    # command-line entry point must not produce a second (and potentially less
    # secure) network-validation result set.
    output = {'file': str(md_file)}

    # The Markdown parser is an adapter. The verifier itself is format-agnostic
    # and receives normalized claim/source evidence instead of a Markdown file.
    try:
        Evidence, VerificationRequest, FilesystemVerifierRegistry, builtin_verifier_root, normalize_result, apply_gate, summarize_metrics = _load_verifier_runtime()
        runtime_decl = config.get('runtime', {}) if isinstance(config.get('runtime', {}), dict) else {}
        kernel_decl = runtime_decl.get('kernel', {}) if isinstance(runtime_decl.get('kernel', {}), dict) else {}
        if kernel_decl:
            from bensz_skill_kernel import __version__ as running_kernel_version, validate_kernel_runtime_declaration
            validate_kernel_runtime_declaration(kernel_decl, running_version=running_kernel_version)
        content_hash = hashlib.sha256(content.encode('utf-8')).hexdigest()
        request_id = args.run_id or f"markdown:{content_hash[:16]}"
        resolved_md_file = md_file.resolve()
        registry = FilesystemVerifierRegistry(builtin_verifier_root())
        declared = config.get('runtime', {}).get('verifiers', []) if isinstance(config.get('runtime', {}), dict) else []
        from bensz_skill_kernel import normalize_requirements
        requirements = list(normalize_requirements(declared or [
            {'id': 'bensz.document.markdown-link-integrity', 'version': '1.0.0', 'required': True},
            {'id': 'bensz.evidence.citation-truth-fit', 'version': '1.0.0', 'required': False},
        ], registry))
        requirement_by_id = {item['id']: item for item in requirements}
        if 'bensz.document.markdown-link-integrity' not in requirement_by_id:
            raise ValueError('runtime verifier declaration must include bensz.document.markdown-link-integrity')
        link_requirement = requirement_by_id.get('bensz.document.markdown-link-integrity', {'version': '1.0.0'})
        citation_requirement = requirement_by_id.get('bensz.evidence.citation-truth-fit', {'version': '1.0.0'})
        link_result = registry.run(
            'bensz.document.markdown-link-integrity',
            {
                'request_id': request_id,
                'subject': {'type': 'file', 'path': str(resolved_md_file), 'content_hash': content_hash},
                'context': {
                    'timeout': int(config.get('validation', {}).get('timeout', 10)),
                    'blacklist': list(config.get('domain_blacklist', []) or []),
                    'whitelist': list(config.get('domain_whitelist', []) or []),
                },
            },
            version=link_requirement.get('version') or None,
        )
        link_facts = link_result.get('facts')
        if not isinstance(link_facts, dict) or not isinstance(link_facts.get('summary'), dict) or not isinstance(link_facts.get('references'), list):
            raise RuntimeError('markdown-link-integrity returned no normalized facts')
        # Expose exactly the facts produced by the kernel Pack.  This keeps the
        # human-facing summary aligned with the required Verifier Gate and its
        # SSRF-safe redirect/hostname policy.
        results = link_facts['references']
        summary = link_facts['summary']
        output.update({'summary': summary, 'references': results})
        request = VerificationRequest(
            subject={'type': 'citation', 'source_format': 'markdown', 'path': str(resolved_md_file), 'content_hash': content_hash},
            requirements=('citation.semantic_review',),
            evidence=(
                Evidence('subject_context', 'markdown', {'path': str(md_file), 'content': content}),
                Evidence('source_metadata', 'citation-list', {'references': results}),
                Evidence('source_excerpt', 'validator', {'summary': summary, 'references': results}),
            ),
            request_id=request_id,
        )
        from bensz_skill_kernel import __version__ as kernel_version
        runtime_metadata = {
            'kernel': {
                'name': 'bensz-skill-kernel',
                'version': kernel_version,
                'source': 'source-tree' if Path(__file__).resolve().parents[4].joinpath('packages', 'bensz-skill-kernel').is_dir() else 'installed-package',
            },
            'pack_versions': {item['id']: item['version'] for item in requirements},
        }
        verifier_results = [{**link_result, 'runtime': runtime_metadata}]
        if 'bensz.evidence.citation-truth-fit' in requirement_by_id:
            citation_result = registry.run(
                'bensz.evidence.citation-truth-fit',
                {
                    'request_id': request.request_id,
                    'subject': dict(request.subject),
                    'requirements': list(request.requirements),
                    'evidence': [item.to_dict() for item in request.evidence],
                    'context': dict(request.context),
                },
                version=citation_requirement.get('version') or None,
            )
            verifier_results.append({**citation_result, 'runtime': runtime_metadata})
        specs = {item['id']: registry.resolve(item['id'], item.get('version') or None).spec for item in requirements}
        for item in verifier_results:
            verifier_id = item.get('verifier_id')
            if verifier_id and verifier_id not in specs:
                specs[verifier_id] = registry.resolve(verifier_id, item.get('verifier_version') or None).spec
        normalized = tuple(normalize_result(item, specs[item.get('verifier_id')], evidence_refs=item.get('evidence_refs', ())) for item in verifier_results if item.get('verifier_id') in specs)
        gate_decision = apply_gate(normalized, requirements=requirements)
        gate = gate_decision.to_dict()
        gate['requirements'] = requirements
        output['verification'] = {
            'request_id': request.request_id,
            'results': verifier_results,
            'gate': gate,
            'metrics': summarize_metrics(normalized, (gate_decision,), required_ids=[item['id'] for item in requirements if item.get('required')]),
            'requirements': requirements,
            'runtime': runtime_metadata,
        }
    except Exception as exc:
        print(json.dumps({'error': f'kernel verifier unavailable: {exc}'}, ensure_ascii=False))
        return 2

    if args.events and output.get('verification', {}).get('results'):
        try:
            output['runtime'] = record_runtime_events(
                args.events,
                output['verification']['results'],
                output['verification']['gate'],
                request_id,
                args.attempt_id,
            )
        except Exception as exc:
            output['runtime'] = {'recorded': False, 'error': str(exc)}
            print(json.dumps(output, ensure_ascii=False, indent=2))
            return 2

    print(json.dumps(output, ensure_ascii=False, indent=2))
    return 0


if __name__ == '__main__':
    raise SystemExit(main())