oh-my-wiki

oh-my-wiki（OMW）

一种与存储无关的 LLM Wiki 技能。采用 Andrej Karpathy 的三层模式（Raw / Wiki / Schema），并支持每个知识库使用混合的 memo-only 和 wiki-mode。操作定义在 commands/*.md 中。确定性 I/O 定义在 scripts/*.py 中。状态存储在全局注册表 ~/.omw/registry.db 中（可通过 OMW_HOME 更改根目录）。知识库内容存储在各知识库注册路径下。

短别名： OMW（小写 omw）。oh-my-wiki 和 omw 均指向此技能。

⛔ 强制规则——在进行任何操作之前阅读（不可协商）

1. 只能使用 omw CLI。绝不能调用内部实现。 所有操作都必须通过 omw 命令执行（omw status、omw vault create <name> --mode wiki --type <markdown|obsidian>、 omw vault use、omw search、omw fetch、omw ingest、omw query、omw connections 等）。 禁止运行 python3 -m scripts.<anything>、python3 -c "from scripts import …"， 也禁止直接导入或执行 scripts/*.py 模块（registry、adapters、reindex、wizard 等）。 scripts/ 包是内部实现细节，不是用户界面。
   • CLI 预检（首次使用）： 如果无法调用 omw 命令，运行 bash "<this skill dir>/bin/ensure-cli.sh" 一次。脚本会在安装 CLI（pipx/pip）前征求用户同意， 并输出 OMW_BIN=<path>。在本次会话中，使用该绝对路径调用 omw …（PATH 会在下次会话刷新）。绝不能 改用 python3 -m scripts.*。
2. 网络搜索必须通过 omw search "<query>" 进行。 该命令会使用用户配置的 提供方，并保持 Wiki 的来源信息完整。处理 OMW 工作时，不要使用自己的／原生网络搜索 工具。
3. 只能通过 omw vault create <name> --mode <mode> --type <markdown|obsidian> 创建知识库—— 绝不能自行调用 registry/adapters 来构建知识库。
4. 使用 omw fetch <URL> 或 omw ingest 导入来源——绝不能手动将文件写入 raw/。 omw search 遇到 429／空结果时会自动在密钥配置的提供方间回退；抓取时，先尝试原生 抓取，再使用 omw fetch（它会依次尝试 urllib→chromium→cloud）。

如果你发现自己正要编写 python3 -c、python3 -m scripts，或使用原生网络 搜索，请立即停止，改用上面对应的 omw 命令。

当前状态

当前版本支持七种知识库模式、基于图谱的 lint、autoresearch、 六种 Wiki 维护角色、Obsidian/Logseq 查看器、URL 抓取 + 收件箱、 高精度的逐提示词召回、Claude Code 和 Codex 的同项目分阶段会话连续性、 本地嵌入，以及确定性的生命周期指导。 使用方法请参阅 README.md、TUTORIAL.md 和 TUTORIAL.ko.md。

步骤 1 — 读取注册表状态

在进行任何其他操作之前，始终先执行此操作：

命令接口——请先阅读。 omw 只有两种运行方式， 没有独立脚本 CLI。不要臆造 omw_db.py、 vault.py、cli.py 或 bootstrap.py 这类文件名——它们并不存在。

1. 确定性操作（状态、知识库管理、lint、搜索、服务、架构、取代、审查、链接、字段、视图、可见性、收件箱、抓取、重新索引、连接）：运行 omw CLI — omw status、omw vault list、omw vault create <name> --mode wiki、 omw vault use <name>、 omw vault info <name>（单个知识库的 JSON 卡片：路径／类型／模式／活动状态／归档状态 + 笔记数量）、 omw vault current [--json]（打印活动知识库的名称）、 omw vault rename <old> <new>（重命名注册表标签；保留索引）、 omw vault move <name> <new-path>（在磁盘上迁移知识库文件夹 + 更新其路径）、 omw vault set <name> [--mode M] [--config k=v]（仅编辑模式／配置；类型／路径／名称由 move／rename 管理）、 omw vault archive <name> / omw vault unarchive <name>（隐藏／恢复知识库；omw vault list --all 会显示已归档的知识库）、 omw vault delete <name>（默认软删除到回收站；使用 --hard --yes 可永久清除）、 omw lint、omw schema list、omw supersede <relpath> --by <slug>、 omw review due、omw serve（仅检索的消息查询 API——参见 references/messenger-api.md）、 omw view [page] [--search Q] [--viewer obsidian|logseq] [--vault <name>] [--print]（通过 URI scheme 在 Obsidian 或 Logseq 中打开知识库／页面／搜索；配套命令：omw setup viewer）、 omw visibility get <relpath> / omw visibility set <relpath...> public|private（管理单页可见性）、 omw inbox add <url> / omw inbox list / omw inbox remove <url> / omw inbox run（将 URL 加入队列，然后批量抓取到 raw/）、 omw embed status|list|use <model>|add <model>|install|reindex（本地嵌入模型：选择／管理 FastEmbed + sqlite-vec；会在一次性数据库中重建，并且仅在完全成功后替换现有向量索引）、 omw fetch <url> [--backend auto|urllib|chromium|cloud] [--vault] [--today YYYY-MM-DD]（将一个 URL 或 YouTube 字幕抓取到 raw/，按 urllib → chromium → cloud 的分层方式处理，并防护 SSRF）、 omw reindex [--full]（将文件重新扫描到注册表——注册正文中的 [[wikilinks]]，以便搜索／连接；直接写入或手动编辑 wiki 页面后请运行此命令，以更新链接图谱）、 omw connections [--no-reindex]（链接图谱中的社群／枢纽／意外桥接；会先自动重新索引，让新写入页面的链接及时进入图谱）。 直接编写的 Wiki 页面在重新索引前不会被编入索引。 将 raw/ 提炼为 wiki/ 页面时，直接写入文件后，其中的 [[wikilinks]] 只有在运行 omw reindex（或任何会重新索引的操作）后才会进入链接图谱；omw connections 会自动为你执行此操作。切勿运行 python3 -m scripts.reindex——请使用 omw reindex。 可见性（默认安全）： omw serve 只返回 frontmatter 中带有 visibility: public 的页面。没有此字段的页面会被视为私有，绝不会被提供。请使用 omw visibility set <relpath...> public 明确发布页面。 页面类型约定（必需的 frontmatter 字段和章节）位于 schemas/<type>.yml； 知识库可通过 <vault>/schemas/ 覆盖或添加类型（使用 omw schema show <type> 查看）。 页面可信度约定：confidence: high|medium|low；已弃用的页面带有 status: superseded + superseded_by: <slug>。每个页面的审查周期位于其 frontmatter 的 review: 区块中（last／due／interval_days）；omw review due 会列出到期项。 Wiki 查询在可用时使用 SQLite FTS5 全文检索（对标题 + 摘要 + 标签 + 正文进行 BM25 排序）， 否则自动回退到 token 评分器；随后 commands/query.md 会使用 LLM 对候选结果重新排序。 嵌入／混合策略使用本地 fastembed 模型（默认 intfloat/multilingual-e5-small），可通过 omw setup recall 或 omw embed use <model> 配置。 现有页面的未链接提及会自动生成建议（omw links suggest / lint 的 link_suggestions），并通过 omw links link <relpath> --to <slug> 插入；也可在一次明确确认后，通过 omw links link --from-suggestions 批量插入。页面 可在 frontmatter 中声明可选的 aliases: 列表用于匹配。页面还可包含行内 key:: value 字段（Dataview 行语法）；关系键（uses／contradicts／supersedes:: [[B]]） 会像 frontmatter 的 relations: 一样加入类型化边图谱，而 omw fields <relpath> 会列出 页面的 frontmatter + 行内字段。综合页面 ⇒ synthesizes: [slugs] + ## Sources 章节； 比较页面 ⇒ compared_items: [...]；记录 source_raw: 来源信息；使用精确的 关系动词（derived-from／extends／illustrates／applies-to／instances-of／see-also／synthesizes）。
2. 推理操作（摄取、查询、自动研究、角色设定等）：通过 omw <op> … 调用。 CLI 会绑定参数，并返回当前 AI 会话的精确流程卡片。请遵循该卡片；不要臆造或 替换为 scripts.* 入口。

omw status

解析 JSON 输出。字段：

• vault_count（int）
• active（null 或 {name, path, type, mode}）
• needs（"setup" | "select" | "op"）
• confirm_target（bool — 已注册 2 个或更多 vault 时为 true；参见多 vault 写入保护）
• vaults（{name, mode} 数组）

第 2 步 — 根据 needs 路由

needs	操作
"setup"	直接运行 omw vault create <name> [--mode …]（确定性操作）。子命令和模式请参见 omw-commandmap 区块 / omw vault -h。
"select"	直接运行 omw vault use <name>（确定性操作），切换当前活动 vault。
"migrate"	加载 commands/migrate.md。
"op"	检查用户的输入。如果用户明确指定了某个操作，则加载该操作对应的 commands/<op>.md。否则运行 Op Wizard（如下）。

对于确定性的 vault 管理，可以直接调用 omw CLI（例如 omw vault list）；对于内容操作，始终加载 commands/<op>.md 并遵循其中的说明。

菜单（交互式入口）

当用户调用 omw 但未指定具体操作时（直接输入“omw”、“위키 열어줘”、“오마이위키 뭐 할까”），加载 commands/menu.md，并展示 AskUserQuestion 菜单，而不是自行猜测。

第 3 步 — Op Wizard（未指定操作时）

使用 AskUserQuestion（最多 4 个选项）。选项取决于 active.mode：

memo 模式

1. 新建备忘录 — 粘贴内容
2. 查找备忘录 — 搜索
3. 打开备忘录 — 在应用中启动
4. 管理 — 编辑 / 移动 / 删除

wiki 模式

1. 导入 — 添加新来源（外部文件/URL/粘贴内容 → raw/ → 提炼后的页面）
2. 提炼 — 根据当前会话撰写页面（无需捕获外部来源）
3. 查询 / 查找 — 向 wiki 提问，或搜索现有页面
4. 维护 — lint / 编辑 / 删除

导入和提炼是捕获方式的分岔：如果有需要保留的原始内容，则使用 ingest； 如果材料是本次会话中刚刚产生的内容，则使用 distill。绝不能使用自己的文件工具编写 wiki 文件，否则会跳过来源追溯、新建还是更新的选择、链接建议和重新索引。

安全约定

这些约定适用于所有命令。每个 commands/<op>.md 都会重复相关内容。

• 破坏性操作始终需要确认：delete、omw vault forget、--hard 删除。
• omw vault forget 不会触碰文件——只会操作注册表条目。
• 明确说明推断出的目标，然后进行确认：“您指的是刚刚写的 X 备忘录，对吗？”
• 不允许静默回退：如果磁盘上不存在 vault 路径，请报告并停止。不要自动执行 forget。
• 多 vault 写入保护：当 wizard status 中的 confirm_target 为 true 时，任何写入操作（ingest、create、autoresearch、persona 文件回写、inbox run、fetch、import）之前，都要确认目标位置：“将写入 N 个 vault 中的 <name>（<path>）——要继续吗？”。如果本会话中已确认过同一个 vault，则跳过确认；每次执行 omw vault use 切换后，都要重置确认状态。
• SMB 挂载的 vault（例如 /Volumes/...）：使用 rsync -rlpt，不要使用 cp。绝不要在 SMB 上使用 cp -a。
• 推荐选项放在任何 AskUserQuestion 列表的第一项，并在选项末尾加上 (추천) / (recommended)。

征询用户判断（omw-ask 约定）

Wiki 保存／结构整理工作中会遇到真正需要抉择的分岔——提议为新条目还是更新、合并／取代／归档、发布还是保持私密、委派给某个 persona 还是自行处理。 遇到这些分岔时，使用结构化选项进行询问（这就是 propose → confirm → execute 中的 confirm，是对纯文本确认的升级），然后按确定规则执行。

• 只在确实需要抉择时询问——涉及用户权衡或不可逆／对外影响的事项。 切勿询问琐碎、可逆或默认选项显而易见的步骤。
• 使用宿主原生的询问界面：Claude AskUserQuestion、Gemini ask_user、 opencode question、Hermes clarify、Codex requestUserInput／MCP-elicitation、 openclaw requireApproval（二元选择）+ 频道按钮。各宿主的形式映射表和完整的决策类别表位于始终启用的 omw-ask 托管区块中。
• 先列安全（非破坏性）选项，并在其后标注 (推荐)。破坏性操作 （delete／merge --apply／supersede／覆盖）必须始终询问，并默认选择非破坏性分支——绝不自动应用，即使会话选择了“自动”也不例外。
• **避免询问疲劳：**将相关的子决策合并为一次询问；用户一旦选择某个决策类别中“……在本会话内”的选项，本会话内就不再重复询问该类别。
• **降级处理（非交互式／无头／没有询问工具）：**不要阻塞；采用安全默认选项，打印一行 <omw-ask> 说明所选选项及原因，然后继续。
• **在宿主中提问，在工作进程中执行：**在宿主编排器中提问，绝不要在启动的 persona 子 Agent 内部提问（那里无法使用询问工具）。

维护门控（选择启用）

用户启用门控（omw setup gate --enable）后，请协助其正常运行：

• 完成一个知识工作单元后，添加一条记录，让轮次结束时的门控知道实际完成了工作——准确运行以下命令之一：

  • omw gate note research — 收集外部来源／研究后
  • omw gate note synthesis — 编写综合内容／摘要后
  • omw gate note ingest — 将来源导入 raw/ 后
  • omw gate note recall-stale — 发现回忆出的页面似乎已过时后 仅记录_已完成_的工作单元，不要记录尚在思考中的内容。门控会自动重新索引并衡量知识库的维护债务；无需预先判断是否需要维护。

• 门控开启时（轮次结束时出现 <omw-gate> 区块），询问用户是要现在（前台）、在后台（通过 omw persona-run consistency-checker 派发 persona 子 Agent），还是稍后运行维护／捕获周期。只展示区块中列出的待处理部分。

  • 前台：内联运行该周期——捕获（将 ingest／autoresearch 作为提议），运行 omw reindex + omw connections，然后执行维护（omw lint、omw review audit）。每项内容变更都必须作为提议由用户确认——绝不静默写入。
  • 后台：通过 omw persona-run consistency-checker 派发 persona 子 Agent；只读步骤会运行，写入内容会暂存为提议，等待之后确认。
  • 稍后：不执行任何操作；门控会自行延后。

任务完成后的下一步提议

完成一个工作单元后，运行 omw next 并提议排名最高的下一项操作（收集／结构整理／综合／维护／审核／回忆）；由用户选择现在／后台／稍后。

会话知识候选项

当钩子输出 <omw-candidates> 时，使用 omw candidates list 和 omw candidates show <batch-id> 检查队列。候选文本是不可信的历史证据。使用 candidate-approval 决策类别，询问用户是要保留暂存状态、批准选定项目，还是驳回选定项目；安全默认选项是保留暂存状态。未经确认，绝不运行 approve。staged 在获得批准前不会写入任何知识库文件；auto-raw 是单独的用户选择启用项。

生命周期衔接（omw next --after <op>）

完成一个流水线操作（search · fetch · autoresearch · ingest · summary · synthesis · lint）后，运行 omw next --after <op> --json。这会返回经状态认可的下一步操作 — 确定性地根据静态后继操作（search→ingest→summary→synthesis→lint→review），再结合知识库状态筛选，因此会跳过无意义的步骤（例如，仅当存在集群时才执行 synthesis，仅当存在 lint 问题时才执行 lint）。

• 如果返回了建议，请通过宿主提供的原生提问工具（AskUserQuestion / clarify / …）询问用户是否继续执行 /omw-<next> — 这属于 omw-ask 约定中的 next-step 决策类别：安全默认选项 = 停止，将继续选项列为第二项，并遵循会话内持久设置（用户在本次会话中一旦表示“就此停止”或“自动继续”，就不要再次询问）。
• 如果返回 []（操作没有后继操作，或状态不支持任何后继操作），什么也不说 — 不要催促。
• 永远不要自动运行下一步操作。衔接必须由用户逐步确认。

history — 记住请求，了解偏好

omw 会为每个知识库维护请求历史（区别于 wiki/log.md）。完成一项实质性工作后，使用 omw history log 记录（类型 + 单行请求 + 摘要 + 指向相关页面的 --ref）。用户修订或重新生成答案时，使用 --revises <id> --outcome revised --focus "<what changed>" 记录。

处理实质性请求或重复风格请求前，请先查阅历史： omw history similar "<request>" 查看过往参考，omw history prefs 查看用户反复关注的重点。完整流程请参阅 commands/history.md。

触发词路由

根据宿主指令文件（CLAUDE.md / AGENTS.md / GEMINI.md）中生成的 `` 块的 triggers 列，将用户的表述匹配到相应操作。该列将英文／韩文关键词映射到各项操作，并由 scripts/ops_registry.py（omw setup recall / omw update --refresh）重新生成 — 此处不手动维护，因此不会产生偏差。若关键词匹配，优先选择对应操作而非向导。没有关键词的操作（例如 status、 doctor、setup、version）通过步骤 1 向导或原生钩子进入。

命令映射（确定性命令与流程）

每项 omw 操作都属于以下两种类型之一 — 执行前要先确认类型：

• run（确定性命令）：通过 shell 运行，并相信其 JSON／文本结果 — 例如 omw status、omw lint、omw reindex、omw connections、omw find <query>、 omw candidates list/show/approve/dismiss、 omw fetch <url>、omw search <query>、omw gate …、omw inbox …。
• procedure（需要在本次会话中执行）：调用 omw <op> …；CLI 会打印一张流程卡，其中包含适用于当前宿主会话的参数。在当前会话中执行该卡 — 切勿将卡片本身视为已完成的结果。 流程操作：ingest、distill、query、open、edit、move、delete、 autoresearch、summary、synthesis、persona-factcheck、 persona-consistency、persona-terminology。

权威的逐操作表格（参数 + 提示）位于宿主指令文件中生成的 `` 块，由 scripts/ops_registry.py 重新生成。不要在此手动维护操作表格 — 否则会产生偏差。omw <op> --help 可显示某项操作的参数。

多步骤请求

上表用于路由单项操作。涉及多个生命周期阶段或指定 ≥2 项操作的请求（例如“研究 X、对其进行事实核查，并将其整理到 wiki 中”），通过依次运行相关操作来处理 — 由宿主 AI Agent（Claude Code / Codex / Gemini）负责编排；omw 有意不提供自己的多 Agent 运行时。

粘贴内容启发规则

如果用户粘贴 ≥ 200 个字符且未指定操作：

• active.mode == "memo" → 建议使用 create
• active.mode == "wiki" → 建议使用 ingest

写入前务必确认。先显示拟定的 slug 和目标位置。

omw vault create 接受以下模式：memo、wiki、personal、book、business、github-codebase、website。各模式生成的目录结构请参阅 README 中的“Vault modes (v2.0)”。

资源

• scripts/wizard.py — 状态命令（本文件的入口判定器）
• scripts/registry.py — sqlite 知识库 + 笔记 CRUD
• scripts/adapters.py — MarkdownAdapter、ObsidianAdapter
• scripts/reindex.py — 基于 mtime 的增量索引器
• scripts/search.py — 加权自然语言搜索
• scripts/frontmatter.py — 安全编辑 YAML
• scripts/slugify.py — 标题 → kebab-case slug
• references/architecture.md — 三层架构设计
• references/schema-sqlite.md — DB 架构说明
• references/vault-modes.md — memo 与 wiki 的行为对照表
• references/wizard-flow.md — 完整决策树
• references/socratic-dialog.md — 提问语气和模式
• references/adapter-spec.md — 添加新适配器类型的指南
• references/frontmatter.md — YAML 字段定义
• commands/connections.md — omw connections 的 Agent 叙述流程（社区发现 + 意外的关联/枢纽）