跳转到内容
KnowFlow logoKnowFlow

命令参考

KnowFlow 是一个单一的 knowflow CLI。命令会从当前目录向上查找最近的 .knowflowrc 来定位项目根，因此在项目子目录里也能直接运行。

一段真实会话

Section titled “一段真实会话”
Terminal window
$ knowflow init my-wiki && cd my-wiki
✅ 已创建 /path/to/my-wiki/.knowflowrc
✅ KnowFlow 项目已初始化: /path/to/my-wiki


$ knowflow ingest "Karpathy 的 LLM Wiki 文章：让 agent 把收藏链接整理成持久、互联的 wiki 页面。" --source text
🔗 开始采集素材...
✅ 采集完成！                       # → raw/web/<时间戳>-note.md


$ knowflow graph --no-open
🕸️  构建知识图谱...
✅ 图谱已生成: /path/to/my-wiki/graph/graph.html


$ knowflow health
🏥 Wiki 健康检查...
✗ wiki/concepts/linked-knowledge.md → [[sources/missing]] (not found)
⚠️  发现一些问题，建议修复（knowflow fix）   # 退出码 1


$ knowflow fix --dry-run
🔧 自动修复 Wiki 问题...
[dry-run] 会创建缺失页面: wiki/sources/missing.md
命令 作用
init 创建独立项目
ingest 采集 URL 或文本到 raw/
compose 列出尚未合成 wiki 页面的 raw 素材
check 对四类页面执行八条合规闸门
status 显示项目统计、索引状态与待审清单
health 检查断链、小文件和孤儿页
fix 修复 health 发现的问题（永不触碰待审页）
graph 生成交互式知识图谱（跳过待审页）
tags 重建 tag 聚合页
index 构建 / 查看向量索引（可选；跳过待审页）
query 混合语义检索（可选）
ask 基于 Wiki 上下文带引用回答问题（可选）

init

Section titled “init”
Terminal window
knowflow init [目录]

创建一个独立项目（默认使用当前目录）：

  • .knowflowrc —— JSON 配置，只在不存在时写入
  • wiki/，含 sources/、entities/、concepts/、comparisons/ 子目录和初始 index.md
  • raw/，含 web/、twitter/、xiaohongshu/、wechat/ 子目录
  • graph/ 输出目录
  • templates/ —— 从包里拷贝的可编辑 Markdown 页面模板

再次运行 init 会保留已有配置、初始首页和自定义过的模板。

ingest

Section titled “ingest”
Terminal window
knowflow ingest <url-或-文本> [--source <类型>]

把 URL 或纯文本笔记采集为 Markdown 存入 raw/。--source（-s）默认 auto，自动识别来源类型；纯文本用 text。

需要知道的细节：

  • URL 采集依赖 Jina Reader；YouTube 和部分需要登录的平台可能还需要 yt-dlp 或带登录态的浏览器工作流。
  • ingest 不合成 Wiki 页面。 它只保存原始素材。合成是你的编码 agent 的事，遵循成文契约 docs/agents/synthesize.md——一个独立的、看得见的步骤。这个边界是有意设计的。

compose

Section titled “compose”
Terminal window
knowflow compose --list

列出还没有对应 wiki 页面的 raw 文件——你 agent 的工作清单。

这份清单是派生的，不是存储的：raw/ 全集减去四个页面目录 frontmatter 中出现过的所有 created_from 指针。零状态文件，因此清单会自愈——删掉某张已合成页，它的 raw 文件就自动回到清单上。

不带 --list 的 compose 只打印用法，并指向合成契约。

check

Section titled “check”
Terminal window
knowflow check

对四个页面目录下的每一页执行八条合规闸门：

  • (a) 文件所在目录与 frontmatter type 一致
  • (b) 正文首个标题是 H1，且与 frontmatter title 一致
  • (c) frontmatter 必填字段齐全（type、title、created、created_from、status）
  • (d) 必填章节齐全，标题与模板逐字一致、按模板顺序
  • (e) 无残留 {{…}} 模板占位符
  • (f) source/entity 页每条核心要点行尾恰好一个 (EXTRACTED)/(INFERRED) 标注，concept/comparison 页全文禁用
  • (g) 验收线成立（核心要点条数、对比页维度行与对比对象数）
  • (h) knowflow health 三查全绿

任一违规即以退出码 1 结束，可以直接给 CI 或 agent 的合成循环当闸门。空库不视为违规。

status

Section titled “status”
Terminal window
knowflow status

打印项目概览：Wiki 文章数与总行数、原始素材数、向量索引状态（已向量化页数）、图谱节点/边数量、API Key 是否已配置。当有页面等待审核时，输出末尾会附上待审清单——四个页面目录里所有 status: pending 的页面。不需要 API Key。

health

