科研 Skill

知识库结构校验

wiki-lint

Validates a wiki’s structural integrity: frontmatter completeness, broken links, orphaned pages, status. Use before drafting or finishing to catch structural errors.

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

SKILL.md

Wiki Lint

Run the wiki linter and act on its findings. Mandatory gate before drafting-manuscript and finishing-a-research-project; useful after bulk ingest or whenever the wiki has grown.

Announce at start: "Using wiki-lint to validate the knowledge tree."

If not met: tell the user which classes of issues remain (errors / warnings / orphans), ask for a short reason to proceed anyway (e.g. "orphan is intentional — it's the index page"), and write the reason into knowledge/_meta/gate-overrides.log. Errors should as a rule be fixed rather than overridden — the override is an audit trail, not a substitute.

When to use

  • Before drafting-manuscript (soft gate)
  • Before finishing-a-research-project (soft gate)
  • After ingest-source batch runs (≥ 3 new sources)
  • When user says "clean up the wiki", "lint", "check the wiki"
  • Periodically when the project is long-running

Checklist

  1. Locate the lint script — scripts/lint-wiki.py in the project root (from template)
  2. Run it — python scripts/lint-wiki.py. If Python or PyYAML or the script itself is missing, take the Python-free fallback path below.
  3. Parse output into categories: errors, warnings, orphans
  4. Fix errors inline (missing frontmatter fields, broken wikilinks, invalid type values)
  5. Assess warnings — stale pages, status inconsistency, empty sections — decide with user: fix / defer / ignore
    • Read the === Research chronology === section — CHRONO-ORDER (a responds-to / supersedes / revises edge pointing from an earlier source to a later one) fails the run: move the edge to the later page, or set orig_year if a date is wrong. ANACHRONISM and SUPERSEDED-CITED are advisory: the first is fixed by moving the edge, the second is a question for the author — is the older source cited as history or as the current state?
  6. Review the open review flags — the === Review flags === section lists open review_flags (content findings from semantic-wiki-review). These do not fail the exit code, but they gate drafting (see drafting-manuscript): decide with the user per flag — fix the underlying issue and set state: resolved, or leave it open and let drafting log an override. Do not clear a flag by deleting it.
  7. Check authority-ID coverage — the === Authority-ID coverage (entities) === section reports how many entities carry a gnd_id / idai_gazetteer_id / wikidata_qid and lists the untagged (--verbose). Advisory only. For persons and places, resolve and add the ID (via dao-paper-search resolve_author / resolve_site) — it is the join key for cross-project linkage (wiki-global-graph.py overlap); datasets / methods / software may legitimately have none. Work the untagged list rather than letting it accumulate.
  8. Handle orphans — pages with no incoming wikilinks: decide link-in, delete, or mark as root
  9. Re-run lint until exit 0 on errors
  10. Log the run in knowledge/_meta/log.md with summary (N errors fixed, N warnings deferred, N open flags)
  11. Dispatch wiki-linter subagent (optional) for large wikis — see agents/wiki-linter.md

See also: scripts/wiki-to-graph.py is the sibling tool for structure analysis (not validation) — it exports the wiki as a graph (graph.json / graph.graphml) and reports god_nodes (most-connected pages) and bridges (entities joining otherwise-unconnected sources). Useful after a lint pass to spot hubs and weak links; it reads the same relations frontmatter the linter validates.

Python-free fallback

For users on Cowork or any environment without a shell — or any project where python3 / pyyaml / scripts/lint-wiki.py are simply not available — the skill performs frontmatter validation inline.

Trigger the fallback automatically when:

  • scripts/lint-wiki.py does not exist in the project, OR
  • the Bash tool is not available, OR
  • running the script returns a "command not found" error for python3 or python, OR
  • the user explicitly says "lint without Python" or "use the inline check"

Tell the user upfront:

"Running wiki-lint in fallback mode (no Python). This checks frontmatter but skips wikilink resolution and orphan detection — those would cost too many tokens on a full wiki scan. For a complete check, install Python+PyYAML and use the scripts/lint-wiki.py script. Recommended for projects above ~20 pages."

Fallback procedure:

  1. Read schema/knowledge-frontmatter.schema.json from the project root. If absent, read the plugin's copy (the plugin ships one).
  2. List every knowledge/**/*.md file (excluding files prefixed _example-).
  3. For each file: parse the YAML frontmatter (the block between the first two --- lines) and validate against:
    • required fields exist and are non-empty
    • type is one of entity | concept | source | synthesis
    • status is one of draft | review | stable
    • author is one of human | llm | mixed
    • created and updated match the ISO date pattern ^\d{4}-\d{2}-\d{2}$
    • if type: source, then bibkey is present
    • if wikidata_qid is present, it matches ^Q\d+$
    • if idai_gazetteer_id is present, it matches ^\d+$
  4. Report any failures in the same format as the Python script: MISSING: <path> — required field '<field>' is missing / INVALID: <path> — <field>='<value>' (allowed: …).
  5. Print a status summary: total pages, draft/review/stable distribution.
  6. Surface open review_flags — these live in frontmatter, so the fallback can list them cheaply (page, kind, detail). Report count + list, exactly as the script's === Review flags === section does; they are advisory (gate drafting, not this check).
  7. Explicitly skip wikilink resolution and orphan detection. State this in the output so the user knows what's not covered.

