wiki-init

Wiki Init

在用户指定的路径下初始化一个由大模型维护的新 Wiki。

准备工作

检查附近是否已存在 SCHEMA.md。如果存在，询问用户是要重新初始化，还是继续使用现有 Wiki。

流程

1. 收集配置（每次只问一个问题）

询问：

1. Wiki 应放在哪里？（绝对路径，例如 ~/wikis/ml-research）

2. 领域／用途是什么？（一句话）

3. 你会添加哪些类型的来源？（论文、URL、代码文件、转录文本等）

4. index.md 应使用哪些类别？

   • 研究默认值：Sources | Entities | Concepts | Analyses
   • 代码库默认值：Modules | APIs | Decisions | Flows — 有关代码库的详细指导，请参阅此技能目录中的 codebase.md
   • 或指定自定义类别

5. 你主要会如何浏览此 Wiki？

   1. Obsidian（或其他支持 [[wiki-link]] 的查看器）— 使用 [[slug]] 语法
   2. GitHub / VS Code 预览 / 静态站点生成器 / 普通 Markdown — 使用 [[slug](pages/slug.md)] 语法

   该选项会记录在 SCHEMA.md 中，格式为 link_style: obsidian 或 link_style: markdown，并由所有其他 Wiki 技能应用。

2. 创建目录结构