Section titled “health”
Terminal window
knowflow health

检查 Wiki 的：

  • 断链 —— 指向不存在文件的 [[wikilinks]] 和 [markdown](链接.md)
  • 小文件 —— 小于 health.minFileSize 字节（默认 100）的页面
  • 孤儿页 —— 没有任何页面链接到的页面，health.excludeOrphanDirs 列出的目录不计入

待审页（status: pending）豁免孤儿判定——没被链接的待审稿是常态；断链与最小体积检查对它们照常全量执行。

发现问题时以退出码 1 结束，可以直接用于 CI 或 Agent 工作流的门禁。用 fix 修复它报告的问题。

fix

Section titled “fix”
Terminal window
knowflow fix [--dry-run]

修复 health 发现的问题：

  • 清理 [[entities/,]] 这类空链接
  • 创建链接指向但不存在的实体/概念页
  • 给低于最小尺寸的文件补内容
  • 把孤儿页自动链接到 index.md

待审页（status: pending）永不触碰——等你审核的草稿不会被修复破坏。

--dry-run 只报告会改什么，不写任何文件。

graph

Section titled “graph”
Terminal window
knowflow graph [--no-open]

解析 Wiki 页面，提取 [[wikilink]] 关系，输出 graph.html（交互式查看器，首次打开从 CDN 加载 vis-network）和 graph.json（原始数据）。frontmatter 在解析前被剥离，待审页（status: pending）被跳过——不建节点、不建边、指向它们的链接也不解析。图谱里永远只有已审核的内容。无需 API Key。默认用浏览器打开查看器，传 --no-open 则只构建。

tags

Section titled “tags”
Terminal window
knowflow tags

扫描全部 Wiki 页面中的 [[tag/<名称>]] 链接，（重新）生成 wiki/tag/<名称>.md 聚合页，索引所有带该标签的页面。全量重建、幂等 —— 新增带标签页面后随时重跑。

index

Section titled “index”
Terminal window
knowflow index build [--incremental] [--stats]
knowflow index stats [--verbose] [--json]

构建与查看语义检索所用的向量索引。

  • build 扫描 Wiki 并嵌入每个页面（小于 300 字节的文件会跳过；待审页也会跳过——未审核内容进不了检索索引）。--incremental（-i）只重新嵌入新增或修改过的页面；--stats 在构建后输出索引统计。
  • stats 报告页数、向量覆盖率、缓存大小与 token 估算——不需要 API Key。--verbose 追加 per-file 明细表；--json 输出结构化数据。

需要 embedding 提供商的 API Key（切换提供商见配置；默认智谱）。

query

Section titled “query”
Terminal window
knowflow query <文本> [--top <n>]

对 Wiki 做混合检索（向量搜索 + 关键词匹配）。--top（-n）控制返回数量（默认 5，范围 1–100）。

前置条件：

  • Embedding 提供商 API Key——默认为智谱 AI，通过 ZHIPUAI_API_KEY 环境变量或项目根 .env 文件提供
  • 由 knowflow index build 构建的向量索引

ask

Section titled “ask”
Terminal window
knowflow ask <问题>

基于检索到的 Wiki 上下文回答问题：取回最匹配的页面作为上下文交给 chat 模型，输出回答并附编号引用列表。前置条件与 query 相同（API Key + 已构建索引）。

配置

Section titled “配置”

knowflow init 会写入 JSON 格式的 .knowflowrc。所有相对路径以该文件所在目录为基准解析。

{
  "wiki": { "root": "./wiki", "rawDir": "./raw" },
  "graph": { "output": "./graph/graph.html" },
  "health": { "minFileSize": 100, "excludeOrphanDirs": ["sources/"] }
}
  • health.excludeOrphanDirs —— 预期不会被引用的目录（每日同步流水页、收件箱等），其中的页面不计入孤儿页
  • wiki.root / wiki.rawDir / graph.output —— 自定义 Wiki、raw 层和图谱输出的位置

图谱生成、健康检查、内容采集和状态查看都不需要 API Key，只有 index build、query 和 ask 需要。

Embedding 提供商可通过可选的 embedding 节插拔，预设会填好默认值，所有字段均可单独覆盖：

{ "embedding": { "provider": "openai" } }
{
  "embedding": {
    "provider": "custom",
    "baseUrl": "https://your-relay.example.com/v1",
    "model": "your-embedding-model",
    "apiKeyEnv": "RELAY_API_KEY",
    "chatModel": "your-chat-model"
  }
}
  • provider —— zhipu（默认）、openai 或 custom
  • baseUrl / model / dims / apiKeyEnv —— 端点覆盖（缺省时用预设默认值）
  • chatModel —— knowflow ask 背后的对话模型

embedding 节写错时会立刻报错并指出问题字段。