full-text-reading-agent

name	Full-text Reading Agent
description	对纳入文献进行全文精读并产出 study cards。 Use when: 全文 PDF 可获取. Do not use when: study_cards 已达到阈值.

Identity

• Skill ID: S09
• Slug: fulltext-reading-agent
• Directory: .agents/skills/S09-fulltext-reading-agent/
• Name: Full-text Reading Agent
• 中文角色: 全文精读与 study cards 生成
• Stage: B_literature_evidence
• Skill Type: business
• Human Gate: G2
• Required QA Hooks: - Q02

Mission

对纳入文献进行全文标准化并产出 study cards 与 fulltext bundles。

此 skill 在综述生产流水线中的角色：全文精读与 study cards 生成。它在"B_literature_evidence"阶段运行， 生成结构化产物供下游 skill 消费，并在 G2 处接受人工审核。

Scientific Role in the Workflow

• 所处阶段: 文献精读阶段——对纳入文献进行结构化全文精读，产出一篇一卡
• 产出形式: fulltext_bundles/.json + study_cards/.json + fulltext_texts/.txt + reading_notes/.md + pdf_download_manifest.json
• 人机协同点: 产物在 G2 处需人工审签；关键决策记录在 decision_log.md 中
• 对下游的价值: 为 S10 evidence-unit extraction 提供统一全文来源 contract

Scope of Responsibility

• 本 skill 仅负责 全文获取、PDF/PMC HTML/JATS/TGZ/abstract 标准化、study card 模板填充
• 不负责 证据矩阵构建（那是 S10 的职责）
• 不负责 偏倚风险评估（那是 S11 的职责）

Trigger When

全文 PDF 可获取

Do Not Trigger When

study_cards 已达到阈值

Required Inputs

• pdfs/
• benchmark_reviews.csv
• project_brief.json

Optional Inputs

• Sci-Hub / Unpaywall 访问策略配置
• 机构图书馆代理设置

Output Contract

1. 所有输出文件写入 /artifacts/run-<ts>/stage-2/ 目录下
2. 结构化输出（.json / .csv）优先于叙述性输出（.md），必须通过 schemas/ 下对应 JSON Schema 校验
3. 每个输出产物在 artifact registry 中注册时，须记录其上游依赖、生成时间、生成器和版本号
4. 产物格式优先级：结构化数据 (.json) > 表格 (.csv) > 叙述性 Markdown (.md) > 自由文本
5. 产物路径和命名遵循 configs/artifact_registry_rules.json 中定义的规范

Expected Outputs

• study_cards/
• fulltext_bundles/
• fulltext_texts/
• reading_notes/
• pdf_download_manifest.json

