Academic Research Skills (ARS) 完整教學

一個 plugin，把學術研究從「找文獻」到「投稿、修審回覆」全部包進 Claude Code。 設計哲學：AI 是副駕，不是駕駛。LLM 結構性缺陷（frame-lock / sycophancy / intent misdetection）由 mandatory integrity gate 強制管控。

1. 專案定位

1.1 一句話介紹

ARS（Academic Research Skills）是 Claude Code 上目前最完整的學術研究 plugin：

• 4 個 skill 覆蓋全流程：deep-research / academic-paper / academic-paper-reviewer / academic-pipeline
• 35+ modes、38-agent ensemble、10-stage orchestrator
• v3.7.3 + v3.8 L3 claim-faithfulness gate（每個 claim ↔ 引用都做忠實度審計）
• v3.9.0 cross-index triangulation（OpenAlex + Semantic Scholar + Crossref 三方校驗）
• CC-BY-NC 4.0 授權，非商業可自由用

1.2 為什麼出現？

作者 Cheng-I Wu (@Imbad0202) 觀察到三個 AI 寫學術的 結構性失敗模式：

1. Frame-lock：DA (devil’s advocate; 反方角色) 攻擊論點不攻擊前提，因為 verifier 和 generator 共享同一 cognitive frame
2. Sycophancy under pushback：使用者一質疑 AI 就退讓，retract 比 launch 還快 — 訓練偏好「對話和諧」
3. Intent misdetection：Socratic mentor 無法區分「探索性對話」vs「目標導向交付」，總是太早收斂

ARS v3.0 引入 Concession Threshold Protocol、Intent Detection Layer、Dialogue Health Indicator 對症下藥，後續 v3.x 持續疊加：

1.3 適合誰？

1.4 數字快照（2026-05-18）

• ⭐ Stars: 10,805 / Forks: 1,143（學術 plugin 罕見的擴散度）
• 🧠 4 skill + 38 agents + 10 commands + 1 SessionStart hook
• 🔬 101 個 check script（CI / CD 級別品質把關）
• 📜 6 種引用格式：APA 7.0 / IEEE / Chicago / MLA / Vancouver / 自訂
• 🌐 雙語界面：English + 繁體中文（自動偵測使用者語言）

2. 安裝指南

2.1 前置需求

• Claude Code 最新版（CLI / VS Code / JetBrains），v3.7.0+ 支援 plugin packaging
• ANTHROPIC_API_KEY（第一次跑 claude 時設定即可）
• 可選：
  • Pandoc — 想出 DOCX
  • tectonic + Source Han Serif TC — 想出 APA 7.0 中文 PDF
  • ARS_CROSS_MODEL=gpt-5.4-pro — 想開 cross-model audit gate

2.2 兩條安裝路徑

flowchart TD
    A[使用者] --> B{用法?}
    B -->|一行裝, 推薦| C["/plugin marketplace add Imbad0202/academic-research-skills"]
    C --> D["/plugin install academic-research-skills"]
    D --> E[Claude Code SessionStart hook
announce ARS loaded]
    E --> F[可用 /ars-* 10 個 slash command]
    B -->|傳統 symlink, 開發者| G[git clone repo]
    G --> H[symlink skills/ -> ~/.claude/skills/]
    H --> F

2.3 路徑 A：Plugin 安裝（推薦）

1# 在 Claude Code 內輸入
2/plugin marketplace add Imbad0202/academic-research-skills
3/plugin install academic-research-skills

裝完會看到 SessionStart announce：

 1ARS v3.9.3 (academic-research-skills) plugin loaded.
 2
 3Slash commands (10):
 4  /ars-full              opus    Full pipeline
 5  /ars-revision-coach    opus    Parse reviewer comments → Revision Roadmap
 6  /ars-plan              sonnet  Socratic chapter-by-chapter planning
 7  /ars-outline           sonnet  Detailed outline + evidence map
 8  /ars-revision          sonnet  Revised draft + R&R responses
 9  /ars-abstract          sonnet  Bilingual abstract + keywords
10  /ars-lit-review        sonnet  Annotated bibliography
11  /ars-format-convert    sonnet  Convert LaTeX / DOCX / PDF / Markdown
12  /ars-citation-check    sonnet  Citation error report
13  /ars-disclosure        sonnet  Venue-specific AI-usage disclosure
14
15Plugin agents (3, model: inherit):
16  synthesis_agent / research_architect_agent / report_compiler_agent
17
18Token budget: docs/PERFORMANCE.md (一次 full pipeline ≈ $4–6 on Opus 4.7)

