@jerryjiao/knowflow 0.3.0

package/scripts/vector_store.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""
+KnowFlow Vector Store — 基于智谱 embedding-3 的语义检索
+用法:
+  python3 vector_store.py build    # 对所有 wiki 页面建索引
+  python3 vector_store.py query "AI Agent"  # 语义查询
+  python3 vector_store.py stats   # 查看索引状态
+"""
+import os, sys, json, glob, hashlib
+from pathlib import Path
+
+PROJECT_ROOT = Path(os.environ.get("KNOWFLOW_ROOT", Path(__file__).resolve().parent.parent))
+WIKI_DIR = Path(os.environ.get("KNOWFLOW_WIKI_DIR", PROJECT_ROOT / "wiki")).resolve()
+INDEX_FILE = WIKI_DIR / ".vector-index.json"
+EMBED_CACHE = WIKI_DIR / ".embed-cache.json"
+
+# ====== Embedding ======
+def get_embedding(text: str, api_key: str = None) -> list:
+    """调用智谱 embedding-3 API 获取向量"""
+    import urllib.request, urllib.error
+    
+    key = api_key or os.environ.get("ZHIPUAI_API_KEY", "")
+    if not key:
+        # 尝试从 openclaw 配置读取
+        cfg_path = Path.home() / ".openclaw" / "config.yaml"
+        if cfg_path.exists():
+            import yaml
+            try:
+                cfg = yaml.safe_load(cfg_path.read_text())
+                key = cfg.get("zhipu", {}).get("apiKey", "") or cfg.get("providers", {}).get("zhipu", {}).get("apiKey", "")
+            except: pass
+    
+    if not key:
+        print("⚠️ 未找到 ZHIPUAI_API_KEY，请设置环境变量或在 .env 中配置")
+        return None
+    
+    url = "https://open.bigmodel.cn/api/paas/v4/embeddings"
+    payload = json.dumps({
+        "model": "embedding-3",
+        "input": text[:8000],  # 截断过长文本
+        "dimensions": 1024
+    }).encode()
+    
+    req = urllib.request.Request(url, data=payload, headers={
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {key}"
+    })
+    
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = json.loads(resp.read())
+            return data["data"][0]["embedding"]
+    except Exception as e:
+        print(f"⚠️ Embedding API 错误: {e}")
+        return None
+
+# ====== 文件扫描 ======
+def scan_wiki_files() -> list:
+    """扫描所有 wiki markdown 文件，返回 (path, content, meta) 列表"""
+    files = []
+    for md_file in sorted(WIKI_DIR.rglob("*.md")):
+        # 跳过隐藏文件和特殊文件
+        if any(p.startswith(".") for p in md_file.parts):
+            continue
+        
+        text = md_file.read_text(encoding="utf-8", errors="ignore")
+        if len(text.strip()) < 50:  # 跳过太短的文件
+            continue
+        
+        # 提取 frontmatter 之后的正文用于 embedding
+        body = text
+        if text.startswith("---"):
+            parts = text.split("---", 2)
+            if len(parts) >= 3:
+                body = parts[2].strip()
+        
+        # 截取前 2000 字符作为 embedding 内容（标题+摘要+关键内容）
+        embed_text = body[:2000]
+        
+        rel_path = str(md_file.relative_to(WIKI_DIR))
+        files.append({
+            "path": rel_path,
+            "full_path": str(md_file),
+            "title": md_file.stem,
+            "body": body,
+            "embed_text": embed_text,
+            "size": len(text),
+            "category": rel_path.split("/")[0] if "/" in rel_path else "root"
+        })
+    
+    return files
+
+# ====== Build Index ======
+def build_index(force=False):
+    """构建/更新向量索引"""
+    print(f"📚 扫描 Wiki 目录: {WIKI_DIR}")
+    files = scan_wiki_files()
+    print(f"📊 找到 {len(files)} 个页面")
+    
+    # 加载已有缓存
+    cache = {}
+    if EMBED_CACHE.exists() and not force:
+        cache = json.loads(EMBED_CACHE.read_text())
+    
+    index = []
+    new_count = 0
+    cache_count = 0
+    
+    for i, f in enumerate(files):
+        # 用文件路径+大小+修改时间做 hash 判断是否需要重新 embedding
+        file_hash = hashlib.md5(f"{f['path']}:{f['size']}".encode()).hexdigest()
+        
+        if file_hash in cache and not force:
+            index.append({**f, "embedding": cache[file_hash], "_hash": file_hash})
+            cache_count += 1
+        else:
+            print(f"  [{i+1}/{len(files)}] Embedding: {f['path']} ...", end=" ", flush=True)
+            emb = get_embedding(f["embed_text"])
+            if emb:
+                f["embedding"] = emb
+                f["_hash"] = file_hash
+                index.append(f)
+                cache[file_hash] = emb
+                new_count += 1
+                print("✅")
+            else:
+                print("❌ 跳过")
+        
+        # 每 10 个保存一次缓存
+        if (i + 1) % 20 == 0:
+            EMBED_CACHE.write_text(json.dumps(cache))
+    
+    # 保存最终结果
+    EMBED_CACHE.write_text(json.dumps(cache))
+    INDEX_FILE.write_text(json.dumps(index, ensure_ascii=False, indent=2))
+    
+    print(f"\n✅ 索引构建完成!")
+    print(f"  新增: {new_count} | 缓存: {cache_count} | 总计: {len(index)}")
+    print(f"  索引文件: {INDEX_FILE} ({INDEX_FILE.stat().st_size / 1024:.1f} KB)")
+    print(f"  缓存文件: {EMBED_CACHE} ({EMBED_CACHE.stat().st_size / 1024:.1f} KB)")
+
+# ====== Query ======
+def query(text: str, top_k: int = 5, category_filter: str = None) -> list:
+    """语义查询，返回最相关的页面"""
+    if not INDEX_FILE.exists():
+        print("❌ 索引不存在，请先运行: python3 vector_store.py build")
+        return []
+    
+    index = json.loads(INDEX_FILE.read_text())
+    if not index:
+        print("❌ 索引为空")
+        return []
+    
+    print(f"🔍 查询: \"{text}\"")
+    query_emb = get_embedding(text)
+    if not query_emb:
+        return []
+    
+    # 余弦相似度
+    def cosine_similarity(a, b):
+        dot = sum(x * y for x, y in zip(a, b))
+        norm_a = sum(x * x for x in a) ** 0.5
+        norm_b = sum(x * x for x in b) ** 0.5
+        if norm_a == 0 or norm_b == 0: return 0
+        return dot / (norm_a * norm_b)
+    
+    results = []
+    for item in index:
+        if category_filter and item.get("category") != category_filter:
+            continue
+        score = cosine_similarity(query_emb, item["embedding"])
+        results.append({**item, "score": round(score, 4)})
+    
+    results.sort(key=lambda x: x["score"], reverse=True)
+    top = results[:top_k]
+    
+    print(f"\n📋 Top {len(top)} 结果:\n")
+    for r in top:
+        cat_emoji = {"sources":"📄","entities":"🏷️","concepts":"💡","topics":"📑","root":"📁"}.get(r.get("category"), "📄")
+        print(f"  {cat_emoji} [{r['score']:.3f}] {r['path']}")
+        print(f"     ({r['size']} chars | {r['category']})")
+        # 显示匹配到的关键词上下文
+        body_preview = r.get("body", "")[:200].replace("\n", " ")
+        print(f"     预览: {body_preview}...")
+        print()
+    
+    return top
+
+# ====== Stats ======
+def show_stats():
+    """显示索引统计"""
+    if not INDEX_FILE.exists():
+        print("❌ 索引不存在"); return
+    
+    index = json.loads(INDEX_FILE.read_text())
+    categories = {}
+    for item in index:
+        c = item.get("category", "root")
+        categories[c] = categories.get(c, 0) + 1
+    
+    print(f"📊 Vector Store 统计:")
+    print(f"  总页面数: {len(index)}")
+    print(f"  索引大小: {INDEX_FILE.stat().st_size / 1024:.1f} KB")
+    print(f"  缓存大小: {EMBED_CACHE.stat().st_size / 1024:.1f} KB" if EMBED_CACHE.exists() else "")
+    print(f"\n  按分类:")
+    for c, cnt in sorted(categories.items(), key=lambda x: -x[1]):
+        emoji = {"sources":"📄","entities":"🏷️","concepts":"💡","topics":"📑","root":"📁"}.get(c, "📁")
+        print(f"    {emoji} {c}: {cnt}")
+
+# ====== Main ======
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "stats"
+    
+    if cmd == "build":
+        build_index("--force" in sys.argv)
+    elif cmd == "query":
+        q = " ".join(sys.argv[2:])
+        if not q:
+            print("用法: python3 vector_store.py query \"搜索内容\"")
+        else:
+            query(q)
+    elif cmd == "stats":
+        show_stats()
+    else:
+        print(__doc__)

package/scripts/wechat_sync.sh

@@ -0,0 +1,199 @@
+#!/bin/bash
+# jerry-wiki wechat article sync
+# Searches for WeChat articles via Brave Search and ingests them
+# Usage: bash scripts/wechat_sync.sh [--dry-run]
+#
+# Config: scripts/.wechat-accounts.json (search queries + accounts)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WIKI_ROOT="${KNOWFLOW_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+RAW_BASE="${KNOWFLOW_RAW_DIR:-$WIKI_ROOT/raw}"
+RAW_DIR="$RAW_BASE/wechat"
+STATE_FILE="$WIKI_ROOT/.wechat-state.json"
+TIMESTAMP=$(date +%Y-%m-%d-%H%M)
+ACCOUNTS_FILE="$SCRIPT_DIR/.wechat-accounts.json"
+
+mkdir -p "$RAW_DIR"
+
+# ── Load config ────────────────────────────────────────
+if [ ! -f "$ACCOUNTS_FILE" ]; then
+  cat > "$ACCOUNTS_FILE" << 'EOF'
+{
+  "accounts": [
+    {"name": "宝玉", "keywords": ["宝玉", "dotey", "Claude Code"]},
+    {"name": "科技爱好者", "keywords": ["AI 工具", "AI 编程", "开源"]}
+  ],
+  "searchQueries": [
+    "AI编程工具 site:mp.weixin.qq.com",
+    "Claude Code 教程 site:mp.weixin.qq.com",
+    "AI Agent 开发 site:mp.weixin.qq.com",
+    "OpenClaw 使用 site:mp.weixin.qq.com"
+  ],
+  "maxResults": 10,
+  "maxAgeDays": 7
+}
+EOF
+  echo "📝 Created default $ACCOUNTS_FILE (edit to customize)"
+fi
+
+CONFIG=$(cat "$ACCOUNTS_FILE")
+
+# Read queries into temp file (handle spaces in queries)
+TMP_QUERIES=$(mktemp)
+echo "$CONFIG" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for q in data.get('searchQueries', []):
+    print(q)
+" > "$TMP_QUERIES" 2>/dev/null || true
+
+MAX_RESULTS=$(echo "$CONFIG" | python3 -c "import json,sys; print(json.load(sys.stdin).get('maxResults',5))" 2>/dev/null || echo 5)
+
+if [ ! -s "$TMP_QUERIES" ]; then
+  rm -f "$TMP_QUERIES"
+  echo "❌ No search queries configured in $ACCOUNTS_FILE"
+  exit 1
+fi
+
+DRY_RUN=false
+case "${1:-}" in --dry-run) DRY_RUN=true ;; esac
+
+# ── State tracking ─────────────────────────────────────
+SEEN_URLS=$(python3 -c "
+import json
+state = {}
+try:
+    with open('$STATE_FILE') as f:
+        state = json.load(f)
+except: pass
+for url in state.get('seenUrls', []):
+    print(url)
+" 2>/dev/null || true)
+
+_TEMP_FILES=("$TMP_QUERIES")
+cleanup() { rm -f "${_TEMP_FILES[@]:-}" 2>/dev/null || true; }
+trap cleanup EXIT INT TERM
+
+# ── Search & Fetch ──────────────────────────────────────
+echo "📱 WeChat Article Sync — $TIMESTAMP"
+echo ""
+
+NEW_COUNT=0
+TMPJSON=$(mktemp)
+_TEMP_FILES+=("$TMPJSON")
+
+while IFS= read -r query; do
+  [ -z "$query" ] && continue
+  echo "🔍 Searching: $query"
+
+  # Try brave-search first (reliable), fallback to exa
+  OK=false
+  if command -v mcporter &>/dev/null; then
+    mcporter call 'brave-search.brave_web_search' query="$query" count="$MAX_RESULTS" > "$TMPJSON" 2>/dev/null && OK=true
+    if [ "$OK" = false ]; then
+      mcporter call 'exa.web_search_exa' query="$query" numResults="$MAX_RESULTS" includeDomains='["mp.weixin.qq.com"]' > "$TMPJSON" 2>/dev/null && OK=true
+    fi
+  fi
+
+  if [ "$OK" = false ]; then
+    echo "  ⚠️ All search providers failed, skipping query"
+    continue
+  fi
+
+  # Parse results and download new articles
+  # brave-search outputs plain text (Title/Description/URL blocks), exa outputs JSON
+  python3 - "$TMPJSON" "$RAW_DIR" "$TIMESTAMP" "$STATE_FILE" << 'PYEOF'
+import json, sys, os, subprocess, re
+from datetime import datetime
+
+tmpjson, raw_dir, timestamp, state_file = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+
+with open(tmpjson) as f:
+    raw = f.read()
+
+results = []
+
+# Try JSON first (exa format)
+try:
+    start = raw.index('{')
+    end = raw.rindex('}') + 1
+    data = json.loads(raw[start:end])
+    results = data.get('results', []) if isinstance(data, dict) else []
+    if not results and isinstance(data, list):
+        results = data
+except Exception:
+    pass
+
+# Fallback: parse plain text format (brave-search)
+if not results:
+    # Split by "Title: " pattern to find result blocks
+    blocks = re.split(r'(?=^Title:\s)', raw, flags=re.MULTILINE)
+    for block in blocks[1:]:  # Skip header if any
+        title_m = re.search(r'^Title:\s*(.+)', block, re.MULTILINE)
+        url_m = re.search(r'^URL:\s*(https?://\S+)', block, re.MULTILINE)
+        desc_m = re.search(r'^Description:\s*(.+?)(?=^URL:|^Title:|$)', block, re.MULTILINE | re.DOTALL)
+        if url_m:
+            results.append({
+                'url': url_m.group(1).strip(),
+                'title': (title_m.group(1).strip() if title_m else 'unknown'),
+                'description': (desc_m.group(1).strip()[:500] if desc_m else ''),
+            })
+
+if not results:
+    print("  ℹ️ No results")
+    sys.exit(0)
+
+state = {"seenUrls": [], "lastSyncAt": ""}
+if os.path.exists(state_file):
+    try:
+        with open(state_file) as f:
+            state = json.load(f)
+    except: pass
+seen = set(state.get("seenUrls", []))
+
+new_count = 0
+for r in results[:10]:
+    url = r.get("url", "")
+    if not url or url in seen or "mp.weixin.qq.com" not in url:
+        continue
+    
+    title = str(r.get("title", "unknown"))
+    published = str(r.get("publishedDate", ""))[:10]
+    
+    safe_title = re.sub(r'[/\\|:*?<>]', '-', title)[:60]
+    filename = f"{timestamp}-{published}-{safe_title}.md"
+    filepath = os.path.join(str(raw_dir), filename)
+    
+    if os.path.exists(filepath):
+        continue
+    
+    try:
+        result = subprocess.run(
+            ["curl", "-sL", "--max-time", "20", f"https://r.jina.ai/{url}"],
+            capture_output=True, text=True, timeout=25
+        )
+        content = result.stdout.strip()
+        if len(content) < 100:
+            content = f"# {title}\n\n> Source: {url}\n> Published: {published}\n\n{r.get('text', '')[:2000]}"
+        
+        with open(filepath, 'w') as f:
+            f.write(content)
+        seen.add(url)
+        new_count += 1
+        print(f"  + {filename}")
+    except Exception as e:
+        print(f"  ✗ Failed: {title} ({e})")
+
+state["seenUrls"] = list(seen)[-500:]
+state["lastSyncAt"] = datetime.now().isoformat()
+with open(state_file, 'w') as f:
+    json.dump(state, f, indent=2, ensure_ascii=False)
+
+print(f"\n  📊 {new_count} new articles saved")
+PYEOF
+
+done < "$TMP_QUERIES"
+
+echo ""
+echo "✅ WeChat sync complete. Run pipeline.sh to ingest → build."

package/scripts/wiki-auto-fix.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# knowflow wiki-auto-fix — 自动修复 health check 发现的问题
+# Usage: bash scripts/wiki-auto-fix.sh [--wiki-dir <path>] [--dry-run]
+#
+# 在 health check 之前运行，自动：
+#   1. 清理空链接 [[entities/,]] [[concepts/,]]
+#   2. 创建缺失的 entity/concept 文件
+#   3. 补充过小的文件（<100B）
+#   4. 关联孤儿页（添加引用）
+
+set -euo pipefail
+
+# ── Config ──────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+WIKI_ROOT="${KNOWFLOW_ROOT:-${WIKI_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}}"
+WIKI_DIR="${KNOWFLOW_WIKI_DIR:-$WIKI_ROOT/wiki}"
+DRY_RUN=false
+MIN_SIZE=100
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true; shift ;;
+    --wiki-root) WIKI_ROOT="$2"; WIKI_DIR="$WIKI_ROOT/wiki"; shift 2 ;;
+    --wiki-dir) WIKI_DIR="$2"; shift 2 ;;
+    --min-size) MIN_SIZE="$2"; shift 2 ;;
+    *) echo "Unknown: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Portable in-place sed: BSD (macOS) needs -i '' with the backup suffix arg,
+# GNU sed takes the script directly after -i.
+sed_i() {
+  if [[ "$(uname)" == "Darwin" ]]; then
+    sed -i '' "$@"
+  else
+    sed -i "$@"
+  fi
+}
+
+FIXED_LINKS=0
+CREATED_FILES=0
+PADDED_FILES=0
+
+run_cmd() {
+  if $DRY_RUN; then
+    echo "[DRY] $*"
+  else
+    "$@"
+  fi
+}
+
+echo "🔧 Wiki Auto-Fix"
+echo "================"
+
+# ════════════════════════════════════════════════
+# Fix 1: 清理空链接 [[entities/,]] [[concepts/,]]
+# ════════════════════════════════════════════════
+echo ""
+echo "[1/4] 清理空链接..."
+
+while IFS= read -r -d '' file; do
+  if grep -q '\[\[entities\/,\]\]\|\[\[concepts\/,\]\]' "$file" 2>/dev/null; then
+    local_count=$(grep -c '\[\[entities\/,\]\]\|\[\[concepts\/,\]\]' "$file" 2>/dev/null || echo 0)
+    run_cmd sed_i '/\[\[entities\/,\]\]/d' "$file"
+    run_cmd sed_i '/\[\[concepts\/,\]\]/d' "$file"
+    FIXED_LINKS=$((FIXED_LINKS + local_count))
+    rel="${file#$WIKI_DIR/}"
+    echo "  ✏️  $rel (清理 $local_count 个空链接)"
+  fi
+done < <(find "$WIKI_DIR" -name '*.md' -not -path '*/.understand-anything/*' -print0)
+echo "  共清理 $FIXED_LINKS 个空链接"
+
+# ════════════════════════════════════════════════
+# Fix 2: 创建缺失的 entity/concept 文件
+# ════════════════════════════════════════════════
+echo ""
+echo "[2/4] 创建缺失实体/概念文件..."
+
+LINKS_TMP="$(mktemp)"
+while IFS= read -r -d '' file; do
+  grep -o '\[\[entities\/[^]]*\]\]\|\[\[concepts\/[^]]*\]\]' "$file" 2>/dev/null \
+    | sed 's/\[\[//;s/\]\]//' \
+    | sed 's/|.*//' \
+    | grep -v '^[[:space:]]*$' \
+    | awk '!seen[$0]++' >> "$LINKS_TMP" || true
+done < <(find "$WIKI_DIR" -name '*.md' -not -path '*/.understand-anything/*' -print0)
+
+while IFS= read -r link; do
+  [ -z "$link" ] && continue
+  target_file="$WIKI_DIR/${link}.md"
+  if [ ! -f "$target_file" ]; then
+    name=$(basename "$link")
+    display_name=$(echo "$name" | sed 's/-/ /g')
+
+    case "${link%%/*}" in
+      entities) type_label="实体" ;;
+      concepts) type_label="概念" ;;
+      topics)   type_label="主题" ;;
+      *)        type_label="待分类" ;;
+    esac
+
+    run_cmd mkdir -p "$(dirname "$target_file")"
+    # NOTE: redirections run before `run_cmd` is called, so we must not route the
+    # heredoc through run_cmd in dry-run mode — the `>` would truncate/create the
+    # file even when the command itself is skipped. Render to a temp buffer and
+    # write once outside dry-run.
+    content=$(printf '# %s\n\n## 类型\n%s\n\n## 描述\n（由 wiki-auto-fix 自动创建，待补充详细信息）\n' "$display_name" "$type_label")
+    if $DRY_RUN; then
+      echo "[DRY] create $target_file"
+    else
+      printf '%s' "$content" > "$target_file"
+    fi
+    CREATED_FILES=$((CREATED_FILES + 1))
+    echo "  ➕ ${link}.md (${type_label})"
+  fi
+done < "$LINKS_TMP"
+rm -f "$LINKS_TMP"
+echo "  共创建 $CREATED_FILES 个缺失文件"
+
+# ════════════════════════════════════════════════
+# Fix 3: 补充过小文件
+# ════════════════════════════════════════════════
+echo ""
+echo "[3/4] 补充过小文件 (<${MIN_SIZE}B)..."
+
+while IFS= read -r -d '' file; do
+  size=$(wc -c < "$file" | tr -d ' ')
+  rel="${file#$WIKI_DIR/}"
+  name_base=$(basename "$rel" .md)
+
+  case "$rel" in
+    entities/*) suffix="\n\n## 备注\n此页面由 wiki-auto-fix 自动扩充。原始内容仅 ${size} 字节。" ;;
+    concepts/*) suffix="\n\n## 延伸阅读\n此概念页面由 wiki-auto-fix 自动扩充。原始内容仅 ${size} 字节。" ;;
+    topics/*)   suffix="\n\n## 子主题\n此主题页面由 wiki-auto-fix 自动扩充。原始内容仅 ${size} 字节。" ;;
+    *)          suffix="\n\n---\n*此文件由 wiki-auto-fix 标记为过小（原 ${size}B）*" ;;
+  esac
+
+  # Same dry-run caveat as Fix 2: route the write explicitly, never through a
+  # redirection that the shell would apply before run_cmd decides to skip.
+  if $DRY_RUN; then
+    echo "[DRY] pad $rel (+$(printf "$suffix" | wc -c | tr -d ' ') bytes)"
+  else
+    printf '%b%s\n' "$(cat "$file")" "$suffix" > "$file"
+  fi
+  PADDED_FILES=$((PADDED_FILES + 1))
+  echo "  📝 $rel (${size}B → 已补充)"
+done < <(find "$WIKI_DIR" -name '*.md' -not -path '*/.understand-anything/*' -size +0 -size -${MIN_SIZE}c -print0)
+
+echo "  共补充 $PADDED_FILES 个文件"
+
+# ════════════════════════════════════════════════
+# Fix 4: 关联孤儿页（用 Python 避免 bash [[ 冲突）
+# ════════════════════════════════════════════════
+echo ""
+echo "[4/4] 处理孤儿页..."
+
+python3 - "$WIKI_DIR" "$DRY_RUN" << 'PYEOF'
+import os, sys, re
+
+wiki_dir = sys.argv[1]
+dry_run = sys.argv[2].lower() == "true"
+index_path = os.path.join(wiki_dir, "index.md")
+skip_prefixes = ("index.md", "overview.md", "topics.md", "log.md",
+                 ".vector", ".embed", "comparisons/", "sources/")
+
+referenced = set()
+for root, dirs, files in os.walk(wiki_dir):
+    if ".understand-anything" in root:
+        continue
+    for f in files:
+        if not f.endswith(".md"):
+            continue
+        fpath = os.path.join(root, f)
+        try:
+            with open(fpath, "r", errors="replace") as fh:
+                for line in fh:
+                    for m in re.finditer(r'\[\[([^]|]+?)(?:\|[^]]+)?\]\]', line):
+                        target = m.group(1).strip()
+                        if not target:
+                            continue
+                        if target.startswith(("entities/", "concepts/", "topics/")):
+                            tpath = os.path.join(wiki_dir, target + ".md")
+                        elif target.startswith("/"):
+                            tpath = os.path.join(wiki_dir, target.lstrip("/") + ".md")
+                        else:
+                            continue
+                        referenced.add(os.path.normpath(tpath))
+        except Exception:
+            pass
+
+orphan_count = 0
+fixed_count = 0
+for root, dirs, files in os.walk(wiki_dir):
+    if ".understand-anything" in root:
+        continue
+    for f in files:
+        if not f.endswith(".md"):
+            continue
+        rel = os.path.relpath(os.path.join(root, f), wiki_dir)
+        if rel.startswith(skip_prefixes) or rel == "index.md":
+            continue
+        fpath = os.path.join(root, f)
+        if fpath not in referenced and os.path.isfile(fpath):
+            orphan_count += 1
+            name_base = os.path.splitext(f)[0]
+            if os.path.exists(index_path):
+                try:
+                    with open(index_path, "r", errors="replace") as idx:
+                        idx_content = idx.read()
+                    if f"[[{name_base}]]" not in idx_content:
+                        if not dry_run:
+                            with open(index_path, "a") as idx:
+                                idx.write(f"- [[{name_base}]] (orphan auto-linked)\n")
+                        fixed_count += 1
+                        print(f"  🔗 {rel} -> index.md")
+                except Exception as e:
+                    print(f"  WARN: {e}")
+
+print(f"  发现 {orphan_count} 个孤儿页，已关联 {fixed_count} 个")
+PYEOF
+
+# ── Summary ────────────────────────────────────────────
+TOTAL_FIXED=$((FIXED_LINKS + CREATED_FILES + PADDED_FILES))
+
+echo ""
+echo "📊 Auto-Fix Summary"
+echo "-------------------"
+echo "  空链接清理:    $FIXED_LINKS"
+echo "  缺失文件创建: $CREATED_FILES"
+echo "  过小文件补充: $PADDED_FILES"
+echo "  总计修复:     $TOTAL_FIXED"
+
+if $DRY_RUN; then
+  echo ""
+  echo "(DRY RUN — 未实际修改)"
+fi
+
+exit 0