Back to Details

check-review-alignment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Check Review Alignment

Check Review Alignment

适用场景

Applicable Scenarios

  • 已有 
    {主题}_review.tex
    与对应 
    .bib
    ，需要核查正文每条引用是否“真的在引用该论文”，并在必要时最小化改写以消除错配/幻觉引用。
  • 需要在优化后自动渲染生成 PDF 与 Word。
  • You have 
    {topic}_review.tex
    and the corresponding 
    .bib
    file, and need to verify whether each in-text citation "actually cites the paper", and make minimal rewrites if necessary to eliminate mismatched/hallucinated citations.
  • Need to automatically render and generate PDF and Word after optimization.

输入

Input

  • work_dir
    ：综述工作目录（包含 
    {主题}_review.tex
    与 
    .bib
    ，可含 PDF）。
  • 可选：
    --tex
    指定 tex 文件名（默认取目录下首个 
    *_review.tex
    ；若目录内存在多个候选，脚本会给出 warning 并提示使用 
    --tex
    明确指定）。
  • work_dir
    : The working directory of the review (contains 
    {topic}_review.tex
    and 
    .bib
    , may include PDFs).
  • Optional: 
    --tex
    specifies the tex file name (by default, the first 
    *_review.tex
    in the directory is selected; if multiple candidates exist in the directory, the script will issue a warning and prompt to use 
    --tex
    to specify explicitly).

输出

Output

  • {work_dir}/.check-review-alignment/ai_alignment_report.md
    ：单一报告，包含 Summary / Critical Fixes (P0) / Warnings (P1) / Rendering Result（末尾附 PDF/Word 路径或错误摘要）。
  • {work_dir}/.check-review-alignment/ai_alignment_input.json
    ：脚本生成的"引用 + 文献元信息（含 DOI/URL） + PDF 摘要段"结构化输入，便于宿主 AI 快速核查。
  • 已优化的 
    {主题}_review.tex
    （保存在 
    work_dir
    根目录）；新生成的 
    {主题}_review.pdf
    与 
    {主题}_review.docx
    （保存在 
    work_dir
    根目录）。
  • {work_dir}/.check-review-alignment/ai_alignment_report.md
    : A single report including Summary / Critical Fixes (P0) / Warnings (P1) / Rendering Result (PDF/Word path or error summary is attached at the end).
  • {work_dir}/.check-review-alignment/ai_alignment_input.json
    : Structured input generated by the script, which includes "citation + literature meta-information (including DOI/URL) + PDF abstract segment", facilitating quick verification by the host AI.
  • Optimized 
    {topic}_review.tex
    (saved in the root directory of 
    work_dir
    ); newly generated 
    {topic}_review.pdf
    and 
    {topic}_review.docx
    (saved in the root directory of 
    work_dir
    ).

工作流

Workflow

步骤 0：依赖检查（仅渲染路径强制）

Step 0: Dependency Check (Mandatory Only for Rendering Path)

本技能支持两类确定性动作：
  • --prepare
    ：生成结构化输入（不依赖渲染 skill）
  • --render
    ：渲染 PDF/Word（强制依赖 
    systematic-literature-review
    ）
当且仅当你需要执行渲染（步骤 5 或 
--render
）时，必须检查以下依赖：
  • systematic-literature-review
    skill 是否可用？
    • 如果不可用：立即停止，并提示： 
      ❌ 缺少依赖：check-review-alignment 依赖 systematic-literature-review skill 进行 PDF/Word 渲染。请先安装 systematic-literature-review skill。
    • 如果可用：继续执行
This skill supports two types of deterministic actions:
  • --prepare
    : Generate structured input (does not depend on rendering skill)
  • --render
    : Render PDF/Word (mandatory dependency on 
    systematic-literature-review
    )
