Wink Pings

一个 Python 文件,把 LLM 知识管成三面树

Reddit 网友开源了 tawjih,单文件零依赖,用三面 Markdown 树管理 LLM 知识,支持跨树分支工作流、确定性缓存和书籍过滤管线。

做 LLM 应用的人常面对一个选择:把所有东西塞进一个大 prompt,或者上 RAG、向量库、框架。Reddit 的 r/PromptEngineering 上有网友(Basic_You_2402)走了另一条路,写了个叫 tawjih 的工具,阿拉伯语里是“引导”的意思。核心只有一个 Python 文件,只用 3.11+ 标准库,不依赖第三方包。

GitHub 地址:AlmodinyMk/LLM-tawjih-Model-building

它的做法是把知识存成一棵棵小 Markdown 文件组成的树,最深六级:general → section → chapter → topic → branch → part。每个节点分三面:

  • human 面(=== human ===):人写的概念解释和笔记
  • machine 面(=== instructions === 加 === code ===):给模型的自包含指令,以及可选的 Python 代码
  • reading 面(=== reading ===):从 UTF-8 书籍或研究材料里筛出的原文段落,带出处

分开的理由很直接。构建时和运行时严格隔离。人把 reading 和 human 两面提炼进 machine 面。运行时只有 machine 面被送进模型,笔记和原书段落不会占上下文窗口。检索和生成在多数管线里是混在一起的,这里被拆成了两个阶段。

跨树工作流用一套双语 DSL,英文和阿拉伯文都行:

A TO B
A TO B AND C
B AND C TO D
A TO B IF word
A TO B IF NOT word
A AMONG B C D
A TO D THROUGH B C

A AMONG B C D 是让模型的输出动态决定下一个节点。示例:

python tawjih.py produce review 1.1 TO 1.2 IF error / 1.1 TO 1.3 IF NOT error / 1.2 AND 1.3 TO 2.1 --input "..." --backend ollama

后端支持本地 ollama、OpenAI 兼容端点、anthropic,还有一个 dry 模式,只打印 prompt 不花 token,以及 manual 模式,把 prompt 贴到任意网页 UI,再把答案贴回来。

缓存和续跑的设计值得看一眼。每条模型响应按 provider、model、精确 prompt 三者的 SHA-256 哈希缓存。多步运行中途失败,--resume 跳过已完成的步骤,--resume --redo <step> 单独重跑某一步,其余不动。

还有个书籍过滤管线:deposit 一本 UTF-8 文本,filter 让 LLM 按你的树结构给段落分类,生成可审查的 JSON 报告,accept 把通过的引用追加到 reading 面。

每次生产运行都会在 runs/ 下记录 prompt 和输出,并在 history/ 里写 JSON 审计记录,追踪所用 machine 面的 SHA-256 摘要。

当前版本 v0.5.1,实验性质。作者说 CLI 在 Linux 和 Windows 上都能跑,Windows 有原生记事本和 VS Code 的 --wait 集成。单元测试在 Python 3.11 到 3.13 上通过。需要留意的地方:代码步骤走 exec 执行,所以 --allow-code 是严格选择性开启;网络后端目前只对本地 mock 服务器测过;Linux 桌面 GUI(GTK 3 / Tkinter)只在无头环境测过。

许可证 CC BY-NC-SA 4.0。

这套设计有个取舍:前期整理知识树要花时间,换来的是运行时上下文干净、步骤可复现。习惯把所有内容丢进 prompt 的人,用起来大概会觉得束手束脚。

发布时间: 2026-11-17 10:30