LLM-Wiki

核心原则

将大语言模型（LLM）视为程序员，将维基百科视为代码库。用户负责提供材料和判断；代理负责提取持久知识、保留溯源信息、维护链接关系，并确保 Markdown 维基的结构一致性。

请将此文件作为操作技能的核心文档。使用 README.md 作为面向用户的概览，AGENTS.md / CLAUDE.md 用于完整协议说明，ROADMAP.md 用于项目规划。

启动每个维基任务前

1. 当任务涉及维基行为、源文件处理或导入/查询协议时，请查阅 AGENTS.md 或 CLAUDE.md。
2. 使用项目中的 Python 环境：Windows 上为 .venv\Scripts\python.exe，Unix 系统上为 .venv/bin/python，或配置后使用 uv run python。
3. 在执行维基操作前，运行 <PY> scripts/agent-bridge.py check。若报告缺少依赖项，请明确指出具体阻塞项，并仅在不依赖缺失运行时的任务中继续操作。
4. 保护 sources/ 目录：禁止在此目录中写入代理生成的摘要、草稿或推测性内容。只有用户提供的文件或经验证的网络/Zotero获取内容可作为源资产。
5. 编辑前检查 git status --short。不得回退用户更改。

选择工作模式

Agent Bridge 快捷命令：

<PY> scripts/agent-bridge.py check
<PY> scripts/agent-bridge.py status
<PY> scripts/agent-bridge.py lint
<PY> scripts/agent-bridge.py link --source "PageName" --mode light
<PY> scripts/agent-bridge.py merge --source "NewPage" --target "OldPage" --strategy append_related --dry-run
<PY> scripts/agent-bridge.py relink --since 2026-04-20 --mode deep --dry-run
<PY> scripts/agent-bridge.py index
<PY> scripts/agent-bridge.py query "question" --semantic

仅在人工脚本编写或调试时使用旧版命令 python -m src.llm_wiki ...。在导入过程中，不得以旧版 CLI 替代 LLM 的判断。

导入工作流程

1. 确认源文件存在于 sources/ 中，或来自真实且经过验证的网络/Zotero操作。
2. 若可用，提取源文件的元数据：标题、作者/创作者、URL、DOI、arXiv ID、Zotero 条目键、引用键以及源类型。
3. 将时间元数据与维基维护日期分开处理：

- published：论文/帖子/发布/文档的发布时间。

- updated_at_source：源端更新时间（如可用）。

- collected：用户保存/导入/Zotero 收集时间。

- ingested：llm-wiki 处理时间。

- date_precision：取值为 day、month、year 或 unknown。

1. 创建或更新最小但有用的 wiki/*.md 页面集合。每个非索引页应包含：frontmatter、一句定义、知识内容、相关页面、源文件引用和变更日志。
2. 为有时间标记的作品添加可见的时间锚点，尤其在概览页中：

- **[YYYY.MM] 作品名称**：表示日/月精度。

- **[YYYY] 作品名称**：表示年份精度。

- **[YYYY.MM-YYYY.MM]**：表示时间范围。

1. 当历史顺序重要时，使用 ## 时间线 / ## Timeline。在 ### 时间定位 / ### Temporal Position 中开始时包含：

- > **时间范围**：...

- > **阶段判断**：...

1. 对新页面运行 agent-bridge.py link。对于高置信度的关系，先预览 merge --dry-run，审查差异后，仅应用安全的向后兼容更新。
2. 更新 wiki/index.md 并追加至 log.md。

切勿将 created 或 updated 视为发表日期。它们仅是维基维护时间。

查询工作流程

1. 首先阅读 wiki/index.md。
2. 阅读相关页面及其链接邻近页面。语义查询可能发现候选页面，但页面内容才是事实来源。
3. 回答时使用 [[PageName]] 引用维基页面。
4. 若答案形成可复用的综合内容，根据用户意图判断是否将其归档至维基。

链接规则

• 在本地章节中首次有意义提及某个概念时即建立链接。
• 每个内部链接在导入结束后必须能解析到真实的 wiki/*.md 文件名。
• 使用规范文件名和别名，例如 [[AI-Coding-Workflow|AI 编码工作流]]。
• 避免过度链接。一个有效链接优于重复的冗余链接。
• 有帮助时描述时间关系：早期工作、后续研究、同期路线、综述、回顾性分析，或过时但具有历史意义。

Zotero 工作流程

将 Zotero 作为文献层，llm-wiki 作为提炼后的 Markdown 知识层。推荐的公开 Zotero 技能源为：

<https://github.com/openai/plugins/tree/main/plugins/zotero/skills/zotero>

当代理具备该技能或等效的 Zotero 能力时，它可以搜索本地 Zotero 库、列出收藏夹/标签、导出 BibTeX/引用、按需读取附件路径或索引全文，并在确认后导入 BibTeX/RIS 记录。

对 llm-wiki 而言，Zotero 结果仅用于源发现和溯源。若可用，应在 frontmatter 中保留 Zotero 标识符：

sources_meta:
  - title: "论文标题"
    type: "academic_paper"
    published: "2025-02"
    collected: "2026-05-24"
    ingested: "2026-05-24"
    date_precision: "month"
    zotero_item_key: "ABCD1234"
    citation_key: "author2025title"
    library_id: "0"
    zotero_uri: "zotero://select/items/ABCD1234"

除非重复的手动流程证明必要，否则不要构建原生的 llm-wiki Zotero 客户端。任意文档上传或附件管理不属于已验证的 llm-wiki 工作流程。

源文件获取安全须知

每次网络获取后，在导入前务必进行验证：

• 文件可读且非空。
• 内容不是错误页面、登录墙、付费墙提示或 JavaScript 占位符。
• 格式与文件扩展名匹配，例如 PDF 文件以 %PDF 开头。
• 标题和标识符与请求的来源一致。
• 提供了 DOI、arXiv ID、作者姓名或 URL 时，需确保其匹配。

若验证失败，请勿创建基于源内容的维基页面。在适当情况下将失败记录至 log.md，并请用户提供正确的来源。

文件处理

• 文本和 Markdown 文件：直接读取。
• PDF 文件：使用项目内置的 Python 工具（如 PyMuPDF）或 scripts/read_pdf.py；仅在必要时才回退到 OCR。
• 图像文件：在需要时使用视觉检查工具。
• Office 文件及其他二进制文件：在提取知识前，使用相应的解析器或工具处理。

优先使用项目管理的 Python 环境：.venv、uv run 或配置好的 conda 环境。不要随意使用全局 pip。

验证完成前的检查

对于仅文档类修改，运行：

git diff --check -- <changed-files>

对于维基/运行时操作，还需运行相关的 agent-bridge.py 命令（如 check、lint、link、merge --dry-run、status 或 query），并报告确切的阻塞项，若依赖缺失。

对于代码变更，运行针对性的 pytest 测试目标，或当修改影响共享行为时运行完整测试套件：

.venv\Scripts\python.exe -m pytest tests/

最后总结已更改的文件、验证输出结果，以及跳过的检查项及其原因。