快速触发词 / Quick Trigger Reference

学术知识库 / Academic Knowledge Base

中文 / Chinese | [English below each section]

面向学术研究者的个人知识中枢 —— 整合 Karpathy LLM Wiki 知识编译 + SmartLib 文献检索 + 向量化语义检索，让每一次检索和研究都沉淀为自己的知识资产。

A personal knowledge hub for academic researchers — integrating Karpathy LLM Wiki knowledge compilation + SmartLib literature search + vectorized semantic retrieval. Every search and study session compounds into your own knowledge asset.

来源参考 / Source References

本技能的设计架构和工作流继承自以下两个上游技能：

参考技能 1：Karpathy LLM Wiki

• 技能位置：~/.workbuddy/skills/Karpathy LLM Wiki/
• 核心理念：用 LLM 增量构建和维护持久化 Wiki 知识库，而非每次查询时做 RAG
• 本技能继承：Raw 不可变性、LLM 维护 Wiki 层、ingest/query/lint 操作、[[wiki-links]] 格式

Inherited: Raw immutability, LLM-owned wiki layer, ingest/query/lint operations, wiki page format.

参考技能 2：smartlib-literature-search

• 技能位置：~/.workbuddy/skills/smartlib-literature-search/
• 版本：v3.0
• 核心理念：基于 SmartLib 开放平台 API 提供中外文学术文献检索，已接入全程自动化服务（gateway 注册 + 配额消耗 + 微信支付充值）
• 本技能继承：文献检索 API + 认证流程、元数据字段结构、三级检索策略、外部检索联动。配额共享——与 literature-search 使用同一 gateway 凭证和配额

Inherited: SmartLib API auth, metadata schema, search strategies, field validation. Quota shared with literature-search.

核心架构 / Core Architecture

~/.workbuddy/academic-kb/
├── raw/                          # 原始资料（不可修改 / Immutable）
│   ├── literature/               #   文献全文 PDF/解析文本
│   ├── news/                     #   资讯/报道原文
│   └── personal/                 #   个人实验数据、笔记
├── db/                           # 结构化数据库
│   ├── literature.json           #   文献元数据（Identifier 为唯一 key）
│   ├── news.json                 #   资讯条目
│   ├── personal_data.json        #   个人学术数据
│   └── tags.json                 #   标签体系
├── wiki/                         # LLM 维护的 Wiki 知识层
│   ├── index.md                  #   知识目录
│   ├── log.md                    #   操作日志
│   └── [topic-pages].md          #   主题/概念页面
├── vectors/                      # 向量化存储
│   ├── embeddings.json           #   向量数据
│   └── vector_config.json        #   向量化范围配置
├── sessions/                     # 研究专题（文献子集+笔记+分析）
│   └── {slug}_yyyymmdd/
│       ├── session.json           #   专题元数据
│       ├── literature.json        #   选中文献快照
│       ├── notes.md               #   用户研究笔记
│       └── analysis.md            #   AI 生成的研究综述
└── KB-SCHEMA.md                  # 知识库 Schema 与约定

凭证与配额 / Credentials & Quota

本技能不独立注册，复用 smartlib-literature-search 的 gateway 凭证和配额：

检查 smartlib-literature-search 的 config.json
  ├── SMARTLIB_EMAIL 已配置 → 复用凭证，进入配额检查
  └── SMARTLIB_EMAIL 未配置 → 引导用户先注册:
        "📋 知识库需要 SmartLib 检索能力。首次使用需绑定邮箱（免费 100 次/月，仅用于配额管理），请输入邮箱即可开始:"
        用户输入 → 调 gateway /register（无需验证码）→ 写入 config.json → 完成

注意：注册无需验证码，极速完成。

配额消耗规则 / Quota Consumption Rules:

本技能与 smartlib-literature-search 共享配额和计次规则。配额按实际 API 接口调用次数计费，共 5 个接口，每次调用计 1 次。

Shared quota and billing rules with literature-search. 5 interfaces, each successful call = 1 quota. Failed calls do NOT consume quota (v36).

计费接口清单（5个）/ Billable Interfaces (5 total):

