Research Citation Check

# research-citation-check 配置（纯 AI 模式）
#
# 设计原则：
# - 删除静态规则/阈值判断：吻合度与改写由宿主 AI 完成
# - 脚本只做确定性工作：解析/抽取/渲染/文件写回

# 技能基本信息（版本号唯一真相来源）
skill_info:
  name: research-citation-check
  version: 1.1.0
  description: "综述引用语义核查：只修复致命性引用错误（虚假/错误/矛盾引用），并可选渲染 PDF/Word；兼容旧名 check-review-alignment 的 prompt 触发"
  author: "Bensz Conan"
  category: "文档质量"

# === 引用命令配置 ===
citation_commands:
  - "cite"
  - "citep"
  - "citet"
  - "citealp"
  - "citeauthor"
  - "Cite"
  - "Citet"

# === PDF 抽取配置（用于提供额外上下文）===
pdf:
  enabled: true
  max_pages: 2

# === 渲染配置（复用依赖 skill 的渲染策略）===
render:
  use_skill: research-literature-review
  fallback_skills:
    - systematic-literature-review
  overwrite: true

# === AI 修改策略（宿主 AI 执行，脚本不调用 LLM API）===
ai:
  input_limits:
    max_abstract_chars: 2000
    max_pdf_excerpt_chars: 3000

  modification:
    auto_apply: false
    preserve_citations: true
    max_edits_per_sentence: 3

    # 错误优先级分级（宿主 AI 使用；脚本只负责打包，不做语义判断）
    #
    # - P0（must_fix）：致命性错误，必须修复
    # - P1（warn_only）：仅警告，不改写
    # - P2（skip）：跳过，不触碰
    error_priority:
      # P0：致命性错误（必须修复）
      - type: "fake_citation"
        action: "must_fix"
        description: "引用的文献根本不存在（.bib 中缺失或 bibkey 错误）"
      - type: "wrong_citation"
        action: "must_fix"
        description: "引用命令中的 bibkey 与文意不符（张冠李戴）"
      - type: "contradictory_citation"
        action: "must_fix"
        description: "正文描述与论文内容矛盾（如论文说男性，文写女性）"

      # P1：仅警告，不改写
      - type: "weak_support"
        action: "warn_only"
        description: "论文只是提及该概念，未深入论证或给出结论"
      - type: "overclaim"
        action: "warn_only"
        description: "论文确实做了此事，但文中的“首创/首次/核心”等定位过度"

      # P2：禁止修改
      - type: "style_issue"
        action: "skip"
        description: "文体/表达优化（语序、措辞、行文润色）"

    # 非致命错误（P1/P2）的处理策略
    # - skip: 仅在报告中按需记录（默认）
    # - warn: 一律记录为 Warnings
    # - report: 输出更完整的“仅报告”条目
    non_fatal_handling: "skip"

  paragraph_optimization:
    enabled: false
    after_all_citations: false

#!/usr/bin/env python3
"""
bib_utils.py - BibTeX 解析与（可选）PDF 摘要段抽取

注意：
- 仅做确定性抽取；抽取失败应降级而非中断
"""

from __future__ import annotations

import re
from pathlib import Path
from typing import Dict, List, Optional


def parse_bib_file(bib_path: Path) -> Dict[str, dict]:
    """解析 BibTeX 为 dict[bibkey -> fields(lowercase)]."""
    text = bib_path.read_text(encoding="utf-8", errors="ignore")
    entries: Dict[str, dict] = {}

    try:
        import bibtexparser  # type: ignore

        bib_db = bibtexparser.loads(text)
        for e in bib_db.entries:
            key = e.get("ID") or e.get("id")
            if not key:
                continue
            entries[key] = {k.lower(): v for k, v in e.items()}
        if entries:
            return entries
    except Exception:
        # fallback to manual parsing
        pass

    raw_entries = re.split(r"@\w+\s*\{", text)
    for chunk in raw_entries[1:]:
        if "}" not in chunk:
            continue
        key_part, rest = chunk.split(",", 1)
        key = key_part.strip()
        fields: Dict[str, str] = {}
        for field_match in re.finditer(r"(\w+)\s*=\s*[{\"]([^}\"]+)", rest):
            fields[field_match.group(1).lower()] = field_match.group(2).strip()
        entries[key] = fields
    return entries


def find_pdf_for_entry(entry: dict, base_dir: Path) -> Optional[Path]:
    """从 bib entry 的 file/pdf/url 字段里尽力解析出本地 PDF 路径。"""
    file_field = entry.get("file") or entry.get("pdf") or entry.get("url")
    if not file_field:
        return None
    raw = str(file_field)

    # 常见 BibTeX `file` 字段格式：
    # - "/abs/path/to/paper.pdf"
    # - "relative/paper.pdf"
    # - "/abs/path/paper.pdf:PDF" (Zotero)
    # - "C:\\path\\paper.pdf:PDF" (Windows)
    # - 多附件用 ';' 分隔
    parts = [p.strip() for p in raw.split(";") if p.strip()]
    for part in parts or [raw.strip()]:
        m = re.search(r"(?P<path>(?:[A-Za-z]:)?[^;]*?\.pdf)", part, re.IGNORECASE)
        candidate = (m.group("path") if m else part).strip().strip("{}").strip()
        candidate = candidate.lstrip(":")  # Zotero 有时会多一个 ':'
        if not candidate:
            continue

        p = Path(candidate)
        if not p.is_absolute():
            p = base_dir / p

        if p.exists() and p.suffix.lower() == ".pdf":
            return p

    return None


