# Mini-Wiki

> A source-traceable project knowledge network for people and AI.

# Core features

Mini-Wiki 3.3 converts the strongest repository-relevant ideas from Obsidian into standalone, versionable
capabilities. Obsidian can enhance exploration, but no core feature depends on the application.

## Managed Markdown and Properties

Properties are the shared metadata model for pages and derived views. The CLI owns IDs, types, domains, sources,
freshness, quality, and version fields while preserving unknown user Properties. Generated/content markers let
machine facts and expert explanation evolve independently.

Rebuilds therefore remain safe after human or Agent enrichment: a page is not a disposable generated artifact, and
authored knowledge does not block structural facts from changing.

## Local CJK-aware search

```bash
mini-wiki search "插件安装" --json /path/to/project
mini-wiki search "storage" --type module --tag domain/storage --limit 10 /path/to/project
```

The index combines Markdown, Properties, aliases, tags, graph metadata, and bounded source text. Deterministic CJK
unigram/bigram normalization supports Chinese and mixed-language queries.

SQLite FTS5 is an optional accelerator, not a dependency. The fallback preserves query filters, result shape, and
ranking rules, keeping retrieval available in minimal Python environments.

## Four Bases turn governance into queues

| File | Purpose |
| --- | --- |
| `views/modules.base` | module status, freshness, quality, and backlinks |
| `views/sources.base` | source coverage, ownership, and drift |
| `views/quality.base` | review and enrichment queue |
| `views/orphans.base` | pages not yet connected to the graph |

Bases are native declarative views over Properties. They contain no unique knowledge; edit canonical facts and
rebuild, and the views follow the Markdown.

## Three Canvas views project the same graph

| File | Perspective |
| --- | --- |
| `canvas/architecture.canvas` | architectural layers and dependencies |
| `canvas/domains.canvas` | domains, modules, and responsibilities |
| `canvas/traceability.canvas` | document-to-source and symbol evidence paths |

Canvas output follows JSON Canvas 1.0. Node IDs, positions, sizes, and edge ordering are deterministic. Canvas is a
spatial exploration surface, never the only source of truth.

## Deterministic builds and recovery

- dry-run shows the write plan first;
- staging holds a complete candidate result;
- canonical Wiki switches only after strict validation;
- retired managed pages move to `.mini-wiki/archive/`;
- a second unchanged build should reproduce the same result.

A failed build cannot leave a half-written Wiki. Migration uses the same preview, backup, copy-validation, and final
configuration-switch discipline.

## One input, several consumable surfaces

Browsers, editors, Git hosts, and Obsidian can read canonical `wiki/`; Agents can use the graph and Manifest; search,
Bases, and Canvas provide distinct retrieval and governance views.

Start with the [knowledge-network model](/en/knowledge-network/), then read [security](/en/security/) before adding
external instructions or publishing generated knowledge.

# Get started in five minutes

Mini-Wiki 3.3 turns a code repository into a root-level `wiki/` knowledge network. The CLI owns repeatable structure
and facts; the AI Agent owns evidence-based explanation. Managed Markdown markers let them collaborate safely.

## 1. Install

Install Mini-Wiki as an Agent Skill first:

```bash
npx skills add trsoliu/mini-wiki
```

For direct local CLI use:

```bash
git clone https://github.com/trsoliu/mini-wiki.git
cd mini-wiki
python -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mini-wiki --version
```

Python 3.10 or newer is required. Core builds require neither Node.js nor Obsidian.

## 2. Initialize and diagnose

Create schema v3 configuration in the target project, then inspect readiness and boundaries:

```bash
mini-wiki init /path/to/project
mini-wiki doctor --json /path/to/project
```

`init` creates `.mini-wiki/config.yaml`. It does not put canonical knowledge in the state directory; the default
destination for durable documents is the root-level `wiki/` directory.

## 3. Preview, then build

```bash
mini-wiki build --dry-run --json /path/to/project
mini-wiki build --json /path/to/project
```

Dry-run returns the write plan without changing files. A real build scans allowed sources, computes stable IDs,
constructs the graph, writes managed pages in staging, validates them, and switches the result transactionally.

After the first build, inspect `.mini-wiki/cache/build-plan.json` and `.mini-wiki/cache/graph.json`. They tell the Agent
what needs explanation and which source evidence can support it, avoiding blank-page generation.