What the fallback does NOT do:

  • Broken-wikilink detection (would need to read every page's body, then cross-reference — O(N²) in tokens).
  • Orphan-page detection (same reason).
  • Gate-override-rate reporting (the override log lives in the project; the fallback could read it but the Python script's output format is more concise).

If those checks are needed and Python isn't an option, dispatch the wiki-linter subagent (agents/wiki-linter.md) — it has a fresh context budget and can afford the full scan once per session.

Process Flow

digraph lint {
    "Locate lint script" [shape=box];
    "Run lint-wiki.py" [shape=box];
    "Parse output" [shape=box];
    "Errors present?" [shape=diamond];
    "Fix errors inline" [shape=box];
    "Warnings: fix / defer / ignore" [shape=box];
    "Orphans: link / delete / mark root" [shape=box];
    "Re-run lint" [shape=box];
    "Exit 0 on errors?" [shape=diamond];
    "Log run summary" [shape=box];
    "Done" [shape=doublecircle];

    "Locate lint script" -> "Run lint-wiki.py";
    "Run lint-wiki.py" -> "Parse output";
    "Parse output" -> "Errors present?";
    "Errors present?" -> "Fix errors inline" [label="yes"];
    "Errors present?" -> "Warnings: fix / defer / ignore" [label="no"];
    "Fix errors inline" -> "Warnings: fix / defer / ignore";
    "Warnings: fix / defer / ignore" -> "Orphans: link / delete / mark root";
    "Orphans: link / delete / mark root" -> "Re-run lint";
    "Re-run lint" -> "Exit 0 on errors?";
    "Exit 0 on errors?" -> "Fix errors inline" [label="no"];
    "Exit 0 on errors?" -> "Log run summary" [label="yes"];
    "Log run summary" -> "Done";
}

What lint-wiki.py Checks

(per the template's scripts/lint-wiki.py)

  • Frontmatter present + required fields (title, type, created, updated, status, author)
  • type ∈ {entity, concept, source, synthesis}
  • status ∈ {draft, review, stable}
  • author ∈ {human, llm, mixed}
  • Dates are ISO (YYYY-MM-DD)
  • Wikilinks [[...]] resolve to existing files
  • No duplicate page titles within a section
  • Orphan detection (pages with zero incoming wikilinks)
  • Structured relations blocks resolve + the inference-rate (share of inferred/ambiguous edges)
  • Open review_flags (content findings from semantic-wiki-review) — surfaced only: advisory, they gate drafting-manuscript, not the lint exit code
  • Citekeys and bibliography — every citekey matches the surname-year-shorttitle convention (it is a cross-project join key); no key defined twice; every bibkey: and every @citation resolves to a real entry; every bibliography: path a manuscript declares exists (Quarto renders a dead bibliography as ??? and still exits 0)
  • The shared library, both directions — advisory, and skipped when no library is configured (CI has none):
    • every source page's bibkey has a PDF at <library>/pdf/<bibkey>.pdf
    • every acquired PDF has a source page — "acquired but NOT ingested". A source that was searched for, downloaded and then forgotten is invisible to every other check: the wiki looks healthy, and drafting has nothing to reach back into. Across 17 live wikis this was true of 146 sources; one project had 48 of its 55 PDFs never ingested. The fix is ingest-source — the PDFs are already there.

Common Fixes

ErrorFix
missing frontmatter field: statusAdd status: draft (or proper value)
broken wikilink: [[finkelstein-2003]]Either create knowledge/sources/finkelstein-2003.md via ingest-source, or correct the slug
invalid type: PersonChange to entity (types are: entity, concept, source, synthesis)
created is not ISO dateReformat to YYYY-MM-DD
orphan: knowledge/entities/foo.mdAdd an incoming link from a relevant source/synthesis page

Red Flags

ThoughtReality
"Lint is bureaucracy, skip it"SOFT-GATE before drafting and finishing. The override gets logged.
"I'd notice broken wikilinks while reading"No — when rendered they vanish silently. They're only visible to the linter.
"Orphans are fine, just internal notes"Orphan means unreachable. Link them in or delete them.
"I can ignore all warnings"Every warning needs a decision, not silence.

Key Principles

  • Fail loud, fix fast — errors block, warnings demand a decision
  • One lint run = one log entry — traceability
  • Orphans are a smell — often a sign of missing synthesis
  • Lint BEFORE draft — never after the fact
  • Subagent for bulk fixes — don't burn the main context on large wikis

示例提示词

帮我检查知识库里有没有断链、孤立页面或元数据缺失的问题。

所属插件

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

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

同插件的其他科研 Skill

常见问题

知识库结构校验能做什么?

Validates a wiki’s structural integrity: frontmatter completeness, broken links, orphaned pages, status. Use before drafting or finishing to catch structural errors。

如何安装知识库结构校验?

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

知识库结构校验需要哪些权限?

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

知识库结构校验经过官方审核吗?

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