def extract_pdf_text(pdf_path: Path, max_pages: int, warnings: List[str]) -> str:
    """抽取 PDF 前 max_pages 页文本；失败则返回空串并写 warnings。"""
    if not pdf_path.exists():
        return ""

    try:
        import pdfplumber  # type: ignore

        text_parts: List[str] = []
        with pdfplumber.open(pdf_path) as pdf:
            for page in pdf.pages[:max_pages]:
                text_parts.append(page.extract_text() or "")
        return "\n".join(text_parts).strip()
    except Exception as e:
        warnings.append(f"pdfplumber 不可用或解析失败，尝试 PyPDF2。原因: {e}")

    try:
        from PyPDF2 import PdfReader  # type: ignore

        reader = PdfReader(str(pdf_path))
        texts: List[str] = []
        for idx, page in enumerate(reader.pages):
            if idx >= max_pages:
                break
            try:
                texts.append(page.extract_text() or "")
            except Exception as inner:
                warnings.append(f"PyPDF2 解析第 {idx+1} 页失败: {inner}")
        return "\n".join(texts).strip()
    except Exception as e:
        warnings.append(f"PyPDF2 不可用或解析失败: {e}")
        return ""

#!/usr/bin/env python3
"""
paragraph_analyzer.py - LaTeX 段落分析器

核心功能：
1. 解析 LaTeX 文档，提取段落结构
2. 定位每个引用所在的句子
3. 建立引用 → 句子 → 段落的映射关系
"""

from __future__ import annotations

import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Dict, List, Optional, Tuple


@dataclass
class CitationInContext:
    """引用及其上下文信息"""
    bibkey: str
    cite_command: str          # 完整的 \cite{...} 命令
    sentence: str              # 包含该引用的完整句子
    sentence_start: int        # 句子在段落中的字符位置
    sentence_end: int
    line_number: int
    paragraph_index: int       # 所属段落索引
    citation_index_in_para: int  # 在段落中的第几个引用
    citation_index_global: int  # 全局第几个引用


@dataclass
class Paragraph:
    """LaTeX 段落"""
    index: int
    raw_text: str
    start_line: int  # 1-based, inclusive
    end_line: int    # 1-based, inclusive
    sentences: List[str] = field(default_factory=list)
    citations: List[CitationInContext] = field(default_factory=list)

    @property
    def has_citations(self) -> bool:
        return len(self.citations) > 0

    @property
    def citation_count(self) -> int:
        return len(self.citations)


@dataclass
class DocumentStructure:
    """LaTeX 文档结构"""
    paragraphs: List[Paragraph] = field(default_factory=list)
    citations: List[CitationInContext] = field(default_factory=list)
    bibkey_to_citations: Dict[str, List[CitationInContext]] = field(default_factory=dict)

    @property
    def total_citations(self) -> int:
        return len(self.citations)

    @property
    def total_paragraphs(self) -> int:
        return len(self.paragraphs)

    @property
    def paragraphs_with_citations(self) -> List[Paragraph]:
        return [p for p in self.paragraphs if p.has_citations]


def parse_latex_document(
    tex_path: Path,
    citation_commands: Optional[List[str]] = None
) -> DocumentStructure:
    """
    解析 LaTeX 文档，提取段落和引用结构

    Args:
        tex_path: LaTeX 文件路径
        citation_commands: 要识别的引用命令列表

    Returns:
        DocumentStructure: 文档结构对象
    """
    if citation_commands is None:
        citation_commands = ["cite", "citep", "citet", "citealp",
                            "citeauthor", "Cite", "Citet"]

    text = tex_path.read_text(encoding="utf-8", errors="ignore")
    lines = _sanitize_lines_for_analysis(text.splitlines())

    # 提取文档主体（跳过导言区）
    body_start = _find_document_body(lines)  # 0-based line index where body starts
    body_lines = lines[body_start:] if body_start > 0 else lines

    # 提取段落（body_lines 已经切片过：用 1-based 行号偏移恢复到原文件行号）
    paragraphs = _extract_paragraphs(body_lines, body_start + 1)

    # 构建引用正则
    cite_pattern = _build_citation_pattern(citation_commands)

    # 分析每个段落的引用
    all_citations: List[CitationInContext] = []
    bibkey_map: Dict[str, List[CitationInContext]] = {}

    global_cite_idx = 0
    for para in paragraphs:
        # 在段落中查找所有引用
        para_citations = _extract_citations_from_paragraph(para, cite_pattern, global_cite_idx)
        para.citations = para_citations
        all_citations.extend(para_citations)
        global_cite_idx += len(para_citations)

        # 更新 bibkey 映射
        for citation in para_citations:
            bibkey_map.setdefault(citation.bibkey, []).append(citation)

    return DocumentStructure(
        paragraphs=paragraphs,
        citations=all_citations,
        bibkey_to_citations=bibkey_map
    )


def _find_document_body(lines: List[str]) -> int:
    """查找 \\begin{document} 的位置"""
    for i, line in enumerate(lines):
        if r"\begin{document}" in line:
            return i + 1
    return 0


