Leo/system-dev-template
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e097c02b9dae8f2a172a218b564f821b3887d5f0
system-dev-template/CHANGELOG.md
T
Leo e097c02b9d fix: 修 1.8.x 舊腳本升級撞 404 + VERSION 被污染 + bump 1.9.1 
1.9.0 把 VERSION 搬到 system-dev/，但 1.8.x 舊用戶本機 update.sh 寫死抓舊路徑,
curl 對 404 把「404:NotFound」當內容寫進 VERSION,且第一次跑不遷移。

- 發佈源保留相容墊片 template/.claude/VERSION(與 system-dev/VERSION 同步)
- 新 update.sh 驗 REMOTE_VER 須像 X.Y.Z,否則視為取不到,永不寫進 VERSION
  (404/HTML/空 全擋,未來路徑變動也不會再污染版號)

照 README curl main/scripts/update.sh 升級者抓遠端新腳本、一次遷移不受影響;
只有跑本機舊 scripts/update.sh 才中,這版修掉。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 15:27:55 +08:00

219 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 更新紀錄 CHANGELOG
> 每次改了什麼，都記在這。版號對應 `template/.claude/VERSION`。
> 想更新到最新版？看 [README → 一鍵更新](README.md#-已安裝舊版一鍵更新)。
版號規則（語意化版本，簡化版）：
- **大版號**（1.x → 2.x）：破壞性變動，舊專案更新後可能要手動調整。
- **中版號**（1.0 → 1.1）：加了新功能，向下相容，更新即用。
- **小版號**（1.1.0 → 1.1.1）：修 bug、改文件，無新功能。
---
## 1.9.1 — 修舊版（1.8.x）升級到 1.9.0 撞 404 + VERSION 被污染
1.9.0 把 VERSION 從 `template/.claude/VERSION` 搬到 `template/system-dev/VERSION`，但 1.8.x 舊用戶**本機的** update.sh 寫死抓舊路徑 → `curl` 對 404 會把「404: Not Found」當內容回傳（非空），舊腳本沒驗證就把它寫進 `.claude/VERSION`，畫面顯示 `Latest version: 404:NotFound`、且第一次跑不會遷移（要再跑一次）。
- **發佈源保留相容墊片** `template/.claude/VERSION`：讓 1.8.x 舊腳本仍抓得到版號、不再 404。（bump 時與 `system-dev/VERSION` 同步）
- **新版 update.sh 加版號格式驗證**：`REMOTE_VER` 必須像 `X.Y.Z`，否則（404 字串／HTML 錯誤頁／空）一律視為「取不到」，永不寫進 VERSION。未來任何路徑變動都不會再污染版號檔。
- 提醒：照 README 那行 `curl … main/scripts/update.sh | bash` 升級的人本就抓遠端新腳本、一次遷移成功不受影響；只有手動跑**本機舊** `bash scripts/update.sh` 才會遇到，這版一併修掉。
## 1.9.0 — 安裝結構收進 `system-dev/`（不再污染用戶根目錄）+ 舊版自動遷移
工具產物原本散在用戶根目錄（`docs/` 七層、update 時的 `scripts/`），又把 `wiki/`、`VERSION` 寄生在 CC 原生的 `.claude/` 裡，用戶分不清「哪個 docs 是工具的、哪個是我的」。這版徹底收斂：除了 CC 死綁的 `.claude/`（settings/commands/hooks）和 `CLAUDE.md` 留根，**工具所有資料收進 `system-dev/`**。對應 SDD：`system-dev/docs/3-specs/install-layout/`。
- **新結構**：`system-dev/{VERSION, wiki/, docs/, scripts/}`。`.claude/` 只剩 CC 機制檔。
- **wiki 改寫產物落點正式化**：install 直接建 `system-dev/wiki/cards/`（含 `.gitkeep`），不再讓用戶自己長出來、自行 git init。
- **docs 雙語義拆開**：工具文件 → `system-dev/docs/`；**用戶 raw source（原始文件來源）維持原處**（用戶的 `docs/`、Logseq `pages/+journals/`、Obsidian vault），工具只讀、不搬。
- **scripts 一開始就裝**：install 把 install.sh/update.sh 放進 `system-dev/scripts/`，之後更新直接 `bash system-dev/scripts/update.sh`。
- **舊版自動遷移（雙保險）**：① update.sh 偵測舊位置 → 冪等搬進 `system-dev/`（wiki 含 `cards/` 與內含 `.git` 一起搬，docs 只搬工具白名單、不動用戶自填內容）；② session-start hook 偵測到舊結構未遷移 → 出聲提示，CC 可當場代為遷移。給「只會叫 CC 做事」的 low-code 用戶兜底。
- **機敏防護路徑跟進**：`wiki-secret-scan.sh` 觸發路徑改 `system-dev/wiki/**`（否則新結構下寫入不啟動、防護失效）。
- 全套路徑引用同步更新：CLAUDE.md、SKILL.md、wiki-init、wiki-recall、wiki-capture、sdd-check、sdd-guard、session-start-recall、INDEX、decisions-summary、README（中英）。
> **升級提醒**：舊用戶跑一次 `update.sh` 即自動遷移；沒跑也會在開 session 時被 hook 提示。屬向下相容的中版號（非破壞性手動遷移）。
## 1.8.2 — 修 update.sh 在 `curl | bash` 下崩潰（bash 3.2 多位元組字元，1.7.0 漏修到的同類 bug）
1.7.0 修了 install.sh 的「多位元組字元旁變數要用 `${VAR}` 包」，但 update.sh 第 54 行漏網：
`已是最新版（$LOCAL_VER）` 的中文全形括號緊貼裸變數 `$LOCAL_VER`，`curl | bash` 串流在多位元組
邊界切斷時，bash 3.2 把後續位元組誤當變數名 → `LOCAL_VER�: unbound variable` 崩潰。偏偏觸發點在
「本機版本＝遠端版本」分支，所以「以為沒更新、再跑一次」必中。
- 第 54-55 行 `$LOCAL_VER` → `${LOCAL_VER}`。已用 bash `set -u` 模擬該分支驗證不再崩。
## 1.8.1 — 補裝 Cowork 的 wiki skill（`docs/SKILL.md`）+ CLAUDE.md 加 wiki/gloss 導航
發現 Cowork（claude.ai）整理 wiki 的規則檔 `docs/SKILL.md`（含 typed-edge、frontmatter 標籤、**gloss**）**從來沒被安裝到用戶端**：install.sh 沒下載它，連 `template/docs/` 發佈源都缺這檔 → claude.ai 來掃時身上沒任何 wiki 規則。同時 CC 平時讀的 CLAUDE.md 沒指向採集規則，導致「CC 說找不到 gloss 指引」。這版把兩條路徑都補上。
- **補發佈源**：`template/docs/SKILL.md` 新增（從根 docs 同步），install.sh 才有得下載。
- **install.sh**：wiki 模組加一行下載 `docs/SKILL.md`。
- **update.sh**：加 `update_file docs/SKILL.md`，舊專案更新會帶上（規則檔，可覆蓋）。
- **CLAUDE.md 模板**：新增「整理 wiki 的方法」導航段，明示 CC（`/wiki-init`）與 Cowork（`docs/SKILL.md`）的採集規則所在地，gloss 不再「藏」在指令內文裡讓 CC 找不到。
## 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 範本。
Reference in New Issue View Git Blame Copy Permalink