不计费的操作 / Non-billable Operations:

🔒 配额耗尽处理 / Quota Exhaustion

配额耗尽后暂停外部检索请求：

配额耗尽后的提示格式：

⚠️ 您的 SmartLib 检索配额已用尽。

知识库内 {N} 篇已有文献仍可正常检索、管理、导出。
但外部检索、入库匹配等需要调用 SmartLib 的功能已被暂停。

> 💰 充值套餐：
> 体验包：¥9.90 / 1000次
> 月付基础：¥29.00 / 5000次/月
> 月付进阶：¥99.00 / 20000次/月
> 月付专业：¥299.00 / 100000次/月
> 回复「充值」获取微信支付码，恢复 SmartLib 外部检索能力。

重要规则：

• 配额耗尽后，所有需要调用 SmartLib API 的操作（外部检索、入库匹配、新文献补充）一律拒绝，不展示任何部分结果
• 知识库内已有文献的检索、标签管理、导出、Wiki 维护、研究专题 — 不受影响（纯本地操作）
• 充值后立即恢复所有外部检索功能

输出规范 / Output Standards

每次调用 SmartLib API 后，在结果末尾展示配额状态：

📊 本次消耗 {n} 次 | 剩余 {remain} 次 (共 {total} 次/月)

知识库初始化 / KB Initialization

无需显式"初始化"。 懒加载引导式设计——首次使用任何功能时，基础设施自动静默创建。

No explicit "init" required. Lazy-loading guided design.

自愈式就绪 / Self-Healing Readiness

向量化方案备选 / Vectorization Options

数据入库 / Data Ingestion

支持 4 种数据类型入库。

类型 1：SmartLib 检索结果入库

触发：用户在使用 smartlib-literature-search 后说"保存到知识库"、"加入知识库"

用户指定入库的检索结果
  ├── 遍历每条结果
  │     ├── Identifier 去重检查（db/literature.json）
  │     │     ├── 已存在 → 跳过
  │     │     └── 不存在 → 入库
  │     └── 入库操作：写 literature.json + 下载原文到 raw/ + 向量化（若配置）
  └── 汇总提示入库结果

文献元数据格式（db/literature.json）：

{
  "Identifier_Value": {
    "identifier": "文献唯一ID",
    "title": "文献标题",
    "authors": ["作者1", "作者2"],
    "source_name": "期刊/来源",
    "publish_year": "2025",
    "abstract": "摘要内容",
    "keywords": ["关键词1"],
    "doi": "10.xxxx/xxxx",
    "core_indexing": "SCI;EI",
    "source": "smartlib",
    "source_links": [
      {"db_id": "scopusjournal", "db_title": "Scopus", "link": "https://www.scopus.com/..."},
      {"db_id": "wsoscimagazine", "db_title": "WoS SCI", "link": "https://www.webofscience.com/..."}
    ],
    "vectorized": true,
    "tags": ["深度学习"],
    "notes": ""
  }
}

source_links 字段说明：从 SmartLib 详情接口的 Source 字段自动提取，保留原始数据库来源链接（覆盖300+数据库，如Scopus/WoS/EI/PubMed等，覆盖率100%，平均4.75个链接/篇）。入库时自动保存，支持多源交叉验证。

类型 2：用户上传文献入库

触发：用户提供 PDF/Word/Markdown/BibTeX 文件路径

Step 1：解析文献（PDF 提取文本 / Word 解析结构 / BibTeX 解析字段）
Step 2：匹配 SmartLib（用标题+作者检索 API 4，标题相似度 > 80% 则合并补全 DOI/ISSN/核心收录）
Step 3：存储（原文 → raw/literature/，元数据 → literature.json，向量化）

未匹配 SmartLib 的文献标注 source: "user_upload"。

类型 3：资讯/报道入库

触发：用户提供 URL 或粘贴文本

Step 1：提取标题、来源、日期、摘要
Step 2：原文 → raw/news/，元数据 → db/news.json

类型 4：个人学术数据入库

触发：用户上传实验数据、CSV、笔记等