def _sanitize_lines_for_analysis(lines: List[str]) -> List[str]:
    """
    为引用抽取做预处理：
    - 剔除未转义的 % 注释（避免把注释里的 \\cite{} 当作真实引用）
    - 将 verbatim-like 环境内容置空（避免从代码块里误抽取引用）

    注意：这里保持行数不变，以确保行号映射仍然可靠。
    """
    out: List[str] = []
    in_verbatim = False

    for line in lines:
        stripped = line.strip()

        # 粗粒度识别 verbatim-like 环境（覆盖常见代码块环境）
        if not in_verbatim and (
            r"\begin{verbatim}" in stripped
            or r"\begin{lstlisting}" in stripped
            or r"\begin{minted}" in stripped
        ):
            in_verbatim = True
            out.append("")
            continue

        if in_verbatim and (
            r"\end{verbatim}" in stripped
            or r"\end{lstlisting}" in stripped
            or r"\end{minted}" in stripped
        ):
            in_verbatim = False
            out.append("")
            continue

        if in_verbatim:
            out.append("")
            continue

        out.append(_strip_latex_comment(line))

    return out


def _strip_latex_comment(line: str) -> str:
    """
    剔除 LaTeX 行内注释：未被转义的 '%' 之后的内容都视为注释。

    规则：
    - '\\%' 表示字面百分号，不开启注释
    - '...\\\\%' 里 '%' 仍然是注释（连续反斜杠数为偶数时不算转义）
    """
    for i, ch in enumerate(line):
        if ch != "%":
            continue

        # 统计 '%' 前连续反斜杠数量，奇数表示该 '%' 被转义。
        bs = 0
        j = i - 1
        while j >= 0 and line[j] == "\\":
            bs += 1
            j -= 1
        if bs % 2 == 1:
            continue
        return line[:i].rstrip()
    return line


def _extract_paragraphs(lines: List[str], offset_line_1based: int) -> List[Paragraph]:
    """
    从 LaTeX 行列表中提取段落
    注意：传入的 lines 应该已经是 \\begin{document} 之后的内容

    规则：
    - 空行分隔段落
    - 跳过注释行（以 % 开头）
    - 跳过纯命令行（如 \\section{...}）
    - 合并连续的非空行为段落
    """
    paragraphs: List[Paragraph] = []
    current_para_lines: List[str] = []
    para_start_line = offset_line_1based
    para_idx = 0

    for i, line in enumerate(lines):
        # 遇到 \end{document} 停止
        if r"\end{document}" in line:
            if current_para_lines:
                para_text = "\n".join(current_para_lines)
                if para_text.strip():
                    paragraphs.append(Paragraph(
                        index=para_idx,
                        raw_text=para_text,
                        start_line=para_start_line,
                        end_line=offset_line_1based + (i - 1),
                        sentences=_split_sentences(para_text)
                    ))
                    para_idx += 1
            current_para_lines = []
            break

        stripped = line.strip()

        # 跳过空行和注释
        if not stripped or stripped.startswith("%"):
            if current_para_lines:
                para_text = "\n".join(current_para_lines)
                if para_text.strip():
                    paragraphs.append(Paragraph(
                        index=para_idx,
                        raw_text=para_text,
                        start_line=para_start_line,
                        end_line=offset_line_1based + (i - 1),
                        sentences=_split_sentences(para_text)
                    ))
                    para_idx += 1
                current_para_lines = []
            continue

        # 跳过纯命令
        if re.match(r"\\(section|subsection|subsubsection|chapter|part|maketitle|setcounter)\s*\{?", stripped):
            if current_para_lines:
                para_text = "\n".join(current_para_lines)
                if para_text.strip():
                    paragraphs.append(Paragraph(
                        index=para_idx,
                        raw_text=para_text,
                        start_line=para_start_line,
                        end_line=offset_line_1based + (i - 1),
                        sentences=_split_sentences(para_text)
                    ))
                    para_idx += 1
                current_para_lines = []
            continue

        # 保留内容
        if not current_para_lines:
            para_start_line = offset_line_1based + i
        current_para_lines.append(line)

    # 最后一个段落
    if current_para_lines:
        para_text = "\n".join(current_para_lines)
        if para_text.strip():
            paragraphs.append(Paragraph(
                index=para_idx,
                raw_text=para_text,
                start_line=para_start_line,
                end_line=offset_line_1based + (len(lines) - 1),
                sentences=_split_sentences(para_text)
            ))

    return paragraphs


def _split_sentences(text: str) -> List[str]:
    """
    将文本分割为句子

    简单规则：
    - 按句号、问号、感叹号分割
    - 保留 LaTeX 命令完整性
    - 过滤空句子
    """
    # 保护常见缩写（避免被断句切开），例如 "i.e.", "e.g.", "etc."
    #
    # 注意：这里必须使用“可还原的 token”，避免把正则转义字符写回正文导致污染。
    abbrev_rules = [
        (r"\betc\.", "etc."),
        (r"\bi\.e\.", "i.e."),
        (r"\be\.g\.", "e.g."),
        (r"\bFig\.", "Fig."),
        (r"\bFigs\.", "Figs."),
        (r"\bvs\.", "vs."),
        (r"\bapprox\.", "approx."),
        (r"\bNo\.", "No."),
    ]
    token_map: Dict[str, str] = {}
    for idx, (pat, literal) in enumerate(abbrev_rules):
        token = f"__ABBR{idx}__"
        token_map[token] = literal
        text = re.sub(pat, token, text, flags=re.IGNORECASE)

    # 按标点分割
    sentences = re.split(r'(?<=[.!?])\s+(?=[A-Z]|\\[\w]|[\u4e00-\u9fff])', text)

    # 恢复缩写
    for i, sent in enumerate(sentences):
        for token, literal in token_map.items():
            sent = sent.replace(token, literal)
        sentences[i] = sent

    # 过滤并清理
    result = [s.strip() for s in sentences if s.strip()]
    return result


