科研 Skill

文献入库知识页生成

ingest-source

Adds one acquired source to a project wiki with a focus-driven summary, extracted entities, and a bibliography entry. Use to intake a downloaded PDF into project knowledge.

发布者 Codar安全审核通过v0.1.0更新于 2026-11-18

SKILL.md

Ingest Source (focus-driven)

Turn a raw scholarly source into structured wiki content scoped to a specific focus — what this project takes from this source. The wiki is purpose-built, not a generic archive. The raw PDF stays in the shared library and can be re-read later under a different focus.

One source × focus → one focus block inside knowledge/sources/<slug>.md. Re-ingest with a different focus → a second focus block appended to the same page. One bibkey, one wiki page, multiple lenses stacked over time.

Announce at start: "Using ingest-source to add <source> to the wiki under focus: <focus>."

If any condition is missing: explain to the user which, ask for a short reason for skipping, write it to knowledge/_meta/gate-overrides.log, and close out the ingest.

When to use

  • A new PDF/book/article has been acquired (via acquire-sources, or dropped in by the user) and serves a specific aspect of the project's research question
  • User says "ingest this source", "ingest Finkelstein 2003 focused on the Megiddo stratigraphy", "add this to the wiki for the chronology question"
  • Re-reading an already-ingested source under a new focus (a new chapter draws on a different aspect of the same source)
  • Batch ingest from a literature list — loop this skill, one source per iteration, focus repeated or per-source

NOT for: modifying existing focus blocks (edit directly), pure BibTeX-only entries without reading (edit the .bib directly, or add-to-library for a PDF you only want catalogued), or single-fact lookups.

Checklist

Create a task-list item for each:

Moved to references/checklist.md to keep this file short; read it when this part is needed.

Re-ingest detection

