Skip to content
KnowFlow logoKnowFlow

Data model

Every page in a KnowFlow wiki is one of four types: source, entity, concept, comparison. Each type has a fixed anatomy — frontmatter fields, required sections, end-of-line confidence markers, linking rules — so pages stay machine-checkable and any coding agent synthesizes them into the same shape. This page walks through that anatomy. The authoritative blueprint is the four Markdown templates in the knowflow repository (templates/source.md, templates/entity.md, templates/concept.md, templates/comparison.md); wherever prose — including this page — disagrees with a template, the template wins.

Project layout

Section titled “Project layout”
project/
├── raw/                     # captured material (immutable); created_from points here
│   ├── web/
│   ├── twitter/
│   ├── xiaohongshu/
│   └── wechat/
├── wiki/
│   ├── index.md             # navigation hub (tool-owned)
│   ├── sources/             # source pages
│   ├── entities/            # entity pages
│   ├── concepts/            # concept pages
│   ├── comparisons/         # comparison pages
│   └── tag/                 # tag hub pages, generated by knowflow tags (tool-owned)
└── graph/                   # graph.html, graph.json (generated)

A page file must live in the directory matching its frontmatter type. wiki/index.md, wiki/log.md, and wiki/tag/ are tool-owned — they are not page types, and agents never create or edit them.

Frontmatter

Section titled “Frontmatter”

Every page opens with a ----wrapped YAML frontmatter — the only carrier of structured metadata. Graph and index builds strip it before processing, so metadata lines never leak into node summaries or vector chunks.

Field Values Required Meaning
type source | entity | concept | comparison yes Page type; a closed enum that must match the file’s directory
title string yes Page title; the body H1 must match it
created YYYY-MM-DD yes Page creation date
created_from repo-relative path yes The raw file this page was synthesized from, e.g. raw/web/2026-09-01-1430-page.md. Required for all four types; concept and comparison pages point at the raw file that prompted their synthesis
status pending | reviewed yes (templates default to pending) Review state, closed to these two values. Legacy pages without a status key are treated as reviewed
source_url URL no Link to the original material; strongly recommended on source pages

The review gate is the point of status. Each gate targets pending only:

  • Graph (knowflow graph): pending pages stay out of the graph — no node, no edge, and wikilinks pointing at them produce no edges.
  • Vector index (knowflow index build): pending pages stay out of the search index.
  • Health (knowflow health): pending pages are exempt from the orphan check — being unlinked is normal while awaiting review — while the broken-link and minimum-size checks still apply to them in full.
  • Repair (knowflow fix): pending pages are never touched by it. (Agents must never run knowflow fix without --dry-run anyway — unflagged repair is destructive; make repairs by editing the page, or read knowflow fix --dry-run output and fix by hand.)
  • Status list (knowflow status): lists every pending page awaiting review.

created_from also powers the synthesis queue: knowflow compose --list reports every raw file that no page’s created_from points at yet — a derived difference with zero state files.

Page sections

Section titled “Page sections”

General rules for every page type:

  • Required sections appear as ## headings exactly as spelled in the template, in template order — the canonical heading strings are Chinese. When a required section truly has nothing to say, write 无; never delete the heading.
  • Optional sections are omitted entirely when irrelevant — that is not a violation.
  • HTML comments inside templates are writing guidance, not sections; they never appear in a finished page.
  • The body H1 matches the frontmatter title.