def _build_citation_pattern(commands: List[str]) -> re.Pattern:
    """
    构建识别引用命令的正则表达式

    支持：
    - \cite{key}
    - \cite{key1,key2}
    - \cite[p.1]{key}
    - \cite*{key}
    - 多行引用
    """
    cmd_pattern = "|".join(re.escape(cmd) for cmd in commands)
    # 修正：避免重复的量词
    # 允许多个可选参数：\cite[see][p.3]{key}
    pattern = rf"\\(?:{cmd_pattern})\*?\s*(?:\[[^\]]*\]\s*)*\{{[^}}]*?\}}"
    return re.compile(pattern, re.MULTILINE | re.DOTALL)


def _extract_citations_from_paragraph(
    paragraph: Paragraph,
    cite_pattern: re.Pattern,
    global_start_idx: int
) -> List[CitationInContext]:
    """从段落中提取所有引用及其上下文"""
    citations: List[CitationInContext] = []

    for match in cite_pattern.finditer(paragraph.raw_text):
        cite_cmd = match.group(0)

        # 计算引用所在行号（1-based）
        # paragraph.start_line 已是文件内的 1-based 行号。
        rel_line_offset = paragraph.raw_text[:match.start()].count("\n")
        line_no = paragraph.start_line + rel_line_offset

        # 提取 bibkey（可能有多个）
        keys_match = re.search(r'\{([^}]*)\}', cite_cmd)
        if not keys_match:
            continue

        keys_str = keys_match.group(1)
        keys = [k.strip() for k in keys_str.split(",") if k.strip()]

        # 提取引用所在句子（及其边界）
        sentence, sent_start, sent_end = _extract_sentence_containing_citation(
            paragraph.raw_text, match.start(), match.end()
        )

        for key in keys:
            citation = CitationInContext(
                bibkey=key,
                cite_command=cite_cmd,
                sentence=sentence,
                sentence_start=sent_start,
                sentence_end=sent_end,
                line_number=line_no,
                paragraph_index=paragraph.index,
                citation_index_in_para=len(citations),
                citation_index_global=global_start_idx + len(citations),
            )
            citations.append(citation)

    return citations


def _extract_sentence_containing_citation(
    text: str,
    cite_start: int,
    cite_end: int
) -> Tuple[str, int, int]:
    """
    提取包含引用的完整句子

    策略：
    - 向前查找句子开始（句号、问号、感叹号或段落开头）
    - 向后查找句子结束（句号、问号、感叹号或段落结尾）
    - 保护 LaTeX 命令完整性
    """
    # 为了避免把 "i.e." / "e.g." / "etc." 里的 '.' 当作断句标点，
    # 在边界扫描时先对常见缩写做等长掩码（不改变字符串长度，保证索引可复用）。
    scan_text = text
    scan_text = re.sub(r"\betc\.", "etc_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\bi\.e\.", "i_e_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\be\.g\.", "e_g_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\bFig\.", "Fig_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\bFigs\.", "Figs_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\bvs\.", "vs_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\bapprox\.", "approx_", scan_text, flags=re.IGNORECASE)
    scan_text = re.sub(r"\bNo\.", "No_", scan_text, flags=re.IGNORECASE)

    # 向前查找
    sentence_start = 0
    for i in range(cite_start - 1, -1, -1):
        if scan_text[i] in ".!?。？！":
            sentence_start = i + 1
            break

    # 向后查找
    sentence_end = len(text)
    for i in range(cite_end, len(text)):
        if scan_text[i] in ".!?。？！":
            sentence_end = i + 1
            break

    sentence = text[sentence_start:sentence_end].strip()
    # 合并多余空格
    sentence = " ".join(sentence.split())

    return sentence, sentence_start, sentence_end


def get_paragraph_by_index(
    structure: DocumentStructure,
    index: int
) -> Optional[Paragraph]:
    """按索引获取段落"""
    if 0 <= index < len(structure.paragraphs):
        return structure.paragraphs[index]
    return None


def get_citations_by_bibkey(
    structure: DocumentStructure,
    bibkey: str
) -> List[CitationInContext]:
    """按 bibkey 获取所有引用"""
    return structure.bibkey_to_citations.get(bibkey, [])


def format_paragraph_summary(paragraph: Paragraph) -> str:
    """格式化段落摘要（用于调试）"""
    lines = [
        f"=== 段落 #{paragraph.index} ===",
        f"行范围: {paragraph.start_line}-{paragraph.end_line}",
        f"引用数: {paragraph.citation_count}",
    ]
    if paragraph.citations:
        lines.append("引用列表:")
        for cite in paragraph.citations:
            lines.append(f"  - [{cite.bibkey}] L{cite.line_number}: {cite.sentence[:80]}...")
    else:
        lines.append("（无引用）")

    return "\n".join(lines)


