knowledge_database

knowledge_database — 从对话里把有用的那几句挑出来，挂成你自己的知识树

快速开始（macOS / Linux，要 Python 3.11 和 Rust 工具链）：

git clone https://github.com/lo2589/knowledge_database.git
git clone https://github.com/lo2589/FastNode.git Node     # 底层节点库，必须放在同一层、目录名叫 Node
cd knowledge_database
./setup.sh                                                # 建 .venv、从 ../Node 编 FastNode、装 PDF/Word 读取库
.venv/bin/python -m km --chat                             # 网页版：左边 Codex 对话，右边知识图

装进 dsh 用：再跑 ./dsh-install.sh，重启 dsh（见第八节）。

跟 agent 聊一下午，真正学到的可能就三五句，混在几百句里，过几天就找不到了。这个工具做的事：

1. 拆：对话、文档拆成一句一句；表格按一条字段数据拆（带行标识和列名）；段落里连续的 A：… B：… / 1) … 2) … 记录逐条拆。公式、代码、图保持完整。
2. 挑：在左边的对话里点句子（一句一张卡），或者按住 Ctrl 框一段话一次入库一批。
3. 入库：留下的做成卡片，每张卡记得来自原文哪句，点一下跳回去。
4. 检查：LLM 说的不一定对。每张卡标「对 / 改正过 / 存疑 / 错」，写上依据。
5. 归纳：自己把卡挂进层级树，再连上别的关系（前提、例子、细化、矛盾、相关）。
6. 看：严格层级树像 mermaid 那样从上往下画；一层排不下就折行，画布宽度有上限（卡片不会被甩到几千像素外）；折叠起来的子树不占位置，兄弟节点自动靠拢；画面外的东西在四边留一条可点的「接字」；排版跟着面板宽度走，你看的位置、折叠、模式会被记住。
7. 带走：一键导出 Markdown 大纲 / Mermaid 图 / JSON / PDF，或把某张卡连同它的下级写进对话框接着问。
8. 不装 dsh 也能用：网页版 /chat 左边是 Codex 对话、右边是同一张知识图——聊完一段，把有用的句子点进图里。

为什么结构要自己挂、不让 AI 自动挂：AI 画的结构图更整齐，但人记不住；自己挂的更乱，记得反而牢。挂的这一下就是学习。

（需求清单、功能对照这类工作笔记留在本地，不随仓库发布。）

---

一、界面：一屏两半，不切换

┌──────────── dsh 对话 ────────────┬──────────────── 知识库 ────────────────┐
│ 你问：残差学习是什么？…          │ 库里有什么 │  知识图（严格层级树）       │
│ 回答（每一句都能点）：           │ 25 张卡…   │      ┌─────┐               │
│ ▍H(x) = F(x) + x        ✓已入库  │ 最近入库   │      │ 根  │               │
│ ▍F(x) 是残差函数…       ✓已入库  │ 目录（树） │   ┌──┴──┐  ┌──┐            │
│ ▍梯度里天然带着 +1…              │  ● Block   │   │Block│──│…│  彩色线=关系 │
│                                  │   ● 残差…  │   └─────┘  └──┘            │
└──────────────────────────────────┴─────────────────────────────────────────┘

• 左边是 dsh 自己的对话，回答用 dsh 原本的 Markdown 渲染（公式、代码、表格都不变），每一句都能点。
• 右边是知识库，一直开着：装成共享右栏（dsh-plugin-rightbar）里的「知识图」标签，和别的插件并排住在一栏；没装那个右栏时退回自己贴右边的浮动面板（拖它的左边缘调宽度，宽度记在 km-panel-w）。
• 白板页面自己的文件一改，页面 3 秒内自己重载（/api/version 轮询），不用手动刷新。

---

二、左边对话怎么用（逐句入库）

入库时一并记下：会话 id、消息 id、句子在消息里的位置、这句话在第几轮、说话人，以及它回答的那个问题（卡片「原文」里显示的就是这个问题）。

