My Wiki

My Wiki 是一个可直接交给 AI Agent 使用的本地优先知识管理项目。项目主体提供 CLI、可视化知识宇宙、知识维护和 Viki 问答；仓库内另带一个可单独安装的轻量 Skill，用于让其他工作区中的 Agent 调用已安装项目。

简体中文 · English

网页、PDF、扫描件、图片、Office 文档、聊天记录和官方资料里有大量有价值的信息，但它们通常散落在不同位置，很难持续整理，更难在以后准确复用。

My Wiki 让本地 AI Agent 负责知识的完整生命周期：保存 Reference 与 original，提取可读正文，蒸馏原子 Concept，建立关系与证据链接，回答问题，维护知识健康，并通过网页把知识呈现为可以探索和操作的知识宇宙。

默认不需要云数据库、向量数据库、Obsidian 或付费 API。知识以 Markdown、原始文件、快照和图片保存在你控制的本地文件夹中。

项目主体与 Skill 分离

My Wiki 的运行主体位于仓库根目录。把仓库作为 Agent 工作区打开后，Agent 可依据 AGENTS.md 直接运行 CLI、Dashboard、测试和容器部署，不需要先安装 Skill。

my-wiki-skill/ 是项目的一部分，但只是可选适配层。它可以单独安装到 Codex、Claude Code、OpenCode 等客户端；使用时会定位已注册的 My Wiki 项目。Skill 不再复制应用代码，也不保存知识库。若项目主体或本地知识库尚未建立，Agent 会先征得用户确认，再代为安装项目并初始化独立 vault。

my-wiki/
  AGENTS.md          Agent 打开项目时的入口说明
  scripts/           CLI 与知识维护主体
  assets/dashboard/  网页应用与本地服务
  deploy/            独立部署方案
  tests/             项目测试
  my-wiki-skill/     可单独安装的轻量 Agent 适配层

全局 Skill 不是 Dashboard 或 CLI 的运行依赖。只在 My Wiki 项目中工作时，无需把它安装到 Codex 或 OpenCode 的全局 Skill 目录。

My Wiki 由两个相互配合的使用界面组成，共享同一个本地知识库：

你可以只使用其中一种，也可以在聊天和网页之间随时切换。两种方式读写的是同一套知识，不需要同步两份数据。

三种使用方式

1. 把项目作为 Agent 工作区打开

克隆并注册项目后，用 Codex、Claude Code、OpenCode 等 Agent 直接打开项目目录，然后说人话：

在 D:\Knowledge\Personal 创建一个 My Wiki 知识库并设为默认。
把这篇文章入库：https://example.com/article
把这个 PDF 和其中的重要图片保存到知识库。
维护知识库。
根据本地知识回答这个问题，并展示相关证据图片。

Agent 会自动定位知识库，保存 Reference、original 和附件，创建或更新原子 Concept，维护双向关系，并优先用 Concept 回答、再回到 Reference 核实重要结论。你不需要记忆一套 CLI。

2. 在其他工作区中通过 Skill 使用

安装仓库中的 my-wiki-skill/ 后，Agent 可以从其他项目调用同一套 My Wiki 主体和本地知识库。Skill 只负责工作流、项目发现与引导安装；项目或 vault 缺失时，它会在用户确认后补齐，而不会把主体或知识内容复制进 Skill 目录。

3. 打开知识宇宙网页前端

对 Agent 说：

打开知识宇宙。
打开 My Wiki 前端。
打开知识图谱。

Agent 会启动本地网页应用。你可以：

• 在知识宇宙中观察多个知识星系及其交会；
• 进入知识星系，查看 Concept 星球关系网络；隐藏星系不会出现在宇宙图谱和概览统计中；
• 打开 Concept 页面，继续进入它背后的 Reference 证据层；
• 搜索 Concept、关系和来源，而不破坏当前图谱层级；
• 双击 Concept 或 Reference 进入内置 Markdown 工作台，在渲染阅读、源码编辑和实时渲染编辑间切换；文档大纲、公式/表格工具、图片选择、粘贴与拖入都直接作用于受控的本地 Markdown 与 references/assets/，不引入第二套笔记数据库；
• 输入网页链接，或上传文件、文件夹和 Markdown + 图片 ZIP 图文包；
• 查看统一维护队列：上传进入后台后立即显示等待、提取进度或失败状态，并可按 Reference 独立蒸馏或修复；批量维护会依据每条状态自动选择动作。本地提取使用独立的 2 个并发槽位，Agent 修复/蒸馏使用另一组 2 个并发槽位，同一 Reference 不会重复执行；
• 查看大文件与知识包进度：分片上传、逐页 OCR 和分批 MinerU 显示实际字节或页数，单进程提取、导入预览与最终写入显示当前处理阶段；
• 使用 Viki 基于 Concept、Reference 和相关图片进行问答；可限定一个或多个知识星系，按需开启联网补充，并查看引用证据；
• 在 Viki 中管理多个本地会话、暂停当前请求、进入全屏、复制回答，并把整个会话导出为 Markdown/ZIP 图文包或快速笔记；CLI/模型切换从下一轮生效，不会中断当前回答；
• 使用快速笔记创建、导入、编辑和删除本地 Markdown/ZIP 图文笔记，保存后可选择进入正常入库与维护流程；
• 新增、重命名、隐藏/显示或删除知识星系，并可导出单个星系、预览及导入别人分享的 .mywiki 知识包；删除前会把完整星系移入 .my-wiki/trash/galaxies/，可从网页回收站恢复或永久删除。共享 Concept 与证据不会被误删，也不会生成 Uncategorized 星系。