# 导出
__all__ = [
    "parse_latex_document",
    "DocumentStructure",
    "Paragraph",
    "CitationInContext",
    "get_paragraph_by_index",
    "get_citations_by_bibkey",
    "format_paragraph_summary",
]

#!/usr/bin/env python3
"""
run_ai_alignment.py - research-citation-check 的确定性入口（纯 AI 模式）

脚本职责（确定性）：
- 依赖检查（research-literature-review）
- 定位 tex/bib
- 解析段落与引用，抽取 bib 元信息与（可选）PDF 摘要段
- 可选：渲染 PDF/Word（复用依赖 skill 的脚本）

非职责（启发式/AI）：
- 判断“引用是否合理”、生成改写句子与段落
- 写 ai_alignment_report.md 的“问题原因/优化版本”等语义内容

这些由宿主 AI（Claude/Codex）在执行本 skill 时完成。
"""

from __future__ import annotations

import argparse
import datetime as dt
import json
import subprocess
from pathlib import Path
from typing import Any, Dict, List, Optional

from bib_utils import extract_pdf_text, find_pdf_for_entry, parse_bib_file
from paragraph_analyzer import parse_latex_document
from runtime_utils import find_tex_and_bib, load_config, python_executable

def _truncate(text: str, limit: int) -> str:
    if not text:
        return ""
    t = " ".join(str(text).split())
    if len(t) <= limit:
        return t
    return t[:limit].rstrip() + " …(truncated)"

def _safe_int(value: Any, default: int, warnings: List[str], name: str) -> int:
    try:
        return int(value)
    except Exception:
        warnings.append(f"invalid int for {name}: {value!r} (fallback to {default})")
        return default


def build_ai_input(
    work_dir: Path,
    tex_path: Path,
    bib_path: Path,
    config: dict,
) -> Dict[str, Any]:
    """生成供宿主 AI 使用的结构化输入（ai_alignment_input.json）。"""
    warnings: List[str] = []

    ai_cfg = config.get("ai", {}) or {}
    limits = ai_cfg.get("input_limits", {}) or {}
    max_abstract_chars = _safe_int(limits.get("max_abstract_chars", 2000), 2000, warnings, "ai.input_limits.max_abstract_chars")
    max_pdf_excerpt_chars = _safe_int(limits.get("max_pdf_excerpt_chars", 3000), 3000, warnings, "ai.input_limits.max_pdf_excerpt_chars")

    # 将“修改策略”打包进输入，确保宿主 AI 在只读取 ai_alignment_input.json 时也能
    # 严格遵循“只修复致命性错误，不为了改而改”的边界（脚本不做任何语义判断）。
    mod_cfg = ai_cfg.get("modification", {}) or {}
    para_cfg = ai_cfg.get("paragraph_optimization", {}) or {}
    policy: Dict[str, Any] = {
        "modification": {
            "auto_apply": bool(mod_cfg.get("auto_apply", False)),
            "preserve_citations": bool(mod_cfg.get("preserve_citations", True)),
            "max_edits_per_sentence": _safe_int(mod_cfg.get("max_edits_per_sentence", 3), 3, warnings, "ai.modification.max_edits_per_sentence"),
            "error_priority": list(mod_cfg.get("error_priority", []) or []),
            "non_fatal_handling": str(mod_cfg.get("non_fatal_handling", "skip")),
        },
        "paragraph_optimization": {
            "enabled": bool(para_cfg.get("enabled", False)),
            "after_all_citations": bool(para_cfg.get("after_all_citations", False)),
        },
    }

    doc = parse_latex_document(
        tex_path,
        citation_commands=config.get("citation_commands", []),
    )
    bib_entries = parse_bib_file(bib_path)

    raw_skill_info = (config.get("skill_info", {}) or {}) if isinstance(config, dict) else {}
    skill_info: Dict[str, Any] = {}
    for k in ("name", "version", "description", "category"):
        if k in raw_skill_info:
            skill_info[k] = raw_skill_info.get(k)

    cited_keys = sorted({c.bibkey for c in doc.citations})

    pdf_cfg = config.get("pdf", {}) or {}
    pdf_enabled = bool(pdf_cfg.get("enabled", True))
    max_pages = _safe_int(pdf_cfg.get("max_pages", 2), 2, warnings, "pdf.max_pages")

    papers: Dict[str, Dict[str, Any]] = {}
    missing_in_bib_keys: List[str] = []
    for key in cited_keys:
        entry = bib_entries.get(key)
        if not entry:
            papers[key] = {"bibkey": key, "missing_in_bib": True}
            missing_in_bib_keys.append(key)
            continue

        paper: Dict[str, Any] = {
            "bibkey": key,
            "missing_in_bib": False,
            "title": entry.get("title", ""),
            "author": entry.get("author", ""),
            "year": entry.get("year", ""),
            "journal": entry.get("journal", "") or entry.get("booktitle", ""),
            "doi": entry.get("doi", "") or "",
            "url": entry.get("url", "") or "",
            "abstract": _truncate(entry.get("abstract", ""), max_abstract_chars),
        }

        if pdf_enabled:
            pdf_path = find_pdf_for_entry(entry, base_dir=work_dir)
            if pdf_path is not None:
                try:
                    resolved_pdf = pdf_path.resolve()
                    resolved_work = work_dir.resolve()
                    # 如果 PDF 路径不在 work_dir 内，给出 warning（但不强制禁止，避免破坏用户工作流）
                    try:
                        resolved_pdf.relative_to(resolved_work)
                    except Exception:
                        warnings.append(f"PDF 路径不在 work_dir 内（仍会尝试读取）：{resolved_pdf}")
                except Exception:
                    # resolve 失败不影响主流程
                    pass
                excerpt = extract_pdf_text(pdf_path, max_pages=max_pages, warnings=warnings)
                if excerpt:
                    paper["pdf_path"] = str(pdf_path)
                    paper["pdf_excerpt"] = _truncate(excerpt, max_pdf_excerpt_chars)
        papers[key] = paper

    paragraphs: List[Dict[str, Any]] = []
    for p in doc.paragraphs_with_citations:
        paragraphs.append(
            {
                "index": p.index,
                "start_line": p.start_line,
                "end_line": p.end_line,
                "citation_count": p.citation_count,
            }
        )

    citations: List[Dict[str, Any]] = []
    for c in doc.citations:
        citations.append(
            {
                "bibkey": c.bibkey,
                "line_number": c.line_number,
                "paragraph_index": c.paragraph_index,
                "citation_index_in_paragraph": c.citation_index_in_para,
                "citation_index_global": c.citation_index_global,
                "sentence": c.sentence,
                "cite_command": c.cite_command,
            }
        )

    citations.sort(
        key=lambda x: (
            int(x.get("line_number", 0)),
            int(x.get("paragraph_index", 0)),
            int(x.get("citation_index_in_paragraph", 0)),
            str(x.get("bibkey", "")),
        )
    )

    if missing_in_bib_keys:
        warnings.append("以下 bibkey 在 .bib 中缺失（已标记 missing_in_bib=true）: " + ", ".join(missing_in_bib_keys))

    return {
        "generated_at": dt.datetime.now().isoformat(timespec="seconds"),
        "skill_info": skill_info,
        "work_dir": str(work_dir),
        "tex": tex_path.name,
        "bib": bib_path.name,
        "policy": policy,
        "stats": {
            "total_paragraphs": doc.total_paragraphs,
            "paragraphs_with_citations": len(doc.paragraphs_with_citations),
            "total_citations": doc.total_citations,
            "unique_cited_bibkeys": len(cited_keys),
            "missing_in_bib_bibkeys": len(missing_in_bib_keys),
        },
        "warnings": warnings,
        "paragraphs": paragraphs,
        "citations": citations,
        "papers": papers,
    }