Step 1：解析数据（CSV 保持表格结构 / 文本 Markdown 存储）
Step 2：询问是否关联已有文献
Step 3：原文 → raw/personal/，元数据 → db/personal_data.json

向量化服务 / Vectorization Service

API 调用规范

统一使用 OpenAI 兼容格式：

POST {base_url}/embeddings
Authorization: Bearer {api_key}
Body: {"model": "{model_name}", "input": ["文本1", "文本2"]}

批量向量化

• 单次最多提交 32 条
• 每批 32 条并发（最多 3 批并行）
• 单批失败自动重试 3 次（指数退避）

向量化触发条件

检索策略 / Retrieval Strategy

双轨检索流程

用户查询
  │
  ├── 1. 知识库分词匹配检索
  │     ├── 中文分词 → title/abstract/keywords 倒排匹配
  │     └── BM25 评分（标题 > 关键词 > 摘要）
  │
  ├── 2. 知识库向量语义检索
  │     ├── 查询向量化 → 余弦相似度匹配
  │     └── 返回 Top-N（N = 分词匹配结果的 2 倍）
  │
  ├── 3. 去重合并
  │     └── BM25 × 0.6 + Vector_Similarity × 0.4
  │
  ├── 4. 自适应外部检索
  │     ├── 知识库 ≥ 3 条 → 知识库置顶 + 正常外部检索
  │     ├── 知识库 1-2 条 → 知识库置顶 + 外部检索加倍
  │     └── 知识库 0 条 → 全量外部检索
  │
  └── 5. 结果展示（分区：知识库 [📚] / 外部 [🌐]）

结果展示格式

🔎 检索："{用户查询}"

════════════════════════════════
📚 你的知识库（共 N 篇）
════════════════════════════════
| # | 收录 | 标题 | 作者 | 来源 | 年份 |
|---|------|------|------|------|------|
| 1 | [SCI] | ... | ... | ... | 2024 |

════════════════════════════════
🌐 外部检索补充（SmartLib，共 M 篇）
════════════════════════════════
| # | 收录 | 标题 | 作者 | 来源 | 年份 |
|---|------|------|------|------|------|
| 1 | - | ... | ... | ... | 2025 |

💾 输入 "保存 1,3" 将外部结果加入知识库

Wiki 知识层维护 / Wiki Maintenance

继承自 LLM Wiki 模式，入库后 LLM 自动维护知识网络。

触发时机

入库后更新流程

文献入库 → 提取主题 → 检查已有 Wiki 页面 → 创建/更新概念页
  → 写入引用 → 更新交叉引用 → 检测矛盾 → 更新 index.md → 追加 log.md

Lint（健康检查）

批量入库 ≥ 5 篇后自动执行，或用户手动触发。检查项：

1. 矛盾检测：不同文献间结论冲突，标注 [⚠️ 矛盾]
2. 过时检测：超过 3 年未更新的概念页
3. 孤立页面：无入链的 Wiki 页面
4. 冗余检测：内容高度相似的页面

参考文献管理 / Reference Management

导出格式

研究专题 / Research Sessions

从知识库中挑选文献子集组成研究专题。专题自包含（文献快照 + 笔记 + AI 分析），可独立导出迁移。

Create focused research sessions from your KB. Self-contained and portable.

触发场景

存储结构

~/.workbuddy/academic-kb/sessions/{slug}_{yyyymmdd}/
├── session.json          # 专题元数据（标题、来源、状态）
├── literature.json       # 选中文献快照（自包含可迁移）
├── notes.md              # 用户研究笔记
└── analysis.md           # AI 生成的研究综述

专题操作

Sessions are snapshots — editing session content never affects the main KB.

知识库统计 / KB Statistics

触发：用户说"知识库统计"、"KB Stats"等

生成交互式 HTML 报告（模板 kb-report.html），包含：

报告通过 preview_url 打开。未初始化时显示引导页。

配置管理 / Configuration Management

Key 写入 ~/.workbuddy/academic-kb/vectors/vector_config.json 的 api_key 字段。

与外部技能的联动 / Integration with Other Skills

安全与隐私 / Security & Privacy

错误处理与回退 / Error Handling & Fallback

版本历史 / Version History