网页前端默认只监听 127.0.0.1。日常通过 Agent 入库或维护时不会自动启动它；只有你明确要求打开知识宇宙、前端或 Dashboard 时才会启动。需要隔离的公网演示时，可使用 deploy/apple-container/ 的 Apple Container 方案并在本机端口前接 Cloudflare Tunnel。

从资料到可复用知识

网页 / PDF / 扫描件 / 图片 / Office 文档 / 外部平台
                         |
                         v
                 Reference 证据层
              原文、original、图片、元数据
                         |
                     AI Agent
              蒸馏、关联、核实、维护、修复
                         |
                         v
                   原子 Concept 页面
             概念、方法、API、实体、流程
                         |
          +--------------+--------------+
          v                             v
     有依据的知识问答               知识宇宙网页

My Wiki 不是给每份文档生成一段摘要。一份 Reference 可以更新多个长期 Concept，一个 Concept 也可以综合多份 Reference。只有 Concept 已建立、双向证据关系闭合、后续事项处理完成，一份 Reference 的 workflow_status 才会变为 processed。

这种结构让知识可以被反复使用：今天保存的资料可以更新已有 Concept，明天的新问题可以复用这些 Concept，重要结论仍然能一路回到原文、图片或 PDF 核实。

探索知识宇宙

• 知识宇宙：整个知识库的全局视图，展示多个知识星系以及它们通过共同 Concept 形成的联系。
• 知识星系：一组成体系、可以独立理解和复用的知识集合，例如 FlexSim、Agent 开发或项目经验。
• Concept 星球：一篇原子 Concept，表达一个概念、方法、实体、流程或可长期复用的结论。
• 参考证据层：支撑某篇 Concept 的网页、Markdown、PDF、图片和其他 Reference。

图谱不是额外维护的一套数据库。它直接从 Concept 与 Reference 的关系生成，知识发生变化时，运行中的前端会自动刷新。

分享和复用知识星系

知识星系可以导出为单个 .mywiki 知识包。它不是只有几篇摘要，而是一套带证据的知识集合，包含：

• 这个星系的 Concept Markdown；
• Concept 关联的 Reference Markdown；
• 可用的来源 URL；
• 相关图片与图像索引；
• Reference 明确引用的网页快照、PDF 和其他 original。

接收方可以先预览重复项、重命名和冲突，再确认导入自己的知识宇宙。即使原始资料没有 URL，例如本地 PDF，知识包仍然可以保留完整证据。

你既可以在网页中导入和导出，也可以直接告诉 Agent：

把“FlexSim”知识星系导出成知识包。
预览导入这个 flexsim.mywiki 知识包。
确认导入，并把星系名改成“仿真工程”。

这使 My Wiki 不只是个人资料整理工具，也可以成为可传播、可验证、可继续维护的知识生态基础。

Open Knowledge Format v0.2

Concept 默认采用 Google Open Knowledge Format v0.2 可消费的 Markdown 表达：标准 YAML frontmatter、draft|stable|deprecated 生命周期、结构化来源对象、标准 Markdown 关系链接和按来源 ID 连接的证据脚注。My Wiki 的知识星系、别名和证据闭环字段作为 OKF 允许的扩展键保留；系统不会把“已经蒸馏”冒充为人工验证。

# 审计当前 Concept 的 OKF v0.2 兼容性
npm run wiki -- okf-audit

# 预览旧知识页的迁移数量；--apply 会先备份 concepts/ 再转换
npm run wiki -- okf-migrate
npm run wiki -- okf-migrate --apply

# 导出全部知识或单个知识星系为独立 OKF directory bundle
npm run wiki -- export-okf
npm run wiki -- export-okf --galaxy "AI" --output /path/to/ai-okf

.mywiki 是经过 OKF v0.2 审计的可移植知识星系包：包内直接采用 index.md、log.md、concepts/、references/ 布局，并在清单中保留星系名、工作流状态、校验和与冲突处理等 My Wiki 扩展。解包后的知识内容可被通用 OKF 消费者读取，My Wiki 则额外恢复可继续维护的证据闭环。

为什么选择 My Wiki