def render_outputs(tex_path: Path, bib_path: Path, config: dict) -> Dict[str, Any]:
    """渲染 PDF/Word（复用依赖 skill 的渲染脚本）。"""
    render_cfg = config.get("render", {}) or {}
    overwrite = bool(render_cfg.get("overwrite", True))

    dep_skill = str(render_cfg.get("use_skill", "research-literature-review"))
    fallback_skills = render_cfg.get("fallback_skills", ["systematic-literature-review"]) or []
    fallback_skill_names = [str(item) for item in fallback_skills]
    # 仅在渲染路径下检查依赖（prepare 不应被渲染依赖阻塞）
    from runtime_utils import resolve_dependency_skill, resolve_render_scripts

    resolved_skill, dep_root = resolve_dependency_skill(dep_skill, fallback_skill_names, reason="PDF/Word 渲染")
    compile_script, word_script = resolve_render_scripts(dep_root, dep_skill_name=resolved_skill)

    pdf_path = tex_path.with_suffix(".pdf")
    docx_path = tex_path.with_suffix(".docx")

    log: List[str] = []
    result: Dict[str, Any] = {"ok": True, "pdf": None, "word": None, "log": log}

    if overwrite or not pdf_path.exists():
        proc_pdf = subprocess.run(
            [python_executable(), str(compile_script), str(tex_path), str(pdf_path)],
            text=True,
            capture_output=True,
            cwd=tex_path.parent,
        )
        if proc_pdf.stdout:
            log.append(proc_pdf.stdout)
        if proc_pdf.returncode != 0:
            if proc_pdf.stderr:
                log.append(proc_pdf.stderr)
            result["ok"] = False
            return result
        result["pdf"] = str(pdf_path)
    else:
        log.append("skip PDF render: overwrite=false and target exists")
        result["pdf"] = str(pdf_path)

    if overwrite or not docx_path.exists():
        proc_docx = subprocess.run(
            [python_executable(), str(word_script), str(tex_path), str(bib_path), str(docx_path)],
            text=True,
            capture_output=True,
            cwd=tex_path.parent,
        )
        if proc_docx.stdout:
            log.append(proc_docx.stdout)
        if proc_docx.returncode != 0:
            if proc_docx.stderr:
                log.append(proc_docx.stderr)
            result["ok"] = False
            return result
        result["word"] = str(docx_path)
    else:
        log.append("skip Word render: overwrite=false and target exists")
        result["word"] = str(docx_path)

    return result