Only when you need to perform rendering (Step 5 or 
--render
), you must check the following dependencies:
  • Is the 
    systematic-literature-review
    skill available?
    • If not available: Stop immediately and prompt: 
      ❌ Missing dependency: check-review-alignment relies on the systematic-literature-review skill for PDF/Word rendering. Please install the systematic-literature-review skill first.
    • If available: Proceed

步骤 1：预检与文件定位

Step 1: Pre-check and File Location

  1. 在 
    work_dir
    内定位 
    *_review.tex
    与对应 
    .bib
    （或用 
    --tex
    指定）。
  2. 若缺项：停止并说明缺失文件。
  1. Locate 
    *_review.tex
    and the corresponding 
    .bib
    in 
    work_dir
    (or specify with 
    --tex
    ).
  2. If any file is missing: Stop and explain the missing files.

步骤 2：提取结构化上下文（推荐）

Step 2: Extract Structured Context (Recommended)

运行脚本生成 
ai_alignment_input.json
，用于宿主 AI 快速、可追溯地逐条核查：
bash
undefined
Run the script to generate 
ai_alignment_input.json
for the host AI to verify each item quickly and traceably:
bash
undefined

进入 skill 根目录（安装后通常是 ~/.codex/skills/check-review-alignment 或 ~/.claude/skills/check-review-alignment）

Enter the skill root directory (usually ~/.codex/skills/check-review-alignment or ~/.claude/skills/check-review-alignment after installation)

cd /path/to/check-review-alignment python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --prepare
undefined
cd /path/to/check-review-alignment python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --prepare
undefined

步骤 3：AI 语义核查与优先级分级

Step 3: AI Semantic Verification and Priority Classification

对每条引用（bibkey）进行核查：
  1. 识别错误类型：判断属于 P0（致命性）/ P1（警告）/ P2（禁止）
  2. 证据来源：按优先级使用 PDF 摘要段 > BibTeX abstract/title > 仅从句子推断（最低优先级）
  3. 按优先级处理：
    • P0：以最小改动改写“包含该引用”的句子以恢复一致性（必要时仅可改写同段内紧邻且也包含该引用的句子；禁止整段重写）
    • P1：仅记录到 Warnings，不改写
    • P2：跳过，不触碰
  4. 强制约束：
    • 保留 LaTeX 命令完整性（
      \cite{}
      、
      \ref{}
      、
      \label{}
      等）
    • 不引入新 bibkey（除非是修复错误 bibkey）
    • 不伪造论文内容
    • 禁止改写未包含引用的句子
    • 无法确定时保留原样（“不动如山”原则）
Verify each citation (bibkey):
  1. Identify Error Type: Determine if it belongs to P0 (Fatal)/P1 (Warning)/P2 (Forbidden)
  2. Evidence Source: Use PDF abstract segment > BibTeX abstract/title > inference only from sentences (lowest priority) in order of priority
  3. Process by Priority:
    • P0: Rewrite the "sentence containing the citation" with minimal changes to restore consistency (only adjacent sentences in the same paragraph that also contain the citation can be rewritten if necessary; whole paragraph rewriting is prohibited)
    • P1: Only record to Warnings, no rewriting
    • P2: Skip, no modification
  4. Mandatory Constraints:
    • Keep LaTeX command integrity (such as 
      \cite{}
      , 
      \ref{}
      , 
      \label{}
      )
    • Do not introduce new bibkeys (unless fixing wrong bibkeys)
    • Do not forge paper content
    • Prohibit rewriting sentences that do not contain citations
    • Keep the original content when uncertain ("Do Not Modify When Unsure" principle)

步骤 4：生成报告

Step 4: Generate Report

