LLM-Wiki

核心原则

将大语言模型（LLM）视为程序员，将维基视为代码库。用户负责提供材料和判断标准；代理（Agent）负责提取持久性知识、保留溯源信息、维护链接关系，并确保 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 的判断能力。

正确理解深度校验结果

agent-bridge.py lint 报告的 Shallow Pages 仅为警告级别。检测器会排除“相关页面”“来源”“变更日志”等部分，然后结合归一化知识量、段落与章节结构、本地文本来源密度、来源数量和压缩率进行评估。默认跳过 QRF；lint_depth: skip 仅用于有意保持简洁的页面，其省略原因需在来源覆盖审计中说明。

干净的深度检测结果并不意味着已完成来源覆盖。请重新审阅分配的源文件，涵盖重要机制、公式、证据、比较、流程、失败模式、权衡因素和决策规则。切勿机械地填充页面以满足阈值要求。

导入工作流

1. 在解读任何源文件或提取路径前，务必先确认其有效性。
2. 在起草前建立临时源内容映射。记录主要主题单元、机制、公式、定量证据、比较、流程、失败模式、决策规则、待解决问题及提取不确定性。
3. 明确分配每个重要单元：将其纳入目标页面、合并至已有页面、创建独立可复用的概念页，或记录具体的遗漏理由。不要因迎合摘要模板而忽略实质性内容。
4. 选择合适的页面原型和标题结构。定义、溯源、相关页面、来源和变更日志为不变项；机制、推导、比较、数据流、决策指南、失败模式、证据、争议点和开放问题为条件性章节。
5. 构建最小化但能保留原始推理逻辑的页面。解释“为何如此”“如何实现”“在何种假设下成立”以及“在何处可能失效”。当源文件依赖时，必须保留核心公式、数值背景、版本差异和工程权衡。
6. 在标记页面为活跃前，执行覆盖审查。所有重要源单元必须存在、已分配至其他页面，或在工作笔记中明确说明被有意省略的原因。
7. 执行深度审查：拒绝仅重复抽象、用标签替代因果机制、列出比较但无维度、或使用泛化边界陈述的页面。
8. 批量导入时，对比草稿是否存在模板坍缩现象。相似的标题与项目符号模式仅在底层知识结构真正相似时才可接受。
9. 当历史顺序重要时，添加时间元数据和可见的时间锚点。
10. 内容审查通过后，再运行链接发现与安全的反向合并，最后更新 wiki/index.md 和 log.md。

源映射与覆盖笔记是代理的临时工作状态。请将其保存在 sources/ 外部，仅在用户请求导入审计或实验时保留在 temp/ 中。

永远不要将 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 记录。

在执行任何 Zotero 操作前，需确认可用的 Zotero 兼容 MCP/工具能访问目标库。对于读取流程，确认集合搜索、条目元数据及附件路径/全文访问功能正常。对于写入流程，须在操作前确认具体能力支持：子笔记创建/更新、增量标签更新、相关条目链接为独立权限。若 Zotero Desktop、MCP 访问或写入能力不可用，应报告阻塞点，并仅在不依赖这些功能的前提下继续维基本地工作。

对 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"

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

Zotero 关联的源文件

使用 Zotero 条目键和附件键作为跨设备稳定的标识符。将私有的 Zotero 源绑定信息存储在 sources/zotero/metadata.yaml 中；该文件为用户本地私有，不得提交至版本控制。将 sources/zotero/ 视为生成的本地符号链接缓存。代理可使用 scripts/zotero_sources.py --dry-run 预览，或使用 scripts/zotero_sources.py 实际生成 metadata.yaml 中声明的别名。

sources/zotero/metadata.yaml 可包含本地绝对路径，因其为私有操作元数据，非共享维基内容。禁止将 LLM 生成的摘要、草稿或合成知识写入 sources/zotero/ 及其元数据。生成的知识应保留在 wiki/ 中。

针对 Zotero 支持的导入流程：

1. 使用 Zotero MCP 查找集合/条目/附件键及本地附件路径。
2. 在 sources/zotero/metadata.yaml 中记录源绑定信息。
3. 使用 scripts/zotero_sources.py 将 sources/zotero/... 符号链接实际化。
4. 通过符号链接别名路径，以常规协议模式导入。
5. 如可用，将 zotero_item_key、zotero_attachment_key、library_id 和 zotero_uri 保留在页面 frontmatter 中。
6. 仅将 Zotero 子笔记作为索引卡片使用：包含维基页面路径、简短摘要、同步哈希/时间戳及已审核的关系笔记。不得将完整维基页面镜像至 Zotero 笔记。
7. 关系审查完成后，可选地使用 Zotero MCP 添加 llm-wiki:* / rel:* 标签及相关条目链接。

网络获取的安全性

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

• 文件可读且非空。
• 内容非错误页、登录墙、付费墙提示或 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/

最终总结已更改文件、验证输出及跳过的检查项，并注明跳过原因。