def main() -> int:
    parser = argparse.ArgumentParser(description="research-citation-check (AI mode) helper runner")
    parser.add_argument("--work-dir", required=True, type=Path, help="综述工作目录（包含 tex/bib）")
    parser.add_argument("--tex", type=str, default=None, help="可选：指定 tex 文件名")
    parser.add_argument("--prepare", action="store_true", help="生成 ai_alignment_input.json")
    parser.add_argument("--render", action="store_true", help="渲染 PDF/Word（不做任何 AI 判断）")
    args = parser.parse_args()

    work_dir = args.work_dir.resolve()
    skill_root = Path(__file__).resolve().parents[1]
    config, cfg_warnings = load_config(skill_root / "config.yaml")
    for w in cfg_warnings:
        # config 读取警告仅用于告知，不影响执行
        print(f"⚠️  {w}")

    do_prepare = bool(args.prepare)
    do_render = bool(args.render)
    if not do_prepare and not do_render:
        do_prepare = True

    selection_warnings: List[str] = []
    try:
        tex_path, bib_path = find_tex_and_bib(work_dir, args.tex, warnings=selection_warnings)
    except FileNotFoundError as e:
        print(f"❌ {e}")
        if args.tex:
            print("   提示：--tex 只支持传入文件名；并确保该文件存在于 work_dir 根目录。")
        return 2
    for w in selection_warnings:
        # 这里的 warning 主要用于可预期性（例如同目录多 tex 的默认选择）
        print(f"⚠️  {w}")
        if "默认选择第一个" in w:
            print("   提示：可用 --tex <file.tex> 指定目标 tex 文件名。")

    # 创建中间文件目录（隐藏文件夹）
    intermediate_dir = work_dir / ".check-review-alignment"
    intermediate_dir.mkdir(exist_ok=True)

    if do_prepare:
        payload = build_ai_input(work_dir, tex_path, bib_path, config=config)
        out_path = intermediate_dir / "ai_alignment_input.json"
        out_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
        print(f"✅ 已生成: {out_path}")

    if do_render:
        print("🖨️  开始渲染 PDF/Word（复用依赖 skill 脚本）...")
        result = render_outputs(tex_path, bib_path, config=config)
        if not result.get("ok"):
            print("❌ 渲染失败（请检查 log）")
            return 2
        print(f"✅ PDF: {result.get('pdf')}")
        print(f"✅ Word: {result.get('word')}")

    return 0


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

#!/usr/bin/env python3
"""
runtime_utils.py - research-citation-check 的确定性运行时工具

原则：
- 不调用任何 LLM API
- 只做路径解析 / 配置加载 / 依赖定位 / 文件发现等确定性工作
"""

from __future__ import annotations

import os
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


def merge_dict(base: dict, override: dict) -> dict:
    merged = dict(base)
    for k, v in override.items():
        if isinstance(v, dict) and isinstance(merged.get(k), dict):
            merged[k] = merge_dict(merged[k], v)
        else:
            merged[k] = v
    return merged


def load_config(config_path: Path) -> Tuple[dict, List[str]]:
    """读取 config.yaml；缺依赖时降级到默认值。"""
    default_cfg: Dict[str, Any] = {
        "citation_commands": ["cite", "citep", "citet", "citealp", "citeauthor", "Cite", "Citet"],
        "pdf": {"enabled": True, "max_pages": 2},
        "render": {
            "use_skill": "research-literature-review",
            "fallback_skills": ["systematic-literature-review"],
            "overwrite": True,
        },
        "ai": {
            "input_limits": {"max_abstract_chars": 2000, "max_pdf_excerpt_chars": 3000},
            "modification": {
                "auto_apply": False,
                "preserve_citations": True,
                "max_edits_per_sentence": 3,
                # 默认策略：只修复致命性错误（P0），P1 仅警告，P2 跳过
                "error_priority": [
                    {"type": "fake_citation", "action": "must_fix", "description": "missing in .bib or wrong bibkey"},
                    {"type": "wrong_citation", "action": "must_fix", "description": "bibkey does not match the claim"},
                    {"type": "contradictory_citation", "action": "must_fix", "description": "claim contradicts the paper"},
                    {"type": "weak_support", "action": "warn_only", "description": "paper only weakly supports the claim"},
                    {"type": "overclaim", "action": "warn_only", "description": "claim strength is overstated"},
                    {"type": "style_issue", "action": "skip", "description": "style / wording only"},
                ],
                "non_fatal_handling": "skip",
            },
            # 默认禁用段落优化：该技能只做“致命性引用错误修复”，避免文体改写
            "paragraph_optimization": {"enabled": False, "after_all_citations": False},
        },
    }
    warnings: List[str] = []

    if not config_path.exists():
        warnings.append("config.yaml 不存在，使用默认配置")
        return default_cfg, warnings

    try:
        import yaml  # type: ignore

        loaded = yaml.safe_load(config_path.read_text(encoding="utf-8"))
        if isinstance(loaded, dict):
            return merge_dict(default_cfg, loaded), warnings
        warnings.append("config.yaml 解析结果非 dict，使用默认配置")
    except ImportError:
        warnings.append("缺少 PyYAML，无法读取 config.yaml，使用默认配置")
    except Exception as e:
        warnings.append(f"读取 config.yaml 失败，使用默认配置: {e}")

    return default_cfg, warnings


