academic-ref-inserter

name	academic-ref-inserter
description	Inserts, formats, and cross-references academic citations in docx. Invoke when user needs to insert references, fix citation order, add cross-reference hyperlinks, or reformat bibliography to Chinese (GB/T 7714) or international (IEEE/APA) standards.

Academic Reference Inserter (学术参考文献插入器)

A comprehensive tool for inserting, formatting, and cross-referencing academic references in Word (.docx) documents. Supports Chinese national standard GB/T 7714-2015 and major international journal formats (IEEE, APA 7th).

---

1. When to Invoke

Invoke this skill when the user:

• Says "插入参考文献" / "insert references"
• Says "格式化参考文献" / "format bibliography"
• Says "添加交叉引用" / "add cross-references"
• Says "按GB/T 7714格式化" / "format by GB/T 7714"
• Says "按IEEE/APA格式" / "format in IEEE/APA style"
• Needs to reorder, validate, or fix citation numbering
• Submits a paper and needs reference checking before journal submission

2. Supported Citation Formats

Format	Region	Common In	Ordering	In-text style
GB/T 7714-2015	China (中文)	计算机工程与应用, 自动化学报	Sequential [1][2][3]	[N]
IEEE	International	Engineering, CS journals	Sequential [1][2][3]	[N]
APA 7th	International	Psychology, Education, Business	Alphabetical	(Author, Year)

3. Complete Workflow

Step 1: Analyze Document

Before making any changes, ALWAYS run the analysis script to understand the current state:

python scripts/insert_refs.py analyze --input <paper.docx>

This will output:

• Total paragraphs
• All in-text citation markers found (in order)
• All bibliography entries found
• Orphan citations (cited but not in bibliography)
• Uncited references (in bibliography but not cited)
• Current ordering analysis

Step 2: Determine Format

Ask the user which format they need (if not already specified):

• GB/T 7714-2015 (Chinese standard, 顺序编码制)
• IEEE (numbered references)
• APA 7th (author-year)
• Vancouver (numbered, medical)

If the document already has references, auto-detect the format.

Step 3: Normalize and Reformat

Run the reformat command:

# GB/T 7714-2015
python scripts/insert_refs.py reformat --input <paper.docx> --format gbt7714

# IEEE
python scripts/insert_refs.py reformat --input <paper.docx> --format ieee

# APA 7th
python scripts/insert_refs.py reformat --input <paper.docx> --format apa7

Step 4: Reorder References

If the format requires sequential numbering (GB/T 7714, IEEE), reorder references to match first citation order in text:

python scripts/insert_refs.py reorder --input <paper.docx>

Step 5: Insert Cross-Reference Hyperlinks

Add bookmarks to each bibliography entry and convert all in-text citations to clickable hyperlinks:

python scripts/insert_refs.py hyperlink --input <paper.docx>

Step 6: Validate

Run comprehensive validation:

python scripts/insert_refs.py validate --input <paper.docx> --format gbt7714

Checks performed:

• All citations have matching bibliography entries
• All bibliography entries are cited in text
• Sequential numbering is correct (no gaps/duplicates)
• Minimum reference count met (default 15)
• Author names formatted correctly
• Document type tags present ([J], [M], [C], etc.)
• Year format valid
• No orphan references

Step 7: Report

Provide the user with a clear summary of:

• Number of references processed
• Changes made (insertions, renumbering, hyperlinks)
• Any warnings (uncited refs, missing tags, format issues)
• Backup file location

---

4. GB/T 7714-2015 Format Rules (中国国家标准)

Journal Article [J]

[序号] 作者. 题名[J]. 刊名, 出版年, 卷(期): 起止页码.

Rules:

• Authors: Lastname FirstInitial SecondInitial (e.g., Wang Y, Wu H)
• Chinese authors: Keep Chinese names (e.g., 刘云) in Chinese journals, use pinyin Liu Y in English journals
• 3 authors or fewer: list all; 4+: list first 3 then , et al.
• No quotes around title
• Journal name in full (not abbreviated) for Chinese journals
• DOI is optional but encouraged

Examples:

[1] Wang Y, Wu H, Dong J, et al. TimeXer: Empowering transformers for time series forecasting with exogenous variables[J]. Advances in Neural Information Processing Systems, 2024, 37: 469-498.

