chore(wiki): 導入 system-dev-template + 合併 wiki 到新位置
- system-dev/ 模板包進版控（VERSION/docs/scripts/wiki 骨架） - 逐檔合併舊 .claude/wiki/ → system-dev/wiki/： - status/mistakes/decisions-summary 真資料覆蓋空範本 - INDEX 新「多角度視圖」結構 + 舊決策/導航併入（過時詞「萬物皆 Block」改 API-as-Wall） - principles/TAXONOMY 為新位置獨有，保留 - 刪舊 .claude/wiki/（git 識別為 rename，內容完整搬移） - 三層機敏防護 hooks + wiki 命令更新 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
---
|
||||
description: 處理本 repo 的 GitHub issue（讀/回/結案），跨 repo 發要先問人
|
||||
---
|
||||
|
||||
# /issue-handle — GitHub issue 處理指引
|
||||
|
||||
你（CC）可以、也該主動用內建的 `gh` CLI 讀寫**自己 repo** 的 GitHub issue。
|
||||
很多人不知道這件事——`gh` 已內建認證，零開發、零外部依賴。issue 同源於 repo，
|
||||
比 Notion / Sheets 更適合做交辦與待辦，不必引入外部 SaaS。
|
||||
|
||||
這份指引分三層，界線要守住。
|
||||
|
||||
---
|
||||
|
||||
## 1. 讀 / 回 / 結案（普世基本功 — 直接做，不用問）
|
||||
|
||||
對**自己這個 repo**，主動處理 open issue：
|
||||
|
||||
```bash
|
||||
gh issue list --state open # 看有哪些待辦
|
||||
gh issue view <n> # 讀完整內容
|
||||
# …實作…
|
||||
gh issue comment <n> --body "做了什麼、怎麼決定的、改了哪些檔"
|
||||
gh issue close <n> # 確認解決後結案
|
||||
```
|
||||
|
||||
回覆要有料：說清楚**做了什麼、為什麼這樣決定、動了哪些檔**，而不是只回「done」。
|
||||
issue 作者（可能是另一個 repo 的 CC，或人類）要靠你的回覆判斷對不對。
|
||||
|
||||
---
|
||||
|
||||
## 2. 發 issue 給「別的 repo」（要先問人 — 不可擅自）
|
||||
|
||||
當你發現**別的 repo** 有值得修正的地方時：
|
||||
|
||||
> ❌ 不要擅自 `gh issue create -R other/repo …`
|
||||
> ✅ 先問人類：「我發現 X repo 有 Y 問題，要我幫你去那邊發 issue 嗎？」得到同意才發。
|
||||
|
||||
理由：通用 template 不知道使用者對那個 repo 有沒有權限、想不想發。留一道人類確認最安全。
|
||||
（對**自己 repo** 開 issue 記待辦則可直接做——那是自己的 repo。）
|
||||
|
||||
---
|
||||
|
||||
## 3. flag 安全界線（最重要 — 絕不可越）
|
||||
|
||||
**「有事才讀」，禁止自動輪詢。**
|
||||
|
||||
- ✅ 想看 issue → 當下主動 `gh issue list`。
|
||||
- 🚫 **禁止**掛 GitHub Actions / cron / webhook 去**自動輪詢** issue。
|
||||
|
||||
為什麼這條是硬底線：自動輪詢 + 事件 fan-out 正是會觸發 GitHub 異常偵測、
|
||||
害你的 token 被 rate limit 砍掉的流量模式。template 給很多人用，這條界線必須守住，
|
||||
保護使用者不踩雷。需要「定期檢查」就由人類主動跑這個指令，不要自動化。
|
||||
|
||||
---
|
||||
|
||||
## （可選）用 label 分來源
|
||||
|
||||
若想用同一套流程同時管「內部交辦」與「外部回報」，可建兩個 label：
|
||||
`internal`（協作/交辦）、`user`（外部使用者回報），靠 label 分流。
|
||||
這對通用 template 不預設——你的 repo 需要再建。
|
||||
@@ -15,7 +15,7 @@
|
||||
|
||||
### 第二步：尋找對應 SDD
|
||||
|
||||
在 `docs/3-specs/` 下尋找對應的子系統目錄，確認有沒有：
|
||||
在 `system-dev/docs/3-specs/` 下尋找對應的子系統目錄，確認有沒有：
|
||||
- `design.md`（設計文件）
|
||||
- `tasks.md`（任務清單）
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
|
||||
**情況 A：找到對應 SDD**
|
||||
```
|
||||
✅ 找到 SDD：docs/3-specs/[子系統]/
|
||||
✅ 找到 SDD：system-dev/docs/3-specs/[子系統]/
|
||||
📋 design.md：[確認]
|
||||
📋 tasks.md：[確認，列出相關 task]
|
||||
🎯 對應 task：[編號和描述]
|
||||
@@ -34,7 +34,7 @@
|
||||
```
|
||||
⚠️ 找不到對應 SDD
|
||||
任務：[描述]
|
||||
建議在 docs/3-specs/[建議子系統名]/ 建立 SDD
|
||||
建議在 system-dev/docs/3-specs/[建議子系統名]/ 建立 SDD
|
||||
|
||||
要我幫你起草 design.md 嗎？（需要你確認後才動手）
|
||||
```
|
||||
|
||||
@@ -7,13 +7,21 @@
|
||||
|
||||
## 執行流程
|
||||
|
||||
### 第零步：機敏檢查（寫入前一律先過）
|
||||
|
||||
把任何內容寫進 wiki 前，先確認**不含**密碼 / API 金鑰 / 私鑰 / 連線字串帳密 / 個資（身分證、信用卡）。
|
||||
- 命中 → 不要記「值」，改記「位置」（例：「DB 密碼放 `.env`，不入 wiki」）
|
||||
- 來源整檔機敏 → 提醒使用者加進 `system-dev/wiki/.wikiignore`
|
||||
- 真要保留示範格式 → 該行尾加 `wiki-secret-ok` 標記
|
||||
> 這是協議層自律。最後一道 `wiki-secret-scan.sh` hook 會在寫入 `system-dev/wiki/` 時機械攔截，但別依賴它兜底——當場就不要把機敏值帶進來。
|
||||
|
||||
### 第一步：辨識對話中的可記錄內容
|
||||
|
||||
掃描當前對話，找出：
|
||||
|
||||
| 類型 | 判斷標準 | 存到哪 |
|
||||
|------|---------|-------|
|
||||
| 架構決策 | 「為什麼選A不選B」「我們決定用X」 | `decisions-summary.md` + `docs/2-architecture/decisions/` |
|
||||
| 架構決策 | 「為什麼選A不選B」「我們決定用X」 | `decisions-summary.md` + `system-dev/docs/2-architecture/decisions/` |
|
||||
| CC 的誤解被糾正 | CC 說了某件事，使用者說「不是，是...」 | `mistakes.md` |
|
||||
| 重要狀態更新 | 完成了某件事、阻擋了某件事 | `status.md` |
|
||||
| 技術發現 | 踩到坑、找到解法、重要行為確認 | `mistakes.md` 或對應 SDD |
|
||||
@@ -51,10 +59,10 @@
|
||||
## [主題] — [YYYY-MM-DD]
|
||||
**結論**：[一句話]
|
||||
**原因**：[簡短說明]
|
||||
**詳細**：docs/2-architecture/decisions/[檔名]
|
||||
**詳細**：system-dev/docs/2-architecture/decisions/[檔名]
|
||||
```
|
||||
|
||||
重大決策同時在 `docs/2-architecture/decisions/` 建立 ADR 檔案。
|
||||
重大決策同時在 `system-dev/docs/2-architecture/decisions/` 建立 ADR 檔案。
|
||||
|
||||
### 第四步：確認
|
||||
|
||||
|
||||
+168
-27
@@ -1,7 +1,25 @@
|
||||
# /wiki-init — 初始化或接入 LLM Wiki 系統
|
||||
|
||||
初始化這個專案的 LLM Wiki 記憶系統。
|
||||
新專案建立空白結構，已有專案掃描現有文件並建立 wiki。
|
||||
新專案建立空白結構，已有專案掃描現有文件並**改寫**成 wiki。
|
||||
|
||||
---
|
||||
|
||||
## 核心概念：wiki 是 AI 改寫過的記憶，不是原文索引
|
||||
|
||||
記憶系統的目的，是讓 AI **之後讀得快**。但人類寫的原始文件——不管是 vault 的隨手記、開發專案的會議記錄、規格草稿、散落的 `.md`——天生是亂的：重複、流水帳、半成品、口語。
|
||||
|
||||
如果 wiki 只是一份 `[[原文檔名]]` 指回原文的**索引**，那每次未來要用都得重新解析那團亂，等於沒省到。**wiki 的價值在於「改寫一次，之後每次讀都便宜」**。
|
||||
|
||||
所以原則對**所有專案**一致（不分 vault 或一般開發）：
|
||||
|
||||
> 人類寫的原文是 **SSoT**（真理來源，永遠唯讀）。
|
||||
> 但實際要長期保存、被 AI 反覆讀的是 **AI 改寫整理過的 wiki**。
|
||||
> **AI 是總編輯**——把原文改寫成自包含、概念原子化、互相連結、適於 AI 讀的知識條目。
|
||||
|
||||
唯一例外：原文是**不可改動的正式文件**（簽署過的規格、法規、合約），必須逐字讀原文——這種才在 wiki 裡用指針指回去，並註明「逐字依原文」。除此之外，一律改寫。
|
||||
|
||||
**raw source 永遠唯讀**：所有產出只往 `system-dev/wiki/` 寫，絕不改動、搬移、重新命名原文。
|
||||
|
||||
---
|
||||
|
||||
@@ -10,45 +28,93 @@
|
||||
### 第一步：偵測專案狀態
|
||||
|
||||
檢查以下項目，判斷是新專案還是已有專案：
|
||||
- 根目錄有沒有 `.claude/wiki/`
|
||||
- 根目錄有沒有 `docs/`
|
||||
- 根目錄有沒有 `system-dev/wiki/`
|
||||
- 根目錄有沒有 `docs/`（或 vault 的 `pages/`、`journals/`、根目錄 `.md`）
|
||||
- 有沒有散落的 `.md` 檔案
|
||||
|
||||
同時**偵測 raw source 路徑**（同 install.sh 邏輯）：
|
||||
- 根目錄有 `logseq/` → Logseq vault，raw source = `pages/` + `journals/`
|
||||
- 根目錄有 `.obsidian/` → Obsidian vault，raw source = 根目錄所有 `.md`
|
||||
- 都沒有 → 一般專案，raw source = `docs/` 下所有 `.md`（及散落的 `.md`）
|
||||
|
||||
**新專案**（幾乎空的）→ 直接建立結構，跳到第三步
|
||||
**已有專案**（有文件）→ 執行第二步
|
||||
|
||||
### 第二步：已有專案的掃描（已有專案才執行）
|
||||
|
||||
1. 遞迴找出所有 `.md` 檔案
|
||||
2. 對每個檔案標注建議位置和信心度
|
||||
3. 列出清單給使用者確認，**停下來等確認**
|
||||
1. 遞迴找出 raw source 裡所有 `.md` 檔案
|
||||
2. **先套用 `system-dev/wiki/.wikiignore`**：命中 pattern 的檔案整個排除，不讀不編入。
|
||||
- 若 `.wikiignore` 不存在，從範本建立一份（預設排除 `.env`/`*.pem`/`*secret*` 等）
|
||||
- 被排除的檔案在清單裡標「🚫 .wikiignore 排除」，**不可被覆蓋**
|
||||
3. 對其餘檔案標注**改寫計畫**：會萃取成哪些 wiki 條目。一份原文可能拆成多個概念原子條目，多份相關原文也可能合併成一條。
|
||||
4. 列出清單給使用者確認，**停下來等確認**
|
||||
|
||||
分類規則：
|
||||
```
|
||||
有明確子系統 + 設計內容 → docs/3-specs/[子系統]/
|
||||
解釋為什麼做某個決定 → docs/2-architecture/decisions/
|
||||
說明怎麼操作 → docs/4-guides/
|
||||
記錄發生過的事 → docs/5-records/
|
||||
給外部使用者看的 → docs/6-user/
|
||||
不確定 → 列為「待確認」，問使用者
|
||||
```
|
||||
> **量大時建議用 Haiku 改寫**：逐份原文「改寫成 wiki 格式」是重複、機械、判斷成本低的工作——正適合 Haiku。原文數量多（如數十、上百份）時，主動建議：
|
||||
> 「共 N 份原文要改寫，這類逐份萃取很適合用 Haiku 並行處理（便宜、夠快）。要我派 Haiku subagent 改寫嗎？」
|
||||
> 得同意後，用 Task / subagent 把每份原文（或每批）丟給 Haiku 改寫，主模型只負責切分概念、定條目邊界、最後審稿與互連。
|
||||
|
||||
> 機敏防護（三層）：
|
||||
> - **L1 .wikiignore**：整檔排除（這一步）
|
||||
> - **L2 行內標記**：檔案要編入但某段不要 → 遇到 `<!-- wiki:ignore -->` … `<!-- wiki:end -->` 之間的內容**略過**，只留「（此處機敏，已略過）」
|
||||
> - **L3 hook**：萬一機敏值仍被寫進 wiki，`wiki-secret-scan.sh` 會 exit 2 擋下
|
||||
> 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。
|
||||
|
||||
### 第三步：建立缺少的結構
|
||||
|
||||
只建立不存在的目錄和檔案，**已有的一律不動**：
|
||||
只建立不存在的目錄和檔案，**已有的一律不動**。
|
||||
|
||||
wiki 採**三層 + 標籤橫切**架構（183 卡實證，issue #8）：
|
||||
|
||||
目錄：
|
||||
```
|
||||
docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}
|
||||
.claude/wiki/
|
||||
system-dev/wiki/
|
||||
├── INDEX.md ← 索引：多角度視圖的家（標籤角度、決策角度、…）
|
||||
├── TAXONOMY.md ← 標籤字典（cards 的分類元資料，受控擴充）
|
||||
├── status.md ← [push] 時態狀態：當前進度、下一步
|
||||
├── mistakes.md ← [push] 踩過的坑、被糾正的誤解（防不自覺盲區）
|
||||
├── principles.md ← [push] 跨全局的設計原則（行動前必服從）
|
||||
└── cards/ ← [pull] 一切知識內容：原文摘要、AI 筆記、決策、概念…
|
||||
└── <bucket>/ ← 儲存桶（分類由 frontmatter 標籤承載）
|
||||
├── 00-INDEX.md ← 桶子索引（固定名，容器：只連不重寫，H2/H3 分節）
|
||||
└── <概念全名>.md ← 概念原子卡（一概念一檔，自包含）
|
||||
```
|
||||
|
||||
> **[push] / [pull] 是這套 wiki 的核心判準——因為 wiki 主要是給 AI（CC）看的。**
|
||||
> 見下方「核心判準：push vs pull」。`decisions-summary.md` 已**降級為 cards + INDEX 決策視圖**（決策是知識內容＝card）；既有的 decisions-summary 若存在，保留為相容，不刪。
|
||||
|
||||
關鍵原則：**資料夾只是儲存桶，分類由 frontmatter 標籤承載**。資料夾名不該硬繼承原稿目錄——原稿目錄是「人為了整理草稿」分的，wiki 連分類都該由 AI 重新組織。
|
||||
|
||||
> **桶子索引固定叫 `00-INDEX.md`**（issue #6）：`00-` 前綴讓它排序最前、一眼可辨（像 README 之於資料夾），AI 載入任何 `cards/<bucket>/` 一律先讀它，不必猜。檔內 H1 仍寫主題名（如 `# PKM 知識管理`），語意不丟。
|
||||
|
||||
一般專案仍可同時建 `system-dev/docs/` 分類樹（SDD 等）：
|
||||
```
|
||||
system-dev/docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}
|
||||
```
|
||||
（純 PKM vault 不需要 `system-dev/docs/` 分類樹時，只建 `system-dev/wiki/`。）
|
||||
|
||||
檔案（不存在才建）：
|
||||
- `.claude/wiki/INDEX.md`
|
||||
- `.claude/wiki/status.md`
|
||||
- `.claude/wiki/mistakes.md`
|
||||
- `.claude/wiki/decisions-summary.md`
|
||||
- `docs/README.md`
|
||||
- `system-dev/wiki/INDEX.md`、`TAXONOMY.md`
|
||||
- `system-dev/wiki/status.md`、`mistakes.md`、`principles.md`（三個 push 檔）
|
||||
- `system-dev/docs/README.md`（一般專案才需要）
|
||||
|
||||
---
|
||||
|
||||
## 核心判準：push vs pull（wiki 是給 AI 看的）
|
||||
|
||||
整理任何內容前，先判斷它該 **push** 還 **pull**——判準是「**CC 做事時會不會被動看見**」：
|
||||
|
||||
- **push**：CC 行動前必須主動出現在 context（session 開始就由 hook 注入）。給「CC 不會主動去查、但不看就出事」的東西。
|
||||
- **pull**：CC 想到要查、或載入相關卡時才看見。給「CC 面對它時自然會查」的知識。
|
||||
|
||||
**為什麼這是核心**：mistakes 防的是 CC「不自覺的盲區」——一個你不知道存在的錯，你不會主動去檢索它。靠 CC 自覺去查自己沒自覺的盲區是自相矛盾的，所以 pull 對盲區失效，**必須 push**。原則同理：沒被推到眼前的準繩，CC 設計時很可能沒想到要服從就做了。
|
||||
|
||||
| 內容 | push/pull | 注入形態（hook）|
|
||||
|------|-----------|----------------|
|
||||
| **status** | push | **全文**——CC 必須知道精確的下一步，摘要會漏 task 編號 |
|
||||
| **principles** | push | **全文（一行一條）**——短而硬的約束，漏一條就違反；≤15 條，超過代表該下放成 card |
|
||||
| **mistakes** | push | **標題清單 + 一行症狀**，全文按需 pull——量可能大，摘要足以觸發「我正撞到某條」的認出 |
|
||||
| **decisions、原文摘要、概念知識、一切其餘** | pull | 寫成 cards；CC 面對時自然會查，INDEX 提供角度入口 |
|
||||
|
||||
**principles 維護規則**：一行一條精煉準繩（如「不污染用戶根目錄」「目標用戶 low-code」「wiki 主要給 AI 看」）。發現新的跨全局原則 → append 一行；超過 ~15 條代表某些該合併或下放成 card。**累積原則只改 principles.md，不必問用戶開新檔。**
|
||||
|
||||
### 第四步：訪談（每次一個問題）
|
||||
|
||||
@@ -60,18 +126,93 @@ docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,te
|
||||
|
||||
把答案填進 `CLAUDE.md`（如果存在）或建立新的。
|
||||
|
||||
### 第五步：已有專案的文件歸檔
|
||||
### 第五步：改寫成 wiki（AI 當總編輯）
|
||||
|
||||
（第二步確認後執行）
|
||||
|
||||
按照確認好的分類移動檔案，完成後更新 `CLAUDE.md` 的路徑引用。
|
||||
**不搬動原文**。逐份讀 raw source，改寫萃取成 `cards/<bucket>/` 裡的自包含原子卡：
|
||||
|
||||
### 第六步：完成報告
|
||||
- **概念原子化**：一張卡講一個概念，不是一篇原文對一張卡。原文太雜就拆，多份相關原文就合。
|
||||
- **自包含**：讀卡就懂，不必回去翻原文。把口語、重複、流水帳改寫成結構化知識，**不寫「詳見原文」**。
|
||||
- **保留來源指針**：每卡標 `**來源**：原文相對路徑`，為可追溯，不是要使用者回去讀。
|
||||
- **frontmatter 標籤分類**（見下方）：分類走 frontmatter `tags:`，不靠資料夾、不靠行內 `#tag`。
|
||||
- **互相連結（typed-edge 三元組）**：`## 關聯` 不只列裸 `[[頁面]]`，改寫成帶語義的三元組（見下方）。
|
||||
- **萃 gloss（node 一句說明）**：frontmatter 放 `gloss:` —— 這張卡（= 一個 entity / graph node）的一句話定義，供下游語義 normalize（見下方）。
|
||||
|
||||
卡片格式（每張卡）：
|
||||
```markdown
|
||||
---
|
||||
tags: [知識管理, AI協作, 方法論]
|
||||
gloss: 一句話定義這個概念是什麼（給下游語義 normalize 用，選填、deep tier 才產）
|
||||
---
|
||||
# 概念全名
|
||||
|
||||
← [[<bucket>/00-INDEX]]
|
||||
|
||||
**來源**：`[raw source 相對路徑]`
|
||||
**最後更新**：YYYY-MM-DD
|
||||
|
||||
## 摘要
|
||||
[一句話核心]
|
||||
|
||||
## 重點
|
||||
- [自包含改寫的要點，不依賴原文]
|
||||
|
||||
## 關聯
|
||||
- [[本卡]] >> 謂詞（動詞短語） >> [[他卡]]
|
||||
- [[原子筆記]] >> 是其最小單元 >> [[卡片盒筆記法]]
|
||||
```
|
||||
|
||||
**麵包屑用帶路徑 wikilink**（issue #7）：H1 次行放 `← [[<bucket>/00-INDEX]]` 指回桶子索引。
|
||||
桶子索引固定名 `00-INDEX` 跨桶會撞名，故**指 00-INDEX 一律帶路徑**（`[[pkm/00-INDEX]]`，Logseq 原生支援、下游 ingest 也能對應到具體檔）。普通卡片間連結仍用裸 `[[卡名]]`（卡名唯一，不需路徑）。
|
||||
|
||||
**frontmatter 標籤分類**（issue #8）：
|
||||
- **用 frontmatter `tags:` 而非行內 `#tag`**：卡片內文常大量用 `#`（講筆記法時的 `#猜想`、`#book100`），分類標籤若也行內 `#`，下游 ingest 無法區分「分類」與「內文範例」會污染 graph。frontmatter 與內文完全分開，零歧義。
|
||||
- **用標籤而非資料夾分類**：資料夾＝強制單一歸屬；標籤＝多重歸屬。一張卡可同時屬知識管理＋AI協作＋架構設計，硬塞一個資料夾會在其他檢索角度漏掉。
|
||||
- **雙軸 taxonomy**（寫進 `TAXONOMY.md` 當字典；**受控擴充**，非凍結）：
|
||||
- 領域（主軸，1-3 個）：如 知識管理／學習認知／AI協作／生產力／系統設計／工具教學
|
||||
- 形態（副軸，0-2 個）：方法論／工具實作／觀點主張／架構設計／案例經驗
|
||||
- 一般開發專案的軸可不同（如 子系統／層級／決策類型），由 AI 依專案性質提出、寫進 TAXONOMY.md。
|
||||
- **遇到現有軸裝不下的內容**：先查是否只是現有標籤的同義詞；確實是新軸才加進 TAXONOMY.md（附定義）再用——**禁止繞過字典在卡片直接冒新標籤**。字典是 per-repo，跨 repo 不必共用。
|
||||
|
||||
**typed-edge 規則**（issue #5，把「關係」也預編譯，下游 ingest 直接 parse 出帶類型的有向邊）：
|
||||
1. **方向性**：`A >> 謂詞 >> B` 必須讀成「A（謂詞）B」一句通順的話；A、B 順序就是主→賓真實方向。
|
||||
2. **謂詞用動詞 / 動詞短語**（反駁、奠基於、是…的實作），動詞天然帶方向。
|
||||
3. **謂詞自由書寫，不受控詞彙**：下游對謂詞 embedding 時同義謂詞會自動聚類；但方向仍靠書寫順序保證。
|
||||
4. **向後相容**：純 `[[A]]` 仍合法（視為無類型邊），盡量補謂詞。
|
||||
|
||||
> `>>` 是分隔語法，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]]`。
|
||||
|
||||
> 與 claude.ai Cowork 的 `system-dev/docs/SKILL.md` 改寫邏輯一致，兩條路徑（CC / Cowork）產出同一種 wiki。
|
||||
|
||||
### 第六步：完成報告 + 驗證
|
||||
|
||||
完成後**驗證原文 0 動**（踩過的坑，issue #8）：
|
||||
```
|
||||
git status --short pages/ journals/ # 或一般專案的 docs/ ——須 0 新增 0 修改
|
||||
```
|
||||
|
||||
> **改寫時必守**（subagent 尤其）：
|
||||
> 1. **絕不寫入 raw source**：subagent 目標一律給絕對路徑到 `cards/<bucket>/`，明寫「絕不寫入 pages/journals/docs 原稿」；事後用上面的 `git status` 驗。
|
||||
> 2. **檔名 = 卡片全名**，否則 `[[全名]]` 對不到檔。冒號用全形「：」、斜線用全形「／」，**全程一種字元**，避免 `/`、`∕`、`：` 混用斷鏈。
|
||||
> 3. **量大用 Haiku 並行改寫**，主模型只切概念邊界＋審稿＋修跨資料夾斷鏈。
|
||||
|
||||
告知：
|
||||
```
|
||||
✅ wiki-init 完成
|
||||
建立了：[列出新建的目錄和檔案]
|
||||
跳過了：[列出已有因此不動的]
|
||||
改寫了：[N 份原文 → M 張原子卡、K 條 typed-edge、M 條 gloss（deep tier）]
|
||||
原文驗證：pages/ journals/ git status 0 異動 ✅
|
||||
下一步：用 /wiki-capture 把重要決策存進 wiki
|
||||
```
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# /wiki-recall — Session 開始，手動接關
|
||||
|
||||
開新對話時接上次進度。**Fallback 命令**：SessionStart hook 沒啟動時手動接關；要完整脈絡時也用。
|
||||
|
||||
> 主路徑是 SessionStart hook 自動注入 status 重點，不靠你打命令。
|
||||
> 這支命令應對 hook 失效，以及需要比「status 重點」更完整脈絡的時候。
|
||||
|
||||
---
|
||||
|
||||
## 命名閉環
|
||||
|
||||
init(建) → update(存，session 末) ↔ **recall(接，session 初)** → capture(隨時存結論)
|
||||
|
||||
---
|
||||
|
||||
## 執行流程
|
||||
|
||||
### 第一步：讀 status.md（當前進度）
|
||||
|
||||
讀 `system-dev/wiki/status.md`，掌握：
|
||||
- 正在做什麼、阻擋點
|
||||
- 下次 session 第一件事
|
||||
- 待負責人確認、已知問題
|
||||
|
||||
### 第二步：讀 decisions-summary.md（為什麼這樣做）
|
||||
|
||||
讀 `system-dev/wiki/decisions-summary.md`，掌握相關的架構決策——避免重新討論已定案的事。
|
||||
|
||||
### 第三步：讀 mistakes.md（別重犯）
|
||||
|
||||
讀 `system-dev/wiki/mistakes.md`，掌握已知誤解 + 快速檢查清單。
|
||||
|
||||
### 第四步：掃 wishlist / HANDOFF（如果有）
|
||||
|
||||
- `docs/wishlist.md`：待補功能
|
||||
- 任何 `HANDOFF.md` / 交接note：上一棒留下的脈絡
|
||||
|
||||
### 第五步：回報接關結果
|
||||
|
||||
```
|
||||
📍 接關完成
|
||||
🔄 上次正在做：[status 的「正在做」]
|
||||
🎯 下次第一件事：[status 的「下次 session 第一件事」]
|
||||
⚠️ 待確認：[如有]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 鐵律：快照非即時狀態
|
||||
|
||||
status / wiki 是 **point-in-time 快照，不是即時狀態**。
|
||||
|
||||
接關 ＝ 讀快照 **＋ 核實快照**，**不盲信**。
|
||||
|
||||
> 實例：某專案 status 曾寫「待 A 收尾 X」，實際 X 早已完成。
|
||||
> 照舊資訊行動會去催一件已完成的事。
|
||||
|
||||
動手前，先用當前 code / git / 檔案核實快照寫的事項是否仍成立。發現落差 → 先更新 status，再動手。
|
||||
Reference in New Issue
Block a user