科研 Skill

研究项目漂移状态检测

drift-report

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.

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

SKILL.md

Drift Report

Deterministic maintenance findings across three scopes — current project, shared library, all registered projects — produced by the same script the SessionStart hook runs. Report-only with one exception: the incremental search-index update (a derived cache).

Announce at start: "Using drift-report to check for accumulated drift."

How the automatic path works (so you can explain it)

At session start, hooks/drift_check.py compares cheap fingerprints (library PDF count/mtimes, master-bib hash, each registered project's bib hash, the current wiki's file count/mtimes) against ~/.cache/research-superpowers/drift-state.json. Nothing changed → nothing runs, nothing is injected. Drift is caused by actions, not by time — in-session actions are covered by the skills that cause them (ingest lints, add-to-library re-indexes); the hook covers what happens out-of-band: manual VPN downloads, Nextcloud syncs from teammates, Obsidian edits, ingests in other projects. The first run is a silent baseline. Kill switch: RESEARCH_SUPERPOWERS_NO_DRIFT_CHECK=1.

Manual run (this skill's job)

python3 "${CLAUDE_PLUGIN_ROOT:-$RESEARCH_SUPERPOWERS_DIR}/hooks/drift_check.py" --force --human

--force ignores the fingerprints (checks everything now — this is how you inspect a freshly installed machine despite the silent baseline); --human prints the report instead of hook JSON. Run from a project root when possible — the wiki-lint scope only exists there.

The checks, and what each finding means

FindingMeaningFix (never run without the user's go-ahead)
lint FAILS after out-of-band editsomeone edited knowledge/ outside a session (Obsidian, editor)python scripts/lint-wiki.py, then fix per wiki-lint skill
PDFs with no text layerscans arrived (VPN download, teammate sync) — invisible to searchocrmypdf, then re-index
PDFs unreadablecorrupt files in the librarybib-search.py status for the list
PDFs > 40 MBpublisher bloat syncing to everyone, foreveroptimize-pdf.py scan . → optimize after review
merge driftingests wrote bibkeys/keywords into project bibs that the master lacks — new keywords are invisible to every OTHER project's bib-search until mergedmerge-bibs.py --report-only first, review FACTUAL conflicts, then merge
bibkey COLLISION / SPLITone key names two works (a false cross-project join) or one work has two keys (a silently missed join)migrate-citekeys.py, guided by the audit output
project sync drifta project's copied schema/ + scripts/ come from an older plugin version — its linter validates against rules the plugin has since changed, and the error reads like a wiki problemsync-project.py --from-registry to see it, --apply to fix
index updated (info)the one permitted mutation — derived cache, incrementalnothing to do

Three of these tools live in the plugin, not in the project. merge-bibs.py, migrate-citekeys.py and sync-project.py are maintainer tools operating across projects, so they are not mirrored into the template — python scripts/merge-bibs.py from a project root fails with "No such file or directory". Run them from the plugin: python3 "${CLAUDE_PLUGIN_ROOT:-$RESEARCH_SUPERPOWERS_DIR}/scripts/merge-bibs.py" … (Claude Code sets CLAUDE_PLUGIN_ROOT; the OpenCode plugin sets RESEARCH_SUPERPOWERS_DIR for every shell command). The report's → lines already carry the absolute path. Everything else in the table (bib-search.py, optimize-pdf.py, lint-wiki.py) is template-mirrored and runs project-relative.

Never expand the registry in the shell. Pass --from-registry and let merge-bibs.py read ~/.config/research-superpowers/projects itself. Both shell forms lose projects silently, in opposite directions: --roots $ROOTS does not word-split in zsh and arrives as one nonexistent path, while --roots $(grep -v "^#" …) splits in bash and zsh — including inside a path, so a project under …/Mobile Documents/… arrives as several nonexistent fragments. A dropped project makes the report say "0 FACTUAL conflicts" about a set that never contained it, and inflates the master-only count. --roots <p1> <p2> … stays for explicitly named projects; quote every path.

Registry

Cross-project checks read ~/.config/research-superpowers/projects (one project root per line, # comments). The hook auto-registers the project each session starts in, so the registry fills itself through normal use; edit the file to add projects you never open with Claude Code, or to remove retired ones.

Red flags

ThoughtReality
"Merge drift found — I'll just run merge-bibs with --out now"No. --report-only first: FACTUAL conflicts (wrong DOI, wrong year) need a human verdict before anything writes to the shared master.
"The report is empty, so the check must be broken"Silence IS the report. Nothing changed since the last look — verify with --force --human if in doubt.
"A collision — I'll rename the key in this project"A bibkey is a cross-project join key derived from the work's metadata. Fix it with migrate-citekeys.py in EVERY affected project, not ad hoc in one.
"I'll OCR/optimize the PDFs right away, it's obviously needed"Library files sync to every machine and every teammate. Surface the worklist; the user decides when the shared collection gets rewritten.

示例提示词

帮我检查文献库和知识库里有没有未索引的PDF或关键词没合并的情况。

所属插件

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

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

同插件的其他科研 Skill

常见问题

研究项目漂移状态检测能做什么?

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。

如何安装研究项目漂移状态检测?

在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「研究项目漂移状态检测」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。

研究项目漂移状态检测需要哪些权限?

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

研究项目漂移状态检测经过官方审核吗?

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