2.4 路徑 B：手動 symlink（不用 plugin 包裝者）

1git clone https://github.com/Imbad0202/academic-research-skills.git
2cd academic-research-skills
3# 把 4 個 skill symlink 到 Claude skills 目錄
4ln -s "$(pwd)/deep-research" ~/.claude/skills/deep-research
5ln -s "$(pwd)/academic-paper" ~/.claude/skills/academic-paper
6ln -s "$(pwd)/academic-paper-reviewer" ~/.claude/skills/academic-paper-reviewer
7ln -s "$(pwd)/academic-pipeline" ~/.claude/skills/academic-pipeline
8# 或裝到專案層級 .claude/skills/

2.5 路徑 C：Codex CLI 使用者

1# 用 sibling distribution
2git clone https://github.com/Imbad0202/academic-research-skills-codex.git
3# 同樣 workflow content，但打包為單一 $academic-research-suite skill

2.6 第一次跑

1# 在 Claude Code 內
2/ars-plan
3# 然後描述你想寫的論文
4> "I want to write a paper on AI's impact on academic peer review."
5# ARS 進 Socratic dialogue mode，幫你規劃章節

3. 核心架構解析

3.1 4 個 Skill 與 10-stage Pipeline

flowchart TB
    User[使用者] --> Orch[academic-pipeline
v3.9.3 orchestrator]
    Orch -->|Stage 1| DR[deep-research
13 agents, 7 modes]
    Orch -->|Stage 2| AP[academic-paper
12 agents, 10 modes]
    Orch -->|Stage 2.5 mandatory| IV[integrity_verification_agent]
    Orch -->|Stage 3| APR[academic-paper-reviewer
7 agents, 6 modes]
    Orch -->|Stage 4| AP2[academic-paper
revision mode]
    Orch -->|Stage 4.5 mandatory| IV2[integrity_verification_agent]
    Orch -->|Stage 5| APR2[academic-paper-reviewer
re-review mode]
    Orch -->|Stage 6| RC[report_compiler_agent
Process Summary + Collab Eval]
    IV -->|fail| Block[BLOCK + return to author]
    IV2 -->|fail| Block

每個 stage 都會在 Material Passport（v3.4+ schema 11）留下：

• data_access_level（raw / redacted / verified_only）
• task_type（open-ended / outcome-gradable）
• repro_lock（v3.3.5+，記錄環境與輸入；非位元組可重現）
• claim_audit 結果（v3.8+，opt-in via ARS_CLAIM_AUDIT=1）

3.2 38-agent ensemble 分組

flowchart LR
    subgraph DR[deep-research, 13 agents]
        research_architect_agent
        research_question_agent
        bibliography_agent
        synthesis_agent
        devils_advocate_agent
        socratic_mentor_agent
        meta_analysis_agent
        risk_of_bias_agent
        source_verification_agent
        ethics_review_agent
        monitoring_agent
        editor_in_chief_agent
        report_compiler_agent
    end
    subgraph AP[academic-paper, 12 agents]
        intake_agent
        literature_strategist_agent
        structure_architect_agent
        argument_builder_agent
        draft_writer_agent
        citation_compliance_agent
        peer_reviewer_agent
        revision_coach_agent
        visualization_agent
        formatter_agent
        abstract_bilingual_agent
        socratic_mentor_agent_ap[socratic_mentor_agent_ap]
    end
    subgraph APR[reviewer, 7 agents]
        field_analyst_agent
        eic_agent
        methodology_reviewer_agent
        domain_reviewer_agent
        perspective_reviewer_agent
        devils_advocate_reviewer_agent
        editorial_synthesizer_agent
    end
    subgraph PIPE[academic-pipeline, 5 agents]
        pipeline_orchestrator_agent
        integrity_verification_agent
        state_tracker_agent
        collaboration_depth_agent
        claim_ref_alignment_audit_agent
    end

3.3 L3 Claim-Faithfulness Gate（v3.8 核心）

v3.7.3 + v3.8 解決 Zhao et al. (2026) 描述的「real citations deployed to support claims the cited references do not actually make」問題：

1. v3.7.3：每個引用都帶 three-layer citation anchor（DOI / source_pointer / locator）
2. v3.8：opt-in ARS_CLAIM_AUDIT=1 啟動 claim_ref_alignment_audit_agent，fetch 引用源頭 + 對照 anchor + 判定 claim 是否真的被支持
3. 5 個 HIGH-WARN class 透過 formatter terminal hard gate 阻擋輸出：
   • claim-not-supported
   • negative-constraint-violation
   • fabricated-reference
   • anchorless
   • constraint-violation-uncited

