数据模型

KnowFlow wiki 的每一页都是四种类型之一：source（来源页）、entity（实体页）、concept（概念页）、comparison（对比页）。每种类型有一副固定的解剖——frontmatter 字段、必填章节、行尾置信标注、链接规则——页面因此可被机器校验，任何编码 agent 合成出来的形状也一致。本页带你走一遍这套解剖。权威本体是 knowflow 仓库下的四张 Markdown 模板（templates/source.md、templates/entity.md、templates/concept.md、templates/comparison.md）；任何文字——包括本页——与模板不一致时，以模板为准。

项目目录

project/
├── raw/                     # 采集的原始素材（不可变）；created_from 指向这里
│   ├── web/
│   ├── twitter/
│   ├── xiaohongshu/
│   └── wechat/
├── wiki/
│   ├── index.md             # 导航 hub（工具所有）
│   ├── sources/             # 来源页
│   ├── entities/            # 实体页
│   ├── concepts/            # 概念页
│   ├── comparisons/         # 对比页
│   └── tag/                 # 标签聚合页，knowflow tags 生成（工具所有）
└── graph/                   # graph.html、graph.json（生成产物）

页面文件必须放在与其 frontmatter type 一致的目录下。wiki/index.md、wiki/log.md、wiki/tag/ 归工具所有——它们不是页面类型，agent 绝不创建或改写。

frontmatter 字段

每页以 --- 包围的 YAML frontmatter 开始——结构化元数据的唯一载体。图谱与向量索引构建会先剥离它，元数据行不会泄漏进节点摘要或向量分块。

字段	值域	必填	语义
`type`	`source` \| `entity` \| `concept` \| `comparison`	是	页面类型；封闭枚举，必须与文件所在目录一致
`title`	字符串	是	页面标题；正文 H1 与之一致
`created`	`YYYY-MM-DD`	是	页面创建日期
`created_from`	仓库相对路径	是	促成该页的 raw 来源文件，如 `raw/web/2026-09-01-1430-page.md`。四种类型皆必填；concept / comparison 页填写促成合成该页的那份 raw 来源
`status`	`pending` \| `reviewed`	是（模板默认 `pending`）	审阅状态，封闭两值。无 `status` 键的存量页按已审（reviewed）处理
`source_url`	URL	否	原始内容链接；source 页强烈建议填写

status 的意义就在审核闸门。各闸门只针对 pending：

图谱（knowflow graph）：待审页不进图谱——不建节点、不建边，指向它们的 wikilink 也不产生边。
向量索引（knowflow index build）：待审页不进检索索引。
健康检查（knowflow health）：待审页豁免孤儿页判定——待审期没被链接是常态——断链与最小体积检查对 pending 页照常全量执行。
修复（knowflow fix）：不碰 pending 页。（agent 本就绝不运行不带 --dry-run 的 knowflow fix——不带旗标的修复是破坏性的；修复靠手工编辑页面，或先读 knowflow fix --dry-run 的输出再动手。）
状态清单（knowflow status）：列出全部待审页。

created_from 还驱动合成队列：knowflow compose --list 的「待合成清单」= raw/ 全集 − 各页面 frontmatter 中出现过的 created_from 指针——派生差集，零状态文件。

页面章节

各页型通用规则：

必填章节的 ## 标题必须按模板顺序精确出现，标题文本逐字一致——固定标题就是这些中文字符串。必填章节确实无内容时写「无」，不得删去标题。
可选章节在无关时整节省略，不算违规。
模板中的 HTML 注释是写作指引，不属于章节，不出现在成品页中。
正文 H1 与 frontmatter title 一致。

source 来源页（`sources/*.md`）

章节	必填	验收线
一句话总结	是	一句话概括本篇来源的核心价值
核心要点	是	3–8 条列表；每条行尾恰好一个 `(EXTRACTED)` 或 `(INFERRED)`
提取的实体	是	指向 `entities/` 页的 wikilink，附该实体在本篇中的角色说明
提取的概念	是	指向 `concepts/` 页的 wikilink，附该概念在本篇中的角色说明；尚无页面的概念写概念名散文、不加 wikilink——概念页仅在人显式点名时合成
与其他来源的关系	否	与其他来源无关时整节省略；关系类型取互补 / 矛盾 / 延伸 / 反驳

entity 实体页（`entities/*.md`）

章节	必填	验收线
基本信息	是	字段式列表（类型、别名/英文名、所属领域、关键数据等）
核心要点	是	2–4 条；行尾标注规则与 source 页核心要点相同
关联内容	是	指向概念/来源/对比等页面的 wikilink
时间线	否	表格三列：日期 \| 事件 \| 来源；来源列为指向 source 页的 wikilink
注意事项与矛盾	否	需核实或互相矛盾的内容

