Leo
f2c048c79f
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) <noreply@anthropic.com>
179 lines
14 KiB
Markdown
179 lines
14 KiB
Markdown
# 更新紀錄 CHANGELOG
|
||
|
||
> 每次改了什麼，都記在這。版號對應 `template/.claude/VERSION`。
|
||
> 想更新到最新版？看 [README → 一鍵更新](README.md#-已安裝舊版一鍵更新)。
|
||
|
||
版號規則（語意化版本，簡化版）：
|
||
- **大版號**（1.x → 2.x）：破壞性變動，舊專案更新後可能要手動調整。
|
||
- **中版號**（1.0 → 1.1）：加了新功能，向下相容，更新即用。
|
||
- **小版號**（1.1.0 → 1.1.1）：修 bug、改文件，無新功能。
|
||
|
||
---
|
||
|
||
## 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` 下會崩。這版一起修：
|
||
|
||
- **修崩潰**：`install.sh` 在 macOS bash 3.2 下會噴 `VAULT_TYPE…: unbound variable` / `SKIPPED[*]: unbound variable`。根因是 bash 3.2 + `set -u` 展開「空陣列」會炸，加上一行多餘的 `${SKIPPED[*]}` no-op。修法：空陣列展開前先檢查、移除廢行、多位元組字串旁的變數一律用 `${VAR}` 包好（避免 `curl | bash` 串流在多位元組字元邊界被切斷而誤判變數名）。
|
||
- **install/update 訊息雙語**：依 locale 自動選語言，**預設英文**（`curl | bash` 常是 `LANG=C`，外國人預設就看得懂），`zh_TW` 自動切回繁中。
|
||
- **寫進 CLAUDE.md 的 raw source 宣告也雙語**：依 locale **只寫一種語言**進 CLAUDE.md（雙語會讓每個 session 的 context 更滿）。
|
||
- **修措辭**：一般開發案不再顯示誤導的「偵測到 vault 類型：docs」。偵測到 logseq/obsidian 筆記庫 → 出聲「會保留你的筆記結構」；不是筆記 → 默默裝完。
|
||
- **README 多語**：新增 `README.en.md`，頂部繁中 ↔ English 切換連結，利於被搜尋到。
|
||
|
||
## 1.6.1 — 釐清 taxonomy 是「受控擴充」非「凍結」
|
||
|
||
1.6.0 把標籤字典寫成「禁止自創」，措辭過嚴：碰到現有軸裝不下的新內容時，會逼 AI 硬塞錯標籤或偷偷自創，兩者都比受控擴充差。改成正確的機制：
|
||
|
||
- **禁止的是「繞過字典在卡片直接冒新標籤」，不是「新增標籤」**。字典**可擴充**。
|
||
- 流程：遇到裝不下的內容 → ① 先查既有（是真新軸還是同義詞？`知識管理` vs `KM` 別重造）→ ② 確實是新軸才登記進字典（附定義）再用。不必停下來問人，但「先查重再登記」不能省。
|
||
- **字典是 per-repo**：跨 repo 引擎靠各 repo 自己一致的 taxonomy 接合，不是逼所有 repo 共用一份。
|
||
- **新增領域軸要慎**（影響全庫聚類），形態軸擴充較安全；不確定就先用最接近的並註記「待人類複核」。
|
||
|
||
同步 `wiki-init.md`、`docs/SKILL.md`、`TAXONOMY.md` 三處措辭。
|
||
|
||
---
|
||
|
||
## 1.6.0 — wiki 完整規劃方式（183 卡實證）：三層架構 + frontmatter 標籤 + 多層索引（issue #8/#6/#7）
|
||
|
||
在一個中文 Logseq vault（234 篇 pages + journals → 183 張原子卡、571 條 typed-edge）完整跑了一輪 LLM Wiki，把「對 AI 最優」的規劃方式定案。一次納入 `wiki-init.md` 與 `docs/SKILL.md`（CC / Cowork 兩路徑一致）：
|
||
|
||
**新增**
|
||
- **三層 + 標籤橫切架構**：頂層 `INDEX.md`（標籤視圖）→ `cards/<bucket>/00-INDEX.md`（桶子索引）→ 概念原子卡。資料夾只是儲存桶，**分類由標籤承載**，不繼承原稿目錄。
|
||
- **frontmatter 標籤分類**（issue #8）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`——內文常用 `#`（如 `#猜想`），行內標籤會讓下游 ingest 分不清「分類」與「內文範例」污染 graph。雙軸 taxonomy（領域 + 形態）寫進新檔 **`TAXONOMY.md`** 當字典，**禁止自創標籤**。
|
||
- **桶子索引固定名 `00-INDEX.md`**（issue #6）：`00-` 排序最前、一眼可辨，AI 載入任何桶一律先讀它。
|
||
- **麵包屑帶路徑 wikilink**（issue #7）：卡片 H1 次行 `← [[<bucket>/00-INDEX]]`。固定名 `00-INDEX` 跨桶撞名，故指它一律帶路徑；卡片間連結仍用裸 `[[卡名]]`。
|
||
- **新檔 `template/.claude/wiki/TAXONOMY.md`**：標籤字典範本。install.sh `download_if_missing`、update.sh `keep_file`（使用者客製，永不覆蓋）。
|
||
|
||
**踩坑警語寫進 wiki-init**
|
||
- subagent 改寫時會誤把卡寫進 raw source → 目標一律給絕對路徑到 `cards/<bucket>/`，事後 `git status --short pages/ journals/` 驗證原文 0 異動。
|
||
- 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。
|
||
- 量大用 Haiku 並行改寫，主模型只切概念邊界 + 審稿 + 修斷鏈。
|
||
|
||
---
|
||
|
||
## 1.5.0 — wiki 連結升級成 typed-edge 三元組（issue #5）
|
||
|
||
**背景**：`## 關聯` 原本只列裸 `[[頁面]]`（沿用 Karpathy LLM Wiki）。但裸 `[[A]]` 是**弱連結**——只說「A 和本卡有關」，沒說關係是什麼。下游要從 wiki 抽 knowledge graph 時，拿到一堆無類型 edges，仍得回讀兩張卡才知道關係，等於關係沒被預編譯、退回 O(N²)。
|
||
|
||
**變更**
|
||
- `wiki-init.md` 與 `docs/SKILL.md` 的 `## 關聯` 升級成 **typed-edge 三元組**：`[[A]] >> 謂詞 >> [[B]]`。下游 ingest 可直接 parse 出帶類型的有向邊，全局 graph 不必再讀卡片內容就知道關係。
|
||
- 規則：① 方向性——`A >> 謂詞 >> B` 須讀成「A（謂詞）B」一句通順的話，順序＝主→賓真實方向；② 謂詞用動詞/動詞短語（天然帶方向）；③ 謂詞自由書寫不受控詞彙（下游 embedding 會聚類同義謂詞，但方向靠書寫順序保證）；④ 向後相容：純 `[[A]]` 仍合法（無類型邊）。
|
||
- `>>` 為分隔語法，repo 可自選符號，全程一致即可。
|
||
|
||
---
|
||
|
||
## 1.4.1 — wiki = AI 改寫的記憶（拿掉索引模式）+ 量大建議 Haiku（issue #4）
|
||
|
||
**修正 1.4.0 的方向**：1.4.0 把「索引 vs 改寫」做成兩種並列模式，預設一般專案走索引、只有 vault 走改寫。這方向錯了——
|
||
|
||
> **記憶系統的目的是讓 AI 之後讀得快。** 不管 vault 還是一般開發專案，人類原文都是亂的（重複、流水帳、半成品）。若 wiki 只是指回原文的索引，每次未來用都得重新解析那團亂＝沒省到。**wiki 的價值就在「改寫一次，之後每次讀都便宜」。**
|
||
|
||
**變更**
|
||
- `wiki-init.md` **拿掉索引模式**，改寫成 wiki 是**所有專案的唯一預設**（vault 與一般開發一致）。原文＝唯讀 SSoT，wiki＝AI 改寫過的記憶，AI 是總編輯。
|
||
- 唯一例外：原文是不可改動的正式文件（簽署規格／法規／合約，須逐字讀）才用指針指回原文並註明「逐字依原文」。
|
||
- **量大建議用 Haiku**：逐份原文改寫成 wiki 格式是重複、機械、判斷成本低的工作，正適合 Haiku。原文數量多時，命令會主動建議派 Haiku subagent 並行改寫，主模型只負責切概念、定條目邊界、審稿與互連。
|
||
- `INDEX.md` 範本：統一成「概念索引指向 wiki 內部條目」，不再提索引模式。
|
||
|
||
---
|
||
|
||
## 1.4.0 — wiki-init 新增「草稿改寫模式」：AI 當總編輯（issue #4）
|
||
|
||
**背景**：在 Logseq vault（234 篇 pages + journals）壓測 `/wiki-init`，發現它整套指令語言只有「分類歸檔／導航」，把人和 AI 都導向做出一個 `[[原文檔名]]` 指回原文的**索引**。但 PKM / vault 使用者的心智模型常是相反的——原文只是**草稿**（轉錄稿、隨手記），要 AI **改寫萃取成自包含 wiki**，之後讀 wiki 就好、不必回原文。template 沒區分這兩種，且預設了「原文是成品」。
|
||
|
||
**新增**
|
||
- `wiki-init.md` 開頭新增**模式分岔（第零步）**：索引模式 vs **草稿改寫模式（AI 當總編輯）**，附對照表講清楚原文角色、INDEX 連結、回答方式的差異。
|
||
- **偵測到 PKM vault（Logseq/Obsidian）→ 預設草稿改寫模式**，但明確問一句讓使用者可切回索引模式。
|
||
- **一般專案 → 預設索引模式**（維持原行為，向下相容）。
|
||
- 草稿改寫模式的產出規則（第五步）：概念原子化、自包含、保留來源指針（可追溯但不必回讀）、`[[wikilink]]` 互連——與 claude.ai Cowork 的 `docs/SKILL.md` 改寫邏輯**一致**，CC / Cowork 兩條路徑產出同一種 wiki。
|
||
- `INDEX.md` 範本：草稿模式下改成「概念索引」指向 wiki **內部**改寫條目，而非指回原文。
|
||
|
||
**不變**：raw source 永遠唯讀，兩種模式都只往 `.claude/wiki/` 寫，絕不搬移/改名原文。
|
||
|
||
---
|
||
|
||
## 1.3.1 — 修：update.sh 不再覆蓋客製的 pre-write-guard.sh（issue #3）
|
||
|
||
**修正**
|
||
- `scripts/update.sh` 原本把 `pre-write-guard.sh` 列在「覆蓋更新」區，**無條件**用模板空殼蓋掉。
|
||
但此檔的定位是「使用者手填的 guardrail 客製檔」（CHANGELOG 1.2.0），下游通常已塞滿自己的 enforcement，
|
||
且 `update_file` 覆蓋**無 `.bak` 備份**——跑一次 update 等於無聲關掉整套 guardrail（如 Arcrun 的 KNOWN_SDDS 白名單、薄殼原則強制等數百行）。
|
||
- 改法（issue 建議方案 1）：新增 `keep_with_template()`，把 `pre-write-guard.sh` 移出覆蓋區。
|
||
**原檔永不覆蓋**，改把最新模板版另存成 `pre-write-guard.template.sh` 旁邊，更新結尾印出 `diff` 指令供使用者自行採納。
|
||
首次安裝（原檔不存在）才會直接抓本體。`install.sh` 路徑本就用 `download_if_missing`（已存在即跳過），無此問題。
|
||
|
||
---
|
||
|
||
## 1.3.0 — vault 偵測（Logseq / Obsidian）+ Cowork 整理 skill
|
||
|
||
**新增**
|
||
- `install.sh` 在建立 `CLAUDE.md` 前**自動偵測資料夾類型**，把對應的「原始文件來源（raw source）」寫進 `CLAUDE.md`：
|
||
- `logseq/` → raw source `pages/`、`journals/`
|
||
- `.obsidian/` → raw source 根目錄下所有 `.md`
|
||
- 都沒有 → `docs/`（維持原行為）
|
||
寫入的宣告是給 AI 讀的指令，對 vault **明令不得搬動/改名/重新分類 `.md`**，整理結果一律只寫進 `.claude/wiki/`，
|
||
面對筆記 vault 不會破壞它原本的結構。已有 `CLAUDE.md` 一律不覆蓋，改在結尾列出該補的宣告提醒手動貼。
|
||
- `docs/SKILL.md`：給 **claude.ai Cowork** 的 `wiki-cowork-scan` skill。
|
||
與 CC 的 `/wiki-init`、`/wiki-capture` 共用同一套規則，用**與 install.sh 一致的偵測邏輯**掃描
|
||
`~/Documents` 下所有裝了本模板的資料夾，只讀 raw source、只往 `.claude/wiki/` 增補（不覆蓋、不刪除），
|
||
絕不動 raw source、`CLAUDE.md`、`logseq/`、`.obsidian/`、`assets/`。讓整理 wiki 不再只限終端機裡的 CC。
|
||
|
||
**變更**
|
||
- README 新增「不只程式碼，也認得 Logseq / Obsidian vault」「Cowork 也能整理 wiki」兩節，並更新目錄樹。
|
||
|
||
---
|
||
|
||
## 1.2.0 — GitHub issue 指引 + pre-write-guard 定位釐清
|
||
|
||
**新增**
|
||
- `/issue-handle` slash command（`template/.claude/commands/issue-handle.md`）：
|
||
CC 處理 GitHub issue 的普世指引，三層界線——
|
||
①讀/回/結案自己 repo 的 issue（直接做）；
|
||
②發 issue 給別的 repo（先問人，不擅自）；
|
||
③**禁止掛 Actions/cron/webhook 自動輪詢 issue**（會觸發 GitHub 異常偵測、被 rate limit）。
|
||
屬共用指引，install/update 不分模組都裝。（issue #1）
|
||
|
||
**變更**
|
||
- `pre-write-guard.sh` 釐清定位（issue #2）：它是「按需手填的空插槽」，不是裝上就生效的警察。
|
||
- 檔頭明講：**有 CC 在場時，直接叫 CC 寫貼合的 guard hook 更好**，這個空殼範本只對「手動 DIY」用戶有價值。
|
||
- 解決安全錯覺：install.sh / update.sh 安裝它時提示「預設不攔任何東西，要手填+掛 settings 才生效」，
|
||
讓用戶不會誤以為裝了就有保護。（hook 執行時維持安靜，避免每次 Write 洗版。）
|
||
|
||
---
|
||
|
||
## 1.1.0 — 一鍵更新
|
||
|
||
**新增**
|
||
- `scripts/update.sh`：已安裝舊版的人，一行指令更新到最新版。
|
||
只覆蓋模板/邏輯檔（hooks、commands、TEMPLATE-*），**完全不碰**使用者資料
|
||
（`wiki/status.md`、`mistakes.md`、`decisions-summary.md`、`.wikiignore`、`settings.json`、`CLAUDE.md`）。
|
||
會先比對版本、列出新功能、依已裝模組自動偵測該更新什麼，跑完自我更新。
|
||
- `template/.claude/VERSION`：版本基準檔，讓「檢查新版」有依據。
|
||
- `CHANGELOG.md`（本檔）。
|
||
|
||
**第一次更新的雞生蛋問題**：舊版本機還沒有 `update.sh`，所以第一次靠 README 那行
|
||
`curl` 從遠端抓更新器來跑；跑完它把自己裝進 `scripts/update.sh`，之後直接跑本機的即可。
|
||
|
||
---
|
||
|
||
## 1.0.0 — 模組化安裝（基準版）
|
||
|
||
此版本之前無 VERSION 檔，以下為依 git 歷史回溯的功能基準。
|
||
|
||
- `scripts/install.sh` 模組化安裝：`--wiki` / `--sdd` / `--all`，無參數則互動詢問。
|
||
- **LLM Wiki**：CC 記憶系統（INDEX / status / mistakes / decisions-summary）
|
||
+ 接關 hook（session-start-recall）+ 對應 slash commands。
|
||
- **wiki 機敏防護三層**：`.wikiignore`（檔案層）＋行內標記（局部）＋
|
||
`wiki-secret-scan.sh`（機械兜底攔截）。
|
||
- **SDD 強制**：動 code 前必須有 `design.md`，由 `sdd-guard.sh` hook 把關，附 TEMPLATE 範本。
|
||
- docs 分類結構（1-vision ~ 6-user）與 ADR 範本。
|