@jerryjiao/knowflow 0.3.0

package/bin/knowflow.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+/** KnowFlow CLI */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, parse, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPTS = join(PACKAGE_ROOT, 'scripts');
+const VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+const RC_NAME = '.knowflowrc';
+const DEFAULT_CONFIG = {
+  wiki: { root: './wiki', rawDir: './raw' },
+  graph: { output: './graph/graph.html' },
+  health: { minFileSize: 100 },
+};
+
+function findProjectRoot(start = process.cwd()) {
+  let current = resolve(start);
+  const filesystemRoot = parse(current).root;
+  while (true) {
+    if (existsSync(join(current, RC_NAME))) return current;
+    if (current === filesystemRoot) return resolve(start);
+    current = dirname(current);
+  }
+}
+
+function loadProject(start = process.cwd()) {
+  const root = findProjectRoot(start);
+  const rcPath = join(root, RC_NAME);
+  let userConfig = {};
+  if (existsSync(rcPath)) {
+    try {
+      userConfig = JSON.parse(readFileSync(rcPath, 'utf8'));
+    } catch (error) {
+      throw new Error(`无法解析 ${rcPath}: ${error.message}`);
+    }
+  }
+
+  const config = {
+    wiki: { ...DEFAULT_CONFIG.wiki, ...userConfig.wiki },
+    graph: { ...DEFAULT_CONFIG.graph, ...userConfig.graph },
+    health: { ...DEFAULT_CONFIG.health, ...userConfig.health },
+  };
+  const pathValue = (value, label) => {
+    if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} 必须是非空路径`);
+    return resolve(root, value);
+  };
+
+  return {
+    root,
+    config,
+    wikiDir: pathValue(config.wiki.root, 'wiki.root'),
+    rawDir: pathValue(config.wiki.rawDir, 'wiki.rawDir'),
+    graphHtml: pathValue(config.graph.output, 'graph.output'),
+  };
+}
+
+function projectEnv(project) {
+  return {
+    ...process.env,
+    KNOWFLOW_ROOT: project.root,
+    KNOWFLOW_WIKI_DIR: project.wikiDir,
+    KNOWFLOW_RAW_DIR: project.rawDir,
+    KNOWFLOW_GRAPH_OUTPUT: project.graphHtml,
+    KNOWFLOW_HEALTH_EXCLUDE_ORPHAN: (project.config.health.excludeOrphanDirs ?? []).join(':'),
+  };
+}
+
+function run(command, args, opts = {}) {
+  const result = spawnSync(command, args, {
+    cwd: opts.cwd,
+    env: opts.env,
+    encoding: 'utf8',
+    stdio: opts.silent ? 'pipe' : 'inherit',
+    timeout: opts.timeout ?? 120_000,
+    shell: false,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = opts.silent ? (result.stderr || result.stdout || '').trim() : '';
+    const error = new Error(detail || `${command} 退出，状态码 ${result.status}`);
+    error.status = result.status;
+    throw error;
+  }
+  return result.stdout || '';
+}
+
+function countFiles(dir, ext = '.md') {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) count += countFiles(path, ext);
+    else if (entry.name.endsWith(ext)) count++;
+  }
+  return count;
+}
+
+function countLines(dir) {
+  if (!existsSync(dir)) return 0;
+  let lines = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) lines += countLines(path);
+    else if (entry.name.endsWith('.md')) {
+      try { lines += readFileSync(path, 'utf8').split('\n').length; } catch {}
+    }
+  }
+  return lines;
+}
+
+function hasApiKey(project) {
+  if (process.env.ZHIPUAI_API_KEY) return true;
+  try {
+    return readFileSync(join(project.root, '.env'), 'utf8')
+      .split(/\r?\n/)
+      .some(line => /^\s*ZHIPUAI_API_KEY\s*=\s*[^$\s]/.test(line));
+  } catch {
+    return false;
+  }
+}
+
+function initialise(directory) {
+  const root = resolve(directory);
+  mkdirSync(root, { recursive: true });
+  const rcPath = join(root, RC_NAME);
+  if (!existsSync(rcPath)) {
+    writeFileSync(rcPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, 'utf8');
+    console.log(chalk.green(`✅ 已创建 ${rcPath}`));
+  } else {
+    console.log(chalk.yellow(`⚠️  ${rcPath} 已存在，保留原配置`));
+  }
+
+  const project = loadProject(root);
+  for (const dir of [
+    project.wikiDir,
+    ...['sources', 'entities', 'concepts', 'comparisons'].map(name => join(project.wikiDir, name)),
+    project.rawDir,
+    ...['web', 'twitter', 'xiaohongshu', 'wechat'].map(name => join(project.rawDir, name)),
+    dirname(project.graphHtml),
+  ]) mkdirSync(dir, { recursive: true });
+
+  const templatesDir = join(root, 'templates');
+  mkdirSync(templatesDir, { recursive: true });
+  for (const name of readdirSync(join(PACKAGE_ROOT, 'templates'))) {
+    const source = join(PACKAGE_ROOT, 'templates', name);
+    const destination = join(templatesDir, name);
+    if (!existsSync(destination)) cpSync(source, destination);
+  }
+
+  const indexPath = join(project.wikiDir, 'index.md');
+  if (!existsSync(indexPath)) {
+    writeFileSync(indexPath, [
+      '# KnowFlow Wiki',
+      '',
+      '欢迎使用 KnowFlow。这里是知识库的首页与导航入口。',
+      '',
+      '## 开始使用',
+      '',
+      '- 将来源页放在 `sources/`',
+      '- 将实体页放在 `entities/`',
+      '- 将概念页放在 `concepts/`',
+      '- 使用双中括号 Wiki 链接建立页面之间的联系',
+      '',
+    ].join('\n'), 'utf8');
+  }
+  console.log(chalk.green(`✅ KnowFlow 项目已初始化: ${root}`));
+}
+
+const banner = `\n${chalk.cyan.bold('  KnowFlow')} ${chalk.dim(`v${VERSION}`)}\n${chalk.green('  AI 知识流系统 — 将 URL 变成结构化 Wiki + 知识图谱')}\n`;
+
+program
+  .name('knowflow')
+  .description('AI 知识流系统 — 将 URL 变成结构化 Wiki + 知识图谱')
+  .version(VERSION)
+  .addHelpText('beforeAll', banner)
+  .addHelpCommand();
+
+program
+  .command('init [directory]')
+  .description('在指定目录初始化 KnowFlow 项目（默认当前目录）')
+  .action((directory = '.') => initialise(directory));
+
+program
+  .command('ingest <url-or-text>')
+  .description('采集 URL 或文本，自动识别来源并保存到 raw 目录')
+  .option('-s, --source <type>', '指定来源类型', 'auto')
+  .action((input, opts) => {
+    const project = loadProject();
+    console.log(chalk.blue('🔗 开始采集素材...'));
+    try {
+      run('bash', [join(SCRIPTS, 'ingest.sh'), input, opts.source], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+      console.log(chalk.green('✅ 采集完成！'));
+    } catch (error) {
+      console.error(chalk.red('❌ 采集失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('query <text>')
+  .description('混合检索知识库（向量搜索 + 关键词匹配）')
+  .option('-n, --top <n>', '返回结果数量', value => {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) throw new Error('--top 必须是 1-100 的整数');
+    return parsed;
+  }, 5)
+  .action((text, opts) => {
+    const project = loadProject();
+    if (!hasApiKey(project)) {
+      console.error(chalk.yellow('⚠️  未检测到 ZHIPUAI_API_KEY，请在项目 .env 或环境变量中配置。'));
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      run(process.execPath, [join(SCRIPTS, 'vector-store.mjs'), 'query', text, '--top', String(opts.top)], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+    } catch (error) {
+      console.error(chalk.red('❌ 检索失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('graph')
+  .description('构建知识图谱并在浏览器中打开')
+  .option('--no-open', '构建但不打开浏览器')
+  .action(opts => {
+    const project = loadProject();
+    mkdirSync(dirname(project.graphHtml), { recursive: true });
+    console.log(chalk.cyan('🕸️  构建知识图谱...'));
+    try {
+      run('python3', [join(SCRIPTS, 'graph_builder.py'), '--wiki-dir', project.wikiDir, '--output', project.graphHtml], {
+        cwd: project.root,
+        env: projectEnv(project),
+        silent: true,
+      });
+      console.log(chalk.green(`✅ 图谱已生成: ${project.graphHtml}`));
+      if (opts.open !== false) {
+        const opener = process.platform === 'darwin' ? ['open', [project.graphHtml]]
+          : process.platform === 'win32' ? ['explorer.exe', [project.graphHtml]]
+            : ['xdg-open', [project.graphHtml]];
+        run(opener[0], opener[1], { cwd: project.root, env: projectEnv(project), silent: true });
+      }
+    } catch (error) {
+      console.error(chalk.red('❌ 图谱构建失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('fix')
+  .description('自动修复 health check 发现的问题（空链接、缺失文件、过小文件、孤儿页）')
+  .option('--dry-run', '只报告，不修改文件')
+  .action(opts => {
+    const project = loadProject();
+    console.log(chalk.magenta('🔧 自动修复 Wiki 问题...'));
+    try {
+      run('bash', [
+        join(SCRIPTS, 'wiki-auto-fix.sh'),
+        '--wiki-dir', project.wikiDir,
+        '--min-size', String(project.config.health.minFileSize),
+        ...(opts.dryRun ? ['--dry-run'] : []),
+      ], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+      console.log(chalk.green('✅ 修复完成！'));
+    } catch (error) {
+      console.error(chalk.red('❌ 修复失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('tags')
+  .description('从 [[tag/<name>]] 链接生成 tag 聚合页（tag/<name>.md）')
+  .action(() => {
+    const project = loadProject();
+    console.log(chalk.blue('🏷  构建 tag 聚合页...'));
+    try {
+      run(process.execPath, [join(SCRIPTS, 'tags-builder.mjs')], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+      console.log(chalk.green('✅ tag 聚合页已生成'));
+    } catch (error) {
+      console.error(chalk.red('❌ 生成失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('health')
+  .description('Wiki 健康检查（断链、空文件、孤立页面）')
+  .action(() => {
+    const project = loadProject();
+    console.log(chalk.yellow('🏥 Wiki 健康检查...'));
+    try {
+      run('bash', [join(SCRIPTS, 'wiki-health.sh'), '--wiki-dir', project.wikiDir, '--min-size', String(project.config.health.minFileSize)], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+    } catch {
+      console.log(chalk.yellow('⚠️  发现一些问题，建议修复（knowflow fix）'));
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('status')
+  .description('显示 Wiki 统计信息（含向量索引状态）')
+  .action(() => {
+    const project = loadProject();
+    const articleCount = countFiles(project.wikiDir);
+    const lineCount = countLines(project.wikiDir);
+    const rawCount = countFiles(project.rawDir);
+    let nodes = '-', edges = '-';
+    const graphJson = project.graphHtml.replace(/\.html$/i, '.json');
+    if (existsSync(graphJson)) {
+      try {
+        const graph = JSON.parse(readFileSync(graphJson, 'utf8'));
+        nodes = graph.nodes?.length ?? '-';
+        edges = graph.edges?.length ?? '-';
+      } catch {}
+    }
+    let vectorStatus = chalk.red('❌ 未构建');
+    const vectorFile = join(project.wikiDir, '.vector-index.json');
+    if (existsSync(vectorFile)) {
+      try {
+        const raw = JSON.parse(readFileSync(vectorFile, 'utf8'));
+        const pages = Array.isArray(raw) ? raw : raw.pages || [];
+        const embedded = pages.filter(item => item.embedding).length;
+        vectorStatus = chalk.green(`✅ ${pages.length} 页，${embedded} 页已向量化`);
+      } catch { vectorStatus = chalk.yellow('⚠️ 索引损坏'); }
+    }
+    console.log(`\n${chalk.bold.cyan('  📊 KnowFlow 状态概览')}`);
+    console.log(`  Wiki 文章数:  ${articleCount} 篇`);
+    console.log(`  总行数:       ${lineCount} 行`);
+    console.log(`  原始素材:     ${rawCount} 个`);
+    console.log(`  向量索引:     ${vectorStatus}`);
+    console.log(`  图谱:         ${nodes} 个节点 / ${edges} 条关系`);
+    console.log(`  API Key:      ${hasApiKey(project) ? '✅ 已配置' : '❌ 未配置'}`);
+    console.log(chalk.dim(`  项目目录: ${project.root}`));
+    console.log(chalk.dim(`  Wiki 目录: ${project.wikiDir}\n`));
+  });
+
+program.configureHelp({ sortSubcommands: true, helpWidth: 60 });
+
+if (process.argv.length === 2) program.outputHelp();
+else program.parse(process.argv);

package/docs/README-CN.md

@@ -0,0 +1,10 @@
+# KnowFlow 中文文档入口
+
+完整、持续维护的中文项目说明已迁移到仓库根目录的 [README.zh-CN.md](../README.zh-CN.md)。
+
+更多专题文档：
+
+- [方法论：LLM Wiki](methodology/llm-wiki-methodology.md)
+- [系统架构](architecture/system-architecture.md)
+- [数据模型](reference/data-model.md)
+- [贡献指南](contributing.md)

package/docs/architecture/system-architecture.md

@@ -0,0 +1,150 @@
+# KnowFlow 系统架构
+
+## 整体流程
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        输入层 (Input)                         │
+│  URL │ Tweet │ PDF │ WeChat │ YouTube │ Bookmark            │
+└──────────────────────┬──────────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Step 1: Fetch (摄取)                      │
+│  自动识别来源类型 → 全文提取 → 存入 raw/                     │
+│  scripts/ingest.sh → fetcher 模块                            │
+└──────────────────────┬──────────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Step 2: Extract (提取)                      │
+│  LLM 分析内容 → 提取实体/概念/关系 → JSON Schema 约束输出    │
+│  scripts/batch-ingest.cjs → extractor 模块                  │
+└──────────────────────┬──────────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Step 3: Compile (编译)                      │
+│  用模板渲染 Wiki 页面 → 自动交叉链接 → 写入 wiki/             │
+│  templates/{entity,concept,comparison,source}.md            │
+└──────────────────────┬──────────────────────────────────────┘
+                       ▼
+          ┌────────────┴────────────┐
+          ▼                         ▼
+┌─────────────────────┐  ┌─────────────────────────────────┐
+│  Step 4: Graph       │  │  Step 5: Vector                │
+│  知识图谱构建         │  │  向量索引构建                   │
+│  scripts/graph_      │  │  scripts/vector-store.mjs       │
+│  builder.py          │  │  scripts/vector_store.py        │
+│  → graph.json        │  │  → vector-store.mjs-data/      │
+│  → graph.html       │  │                               │
+└─────────────────────┘  └─────────────────────────────────┘
+```
+
+## 目录结构详解
+
+```
+knowflow/
+├── bin/
+│   └── knowflow.js          # CLI 入口，命令路由
+├── scripts/
+│   ├── ingest.sh            # 单条 URL/文本采集（fetch→raw）
+│   ├── batch-ingest.cjs     # 批量处理原始素材
+│   ├── enrich-wiki.js       # Wiki 后处理（链接补全、摘要生成）
+│   ├── graph_builder.py     # 从 Wiki 页面构建知识图谱
+│   ├── graph_relation_labeler.py  # LLM 分析关系类型
+│   ├── vector-store.mjs     # 向量索引（Embedding + 存储）
+│   ├── vector_store.py      # 向量检索接口
+│   ├── pipeline.sh          # 5 步全自动化管线
+│   ├── bookmark_sync.sh     # X/Twitter 书签同步
+│   ├── wechat_sync.sh       # 微信公众号文章同步
+│   └── wiki-health.sh       # 健康检查（断链、空页面、孤立页）
+├── templates/
+│   ├── entity.md            # 实体页模板（人物/公司/项目）
+│   ├── concept.md           # 概念页模板（方法论/技术概念）
+│   ├── comparison.md        # 对比页模板（A vs B）
+│   └── source.md            # 来源页模板（原始内容摘要）
+├── docs/
+│   ├── methodology/         # 方法论文档
+│   ├── architecture/        # 架构文档（本文件）
+│   └── reference/           # 参考文档
+├── articles/               # 博客系列文章
+├── .knowflowrc.example      # 配置示例
+└── package.json
+```
+
+## 数据流
+
+### 单条 URL 的完整生命周期
+
+```
+1. 用户执行: knowflow ingest https://example.com/article
+
+2. Fetch 阶段:
+   - 检测 URL 类型（普通网页 / Twitter / YouTube / PDF）
+   - 选择对应的 fetcher
+   - 下载全文，提取标题、作者、日期等元数据
+   - 存储为 raw/{timestamp}-{slug}.md
+
+3. Extract 阶段:
+   - 读取 raw 文件
+   - 调用 LLM（带 JSON Schema 约束）提取:
+     {
+       "entities": [{name, type, description, mentions}],
+       "concepts": [{name, definition, related}],
+       "summary": "...",
+       "key_points": ["..."]
+     }
+   - 结果存入临时变量
+
+4. Compile 阶段:
+   - 根据提取结果选择模板:
+     - 主要实体 → entity.md
+     - 新概念 → concept.md
+     - 与已有实体对比 → comparison.md
+     - 来源记录 → source.md
+   - 渲染 Markdown，自动添加 [[WikiLink]] 语法
+   - 扫描已有 Wiki 页面，添加反向链接
+
+5. Graph 阶段:
+   - 解析所有 Wiki 页面中的 `[[link]]` 语法
+   - 构建节点和边
+   - 调用 LLM 标注关系类型（"created_by"、"uses"、"competes_with" 等）
+   - 输出 graph.json + graph.html
+
+6. Vector 阶段:
+   - 对每个 Wiki 页面做 Embedding
+   - 存入本地向量索引
+   - 支持语义搜索查询
+```
+
+## 关键设计决策
+
+### 为什么用 JSON Schema 约束 LLM 输出？
+
+LLM 的自由输出格式不可预测。JSON Schema 就像合同——告诉 AI "我只要你这种格式的输出"。代码里加了 fallback：解析失败重试一次，再失败就当纯文本存入。
+
+### 为什么 Wiki 用 Markdown 而不是数据库？
+
+- **人类可读** — 直接用编辑器打开就能看
+- **版本控制友好** — Git 可以追踪每次变更
+- **AI 友好** — LLM 天然擅长生成和理解 Markdown
+- **可移植** — 不依赖任何数据库服务
+
+### 为什么图谱和向量都要？
+
+| 能力 | 知识图谱 | 向量检索 |
+|------|---------|---------|
+| 精确查找 | ✅ 按实体名/关系查 | ❌ |
+| 语义搜索 | ❌ | ✅ "类似 XXX 的内容" |
+| 发现关联 | ✅ A→B→C 的路径 | ❌ |
+| 模糊匹配 | ❌ | ✅ 语义相近即可 |
+
+两者互补，缺一不可。
+
+## 技术栈
+
+| 组件 | 技术 | 原因 |
+|------|------|------|
+| CLI 运行时 | Node.js | npm 生态，开发者熟悉 |
+| 内容提取 | 智谱 AI (GLM-Flash) | 性价比高，中文优秀 |
+| 知识图谱 | Python + vis.js | 图算法成熟，可视化好 |
+| 向量索引 | 本地 Embedding | 无需外部服务，隐私安全 |
+| 数据存储 | 文件系统 (Markdown) | 零依赖，Git 友好 |

package/docs/contributing.md

@@ -0,0 +1,131 @@
+# KnowFlow 贡献指南
+
+[English contribution guide](../CONTRIBUTING.md) | 简体中文
+
+> 欢迎贡献！无论是代码、文档、Wiki 模板还是博客文章。
+
+## 给人类贡献者的指南
+
+### 报 Bug
+
+在 GitHub Issues 提交，请包含：
+1. **复现步骤** — 怎么操作的
+2. **期望行为** — 你期望发生什么
+3. **实际行为** — 实际发生了什么
+4. **环境信息** — Node.js 版本、OS、`.knowflowrc` 关键配置（脱敏）
+
+### 提 PR
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/amazing`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送分支 (`git push origin feature/amazing`)
+5. 创建 Pull Request
+
+### 代码规范
+
+- **Shell 脚本**: `set -euo pipefail`，用 `${var:+"${arr[@]}"}` 处理空数组
+- **Node.js**: ES Modules (`import/export`)，不用 CommonJS
+- **Python**: 类型注解，Python 3.10+
+- **Commit message**: 用 Conventional Commits (`feat:`, `fix:`, `docs:` 等)
+
+## 给 AI 助手的指南
+
+如果你是 AI 助手（Claude、GPT、Cursor 等），以下信息帮你快速理解项目：
+
+### 项目本质
+
+KnowFlow 是一个 **知识编译器**，不是搜索工具。核心价值链：
+
+```
+原始内容 → [AI提取] → 结构化Wiki → [关联] → 知识图谱 + 向量索引
+```
+
+### 关键文件速查
+
+| 你想做什么 | 看哪个文件 |
+|-----------|----------|
+| 理解整体架构 | `docs/architecture/system-architecture.md` |
+| 理解方法论 | `docs/methodology/llm-wiki-methodology.md` |
+| 理解数据模型 | `docs/reference/data-model.md` |
+| 修改提取逻辑 | `scripts/batch-ingest.cjs` |
+| 修改模板 | `templates/*.md` |
+| 修改 CLI 命令 | `bin/knowflow.js` |
+| 修改图谱构建 | `scripts/graph_builder.py` |
+| 修改向量检索 | `scripts/vector-store.mjs` |
+
+### 常见贡献场景
+
+#### 1. 新增一个 Fetcher（支持新的内容来源）
+
+在 `ingest.sh` 的 URL 类型检测逻辑中添加新分支：
+```bash
+# 示例：支持 Reddit
+if [[ "$url" == *reddit.com* ]]; then
+  fetch_reddit "$url" > "$raw_file"
+fi
+```
+
+#### 2. 改进提取 Prompt
+
+在 `batch-ingest.cjs` 中调整提取逻辑时，注意保持现有 Markdown 数据的向后兼容。
+
+#### 3. 新增 Wiki 模板
+
+在 `templates/` 创建新 `.md` 文件，然后在 `enrich-wiki.js` 中注册。
+
+#### 4. 优化知识图谱关系标注
+
+`graph_relation_labeler.py` 控制 LLM 如何标注边的类型。可以扩展关系类型列表。
+
+### 测试你的改动
+
+```bash
+# 单 URL 原始采集测试（只写入 raw，不生成 Wiki 页面）
+knowflow ingest https://example.com/test-article
+
+# 检查输出
+ls raw/web/       # 原始素材是否生成？
+
+# 手动或通过 Agent 整理 Wiki 页面后再生成图谱
+knowflow graph --no-open
+cat graph/graph.json
+
+# 健康检查
+knowflow health
+```
+
+## Wiki 页面贡献
+
+除了代码，你也可以通过**写 Wiki 页面**来贡献！
+
+### 方式一：Ingest 高质量内容
+
+最简单的贡献方式 — 找到好的 URL，跑一次 ingest：
+
+```bash
+# 找一篇关于 AI/开发/知识管理的好文章
+knowflow ingest https://awesome-article.example.com/post
+```
+
+### 方式二：直接写 Wiki 页面
+
+在 `wiki/` 目录下创建 `.md` 文件，遵循[数据模型](./reference/data-model.md)中的格式。记得用 `[[Link]]` 语法链接到其他页面。
+
+## 文档结构
+
+```
+docs/
+├── methodology/
+│   └── llm-wiki-methodology.md   # 核心理念（必读）
+├── architecture/
+│   └── system-architecture.md     # 技术架构（开发者必读）
+└── reference/
+    └── data-model.md              # 数据格式（贡献者参考）
+```
+
+这些文档不仅是给人看的——它们也是**项目的自文档化知识库**。任何 LLM 读取这个仓库后，都应该能理解 KnowFlow 是什么、怎么工作、如何参与贡献。
+
+## 许可证
+
+MIT License — 随意使用、修改、分发。