• 本地优先：Markdown、原件、网页快照和图片都在你控制的目录中。
• Agent 自动维护：短指令即可完成入库、蒸馏、链接、检查和修复。
• 结论可追溯：Concept 结论回链 Reference，重要信息可以核实到原文与图片。
• 面向复用而非堆积：资料被整理成原子 Concept 和关系，而不是只进入一个搜索黑盒。
• 网页应用可操作：不仅看图谱，还能添加资料、处理维护队列、问 Viki、导入和导出知识星系。
• 支持多种本地文档：文本 PDF、扫描 PDF、图片、DOCX、PPTX、XLSX、文件夹批次和 ZIP 图文包。
• 质量感知的 PDF 解析：逐页检查乱码、稀疏文本和公式版面风险；中文 OCR 会清理逐字空格，低质量页面不会静默进入维护。
• 失败不会伪装成功：空内容、低置信度或不完整解析会锁定为 needs-followup，不会被当成已读资料。
• 开放且可迁移：Wiki 可审计并导出为 OKF v0.2，知识也可用任意 Markdown 编辑器打开或接入 Obsidian、RAG 和其他 Agent 工具。
• 零成本起步：只需要 Node.js 和一个已经可用的本地 Agent 客户端。

统一文档提取与验收

My Wiki 自己定义文档 IR、逐页质量门禁和验收报告，外部解析器不能自行宣布资料可维护。每次本地文档提取都会在知识库的 .my-wiki/extractions/ 写入一份可读的 *.report.json 和压缩的 *.document.json.gz；Raw frontmatter 记录两者路径。报告统一汇总页覆盖、版面/OCR 质量、公式、编码和本地附件门禁，只有通过硬门禁的证据才能进入蒸馏。

推荐工具链分工如下：

• MinerU 是中文扫描件、公式与表格密集技术 PDF 的主解析器。
• Docling 提供统一结构、阅读顺序、表格和元素级页码/bounding box provenance，也是 Office、OpenDocument 和 EPUB 的首选解析器。
• My Wiki 内置的 Agent 视觉修复器借鉴 doc7 的页级视觉重建思路：将中央门禁标出的风险页渲染为图片，交给现有 OpenCode 或 Codex CLI 的多模态模型。结果必须明显优于原页才会替换，并记录 provider、模型与被拒绝页，不需要安装 doc7。
• PDF.js/Tesseract 是无高保真引擎时的降级路径，不能覆盖已经实际运行但失败的 MinerU 或 Docling 结果。

安装 uv 后，在 macOS、Windows 或 Linux 项目目录运行：

npm run document:setup
npm run document:doctor

该命令安装项目验证过的 MinerU 与 Docling；模型文件由各引擎首次使用时下载。疑难页视觉修复复用已经登录的 OpenCode/Codex CLI 与其中可用的多模态模型，不安装额外文档 CLI。npm run pdf:setup 仍保留为只安装 MinerU 的兼容命令。

自动 PDF 路由默认先用 MinerU；仅当 MinerU 不可用时尝试 Docling，再降级到 PDF.js/Tesseract。可用 MY_WIKI_PDF_ENGINE=mineru|docling|pdfjs|tesseract 强制指定。风险页视觉修复默认复用可用的 OpenCode/Codex，可用 MY_WIKI_VISUAL_REPAIR_MODE=off|auto|required、MY_WIKI_VISUAL_REPAIR_PROVIDER、MY_WIKI_VISUAL_REPAIR_MODEL 和 MY_WIKI_VISUAL_REPAIR_MAX_PAGES 控制。超过 512 页的 PDF 默认按 64 页分批运行 MinerU，再恢复连续页码和图片命名空间；MY_WIKI_MINERU_BATCH_THRESHOLD_PAGES 和 MY_WIKI_MINERU_BATCH_PAGES 可调整批次。

完整的 IR、路由、报告字段和验收规则见 docs/document-extraction.md。

最终写入 Raw 的 ## Capture 正文还会执行编码完整性门禁。任何 U+FFFD 替换字符都会按页记录并将 Raw 锁定为 needs-followup；捕获、重提取、Agent 修复、维护预检和 lint 都会重复验证，避免后续写回造成的乱码沿用旧质量分数。

与 RAG、LLM + Obsidian 的区别

My Wiki 重点解决知识进入检索之前的整理层：把原始资料变成可读、有关系、能核实、可维护的长期知识。

My Wiki 不排斥 RAG 或 Obsidian。你可以用 Obsidian 打开同一个知识库，也可以在规模真正需要时，把已经整理干净的 Concept 与 Reference 交给 RAG。

快速开始

需要 Node.js 18+ 和 npm。先安装并注册项目主体：

git clone https://github.com/NimaChu/my-wiki.git
cd my-wiki
npm run setup
npm run wiki -- init /path/to/my-vault --name personal --use

之后可以直接把 my-wiki 项目目录