三、右边白板怎么用

顶上那一行

卡片上的工具行（鼠标移上去由淡变实）

从左到右：

画布上的手势

摆放与画面：活跃的那一段说了算

• 一层排不下就折行：同一层的卡片按家族顺序排成行，一行到上限（4 张卡，或者 1.5 个面板宽，取大的那个）就换行；一家人整块搬下去，不拆两半；父母仍摆在自己孩子上方的中间。挪动之后每一行按比例收回它自己的宽度、回到同一条中轴——所以画布宽度有硬上限，不会出现"卡片被甩到几千像素外"。84d106 那份库全部展开：改之前 11 857 像素宽（60 张里 45 张在画面外），现在是 2 023 像素。
• 新卡落在离上级最近的那一格（上级正下方），不是一整排的最右边——所以越点越远这种事不会发生。
• 刚入图的卡：已经在眼前就只闪一下，画面一动不动；真在屏幕外，画面才挪刚好把它露出来的那一小步，绝不为了它把镜头甩到别处。
• 打开一份库 / 切会话时，画面对准活跃那一段（挂载点 + 它的子节点；挂载点没有子节点时带上它的上一级），不放大超过 1:1——其它分支不缩、也不抢镜头，就落在视野边上；自适应 才是"把整张图铺开给我看"。
• 顶栏 新知识挂到：X 点一下，画面立刻回到这一段。
• 展开/折叠：不活跃的子树默认折起来（不折的话，一个兄弟的子树就能把兄弟之间撑开几千像素）；切挂载点时，新挂载点这一条路径会自动展开；你自己展开过的分支不会被自动折回去，你自己折起来的也一直保持折着，都按会话记住。
• 被看到的卡片是完整的：取景框只收完整的卡——活跃节点和它的所有子节点永远整张在画面里（必要时可以缩到 0.32 那么小）；画面边上露了半张的邻卡，能整张收进来就一起收，为此最多缩到 0.5。再往外就留在边上——清晰度优先。
• 折起来的卡不是空壳：卡片底部一条虚线，列出折起的前 3 条（点一条直接跳过去，顺路把那条分支展开），剩下写「…另 N 项（搜索能找到）」。
• 画面外有东西，四边会留「接字」（书里翻到页末那一行"接下页"）：写明那边还有几张、最近的是哪张，点一下带过去。只算"大半在画面外"的卡——边上被切掉一条边的不算，所以接字不会压在卡片上；左右两条贴在画面下方两角。
• 一屏同时摆的卡片有上限（120 张）：超过就把最占地方的分支自动折起来（活跃路径上的、以及你自己展开过的一律不动），提示只说一次。折起来的卡片照样列出下面几条，搜索也照样能找到。
• 手动摆放有墙：一张卡最多摆到离它在树上的位置 1200 像素的地方（层坐标），拖到头就停住，并说明一次原因。
• 摆在很远处的老坐标会被拉回来：打开库时，离树 1800 像素以外的坐标一律当作"摆丢了"，直接回到树上，同时把这个决定告诉服务端——所以下次打开它不会又飘在那边。
• 画面不允许空着：任何时候画面被内容盖住的比例低于约 1/4、而外面还有卡没显示，就自动重新取景把最近的卡拉进来（"地广行稀"是明确要避免的状态）。一个小库本来就填不满屏幕（那是没东西可填），不会来回晃。
• 换了排法之后，上一次记住的镜头不作数（视图版本 5 → 6）：按会话记住的是折叠、模式、搜索词这些，画面位置按新的几何重算。

融合与删除都不会丢东西

• 拖到卡片中间 / ⊕+↳ / Ctrl 拉框：正文拼接（留下的在前、并进来的在后）、原文两条都留、下级和所有关系一并转移，卡面直接显示合并后的正文。
• 删卡片：下级接到上级下面，顺序不变。
• 删资料：连用它做的卡片一起删（卡的原文已经不存在了，留着就是半截状态），提示里会说删了几张。

左边目录栏（☰）