Source page (sources/*.md)

Section titled “Source page (sources/*.md)”
Section Required Acceptance line
一句话总结 (one-sentence summary) yes One sentence on the source’s core value
核心要点 (key points) yes 3–8 bullets; each ends with exactly one (EXTRACTED) or (INFERRED)
提取的实体 (extracted entities) yes Wikilinks to entities/ pages, each with the entity’s role in this source
提取的概念 (extracted concepts) yes Wikilinks to concepts/ pages, each with the concept’s role in this source; a concept that has no page yet is named in prose without a wikilink — concept pages are synthesized only when you explicitly ask
与其他来源的关系 (relations to other sources) no Omit the whole section when there are none; relation types are 互补 / 矛盾 / 延伸 / 反驳 (complement, contradiction, extension, rebuttal)

Entity page (entities/*.md)

Section titled “Entity page (entities/*.md)”
Section Required Acceptance line
基本信息 (basic info) yes Field list (type, alias/English name, domain, key data, …)
核心要点 (key points) yes 2–4 bullets; same end-of-line marker rule as source pages
关联内容 (related) yes Wikilinks to concept, source, or comparison pages
时间线 (timeline) no Three-column table: 日期 | 事件 | 来源; the source column is a wikilink to a source page
注意事项与矛盾 (caveats and contradictions) no Claims to verify, or content that conflicts across sources

Concept page (concepts/*.md)

Section titled “Concept page (concepts/*.md)”
Section Required Acceptance line
定义 (definition) yes One sentence
核心观点 (core claims) yes Each claim notes which source page it comes from
不同来源的视角对比 (cross-source perspectives) yes Three-column table: 来源 | 视角 | 关键论点; at least 2 data rows citing at least 2 distinct source pages ([[sources/…]] wikilinks)
关联内容 (related) yes Wikilinks
反面观点 (counterpoints) no Recorded when controversy or opposing views exist
实践应用 (practice) no Application scenarios
延伸阅读 (further reading) no Wikilinks

Comparison page (comparisons/*.md)

Section titled “Comparison page (comparisons/*.md)”
Section Required Acceptance line
对比对象 (subjects) yes 2–3 subjects; all seven dimension rows are required — 定位/定义, 核心优势, 核心劣势, 适用场景, 学习成本, 生态成熟度, 成本; custom dimension rows may be appended
结论 (verdict) yes A recommended subject per scenario, with reasons
局限性 (limitations) yes The sources the comparison rests on, and possible bias
关联内容 (related) yes Wikilinks

Where “Related content” applies

Section titled “Where “Related content” applies”

A recorded ruling: the required 关联内容 section applies only to entity, concept, and comparison pages. Source pages have no such section — their outgoing links are carried by the two required sections 提取的实体 and 提取的概念, and source-to-source links by the optional 与其他来源的关系.

EXTRACTED / INFERRED markers

Section titled “EXTRACTED / INFERRED markers”
  • Closed set of two: (EXTRACTED) (taken from the source) and (INFERRED) (the agent’s inference). There is no third value; an (INFERRED) bullet must state its basis in the bullet text.
  • Fixed position: exactly one marker at the end of each bullet — never omitted, never duplicated.
  • Scope: only the source page’s 核心要点 (3–8 bullets) and the entity page’s 核心要点 (2–4 bullets). Concept and comparison pages carry no markers, and no other section carries them.
  • Lifecycle: markers are part of the content. After human review flips pending to reviewed, the markers stay.

File naming

Section titled “File naming”
  • Files live in the page-type directory matching type; the file name is the slug of the page title (for entity pages, the entity’s proper name).
  • Slug rules: ASCII letters lowercased; CJK characters kept verbatim; spaces become hyphens; no date prefix (the date lives in frontmatter created); NFC Unicode normalization applied before writing.
  • Name collision: a disambiguating suffix is appended — existing files are never silently overwritten.
  • Examples: 「检索增强生成 RAG」 → concepts/检索增强生成-rag.md; Andrej Karpathy → entities/andrej-karpathy.md.
Section titled “Wikilinks”
[[entities/karpathy]]           valid — resolves to wiki/entities/karpathy.md
[[concepts/检索增强生成-rag]]   valid — CJK slugs are kept verbatim
[[tag/rag]]                     valid — tool-owned tag hub link
[[karpathy]]                    invalid — bare name, no directory prefix
[[entities/karpathy.md]]        invalid — targets never carry the .md suffix
[[entities/karpathy|Andrej]]    invalid — the pipe alias is not valid syntax
  • The target of [[…]] is a wiki-root-relative path without the .md suffix and without a |alias pipe. To show different text, write it in the prose around the link, not inside the brackets.
  • No bare names: the target must carry the page-type directory prefix so it resolves strictly on the first try.
  • Strict resolution is the gate: knowflow health reads every wikilink as wiki/<target>.md; a miss is a broken link. knowflow graph keeps two lenient fallbacks (filename-stem and substring match) for hand-written pages, but generated pages must never rely on them — every wikilink on a generated page must resolve strictly.
  • No fuzzy matching, no auto-stub: this repository has no edit-distance link guessing and no feature that creates a page because a link points at a missing file. A missing target is simply a broken link for knowflow health to report; repairs are made by editing pages, never by automatic page creation.
  • Links to pending pages produce no graph edges — that is the review gate working as intended — while health’s broken-link check still covers them in full.

A source page

Section titled “A source page”

A source page in this shape (excerpted from the sample wiki in the knowflow repository, sample-wiki/sources/mcp-protocol.md):

---
type: source
title: Model Context Protocol (MCP)
created: 2026-04-27
created_from: raw/web/2026-04-27-1020-mcp-protocol.md
status: reviewed
source_url: https://modelcontextprotocol.io/introduction
---


# Model Context Protocol (MCP)


## 一句话总结


Anthropic 主导的开放标准协议 MCP：用统一接口把 AI 助手连接到外部数据源与工具。


## 核心要点


- MCP 出现前 AI 助手接入外部工具面临四重障碍：每次集成成本高、API 格式无标准、上下文注入效率受限、权限边界不清 (EXTRACTED)
- 架构分三层角色：Host（Claude Desktop、IDE 等 AI 应用）、Client（Host 启动的连接进程）、Server（暴露资源与工具的程序） (EXTRACTED)
- KnowFlow 可作为 MCP Server 把 Wiki 知识库暴露为 Resource——由「Server 通过统一接口暴露数据与工具」推断 (INFERRED)


## 提取的实体


- [[entities/knowflow]] — Wiki 可暴露为 MCP Resource、ingest 可封装为 MCP Tool


## 提取的概念


- [[concepts/multi-agent-architecture]] — 统一的工具协议是多个 AI 应用与 Agent 协作的基础设施

Worth noticing:

  • Six frontmatter fields, with created_from pointing back at the raw file; this page has already been reviewed (status: reviewed).
  • Section headings are canonical Chinese strings; the body text stays in the author’s own language.
  • Every bullet ends with exactly one (EXTRACTED) or (INFERRED) marker, and the (INFERRED) bullet states its basis.
  • Wikilinks carry their directory prefix, followed by the role description after —.

Going deeper

Section titled “Going deeper”
  • Synthesis contract — docs/agents/synthesize.md, materialized into every workspace by knowflow init; see Use with an AI assistant. The upstream master lives at the same path in the knowflow repository: https://github.com/jerryjiao/knowflow/blob/main/docs/agents/synthesize.md
  • Reference spec — docs/reference/data-model.md in the knowflow repository: every rule on this page in gate-checkable form.
  • Templates — templates/source.md, templates/entity.md, templates/concept.md, templates/comparison.md in the same repository: the authoritative anatomy.
  • Machine gate — knowflow check validates the eight-condition page anatomy; see the Command reference.