[2] 刘云, 胡涛, 张华, 等. 基于深度学习的空气质量预测综述[J]. 计算机工程与应用, 2024, 60(2): 1-15.

Conference Paper [C]

[序号] 作者. 题名[C]//会议录名称. 出版地: 出版者, 出版年: 起止页码.

Example:

[3] Zeng A, Chen M, Zhang L, et al. Are transformers effective for time series forecasting?[C]//Proceedings of the AAAI Conference on Artificial Intelligence. 2023: 11121-11128.

Book [M]

[序号] 作者. 书名[M]. 出版地: 出版者, 出版年.

Example:

[4] Box G E, Jenkins G M, Reinsel G C, et al. Time series analysis: forecasting and control[M]. John Wiley & Sons, 2015.

Dissertation [D]

[序号] 作者. 题名[D]. 出版地: 出版单位, 出版年.

Standard [S]

[序号] 发布机构. 标准编号 标准名称[S]. 出版地: 出版者, 出版年.

Electronic Resource [EB/OL]

[序号] 作者. 题名[EB/OL]. (发布日期)[引用日期]. URL.

Preprint / arXiv

Treat as [J] with journal name arXiv preprint arXiv:XXXX:

[5] Liu Y, Hu T, Zhang H, et al. iTransformer: Inverted transformers are effective for time series forecasting[J]. arXiv preprint arXiv:2310.06625, 2023.

Type Tags Reference

Tag	Document Type
[J]	Journal article
[C]	Conference paper
[M]	Monograph (book)
[D]	Dissertation
[N]	Newspaper
[S]	Standard
[P]	Patent
[R]	Report
[EB/OL]	Electronic resource

GB/T 7714 Specific Rules

1. Author names: Chinese → keep original; English → Last F M format
2. Capitalization: Chinese → keep original; English → title case for title
3. Punctuation: Use . between fields, not ;
4. Periods: End each entry with .
5. Ordering: Sequential by first citation in text

---

5. IEEE Format Rules

Journal Article [J]

[1] A. Author, B. Author, and C. Author, "Title of article," Journal Name, vol. X, no. Y, pp. Z1-Z2, Month, Year.

Rules:

• Authors: F. Lastname (initial then last name)
• Use , between authors, and before last
• Title in double quotes, sentence case
• Journal name in italics
• vol., no., pp. abbreviations

Conference [C]

[2] A. Author and B. Author, "Title," in Conference Proceedings, Year, pp. X-Y.

Book [M]

[3] A. Author, Book Title, Xth ed. City, State: Publisher, Year.

---

6. APA 7th Format Rules

Journal Article [J]

Author, A. A., & Author, B. B. (Year). Title of article. Journal Name, Volume(Issue), page-page. https://doi.org/xxxx

Rules:

• Authors: Last, F. M. format
• Use & before last author
• Title in sentence case
• Journal name in italics
• DOI required

Book [M]

Author, A. A. (Year). Title of work: Capital letter also for subtitle. Publisher.

---

7. Error Handling

Common Issues

Issue	Detection	Fix
Missing type tag	[J] not found in ref	Auto-detect from source pattern
Author name format wrong	Name has incorrect capitalization or order	Normalize to target format
No matching citation	Ref in bib but never cited	Either remove ref or add citation with [TODO: add citation context]
No matching ref	Citation [N] in text but not in bib	Add placeholder ref entry
Duplicate citation numbers	Two refs with same number	Renumber sequentially
Gaps in numbering	[1], [2], [4] without [3]	Compact to sequential

Recovery

If any step fails:

1. Restore from the automatic backup (_backup_refs.docx)
2. Report the error to the user
3. Offer manual intervention for complex cases

---

8. Output Files

After running the full workflow:

File	Description
paper.docx (original)	Updated with hyperlinks
paper_backup_refs_YYYYMMDD_HHMMSS.docx	Timestamped pre-modification backup
paper_analysis.json	Citation analysis report

---

9. Validation Checklist

Before reporting completion, verify ALL of:

• Reference count ≥ 15 (for journal papers)
• ≥ 50% references from last 5 years
• All in-text citations have matching bibliography entries
• All bibliography entries are cited in text
• Sequential numbering matches citation order (GB/T, IEEE)
• Each entry has proper type tag [J]/[M]/[C]/[D]
• Author names formatted correctly for target style
• Cross-reference hyperlinks work (Ctrl+Click)
• Backup file created