concept 概念页（`concepts/*.md`）

章节	必填	验收线
定义	是	一句话定义
核心观点	是	逐条注明出自哪张来源页
不同来源的视角对比	是	表格三列：来源 \| 视角 \| 关键论点；≥ 2 行数据，且引用 ≥ 2 张不同的 source 页（`[[sources/…]]` 形式的 wikilink）
关联内容	是	wikilink
反面观点	否	存在争议或对立观点时记录
实践应用	否	应用场景
延伸阅读	否	wikilink

comparison 对比页（`comparisons/*.md`）

章节	必填	验收线
对比对象	是	2–3 个对比对象；七个维度行全部必填——定位/定义、核心优势、核心劣势、适用场景、学习成本、生态成熟度、成本；可按需追加自定义维度行
结论	是	按场景给出推荐对象及理由
局限性	是	说明本次对比依据的来源与可能的信息偏差
关联内容	是	wikilink

「关联内容」的适用范围（裁定）

一条已记录的裁定：必填章节「关联内容」仅适用于 entity / concept / comparison 三种页面。source 页不设「关联内容」章节——其对外链接职责由两个必填章节「提取的实体」「提取的概念」承担，来源页之间的横向链接由可选章节「与其他来源的关系」承担。

EXTRACTED / INFERRED 标注

值域封闭，仅两值：(EXTRACTED)（摘自原文）与 (INFERRED)（agent 推断），无第三种值；使用 (INFERRED) 时要点文本需注明推断依据。
位置固定：每条要点行尾恰好一个标注，不省略、不重复。
适用范围：仅 source 页核心要点（3–8 条）与 entity 页核心要点（2–4 条）。concept / comparison 页不带任何标注，其他章节亦不带。
生命周期：标注是正文内容的一部分。人工审阅把 pending 翻成 reviewed 之后，标注保留、不删除。

文件命名

文件放在与 type 一致的页型目录下；文件名取页面标题（entity 页为实体本名）的 slug。
slug 规则：ASCII 字母转小写；CJK 字符原样保留；空格转换为连字符 -；不加日期前缀（日期在 frontmatter created）；写入前做 NFC Unicode 规范化。
撞名处理：追加消歧后缀，绝不静默覆盖既有文件。
示例：「检索增强生成 RAG」→ concepts/检索增强生成-rag.md；Andrej Karpathy → entities/andrej-karpathy.md。

内部链接（wikilink）

[[entities/karpathy]]           合法——解析到 wiki/entities/karpathy.md
[[concepts/检索增强生成-rag]]   合法——CJK slug 原样保留
[[tag/rag]]                     合法——工具所有的标签聚合链接
[[karpathy]]                    非法——裸名，无页型目录前缀
[[entities/karpathy.md]]        非法——目标不带 .md 后缀
[[entities/karpathy|Andrej]]    非法——管道别名不是合法语法

[[…]] 的目标是不带 .md 后缀、不带 |别名 管道的 wiki 根相对路径。想让显示文本与 slug 不同，把变体写进链接周围的散文，不写进方括号。
禁止裸名：目标必须带页型目录前缀，保证首次即严格解析命中。
严格解析即门：knowflow health 将 wikilink 目标一律按 wiki/<目标>.md 解析，解析不到即记为断链。knowflow graph 为手写页保留了文件名 stem 匹配与子串包含匹配两档宽容，但生成页面绝不得依赖——生成页的每条 wikilink 必须在严格解析下可达。
无模糊匹配、无自动建桩（auto-stub）：本仓库没有按编辑距离猜链接的规则，也没有「链接目标不存在就自动建页」的功能。目标不存在即断链，由 knowflow health 报告；修复靠编辑页面，绝不靠自动建页。
指向待审页的链接在图谱中不产生边——这是审核闸门的预期行为——health 的断链检查对它们照常全量执行。

来源页示例

一张此形状的 source 页（裁剪自 knowflow 仓库的示例库 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 协作的基础设施

值得注意的几点：

frontmatter 六字段齐全，created_from 指回 raw 来源文件；这张页已通过人工审核（status: reviewed）。
章节标题是固定的中文字符串；正文内容用作者自己的语言。
每条要点行尾恰好一个 (EXTRACTED) 或 (INFERRED) 标注，(INFERRED) 那条注明了推断依据。
wikilink 带页型目录前缀，后接 — 引出的角色说明。