fulltext_bundles/*.json 必须统一承载 PMC OA TGZ/JATS、PMC/HTML、PDF text、abstract-only fallback 的标准化结果，并保留 parse_status、section_index、figure_table_index、parser_metadata、normalization_warnings、fallback_reason 与 acquisition provenance。JATS 中的 figure caption / table note 必须进入 section-aware contract，不得只保留在索引里。

Operational Steps

1. 验证所有 Required Inputs 存在且可读，缺失则立即停止并报告
2. 加载相关 Schema 和契约文件（schemas/ 目录下）
3. 仅执行 Purpose 与 Scope of Responsibility 中定义的任务，不漂移到相邻 skill 的职责
4. 先产出结构化数据（.json / .csv），再生成叙述性说明（.md）
5. 记录所有假设、未解决的歧义和失败追踪信息
6. 若置信度不足（如关键数据缺失导致无法做出科学判断），停止执行并升级给人工，不得猜测或编造

Decision / Writing / Validation Principles

• 结构化字段优先：先填满 schema 的 required 字段，再补充 optional 字段
• 证据三元组：每个科学论断必须包含 (source_id, finding_direction, evidence_strength)
• 冲突分类：如发现证据方向矛盾，标记为 direction_conflict 而非强行选边
• 术语一致性：同一实体在全文中使用统一的 canonical term（参见 configs/ontology/）
• 保守推断：不在证据不足时声称"clearly" "definitively" "proves"

Hard Constraints

• 不得编造 DOI、PMID、样本量、统计值、期刊身份或研究结论
• 不得静默覆盖已有高版本 artifact（必须 version incrementally，参见 AGENTS.md）
• 不得删除上游可审计痕迹（raw exports、screening decisions、extraction logs 必须保留）
• 不得绕过 Gate 或把 QA 结论写成"已人工确认"（除非真正通过了人工审核）
• 不对原文未提供的数据做任何推断
• 区分'作者说了什么'与'数据显示了什么'
• 不将动物实验结果直接陈述为人类临床事实
• PMC OA TGZ/JATS 解析失败时不得伪造全文结构；必须记录 parser error / normalization warning，并按 PDF/HTML/abstract fallback 顺序降级

QA Hooks

• Q02

Human-in-the-Loop Checkpoint

• 产出物完成后，进入 G2 等待人工审核
• 审核通过前，下游 skill 不得启动
• 若人工审核要求修订，返回上游 skill（参见 orchestrator/state_machine/transitions.yaml）

Acceptance Checklist (Self-Verification Before Declaring Done)

• 所有 Required Inputs 已加载且完整
• 所有 Expected Outputs 已生成且非空
• 结构化输出通过对应 JSON Schema 校验
• 产物已在 artifact registry 中注册（含 checksum + version）
• QA hooks 中列出的所有 QA skill 已触发
• decision_log.md 记录了关键决策及其理由

Failure Handling

• 缺少输入: 发出 blocking error，立即停止，不继续执行
• Schema 校验失败: 重试一次（带错误上下文修正）；若第二次仍失败，升级给 checkpoint manager
• 下游污染风险: 如果当前产物可能影响下游 skill 的正确性，标记为 status: blocked，阻止流水线继续
• 领域特定失败: 若 study_cards 完成率 <70% 纳入文献 → warning
• 重试耗尽: 若达到 orchestrator/retry_policies/ 中定义的最大重试次数，升级给人工

Logging and Observability

每个 skill 必须产出以下日志文件（写入 /artifacts/run-<ts>/logs/S09/）：

• input_manifest.json — 所有输入的路径和校验和
• output_manifest.json — 所有输出的路径和校验和
• validation_result.json — Schema 校验结果
• decision_log.md — 关键决策及其理由
• failure_trace.md — 失败时的错误堆栈（如有）

Collaboration Notes for Codex / Orchestrator

• 执行前先读取 AGENTS.md 获取项目级非协商规则
• 执行前先读取 configs/skills_manifest.json 确认本 skill 的上下游依赖
• 产物注册使用 orchestrator/artifact_registry/registry_v2.py 的统一接口

Definition of Done

1. 所有 Expected Outputs 已写入磁盘并通过 Schema 校验
2. 所有 Required QA Hooks 已触发并获得非 blocking 结果
3. 产物已在 artifact registry 中注册，具备完整的 provenance 记录

Examples

Example study card (excerpt)

{
  "source_id": "PMID:34567890",
  "citation_key": "Zhang_2024",
  "study_type": "in_vivo + in_vitro",
  "model_system": "ApoE-/- mice + primary mouse VSMCs",
  "key_findings": [
    {"finding": "lncRNA-X knockdown reduced plaque area by 35% in ApoE-/- mice (p<0.01, n=8/group, Fig 2C)", "support": "Fig 2C"},
    {"finding": "lncRNA-X acts as ceRNA for miR-155, derepressing contractile marker SMA (Fig 4)", "support": "Fig 4A-D"}
  ],
  "review_relevance": 5,
  "review_relevance_note": "Directly addresses mechanism of lncRNA-mediated VSMC phenotypic switch in atherosclerosis model"
}