@jerryjiao/knowflow 0.3.0

package/docs/methodology/llm-wiki-methodology.md

@@ -0,0 +1,110 @@
+# LLM Wiki 方法论
+
+> 基于 Andrej Karpathy 的 [LLM Wiki Gist](https://karpathy.github.io/llm-wiki/)，KnowFlow 将这一理念工程化实现。
+
+## 核心问题
+
+传统知识管理方式存在根本性缺陷：
+
+| 方式 | 问题 |
+|------|------|
+| **收藏/书签** | "存了 = 学了" 的错觉（Collector's Fallacy） |
+| **笔记软件** | 只解决"存"，不解决"整理"和"连接" |
+| **RAG** | 每次从零搜索，无记忆、无积累、无上下文 |
+
+## LLM Wiki 的核心洞察
+
+> **别每次都去原始文档里翻，先把知识编译好，放在那，用的时候直接拿。**
+
+类比：
+
+- **RAG = 临时工** — 每次慌慌张张翻文件柜，找到几张纸拼答案，下次再来一脸懵
+- **LLM Wiki = 全职图书管理员** — 平时就在整理材料：提取信息、发现关联、建立索引、维护知识图谱。你来问时直接调取
+
+## 三层架构
+
+### 1. Raw Layer（原材料）
+
+你喂进去的一切原始内容：
+- 网页 URL（文章、博客、文档）
+- Twitter/X 书签和推文
+- PDF 论文和白皮书
+- 微信公众号文章
+- YouTube 字幕
+- 飞书/Notion 文档
+
+**原则**：Raw 层只存储，不修改。它是不可变的源数据。
+
+### 2. Wiki Layer（编译后的知识）— 核心
+
+AI 读取 Raw 内容后，自动生成三类结构化页面：
+
+#### 实体页（Entity Pages）
+具体的"东西"：
+- 人物：Andrej Karpathy、Jerry
+- 公司/组织：OpenAI、智谱 AI
+- 项目/产品：MCP 协议、KnowFlow、Claude Code
+- 概念的具体实例
+
+#### 概念页（Concept Pages）
+抽象的"想法"和方法论：
+- RAG（检索增强生成）
+- Embedding（向量嵌入）
+- 向量检索
+- 自回归 vs 扩散模型
+- Collector's Fallacy
+
+#### 对比页（Comparison Pages）
+两个事物之间的系统对比：
+- MCP vs A2A（Agent 通信协议）
+- RAG vs LLM Wiki
+- KnowFlow vs Notion AI
+- CogView vs DALL-E
+
+#### 来源页（Source Pages）
+原始内容的结构化摘要：
+- 原文链接 + 元数据
+- 提取的关键实体列表
+- 自动生成的摘要
+
+**关键特性**：页面之间**自动互相链接**
+- 提到 OpenAI → 自动链到 OpenAI 实体页
+- 提到 RAG → 自动链到 RAG 概念页
+- 时间一长 → 形成一张**活的知识网络**
+
+### 3. Schema Layer（结构规则）
+
+告诉 AI 怎么编 Wiki 的"工作手册"：
+- 什么该提取，什么该忽略
+- 页面格式规范
+- 实体识别规则
+- 链接策略
+
+## 为什么这比 RAG 更好？
+
+```
+RAG 的流程:
+  用户提问 → 搜索原始文档 → 拼凑答案 → 忘记一切
+
+LLM Wiki 的流程:
+  新内容进入 → 编译为 Wiki 页面 → 建立关联 → 更新知识图谱
+                                                              ↓
+  用户提问 → 从已编译的知识库调取 → 基于完整上下文回答 → 知识库持续增长
+```
+
+优势：
+1. **有记忆** — 知识是累积的，不是每次从零开始
+2. **有结构** — 实体、概念、对比，不是扁平的文档片段
+3. **可探索** — 知识图谱让你发现隐藏的关联
+4. **可验证** — 每条知识都有来源追溯
+
+## KnowFlow 的定位
+
+KnowFlow 是 LLM Wiki 方法论的**开源实现**：
+
+- 用 Node.js 构建 CLI 工具
+- 用智谱 AI（或其他 LLM）做内容提取
+- 用 Python 构建知识图谱和向量索引
+- 全部本地运行，数据自主可控
+
+**核心理念**：最有意思的不是最终工具，而是看着零散的信息一点点变成结构化知识的过程。

package/docs/reference/data-model.md

@@ -0,0 +1,200 @@
+# KnowFlow 数据模型
+
+## Wiki 页面类型
+
+### 实体页 (Entity)
+
+```markdown
+# {name}
+
+**类型**: {person | organization | project | product | location}
+**来源**: [{source_url}]
+**首次提及**: {date}
+
+## 简介
+{description 一段话}
+
+## 关键信息
+- {field}: {value}
+- {field}: {value}
+
+## 相关概念
+- [[Concept1]]
+- [[Concept2]]
+
+## 相关实体
+- [[EntityA]] — {关系描述}
+- [[EntityB]] — {关系描述}
+
+---
+*最后更新: {date} | 来源: {url}*
+```
+
+### 概念页 (Concept)
+
+```markdown
+# {name}
+
+**分类**: {methodology | technology | framework | pattern}
+
+## 定义
+{清晰的技术定义，1-3 句话}
+
+## 核心要点
+1. **Point 1** — 解释
+2. **Point 2** — 解释
+3. **Point 3** — 解释
+
+## 与其他概念的关系
+- **父概念**: [[ParentConcept]]
+- **子概念**: [[ChildConcept]]
+- **对比**: [[SimilarConcept]] (差异在于...)
+
+## 实际应用
+- 在 {context} 中，{how it's used}
+- {example from real world}
+
+## 参考
+- [{source_title}]({url})
+```
+
+### 对比页 (Comparison)
+
+```markdown
+# {A} vs {B}
+
+## 概述
+{一句话说明两者定位差异}
+
+## 对比维度
+
+| 维度 | {A} | {B} |
+|------|-----|-----|
+| 定位 | ... | ... |
+| 适用场景 | ... | ... |
+| 优势 | ... | ... |
+| 劣势 | ... | ... |
+| 学习成本 | ... | ... |
+| 生态 | ... | ... |
+
+## 结论
+{什么场景选 A，什么场景选 B}
+
+## 相关
+- [[RelatedEntity1]]
+- [[RelatedConcept1]]
+```
+
+### 来源页 (Source)
+
+```markdown
+# {title}
+
+**原始链接**: {url}
+**作者**: {author}
+**发布日期**: {date}
+**摄取时间**: {ingest_date}
+
+## 摘要
+{AI 生成的 2-3 句摘要}
+
+## 提取的实体
+- [[Entity1]] ({type})
+- [[Entity2]] ({type})
+
+## 涉及的概念
+- [[Concept1]]
+- [[Concept2]]
+
+## 关键观点
+1. "{quote or key point}"
+2. "{quote or key point}"
+```
+
+## 内部数据格式
+
+### .ingest-state.json
+
+```json
+{
+  "files": {
+    "raw/article-001.md": {
+      "mtime": "1740000000",
+      "hash": "abc123def456"
+    }
+  },
+  "lastIngestAt": "2026-04-28T10:00:00"
+}
+```
+
+用途：追踪哪些 raw 文件已被处理，支持增量 ingest。
+
+### graph.json
+
+```json
+{
+  "nodes": [
+    {"id": "knowflow", "label": "KnowFlow", "type": "project", "size": 15},
+    {"id": "rag", "label": "RAG", "type": "concept", "size": 10},
+    {"id": "llm-wiki", "label": "LLM Wiki", "type": "concept", "size": 10},
+    {"id": "jerry", "label": "Jerry", "type": "person", "size": 5}
+  ],
+  "edges": [
+    {"source": "jerry", "target": "knowflow", "label": "created_by"},
+    {"source": "knowflow", "target": "rag", "label": "alternative_to"},
+    {"source": "knowflow", "target": "llm-wiki", "label": "implements"},
+    {"source": "knowflow", "target": "glm-flash", "label": "uses"}
+  ]
+}
+```
+
+### .bookmark-state.json
+
+```json
+{
+  "lastSyncAt": "2026-04-28T10:00:00",
+  "lastProcessedId": "18923456789012",
+  "stats": {
+    "totalBookmarks": 150,
+    "processedCount": 130,
+    "newThisRun": 5,
+    "skippedCount": 15
+  }
+}
+```
+
+## Wiki Link 语法
+
+KnowFlow 使用 `[[Name]]` 语法表示内部链接：
+
+```markdown
+// 标准链接
+[[RAG]]
+
+// 带显示文本
+[[检索增强生成|RAG]]
+
+// 链接自动解析规则:
+// 1. 精确匹配已有页面标题 → 直接链接
+// 2. 模糊匹配（编辑距离 < 3）→ 警告但创建
+// 3. 无匹配 → 创建新页面占位（标记为 stub）
+```
+
+## 配置文件 (.knowflowrc)
+
+```json
+{
+  "wiki": {
+    "root": "./wiki",
+    "rawDir": "./raw"
+  },
+  "graph": {
+    "output": "./graph/graph.html"
+  },
+  "health": {
+    "minFileSize": 100
+  }
+}
+```
+
+配置必须是有效 JSON，相对路径以 `.knowflowrc` 所在目录为基准。向量索引和查询使用项目根目录 `.env` 中的 `ZHIPUAI_API_KEY`，或同名环境变量。

package/examples/quickstart.md

@@ -0,0 +1,60 @@
+# KnowFlow text-to-graph quickstart
+
+This walkthrough is deterministic and does not fetch a URL or require an API key. It demonstrates the real boundary between raw capture and Wiki organization.
+
+## 1. Create a project and capture a note
+
+```bash
+npx knowflow@latest init knowflow-demo
+cd knowflow-demo
+npx knowflow ingest "Linked notes become more useful when concepts point to sources." --source text
+```
+
+If you installed KnowFlow from a source checkout with `npm link`, replace `npx knowflow` with `knowflow` in every command.
+
+The note now exists under `raw/web/`. It has **not** been converted into a structured Wiki page.
+
+## 2. Organize one Wiki page
+
+Create `wiki/concepts/linked-knowledge.md` with this content:
+
+```markdown
+# Linked knowledge
+
+Linked knowledge connects durable concepts to the sources that support them.
+
+## Connections
+
+- [[index]]
+- [[sources/capture-example]]
+```
+
+Then create `wiki/sources/capture-example.md`:
+
+```markdown
+# Capture example
+
+This source page records the note captured during the KnowFlow quickstart.
+
+## Connections
+
+- [[concepts/linked-knowledge]]
+```
+
+This manual step is exactly where an AI agent or custom workflow can read `raw/`, draft pages from the included templates, and ask for review.
+
+## 3. Validate and build the graph
+
+```bash
+npx knowflow health
+npx knowflow status
+npx knowflow graph --no-open
+```
+
+Expected outputs:
+
+- `graph/graph.html` — interactive graph viewer
+- `graph/graph.json` — graph data for other tools
+- `graph/.graph-state.json` — graph build state
+
+Open `graph/graph.html` in a browser. The viewer loads vis-network from a CDN, so the first view requires a network connection.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@jerryjiao/knowflow",
+  "version": "0.3.0",
+  "description": "Agent-native Markdown workspace for raw capture, linked wikis, knowledge graphs, and semantic search",
+  "type": "module",
+  "bin": {
+    "knowflow": "./bin/knowflow.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "templates/",
+    "docs/",
+    "!docs/launch",
+    "examples/",
+    "README.md",
+    "README.zh-CN.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "knowflow": "node bin/knowflow.js",
+    "test": "node --test",
+    "check": "node --check bin/knowflow.js && node --check scripts/batch-ingest.cjs && node --check scripts/enrich-wiki.js && node --check scripts/vector-store.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jerryjiao/knowflow.git"
+  },
+  "homepage": "https://github.com/jerryjiao/knowflow#readme",
+  "bugs": {
+    "url": "https://github.com/jerryjiao/knowflow/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "knowledge-base",
+    "knowledge-graph",
+    "knowledge-management",
+    "personal-knowledge-management",
+    "markdown",
+    "ai-agent",
+    "wiki",
+    "llm",
+    "rag",
+    "cli"
+  ],
+  "license": "MIT"
+}