When step 5 finds an existing source page:

  • Read the existing page. Count the ## Focus: headings already present.
  • Inform the user: "Source <slug> is already ingested with N focus block(s): [list focus strings + dates]. Proceeding will append a new focus block for the current focus."
  • Same-focus warning: if a focus block within the last 14 days matches the current focus string closely (case-insensitive substring), warn: "A recent focus block looks similar: «». Append anyway, update the existing block, or cancel?"
  • Legacy migration: if the existing page predates v0.5 (no ## Focus: headings, uses old ## Core Theses / ## Method / etc.), offer: "Wrap the existing content as ## Focus: (legacy — full summary) — <original updated date> before appending the new focus block?" User chooses; if declined, just append the new focus block alongside the old structure.
  • Mode logged: the agent output report names the mode (fresh | append-section | update-existing-focus | legacy-wrap).
  • Keywords accrete too. Unlike the rest of the BibTeX entry, keywords is unioned with any newly-recognized terms from this focus pass — see step 11 and "BibTeX Entry Convention" below.

Provenance of substitutes

The default and the norm is to ingest the original cited work. When the original cannot be acquired (paywalled, not yet downloaded), the honest move is to stop and route the user to acquisition-todo.md — not to quietly read a preprint, a prior version, or a book review in its place. A substitute has different pagination and sometimes different claims; ingesting it under the original's bibkey silently corrupts provenance.

Only when the user explicitly consents to ingest a substitute (e.g. "go ahead and ingest the preprint for now"):

  1. Set based_on: in the source-page frontmatter — review | preprint | prior-version (default original, omitted or original otherwise).
  2. Add a callout at the top of the focus block:
    > [!warning] Provenance: based on the **preprint**, not the published original.
    > Pagination and final claims may differ. Re-ingest the original when acquired
    > (set `based_on: original`).
    
  3. Mark the log line:
    - YYYY-MM-DD · ingest · [[slug]] · based_on: preprint (user-approved substitute) · focus: «<focus>»
    
  4. Keep the source on acquisition-todo.md so the original is still acquired later; on re-ingest of the original, flip based_on back to original and remove the callout.

The based_on field is optional in the schema (schema/knowledge-frontmatter.schema.json) — original pages need no entry.

Process Flow

digraph ingest {
    "Determine focus" [shape=box];
    "Default proposed?" [shape=diamond];
    "Confirm/refine focus" [shape=box];
    "Locate source file" [shape=box];
    "Original present?" [shape=diamond];
    "HARD-STOP: point to acquisition-todo" [shape=box];
    "User consents to substitute?" [shape=diamond];
    "Record provenance (based_on)" [shape=box];
    "Scanned PDF?" [shape=diamond];
    "OCR the scan (ocrmypdf)" [shape=box];
    "Read source under focus" [shape=box];
    "Derive slug" [shape=box];
    "Source page exists?" [shape=diamond];
    "Re-ingest mode" [shape=box];
    "Fresh ingest" [shape=box];
    "Extract bibdata" [shape=box];
    "Identify focus-relevant entities" [shape=box];
    "Create or append page" [shape=box];
    "Derive typed relations" [shape=box];
    "Create/extend entity pages" [shape=box];
    "Add BibTeX" [shape=box];
    "Append log" [shape=box];
    "Run wiki-lint" [shape=box];
    "Lint green?" [shape=diamond];
    "Fix issues" [shape=box];
    "Done" [shape=doublecircle];

    "Determine focus" -> "Default proposed?";
    "Default proposed?" -> "Confirm/refine focus" [label="yes"];
    "Default proposed?" -> "Confirm/refine focus" [label="no — ask explicitly"];
    "Confirm/refine focus" -> "Locate source file";
    "Locate source file" -> "Original present?";
    "Original present?" -> "Scanned PDF?" [label="yes"];
    "Original present?" -> "User consents to substitute?" [label="no"];
    "User consents to substitute?" -> "HARD-STOP: point to acquisition-todo" [label="no"];
    "User consents to substitute?" -> "Record provenance (based_on)" [label="yes"];
    "Record provenance (based_on)" -> "Scanned PDF?";
    "Scanned PDF?" -> "OCR the scan (ocrmypdf)" [label="yes"];
    "Scanned PDF?" -> "Read source under focus" [label="no"];
    "OCR the scan (ocrmypdf)" -> "Read source under focus";
    "Read source under focus" -> "Derive slug";
    "Derive slug" -> "Source page exists?";
    "Source page exists?" -> "Re-ingest mode" [label="yes"];
    "Source page exists?" -> "Fresh ingest" [label="no"];
    "Fresh ingest" -> "Extract bibdata";
    "Re-ingest mode" -> "Identify focus-relevant entities";
    "Extract bibdata" -> "Identify focus-relevant entities";
    "Identify focus-relevant entities" -> "Create or append page";
    "Create or append page" -> "Derive typed relations";
    "Derive typed relations" -> "Create/extend entity pages";
    "Create/extend entity pages" -> "Add BibTeX";
    "Add BibTeX" -> "Append log";
    "Append log" -> "Run wiki-lint";
    "Run wiki-lint" -> "Lint green?";
    "Lint green?" -> "Fix issues" [label="no"];
    "Fix issues" -> "Run wiki-lint";
    "Lint green?" -> "Done" [label="yes"];
}

Source Page Template

Frontmatter follows the central schema at schema/knowledge-frontmatter.schema.json in the project root. Required fields for source pages: title, type: source, created, updated, status, author, bibkey. On first ingest, a…

Moved to references/source-page-template.md to keep this file short; read it when this part is needed.

Typed relations

The relations: frontmatter block is what turns a flat wikilink into a typed, confidence-tagged edge in the knowledge graph. scripts/wiki-to-graph.py reads it directly: a wikilink becomes a generic wikilink edge, but a relations: entry becomes an edge carrying your type and confidence (and the because shows up in the graph viz and the relations queries). Writing it at ingest time means the graph is born typed instead of needing a later hardening pass.

What gets an entry — and what does not. Add a relations: entry for every connection where this source takes a stance toward another page: it confirms, contradicts, supplements, builds on, or cites it. Do not add entries for plain "this entity appears here" mentions — those are already covered by the ## Mentioned entities wikilinks (which become wikilink edges anyway).

Direction. The relation runs from this source page to the target: finkelstein-2003 --contradicts--> high-chronology.

target is the bare page slug (e.g. high-chronology, mazar-2011) and must resolve to an existing page — lint-wiki.py flags a relation to a missing page. If the target page does not exist yet, create it (concept/entity) or leave the connection as prose only until it does; never point a typed relation at a dangling target.

type — recommended controlled vocabulary (free-form is allowed, but sticking to these keeps relations --type … queries useful):

Prose in ## Connectionstype
confirms / agrees with / corroboratessupports
contradicts / rejects / argues againstcontradicts
supplements / extends / builds onbuilds-on
draws on / cites / relies oncites
(generic association, no stance)mentions
answers / engages / replies to an earlier workresponds-to
replaces / renders obsolete / overturns an earlier positionsupersedes
the same author corrects or abandons their own earlier positionrevises

confidence — be honest, lint measures it. lint-wiki.py reports the inferred + ambiguous share as the wiki's inference-rate, so do not inflate to extracted:

  • extracted — explicitly supported by this source, ideally with a verbatim quote and page in because.
  • inferred — a defensible link you are adding, not stated in the source (e.g. "shares the dating method of X"). The honest default when there is no quote.
  • ambiguous — the relation is real but its type/direction is unclear.

because is one line, ideally a quote + page for extracted entries. It is the natural place to ground an inferred relation later: when you find the supporting passage, add the quote and flip confidence to extracted.

relations:
  - target: high-chronology
    type: contradicts
    confidence: extracted
    because: "«The conventional dating of Megiddo VA–IVB to the 10th century cannot be sustained» (p. 156)."

Research chronology

Two sources in a wiki are not two equal voices. One was written knowing the other, and often knowing finds the other could not. Researchers also change their minds. A wiki that records only "A contradicts B" loses this, and a manuscript drafted from it sets a position from 1996 beside one from 2020 as if both were on the table today.

When a source is dated. By the year in its bibkey — there is no separate publication-year field. Two optional frontmatter fields correct the cases where that year misleads:

orig_year: 1996        # the text is a reprint / translation / unrevised later edition
evidence_until: 2005   # data cut-off the source itself states (last season, dataset, curve)

Set orig_year when the edition you cite is later than the text. Do not set it for a revised edition whose argument changed. Set evidence_until only when the source says what it could take into account; do not estimate it.

Three relation types are directed in time. They run from the later source to the earlier one, and lint-wiki.py fails the build when the dates say otherwise:

typeMeaningTypical wording in the source
responds-toengages an earlier work explicitly; the debate stays open"contra X", "in reply to", "X has argued … but"
supersedesreplaces an earlier position, which in this respect no longer stands"can no longer be maintained", "is now ruled out by"
revisesthe same author corrects their own earlier position"I previously argued", "contrary to my earlier view"

contradicts remains the type for a disagreement that is live on both sides.

basis says why the later work departs from the earlier one:

basisThe later work has …
new-evidencefinds, data or texts the earlier work could not know
new-methodthe same material under a different method (new calibration curve, statistical model)
reinterpretationthe same material and method, read differently
argumenta logical or conceptual objection

Later is not the same as right. A 2022 paper that ignores a 2015 rebuttal has not superseded it. Write supersedes with confidence: extracted only when the later source engages the earlier one by name and says the earlier position fails; otherwise use responds-to, or contradicts if it does not engage it at all. Self-revision is the strongest case and the easiest to miss — search the source for the author's own earlier works in the bibliography and for first-person retractions.

No edges forward in time. A 2003 source cannot take a stance on a 2011 one. When you ingest an older source and the wiki already holds its later answer, put the edge on the later page and leave a prose pointer in this page's ## Connections ("Later response: [[mazar-2011]]"). lint-wiki.py reports forward-pointing stance edges as ANACHRONISM.

MCP Optimisation (recommended)

For the BibTeX entry (step 10): Instead of formatting by hand, fetch the ready-made reference string:

Moved to references/mcp-optimisation-recommended.md to keep this file short; read it when this part is needed.

BibTeX Entry Convention

Key = slug exactly. Example:

@article{finkelstein-2003,
  author   = {Finkelstein, Israel},
  title    = {The Low Chronology and the Problem of the Archaeology of Iron Age Palestine},
  journal  = {Tel Aviv},
  volume   = {30},
  number   = {2},
  year     = {2003},
  pages    = {149--174},
  doi      = {10.1179/tav.2003.2003.2.149},
  keywords = {low chronology; Iron Age chronology; Megiddo stratigraphy}
}

keywords is semicolon-separated (the Zotero / Better-BibTeX export convention): 3–8 terms, the canonical name plus known synonyms and aliases — this is what bib-search.py searches when a source describes a method in prose without ever naming it (see that script's module docstring and drafting-manuscript's "Searching for a concept, not a string").

A quick self-test before moving on: run the concept search a later drafter would run —

python scripts/bib-search.py '"<canonical name>"' --q '<alias 1>' --q '<alias 2>'

If the alias queries alone would find this source on the pages that matter, the keywords are a bonus. If they would not — the prose-only case — the keywords you just wrote are the only mechanism that will surface it (--q fusion changes ranking, never recall), and a keyword hit prints first, ahead of every page hit. That asymmetry is why thin-but-honest keywords beat none, and why terms the paper itself never uses are exactly the ones worth recording.

If a key collides (e.g. two Finkelstein 2003 papers), append a letter: finkelstein-2003a, finkelstein-2003b. Update the source-page filename accordingly. On re-ingest with a new focus, the BibTeX entry is not changed — it's the same source — except keywords: newly-recognized terms are unioned in, deduped case-insensitively.

Log Entry Convention

Append a single line to knowledge/_meta/log.md:

- YYYY-MM-DD · ingest · [[finkelstein-2003]] · focus: «<focus string>»
- YYYY-MM-DD · re-ingest · [[finkelstein-2003]] · focus: «<new focus>» (now N focus blocks)

Subagent Dispatch (optional)

For batch ingest (≥ 3 sources), dispatch source-ingester subagent per source (see agents/source-ingester.md). The subagent gets fresh context with this skill preloaded (its skills: frontmatter; embed this skill's content in the prompt only on a host without preloading) and the prompt passes the source PDF + the project frontmatter schema + the focus string. Main conversation reviews the diff after each ingest.

Red Flags

ThoughtReality
"I can't get the original, I'll just ingest the book review / preprint"No — HARD-STOP. Wrong pagination, second-hand claims, silent misattribution under the original's bibkey. Point the user to acquisition-todo.md; ingest a substitute only with explicit consent, recorded as based_on: provenance.
"I'll just summarise the whole source — that's safer"No. A summary is undifferentiated prose that retells the source at half length; it obscures what the project needs and answers no question. Kernthesen are not that: they are enumerated, page-anchored, weighted claims, and they stop. Writing twenty theses with their reasons is the opposite of retelling forty pages — it is the work of deciding what the twenty are.
"The Kernthesen can just restate what the focus needs"No — then the page has two focus blocks under different names and still cannot answer a question it was not written for. Kernthesen are the SOURCE's theses, including the ones this project has no use for today.
"Ten theses is a lot; I'll write five good ones"The floor is ten at depth: standard. If the source genuinely has fewer load-bearing claims, it is a map source or the reading was too quick — say which.
"The section map is obvious, I'll skip it"It is the cheapest section to write and the only one that answers "do I need to re-read this?". Skipping it is what made 131 of 136 pages unable to answer that.
"The user said this article is important — I'll write more this time"Write more AND set depth: deep. An instruction that lives only in this conversation is gone next session; the frontmatter field survives.
"The abstract gives me the claims relevant to my focus"No — claims relevant to a focus often live in a specific section, not the abstract. Full text under the focus lens.
"The default focus from project-description.md is good enough"Sometimes yes, often no — the project's research question is usually too broad to be a useful per-source focus. Refine for this specific source.
"I'll fill in entities later"Then they stay unlinked. Create them now (only the focus-relevant ones; rest stays in the PDF).
"I'll do BibTeX at the end of the day"The source key IS the BibTeX key — without the entry, lint fails.
"Skipping keywords is fine — bib-search's --q fusion will find this source later"No — fusion re-ranks what some alias literally matches; it adds zero recall. A source that names its method only in prose is invisible to every alias query, and the ingest moment — source just read, vocabulary fresh — is the one chance to record the terms that make it findable.
"Re-ingest means I should overwrite the old focus block"No — append. The old focus is still valid (the project still needs that aspect). New focus = new block.
"If two focuses are similar I'll just pick one"The skill warns at similar-focus detection but the user decides. Don't pretend two focus questions are the same when they aren't.
"I'll just leave the contradiction as a [[wikilink]]"Then the graph sees a generic edge and loses the stance. Mirror every confirms / contradicts / builds-on / cites into a typed relations: entry — that is the whole point of the typed-edge layer.
"The qualifier is a detail — the gist is what matters"The qualifier often is the claim. Dropping "in the excavated area" or "probably" turns a local, hedged finding into a general one the author never made — and the draft will cite it under their name.
"I'll mark every relation extracted so it looks solid"No — extracted means a quote + page backs it. Model-added links are inferred. Lint reports the inference-rate; inflating it is dishonest and hides which edges still need grounding.

Key Principles

  • Focus-driven, not summary-driven — the wiki documents what THIS project takes from THIS source. Generic content stays in the PDF.
  • One source = one wiki page, multiple focus blocks — append over time as the project's needs evolve.
  • The raw PDF is the archive — <library>/pdf/<bibkey>.pdf is the canonical "everything"; the wiki is the interpretation.
  • Wikilinks before full prose — link every focus-relevant entity at first mention.
  • Typed relations at ingest — stance-bearing connections (confirms / contradicts / builds-on / cites) go into the relations: frontmatter as typed, confidence-tagged edges, not just prose wikilinks. The graph is born typed; confidence: extracted only with a quote + page.
  • Verbatim quotations + page — indispensable for drafts later; at least 1 quote per focus block.
  • Capture the examples, not just the claims — the concrete cases a source uses (an artefact, site, dataset, passage) are what let a later draft develop a point instead of reflowing a bullet. Record them (or their page anchor) in ### Examples & illustrations; a claim page with no examples produces dense prose downstream.
  • Status: review on first pass — only moves to stable after user review.
  • Explicit boundaries — name what the source does NOT address (within the focus). This honesty saves later confusion.
  • Scope-faithful — every thesis and claim keeps the source's hedges, scope and conditions; a summary that is wider than its source is a misquotation.

示例提示词

帮我把这篇文章按当前研究焦点提炼成知识库中的来源页面并更新文献。

所属插件

人文学科面向历史、哲学、语言学、考古与艺术研究:TEI/OCR 与数字档案、论证分析、语料库与语音学、放射性碳测年、乐谱与音频分析,以及人文论证写作与审稿。

安装该插件会一并获得同领域的 62 个 Skill / MCP。

同插件的其他科研 Skill

常见问题

文献入库知识页生成能做什么?

Adds one acquired source to a project wiki with a focus-driven summary, extracted entities, and a bibliography entry. Use to intake a downloaded PDF into project knowledge。

如何安装文献入库知识页生成?

在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「文献入库知识页生成」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。

文献入库知识页生成需要哪些权限?

该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。

文献入库知识页生成经过官方审核吗?

是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。