## 4. Let the Agent write only in the content region

Every managed page separates two responsibilities:

```markdown
<!-- mini-wiki:generated:start -->
CLI-managed navigation, relationships, and evidence.
<!-- mini-wiki:generated:end -->

<!-- mini-wiki:content:start -->
Agent-authored explanation grounded in source evidence.
<!-- mini-wiki:content:end -->
```

The Agent edits only `mini-wiki:content`, leaving stable IDs, source lists, and generated navigation to the CLI.
Unknown Properties are user-owned and survive later rebuilds.

## 5. Rebuild and validate strictly

```bash
mini-wiki build --json /path/to/project
mini-wiki check --strict --json /path/to/project
```

A second build with unchanged sources should have no unexplained diff. Strict mode validates IDs, links, source
drift, ownership markers, orphans, Base schemas, and Canvas node/edge integrity.

## 6. Search without Obsidian

```bash
mini-wiki search "architecture decision" --json /path/to/project
mini-wiki search "storage" --type module --tag domain/storage --limit 10 /path/to/project
```

Search covers Markdown, Properties, aliases, tags, graph metadata, and bounded source text. SQLite FTS5 accelerates
the index when available; the fallback preserves filters and ranking semantics.

## Definition of done

- `wiki/index.md` and the knowledge map open correctly;
- Agent content cites locatable repository evidence;
- `mini-wiki check --strict --json` succeeds;
- the second unchanged build is stable;
- English, Chinese, or mixed-language queries retrieve the expected page.

Continue with the [knowledge-network model](/en/knowledge-network/), then use [features](/en/features/) and
[security boundaries](/en/security/) as the operating manual.

Mini-Wiki 3.3.0
Mini-WikiTurn repositories into traceable knowledge networks
Build deterministic, searchable, versioned project knowledge for maintainers and AI agents.

[Get started](/en/guide/)