<wiki-root>/
├── SCHEMA.md         ← conventions + absolute path (how other skills find the wiki)
├── config/
│   └── link-style.md ← cross-reference emit/parse rules (copied from this skill)
├── .gitignore        ← local-only / generated artifacts (audit reports, index) excluded from version control
├── bin/                  ← helper scripts (copied verbatim from this skill's assets/bin/)
│   ├── generate-index.py  ← regenerates wiki/index.md from page frontmatter (stdlib only)
│   ├── render-log.py      ← renders the operation log from git history (stdlib only)
│   ├── check-contradictions.py ← pre-commit gate: blocks staged pages flagged as contradicting
│   ├── lint-mechanical.py ← deterministic lint checks; full mode (JSON for wiki-lint) + --staged gate
│   └── hooks/pre-commit   ← tracked git hook chaining both gates (wired via core.hooksPath)
├── raw/              ← immutable source documents (you add these, LLM never modifies)
├── wiki/
│   ├── index.md      ← GENERATED catalog (gitignored) — never hand-edit; run bin/generate-index.py
│   ├── log.md        ← operation log — ONLY for non-git wikis (git wikis use git history)
│   ├── overview.md   ← evolving synthesis of everything known
│   └── pages/        ← all wiki pages, flat, slug-named (NO subdirectories)
└── assets/           ← downloaded images, PDFs, attachments

重要：wiki/pages/ 是扁平目录。所有页面都放在这里，命名为 <slug>.md。不得创建子目录。slug 使用小写字母，以连字符分隔。

将选定的链接样式规则文件复制到 Wiki 中：

• 如果用户选择选项 1（Obsidian）：将此技能的 config/link-style-obsidian.md 复制到 <wiki-root>/config/link-style.md。
• 如果用户选择选项 2（Markdown）：将此技能的 config/link-style-markdown.md 复制到 <wiki-root>/config/link-style.md。

只复制一个文件，即用户选定的文件，并在 Wiki 中将其重命名为 link-style.md。所有其他 Wiki 技能都会读取 <wiki-root>/config/link-style.md，以了解如何生成和解析交叉引用。

确保 <wiki-root>/.gitignore 排除生成的和仅本地使用的文件（审计报告和生成的索引）——如果 Wiki 已经是 git 仓库或之后变为 git 仓库，这样可以避免将临时文件纳入版本控制。不要覆盖现有的 .gitignore——重新初始化的 Wiki，或嵌套在现有 git 仓库中的 Wiki 根目录，可能已经包含此文件：

• 如果 <wiki-root>/.gitignore 不存在，请使用下面的代码块创建。
• 如果该文件存在，但缺少任意一条忽略规则，请追加缺少的规则。
• 如果两条规则都已存在，请保持文件不变。

# Audit reports are regenerated local-only artifacts (wiki-audit). The committed record
# of an audit is the `review:` frontmatter token on the audited page, not the report.
wiki/pages/audit-*.md
# index.md is generated from page frontmatter by bin/generate-index.py — a runtime
# artifact, regenerated on demand. The source of truth is each page's frontmatter.
wiki/index.md

这与 wiki-audit 用于自我修复的创建或追加规则相同（任务 4）。

3. 编写 SCHEMA.md

# Wiki Schema

## Identity
- **Path:** <absolute path to wiki-root>
- **Domain:** <user's domain description>
- **Source types:** <list>
- **Created:** <YYYY-MM-DD>

## Page Frontmatter
Every wiki page must start with:
---
title: <page title>
category: <one of the Index Categories below>
summary: <one-line description — becomes this page's index entry>
tags: [tag1, tag2]
sources: [source-slug1]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

`category` and `summary` drive index generation (see **Index Generation** below);
`category` must match one of the wiki's Index Categories. `created` is set once when the
page is first written and never changes; `updated` bumps on every edit.

## Cross-References
- **link_style:** <obsidian | markdown — the user's choice from step 1, question 5>
- **link_style_rules:** config/link-style.md
- See `config/link-style.md` for the exact emit and parse rules. Every wiki skill
  reads that file to decide how to write new cross-references and how to scan
  existing ones.

## Concept Identity

The slug **is** the concept's identity — there is no separate id. A concept is the
page at `wiki/pages/<slug>.md`; everything that links to it uses `[[slug]]`. This only
works if the link graph is trustworthy, so two rules hold everywhere links are written:

1. **Links are verified, never invented.** Before writing any `[[slug]]`, the slug must
   resolve to an existing `wiki/pages/<slug>.md` **or** to a page being created in the
   same operation. List the existing page set first (`ls wiki/pages/`); never emit a
   link to a slug you have not confirmed. A `[[slug]]` that resolves to nothing is a
   hallucinated link — the failure this discipline exists to prevent.

2. **Homonyms get qualified slugs.** When a new concept collides with an existing slug
   for a *different* sense, qualify both with a discriminator rather than overloading
   one page:
   - `mercury-planet` / `mercury-element` / `mercury-mythology`
   - `transformer-ml` / `transformer-electrical`

   Pick the narrowest discriminator that disambiguates. `wiki-lint` warns when slugs
   sharing a base token look like an unintended collision.

Consolidating two pages that turn out to be the same concept (merge), or separating one
overloaded page into qualified pages (split), is the job of the `wiki-merge` skill.

## Citations

Cite every non-common-knowledge factual claim. "Common knowledge" = uncontroversial,
undergraduate-level facts in this wiki's domain. Granularity is paragraph or claim,
never per-sentence. If you cannot produce a citation in one of the forms below,
find one, weaken the claim, or drop it.

Format: Markdown footnotes. Two citation kinds, three valid targets.
The slug-target form below follows the `link_style` declared above; the examples
shown here use that style.

**Quote citation** (preferred):

该模型使用 8 个注意力头。[^1]

[^1]: [[attention-is-all-you-need]] §3.2.2 L142-143 — “We employ h = 8 parallel attention layers” [^1]: [[attention-is-all-you-need](pages/attention-is-all-you-need.md)] §3.2.2 L142-143 — “We employ h = 8 parallel attention layers” ```

Synthesis citation (when no single quote captures the claim):

该架构本质上是一个带有注意力机制的编码器-解码器。[^2]

<if link_style: obsidian>
[^2]: [[attention-is-all-you-need]] §3.2-3.4 [synthesis] L138-202 — 编码器、解码器和
      注意力章节共同描述了完整的多头架构
<if link_style: markdown>
[^2]: [[attention-is-all-you-need](pages/attention-is-all-you-need.md)] §3.2-3.4 [synthesis] L138-202 — 编码器、解码器和
      注意力章节共同描述了完整的多头架构

L142-143 / L138-202 are line ranges in the raw source file. For a quote they mark the lines the quote is taken from; for a synthesis they mark the block being summarized.

Three rules for every footnote:

1. The cited target is one of three forms:

   • A slug reference to a source-type wiki page, written in the wiki's link_style (preferred for sources you've ingested via wiki-ingest)
   • raw/<file> or assets/<file> — a path to a local file (for drive-by citations where a synthesis page isn't worth creating)
   • <URL> — a live URL, tweet, or ephemeral source (no local copy required)

   Never cite entity, concept, or analysis pages — those are syntheses, not sources.

2. A locator is present. Always a semantic locator: §<section>, p.<n>, [HH:MM:SS] for transcripts, URL anchor for web, or (YYYY-MM-DD) for dated posts.

   Plus a line-range when the source is text-addressable. If the resolved raw file is markdown, plaintext, code, or cached HTML, append a line-range token after the semantic locator:

   • L<start>-<end> — a range, e.g. L142-145
   • L<n> — a single line, e.g. L142
   • L142-145,L201-203 — disjoint ranges

   The line range refers to lines in the raw source file resolved from the target ([[slug]] → its **Source:** raw path; or a direct raw/<file>/assets/<file>). raw/ is immutable, so these line numbers are stable references.

   A line-range is required for text-addressable sources and applies to BOTH citation kinds — a [synthesis] footnote marks the block it summarizes with L… just as a quote marks the lines it quotes. Exempt (semantic locator only, no L…): PDFs, transcripts, and live URLs with no local cached copy.

3. Either a verbatim quote, or the [synthesis] tag plus a description of what the cited range supports. No third option.

Drive-by citation examples:

[^3]: raw/scaling-laws.pdf p.7 — “loss scales as a power law in compute”
[^4]: https://twitter.com/user/status/123 (2026-04-15) — “<tweet text>”

Cross-Model Review

wiki-audit strong runs a second-opinion pass with a different-provider model and stamps the audited page with an optional review: frontmatter block:

review:
  model: codex          # gemini | claude-sonnet
  provider: openai      # google | anthropic
  date: YYYY-MM-DD
  status: clean         # or: disputed
  findings: 2           # present only when status: disputed

• status: clean — the reviewer surfaced no disagreement with the normal audit.
• status: disputed — the reviewer flagged overreach or a contradiction the normal audit missed; findings: carries the count. The detail lives in the (local-only) audit report.
• provider: anthropic (the claude-sonnet fallback) means no different-provider CLI was available, so the check is same-provider and weaker.

This block is optional and is added only by wiki-audit strong. Pages never need it to be valid.

Contradiction Check

wiki-ingest runs a cheap contradiction check on the pages each ingest touches, before it commits. It is a gate, not an annotation: every page that lands in git is clean.

• Scope — touched neighbors only. The check compares the pages an ingest wrote or edited against (a) themselves and (b) the pages that ingest already read (the entity / concept pages it updated and the neighbor pages from its backlink audit). It does NOT re-read the whole wiki — a conflict with a distant, untouched page is left to the periodic wiki-lint sweep.
• Blocking vs. soft. A blocking contradiction is a real factual conflict on the same entity under the same scope — incompatible dates, counts, names, or mutually-exclusive claims. A soft tension (differing emphasis, values within plausible version / measurement variance, claims that hold under different scope) is not a conflict.
• The transient blocker flag. When a blocking contradiction is found, a single line is written to the affected page's frontmatter and the ingest stops before committing:

  contradiction-check: failed — <one-line reason naming the counterpart [[slug]] or "internal">
  

  机器可读标记是字面值 contradiction-check: failed。它仅在冲突尚未解决时存在；解决冲突后，删除此行。已提交的页面绝不会带有此标记——没有 passed 标记、没有严重程度历史记录，什么都没有。缺少此标记是唯一的“正常”状态。
• 软性矛盾只提示，不记录——在摄取摘要中提及，方便你酌情处理，但绝不持久化，也不会阻止操作。

下方的 提交前门禁 也会扫描暂存文件中的此标记。

提交前门禁

在 git wiki 中，bin/hooks/pre-commit（由 wiki-init 通过 git config core.hooksPath bin/hooks 安装）会在每次提交前运行两个确定性门禁—— 不使用大模型：

1. bin/check-contradictions.py——仅扫描 wiki/pages/*.md 中已暂存内容的 frontmatter；如果任何页面仍带有 contradiction-check: failed 标记，就会阻止提交。 这是 wiki-ingest 第 7b 步技能级拦截的后备机制；在运行正常的 wiki 上，它永远不会触发。 解决矛盾并删除 contradiction-check: 行，然后重新暂存。
2. bin/lint-mechanical.py --staged——扫描已暂存页面中的结构性问题，发现任何 问题都会阻止提交：缺少必需的 frontmatter、[[link]] 无效，或 slug 冲突（裸 slug 与带限定符的 slug 冲突）。修复页面并重新暂存。

• 全新克隆：core.hooksPath 是仓库本地配置，不会随克隆复制——克隆后需重新运行一次 git config core.hooksPath bin/hooks。
• 使用 git commit --no-verify 跳过检查，以完成有意为之的提交。

操作日志与提交约定

操作：init、ingest、query、update、lint、audit、merge、split

Git wiki——Git 历史记录就是操作日志。 操作完成后，技能会建议一条提交消息，并在你确认后提交（技能绝不会自动提交）。 按需使用 python bin/render-log.py 生成人类可读的日志。

建议的主题行遵循仓库的提交约定：

1. 先检测现有约定——扫描近期的 git log，以及任何 .gitmessage、commitlint 配置或 CONTRIBUTING.md。如果仓库已有主题行样式，就遵循该样式。

2. 未发现现有约定时，默认使用 Conventional Commits，并按操作选择类型：

   操作	类型
   init	chore
   ingest	docs
   update	docs
   query（已保存）	docs
   lint	如果已应用修复，则为 fix，否则为 chore
   audit	如果已应用修复，则为 fix，否则为 chore
   merge / split	refactor

始终追加 Wiki-Op: 尾注，无论主题行采用哪种样式——render-log.py 会以此为依据，从而使日志与主题行约定相互独立。 哪些页面发生了更改会从提交差异中读取，因此无需添加 Pages: 尾注。

docs: summarize Attention Is All You Need

Wiki-Op: ingest

非 Git wiki——回退到 wiki/log.md。 每次操作追加一条记录： ## [YYYY-MM-DD] <operation> | <title>。

索引生成

wiki/index.md 是生成的、被 Git 忽略的产物——切勿手动编辑。它由 bin/generate-index.py 根据页面 frontmatter 重新生成：

• 在读取索引前以及任何会添加、删除、重命名或重新分类页面的操作之后，运行 python bin/generate-index.py（或 python3）。
• 生成器按页面 frontmatter 中的 category 分组，顺序与下方索引分类中列出的分类顺序一致；每个分类内的页面按 created 从新到旧排列。每个条目的格式为 - [[slug]] — summary _(created)_。
• 文件名匹配 audit-*.md 的页面会被排除（被 Git 忽略的本地专用产物）。category 缺失或无法识别的页面会归入 未分类 部分。

索引分类

<每行一个，符合用户选择的分类体系>

约定

• raw/ 不可变 — 技能绝不修改它
• 操作日志：Git wiki 将每项操作记录为一次提交（参见 Operation Log & Commit Convention），并通过 bin/render-log.py 呈现；非 Git wiki 则追加到 log.md（只追加，绝不重写）
• index.md 由 bin/generate-index.py 生成，且被 Git 忽略 — 绝不手动编辑；应设置页面 frontmatter（category、summary）并重新生成
• 所有页面都平铺在 wiki/pages/ 中 — 不设子目录
• overview.md 反映所有来源当前的综合结果
• 交叉引用和引用的 slug 目标遵循 config/link-style.md — 每个技能在编写或扫描链接前都要先阅读该文件
• 矛盾检查：摄取时会通过临时的 contradiction-check: failed 标记，阻止涉及页面中存在未解决的矛盾；该标记会在提交前移除 — 已提交的页面始终不存在矛盾（参见 Contradiction Check）
• 提交前检查：Git wiki 通过 core.hooksPath 运行 bin/hooks/pre-commit → bin/check-contradictions.py，阻止提交任何仍带有该标记的暂存页面（参见 Pre-commit Gate）；全新克隆后需重新运行 git config core.hooksPath bin/hooks
• README 边界：wiki 页面不得重复 README 内容。提取结构性信息；对于操作性内容（设置、贡献、运行），链接到 README。摄取任何 README 时，还要评估其中的缺漏并建议修改。

### 4. Install the `bin/` helper scripts and generate the index

The wiki ships four stdlib-only helper scripts (no dependencies) plus a tracked git hook.
They are **bundled with this skill** at `assets/bin/` — copy them verbatim into
`<wiki-root>/bin/` (do not retype or regenerate them). From this skill's directory:

```sh
mkdir -p <wiki-root>/bin/hooks
cp assets/bin/generate-index.py       <wiki-root>/bin/
cp assets/bin/render-log.py           <wiki-root>/bin/
cp assets/bin/check-contradictions.py <wiki-root>/bin/
cp assets/bin/lint-mechanical.py      <wiki-root>/bin/
cp assets/bin/hooks/pre-commit        <wiki-root>/bin/hooks/
chmod +x <wiki-root>/bin/*.py <wiki-root>/bin/hooks/pre-commit

各文件的作用：

• bin/generate-index.py — wiki/index.md 根据页面 frontmatter 生成，绝不手动编写，因此不会与实际情况脱节。复制后运行一次（python bin/generate-index.py），以确保存在有效的 index.md。
• bin/render-log.py — 按需根据 Git 历史呈现操作日志（参见 SCHEMA.md 中的 Operation Log & Commit Convention）。在非 Git wiki 上无害 — 它只会提示日志位于 log.md。
• bin/check-contradictions.py — 提交前检查（参见 SCHEMA.md 中的 Pre-commit Gate 和 Contradiction Check 部分）。如果提交中暂存的 wiki/pages/ 文件仍带有 P8 的 contradiction-check: failed 标记，它就会阻止提交。结果确定，不使用大模型。在非 Git wiki 上无害 — 它会直接跳过。
• bin/lint-mechanical.py — 确定性的健康检查，分为两种模式。完整模式（python bin/lint-mechanical.py）会输出 JSON，供 wiki-lint 的 Phase 1 使用（失效链接、孤立页面、缺少 frontmatter、slug 冲突、日期过期、缺少概念），并提供其矛盾扫描所需的标签簇列表。暂存模式（--staged）是第二道提交前检查：如果暂存页面缺少 frontmatter、存在失效链接或 slug 冲突，就会阻止提交。不使用大模型；在 Git 工作树之外会直接跳过。
• bin/hooks/pre-commit — 已跟踪的 Git 钩子，通过 uv run（确保解释器可用）串联两道检查（check-contradictions.py，然后是 lint-mechanical.py --staged）。此钩子将在步骤 5 中启用。

5. 设置操作日志

操作日志的记录方式取决于 wiki 是否为 Git 仓库。如果尚未初始化，请提议运行 git init — Git 历史日志是更好的方案。

• Git 仓库：Git 历史记录就是操作日志（参见 SCHEMA 中的 Operation Log & Commit Convention）。不要创建 log.md。首先安装提交前检查（矛盾标记 + 结构有效性）：使钩子可执行，并将 Git 指向已跟踪的钩子目录 —

  chmod +x bin/hooks/pre-commit
  git config core.hooksPath bin/hooks
  

  钩子已纳入版本控制（将在下方提交），但 core.hooksPath 是仓库本地配置，全新克隆后不会保留 — 告知用户克隆后重新运行 git config 命令。然后建议进行初始提交，并在用户确认后执行：

  chore: initialize <domain> wiki
  
  Wiki-Op: init
  

• **非 Git 仓库：**创建 wiki/log.md 作为备用操作日志：

  # Wiki Log
  
  Append-only fallback log (this wiki is not a git repo). Format:
  `## [YYYY-MM-DD] <operation> | <title>` — recent: `grep "^## \[" log.md | tail -10`
  
  ---
  
  ## [<today>] init | <domain>
  

6. 编写 wiki/overview.md

---
title: Overview
tags: [overview, synthesis]
sources: []
updated: <today>
---

# <Domain> — Overview

> Evolving synthesis of everything in the wiki. Updated by wiki-ingest when sources shift the understanding.

## Current Understanding

*No sources ingested yet.*

## Open Questions

*Add questions here as they arise.*

## Key Entities / Concepts

*Populated as pages are created.*

7. 确认

告知用户：

• 知识库已初始化，路径为 <path>
• 链接样式：<obsidian | markdown> — 规则见 config/link-style.md。之后如需切换，请将该文件替换为此技能 config/ 目录中的另一种版本，并更新 SCHEMA.md 中的 link_style:。现有页面不会自动转换。
• 手动将来源添加到 raw/，或直接使用 URL 或文件路径运行 wiki-ingest
• 定期运行 wiki-lint，保持知识库健康
• 对于 git 知识库，每项操作都会记录为一次提交；使用 python bin/render-log.py 查看操作日志
• 其他所有技能都通过 SCHEMA.md 定位此知识库 — 请勿移动或删除它