@jerryjiao/knowflow 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,12 +5,37 @@ All notable changes to KnowFlow are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-27
+
 ### Added
 
+- `knowflow index build [--incremental] [--stats]` and `knowflow index stats [--verbose] [--json]`
+  expose the vector index as a first-class CLI surface — no more running
+  `scripts/vector-store.mjs` by hand to build or inspect the semantic index.
+- `knowflow ask <question>` answers questions from retrieved Wiki context with
+  a citation list, promoted from the vector-store script to the CLI.
+- Pluggable embedding providers via the optional `embedding` section of
+  `.knowflowrc`. Built-in presets: `zhipu` (default, unchanged behavior) and
+  `openai`; `custom` points at any OpenAI-compatible endpoint
+  (`baseUrl`, `model`, `apiKeyEnv`, `dims`, `chatModel` all overridable).
+  `knowflow status` now shows the resolved provider and required key env;
+  malformed `embedding` sections fail fast naming the offending field.
 - Bilingual documentation website (Astro + Starlight) under `site/`, deployed to
   GitHub Pages via GitHub Actions. English landing at `/`, Chinese at `/zh/`,
   docs under `/en/` and `/zh/` with browser-language auto-switch.
 
+### Changed
+
+- API-key checks for `query` (and the new index/ask commands) honor the
+  configured provider's key env instead of assuming `ZHIPUAI_API_KEY`.
+- Version assertions in the CLI test suite read `package.json` instead of a
+  hardcoded string.
+
+### Removed
+
+- Dead `scripts/wiki-health.py` and `scripts/vector_store.py` superseded by the
+  shell/Node implementations the CLI already invokes.
+
 ## [0.3.0] - 2026-08-18
 
 ### Added
@@ -36,8 +61,7 @@ All notable changes to KnowFlow are documented here. This project follows
 
 ### Changed
 
-- Both READMEs make the source checkout the primary install path until the
-  npm package is published, instead of an `npx` command that 404s.
+- Both READMEs use `npm install -g @jerryjiao/knowflow` as the primary install path, with the source checkout as an alternative.
 
 ## [0.2.1] - 2026-08-10
 

package/README.md