在 
{work_dir}/.check-review-alignment/ai_alignment_report.md
生成报告，必须包含以下章节：
  • Summary：段落数、引用数、P0 修改数、P1 警告数、P2 跳过数等统计
  • 具体细节（强制）：每条引用的详细核查记录，包含：
    • 引用：文献标题 
      {title}
      ；DOI 号 
      {DOI}
      （如无则标注"无 DOI"）
    • 原文内容：包含该引用的句子原文
    • 文献实际：该论文的实际内容（从 PDF 摘要段 / BibTeX abstract / title 提取）
    • 引用合理性评估：语义一致性分析，说明原文描述是否准确反映文献内容
    • 问题级别：P0（致命）/ P1（警告）/ P2（禁止）/ 无问题
  • Critical Fixes (P0)：必须修复的致命性错误（原句/原因/新句/行号/优先级）
  • Warnings (P1)：仅警告的问题（原句/原因/建议/行号/优先级）
  • Rendering Result：PDF/Word 路径或错误摘要
具体细节章节格式示例：
markdown
undefined
Generate a report in 
{work_dir}/.check-review-alignment/ai_alignment_report.md
, which must include the following sections:
  • Summary: Statistics such as number of paragraphs, number of citations, number of P0 modifications, number of P1 warnings, number of P2 skips, etc.
  • Detailed Information (Mandatory): Detailed verification records for each citation, including:
    • Citation: Literature title 
      {title}
      ; DOI number 
      {DOI}
      (mark "No DOI" if not available)
    • Original Content: Original sentence containing the citation
    • Actual Literature Content: Actual content of the paper (extracted from PDF abstract segment / BibTeX abstract / title)
    • Citation Rationality Evaluation: Semantic consistency analysis, explaining whether the original description accurately reflects the literature content
    • Issue Level: P0 (Fatal)/P1 (Warning)/P2 (Forbidden)/No Issue
  • Critical Fixes (P0): Fatal errors that must be fixed (original sentence/cause/new sentence/line number/priority)
  • Warnings (P1): Issues that only require warnings (original sentence/cause/suggestion/line number/priority)
  • Rendering Result: PDF/Word path or error summary
Example Format for Detailed Information Section:
markdown
undefined

具体细节

Detailed Information

引用：[bibkey]

Citation: [bibkey]

字段内容
文献标题{title}
DOI{DOI 或 "无 DOI"}
原文内容{包含该引用的句子原文}
文献实际{从 PDF/BibTeX 提取的论文实际内容}
引用合理性评估{语义一致性分析}
问题级别P0 / P1 / P2 / 无问题
undefined
FieldContent
Literature Title{title}
DOI{DOI or "No DOI"}
Original Content{Original sentence containing the citation}
Actual Literature Content{Actual paper content extracted from PDF/BibTeX}
Citation Rationality Evaluation{Semantic consistency analysis}
Issue LevelP0 / P1 / P2 / No Issue
undefined

步骤 5：渲染 PDF/Word

Step 5: Render PDF/Word

在完成 tex 修改后渲染：
bash
cd /path/to/check-review-alignment
python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --render
Render after modifying the tex file:
bash
cd /path/to/check-review-alignment
python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --render

修改边界与优先级

Modification Boundaries and Priorities

必须修复（P0）

Must Fix (P0)

以下情况必须修改（最小改动）：
  1. 虚假引用（
    fake_citation
    ）
    • 表现：引用的文献根本不存在（.bib 中缺失或 bibkey 错误）
    • 处理：在报告中标记 
      missing_in_bib: true
      并说明，建议用户检查 bibkey
  2. 错误引用（
    wrong_citation
    ）
    • 表现：引用命令中的 bibkey 与文意不符（张冠李戴）
    • 处理：改写句子使其与该 bibkey 的文献内容一致，或更换正确 bibkey
  3. 矛盾引用（
    contradictory_citation
    ）
    • 表现：正文描述与论文内容矛盾（如论文说男性，文写女性）
    • 处理：改写句子使其与论文内容一致
