From f2c048c79f1fd6e1ed9accca05598bca6ee83895 Mon Sep 17 00:00:00 2001 From: richblack Date: Fri, 26 Jun 2026 13:47:07 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20wiki=20=E6=8E=A1=E9=9B=86=E5=8A=A0?= =?UTF-8?q?=E3=80=8C=E8=90=83=20gloss=E3=80=8D=EF=BC=88node=20=E4=B8=80?= =?UTF-8?q?=E5=8F=A5=E8=AA=AA=E6=98=8E=EF=BC=8C=E4=BE=9B=E4=B8=8B=E6=B8=B8?= =?UTF-8?q?=E8=AA=9E=E7=BE=A9=20normalize=EF=BC=89+=20bump=201.8.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit issue #9：下游 KBDB 語義 normalize 要對「entity 名 + gloss」一起 embedding 自動 歸一同義詞，但採集只萃三元組沒萃 gloss。原則：gloss 在知識生產當下由 local CC/Cowork 建，不留給下游 ingest 臨時補（下游視角編不出好 gloss）。 - 卡片 frontmatter 加 gloss: 欄位（選填、deep tier 才產） - gloss ≠ 摘要：gloss 給機器 normalize，## 摘要 給人讀 - 對齊下游 envelope nodes[].gloss - wiki-init.md（CC）與 docs/SKILL.md（Cowork）兩路徑同步 Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 10 ++++++++++ docs/SKILL.md | 10 ++++++++++ template/.claude/VERSION | 2 +- template/.claude/commands/wiki-init.md | 11 ++++++++++- 4 files changed, 31 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f21eea6..c0d5f28 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,16 @@ --- +## 1.8.0 — wiki 採集加「萃 gloss」（每個 node 一句說明，供下游語義 normalize） + +下游 KBDB 要做語義 normalize：對「entity 名 + gloss（一句說明）」一起 embedding 求相似度自動歸一同義詞。但本地 wiki 採集只萃三元組、沒萃 gloss。原則是 gloss 該在知識生產當下由 local CC/Cowork 建（下游只有單檔／跨庫視角編不出好 gloss），不留給下游 ingest 臨時補。（issue #9） + +- **卡片 frontmatter 加 `gloss:`**：每張卡＝一個 entity/graph node，補一句機器可 normalize 的定義句。 +- **選填、deep tier 才產**：淺萃不浪費；deep 改寫時每卡補一句。 +- **gloss ≠ 摘要**：`gloss` 是 frontmatter 給機器的定義句，`## 摘要` 是給人讀的核心句，兩處兩用途。 +- **對齊下游 envelope**：`gloss:` 對應 ingest envelope 的 `nodes[].gloss`，ingest 直接取用。 +- **兩條路徑同步**：`wiki-init.md`（CC）與 `docs/SKILL.md`（Cowork）都加上，產出一致。 + ## 1.7.0 — install/update 雙語化 + 修 macOS bash 3.2 安裝崩潰 非台灣使用者看不懂中文安裝訊息（`curl | bash` 出來整片中文），加上 macOS 內建 bash 3.2 在 `set -u` 下會崩。這版一起修： diff --git a/docs/SKILL.md b/docs/SKILL.md index fa5cf95..647f78b 100644 --- a/docs/SKILL.md +++ b/docs/SKILL.md @@ -92,6 +92,7 @@ else ```markdown --- tags: [知識管理, AI協作, 方法論] +gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產） --- # 概念全名 @@ -141,6 +142,15 @@ cards// `>>` 為分隔語法，全程一致即可。這是 Karpathy LLM Wiki「知識互連」的強化版——連結不只存在，還帶類型與方向。 +### 萃 gloss（node 一句說明，供下游語義 normalize） + +每張卡＝一個 entity / graph node。deep tier 改寫時，frontmatter 補一句 `gloss:`——這個 node 是什麼的一句定義。下游 KBDB 對「entity 名 + gloss」一起做 embedding 求相似度，自動歸一同義詞（比只對名字準、比手維護 alias 表自動）。 + +- **在知識生產的當下、由整理者（CC / Cowork）建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔／跨庫視角，編不出貼合的 gloss。 +- **選填、deep tier 才產**：淺萃不浪費。 +- **gloss ≠ 摘要**：`gloss` 是 frontmatter 給機器 normalize 的定義句（「X 是…」）；`## 摘要` 是給人讀的核心句。 +- **對齊下游 envelope**：frontmatter `gloss:` 對應 ingest envelope 的 `nodes[].gloss`。 + > **改寫時必守**：① 絕不寫入 raw source（只往 `cards//` 寫，事後驗 raw source 0 異動）；② 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。 ### 使用 typed-edge 三元組（不只裸 `[[wikilink]]`） diff --git a/template/.claude/VERSION b/template/.claude/VERSION index bd8bf88..27f9cd3 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.7.0 +1.8.0 diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md index c04a87e..cbf33ff 100644 --- a/template/.claude/commands/wiki-init.md +++ b/template/.claude/commands/wiki-init.md @@ -112,11 +112,13 @@ docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,te - **保留來源指針**：每卡標 `**來源**：原文相對路徑`，為可追溯，不是要使用者回去讀。 - **frontmatter 標籤分類**（見下方）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`。 - **互相連結（typed-edge 三元組）**：`## 關聯` 不只列裸 `[[頁面]]`，改寫成帶語義的三元組（見下方）。 +- **萃 gloss（node 一句說明）**：frontmatter 放 `gloss:` —— 這張卡（= 一個 entity / graph node）的一句話定義，供下游語義 normalize（見下方）。 卡片格式（每張卡）： ```markdown --- tags: [知識管理, AI協作, 方法論] +gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產） --- # 概念全名 @@ -156,6 +158,13 @@ tags: [知識管理, AI協作, 方法論] > `>>` 是分隔語法，repo 可自選符號，但全程一致。 +**萃 gloss 規則**（issue #9，把「node 的一句說明」也預編譯，供下游 KBDB 語義 normalize）： +- **gloss = 這個 entity / graph node 是什麼的一句話**。下游對「entity 名 + gloss」一起做 embedding 求相似度，自動歸一同義詞（比只對名字準、比手維護 alias 表自動）。 +- **在知識生產的當下、由 local CC 建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔 / 跨庫視角，編不出貼合的 gloss（＝胡扯）。local scope 才有完整脈絡寫對。 +- **選填、deep tier 才產**：淺萃（只要結構）時不浪費；deep 改寫時每張卡補一句 `gloss:`。 +- **gloss ≠ 摘要**：`gloss` 是 frontmatter 裡給機器 normalize 用的定義句（「X 是…」），求精準可 embedding；`## 摘要` 是給人讀的核心一句。可相近但分屬兩處、兩用途。 +- **格式對齊下游 envelope**：frontmatter `gloss:` 對應下游 ingest envelope 的 `nodes[].gloss` 欄位，ingest 直接取用、不再回頭補。 + **INDEX.md 是標籤視圖**（非資料夾列表），`00-INDEX.md` 是桶內容器（只連不重寫，H2/H3 分節）。 頂層索引指桶子索引帶路徑：`[[pkm/00-INDEX]]`。 @@ -178,7 +187,7 @@ git status --short pages/ journals/ # 或一般專案的 docs/ ——須 0 ✅ wiki-init 完成 建立了：[列出新建的目錄和檔案] 跳過了：[列出已有因此不動的] -改寫了：[N 份原文 → M 張原子卡、K 條 typed-edge] +改寫了：[N 份原文 → M 張原子卡、K 條 typed-edge、M 條 gloss（deep tier）] 原文驗證：pages/ journals/ git status 0 異動 ✅ 下一步：用 /wiki-capture 把重要決策存進 wiki ```