科研 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.
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,
keywordsis 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"):
- Set
based_on:in the source-page frontmatter —review | preprint | prior-version(defaultoriginal, omitted ororiginalotherwise). - 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`). - Mark the log line:
- YYYY-MM-DD · ingest · [[slug]] · based_on: preprint (user-approved substitute) · focus: «<focus>» - Keep the source on
acquisition-todo.mdso the original is still acquired later; on re-ingest of the original, flipbased_onback tooriginaland 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 ## Connections | type |
|---|---|
| confirms / agrees with / corroborates | supports |
| contradicts / rejects / argues against | contradicts |
| supplements / extends / builds on | builds-on |
| draws on / cites / relies on | cites |
| (generic association, no stance) | mentions |
| answers / engages / replies to an earlier work | responds-to |
| replaces / renders obsolete / overturns an earlier position | supersedes |
| the same author corrects or abandons their own earlier position | revises |
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 inbecause.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:
type | Meaning | Typical wording in the source |
|---|---|---|
responds-to | engages an earlier work explicitly; the debate stays open | "contra X", "in reply to", "X has argued … but" |
supersedes | replaces an earlier position, which in this respect no longer stands | "can no longer be maintained", "is now ruled out by" |
revises | the 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:
basis | The later work has … |
|---|---|
new-evidence | finds, data or texts the earlier work could not know |
new-method | the same material under a different method (new calibration curve, statistical model) |
reinterpretation | the same material and method, read differently |
argument | a 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
| Thought | Reality |
|---|---|
| "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>.pdfis 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: extractedonly 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
stableafter 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.
示例提示词
帮我把这篇文章按当前研究焦点提炼成知识库中的来源页面并更新文献。
所属插件
安装该插件会一并获得同领域的 62 个 Skill / MCP。
同插件的其他科研 Skill
- 学术文献获取下载Auto-downloads open-access PDFs for graded sources and writes a manual worklist for paywalled items. Use after literature-review, before ingest-source.
- 单篇文献入库管理Adds one verified PDF to a shared bibliography library, computing its citation key and keywords. Use to register a single document outside the full workflow.
- 数字人文计算方法Surveys computational DH methods: text mining, NLP, corpus linguistics, archive standards, GIS, network analysis, and OCR. Use for an overview of available DH tools.
- 考古地理信息系统分析Runs archaeological GIS analysis with GeoPandas: catchment analysis, viewshed, kernel density, spatial statistics. Use for mapping archaeological site locations.
- 论证结构提取可视化Extracts and visualizes argument structure: Toulmin reconstruction, support/attack graphs, circularity detection. Use to diagram an argument’s logical structure.
- 考古遗物类型学分析Performs artifact analysis: typological classification, ceramic attribute coding, lithic reduction analysis. Use when classifying excavated artifacts statistically.
- 引文与出处核查Checks citations, quotations, page numbers, and bibliography entries for accuracy and source fit. Use before submission to verify source-supported claims.
- 研究选题构思设计Explores research intent, field state, methodology, and ethics, then writes an approved design doc. Use before starting a new research question or chapter.
- 术语译名一致性检查Audits a manuscript for terms, translations, abbreviations, and names whose forms must stay stable. Use when terminology drift could undermine an argument.
- 计算语用学分析Runs computational pragmatics: speech act classification, implicature detection, discourse coherence, politeness analysis. Use for language-use-and-meaning studies.
- 文献综述学术对话构建Turns verified sources into a structured scholarly conversation among positions, not a chronological summary. Use when synthesizing literature into a debate narrative.
- 语料库语言学分析Performs corpus analysis with NLTK/spaCy: collocation, keyword analysis, KWIC concordance, word2vec, diachronic trends. Use for quantitative text-corpus research.
- 数字档案馆资源检索Queries digital archive REST APIs: Europeana, Chronicling America, Internet Archive, HathiTrust, DPLA, OAI-PMH. Use when searching or harvesting heritage metadata.
- 学术手稿章节撰写Drafts a chapter or article section by section from synthesized wiki content, agreeing each section’s argument first. Use to turn stable research synthesis into prose.
- 研究项目漂移状态检测Checks a shared source library and registered projects for drift: un-indexed PDFs, unmerged keywords, bibkey collisions. Use to audit a multi-project research setup.
- EMI课堂语料转写分析Segments and annotates classroom transcripts, coding language choice and discourse function with anonymised output. Use to quantify classroom talk or translanguaging.
- 人工智能伦理分析Analyzes AI ethics: algorithmic fairness metrics, bias auditing, value alignment, moral philosophy reasoning. Use to evaluate an AI system’s ethical dimensions.
- 研究计划任务执行Executes a ready research plan task by task, gating acquisition before ingest and dispatching analysis. Use after writing-research-plan to run the planned work.
- 研究项目结项清单Runs the final completion checklist: rendering, bibliography, wiki, data, reproducibility, archiving. Use when a manuscript is finalized and ready to publish.
- 形式逻辑自动推理Applies formal logic tools: Z3 SMT solver, modal logic S5, SAT encoding, Lean4 proof verification. Use to formalize or mechanically check a logical argument.
- 研究问题凝练构建Turns a broad topic or intuition into a precise, contestable, researchable question. Use at the start of a project when no defensible question yet exists.
- 历史地理信息系统分析Performs historical GIS work: georeferencing old maps, digitizing boundaries, temporal territory overlays, population interpolation. Use for historical spatial analysis.
- 历史语言学比较分析Analyzes historical linguistics in Python: sound correspondences, cognate detection, phylogenetic trees, Swadesh lists. Use when reconstructing language relationships.
- 历史社会网络分析Builds historical network analyses: correspondence networks, prosopography, temporal community detection, Gephi export. Use to map relationships among historical actors.
常见问题
文献入库知识页生成能做什么?
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 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。