The following situations must be modified (with minimal changes):
  1. Fake Citation (
    fake_citation
    )
    • Performance: The cited literature does not exist at all (missing in .bib or wrong bibkey)
    • Handling: Mark 
      missing_in_bib: true
      in the report and explain, suggest the user check the bibkey
  2. Wrong Citation (
    wrong_citation
    )
    • Performance: The bibkey in the citation command does not match the context (mixing up references)
    • Handling: Rewrite the sentence to match the literature content of the bibkey, or replace with the correct bibkey
  3. Contradictory Citation (
    contradictory_citation
    )
    • Performance: The main body description contradicts the paper content (e.g., the paper says male, but the text writes female)
    • Handling: Rewrite the sentence to match the paper content

仅警告不改（P1）

Only Warn, No Modification (P1)

以下情况仅记录到报告 Warnings，不改写：
  1. 支撑弱（
    weak_support
    ）：建议用户补充更强引用
  2. 定位偏差（
    overclaim
    ）：建议用户降低表述强度（如避免“首创/首次/核心”）
The following situations are only recorded in the report's Warnings, no rewriting:
  1. Weak Support (
    weak_support
    ): Suggest the user add stronger citations
  2. Positioning Deviation (
    overclaim
    ): Suggest the user reduce the intensity of the statement (e.g., avoid "first-ever/initial/core")

禁止修改（P2）

Prohibit Modification (P2)

以下情况完全禁止触碰：
  1. 文体优化（
    style_issue
    ）：语序/措辞/润色
  2. 未引用句子：不包含任何 
    \cite{}
    的句子
  3. 段落重写：即使段落内所有引用都修复，也不得重写整段
The following situations are completely prohibited from being modified:
  1. Style Optimization (
    style_issue
    ): Word order/wording/polishing
  2. Sentences Without Citations: Sentences that do not contain any 
    \cite{}
  3. Paragraph Rewriting: Even if all citations in the paragraph are fixed, the whole paragraph cannot be rewritten

修改原则

Modification Principles

  • 最小改动原则：只改写必要句子，不改写相邻无关句或整段
  • 不动如山原则：无法确定是否为致命性错误时，保留原样并记录到 Warnings
  • 证据优先原则：判断依据优先级：PDF 摘要段 > BibTeX abstract/title > 仅从句子推断
  • Minimal Change Principle: Only rewrite necessary sentences, do not rewrite adjacent irrelevant sentences or the whole paragraph
  • Do Not Modify When Unsure Principle: Keep the original content and record to Warnings when uncertain whether it is a fatal error
  • Evidence Priority Principle: Judgment basis priority: PDF abstract segment > BibTeX abstract/title > inference only from sentences

配置（见 
check-review-alignment/config.yaml
）

Configuration (See 
check-review-alignment/config.yaml
)

  • citation_commands
    ：识别的引用命令
  • pdf.*
    ：是否抽取 PDF 文本及页数上限
  • render.*
    ：依赖 skill 名称与覆盖策略
  • ai.input_limits.*
    ：结构化输入（
    ai_alignment_input.json
    ）的文本截断上限
  • ai.modification.*
    ：修改策略（由宿主 AI 执行；脚本仅打包进 
    ai_alignment_input.json
    ） 
    • ai.modification.error_priority
      ：P0/P1/P2 分级（只改 P0；P1 仅警告；P2 跳过）
    • ai.modification.non_fatal_handling
      ：P1/P2 的处理策略
  • ai.paragraph_optimization.*
    ：段落优化策略（由宿主 AI 执行；默认关闭，避免文体改写）
  • citation_commands
    : Recognized citation commands
  • pdf.*
    : Whether to extract PDF text and page limit
  • render.*
    : Dependent skill name and override strategy
  • ai.input_limits.*
    : Text truncation limit for structured input (
    ai_alignment_input.json
    )
  • ai.modification.*
    : Modification strategy (executed by the host AI; the script only packages it into 
    ai_alignment_input.json
    ) 
    • ai.modification.error_priority
      : P0/P1/P2 classification (only modify P0; P1 only warns; P2 skips)
    • ai.modification.non_fatal_handling
      : Handling strategy for P1/P2
  • ai.paragraph_optimization.*
    : Paragraph optimization strategy (executed by the host AI; disabled by default to avoid style rewriting)