• 库里有什么：卡片数、关系数、带原文数、各核对状态的计数；
• 最近入库：最近 5 张，点一下就跳过去；
• 目录：整棵树的目录，点一下就跳过去；
• 导入的资料：点一下把那份资料移到眼前。

Outliner 模式（☷）

一条一张卡：▸/▾ 折叠下级、⌖ 设为挂载点、行里是标题 + #id · n 个下级 · 关系摘要、✎ 改正文、T 改标题、× 删除；双击行也是改正文。适合逐条读和重排。

---

四、图片

一张图（截图、示意图、公式照片）可以这样进知识库：

• 图片存在 data/images/，按内容命名（同一张图存两份也只有一个文件），卡片正文里留一行 ![](/images/xxxx.png)；渲染、Markdown / PDF 导出、打印版式都带着这张图。
• 只收 png / jpeg / gif / webp（svg 会当脚本执行，不收），单张上限 12MB。
• 卡片里的图不会撑破卡片：宽度跟着卡片走，高度最多 60vh。

---

五、导入的资料与原文跳转

• 导入的资料在图的左边一栏，标题右上角 × 点一次就删（连带用它做的卡片）。
• 资料里的句子可以直接点：点一下就是一张卡（挂到挂载点下），已用的句子标 ✓ 已成卡；Ctrl 拖框把框住的几句合成一张卡。
• 表格按表显示（不再是"每格一行"），三层随你点：整张表 / 一行 / 一格（见上表）。对话里的表格也一样。
• 卡片「原文」里的句子点 ↗：来自导入资料的，跳到那份资料里的那一句并高亮；来自 dsh 对话的，跳到左边对话的那一句。
• 长会话也跳得到：句子在第几轮入库时记在库里；那条消息还没被加载出来时，插件会点对话左侧的轮次标记让 dsh 把那一轮翻回页面，落地后再定位、再高亮（没有轮次信息的老卡片退回「逐个加载更早」）。

---

六、导出（导出 按钮）

点开是一个小面板，选格式后先把全文显示在框里（文件名 / 行数 / 大小都写着），再按 下载文件 或 复制全部：

面板底部还有 打印 / 另存为 PDF：把同一个打印版式开在新标签页里，用系统打印对话框「另存为 PDF」。没有 Chrome / Chromium / Edge 时，点 PDF 会自动退到这条路，并说明原因。

服务端对应：GET /api/export?fmt=markdown|mermaid|mermaid-full|json、GET /api/pdf、GET /print（打印页）。

---

七、网页版：左边 Codex 对话，右边知识图（/chat）

不经过 dsh，直接在浏览器里：

http://127.0.0.1:8795/chat

• 左边是 Codex 对话：回答用 dsh 之外的同一个渲染器画（公式、代码、表格都在），每一句都能点——点一下就变成右边知识图里的一张卡。
• 右边是同一张白板：排版、折叠、搜索、融合、导出、状态保持，全是上面第三、五节里那套，一点没变。中间那条分隔可以拖动，宽度会记住。
• 每个对话一份知识库：第一个问题会成为这份库的名字；「新对话」开新的库，「最近」列出以前的对话（每个对话记得自己的 Codex 线程，接着聊是同一个上下文）。
• Codex 是用你机器上已经装好的那个：codex exec --json（桌面版自带，或用 KM_CODEX=/path/to/codex 指定），所以用的是你已经登录的账号和 ~/.codex/config.toml 里的模型，不用再配一遍 key。
• 只读沙箱：默认 read-only，Codex 能读代码、能跑只读命令，但不会改你的文件；要放开就 KM_CODEX_SANDBOX=workspace-write。
• **顶上的「目录」**就是 Codex 的工作目录（读写都限制在它的策略里），默认用 Codex 自己的默认值，改过会记住。
• 可以给 Codex 发图：composer 上点「图片」或直接粘一张，走 codex exec -i，图上还会出现在问题气泡里、可以点进知识图。同样支持：Ctrl/⌘ 拖框选多句 → 合成一张卡、已经入库的句子标 ✓ 已入库 再点就跳回那张卡、卡片上的 ↗ 跳回左边那句原文并高亮、思考过程折起来、跑了哪些命令、token 用量。
• 首轮可能要等一两分钟：Codex CLI 会先试它的 WebSocket 通道，在这个网络上要重试五轮（约 113 秒）才回退到 HTTPS，然后几秒钟就答完。这是 Codex 自己的行为，不是页面卡住——页面会把「Reconnecting… / Falling back…」显示成一行灰色的状态提示，20 秒没动静还会写清楚在等什么。真没拿到回答时，那一轮下面有 重试这一轮。
• 对话存在 data/chats/<对话 id>.json（线程 id、目录、每一轮的问答），和卡片所在的库分开存——关掉浏览器再回来，两边都还在。