[View on GitHub](https://github.com/trsoliu/mini-wiki)

$npx skills add trsoliu/mini-wiki

01Deterministic buildsStable IDs, transactional writes, and repeatable output make knowledge changes reviewable and reproducible.
02Source traceabilityProjects, domains, modules, files, and symbols all resolve to explicit repository evidence.
03CJK-aware searchRetrieve Markdown, Properties, graph metadata, and bounded source text locally.
04Bases and CanvasGovern knowledge through structured queues and explore project relationships spatially.
05Safe collaborationThe CLI owns structure while agents add evidence-based explanation only inside protected regions.
06Agent-ready outputGenerate search indexes, Markdown routes, and model-independent discovery files from one source.

AI-ready documentationBuild once for humans and agents.Every public surface comes from the same curated pages.

[`llms.txt`](/llms.txt)

[`llms-full.txt`](/llms-full.txt)

[`ai-index.json`](/ai-index.json)

[`Agent Contract`](/.well-known/silen/manifest.json)

# The knowledge-network model

Mini-Wiki does more than replace a directory tree with summaries. It constructs a stable repository graph first,
then derives Markdown, search, Bases, Canvas, and the Manifest from that graph. Every surface uses the same IDs and
relationship facts.

## Six core node types

| Node | Meaning | Typical relationship |
| --- | --- | --- |
| project | Root identity of the repository | contains domains and modules |
| domain | Business or technical responsibility boundary | groups modules |
| module | Explainable implementation unit | owns sources and symbols |
| source | Source file inside the scan boundary | defines or references symbols |
| symbol | Traceable class, function, or code entity | explained by documents |
| document | Canonical knowledge page | references sources, symbols, and documents |

Direction, node type, and paths are recorded in `.mini-wiki/cache/graph.json`. Pages, Bases, and Canvas project those
facts instead of maintaining conflicting copies.

## Stable identities, not fragile titles

A managed page carries a machine-stable identity:

```yaml
id: mw:document:domains/core/core
title: Core
type: module
domain: core
sources:
  - src/core/app.py
freshness: current
quality: basic
mini_wiki_version: 3.3.0
```

Titles serve readers; stable IDs serve rebuilds, link validation, and Agent citations. A source-content change does
not need to change page identity. When a module leaves management, its page moves to a recoverable archive instead
of disappearing silently.

## One page, three ownership zones

1. **Properties:** known Mini-Wiki fields are CLI-owned; unknown fields remain user-owned.
2. **generated region:** navigation, sources, relationships, and machine facts are rebuilt by the CLI.
3. **content region:** expert explanation from an AI Agent or maintainer is preserved byte-for-byte.

```markdown
<!-- mini-wiki:generated:start -->
CLI-owned navigation, evidence, and relationships.
<!-- mini-wiki:generated:end -->

<!-- mini-wiki:content:start -->
Agent-owned explanation grounded in repository evidence.
<!-- mini-wiki:content:end -->
```

Documents without ownership markers are not adopted or overwritten. During legacy migration, `migrate --adopt`
explicitly wraps the existing body and preserves it inside the Agent-owned region.

## The source-to-explanation evidence chain

A useful explanation should answer:

- Which domain and module own this knowledge?
- Which sources and symbols support the conclusion?
- Is every source still in bounds and current?
- Is the text authored explanation or rebuildable machine fact?

The build plan says what needs enrichment, the graph says what can be cited, and the Manifest says what the current
build actually manages. The Agent is completing an inspectable evidence chain, not generating a free-form wiki.

## Four views of one graph

- Markdown pages support continuous reading;
- local search supports fast human and Agent retrieval;
- Bases turn Properties into governance queues;
- Canvas exposes deterministic spatial relationships.

See [core features](/en/features/) for each projection, or follow the [five-minute guide](/en/guide/) to build one.

# CLI and configuration reference

This page describes Mini-Wiki **3.3.0**. Project paths default to the current directory and can be supplied explicitly.

## Installation and version

```bash
npx skills add trsoliu/mini-wiki
mini-wiki --version
```

Local development installation:

```bash
python -m venv .venv
.venv/bin/pip install -e .
```

## Initialize, diagnose, and analyze

```bash
mini-wiki init /path/to/project
mini-wiki init --force /path/to/project
mini-wiki doctor --json /path/to/project
mini-wiki analyze /path/to/project
mini-wiki changes /path/to/project
```

`init --force` backs up existing configuration first. `doctor` checks project and optional-integration readiness.

## Build

```bash
mini-wiki build --dry-run --json /path/to/project
mini-wiki build --json /path/to/project
mini-wiki build --full --json /path/to/project
```

`--dry-run` writes nothing; `--full` rebuilds every managed document; `--json` provides machine-readable results.

## Strict validation

```bash
mini-wiki check --strict --json /path/to/project
```

Strict mode validates stable IDs, links, source bounds and drift, ownership markers, orphans, Base schemas, and
Canvas nodes and edges.

## Local search

```bash
mini-wiki search "architecture decision" --json /path/to/project
mini-wiki search "storage" --type module --tag domain/storage --limit 10 /path/to/project
```

`--limit` accepts 1–200 and defaults to 20. `--type` filters document type; `--tag` matches an exact tag.

## Migration

```bash
mini-wiki migrate --json /path/to/project
mini-wiki migrate --apply --json /path/to/project
mini-wiki migrate --apply --adopt --json /path/to/project
```

`--apply` runs the previewed v2→v3 copy migration. `--adopt` wraps legacy Markdown bodies in managed content regions.

## Optional Obsidian integration

```bash
mini-wiki obsidian status --json /path/to/project
mini-wiki obsidian status --probe --json /path/to/project
mini-wiki obsidian open /path/to/project
```

Normal status does not launch the app. `--probe` explicitly permits an Obsidian CLI call; `open` explicitly asks the
app to open the configured Wiki.

## Instruction-only plugins

```bash
mini-wiki plugins list /path/to/project
mini-wiki plugins install owner/repository /path/to/project
mini-wiki plugins enable plugin-name /path/to/project
mini-wiki plugins disable plugin-name /path/to/project
mini-wiki plugins update plugin-name /path/to/project
mini-wiki plugins uninstall plugin-name /path/to/project
```

Plugins are disabled by default and supply text guidance only. Scripts, hooks, package managers, and commands must
never be imported or executed.

## Default directories

```text
wiki/                         # canonical knowledge
├── index.md
├── getting-started.md
├── architecture.md
├── knowledge-map.md
├── domains/
├── reference/
├── views/*.base
└── canvas/*.canvas

.mini-wiki/                   # configuration and state
├── config.yaml
├── manifest.json
├── meta.json
├── cache/
├── staging/
└── archive/
```

## Managed ownership markers

```markdown
<!-- mini-wiki:generated:start -->
CLI-owned facts.
<!-- mini-wiki:generated:end -->

<!-- mini-wiki:content:start -->
Agent-owned explanation.
<!-- mini-wiki:content:end -->
```

## Feature switches

Schema v3 has independent switches for search, Bases, Canvas, and optional Obsidian integration. Scan settings also
cover Git ignore rules, explicit exclusions, symlink boundaries, file-size limits, and state/Wiki isolation.

For a first run, complete the [five-minute guide](/en/guide/). For data relationships, see the
[knowledge-network model](/en/knowledge-network/).

# Security, boundaries, and recovery

Mini-Wiki security is designed into directory responsibilities, ownership markers, scanning constraints,
transactional writes, and disabled-by-default external instructions.

## Canonical knowledge and local state

```text
wiki/          # canonical, portable, suitable for Git
.mini-wiki/    # configuration, caches, staging, recoverable archive
.obsidian/     # never created or modified by Mini-Wiki
```

`wiki/` is the durable-fact boundary. `.mini-wiki/` primarily holds rebuildable or local state. Do not treat caches
as canonical knowledge, and do not allow repository-external files or machine-local absolute paths into the Wiki.

## Scan boundaries

Scanning respects Git ignore rules, explicit exclusions, file-size limits, state/Wiki exclusions, and symlink
boundaries. Only sources inside the allowed project root can become evidence, preventing credentials, build output,
or adjacent repositories from entering the knowledge graph.

## Managed pages do not adopt unknown documents

The builder updates only documents with complete Mini-Wiki ownership markers. Unknown Properties remain user-owned,
and existing documents without markers are not overwritten. Retired pages move to `.mini-wiki/archive/` for review
and recovery.

## Third-party plugins are instructions, not code

The plugin model is **instruction-only**: installed `PLUGIN.md` or `SKILL.md` files are untrusted text and disabled by
default. An Agent may read relevant enabled guidance, but it must **never import or execute plugin scripts, hooks,
package managers, or commands**.

Installation also rejects:

- non-HTTPS network sources;
- path traversal, invalid roots, and symbolic links;
- archives over bounded limits;
- unconfirmed same-name replacement;
- silent content changes that disagree with the recorded tree hash.

## Obsidian is an optional interface

Build, search, strict validation, migration, Bases, and Canvas do not require Obsidian. Normal status is side-effect
free:

```bash
mini-wiki obsidian status --json /path/to/project
```

Only explicit `--probe` may invoke the Obsidian CLI and start the app. Only `obsidian open` asks the application to
open the configured Wiki through an encoded URI. Mini-Wiki does not write `.obsidian/`.

## Transactions, migration, and recovery

Builds create a complete candidate in staging and switch only after validation. Failure leaves the current canonical
Wiki intact. Migration previews by default, refuses a non-empty destination, backs up legacy material, validates the
copy, and changes configuration last.

```bash
mini-wiki migrate --json /path/to/project
mini-wiki migrate --apply --json /path/to/project
mini-wiki migrate --apply --adopt --json /path/to/project
```

## Pre-publication checklist

1. Check `wiki/` for credentials, personal data, and machine-local paths.
2. Run `mini-wiki check --strict --json`.
3. Review source evidence for Agent-authored claims.
4. Compare a second unchanged build.
5. Commit only canonical knowledge and intentionally shared configuration.

Use the [CLI reference](/en/reference/) for exact commands and the [five-minute guide](/en/guide/) for the full loop.

# 核心能力

Mini-Wiki 3.3 把 Obsidian 中最有价值的知识管理理念转化为独立、可版本化的仓库能力。Obsidian 可以
增强阅读体验，但不是任何核心能力的运行依赖。

## 托管 Markdown 与 Properties

Properties 是页面和派生视图共用的元数据模型。CLI 维护 ID、类型、领域、来源、新鲜度、质量与版本，
同时保留用户添加的未知 Properties。正文中的 generated/content 标记让机器事实与专业解释可以独立更新。

结果是：重建不会把页面变成一次性生成物，手工知识也不会阻止结构和来源事实继续演进。

## 中文感知的本地搜索

```bash
mini-wiki search "插件安装" --json /path/to/project
mini-wiki search "storage" --type module --tag domain/storage --limit 10 /path/to/project
```

索引组合 Markdown、Properties、别名、标签、图谱元数据与受限源码文本。确定性的中文 unigram/bigram
归一化支持中文和中英混合查询。

SQLite FTS5 是可选加速器，不是功能依赖。后备实现保持相同的查询筛选、结果格式和排序规则，因此
知识库在精简 Python 环境中仍可检索。

## 四个 Bases：把知识治理变成队列

| 文件 | 用途 |
| --- | --- |
| `views/modules.base` | 查看模块状态、新鲜度、质量与反向链接 |
| `views/sources.base` | 查看源码覆盖、归属与漂移 |
| `views/quality.base` | 形成待评审和待增补队列 |
| `views/orphans.base` | 找出尚未接入知识网络的页面 |

Bases 是 Properties 上的原生声明式视图。它们不持有唯一知识；修改事实后重新构建，视图会跟随正式
Markdown 更新。

## 三个 Canvas：从不同尺度查看同一张图

| 文件 | 视角 |
| --- | --- |
| `canvas/architecture.canvas` | 架构层次和模块依赖 |
| `canvas/domains.canvas` | 领域、模块与职责分布 |
| `canvas/traceability.canvas` | 文档到源码和符号的证据路径 |

Canvas 使用 JSON Canvas 1.0，节点 ID、位置、大小和边顺序均为确定性输出。它适合空间探索，但不应
成为唯一事实来源。

## 确定性构建与恢复

- dry-run 先展示写入计划；
- staging 中生成完整候选结果；
- 严格校验通过后才切换正式 Wiki；
- 退出管理的页面移动到 `.mini-wiki/archive/`；
- 第二次无变化构建应产生相同结果。

构建失败不会留下半写入的 Wiki。迁移同样采用预览优先、备份旧材料、校验副本、最后切换配置的流程。

## 一个输入面，多个可消费产物

正式 `wiki/` 可以被浏览器、编辑器、Git 主机和 Obsidian 阅读；图谱与 Manifest 可以被 Agent 使用；
搜索、Bases、Canvas 则提供不同的召回和治理方式。

先理解[知识网络模型](/knowledge-network/)，再阅读[安全边界](/security/)了解哪些内容可以生成、执行或发布。

# 五分钟上手 Mini-Wiki

Mini-Wiki 3.3 把一个代码仓库转换成仓库根级 `wiki/` 知识网络。CLI 负责可重复的结构和事实，AI Agent
负责有源码证据的专业解释；二者通过托管 Markdown 的所有权标记协作。

## 1. 安装

推荐先把 Mini-Wiki 安装为 Agent Skill：

```bash
npx skills add trsoliu/mini-wiki
```

需要直接使用本地 CLI 时：

```bash
git clone https://github.com/trsoliu/mini-wiki.git
cd mini-wiki
python -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mini-wiki --version
```

要求 Python 3.10 或更高版本。核心构建不需要 Node.js，也不需要 Obsidian。

## 2. 初始化并诊断

在目标项目上创建 schema v3 配置，然后先检查运行环境和边界：

```bash
mini-wiki init /path/to/project
mini-wiki doctor --json /path/to/project
```

`init` 创建 `.mini-wiki/config.yaml`，不会把正式知识写进状态目录。正式文档的默认目标是项目根级
`wiki/`。

## 3. 先预览，再构建

```bash
mini-wiki build --dry-run --json /path/to/project
mini-wiki build --json /path/to/project
```

dry-run 输出计划但不写文件。正式构建会扫描受允许的源文件、计算稳定 ID、生成图谱、写入托管页面，
并通过事务暂存后一次性切换结果。

第一次构建后，先查看 `.mini-wiki/cache/build-plan.json` 和 `.mini-wiki/cache/graph.json`。它们告诉 Agent
哪些页面需要解释、每个结论能追溯到哪些源码，而不是让 Agent 从空白页面猜测。

## 4. 让 Agent 只写内容区

每个托管页面有两个职责区：

```markdown
<!-- mini-wiki:generated:start -->
CLI 管理的导航、关系与证据。
<!-- mini-wiki:generated:end -->

<!-- mini-wiki:content:start -->
Agent 根据源码证据编写的专业解释。
<!-- mini-wiki:content:end -->
```

Agent 只修改 `mini-wiki:content` 区域，不改稳定 ID、来源列表或 CLI 管理的导航。未知 Properties 视为
用户所有，后续重建会保留。

## 5. 重建并严格校验

```bash
mini-wiki build --json /path/to/project
mini-wiki check --strict --json /path/to/project
```

第二次未发生源码变化的构建应当没有无法解释的差异。严格模式检查 ID、链接、来源漂移、所有权标记、
孤立页面、Base schema，以及 Canvas 节点和边的完整性。

## 6. 不依赖 Obsidian 的搜索

```bash
mini-wiki search "架构决策" --json /path/to/project
mini-wiki search "storage" --type module --tag domain/storage --limit 10 /path/to/project
```

搜索覆盖 Markdown、Properties、别名、标签、图谱元数据和有界源码文本。SQLite FTS5 只是加速器；没有
FTS5 时，后备实现保持相同的筛选与排序语义。

## 完成标准

- `wiki/index.md` 与知识地图可以打开；
- Agent 内容区包含可定位到仓库源码的证据；
- `mini-wiki check --strict --json` 成功；
- 第二次无变化构建稳定；
- 中文或混合语言查询能返回正确页面。

接下来阅读[知识网络模型](/knowledge-network/)，再根据需要查看[核心能力](/features/)与[安全边界](/security/)。

Mini-Wiki 3.3.0
Mini-Wiki把代码仓库变成可追溯的知识网络
为维护者与 AI Agent 生成确定性、可搜索、可版本化的项目知识。

[开始使用](/guide/)

[在 GitHub 查看](https://github.com/trsoliu/mini-wiki)

$npx skills add trsoliu/mini-wiki

01确定性构建稳定 ID、事务写入与可重复构建，让知识变更可以审查和重放。
02源码可追溯项目、领域、模块、文件与符号都能回到明确的仓库证据。
03中英混合搜索本地检索 Markdown、Properties、图谱元数据与有界源码文本。
04Bases 与 Canvas用结构化队列治理知识，用空间视图探索项目关系。
05安全协作边界CLI 管理结构，Agent 只在受保护内容区内补充证据化解释。
06面向 AI Agent同源生成搜索索引、Markdown 路由与模型无关的发现文件。

AI-ready documentation一次构建，同时服务人和 Agent。所有公开入口来自同一组受控页面。

[`llms.txt`](/llms.txt)

[`llms-full.txt`](/llms-full.txt)

[`ai-index.json`](/ai-index.json)

[`Agent Contract`](/.well-known/silen/manifest.json)

# 知识网络模型

Mini-Wiki 不是把目录树换成一批摘要。它先构建稳定的仓库图谱，再从图谱派生 Markdown、搜索、Bases、
Canvas 与 Manifest。所有输出共享同一组 ID 和关系事实。

## 六类核心节点

| 节点 | 说明 | 典型关系 |
| --- | --- | --- |
| project | 当前仓库的根身份 | 包含 domain 与 module |
| domain | 业务或技术职责边界 | 聚合 module |
| module | 可解释的实现单元 | 拥有 source 与 symbol |
| source | 受扫描边界约束的源码文件 | 定义或引用 symbol |
| symbol | 类、函数等可追溯代码实体 | 被 document 解释 |
| document | 正式知识页面 | 引用 source、symbol 与其他 document |

关系方向、节点类型和路径都会进入 `.mini-wiki/cache/graph.json`。页面、Base 与 Canvas 只投影这些事实，
不会各自维护互相冲突的数据副本。

## 稳定 ID，而不是脆弱标题

托管页面用机器稳定 ID 表示身份，例如：

```yaml
id: mw:document:domains/core/core
title: Core
type: module
domain: core
sources:
  - src/core/app.py
freshness: current
quality: basic
mini_wiki_version: 3.3.0
```

标题适合人阅读，稳定 ID 适合重建、链接校验和 Agent 引用。源文件内容改变不必导致页面身份变化；
模块真正退出管理时，相关页面会进入可恢复归档，而不是静默删除。

## 一份页面，三种所有权

1. **Properties：** 已知 Mini-Wiki 字段由 CLI 管理，未知字段保留给用户。
2. **generated 区域：** 导航、来源、关系和机器事实由 CLI 重建。
3. **content 区域：** AI Agent 或维护者编写的专业解释逐字节保留。

```markdown
<!-- mini-wiki:generated:start -->
CLI-owned navigation, evidence, and relationships.
<!-- mini-wiki:generated:end -->

<!-- mini-wiki:content:start -->
Agent-owned explanation grounded in repository evidence.
<!-- mini-wiki:content:end -->
```

没有所有权标记的现有文档不会被自动接管或覆盖。需要迁移旧知识时，`migrate --adopt` 会显式包装原有
正文，并保留在 Agent 内容区。

## 从源码到解释的证据链

一次有效解释应当能够回答：

- 这段知识对应哪个 domain 和 module？
- 哪些 source 与 symbol 支撑这个结论？
- 证据是否仍在扫描边界内，是否发生漂移？
- 这段文字属于 Agent 内容，还是可重建的机器事实？

构建计划提供“需要补充什么”，图谱提供“可以引用什么”，Manifest 提供“本次构建实际管理了什么”。
因此 Agent 的工作不是自由生成百科，而是补齐一条可检查的证据链。

## 同一图谱的四种读法

- Markdown 页面给维护者连续阅读；
- 本地搜索给人和 Agent 快速召回；
- Bases 用 Properties 形成治理工作台；
- Canvas 用确定性节点和边展示空间关系。

更具体的视图与检索方式见[核心能力](/features/)。要开始建立自己的图谱，请回到[五分钟上手](/guide/)。

# 命令与配置参考

本页对应 Mini-Wiki **3.3.0**。命令中的项目路径默认是当前目录，也可以显式传入目标仓库。

## 安装与版本

```bash
npx skills add trsoliu/mini-wiki
mini-wiki --version
```

本地开发安装：

```bash
python -m venv .venv
.venv/bin/pip install -e .
```

## 初始化、诊断与分析

```bash
mini-wiki init /path/to/project
mini-wiki init --force /path/to/project
mini-wiki doctor --json /path/to/project
mini-wiki analyze /path/to/project
mini-wiki changes /path/to/project
```

`init --force` 会先备份已有配置。`doctor` 用于诊断项目和可选集成是否就绪。

## 构建

```bash
mini-wiki build --dry-run --json /path/to/project
mini-wiki build --json /path/to/project
mini-wiki build --full --json /path/to/project
```

`--dry-run` 不写文件；`--full` 忽略增量判断并重建所有托管文档；`--json` 提供机器可读结果。

## 严格校验

```bash
mini-wiki check --strict --json /path/to/project
```

严格模式检查稳定 ID、链接、来源边界与漂移、所有权标记、孤立页面、Base schema，以及 Canvas 节点和边。

## 本地搜索

```bash
mini-wiki search "架构决策" --json /path/to/project
mini-wiki search "storage" --type module --tag domain/storage --limit 10 /path/to/project
```

`--limit` 范围为 1–200，默认 20。`--type` 按文档类型过滤，`--tag` 做精确标签过滤。

## 迁移

```bash
mini-wiki migrate --json /path/to/project
mini-wiki migrate --apply --json /path/to/project
mini-wiki migrate --apply --adopt --json /path/to/project
```

`--apply` 应用预览过的 v2→v3 复制迁移；`--adopt` 把旧 Markdown 正文包装进托管内容区。

## 可选 Obsidian

```bash
mini-wiki obsidian status --json /path/to/project
mini-wiki obsidian status --probe --json /path/to/project
mini-wiki obsidian open /path/to/project
```

普通 status 不启动应用。`--probe` 明确允许调用 Obsidian CLI；`open` 明确请求打开配置的 Wiki。

## instruction-only 插件

```bash
mini-wiki plugins list /path/to/project
mini-wiki plugins install owner/repository /path/to/project
mini-wiki plugins enable plugin-name /path/to/project
mini-wiki plugins disable plugin-name /path/to/project
mini-wiki plugins update plugin-name /path/to/project
mini-wiki plugins uninstall plugin-name /path/to/project
```

插件默认禁用，只提供说明文本；任何脚本、钩子、包管理器或命令都不得导入或执行。

## 默认目录

```text
wiki/                         # 正式知识
├── index.md
├── getting-started.md
├── architecture.md
├── knowledge-map.md
├── domains/
├── reference/
├── views/*.base
└── canvas/*.canvas

.mini-wiki/                   # 配置与状态
├── config.yaml
├── manifest.json
├── meta.json
├── cache/
├── staging/
└── archive/
```

## 托管标记

```markdown
<!-- mini-wiki:generated:start -->
CLI-owned facts.
<!-- mini-wiki:generated:end -->

<!-- mini-wiki:content:start -->
Agent-owned explanation.
<!-- mini-wiki:content:end -->
```

## 配置能力开关

schema v3 为搜索、Bases、Canvas 与可选 Obsidian 集成提供独立开关。扫描配置还包括 Git ignore、显式排除、
符号链接边界、文件大小限制，以及 Wiki/状态目录隔离。

如果这是第一次使用，先按[五分钟上手](/guide/)完成完整闭环；数据关系见[知识网络模型](/knowledge-network/)。

# 安全、边界与恢复

Mini-Wiki 的安全不是“生成完成后再检查”，而是由目录职责、所有权标记、扫描限制、事务写入和默认禁用
共同组成。

## 正式知识与状态目录

```text
wiki/          # 正式、可移植、适合提交 Git
.mini-wiki/    # 配置、缓存、暂存与可恢复归档
.obsidian/     # Mini-Wiki 不创建、不修改
```

`wiki/` 是持久事实边界；`.mini-wiki/` 主要包含可重建或本地状态。不要把缓存当作正式知识，也不要让
构建流程把仓库外文件或机器本地绝对路径写进 Wiki。

## 扫描边界

扫描遵守 Git ignore、显式排除、文件大小限制、状态目录和 Wiki 目录排除，以及符号链接边界。来源只有
在允许的项目根目录内才可成为证据，避免把凭证、构建输出或相邻项目误纳入知识网络。

## 托管页面不会接管未知文档

只有带完整 Mini-Wiki 所有权标记的文档才由构建器更新。未知 Properties 保留给用户；缺少标记的现有
文档不会被覆盖。页面退出管理时先进入 `.mini-wiki/archive/`，便于审查与恢复。

## 第三方插件只提供说明

Mini-Wiki 插件采用 **instruction-only** 模型：安装的 `PLUGIN.md` 或 `SKILL.md` 是不可信文本，默认禁用。
Agent 可以阅读已启用的相关说明，但安全不变量是：**never import or execute plugin scripts, hooks,
package managers, or commands**（绝不导入或执行插件脚本、钩子、包管理器或命令）。

安装还会拒绝：

- 非 HTTPS 网络来源；
- 路径穿越、无效根目录与符号链接；
- 超出限制的压缩包；
- 未确认的同名覆盖；
- 与记录 tree hash 不一致的静默内容变化。

## Obsidian 是可选界面

构建、搜索、严格校验、迁移、Bases 与 Canvas 均不依赖 Obsidian。普通状态检查无副作用：

```bash
mini-wiki obsidian status --json /path/to/project
```

只有显式 `--probe` 才可能调用 Obsidian CLI 并启动应用；只有 `obsidian open` 会通过编码后的 Obsidian URI
请求打开配置的 Wiki。Mini-Wiki 不需要写入 `.obsidian/`。

## 事务、迁移与失败恢复

构建先在 staging 生成候选结果，验证成功后再切换。失败时保留当前正式 Wiki。迁移默认只预览，应用时
拒绝非空目标、备份旧材料、验证复制结果，并在最后一步切换配置。

```bash
mini-wiki migrate --json /path/to/project
mini-wiki migrate --apply --json /path/to/project
mini-wiki migrate --apply --adopt --json /path/to/project
```

## 发布前检查

1. 确认 `wiki/` 中没有凭证、个人信息或机器绝对路径；
2. 运行 `mini-wiki check --strict --json`；
3. 审查 Agent 内容的源码证据；
4. 比较第二次无变化构建；
5. 只提交正式知识和明确需要的配置。

命令与开关的完整入口在[参考手册](/reference/)，首次操作流程见[五分钟上手](/guide/)。