calibration target: FNR < 0.15 + FPR < 0.10（20-tuple gold set）。

3.4 Cross-Model Audit Gate（v3.6.7）

sequenceDiagram
    participant User
    participant CC as Claude (generator)
    participant CodeX as gpt-5.4-pro (verifier)
    participant Stage as Stage 2.5/4.5

    Note over User: export ARS_CROSS_MODEL="gpt-5.4-pro"
    User->>CC: /ars-full
    CC->>Stage: produce artifact
    Stage->>CodeX: cross-model verify (different model)
    CodeX-->>Stage: PASS / FAIL + critique
    Stage->>User: block if FAIL

目的：避免 verifier 與 generator 同模型造成的「cognitive frame 共謀」(v3.0 frame-lock 對症)。

4. Helper Scripts 詳細用法

4.1 10 個 Slash Commands

 1/ars-full              # 全流程 opus（research → write → review → revise → finalize）
 2/ars-plan              # Socratic 章節規劃 sonnet
 3/ars-outline           # 詳細 outline + evidence map（不寫全文）
 4/ars-revision          # 改稿 + R&R responses
 5/ars-revision-coach    # 解析審查意見 → Revision Roadmap + Response Letter skeleton (opus)
 6/ars-abstract          # 雙語 abstract + keywords
 7/ars-lit-review        # Annotated bibliography
 8/ars-format-convert    # LaTeX / DOCX / PDF / Markdown 互轉
 9/ars-citation-check    # 引用錯誤檢查
10/ars-disclosure        # 期刊專屬 AI-usage disclosure

4.2 環境變數

4.3 101 個 check script（品質把關 toolkit）

部分代表性的 script：

CI 跑 pytest tests/ 跑 1,500+ test，零 regression 才放行 release（見 Issue #128 closure note: “1505 passed (+23 new, 0 regression)"）。

4.4 外部 API 客戶端