def find_tex_and_bib(
    work_dir: Path, tex_arg: Optional[str], warnings: Optional[List[str]] = None
) -> Tuple[Path, Path]:
    """在 work_dir 内定位 review.tex 与对应的 .bib。"""
    tex_path: Optional[Path] = None
    bib_path: Optional[Path] = None

    if tex_arg:
        # 安全与可预期性：--tex 只允许文件名（不允许路径），避免路径遍历/误读其他目录文件。
        raw = Path(tex_arg)
        if raw.is_absolute() or raw.name != tex_arg:
            raise SystemExit("❌ 无效参数：--tex 只允许传入 tex 文件名（不支持路径）")

        name = raw.name
        if not name.lower().endswith(".tex"):
            if raw.suffix == "":
                name = f"{name}.tex"
            else:
                raise SystemExit("❌ 无效参数：--tex 必须是 .tex 文件名（不支持路径）")

        candidate = work_dir / name
        if candidate.exists():
            tex_path = candidate
    else:
        review_candidates = sorted(work_dir.glob("*_review.tex"))
        if review_candidates:
            if warnings is not None and len(review_candidates) > 1:
                names = ", ".join(p.name for p in review_candidates)
                warnings.append(f"work_dir 内存在多个 *_review.tex，默认选择第一个（按文件名排序）：{names}")
            tex_path = review_candidates[0]
        else:
            tex_candidates = sorted(work_dir.glob("*.tex"))
            if tex_candidates:
                if warnings is not None and len(tex_candidates) > 1:
                    names = ", ".join(p.name for p in tex_candidates)
                    warnings.append(f"work_dir 内存在多个 *.tex，默认选择第一个（按文件名排序）：{names}")
                tex_path = tex_candidates[0]

    if tex_path:
        # 常见命名：topic_review.tex -> topic_review.bib（同名）或 topic.bib（去掉 _review）
        candidates: List[Path] = []
        candidates.append(tex_path.with_suffix(".bib"))
        stem = tex_path.stem
        if stem.endswith("_review") and len(stem) > len("_review"):
            candidates.append((work_dir / f"{stem[:-len('_review')]}.bib"))

        for c in candidates:
            if c.exists():
                bib_path = c
                break

        if bib_path is None:
            for p in sorted(work_dir.glob("*.bib")):
                bib_path = p
                break

    if not tex_path or not bib_path:
        missing: List[str] = []
        if not tex_path:
            missing.append("tex")
        if not bib_path:
            missing.append("bib")
        raise FileNotFoundError(f"找不到所需文件: {', '.join(missing)} (work_dir={work_dir})")

    return tex_path, bib_path


def resolve_skill_root(skill_name: str) -> Optional[Path]:
    """尝试定位某个已安装的 skill 根目录。"""
    # 1) 显式指定（最强）
    env_key = f"{skill_name.upper().replace('-', '_')}_SKILL_DIR"
    if os.environ.get(env_key):
        p = Path(os.environ[env_key]).expanduser()
        if p.is_dir():
            return p

    # 2) 同仓库相邻目录（开发时）
    here = Path(__file__).resolve()
    skill_root = here.parents[1]  # {skill}/scripts/ -> {skill}/
    sibling = (skill_root.parent / skill_name).resolve()
    if sibling.is_dir():
        return sibling

    # 3) 常见安装目录
    home = Path.home()
    candidates = [
        home / ".codex" / "skills" / skill_name,
        home / ".claude" / "skills" / skill_name,
    ]

    codex_home = os.environ.get("CODEX_HOME")
    if codex_home:
        candidates.insert(0, Path(codex_home) / "skills" / skill_name)

    for c in candidates:
        if c.is_dir():
            return c

    return None


def require_dependency_skill(skill_name: str, reason: str) -> Path:
    """强制依赖检查：找不到则按约定提示并停止。"""
    root = resolve_skill_root(skill_name)
    if root is not None:
        return root
    # 计划要求的固定提示口径
    raise SystemExit(
        "❌ 缺少依赖：research-citation-check 依赖 "
        f"{skill_name} skill 进行 {reason}。请先安装 {skill_name} skill。"
    )


def resolve_dependency_skill(skill_name: str, fallback_skill_names: List[str], reason: str) -> Tuple[str, Path]:
    """优先解析新 skill 名，过渡期允许旧名 fallback。"""
    for candidate in [skill_name, *fallback_skill_names]:
        root = resolve_skill_root(candidate)
        if root is not None:
            return candidate, root
    candidates = ", ".join([skill_name, *fallback_skill_names])
    raise SystemExit(
        "❌ 缺少依赖：research-citation-check 依赖 "
        f"{skill_name} skill 进行 {reason}。过渡期也可使用旧名 fallback：{candidates}。"
    )


def resolve_render_scripts(dep_skill_root: Path, dep_skill_name: str = "research-literature-review") -> Tuple[Path, Path]:
    """从依赖 skill 定位渲染脚本路径。"""
    compile_script = dep_skill_root / "scripts" / "compile_latex_with_bibtex.py"
    word_script = dep_skill_root / "scripts" / "convert_latex_to_word.py"
    if not compile_script.exists() or not word_script.exists():
        raise SystemExit(
            "❌ 缺少依赖：research-citation-check 依赖 "
            f"{dep_skill_name} skill 进行 PDF/Word 渲染。请先安装 {dep_skill_name} skill。"
        )
    return compile_script, word_script


def python_executable() -> str:
    # 允许宿主用不同 python，但优先当前解释器
    return sys.executable or "python3"