diff --git a/CHANGELOG.md b/CHANGELOG.md index c3f327d..91d0136 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,17 @@ --- +## 1.11.0 — 採集規範升級：三元組抓內文實體關係 + `## 實體` 區塊（issue #11） + +從 Logseq vault 183 卡落地暴露：現行三元組只示範「卡對卡」（既有雙鏈加動詞、資訊量沒增加）；gloss 只描述卡標題一個 node，內文實體無處放描述。本升級只談採集端（卡片該寫什麼），ingest 端另立 kbdb-ingest-plugin#1。對應 SDD：wiki-architecture。 + +- **三元組改抓內文實體關係**：`原子筆記 >> 對立於 >> 傳統筆記`（A/B 是內文概念非卡標題）；卡對卡只是其中一類。 +- **卡片新增 `## 實體` 區塊**：集中列內文關鍵實體 `正規名（同義詞）— 一句描述`，供下游 embedding normalize（內文實體也是 graph node、也需描述句）。集中放、不縮排、不重複（生產者是 AI 不會邊寫邊漏）。 +- **`## 關聯` 拆兩層**：內文知識關係（端點裸文字，對應實體表）+ 卡片關係（卡對卡 `[[]]`）。內文端點裸文字避免 Logseq 紅色斷鏈。 +- **★ 端點硬自檢（Haiku 量產護欄）★**：端點必須與 `## 實體` 正規名一字不差，寫完逐條比對。實證：光寫規則 Haiku 略過、端點對不齊 14 條；寫成自檢動作後 14→0。跑 12 張才暴露的盲點。 +- **謂詞限定動詞、禁名詞**：否則 Haiku 寫出 `>> 存儲格式 >>` 讀不通的名詞謂詞。 +- 兩路徑同步：SKILL.md（Cowork）+ wiki-init.md（CC）。 + ## 1.10.1 — install 防重複安裝：已裝過一律導去 update（杜絕 wiki 並存） 實測踩到：一個裝過舊版的專案，「先跑 install、發現裝過、再跑 update」→ install 先在 system-dev/ 建了空白範本，update 的遷移看到「目的地已存在」就冪等跳過 → 真資料卡在舊 .claude/wiki/、空殼佔新位置，兩套 wiki 並存內容不同。 diff --git a/docs/SKILL.md b/docs/SKILL.md index 4bc3d55..254fb1c 100644 --- a/docs/SKILL.md +++ b/docs/SKILL.md @@ -126,10 +126,23 @@ gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用， - [自包含改寫的要點，不寫「詳見原文」] +## 實體 + +> 本卡內文的關鍵實體（也是 graph node）。名＋描述一起供下游 embedding normalize。 +> AI 生產、人不必讀；集中放、一實體一行、不縮排、不重複。 +- **原子筆記**（atomic note／卡片原子化）— 每張卡只承載一個不可再分論點的知識記錄單元。 +- **傳統筆記**（大鍋炒筆記）— 把多主題混雜在同一篇、難精確引用的記錄方式。 + ## 關聯 +### 內文知識關係（內文實體間；端點＝上方 `## 實體` 的正規名，一字不差） + +- 原子筆記 >> 對立於 >> 傳統筆記 +- 傳統筆記 >> 犧牲 >> 精確引用 + +### 卡片關係（卡對卡） + - [[本卡]] >> 謂詞（動詞短語） >> [[他卡]] -- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]] ``` ### 架構：三層 + 標籤橫切（183 卡實證） @@ -147,15 +160,22 @@ cards// - **frontmatter `tags:` 而非行內 `#tag`**：內文常用 `#`（如 `#猜想`），行內標籤會讓 ingest 分不清「分類」與「內文範例」污染 graph；frontmatter 零歧義。標籤只能用 `TAXONOMY.md` 列出的；**禁止繞過字典在卡片直接冒新標籤**，但字典可受控擴充（遇新軸先查重、確認非同義詞，再登記進本 repo 的 TAXONOMY.md）。 - **麵包屑帶路徑**：H1 次行 `← [[/00-INDEX]]`。指 `00-INDEX` 因固定名跨桶撞名，**一律帶路徑**；卡片間連結用裸 `[[卡名]]`。 -### 使用 typed-edge 三元組（不只裸 `[[wikilink]]`） +### 使用 typed-edge 三元組（抓內文實體關係，不只卡對卡） -整理時，發現內容與其他頁面有關聯，用**帶語義的三元組**寫進 `## 關聯`，而非只列裸 `[[頁面]]`。裸 `[[A]]` 只說「有關」、沒說關係，下游要建 knowledge graph 還得回讀兩張卡；三元組把關係也預編譯，ingest 直接 parse 出帶類型的有向邊。 +用**帶語義的三元組** `A >> 謂詞 >> B` 寫進 `## 關聯`。**重點是抓內文裡的實體關係**——卡對卡（`[[卡A]] >> 謂詞 >> [[卡B]]`）只是把既有雙鏈加個動詞、資訊量幾乎沒增加；知識圖譜的價值在內文概念間的關係（`原子筆記 >> 對立於 >> 傳統筆記`，這些 A/B 是內文概念、不是卡標題）。 格式 `A >> 謂詞 >> B`，規則： 1. **方向性**：必須讀成「A（謂詞）B」一句通順的話；A、B 順序＝主→賓真實方向。 -2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），天然帶方向。 -3. **謂詞自由書寫**，不受控詞彙；下游對謂詞 embedding 時同義謂詞會自動聚類，但方向仍靠書寫順序保證。 -4. **向後相容**：純 `[[A]]` 仍合法（無類型邊），盡量補謂詞。 +2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、犧牲），天然帶方向。**禁名詞當謂詞**——`>> 存儲格式 >>`、`>> 操作體驗 >>` 讀不通，是錯的。 +3. **謂詞自由書寫但別太天馬行空**：寫「參考／參照」皆可（下游 embed 自動聚類同義謂詞），別寫「瞄了一眼」這種抓不到同義的。 +4. **內文三元組端點用裸文字**（非 `[[wikilink]]`），避免在 Logseq 產生大量紅色斷鏈；卡對卡那層才用 `[[]]`。 +5. **向後相容**：純 `[[A]]` 仍合法（無類型邊），盡量補謂詞。 + +> **★ 硬自檢（Haiku 量產必備護欄）★** —— 內文三元組的「端點 = `## 實體` 詞條」 +> `A >> 謂詞 >> B` 的 A、B 必須與 `## 實體` 某個粗體正規名【一字不差】。**寫完後逐條自檢**：把 A、B 拿去 `## 實體` 找有沒有完全相同的正規名，沒有 → 這條錯了。 +> 修法擇一：(a) 改用實體表已有的詞；(b) 端點確是重要實體 → 補進 `## 實體` 再指它。 +> 禁止：端點帶括號註解、端點是整句補語、端點是形容詞短語。 +> （實證：光寫規則 Haiku 會略過，端點對不齊 14 條；寫成自檢動作後 14→0。跑 1-2 張看不出，跑 12 張才暴露。） `>>` 為分隔語法，全程一致即可。這是 Karpathy LLM Wiki「知識互連」的強化版——連結不只存在，還帶類型與方向。 @@ -166,7 +186,9 @@ cards// - **在知識生產的當下、由整理者（CC / Cowork）建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔／跨庫視角，編不出貼合的 gloss。 - **選填、deep tier 才產**：淺萃不浪費。 - **gloss ≠ 摘要**：`gloss` 是 frontmatter 給機器 normalize 的定義句（「X 是…」）；`## 摘要` 是給人讀的核心句。 -- **對齊下游 envelope**：frontmatter `gloss:` 對應 ingest envelope 的 `nodes[].gloss`。 +- **兩層 gloss**：① frontmatter `gloss:` 描述「卡標題」這個 node；② `## 實體` 區塊的每行描述句，描述「內文實體」這些 node。**內文實體也是 graph node、也需描述句**才能被下游 embedding normalize（`黃仁勳` vs `Jensen Huang` 靠描述拉近向量）。 +- **實體要描述、謂詞不用**：實體同義詞字面差遠需描述拉近；謂詞同義詞字面本就近，裸詞 embed 自動聚類。 +- **對齊下游 envelope**：frontmatter `gloss:` 與 `## 實體` 詞條對應 ingest envelope 的 `nodes[].gloss`。 > **改寫時必守**：① 絕不寫入 raw source（只往 `cards//` 寫，事後驗 raw source 0 異動）；② 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。 diff --git a/template/.claude/VERSION b/template/.claude/VERSION index e33692a..169f19b 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.10.1 \ No newline at end of file +1.11.0 \ No newline at end of file diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md index 2fcca5e..c9b0ef6 100644 --- a/template/.claude/commands/wiki-init.md +++ b/template/.claude/commands/wiki-init.md @@ -158,9 +158,16 @@ gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用， ## 重點 - [自包含改寫的要點，不依賴原文] +## 實體 +> 本卡內文的關鍵實體（也是 graph node）。名＋描述供下游 embedding normalize。集中放、一行一個、不縮排、不重複。 +- **原子筆記**（atomic note／卡片原子化）— 每張卡只承載一個不可再分論點的知識記錄單元。 +- **傳統筆記**（大鍋炒筆記）— 把多主題混雜在同一篇、難精確引用的記錄方式。 + ## 關聯 +### 內文知識關係（內文實體間；端點＝上方 `## 實體` 正規名，一字不差） +- 原子筆記 >> 對立於 >> 傳統筆記 +### 卡片關係（卡對卡） - [[本卡]] >> 謂詞（動詞短語） >> [[他卡]] -- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]] ``` **麵包屑用帶路徑 wikilink**（issue #7）：H1 次行放 `← [[/00-INDEX]]` 指回桶子索引。 @@ -175,20 +182,25 @@ gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用， - 一般開發專案的軸可不同（如 子系統／層級／決策類型），由 AI 依專案性質提出、寫進 TAXONOMY.md。 - **遇到現有軸裝不下的內容**：先查是否只是現有標籤的同義詞；確實是新軸才加進 TAXONOMY.md（附定義）再用——**禁止繞過字典在卡片直接冒新標籤**。字典是 per-repo，跨 repo 不必共用。 -**typed-edge 規則**（issue #5，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）： +**typed-edge 規則**（issue #5/#11，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）： +- **重點抓內文實體關係，不只卡對卡**：卡對卡（`[[卡A]] >> 謂詞 >> [[卡B]]`）只是既有雙鏈加動詞、資訊量幾乎沒增加；價值在內文概念關係（`原子筆記 >> 對立於 >> 傳統筆記`，A/B 是內文概念非卡標題）。 1. **方向性**：`A >> 謂詞 >> B` 必須讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓真實方向。 -2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），動詞天然帶方向。 -3. **謂詞自由書寫，不受控詞彙**：下游對謂詞 embedding 時同義謂詞會自動聚類；但方向仍靠書寫順序保證。 -4. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），盡量補謂詞。 +2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、犧牲）。**禁名詞當謂詞**——`>> 存儲格式 >>`、`>> 操作體驗 >>` 讀不通，是錯的。 +3. **謂詞自由但別太天馬行空**：「參考／參照」皆可（下游 embed 自動聚類），別寫「瞄了一眼」這種抓不到同義的。 +4. **內文三元組端點用裸文字**（非 `[[wikilink]]`），避免 Logseq 紅色斷鏈；卡對卡那層才用 `[[]]`。 +5. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），盡量補謂詞。 +> **★ 硬自檢（Haiku 量產必備）★** 內文三元組端點必須與 `## 實體` 某粗體正規名【一字不差】。**寫完逐條把 A、B 拿去 `## 實體` 比對**，沒有完全相同的 → 這條錯了，改用實體表已有的詞、或把端點補進 `## 實體` 再指它。禁止端點帶括號註解／整句補語／形容詞短語。（實證：光寫規則 Haiku 會略過，端點對不齊 14 條；寫成自檢動作後 14→0。跑 12 張才暴露。） > `>>` 是分隔語法，repo 可自選符號，但全程一致。 -**萃 gloss 規則**（issue #9，把「node 的一句說明」也預編譯，供下游 KBDB 語義 normalize）： +**萃 gloss 規則**（issue #9/#11，把「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 直接取用、不再回頭補。 +- **兩層 gloss**：① frontmatter `gloss:` 描述卡標題這個 node；② `## 實體` 每行描述句描述內文實體 node。**內文實體也是 graph node、也需描述句**才能 normalize（`黃仁勳` vs `Jensen Huang` 靠描述拉近向量）。 +- **實體要描述、謂詞不用**：實體同義詞字面差遠需描述拉近；謂詞同義詞字面本就近，裸詞 embed 自動聚類。 +- **在知識生產的當下、由 local CC 建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔 / 跨庫視角，編不出貼合的 gloss（＝胡扯）。 +- **選填、deep tier 才產**：淺萃（只要結構）時不浪費；deep 改寫時每張卡補。 +- **gloss ≠ 摘要**：`gloss` 是給機器 normalize 的定義句（「X 是…」）；`## 摘要` 是給人讀的核心一句。 +- **格式對齊下游 envelope**：frontmatter `gloss:` 與 `## 實體` 詞條對應下游 ingest envelope 的 `nodes[].gloss`，ingest 直接取用。 **INDEX.md 是標籤視圖**（非資料夾列表），`00-INDEX.md` 是桶內容器（只連不重寫，H2/H3 分節）。 頂層索引指桶子索引帶路徑：`[[pkm/00-INDEX]]`。 diff --git a/template/system-dev/VERSION b/template/system-dev/VERSION index e33692a..169f19b 100644 --- a/template/system-dev/VERSION +++ b/template/system-dev/VERSION @@ -1 +1 @@ -1.10.1 \ No newline at end of file +1.11.0 \ No newline at end of file diff --git a/template/system-dev/docs/SKILL.md b/template/system-dev/docs/SKILL.md index 4bc3d55..254fb1c 100644 --- a/template/system-dev/docs/SKILL.md +++ b/template/system-dev/docs/SKILL.md @@ -126,10 +126,23 @@ gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用， - [自包含改寫的要點，不寫「詳見原文」] +## 實體 + +> 本卡內文的關鍵實體（也是 graph node）。名＋描述一起供下游 embedding normalize。 +> AI 生產、人不必讀；集中放、一實體一行、不縮排、不重複。 +- **原子筆記**（atomic note／卡片原子化）— 每張卡只承載一個不可再分論點的知識記錄單元。 +- **傳統筆記**（大鍋炒筆記）— 把多主題混雜在同一篇、難精確引用的記錄方式。 + ## 關聯 +### 內文知識關係（內文實體間；端點＝上方 `## 實體` 的正規名，一字不差） + +- 原子筆記 >> 對立於 >> 傳統筆記 +- 傳統筆記 >> 犧牲 >> 精確引用 + +### 卡片關係（卡對卡） + - [[本卡]] >> 謂詞（動詞短語） >> [[他卡]] -- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]] ``` ### 架構：三層 + 標籤橫切（183 卡實證） @@ -147,15 +160,22 @@ cards// - **frontmatter `tags:` 而非行內 `#tag`**：內文常用 `#`（如 `#猜想`），行內標籤會讓 ingest 分不清「分類」與「內文範例」污染 graph；frontmatter 零歧義。標籤只能用 `TAXONOMY.md` 列出的；**禁止繞過字典在卡片直接冒新標籤**，但字典可受控擴充（遇新軸先查重、確認非同義詞，再登記進本 repo 的 TAXONOMY.md）。 - **麵包屑帶路徑**：H1 次行 `← [[/00-INDEX]]`。指 `00-INDEX` 因固定名跨桶撞名，**一律帶路徑**；卡片間連結用裸 `[[卡名]]`。 -### 使用 typed-edge 三元組（不只裸 `[[wikilink]]`） +### 使用 typed-edge 三元組（抓內文實體關係，不只卡對卡） -整理時，發現內容與其他頁面有關聯，用**帶語義的三元組**寫進 `## 關聯`，而非只列裸 `[[頁面]]`。裸 `[[A]]` 只說「有關」、沒說關係，下游要建 knowledge graph 還得回讀兩張卡；三元組把關係也預編譯，ingest 直接 parse 出帶類型的有向邊。 +用**帶語義的三元組** `A >> 謂詞 >> B` 寫進 `## 關聯`。**重點是抓內文裡的實體關係**——卡對卡（`[[卡A]] >> 謂詞 >> [[卡B]]`）只是把既有雙鏈加個動詞、資訊量幾乎沒增加；知識圖譜的價值在內文概念間的關係（`原子筆記 >> 對立於 >> 傳統筆記`，這些 A/B 是內文概念、不是卡標題）。 格式 `A >> 謂詞 >> B`，規則： 1. **方向性**：必須讀成「A（謂詞）B」一句通順的話；A、B 順序＝主→賓真實方向。 -2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），天然帶方向。 -3. **謂詞自由書寫**，不受控詞彙；下游對謂詞 embedding 時同義謂詞會自動聚類，但方向仍靠書寫順序保證。 -4. **向後相容**：純 `[[A]]` 仍合法（無類型邊），盡量補謂詞。 +2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、犧牲），天然帶方向。**禁名詞當謂詞**——`>> 存儲格式 >>`、`>> 操作體驗 >>` 讀不通，是錯的。 +3. **謂詞自由書寫但別太天馬行空**：寫「參考／參照」皆可（下游 embed 自動聚類同義謂詞），別寫「瞄了一眼」這種抓不到同義的。 +4. **內文三元組端點用裸文字**（非 `[[wikilink]]`），避免在 Logseq 產生大量紅色斷鏈；卡對卡那層才用 `[[]]`。 +5. **向後相容**：純 `[[A]]` 仍合法（無類型邊），盡量補謂詞。 + +> **★ 硬自檢（Haiku 量產必備護欄）★** —— 內文三元組的「端點 = `## 實體` 詞條」 +> `A >> 謂詞 >> B` 的 A、B 必須與 `## 實體` 某個粗體正規名【一字不差】。**寫完後逐條自檢**：把 A、B 拿去 `## 實體` 找有沒有完全相同的正規名，沒有 → 這條錯了。 +> 修法擇一：(a) 改用實體表已有的詞；(b) 端點確是重要實體 → 補進 `## 實體` 再指它。 +> 禁止：端點帶括號註解、端點是整句補語、端點是形容詞短語。 +> （實證：光寫規則 Haiku 會略過，端點對不齊 14 條；寫成自檢動作後 14→0。跑 1-2 張看不出，跑 12 張才暴露。） `>>` 為分隔語法，全程一致即可。這是 Karpathy LLM Wiki「知識互連」的強化版——連結不只存在，還帶類型與方向。 @@ -166,7 +186,9 @@ cards// - **在知識生產的當下、由整理者（CC / Cowork）建**：gloss 跟三元組同階段萃，**不留給下游 ingest 臨時補**——下游只有單檔／跨庫視角，編不出貼合的 gloss。 - **選填、deep tier 才產**：淺萃不浪費。 - **gloss ≠ 摘要**：`gloss` 是 frontmatter 給機器 normalize 的定義句（「X 是…」）；`## 摘要` 是給人讀的核心句。 -- **對齊下游 envelope**：frontmatter `gloss:` 對應 ingest envelope 的 `nodes[].gloss`。 +- **兩層 gloss**：① frontmatter `gloss:` 描述「卡標題」這個 node；② `## 實體` 區塊的每行描述句，描述「內文實體」這些 node。**內文實體也是 graph node、也需描述句**才能被下游 embedding normalize（`黃仁勳` vs `Jensen Huang` 靠描述拉近向量）。 +- **實體要描述、謂詞不用**：實體同義詞字面差遠需描述拉近；謂詞同義詞字面本就近，裸詞 embed 自動聚類。 +- **對齊下游 envelope**：frontmatter `gloss:` 與 `## 實體` 詞條對應 ingest envelope 的 `nodes[].gloss`。 > **改寫時必守**：① 絕不寫入 raw source（只往 `cards//` 寫，事後驗 raw source 0 異動）；② 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。