---

八、装与跑

需要：Python 3.11、Rust 工具链（cargo，setup.sh 用 maturin 现编 FastNode）、FastNode 源码放在同级目录 Node：

git clone https://github.com/lo2589/FastNode.git ../Node   # 只需一次；或用 FASTNODE_DIR=/别处/FastNode ./setup.sh
./setup.sh          # Python 环境 + FastNode + 读 PDF/Word 的库
./dsh-install.sh    # 装进 ~/.dsh/profiles/web（先备份 package.json）；装完重启 dsh

重启 dsh 之后，右栏会出现「知识图」标签；插件会自己用 .venv 的 Python 起知识库服务（默认 8795 端口，被占就往后找），并轮流探活、挂了自动拉起。同一个服务也提供上面第六节的网页版 /chat，不装 dsh 一样能开。

不想装 dsh 也能单独开一个库看（没有 dsh 对话，只能看图和导入）：

.venv/bin/python -m km --open                           # 按会话分库（默认 data/repos）
.venv/bin/python -m km --db data/repos/某个库.db --open  # 只看这一个文件

python -m km 的参数：--port（默认 8790）、--repos（按会话分库的文件夹）、--db（只服务这一个库文件）、--open（启动后开白板）、--chat（启动后直接开网页版的 Codex 对话页）。

卸载：./dsh-install.sh remove。

别 pip install fastnode：PyPI 上那个同名包跟本项目无关。FastNode 只从 lo2589/FastNode 源码编。

PDF 直接用本机浏览器渲染。想指定用哪个：KM_CHROME=/path/to/chrome。

---

九、一个会话一个库

没有默认库，也没有仓库切换。 白板永远只显示当前会话自己的那个库（data/repos/会话-<标题>-<尾号>.db）：会话第一次打开时建好，以后回到这个会话还是它。别的会话的库不会出现在这里，也拿不到——请求不带会话 id 时服务端直接拒绝（这个白板只属于会话…）。

绑定关系写在 data/repos/repos.json 的 sessions 里（会话 id → 库文件）。想换机器或备份，整个 data/repos/ 拷走即可。

---

十、能导入什么

导入框里填路径（文件或文件夹），或者直接粘贴文字：

网页里 KaTeX / MathJax 渲染过的公式会还原成 TeX；Jupyter 的 markdown 单元原样、代码单元带语言标记；PDF 抽文字、docx 转 Markdown。

十一、能显示什么

