系统架构

整体流程

输入               确定性采集            任一编码 agent                你
(URL / 推文 / ──► 存入 raw/ ──► 按共享契约合成 ──► 审核，
 笔记)             （无 AI）      docs/agents/        一词翻转
                                  synthesize.md       pending → reviewed
                                         │
                          ┌──────────────┤
                          ▼              ▼
                       知识图谱       可选语义检索
                    (graph.html/json) (向量索引 + query)

待审页在审核前进不了图谱和检索索引。

三条边界定义了整个设计：

1. 采集是确定性的。 ingest 抓取来源素材并以 Markdown 存入 raw/，不调用 LLM，不写 Wiki 页面。
2. 合成委托给 agent，审核权在人。 任一编码 agent——ZCode、Codex CLI、Claude Code、OpenCode——按成文契约 docs/agents/synthesize.md 把 raw/ 变成结构化页面。每张合成页以 status: pending 直落最终目录，只有你把它翻成 reviewed，它才算进入 Wiki。
3. 未审核内容有闸门。 graph 与 index build 剥离 frontmatter 并跳过待审页；health 对待审页全量执行断链与体积检查，但豁免孤儿判定；fix 永不触碰待审页。

目录结构

knowflow/
├── bin/
│   └── knowflow.js          # CLI 入口，命令路由
├── scripts/
│   ├── ingest.sh            # 单条 URL/文本采集（fetch → raw/）
│   ├── graph_builder.py     # 从 Wiki 页面构建知识图谱
│   ├── wiki-health.sh       # 健康检查（断链、小文件、孤儿页）
│   ├── wiki-auto-fix.sh     # knowflow fix 背后的修复逻辑
│   ├── tags-builder.mjs     # knowflow tags 背后的 tag 聚合页构建
│   ├── vector-store.mjs     # 向量索引（嵌入 + 存储）与查询
│   ├── graph_relation_labeler.py  # LLM 关系类型标注（可选）
│   ├── bookmark_sync.sh     # X/Twitter 书签同步
│   └── wechat_sync.sh       # 微信公众号文章同步
├── templates/               # 可编辑页面模板（实体/概念/对比/来源）
├── docs/                    # 架构、方法论、参考文档
└── package.json

核心命令（init、ingest、compose、check、status、health、fix、graph、tags、index、query、ask）稳定且有测试覆盖。从原始采集到已审核页面的 Agent 工作流已经落地：合成契约随仓库发布在 docs/agents/synthesize.md，审核闸门把未审核页面挡在图谱和检索索引之外。

一条 URL 的生命周期

1. 采集。 knowflow ingest <url> 识别来源类型，抓取全文（网页走 Jina Reader；部分平台可能需要 yt-dlp），带元数据存入 raw/。仅此而已，不写任何别的东西。
2. 合成。 任一编码 agent 读取 raw 文件并遵循 docs/agents/synthesize.md：起草 status: pending 的 source 页（外加最小 entity 页），直落最终目录，frontmatter 带 created_from 溯源，核心要点带 (EXTRACTED)/(INFERRED) 置信标注。knowflow compose --list 显示尚未合成的素材。
3. 审核。 你把 pending 翻成 reviewed——只改一个词——或者删除文件即驳回。审核前可用 knowflow check 校验八条页面解剖合规；knowflow status 列出所有还在等你审核的页面。
4. 图谱。 knowflow graph 剥离 frontmatter、跳过待审页，对已审页面按路径解析 [[wikilink]]，输出 graph.json 和交互式查看器 graph.html。
5. 检索（可选）。 配置 embedding 提供商 Key（默认智谱，支持 OpenAI 与自定义 OpenAI 兼容端点）后，可用 knowflow index build 构建本地向量索引——待审页被跳过——再通过 knowflow query 与 knowflow ask 查询。

为什么用 Markdown 而不是数据库？

• 人类可读 —— 编辑器直接打开就能看
• 版本控制友好 —— Git 追踪每次变更
• Agent 友好 —— LLM 天然擅长读写 Markdown
• 可移植 —— 不依赖任何数据库服务，零锁定

为什么图谱和向量检索都要？

能力	知识图谱	向量检索
精确查找	✅ 按实体/关系查	❌
语义搜索	❌	✅ “类似 XXX 的内容”
发现关联	✅ A→B→C 的路径	❌
模糊匹配	❌	✅ 语义相近即可

两者互补。图谱本地运行、零依赖；语义检索是可选项，默认关闭。

技术栈

组件	技术	原因
CLI 运行时	Node.js 18+	npm 生态，开发者熟悉
图谱构建	Python 3.10+	图算法成熟，vis-network 可视化
合成	任一编码 agent + 成文契约（docs/agents/synthesize.md）	CLI 不内嵌 LLM；起草由你已有的 agent 完成
向量索引（可选）	可插拔嵌入（默认智谱，支持 OpenAI / 自定义）	本地索引文件，无需外部服务
数据存储	纯文件（Markdown/JSON）	零依赖，Git 友好