Skip to content
Back to search

thesis-skills

面向 Word→LaTeX 迁移、引用完整性、中文语言规范、格式验证与高校规则包的确定性论文工作流仓库。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/quzhiii--thesis-skills/badge.svg)](/listings/quzhiii--thesis-skills)

HTML

<a href="/listings/quzhiii--thesis-skills"><img src="/api/listings/quzhiii--thesis-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Run the built-in sample project through the check pipeline:

git clone https://github.com/quzhiii/thesis-skills.git
cd thesis-skills

test -d examples/minimal-latex-project

python run_check_once.py \
  --project-root examples/minimal-latex-project \
  --ruleset university-generic \
  --skip-compile

Expected result: JSON reports are written to `examples/minimal-latex-project/reports/`, including `run-summary.json` and `readiness-report.json`, without requiring a local LaTeX installation.

If you already have a LaTeX thesis project:

python run_check_once.py \
  --project-root thesis \
  --ruleset university-generic \
  --skip-compile

More details: [`docs/quickstart.md`](docs/quickstart.md).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 782 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Thesis Skills v3.5.0
  2. <div align="center">
  3. **Deterministic thesis workflow tools for citation sync, format checks, review handoff, and pre-submission readiness.**
  4. Spend your time thinking, not fixing formatting.
  5. [![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
  6. [![License](https://img.shields.io/github/license/quzhiii/thesis-skills)](LICENSE)
  7. [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](https://github.com/quzhiii/thesis-skills)
  8. [![Showcase](https://img.shields.io/badge/Showcase-Live-success)](https://quzhiii.github.io/thesis-skills)
  9. [中文文档](README.zh-CN.md) · **English** · [Showcase](https://quzhiii.github.io/thesis-skills)
  10. [What's New](#whats-new-in-v350) · [Quickstart](#quickstart) · [Outputs](#outputs) · [Scenarios](#scenarios) · [Updating](#updating-your-local-copy) · [Rule Packs](#rule-packs) · [Creating Your Own](#creating-your-own-school-rule-pack) · [Boundaries](#boundaries)
  11. </div>
  12. ---
  13. ## What is this?
  14. Thesis Skills is **not** an AI writing assistant, **not** a thesis template, and **not** a tool that writes thesis content for you.
  15. It is a **CLI workflow system** that connects the tools many graduate students and researchers already use: Word, Zotero, EndNote, LaTeX, structured check reports, safe fix patches, review handoff artifacts, and pre-submission readiness checks.
  16. ```text
  17. ┌───────────────────────────────────────────┐
  18. Zotero / EndNote ─┤ ├─→ LaTeX thesis
  19. Word .docx ───────┤ Thesis Skills ├─→ Review Word export
  20. LaTeX project ────┤ ├─→ Defense pack
  21. └───────────────────────────────────────────┘
  22. │
  23. ▼
  24. check reports → dry-run fixes → readiness gate
  25. ```
  26. The goal is simple: turn scattered, manual, error-prone thesis finishing work into a workflow that is **checkable, repeatable, and auditable**.
  27. For repetitive finishing work, the expected time savings are concrete:
  28. | Workflow | Manual baseline | With Thesis Skills | Speedup |
  29. |---|---:|---:|---:|
  30. | Bibliography intake | 30-60 min | 2-5 min | **~10× faster** |
  31. | Word ↔ LaTeX review handoff | 1-3 hrs | 5-10 min | **~15× faster** |
  32. | Deterministic format checks | 1-3 hrs | 2-5 min | **~20× faster** |
  33. | Safe report-driven fixes | 1-2 hrs | 5-10 min | **~10× faster** |
  34. | Pre-submission readiness review | 30-60 min | 1-2 min | **~30× faster** |
  35. | Defense prep inventory | 2-4 hrs | 10-15 min | **~15× faster** |
  36. > Time savings are conservative estimates for repetitive formatting and handoff work. Thesis Skills does not replace writing, thinking, advisor judgment, or institutional confirmation.
  37. ---
  38. ## What's new in v3.5.0
  39. - **Bounded auto-fix for final-audit findings**: new fixers for final cleanup residue, statistical notation normalization, manual anchor insertion, and unused bibliography entry removal. All fixers are preview-first and only apply low-risk, reversible edits.
  40. - **Final delivery workflow**: `33-final-delivery/run_final_delivery.py` orchestrates evidence generation, final-audit checks, optional bounded fixes, and bundle rebuild in one command.
  41. - **Fix cycle integration**: `run_fix_cycle.py` now supports `final-audit` and `all` modes for running the new fixers.
  42. - **Report navigation polish** (from v3.4.1): local HTML report surfaces now cross-link `index`, `final-audit`, `reference-ledger`, `claim-citation`, readiness, and raw JSON / CSV artifacts more consistently.
  43. - **Support-risk heuristic calibration** (from v3.4.1): `possible_overclaim` no longer duplicates `possible_topic_mismatch` when a `PASS` reference is already flagged by the more specific topic-mismatch signal.
  44. - **V3.4 final-audit surfaces** remain in place: deterministic final cleanup, statistical consistency, manual-anchor checks, final-audit JSON aggregation, reference-audit ledger, and static HTML report surfaces.
  45. - **Static local report UX**: `reports/index.html`, `reports/final-audit-report.html`, `reports/reference-audit-ledger.html`, and `reports/claim-citation-triage.html` make JSON / CSV artifacts easier to review without replacing them as source of truth.
  46. - **V3.3 reference verification hardening** remains in place: final reference set parsing, DOI candidates, URL verification, scoped/resumable external verification, and the unified evidence pipeline runner `run_evidence_pipeline.py`.
  47. ### v3.3 highlights recap
  48. - **Readiness Gate Integration** with the four-layer citation evidence pipeline remains in place; V3.4 built on top of that with final-audit and local HTML report surfaces.
  49. ---
  50. ## Quickstart
  51. Run the built-in sample project through the check pipeline:
  52. ```bash
  53. git clone https://github.com/quzhiii/thesis-skills.git
  54. cd thesis-skills
  55. test -d examples/minimal-latex-project
  56. python run_check_once.py \
  57. --project-root examples/minimal-latex-project \
  58. --ruleset university-generic \
  59. --skip-compile
  60. ```
  61. Expected result: JSON reports are written to `examples/minimal-latex-project/reports/`, including `run-summary.json` and `readiness-report.json`, without requiring a local LaTeX installation.
  62. If you already have a LaTeX thesis project:
  63. ```bash
  64. python run_check_once.py \
  65. --project-root thesis \
  66. --ruleset university-generic \
  67. --skip-compile
  68. ```
  69. More details: [`docs/quickstart.md`](docs/quickstart.md).
  70. ---
  71. ## Outputs
  72. ### Hero workflow
  73. ```text
  74. 1. Intake 2. Check 3. Fix safely 4. Gate 5. Handoff
  75. ────────── ─────────── ───────────── ───────── ─────────────
  76. Zotero references dry-run patches PASS advisor Word
  77. EndNote → language → preview first → WARN → review TODOs
  78. Word/LaTeX format apply explicitly BLOCK defense pack
  79. ```
  80. ### Readiness gate preview
  81. ```text
  82. ┌──────────────────────────────────────────────────────────────┐
  83. │ Readiness verdict: WARN │
  84. ├───────────────────────┬────────┬─────────────────────────────┤
  85. │ Dimension │ Status │ Why it matters │
  86. ├───────────────────────┼────────┼─────────────────────────────┤
  87. │ References │ PASS │ all cite keys resolve │
  88. │ Language │ WARN │ 2 style warnings remain │
  89. │ Format │ PASS │ labels and refs are stable │
  90. │ Compile evidence │ WARN │ skipped in demo mode │
  91. │ Export evidence │ WARN │ not produced by smoke test │
  92. │ Review-loop evidence │ WARN │ not produced by smoke test │
  93. └───────────────────────┴────────┴─────────────────────────────┘
  94. Next actions:
  95. 1. Review reports/check_language-report.json
  96. 2. Generate Word export / review-loop artifacts when those handoffs are needed
  97. 3. Re-run without --skip-compile before final submission
  98. ```
  99. The baseline `run_check_once.py` command writes machine-readable artifacts such as:
  100. - `reports/check_bib_quality-report.json`
  101. - `reports/check_references-report.json`
  102. - `reports/citation-integrity-report.json`
  103. - `reports/citation-integrity-report.md`
  104. - `reports/citation-issues.csv`
  105. - `reports/check_language-report.json`
  106. - `reports/check_language_deep-report.json`
  107. - `reports/check_format-report.json`
  108. - `reports/check_content-report.json`
  109. - `reports/readiness-report.json`
  110. - `reports/run-summary.json`
  111. Optional final-audit foundation artifact:
  112. - `reports/final-cleanup-report.json` from `23-check-final-cleanup/check_final_cleanup.py`
  113. - `reports/statistical-consistency-report.json` from `25-check-statistical-consistency/check_statistical_consistency.py`
  114. - `reports/manual-anchor-report.json` from `26-check-manual-anchor/check_manual_anchor.py`
  115. - `reports/final-audit-report.json` from `27-final-audit-report/build_final_audit_report.py`
  116. - `reports/reference-audit-ledger.csv` from `28-reference-audit-ledger/build_reference_audit_ledger.py`
  117. - `reports/index.html` from `29-report-index/build_report_index.py`
  118. - `reports/final-audit-report.html` from `30-final-audit-html/build_final_audit_html.py`
  119. - `reports/reference-audit-ledger.html` from `31-reference-ledger-html/build_reference_audit_ledger_html.py`
  120. - `reports/claim-citation-triage.html` from `32-claim-citation-html/build_claim_citation_html.py`
  121. Bounded auto-fix modules (preview-first, low-risk only):
  122. - `23-fix-final-cleanup/fix_final_cleanup.py` — remove exact process markers (`TODO`, `FIXME`, `???`, `draft`, `debug`, `\textcolor{blue}`)
  123. - `25-fix-statistical-consistency/fix_statistical_consistency.py` — normalize non-dominant statistical notation when dominant style is unambiguous
  124. - `26-fix-manual-anchor/fix_manual_anchor.py` — insert `\phantomsection` before flagged `\addcontentsline` entries
  125. - `28-fix-reference-audit-ledger/fix_reference_audit_ledger.py` — remove truly unused bibliography entries (`is_unused_bib_entry=true`, `is_cited_in_tex=false`, `is_final_reference=false`)
  126. Final delivery workflow:
  127. - `33-final-delivery/run_final_delivery.py` — orchestrate evidence generation, final-audit checks, optional bounded fixes, and bundle rebuild
  128. The optional v3.3 evidence pipeline writes the citation evidence artifacts:
  129. - `reports/final-reference-set-report.json`
  130. - `reports/final-reference-set-report.csv`
  131. - `reports/external-verification-report.json` when external verification is not skipped
  132. - `reports/missing-doi-candidates.json` when external verification is not skipped
  133. - `reports/missing-doi-candidates.csv` when external verification is not skipped
  134. - `reports/url-verification-report.json` when external verification is not skipped
  135. - `reports/url-verification-flagged.csv` when external verification is not skipped
  136. - `reports/hallucination-risk-report.json`
  137. - `reports/high-risk-references.csv`
  138. - `reports/claim-citation-triage-report.json`
  139. - `reports/claim-citation-triage.md`
  140. - `reports/claim-citation-triage.csv`
  141. Example JSON snippets and demo walkthroughs: [`docs/examples.md`](docs/examples.md).
  142. ### Citation Integrity preview
  143. The current v3.5.0 release line keeps local Citation Integrity as the first layer of pre-submission reference checking:
  144. ```text
  145. References: BLOCK
  146. - cited keys missing from bibliography files
  147. - duplicate citation keys with conflicting metadata
  148. - DOI/year field warnings
  149. - LaTeX undefined-citation warnings from local compile logs
  150. ```
  151. Boundary: the current Citation Integrity workflow only checks local citation integrity. It does not query external databases and never auto-inserts or rewrites citations. Use the external verification and hallucination risk layers for evidence-based screening.
  152. ### External Verification (v2.0.0)
  153. An optional external metadata verification layer queries **CrossRef**, **OpenAlex**, and **Semantic Scholar** for each bibliography entry and writes `reports/external-verification-report.json`.
  154. Use this when you want a fast authenticity screen for AI-drafted or suspicious-looking references before a manual final check.
  155. ```bash
  156. python 18-verify-references/verify_external_references.py \
  157. --project-root thesis \
  158. --ruleset university-generic
  159. ```
  160. Or via the existing reference checker with an explicit flag:
  161. ```bash
  162. python 10-check-references/check_references.py \
  163. --project-root thesis \
  164. --ruleset university-generic \
  165. --with-external-verification
  166. ```
  167. V2.0 boundaries:
  168. - Providers: CrossRef, OpenAlex, and Semantic Scholar.
  169. - No readiness gate blocking from the local References dimension.
  170. - `external_verification` is advisory only.
  171. - No automatic citation rewriting.
  172. - Network failures degrade to `UNAVAILABLE`, never crash.
  173. ### Final Reference Set + DOI / URL checks (v3.3.0)
  174. V3.3 hardens citation evidence by separating three scopes:
  175. - `final`: references that actually entered the compiled bibliography via `.aux` / `.bbl`
  176. - `cited`: citation keys extracted from TeX source `\cite{}` commands
  177. - `all`: every entry in active `.bib` files
  178. The final reference set builder writes:
  179. - `reports/final-reference-set-report.json`
  180. - `reports/final-reference-set-report.csv`
  181. The external verification layer can now resume long runs and write partial results safely:
  182. ```bash
  183. python 18-verify-references/verify_external_references.py \
  184. --project-root thesis \
  185. --ruleset university-generic \
  186. --scope final \
  187. --resume
  188. ```
  189. V3.3 also adds advisory follow-up reports:
  190. - `reports/missing-doi-candidates.json` and `.csv` for likely DOI additions
  191. - `reports/url-verification-report.json` and `reports/url-verification-flagged.csv` for URL resolution checks
  192. Boundaries:
  193. - No LLM usage.
  194. - No automatic DOI write-back to `.bib` files.
  195. - No automatic URL replacement.
  196. - URL verification checks whether a URL resolves; it does not judge document authenticity.
  197. ### Hallucination Risk (v3.0.0)
  198. Score each bibliography entry for hallucination risk using local metadata and optional external verification evidence. The hallucination risk scorer reads `reports/external-verification-report.json` if present and writes `reports/hallucination-risk-report.json` plus `reports/high-risk-references.csv`.
  199. ```bash
  200. python 19-check-hallucination-risk/check_hallucination_risk.py \
  201. --project-root thesis \
  202. --ruleset university-generic
  203. ```
  204. Risk labels:
  205. | Label | Meaning |
  206. |---|---|
  207. | `PASS` | Multi-source match with consistent metadata |
  208. | `WARN` | Entry exists but fields differ noticeably |
  209. | `REVIEW` | Possible match but evidence is weak |
  210. | `HIGH_RISK` | No credible match found in enabled databases |
  211. | `UNSUPPORTED` | Chinese-language or non-standard entry that cannot be auto-verified |
  212. V3.0 boundaries:
  213. - No LLM usage. Scoring is deterministic based on local metadata and external verification evidence.
  214. - No automatic citation or bibliography rewriting.
  215. - No live network calls. Reads `external-verification-report.json` if present.
  216. - `UNSUPPORTED` means "cannot be automatically judged by enabled evidence," not "safe."
  217. - `HIGH_RISK` means "manual verification strongly recommended," not "fake."
  218. ### Claim-Citation Support Triage (v3.1.0)
  219. Extract the sentence surrounding each `\cite{}` command from `.tex` files and pair it with cited bibliography metadata and V3.0 hallucination risk data. Produce deterministic triage labels that help identify claim-citation pairs that may lack credible structural support — without LLM.
  220. ```bash
  221. python 20-check-claim-citation/check_claim_citation.py \
  222. --project-root thesis \
  223. --ruleset university-generic
  224. ```
  225. Triage labels:
  226. | Label | Meaning |
  227. |---|---|
  228. | `WELL_SUPPORTED` | Cited reference PASS in V3.0, complete metadata, substantive context |
  229. | `SUPPORTED` | Reference PASS/WARN in V3.0, minor risk signals |
  230. | `WEAK` | Reference REVIEW in V3.0, or vague context, or incomplete metadata |
  231. | `ORPHANED` | Citation key not found in bibliography files |
  232. | `UNVERIFIABLE` | Cited reference UNSUPPORTED in V3.0 (CJK, thesis type) |
  233. The report also includes a backward-compatible support-review layer: `claim_type`, `support_review_label`, `support_review_reason`, `support_signals`, `risk_signals`, `cluster_keys`, `cluster_risk_summary`, and `next_actions`. These fields explain why a pair or grouped citation cluster deserves manual review; they do not replace the original `triage_label` or make final truth claims. Local lexical evidence can use title, abstract, and keyword token overlap when those `.bib` fields are present. Conservative risk signals such as `possible_topic_mismatch`, `possible_outdated_support`, and `possible_overclaim` are advisory prompts for human review, not automatic judgments. The JSON/Markdown reports may also include advisory `citation_needed_candidates` for uncited high-assertion sentences; these are manual review prompts, not blocking findings.
  234. V3.1 boundaries:
  235. - No LLM usage. Scoring is deterministic based on V3.0 risk labels, metadata, context quality, grouping, and citation frequency.
  236. - No semantic similarity between claim text and reference content.
  237. - No automatic citation rewrite or suggestion.
  238. - Reads `reports/hallucination-risk-report.json` if present; treats missing it conservatively.
  239. - Exit code 1 when any pair is `ORPHANED`.
  240. ### Final Cleanup Checker
  241. Before final PDF or submission handoff, scan LaTeX sources for process residue such as `TODO`, `FIXME`, `???`, `\textcolor{blue}`, `\color{blue}`, `draft`, `debug`, and Chinese review notes like `待修改` or `待核查`.
  242. ```bash
  243. python 23-check-final-cleanup/check_final_cleanup.py \
  244. --project-root thesis \
  245. --ruleset university-generic
  246. ```
  247. Output: `reports/final-cleanup-report.json`. This checker is report-only: it does not delete markers, rewrite prose, or change source files. The final-audit workflow can aggregate this JSON into `reports/final-audit-report.json` and render it through `reports/final-audit-report.html` and the local report index.
  248. ### Statistical Consistency Checker
  249. Before final submission, scan for mixed statistical notation such as `p值/P值`, `p=/P=`, `95%CI/95\%CI/95%置信区间`, `Bootstrap/自助法`, and `SMD/标准化均数差`.
  250. ```bash
  251. python 25-check-statistical-consistency/check_statistical_consistency.py \
  252. --project-root thesis \
  253. --ruleset university-generic
  254. ```
  255. Output: `reports/statistical-consistency-report.json`. The checker reports the dominant style in the current project and flags deviations; it does not force a universal notation preference or rewrite source files.
  256. ### Manual Anchor Checker
  257. If the project uses manual contents entries, scan for `\addcontentsline` commands that may be missing a nearby preceding `\phantomsection` anchor.
  258. ```bash
  259. python 26-check-manual-anchor/check_manual_anchor.py \
  260. --project-root thesis \
  261. --ruleset university-generic
  262. ```
  263. Output: `reports/manual-anchor-report.json`. The checker reports likely TOC / LOF / LOT hyperlink-jump risks, but it does not repair labels, captions, numbering, figures, tables, or references.
  264. ### Final Audit Report
  265. After generating the source-of-truth JSON reports, aggregate them into a single final-audit handoff artifact:
  266. ```bash
  267. python 27-final-audit-report/build_final_audit_report.py \
  268. --project-root thesis \
  269. --ruleset university-generic
  270. ```
  271. Output: `reports/final-audit-report.json`. This report imports existing JSON evidence and groups dimensions, blockers, warnings, next actions, and source links. It does not rerun checks, call external services, modify thesis sources, or replace the raw JSON reports.
  272. ### Reference Audit Ledger
  273. For spreadsheet review and advisor/service handoff, aggregate existing reference evidence into one CSV ledger:
  274. ```bash
  275. python 28-reference-audit-ledger/build_reference_audit_ledger.py \
  276. --project-root thesis \
  277. --ruleset university-generic
  278. ```
  279. Output: `reports/reference-audit-ledger.csv`. The ledger preserves source-specific statuses from local citation integrity, final reference set, external verification, DOI candidates, URL verification, and hallucination-risk reports. It does not edit `.bib`, insert DOI values, replace URLs, call external services, or treat `NO_CANDIDATE` as fake.
  280. ### Static Report Index
  281. Generate a local HTML landing page for the reports directory:
  282. ```bash
  283. python 29-report-index/build_report_index.py \
  284. --project-root thesis
  285. ```
  286. Output: `reports/index.html`. This page links available JSON / CSV artifacts and shows present / missing / unreadable counts. It is a local reading surface only; JSON and CSV remain the source of truth.
  287. ### Final Audit HTML
  288. Generate a readable local detail page for the aggregated final-audit JSON:
  289. ```bash
  290. python 30-final-audit-html/build_final_audit_html.py \
  291. --project-root thesis
  292. ```
  293. Output: `reports/final-audit-report.html`. This static page is generated from `final-audit-report.json` and shows the overall verdict, KPI row, dimension matrix, issues, next actions, and source links. JSON remains authoritative.
  294. ### Reference Audit Ledger HTML
  295. Generate a readable local detail page for the reference-audit CSV ledger:
  296. ```bash
  297. python 31-reference-ledger-html/build_reference_audit_ledger_html.py \
  298. --project-root thesis
  299. ```
  300. Output: `reports/reference-audit-ledger.html`. This static page is generated from `reference-audit-ledger.csv` and shows summary stats, scope slices, citation-key groupings, and the full ledger table. CSV remains authoritative.
  301. ### Claim-Citation HTML
  302. Generate a readable local detail page for claim-citation support review:
  303. ```bash
  304. python 32-claim-citation-html/build_claim_citation_html.py \
  305. --project-root thesis
  306. ```
  307. Output: `reports/claim-citation-triage.html`. This static page is generated from `claim-citation-triage-report.json` and shows P0 / P1 / P2 / P3 review groups, issue-card style summaries, citation-needed candidates, uncited references, cluster review details, support/risk signals, and next actions. It also deep-links the local readiness / references / claim-citation / final-audit report surfaces so reviewers can move between summary, reference ledger, and detail pages. The HTML is a mobile-readable local HTML bundle for manual review. JSON / CSV remain the source of truth; CSV / Markdown outputs remain unchanged.
  308. ## Scenarios
  309. ### 1. I just switched from Word to LaTeX
  310. ```bash
  311. python 00-bib-zotero/sync_from_word.py \
  312. --project-root thesis \
  313. --word-file thesis.docx \
  314. --apply
  315. python run_check_once.py \
  316. --project-root thesis \
  317. --ruleset university-generic \
  318. --skip-compile
  319. ```
  320. ### 2. I already use LaTeX and want to check my thesis
  321. ```bash
  322. python run_check_once.py \
  323. --project-root thesis \
  324. --ruleset university-generic
  325. python 16-check-readiness/check_readiness.py \
  326. --project-root thesis \
  327. --ruleset university-generic \
  328. --mode advisor-handoff
  329. ```
  330. ### 3. My advisor needs a Word version for review
  331. ```bash
  332. python 02-latex-to-word/migrate_project.py \
  333. --project-root thesis \
  334. --output-file thesis-review.docx \
  335. --profile review-friendly \
  336. --apply true
  337. ```
  338. ### 4. I received Word feedback and need to update LaTeX
  339. ```bash
  340. python 04-word-review-ingest/feedback_ingest.py \
  341. --project-root thesis \
  342. --input review-feedback.json
  343. python 03-latex-review-diff/review_diff.py \
  344. --project-root thesis
  345. ```
  346. ### 5. I am preparing for defense
  347. ```bash
  348. python 17-defense-pack/generate_outline.py \
  349. --project-root thesis \
  350. --ruleset university-generic
  351. python 17-defense-pack/generate_figure_inventory.py \
  352. --project-root thesis \
  353. --ruleset university-generic
  354. ```
  355. ### 6. I want to screen AI-generated or suspicious references
  356. ```bash
  357. python 18-verify-references/verify_external_references.py \
  358. --project-root thesis \
  359. --ruleset university-generic
  360. python 19-check-hallucination-risk/check_hallucination_risk.py \
  361. --project-root thesis \
  362. --ruleset university-generic
  363. ```
  364. Use this when you want a fast authenticity screen for references drafted by AI or copied from sources you do not fully trust. It produces a `hallucination_risk_score` per entry and a `high-risk-references.csv` for manual review, without rewriting the bibliography. Chinese-language references are marked `UNSUPPORTED` since external databases do not cover them.
  365. More scenarios: [`docs/examples.md`](docs/examples.md).
  366. ---
  367. ## Rule Packs
  368. Rule packs are the most important concept in Thesis Skills: they encode your institution's formatting requirements as structured YAML so the checkers know what counts as "correct" and what counts as an issue.
  369. ### Built-in Packs
  370. ```text
  371. 90-rules/packs/
  372. ├── university-generic/ # Generic university thesis starter (default, permissive)
  373. ├── journal-generic/ # Generic journal article starter (English, minimal)
  374. ├── tsinghua-thesis/ # Tsinghua University Master's/PhD thesis pack
  375. │ # First-pass calibrated against 《研究生学位论文写作指南(202503)》
  376. │ # CJK/English rules, figure numbering, and reference defaults tuned to the guide
  377. └── demo-university-thesis/ # Concrete non-Tsinghua example pack
  378. ```
  379. - `university-generic` is suitable for **most Chinese universities** — broad coverage, moderate thresholds.
  380. - `tsinghua-thesis` is specifically calibrated for Tsinghua students: GB/T 7714 reference style, mixed CJK/English rules per the university writing guide, and Chinese chapter naming conventions. For many Tsinghua thesis projects this works as a direct starting point, but you should still verify against your department template and local requirements.
  381. - `journal-generic` targets English journal submissions, with CJK-specific rules disabled.
  382. ### Inside a Rule Pack
  383. Each pack is a folder with three files:
  384. ```
  385. 90-rules/packs/your-school/
  386. ├── pack.yaml # Metadata: name, kind, version
  387. ├── rules.yaml # Rules: what to check, severity, thresholds
  388. └── mappings.yaml # File/path mappings (main tex candidates, bib paths)
  389. ```
  390. `rules.yaml` is organized by dimension:
  391. | Section | Controls | Examples |
  392. |---|---|---|
  393. | `project` | Project structure: main tex file names, chapter globs, bib paths | `main_tex_candidates`, `chapter_globs` |
  394. | `reference` | Citation integrity: missing keys, orphans, duplicates, bib quality | `missing_key: error` |
  395. | `language` | Surface language: CJK/Latin spacing, brackets, punctuation, weak phrases | `cjk_latin_spacing`, `bracket_mismatch` |
  396. | `language_deep` | Deep language: connectors, collocations, inference strength, boundary signposts | `inference_overclaim`, `boundary_signpost` |
  397. | `consistency` | Terminology: variant detection for the same concept | `terminology_consistency` |
  398. | `format` | Format structure: figure/table lists, numbering, cross-references | `require_list_of_figures` |
  399. | `content` | Content completeness: required sections, keyword count | `required_sections` |
  400. | `compile` | Compile diagnostics: engine, error categories, severity mapping | `engine_hint: xelatex` |
  401. ### Creating Your Own School Rule Pack
  402. If you are not a Tsinghua student, or your department/journal has specific requirements, create a custom pack from one of the built-in starters.
  403. **Step 1: Scaffold the pack**
  404. ```bash
  405. python 90-rules/create_pack.py \
  406. --pack-id my-university \
  407. --display-name "My University Master's Thesis" \
  408. --starter university-generic \
  409. --kind university-thesis
  410. ```
  411. This generates three files under `90-rules/packs/my-university/`, copied from `university-generic` as a starting point.
  412. **Step 2: Adjust project structure**
  413. Edit `rules.yaml` → `project` to match your thesis directory layout:
  414. ```yaml
  415. project:
  416. main_tex_candidates: # Possible names for your main tex file, in priority order
  417. - thesis.tex
  418. - main.tex
  419. chapter_globs: # Where chapter files live and their naming pattern
  420. - chapters/*.tex
  421. bibliography_files: # Paths to .bib files
  422. - ref/refs.bib
  423. ```
  424. **Step 3: Tune rules to your school's guide**
  425. Check your institutional thesis writing guide and decide rule by rule:
  426. - **Keep enabled**: Rules that your guide explicitly requires and the checker can reliably detect (e.g., missing citation keys, figure/table numbering)
  427. - **Demote**: Rules your guide does not mandate — change `severity` from `warning` to `info` (e.g., CJK/Latin spacing if not required)
  428. - **Disable**: Rules clearly irrelevant to your institution or discipline — set `enabled: false` (e.g., CJK rules for English-only theses)
  429. Example — demoting CJK spacing when your guide doesn't require it:
  430. ```yaml
  431. # Before
  432. cjk_latin_spacing:
  433. enabled: true
  434. severity: warning
  435. # After (school guide does not mandate CJK-Latin spacing)
  436. cjk_latin_spacing:
  437. enabled: true
  438. severity: info
  439. ```
  440. **Step 4: Update required section names**
  441. If your thesis uses Chinese section naming (not English IMRaD), sync the content rules:
  442. ```yaml
  443. content:
  444. required_sections:
  445. - Introduction (or 绪论)
  446. - Literature Review (or 文献综述)
  447. - Methods (or 研究方法)
  448. - Conclusion (or 结论)
  449. ```
  450. **Step 5: Run checks with your custom pack**
  451. ```bash
  452. python run_check_once.py \
  453. --project-root thesis \
  454. --ruleset my-university \
  455. --skip-compile
  456. ```
  457. **Step 6: Validate and iterate**
  458. After running, inspect the JSON reports under `reports/`. If you notice:
  459. - **Too many false positives in a category** → demote or disable that rule
  460. - **Real issues not detected** → check if the rule is enabled and severity is set high enough
  461. - **Project discovery failed** → adjust `main_tex_candidates` or `chapter_globs`
  462. Tweak → re-run → review reports. Most packs converge in 1–2 calibration rounds.
  463. **Step 7: Export a handoff bundle**
  464. After the pack passes lint, export a minimal versioned export bundle for handoff:
  465. ```bash
  466. python 90-rules/export_pack.py \
  467. --pack-path 90-rules/packs/my-university \
  468. --output dist/my-university.zip
  469. ```
  470. This creates a linted ZIP bundle for sharing the pack outside a local checkout. The ZIP includes `manifest.json` with pack metadata and the lint scorecard summary. There is still no formal registry or publish command.
  471. > **For non-Tsinghua users**: If your calibrated rule pack is stable and you'd like it featured, PRs adding new packs to `90-rules/packs/` are welcome. Future students from your school won't have to start from scratch.
  472. ---
  473. ## Tested on
  474. - Python 3.10+
  475. - Windows / macOS / Linux
  476. - LaTeX optional for the `--skip-compile` demo; run without `--skip-compile` when you want compile-log diagnostics
  477. ---
  478. ## Boundaries
  479. | Thesis Skills is | Thesis Skills is not |
  480. |---|---|
  481. | A bridge between Word, Zotero, EndNote, and LaTeX | A thesis template or document class |
  482. | A deterministic checker for formatting and structural rules | An AI writing assistant that generates thesis content |
  483. | A report-driven workflow with dry-run previews | A replacement for Grammarly or other prose editors |
  484. | A pre-submission readiness gate | An automatic final defense PPT generator |
  485. | Extensible through institution-specific rule packs | A guarantee that every school or journal rule is already supported |
  486. | CLI-based with auditable artifacts | A GUI or web-based editor |
  487. ---
  488. ## Documentation
  489. | Document | Purpose |
  490. |---|---|
  491. | [`docs/quickstart.md`](docs/quickstart.md) | Minimal install and first check run |
  492. | [`docs/examples.md`](docs/examples.md) | Output previews and scenario examples |
  493. | [`docs/modules.md`](docs/modules.md) | Full module reference moved out of the README |
  494. | [`docs/architecture.md`](docs/architecture.md) | Workflow and module architecture |
  495. | [`docs/getting-started-zh.md`](docs/getting-started-zh.md) | Step-by-step beginner guide in Chinese |
  496. | [`CHANGELOG.md`](CHANGELOG.md) | Release history |
  497. ---
  498. ## Release history
  499. - `v3.4.1`: polished cross-report HTML navigation and calibrated duplicate support-risk signals.
  500. - `v3.4.0`: added final-audit report surfaces, reference-audit ledger HTML, and conservative claim-citation support-risk signals.
  501. - `v3.3.0`: hardened reference verification with final reference set parsing, resumeable external verification, DOI candidate suggestions, and URL verification.
  502. - `v3.2.0`: integrated hallucination risk and claim-citation triage into readiness gate, added unified evidence pipeline runner, `run_evidence_pipeline.py`.
  503. - `v3.1.0`: added claim-citation support triage, `claim-citation-triage-report.json`, deterministic triage scoring, and three demo projects.
  504. - `v3.0.0`: added hallucination risk scoring, `hallucination-risk-report.json`, `high-risk-references.csv`, Chinese-language `UNSUPPORTED` handling, and three demo projects.
  505. - `v2.0.0`: added CrossRef / OpenAlex / Semantic Scholar external verification, consensus candidates, and an `external_verification` readiness advisory.
  506. - `v1.0.0`: stabilized the public workflow story across README, roadmap, site, examples, and code paths.
  507. - `v1.1.0`: added the local-first Citation Integrity engine and readiness integration.
  508. - `v1.2.0`: added Markdown/CSV Citation Integrity outputs, clean/broken demos, and public version-line alignment.
  509. - See [`CHANGELOG.md`](CHANGELOG.md) for the full changelog.
  510. ---
  511. ## Updating your local copy
  512. Downloading or cloning the repository once does **not** make future updates appear automatically on your machine.
  513. Choose the update path that matches how you got Thesis Skills:
  514. ### If you cloned with Git
  515. Run:
  516. ```bash
  517. git pull origin main
  518. ```
  519. This fetches the newest committed changes from GitHub into your local checkout.
  520. If you want to see what changed before pulling:
  521. ```bash
  522. git fetch origin
  523. git log --oneline HEAD..origin/main
  524. ```
  525. ### If you downloaded a ZIP
  526. A ZIP download is just a snapshot. It will **not** sync by itself.
  527. To get updates, either:
  528. 1. download a fresh ZIP from GitHub and replace your local copy manually, or
  529. 2. switch to a Git clone so future updates only need `git pull`
  530. ### If you edited the repository locally
  531. Pulling new changes is easiest when your local copy has no uncommitted edits.
  532. Before updating, check:
  533. ```bash
  534. git status
  535. ```
  536. If you have local modifications, commit or back them up first so `git pull` does not create conflicts unexpectedly.
  537. ---
  538. ## Module reference
  539. The long module table lives in [`docs/modules.md`](docs/modules.md) so this README stays focused on the product workflow.
  540. ---
  541. ## Template recommendations
  542. Thesis Skills is designed to work alongside mature templates and institution-specific document classes.
  543. | Institution | Template repository |
  544. |---|---|
  545. | Tsinghua University | [tuna/thuthesis](https://github.com/tuna/thuthesis) |
  546. | Shanghai Jiao Tong University | [sjtug/SJTUThesis](https://github.com/sjtug/SJTUThesis) |
  547. | University of Science and Technology of China | [ustctug/ustcthesis](https://github.com/ustctug/ustcthesis) |
  548. | Peking University | [CasperVector/pkuthss](https://github.com/CasperVector/pkuthss) |
  549. | Stanford University | [dcroote/stanford-thesis-example](https://github.com/dcroote/stanford-thesis-example) |
  550. | University of Cambridge | [cambridge/thesis](https://github.com/cambridge/thesis) |
  551. ---
  552. ## Acknowledgments
  553. Special thanks to [tuna/thuthesis](https://github.com/tuna/thuthesis) and other open-source thesis template projects. These projects make high-quality LaTeX thesis writing more accessible and inspired the workflow design of Thesis Skills.
  554. ---
  555. ## License
  556. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.