• 公式：$…$、$$…$$、\(…\)、\[…\]、\begin{align}…、矩阵、```math、化学式 \ce{H2O}；
• 代码高亮、表格、引用、列表、图片、链接、mermaid 流程图；
• $5 和 $10、$HOME/bin:$PATH 这种不会被误当成公式；
• 公式必须显示齐全：卡片会为宽公式让宽（到 MAX_W），还放不下就整条等比缩小（不低于 55%，再往下横向滚动并留滚动条）；每次排版后页面自己复查一遍，把「没显示全」的公式报给服务端（data/repos/selfcheck.json），所以被切掉的公式不会悄悄混过去。

显示用的库（KaTeX、markdown-it、highlight.js、DOMPurify）都在 km/web/vendor/，断网也能用。

---

十二、卡片之间的关系

正文里的链接：[[标题]]、[[标题|显示的字]]、[[#12]]（按 id）。改名后别处的引用自动跟着改；先写了 [[还没有的卡]]，等那张卡建好会自动连上；点一下链接就跳到那张卡。

十三、层级规则（严格树）

• 每个库一个根节点，所有卡都在它下面，没有游离的卡；
• 每张卡有且只有一个上级，不许转圈；
• 同一级的顺序永远是 0, 1, 2…；
• 删掉一张卡，它的下级按原来的顺序接到它的上级下面；
• 每一步都在服务端校验（check_structure），不合格直接报错，不会画出坏图。

---

十四、数据怎么存的

底层是 FastNode（克隆在同级目录 Node，SQLite 上的节点库）：

source  导入的一份资料
unit    拆出来的一句 / 一块              unit -in_source-> source
card    一张知识卡片                    card -from_unit-> unit        （出处）
                                        card -belongs_to-> card       （层级，唯一）
                                        card -<其他关系>-> card        （六种语义关系）
                                        card -mentions-> card         （正文 [[ ]] 自动维护）

卡片额外的属性：check / check_note（核对）、pos（同级顺序）、x / y（手动摆放，null 表示回到自动排版）。来源（source）上记着 dsh_session / dsh_message / dsh_turn，原文跳转就靠它们。

用 FastNode 自己的命令行也能读：../Node/target/release/fastnode data/repos/你的库.db stats。

---

十五、怎么验证的

.venv/bin/python -m unittest discover -s tests -v                 # 76 项：拆句 / 导入 / 存储 / 层级 / 接口 / 五种导出 + PDF
node --test dsh-plugin-known-manage/test/host.test.js \
           dsh-plugin-known-manage/test/pick.test.js              # 8 项：读会话、去系统注入、公式原样；选句把「第几轮」带进库；一次入库多句（真起一个知识库服务跑）
cd ../deepseek-harness && node --import tsx/esm \
  ../known_manage/tests/slot-rightbar.mjs                          # 插件进右栏「知识图」标签（没右栏时退回浮动面板）

tests/test_layout.py（7 项）是在白板自己身上量的，跑起来需要一个带 Chromium 的 Playwright；环境里没有就整文件跳过，不会假装通过：

界面上的关键动作都在真实 dsh 里点过（Playwright 驱动，含截图）：逐句入库、框选批量入库、原文翻页跳转、导出面板（含拿到 .pdf）、打印页、窄栏排版与状态保持、折叠汇总条跳转、接字带人过去。

调试用的落盘证据：data/requests.log（每个请求一行，KM_REQLOG=off 可关）、data/repos/diag.json（页面自报的右栏几何和 JS 报错）、data/repos/selfcheck.json（没显示全的公式）。

---

十六、文件

km/split.py        拆句子 / 块（标点、块、表格、编号记录；公式代码图不拆）
km/importers.py    各种格式 → Markdown（md/txt/tex/rst/html/pdf/docx/ipynb/json/jsonl/文件夹）
km/store.py        卡片、关系、严格层级、核对、合并、Markdown / Mermaid / JSON 导出（FastNode）
km/repos.py        会话各自的库（一个会话一个库，没有默认库）
km/chat.py         把 codex exec --json 驱动成网页里的对话（事件流 → 页面能画的东西）
km/chats.py        每个 Codex 对话一条记录（线程 id、目录、每轮问答）
data/images/       粘进卡片的图片（按内容命名；data/ 不进仓库）
km/pdf.py          用本机浏览器把打印页印成 PDF
km/server.py       本机 HTTP 接口 + 静态页面
km/__main__.py     python -m km --port/--repos/--db/--open
km/web/index.html  白板页面
km/web/graph.js    白板交互（折行排版、折叠汇总、接字、拖拽、框选、编辑、关系、搜索、导出面板、状态保持）
km/web/render.js   Markdown + KaTeX + 代码高亮渲染
km/web/graph.css   白板样式
km/web/print.*     打印版式 / PDF 用的那一页（print.html + print.js + print.css）
km/web/chat.*      网页版：左边 Codex 对话 + 右边知识图（chat.html + chat.js + chat.css）
km/web/vendor/     KaTeX / markdown-it / highlight.js / DOMPurify（本地，断网可用）
dsh-plugin-known-manage/
  src/host.js      dsh 宿主半边：起知识库服务、读会话文件、/plugins/known-manage/*
  src/client.js    dsh 页面半边：右栏「知识图」标签、逐句可点的回答、框选入库、原文跳转、写进对话框
  cordis.patch.yml 插件挂载点
  test/            node --test 用的测试
tests/             Python 单测（test_km.py）+ 白板几何检查（test_layout.py，要 Playwright）+ 右栏 slot 测试

HTTP 接口一览（都在 127.0.0.1，库相关的一律要带 ?s=<会话 id>）

GET    /api/canvas                 一次读全：卡片、层级、原文、关系、挂载点、资料列表（白板就用这一个）
GET    /api/structure              严格层级结构 + refs（导出 JSON 用）
GET    /api/tree  /api/board  /api/graph   树的骨架 / 画布数据 / 极简图
GET    /api/meta                   关系与核对状态的名字、统计、库名
GET    /api/export?fmt=…           markdown | mermaid | mermaid-full | json
GET    /api/mermaid                只取 Mermaid 图（严格的层级 + 语义关系），不带别的东西
GET    /api/pdf                    浏览器渲染的 A4 PDF（字节流，带下载文件名）
GET    /print                      打印版式页面（/api/pdf 和「另存为 PDF」用的就是它）
GET    /chat                       网页版：Codex 对话 + 知识图（km/web/chat.*）
POST   /api/images                 收一张图（粘/拖来的 base64，或本机路径）→ 存成 /images/xxx.png
GET    /images/<名字>              取回那张图（名字限定在图片目录里）
POST   /api/chat                   跑一轮 Codex，把事件流一行一个 JSON 地推回来（NDJSON）
GET    /api/chat/<id>              某个对话的线程、目录和每一轮
GET    /api/chats                  最近对话（网页版的「最近」）
POST   /api/pick                   一句话入库（origin：kind=dsh|codex|claude + session/message/turn/…）
POST   /api/pick-many              一批句子入库（merge=true 时合成一张）
GET    /api/picked?message=…       这条消息里哪些句子已经是卡片
GET    /api/target   POST /api/target          读 / 设挂载点
GET    /api/cards?q=…  POST /api/cards         搜卡 / 新建卡
GET    /api/cards/<id> PATCH DELETE            读 / 改标题正文 / 删（下级接到上级下）
POST   /api/cards/merge            融合两张卡（正文、原文、关系都保留）
POST   /api/cards/<id>/move        改上级 / 调同级顺序
POST   /api/cards/<id>/place       手动摆放在 x,y（null 就是回到自动排版）
POST   /api/cards/<id>/check       核对状态 + 依据
POST   /api/links  PATCH  DELETE   连 / 改关系类型 / 断开
GET    /api/sources  POST          资料列表 / 导入（text|path|folder|claude_session|file_b64|messages）
PATCH  /api/sources/<id>  DELETE   改标题 / 删（连它做的卡一起删）
GET    /api/sources/<id>/units     这份资料的句子
PATCH  /api/units/<id>  POST /api/units/merge   改句子 / 合并相邻句
POST   /api/split                  只拆句、不碰库（对话页面用它把回答切开）
GET    /api/claude-sessions        最近的本机 Claude Code 会话
GET    /api/version                页面自己的版本（改了文件就自动重载）
POST   /api/selfcheck  /api/diag   公式自查报告 / 页面自报几何与报错（只落盘，不影响画图）

dsh 插件自己的路由（由宿主半边提供）：/plugins/known-manage/status | split | pick | pick-many | picked | session。