@@ -79,7 +79,10 @@ KnowFlow is inspired by [Andrej Karpathy's LLM Wiki](https://karpathy.github.io/
 | `knowflow health` | Check broken links, small files, and isolated pages |
 | `knowflow tags` | Build `tag/<name>.md` hub pages from `[[tag/<name>]]` links |
 | `knowflow status` | Show raw, Wiki, graph, vector-index, and API-key status |
-| `knowflow query <text>` | Query an existing vector index |
+| `knowflow index build [--incremental]` | Build the vector index for semantic search (incremental skips unchanged pages) |
+| `knowflow index stats [--verbose] [--json]` | Report index coverage, cache, and token estimates |
+| `knowflow query <text>` | Query an existing vector index (hybrid vector + keyword ranking) |
+| `knowflow ask <question>` | Answer a question from retrieved Wiki context, with citations |
 
 KnowFlow searches upward from the current directory for the nearest `.knowflowrc`, so commands also work inside project subdirectories.
 
@@ -133,19 +136,39 @@ my-wiki/
 
 `health.excludeOrphanDirs` lists directories whose pages are expected to be unreferenced (daily-sync feeds, inboxes) and should not count as isolated pages. `knowflow tags` regenerates every hub page under `wiki/tag/`, so re-running it after new tagged pages arrive is safe and idempotent.
 
-Graph generation, health checks, capture, and status do not require an API key. Semantic search requires `ZHIPUAI_API_KEY` in the project environment or a project-root `.env` file:
+Graph generation, health checks, capture, and status do not require an API key. Semantic search (`index build`, `query`, `ask`) needs an embedding-provider key in the project environment or a project-root `.env` file. The default provider is Zhipu:
 
 ```bash
 ZHIPUAI_API_KEY=your-key-here
 ```
 
-The current CLI can query an existing vector index but does not yet expose a standalone `index` command. See [Current limitations](#current-limitations) before relying on search.
+The embedding provider is pluggable via the optional `embedding` section of `.knowflowrc`. Switch to OpenAI, or point at any OpenAI-compatible endpoint:
+
+```json
+{
+  "embedding": { "provider": "openai" }
+}
+```
+
+```json
+{
+  "embedding": {
+    "provider": "custom",
+    "baseUrl": "https://your-relay.example.com/v1",
+    "model": "your-embedding-model",
+    "apiKeyEnv": "RELAY_API_KEY",
+    "chatModel": "your-chat-model"
+  }
+}
+```
+
+Presets (`zhipu`, `openai`) fill in endpoint, model, and key-env defaults; every field can be overridden individually. `chatModel` backs `knowflow ask`. Malformed `embedding` sections fail fast with the offending field named.
 
 ## Current limitations
 
 - `ingest` captures raw material; structured Wiki synthesis is a separate human or agent step.
 - URL capture uses Jina Reader. YouTube and some logged-in platforms may also require `yt-dlp` or an authenticated browser workflow.
-- `query` needs a prebuilt vector index and a [Zhipu AI API key](https://open.bigmodel.cn/). Until an `index` CLI command is added, advanced users can run `node <knowflow-install>/scripts/vector-store.mjs build`.
+- `query` / `ask` need a vector index built with `knowflow index build` and a [Zhipu AI](https://open.bigmodel.cn/) (default) or other embedding-provider API key.
 - `bookmark_sync.sh` depends on the optional third-party `ft` command.
 - Generated graph HTML loads vis-network from a CDN when opened.
 
@@ -154,9 +177,9 @@ The current CLI can query an existing vector index but does not yet expose a sta
 - [x] Standalone project initialization and portable paths
 - [x] Raw URL/text capture, Wiki health checks, and interactive graphs
 - [x] CLI tests and CI across supported Node.js versions
+- [x] `knowflow index` and pluggable embedding providers
 - [ ] A first-class agent workflow from raw capture to reviewed Wiki pages
 - [ ] Incremental ingestion and duplicate-source detection
-- [ ] `knowflow index` and pluggable embedding providers
 - [ ] Extractor/plugin system and a local Web UI
 
 Ideas and focused pull requests are welcome. Start with the [contribution guide](CONTRIBUTING.md), run the [text-to-graph example](examples/quickstart.md), or propose a use case in [GitHub Issues](https://github.com/jerryjiao/knowflow/issues).

package/README.zh-CN.md

@@ -78,7 +78,10 @@ KnowFlow 的灵感来自 [Andrej Karpathy 的 LLM Wiki](https://karpathy.github.
 | `knowflow health` | 检查断链、小文件和孤立页面 |
 | `knowflow tags` | 根据 `[[tag/<名称>]]` 链接生成 `tag/<名称>.md` 聚合页 |
 | `knowflow status` | 显示原始素材、Wiki、图谱、向量索引和 API Key 状态 |
-| `knowflow query <text>` | 查询已有向量索引 |
+| `knowflow index build [--incremental]` | 构建语义检索的向量索引（`--incremental` 跳过未变化页面） |
+| `knowflow index stats [--verbose] [--json]` | 查看索引覆盖率、缓存与 token 估算 |
+| `knowflow query <text>` | 查询已有向量索引（向量 + 关键词混合排序） |
+| `knowflow ask <question>` | 基于检索到的 Wiki 上下文回答问题，附引用来源 |
 
 KnowFlow 会从当前目录向上查找最近的 `.knowflowrc`，因此也可以在项目子目录中运行命令。
 
@@ -132,19 +135,39 @@ my-wiki/
 
 `health.excludeOrphanDirs` 列出预期不会被引用的目录（每日同步流水页、收件箱等），其中的页面不计入孤立页面。`knowflow tags` 每次都会全量重建 `wiki/tag/` 下的聚合页，新增带标签页面后重跑即可，幂等安全。
 
-图谱生成、健康检查、内容采集和状态查看均不需要 API Key。语义检索需要在项目环境变量或项目根目录 `.env` 中设置 `ZHIPUAI_API_KEY`：
+图谱生成、健康检查、内容采集和状态查看均不需要 API Key。语义检索（`index build`、`query`、`ask`）需要在项目环境变量或项目根目录 `.env` 中配置 embedding 提供商的 Key，默认提供商为智谱：
 
 ```bash
 ZHIPUAI_API_KEY=your-key-here
 ```
 
-当前 CLI 可以查询已有向量索引，但尚未提供独立的 `index` 命令。依赖搜索功能前，请先阅读[当前限制](#当前限制)。
+Embedding 提供商可通过 `.knowflowrc` 的可选 `embedding` 节插拔。切换到 OpenAI，或指向任意 OpenAI 兼容端点：
+
+```json
+{
+  "embedding": { "provider": "openai" }
+}
+```
+
+```json
+{
+  "embedding": {
+    "provider": "custom",
+    "baseUrl": "https://your-relay.example.com/v1",
+    "model": "your-embedding-model",
+    "apiKeyEnv": "RELAY_API_KEY",
+    "chatModel": "your-chat-model"
+  }
+}
+```
+
+内置预设（`zhipu`、`openai`）会填好端点、模型与 Key 环境变量名，所有字段均可单独覆盖；`chatModel` 供 `knowflow ask` 使用。`embedding` 节写错时会立刻报错并指出问题字段。
 
 ## 当前限制
 
 - `ingest` 只采集原始素材；将其提炼为结构化 Wiki 是独立的人工或 Agent 步骤。
 - URL 采集依赖 Jina Reader；YouTube 和部分需要登录的平台可能还需要 `yt-dlp` 或带登录态的浏览器工作流。
-- `query` 需要预先构建的向量索引和[智谱 AI API Key](https://open.bigmodel.cn/)。在加入 `index` 命令前，高级用户可运行 `node <knowflow-install>/scripts/vector-store.mjs build`。
+- `query` / `ask` 需要先运行 `knowflow index build` 构建向量索引，并配置[智谱 AI](https://open.bigmodel.cn/)（默认）或其他 embedding 提供商的 API Key。
 - `bookmark_sync.sh` 依赖可选的第三方 `ft` 命令。
 - 生成的图谱 HTML 打开时会从 CDN 加载 vis-network。
 
@@ -153,9 +176,9 @@ ZHIPUAI_API_KEY=your-key-here
 - [x] 独立项目初始化和可移植路径
 - [x] URL / 文本原始采集、Wiki 健康检查和交互式图谱
 - [x] CLI 自动化测试与多 Node.js 版本 CI
+- [x] `knowflow index` 与可插拔嵌入提供商
 - [ ] 从原始素材到已审核 Wiki 页面的一等 Agent 工作流
 - [ ] 增量采集和重复来源检测
-- [ ] `knowflow index` 与可插拔嵌入提供商
 - [ ] 提取器 / 插件系统和本地 Web UI
 
 欢迎提交想法和范围清晰的 PR。你可以先阅读[贡献指南](CONTRIBUTING.md)、运行[从文本到图谱的示例](examples/quickstart.md)，或在 [GitHub Issues](https://github.com/jerryjiao/knowflow/issues) 中提出使用场景。

package/bin/knowflow.js

@@ -14,6 +14,7 @@ import {
 } from 'node:fs';
 import { dirname, join, parse, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveEmbeddingConfig } from '../scripts/embedding-config.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const SCRIPTS = join(PACKAGE_ROOT, 'scripts');
@@ -51,6 +52,7 @@ function loadProject(start = process.cwd()) {
     wiki: { ...DEFAULT_CONFIG.wiki, ...userConfig.wiki },
     graph: { ...DEFAULT_CONFIG.graph, ...userConfig.graph },
     health: { ...DEFAULT_CONFIG.health, ...userConfig.health },
+    embedding: userConfig.embedding ?? {},
   };
   const pathValue = (value, label) => {
     if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} 必须是非空路径`);
@@ -120,17 +122,38 @@ function countLines(dir) {
   return lines;
 }
 
-function hasApiKey(project) {
-  if (process.env.ZHIPUAI_API_KEY) return true;
+function hasApiKey(project, apiKeyEnv = 'ZHIPUAI_API_KEY') {
+  if (process.env[apiKeyEnv]) return true;
   try {
     return readFileSync(join(project.root, '.env'), 'utf8')
       .split(/\r?\n/)
-      .some(line => /^\s*ZHIPUAI_API_KEY\s*=\s*[^$\s]/.test(line));
+      .some(line => line.startsWith(apiKeyEnv) && /^\s*=\s*[^$\s]/.test(line.slice(apiKeyEnv.length)));
   } catch {
     return false;
   }
 }
 
+// Resolves the embedding provider from project config; returns null (and sets
+// the exit code) when the user's `embedding` section is malformed.
+function embeddingFor(project) {
+  try {
+    return resolveEmbeddingConfig(project.config.embedding);
+  } catch (error) {
+    console.error(chalk.red('❌ embedding 配置错误:'), error.message);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function requireApiKey(project, embedding, action) {
+  if (!hasApiKey(project, embedding.apiKeyEnv)) {
+    console.error(chalk.yellow(`⚠️  未检测到 ${embedding.apiKeyEnv}（embedding.provider=${embedding.provider}），请在项目 .env 或环境变量中配置后再${action}。`));
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
 function initialise(directory) {
   const root = resolve(directory);
   mkdirSync(root, { recursive: true });
@@ -221,11 +244,9 @@ program
   }, 5)
   .action((text, opts) => {
     const project = loadProject();
-    if (!hasApiKey(project)) {
-      console.error(chalk.yellow('⚠️  未检测到 ZHIPUAI_API_KEY，请在项目 .env 或环境变量中配置。'));
-      process.exitCode = 1;
-      return;
-    }
+    const embedding = embeddingFor(project);
+    if (!embedding) return;
+    if (!requireApiKey(project, embedding, '检索')) return;
     try {
       run(process.execPath, [join(SCRIPTS, 'vector-store.mjs'), 'query', text, '--top', String(opts.top)], {
         cwd: project.root,
@@ -306,6 +327,79 @@ program
     }
   });
 
+const index = program
+  .command('index')
+  .description('向量索引管理（语义检索的数据底座，provider 可在 .knowflowrc 的 embedding 节配置）')
+  .action(() => index.help());
+
+index
+  .command('build')
+  .description('构建向量索引（默认全量；--incremental 只处理新增/修改文件）')
+  .option('-i, --incremental', '增量构建，跳过未变化文件')
+  .option('--stats', '构建完成后显示索引统计')
+  .action(opts => {
+    const project = loadProject();
+    const embedding = embeddingFor(project);
+    if (!embedding) return;
+    if (!requireApiKey(project, embedding, '构建索引')) return;
+    console.log(chalk.blue('🧱 构建向量索引...'));
+    try {
+      run(process.execPath, [
+        join(SCRIPTS, 'vector-store.mjs'), 'build',
+        ...(opts.incremental ? ['--incremental'] : []),
+        ...(opts.stats ? ['--stats'] : []),
+      ], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+      console.log(chalk.green('✅ 索引构建完成！'));
+    } catch (error) {
+      console.error(chalk.red('❌ 索引构建失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+index
+  .command('stats')
+  .description('查看索引统计（页数 / 向量覆盖率 / 缓存 / token 估算）')
+  .option('-v, --verbose', '显示 per-file 明细表')
+  .option('--json', 'JSON 结构化输出')
+  .action(opts => {
+    const project = loadProject();
+    try {
+      run(process.execPath, [
+        join(SCRIPTS, 'vector-store.mjs'), 'stats',
+        ...(opts.verbose ? ['--verbose'] : []),
+        ...(opts.json ? ['--json'] : []),
+      ], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+    } catch (error) {
+      console.error(chalk.red('❌ 统计失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command('ask <question>')
+  .description('基于知识库检索上下文回答问题（附引用来源，需已构建索引）')
+  .action(question => {
+    const project = loadProject();
+    const embedding = embeddingFor(project);
+    if (!embedding) return;
+    if (!requireApiKey(project, embedding, '提问')) return;
+    try {
+      run(process.execPath, [join(SCRIPTS, 'vector-store.mjs'), 'ask', question], {
+        cwd: project.root,
+        env: projectEnv(project),
+      });
+    } catch (error) {
+      console.error(chalk.red('❌ 问答失败:'), error.message);
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('health')
   .description('Wiki 健康检查（断链、空文件、孤立页面）')
@@ -350,13 +444,18 @@ program
         vectorStatus = chalk.green(`✅ ${pages.length} 页，${embedded} 页已向量化`);
       } catch { vectorStatus = chalk.yellow('⚠️ 索引损坏'); }
     }
+    const embedding = embeddingFor(project);
+    const keyStatus = embedding
+      ? (hasApiKey(project, embedding.apiKeyEnv) ? `✅ 已配置 (${embedding.apiKeyEnv})` : `❌ 未配置（需要 ${embedding.apiKeyEnv}）`)
+      : '❌ embedding 配置错误';
     console.log(`\n${chalk.bold.cyan('  📊 KnowFlow 状态概览')}`);
     console.log(`  Wiki 文章数:  ${articleCount} 篇`);
     console.log(`  总行数:       ${lineCount} 行`);
     console.log(`  原始素材:     ${rawCount} 个`);
     console.log(`  向量索引:     ${vectorStatus}`);
+    console.log(`  Embedding:    ${embedding ? `${embedding.provider} · ${embedding.model}` : '-'}`);
     console.log(`  图谱:         ${nodes} 个节点 / ${edges} 条关系`);
-    console.log(`  API Key:      ${hasApiKey(project) ? '✅ 已配置' : '❌ 未配置'}`);
+    console.log(`  API Key:      ${keyStatus}`);
     console.log(chalk.dim(`  项目目录: ${project.root}`));
     console.log(chalk.dim(`  Wiki 目录: ${project.wikiDir}\n`));
   });

package/docs/architecture/system-architecture.md

@@ -32,8 +32,8 @@
 │  Step 4: Graph       │  │  Step 5: Vector                │
 │  知识图谱构建         │  │  向量索引构建                   │
 │  scripts/graph_      │  │  scripts/vector-store.mjs       │
-│  builder.py          │  │  scripts/vector_store.py        │
-│  → graph.json        │  │  → vector-store.mjs-data/      │
+│  builder.py          │  │  (provider 可插拔，默认智谱)     │
+│  → graph.json        │  │  → .vector-index.json          │
 │  → graph.html       │  │                               │
 └─────────────────────┘  └─────────────────────────────────┘
 ```
@@ -50,8 +50,8 @@ knowflow/
 │   ├── enrich-wiki.js       # Wiki 后处理（链接补全、摘要生成）
 │   ├── graph_builder.py     # 从 Wiki 页面构建知识图谱
 │   ├── graph_relation_labeler.py  # LLM 分析关系类型
-│   ├── vector-store.mjs     # 向量索引（Embedding + 存储）
-│   ├── vector_store.py      # 向量检索接口
+│   ├── vector-store.mjs     # 向量索引（Embedding + 存储，provider 可插拔）
+│   ├── embedding-config.mjs # embedding 提供商解析（zhipu/openai/custom）
 │   ├── pipeline.sh          # 5 步全自动化管线
 │   ├── bookmark_sync.sh     # X/Twitter 书签同步
 │   ├── wechat_sync.sh       # 微信公众号文章同步

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jerryjiao/knowflow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent-native Markdown workspace for raw capture, linked wikis, knowledge graphs, and semantic search",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   "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"
+    "check": "node --check bin/knowflow.js && node --check scripts/batch-ingest.cjs && node --check scripts/enrich-wiki.js && node --check scripts/vector-store.mjs && node --check scripts/embedding-config.mjs"
   },
   "repository": {
     "type": "git",

package/scripts/embedding-config.mjs

@@ -0,0 +1,62 @@
+/**
+ * Pluggable embedding provider configuration for KnowFlow.
+ *
+ * Reads the optional `embedding` section of .knowflowrc and resolves it into
+ * a concrete endpoint description. Zero side effects — safe to import from
+ * tests and the CLI.
+ *
+ * Resolved shape: { provider, baseUrl, model, dims, apiKeyEnv, chatModel }
+ *   - dims: number sent as `dimensions`, or null to use the model default
+ *   - chatModel: model used by `knowflow ask`, or null when not applicable
+ */
+
+export const EMBEDDING_PRESETS = {
+  zhipu: {
+    baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+    model: 'embedding-3',
+    dims: 1024,
+    apiKeyEnv: 'ZHIPUAI_API_KEY',
+    chatModel: 'glm-4-flash',
+  },
+  openai: {
+    baseUrl: 'https://api.openai.com/v1',
+    model: 'text-embedding-3-small',
+    dims: null,
+    apiKeyEnv: 'OPENAI_API_KEY',
+    chatModel: 'gpt-4o-mini',
+  },
+};
+
+const DEFAULT_PROVIDER = 'zhipu';
+const CUSTOM_API_KEY_ENV = 'EMBEDDING_API_KEY';
+
+export function resolveEmbeddingConfig(userConfig = {}) {
+  const provider = userConfig.provider ?? DEFAULT_PROVIDER;
+
+  if (provider === 'custom') {
+    if (!userConfig.baseUrl) throw new Error("embedding.provider 'custom' requires embedding.baseUrl");
+    if (!userConfig.model) throw new Error("embedding.provider 'custom' requires embedding.model");
+  } else if (!EMBEDDING_PRESETS[provider]) {
+    const known = [...Object.keys(EMBEDDING_PRESETS), 'custom'].join(', ');
+    throw new Error(`Unknown embedding provider "${provider}". Available: ${known}`);
+  }
+
+  const preset = EMBEDDING_PRESETS[provider] ?? {};
+  const dims = userConfig.dims !== undefined ? userConfig.dims : preset.dims ?? null;
+  if (dims !== null && (!Number.isInteger(dims) || dims <= 0)) {
+    throw new Error('embedding.dims must be a positive integer or null');
+  }
+
+  return {
+    provider,
+    baseUrl: stripTrailingSlash(userConfig.baseUrl ?? preset.baseUrl),
+    model: userConfig.model ?? preset.model,
+    dims,
+    apiKeyEnv: userConfig.apiKeyEnv ?? preset.apiKeyEnv ?? CUSTOM_API_KEY_ENV,
+    chatModel: userConfig.chatModel ?? preset.chatModel ?? null,
+  };
+}
+
+function stripTrailingSlash(url) {
+  return typeof url === 'string' ? url.replace(/\/+$/, '') : url;
+}

package/scripts/vector-store.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * KnowFlow Vector Store v2.1
- * 智谱 embedding-3 向量检索引擎
+ * KnowFlow Vector Store v2.2
+ * 向量检索引擎（embedding provider 可插拔，默认智谱 embedding-3；.knowflowrc 的 embedding 节可切换 openai / 自定义 OpenAI 兼容端点）
  *
  * 用法:
  *   node vector-store.mjs build              全量构建索引
@@ -21,6 +21,7 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'fs';
 import { dirname, join, relative, extname, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { resolveEmbeddingConfig } from './embedding-config.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const PROJECT_ROOT = resolve(process.env.KNOWFLOW_ROOT || PACKAGE_ROOT);
@@ -28,11 +29,27 @@ const WIKI_DIR = resolve(process.env.KNOWFLOW_WIKI_DIR || join(PROJECT_ROOT, 'wi
 const INDEX_FILE = join(WIKI_DIR, '.vector-index.json');
 const CACHE_FILE = join(WIKI_DIR, '.embed-cache.json');
 const MANIFEST_FILE = join(WIKI_DIR, '.vector-manifest.json'); // 增量用：记录文件 mtime
-const API_URL = 'https://open.bigmodel.cn/api/paas/v4/embeddings';
-const MODEL = 'embedding-3';
-const CHAT_API_URL = 'https://open.bigmodel.cn/api/paas/v4/chat/completions';
-const CHAT_MODEL = 'glm-4-flash';
-const DIMS = 1024;
+
+// Pluggable embedding provider: `embedding` section of .knowflowrc, resolved
+// against built-in presets (zhipu default, openai) or a custom OpenAI-compatible endpoint.
+function loadUserEmbeddingConfig() {
+  const rcPath = join(PROJECT_ROOT, '.knowflowrc');
+  if (!existsSync(rcPath)) return {};
+  try {
+    return JSON.parse(readFileSync(rcPath, 'utf8')).embedding ?? {};
+  } catch (error) {
+    console.error(`⚠️ 无法解析 ${rcPath} 的 embedding 配置（${error.message}），使用默认 provider zhipu`);
+    return {};
+  }
+}
+
+let EMBEDDING;
+try {
+  EMBEDDING = resolveEmbeddingConfig(loadUserEmbeddingConfig());
+} catch (error) {
+  console.error(`❌ ${error.message}`);
+  process.exit(1);
+}
 const BATCH_SIZE = 20;
 const MIN_SIZE = 300; // 最小文件大小阈值
 const QUERY_CACHE_TTL = 60_000; // 查询缓存 TTL: 60 秒
@@ -58,14 +75,14 @@ if (existsSync(envPath)) {
     if (k?.trim() && !process.env[k.trim()]) process.env[k.trim()] = v.join('=').trim();
   }
 }
-const API_KEY = process.env.ZHIPUAI_API_KEY || '';
-
-if (!API_KEY) {
-  console.error('❌ Error: ZHIPUAI_API_KEY environment variable is required');
-  console.error('   export ZHIPUAI_API_KEY="your-key-here"');
-  // Don't exit for stats/help commands, only block LLM calls
-  const isLlmCommand = process.argv[2] === 'ask' || process.argv[2] === 'query';
-  if (isLlmCommand) process.exit(1);
+const API_KEY = process.env[EMBEDDING.apiKeyEnv] || '';
+
+// LLM 命令（build/query/ask）缺 key 时立即报错退出；纯本地命令（stats）不受影响。
+// 通过 knowflow CLI 跑时，门面层已按 provider 前置拦截，这里是直跑脚本的兜底。
+if (!API_KEY && ['build', 'query', 'search', 'ask'].includes(process.argv[2])) {
+  console.error(`❌ Error: ${EMBEDDING.apiKeyEnv} environment variable is required (embedding.provider=${EMBEDDING.provider})`);
+  console.error(`   export ${EMBEDDING.apiKeyEnv}="your-key-here"`);
+  process.exit(1);
 }
 
 // ─── 工具函数 ───
@@ -120,13 +137,15 @@ function formatDuration(ms) {
 // ─── Embedding API ───
 
 async function getEmbedding(texts) {
-  const res = await fetch(API_URL, {
+  const body = { model: EMBEDDING.model, input: texts };
+  if (EMBEDDING.dims) body.dimensions = EMBEDDING.dims;
+  const res = await fetch(`${EMBEDDING.baseUrl}/embeddings`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Authorization': `Bearer ${API_KEY}`
     },
-    body: JSON.stringify({ model: MODEL, input: texts, dimensions: DIMS })
+    body: JSON.stringify(body)
   });
   if (!res.ok) {
     const err = await res.text();
@@ -150,7 +169,7 @@ function saveManifest(manifest) {
 // ─── Build 索引 ───
 
 async function buildIndex(incremental = false) {
-  if (!API_KEY) throw new Error('需要 ZHIPUAI_API_KEY 环境变量');
+  if (!API_KEY) throw new Error(`需要 ${EMBEDDING.apiKeyEnv} 环境变量`);
 
   log('📂 扫描 wiki 目录...');
   const files = getAllMdFiles(WIKI_DIR);
@@ -254,7 +273,7 @@ function keywordMatch(queryTerms, content, title) {
 // ─── Query 查询（混合检索：向量 + 关键词） ───
 
 async function queryIndex(queryText, topK = 10) {
-  if (!API_KEY) throw new Error('需要 ZHIPUAI_API_KEY 环境变量，请先运行 knowflow init 配置');
+  if (!API_KEY) throw new Error(`需要 ${EMBEDDING.apiKeyEnv} 环境变量，请先在项目 .env 或环境变量中配置`);
   if (!existsSync(INDEX_FILE)) { log('❌ 向量索引不存在，请先运行 knowflow ingest 添加内容后自动构建索引'); return []; }
 
   const raw = JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
@@ -550,7 +569,7 @@ function showStats(verbose = false, json = false) {
 // ─── Ask (LLM Q&A) ───
 
 async function askQuestion(queryText) {
-  if (!API_KEY) throw new Error('需要 ZHIPUAI_API_KEY 环境变量');
+  if (!API_KEY) throw new Error(`需要 ${EMBEDDING.apiKeyEnv} 环境变量`);
   if (!existsSync(INDEX_FILE)) { log('❌ 索引不存在，先运行 build'); return; }
 
   // Step 1 & 2: Find top 5 relevant passages using existing queryIndex logic
@@ -589,14 +608,15 @@ ${contextText}`;
 
   log('🤖 生成回答...');
 
-  const res = await fetch(CHAT_API_URL, {
+  if (!EMBEDDING.chatModel) throw new Error(`当前 embedding provider (${EMBEDDING.provider}) 未配置 chatModel，knowflow ask 不可用`);
+  const res = await fetch(`${EMBEDDING.baseUrl}/chat/completions`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'Authorization': `Bearer ${API_KEY}`
     },
     body: JSON.stringify({
-      model: CHAT_MODEL,
+      model: EMBEDDING.chatModel,
       messages: [
         { role: 'system', content: systemPrompt },
         { role: 'user', content: queryText }

package/scripts/vector_store.py

@@ -1,225 +0,0 @@
-#!/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/wiki-health.py

@@ -1,285 +0,0 @@
-#!/usr/bin/env python3
-"""Wiki Health Check — validates links, file sizes, and orphan pages.
-
-Usage:
-    python scripts/wiki-health.py [WIKI_DIR]
-
-Checks:
-  1. Broken links: [[wiki-links]] and [markdown](links) pointing to missing files
-  2. Tiny files: .md files under 100 bytes
-  3. Orphan pages: .md files not linked from any other page (excludes index.md, topics.md, overview.md, log.md)
-
-Exit codes:
-  0 — all checks pass (or only warnings)
-  1 — broken links found
-  2 — errors during execution
-"""
-
-import os
-import re
-import sys
-import urllib.request
-import urllib.parse
-from pathlib import Path
-from collections import defaultdict
-
-# --- Configuration ---
-WIKI_ROOT = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("wiki")
-TINY_THRESHOLD = 100  # bytes
-INDEX_FILES = {"index.md", "topics.md", "overview.md", "log.md"}
-
-# --- Helpers ---
-
-def resolve_wiki_link(link_target: str, source_file: Path, wiki_root: Path) -> Path:
-    """Resolve a [[wiki-link]] target to an actual file path.
-
-    Wiki-links are relative to wiki_root, not to the source file.
-    Supports optional display text: [[target|Display Text]] -> target
-    """
-    # Strip optional display text: [[target|display]] -> target
-    target = link_target.split("|")[0].strip()
-    if not target:
-        return None
-
-    # Wiki-links are relative to wiki root
-    resolved = wiki_root / target
-
-    # Try exact path first
-    if resolved.is_file():
-        return resolved
-
-    # Try with .md extension
-    md_path = resolved.with_suffix(".md")
-    if md_path.is_file():
-        return md_path
-
-    return None
-
-
-def resolve_md_link(link_target: str, source_file: Path, wiki_root: Path) -> Path:
-    """Resolve a [markdown](link) target to an actual file path.
-
-    Markdown links are relative to the source file's directory.
-    """
-    if not link_target or link_target.startswith(("http://", "https://", "#", "mailto:")):
-        return None  # External or anchor links — skip
-
-    # URL-decode for Chinese filenames
-    decoded = urllib.parse.unquote(link_target)
-
-    # Markdown links are relative to the source file directory
-    source_dir = source_file.parent
-    resolved = (source_dir / decoded).resolve()
-
-    if resolved.is_file():
-        return resolved
-
-    return None
-
-
-def strip_code_blocks(content: str) -> str:
-    """Remove fenced code blocks and inline code to avoid false positive links."""
-    # Remove fenced code blocks (```...```)
-    content = re.sub(r'```.*?```', '', content, flags=re.DOTALL)
-    # Remove inline code (`...`)
-    content = re.sub(r'`[^`]+`', '', content)
-    return content
-
-
-def extract_links(content: str, source_file: Path, wiki_root: Path):
-    """Extract all link targets from markdown content.
-
-    Returns:
-        wiki_links: set of (raw_target, resolved_path_or_None) for [[]] links
-        md_links: set of (raw_target, resolved_path_or_None) for []() links
-    """
-    wiki_links = set()
-    md_links = set()
-
-    # Strip code blocks to avoid false positives
-    clean = strip_code_blocks(content)
-
-    # [[wiki-links]] — may contain | for display text
-    for match in re.finditer(r'\[\[([^\]]+)\]\]', clean):
-        raw = match.group(1)
-        target = raw.split("|")[0].strip()
-        resolved = resolve_wiki_link(target, source_file, wiki_root)
-        wiki_links.add((target, resolved))
-
-    # [markdown](links) — standard markdown
-    for match in re.finditer(r'\[([^\]]*)\]\(([^)]+)\)', clean):
-        raw_target = match.group(2).strip()
-        resolved = resolve_md_link(raw_target, source_file, wiki_root)
-        if resolved is not None or not raw_target.startswith(("http://", "https://", "#", "mailto:")):
-            md_links.add((raw_target, resolved))
-
-    return wiki_links, md_links
-
-
-# --- Checks ---
-
-def check_broken_links(wiki_root: Path) -> list[dict]:
-    """Find all broken links across the wiki."""
-    broken = []
-
-    for md_file in sorted(wiki_root.rglob("*.md")):
-        try:
-            content = md_file.read_text(encoding="utf-8")
-        except Exception as e:
-            broken.append({
-                "file": str(md_file.relative_to(wiki_root)),
-                "error": f"Cannot read file: {e}"
-            })
-            continue
-
-        wiki_links, md_links = extract_links(content, md_file, wiki_root)
-
-        rel_path = str(md_file.relative_to(wiki_root))
-
-        for raw_target, resolved in wiki_links:
-            if resolved is None:
-                broken.append({
-                    "type": "wiki-link",
-                    "file": rel_path,
-                    "target": raw_target,
-                    "detail": f"[[{raw_target}]] -> file not found"
-                })
-
-        for raw_target, resolved in md_links:
-            # Skip external links
-            if raw_target.startswith(("http://", "https://", "#", "mailto:")):
-                continue
-            if resolved is None:
-                broken.append({
-                    "type": "md-link",
-                    "file": rel_path,
-                    "target": raw_target,
-                    "detail": f"[]({raw_target}) -> file not found"
-                })
-
-    return broken
-
-
-def check_tiny_files(wiki_root: Path, threshold: int = TINY_THRESHOLD) -> list[dict]:
-    """Find .md files smaller than threshold bytes."""
-    tiny = []
-
-    for md_file in sorted(wiki_root.rglob("*.md")):
-        try:
-            size = md_file.stat().st_size
-        except OSError:
-            continue
-
-        if size < threshold:
-            tiny.append({
-                "file": str(md_file.relative_to(wiki_root)),
-                "size": size,
-                "detail": f"{size}B < {threshold}B threshold"
-            })
-
-    return tiny
-
-
-def check_orphan_pages(wiki_root: Path) -> list[dict]:
-    """Find .md pages not referenced by any other page."""
-    # Collect all existing pages
-    all_pages = set()
-    for md_file in wiki_root.rglob("*.md"):
-        all_pages.add(md_file)
-
-    # Collect all link targets across all files
-    referenced = set()
-    for md_file in wiki_root.rglob("*.md"):
-        try:
-            content = md_file.read_text(encoding="utf-8")
-        except Exception:
-            continue
-
-        wiki_links, md_links = extract_links(content, md_file, wiki_root)
-
-        for _, resolved in wiki_links:
-            if resolved is not None:
-                referenced.add(resolved)
-
-        for _, resolved in md_links:
-            if resolved is not None:
-                referenced.add(resolved)
-
-    orphans = []
-    for page in sorted(all_pages):
-        rel = str(page.relative_to(wiki_root))
-        # Index files are never considered orphans
-        if page.name in INDEX_FILES:
-            continue
-        if page not in referenced:
-            orphans.append({
-                "file": rel,
-                "detail": "not linked from any other page"
-            })
-
-    return orphans
-
-
-# --- Main ---
-
-def main():
-    if not WIKI_ROOT.is_dir():
-        print(f"ERROR: wiki directory not found: {WIKI_ROOT}")
-        sys.exit(2)
-
-    print(f"Wiki Health Check — {WIKI_ROOT.resolve()}")
-    print(f"{'=' * 60}")
-
-    # Count files
-    md_files = list(WIKI_ROOT.rglob("*.md"))
-    print(f"Total .md files: {len(md_files)}")
-
-    exit_code = 0
-
-    # 1. Broken links
-    print(f"\n--- Broken Links ---")
-    broken = check_broken_links(WIKI_ROOT)
-    if broken:
-        errors = [b for b in broken if "error" in b]
-        link_issues = [b for b in broken if "error" not in b]
-        if link_issues:
-            print(f"  BROKEN LINKS: {len(link_issues)}")
-            for item in link_issues:
-                print(f"    [{item['type']}] {item['file']} -> {item['target']}")
-            exit_code = 1
-        if errors:
-            print(f"  READ ERRORS: {len(errors)}")
-            for item in errors:
-                print(f"    {item['file']}: {item['error']}")
-    else:
-        print("  OK — no broken links found")
-
-    # 2. Tiny files
-    print(f"\n--- Tiny Files (< {TINY_THRESHOLD}B) ---")
-    tiny = check_tiny_files(WIKI_ROOT)
-    if tiny:
-        print(f"  TINY FILES: {len(tiny)}")
-        for item in tiny:
-            print(f"    {item['file']} ({item['detail']})")
-    else:
-        print("  OK — no tiny files found")
-
-    # 3. Orphan pages
-    print(f"\n--- Orphan Pages ---")
-    orphans = check_orphan_pages(WIKI_ROOT)
-    if orphans:
-        print(f"  ORPHAN PAGES: {len(orphans)}")
-        for item in orphans:
-            print(f"    {item['file']}")
-    else:
-        print("  OK — no orphan pages found")
-
-    print(f"\n{'=' * 60}")
-    total_issues = len(broken) + len(tiny) + len(orphans)
-    print(f"Total issues: {total_issues}")
-
-    sys.exit(exit_code)
-
-
-if __name__ == "__main__":
-    main()