快速使用

Quick Start

bash
cd /path/to/check-review-alignment
bash
cd /path/to/check-review-alignment

1) 生成结构化输入（推荐）

1) Generate structured input (Recommended)

python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --prepare
python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --prepare

2) 宿主 AI 按本 SKILL.md 工作流完成核查与 tex 改写，并写 ai_alignment_report.md

2) The host AI completes verification and tex rewriting according to this SKILL.md workflow, and writes ai_alignment_report.md

3) 渲染 PDF/Word

3) Render PDF/Word

python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --render
undefined
python3 scripts/run_ai_alignment.py --work-dir "/path/to/work_dir" --render
undefined

依赖

Dependencies

  • Python 包：
    PyYAML
    、
    bibtexparser
    （读取 config/bib）、
    pdfplumber
    或 
    PyPDF2
    （PDF 抽取）。缺少时会降级（不会中断）。
  • AI 功能无需额外依赖：AI 由 Agent Skills 宿主环境（Claude/Codex）提供；脚本不在本地直接调用 LLM API。
  • 参考目录：当前 
    check-review-alignment/references/
    为空（如未来引入更详细的策略/模板，会在该目录补充）。
  • Python packages: 
    PyYAML
    , 
    bibtexparser
    (reads config/bib), 
    pdfplumber
    or 
    PyPDF2
    (PDF extraction). It will degrade when missing (will not interrupt).
  • No additional dependencies for AI functions: AI is provided by the Agent Skills host environment (Claude/Codex); the script does not directly call the LLM API locally.
  • Reference directory: The current 
    check-review-alignment/references/
    is empty (if more detailed strategies/templates are introduced in the future, they will be added to this directory).

验证清单（静态自检）

Verification Checklist (Static Self-check)

  • {work_dir}/.check-review-alignment/ai_alignment_report.md
    已生成，且每条修改包含：原句/原因/新句/定位信息。
  • {work_dir}/.check-review-alignment/ai_alignment_input.json
    已生成，包含结构化的引用与文献信息。
  • 修改后的 tex 可编译无错误，且引用命令（
    \cite{}
    等）完整保留。
  • 渲染后的 PDF/Word 路径与状态已写入报告。
  • {work_dir}/.check-review-alignment/ai_alignment_report.md
    has been generated, and each modification includes: original sentence/cause/new sentence/location information.
  • {work_dir}/.check-review-alignment/ai_alignment_input.json
    has been generated, containing structured citation and literature information.
  • The modified tex can be compiled without errors, and citation commands (such as 
    \cite{}
    ) are completely retained.
  • The path and status of the rendered PDF/Word have been written to the report.

安全原则

Security Principles

本技能遵循以下原则，确保“不为了改而改”：
原则说明实现
确定性脚本边界脚本只做解析/抽取/渲染，不做语义判断脚本不调用 LLM API
优先级分级P0 修复 / P1 警告 / P2 跳过
ai.modification.error_priority
不动如山无法确定时保留原样工作流强制约束 + Warnings
最小改动只改必要句子，不整段重写
max_edits_per_sentence
+ 禁止段落重写
LaTeX 完整性保留所有 LaTeX 命令结构
preserve_citations: true
This skill follows the following principles to ensure "Do not modify for the sake of modifying":
PrincipleDescriptionImplementation
Deterministic Script BoundaryThe script only performs parsing/extraction/rendering, no semantic judgmentThe script does not call LLM API
Priority ClassificationP0 Fix / P1 Warning / P2 Skip
ai.modification.error_priority
Do Not Modify When UnsureKeep original content when uncertainWorkflow mandatory constraints + Warnings
Minimal ChangeOnly rewrite necessary sentences, no whole paragraph rewriting
max_edits_per_sentence
+ Prohibit paragraph rewriting
LaTeX IntegrityRetain all LaTeX command structures
preserve_citations: true