• scripts/openalex_client.py — OpenAlex (https://api.openalex.org)
• scripts/semantic_scholar_client.py — S2 (https://api.semanticscholar.org/graph/v1)
• scripts/adapters/zotero.py — Zotero adapter
• v3.9.0+ 起做三方交叉驗證（cross-index triangulation）

5. 應用場景

5.1 場景 A：博士生第一次寫期刊論文

 11. /ars-full
 22. 輸入題目 + 預期投稿期刊
 33. ARS Stage 1: deep-research 跑 socratic + lit-review + PRISMA
 4   → 產出 literature_corpus + research questions
 54. Stage 2: academic-paper 跑 plan → outline → draft
 6   → 產出 MD + bilingual abstract
 75. Stage 2.5: integrity_verification_agent 跑（必過）
 8   → fail 退回 Stage 2
 96. Stage 3: academic-paper-reviewer 跑 EIC + 3R + DA
10   → 產出 reviewer scores + revision roadmap
117. Stage 4: revision mode
128. Stage 4.5: integrity 再驗
139. Stage 5: re-review
1410. Stage 6: report_compiler_agent 產 Process Summary
15    → 6-dimension Collaboration Quality Evaluation (1-100)

預算：≈ $4–6 / 篇 15k 字論文（opus 4.7 + sonnet 混用）。

5.2 場景 B：審查者用 ARS 當「審查助手」

 1You: 我收到一篇 ML 論文要審，請幫我跑 review
 2> /ars-* triggers academic-paper-reviewer skill
 3> 自動偵測 field（field_analyst_agent）
 4> 動態配置 EIC + 3 reviewer + DA
 5> 0-100 評分 rubric 對齊：
 6>   ≥80 Accept
 7>   65-79 Minor Revision
 8>   50-64 Major Revision
 9>   <50 Reject
10> 產 structured Editorial Decision + Revision Roadmap

5.3 場景 C：解析審查意見並生成回覆

1You: 我有 reviewer comments，請幫我整理成 revision roadmap
2> /ars-revision-coach（opus 模型）
3> 解析 R1/R2/R3 各自的 major/minor concern
4> 自動 group by 主題（method / data / framing / writing）
5> 產出 Response Letter skeleton（含 "Thank you for..." 模板）
6> + 對應 manuscript line-level revision action items

5.4 場景 D：開啟 cross-model + claim audit 雙保險

1export ARS_CROSS_MODEL="gpt-5.4-pro"
2export ARS_CLAIM_AUDIT=1
3# 然後在 Claude Code 內
4/ars-full

跑出來的論文：

• 每個 claim 都被 fetch source 驗證過
• Stage 2.5 / 4.5 integrity 用不同模型背對背 audit
• 任何 HIGH-WARN class 都會被 formatter 攔截

6. 資安掃描報告

掃描方法：grep -rE "os\.system|shell=True|child_process\.exec|eval\(|api_key=|password=|sk-[a-zA-Z0-9]{20}" + 檢視 hooks + 外部 API endpoint + 讀 SECURITY.md。

6.1 結論：🟢 LOW RISK

ARS 在資安實踐上相當謹慎：明確 SECURITY.md（含 prompt injection / credential leakage / data exfiltration scope）、無 eval/exec 動態執行、無 hardcoded secret、SessionStart hook script 自帶 “does not write outside its own stdout” 註記。

6.2 細項

6.3 SECURITY.md 明列威脅範疇

repo 自身 SECURITY.md 把以下列為 in-scope：

• Prompt injection 繞過 IRON RULE / integrity gate / ethics protocol
• Credential leakage (ARS_CROSS_MODEL / S2 key 設定錯誤)
• Data exfiltration（agent 把使用者研究資料送到非預期 service）
• Integrity gate bypass（跳過 Stage 2.5 / 4.5）

回報窗口：GitHub Security Advisories（私下回報），7 日內回應。

6.4 給使用者的建議

1. ✅ 學術 / 個人使用：可放心安裝
2. ⚠️ 處理未發表機密內容：避免啟用 ARS_CROSS_MODEL（會把內容送到第二個 LLM）
3. ⚠️ 企業 / 商業用途：CC-BY-NC 4.0 禁止，需聯絡作者另談授權
4. ✅ 想加層保護：開 ARS_CLAIM_AUDIT=1 讓 L3 audit 把關每個 claim ↔ reference

7. FAQ

Q1：和 agent-skills (tech-leads-club) 有什麼不同？ A：agent-skills 是「跨 14 種 agent 的通用 skill 註冊中心」，ARS 是「Claude Code 專屬的學術 deep-stack plugin」。前者強調廣度，後者強調垂直深度。

Q2：跑一次 full pipeline 多少錢？ A：作者文件 docs/PERFORMANCE.md 給出參考：15k 字論文 ≈ $4–6（用 Opus 4.7 跑 opus-routed command + sonnet 跑其他），實際依複雜度浮動。

Q3：可以不要全自動，只用一兩個 mode 嗎？ A：完全可以。/ars-plan（規劃）、/ars-lit-review（文獻回顧）、/ars-citation-check（引用檢查）都是獨立 mode。事實上作者「人類 in the loop」哲學就鼓勵這種用法。

Q4：支援哪些語言？ A：英文 + 繁體中文自動偵測（使用者打中文就回中文）。LaTeX 中文 PDF 用 Source Han Serif TC。

Q5：v3.10 conductor 何時上？ A：Issue #134 標記 OPEN，作者表示在 v3.9.2 hot-fix 設計時 explicitly 預留 v3.10 conductor 可繼承 v3.9.2 的 verifier + frontmatter sentinel，不需 rework。沒有公開時程，但活躍開發中。

Q6：可以用在我的 Codex / Cursor 嗎？ A：Codex 有 sibling repo academic-research-skills-codex（同 workflow content，Codex-native 打包）。Cursor 暫無官方版本，可參考 Issue #132 自行轉。

Q7：為什麼引用要做 3 層 anchor？ A：因為 Zhao et al. (2026, arXiv:2605.07723) 對 111M 引用做 audit 發現「真實引用但聲明錯誤」也是 hallucination 的一種；單看 DOI 抓不到。三層（DOI + source_pointer + locator）才能對 claim 做點對點驗證。

8. 進階技巧

8.1 自訂 Cross-Model

1# 用 GPT-5.4 Pro 當 verifier
2export ARS_CROSS_MODEL="gpt-5.4-pro"
3
4# 或自架 LLM (OpenAI compatible)
5export ARS_CROSS_MODEL="my-internal-llm@http://localhost:11434"
6
7# 取消
8unset ARS_CROSS_MODEL

8.2 用 ARS Material Passport 串自家 pipeline

Material Passport 是一份 JSON 紀錄，schema 11 包含：

 1artifact_id: <hash>
 2stage: <1-6>
 3data_access_level: raw|redacted|verified_only
 4task_type: open-ended|outcome-gradable
 5upstream_dependencies:
 6  - <parent_artifact_id>
 7repro_lock:
 8  env: { CLAUDE_MODEL: opus-4.7, ARS_CROSS_MODEL: gpt-5.4-pro }
 9  inputs_hash: <sha256>
10claim_audit:
11  enabled: true
12  high_warn_count: 0

你可以把外部工具產出對齊到這個 schema，跨 pipeline 共享 audit trail。

8.3 PRISMA-trAIce 系統性回顧

1/ars-* triggers deep-research with systematic-review mode
2> 自動套用 PRISMA-trAIce protocol（v3.4 Compliance Agent）
3> 產出 PRISMA flow diagram + Risk of Bias 矩陣

8.4 R&R Traceability Matrix（Schema 11）

revision mode 跑完，會產一份 R&R matrix：每條 reviewer comment ↔ 你的修改 ↔ manuscript line ↔ 證據連結。投稿時直接附上，省 30% 與審查者來回時間。

8.5 觀察 Collaboration Depth

v3.5 加的 collaboration_depth_agent 是 advisory（不擋你），但在 Stage 6 會出 6-dimension 報告：

• 1. Intent precision（你定義問題清楚程度）
• 2. Counter-evidence engagement（你對 DA 的抵抗）
• 3. Methodology depth
• 4. Synthesis quality
• 5. Revision discipline
• 6. Disclosure honesty

打 1-100 分，幫你看自己這次「用 AI 的姿勢」對不對。

9. 整合進其他工作流

9.1 與 paper-search / paper-qa-lite 整合

flowchart LR
    A[paper-search
跨資料庫蒐集] --> B[inbox/Paper/]
    B --> C[paper-qa-lite
本地 RAG 問答]
    B --> D[ARS deep-research
系統性回顧]
    D --> E[ARS academic-paper
撰寫]
    E --> F[ARS reviewer
多角度審查]
    F --> G[final PDF]

paper-search (本專案 skill) 蒐集 → ARS 加工成論文，是常見組合。

9.2 與 docling 整合

收到 PDF reviewer comments？

1docling: reviewer_comments.pdf
2> 產 md
3/ars-revision-coach
4> 解析 reviewer_comments.md → Revision Roadmap

9.3 與 quarkdown / kami 整合

論文寫完想出漂亮 HTML / PDF：

1# ARS 產 MD → quarkdown 出 paged HTML
2qd from: paper-final.md as paper
3# 或 kami 出 long-doc PDF
4kami: long-doc paper-final

10. 重點摘要 Checklist

• ARS = Claude Code 學術全流程 plugin（4 skill / 35+ modes / 38 agents / 10 stages）
• 設計鎖定 LLM 三大失敗模式：frame-lock / sycophancy / intent misdetection
• mandatory integrity gate（Stage 2.5 + 4.5 不可略過）+ cross-model audit + L3 claim-faithfulness
• v3.9.x 主軸：cross-index triangulation + phase boundary fence + client hardening
• 雙語（EN + 繁體中文）、6 種引用格式、5 種輸出（MD / DOCX / PDF / LaTeX / Markdown）
• 資安 🟢 LOW（無 eval / 無 hardcoded secret / 明確 SECURITY.md）
• CC-BY-NC 4.0（學術 / 個人 OK，商用不可）
• 預算約 $4–6 / 篇 15k 字論文
• 一行裝：/plugin marketplace add Imbad0202/academic-research-skills

11. 進一步閱讀

• GitHub repo：https://github.com/Imbad0202/academic-research-skills
• 繁體中文 README：README.zh-TW.md
• 完整架構：docs/ARCHITECTURE.md
• 效能與成本：docs/PERFORMANCE.md
• 安裝細節：docs/SETUP.md
• AI 失敗模式對照：academic-pipeline/references/ai_research_failure_modes.md
• Substack 文章（中文）：學術寫作不該是一個人的事
• Substack 文章（英文）：Academic Writing Shouldn’t Be a Solo Act
• 引用 hallucination 研究：Zhao et al. 2026, arXiv:2605.07723
• AI Scientist 研究：Lu et al. (2026, Nature 651:914-919)
• Codex sibling：https://github.com/Imbad0202/academic-research-skills-codex
• 作者贊助：https://buymeacoffee.com/crucify020v

Captured：2026-05-18 by gh-tutorial-qd workflow（depth=full / lang=zh-tw / qd_preset=report / security=on）。