語法結構

Markdown+ 文件由 一份 H1 標題 + 一段引言 + 多個 bullet-list block 組成。每個 block 的開頭固定格式:

- **#<kebab-case-id>** `type:<value>` `<key>:<value>` ...
  <block body, 縮排 2 spaces, 任意合法 Markdown>

  - **#<child-id>** `type:<value>` ...
    <子 block, 縮排 4 spaces>

組成元素

受控 metadata 字彙表

type: (block 主類型,closed list)

需要擴充必須用 x- 前綴。

status: (closed list)

draft active proposed accepted rejected superseded deprecated archive healthy degraded down on-track behind exceeded done blocked open closed

其他常用 metadata

• updated:YYYY-MM-DD — ISO 日期
• visibility:collapsed — viewer 預設摺疊
• priority:high|normal|low|critical
• tags:[domain:auth,team:platform] — 用 namespace
• superseded-by:<id> — 指向替代者
• related:[id1,id2]
• variant-group:install + variant:mac — 同 group 的 sibling 會被 viewer 聚合成 tab
• KPI: value: target: delta: unit:
• Gauge: value: min: max: target: zones:[99:red,99.9:amber,99.95:green]
• keywords:a,b,c — block 關鍵詞清單。手動宣告永遠優先;未宣告時 viewer 會自動抽出(虛線 chip)。詳見 自動關鍵詞抽取

必須遵守的約束關係

• status:deprecated ⇒ 必有 superseded-by:<id>
• type:history ⇒ visibility:collapsed
• type:kpi ⇒ value:,且與 prose 段數字一致
• type:gauge ⇒ value: min: max: target: zones: 全要
• 同層共用 variant-group: 的 sibling 必須各有不同 variant:
• 每個 figure / chart / table / kpi / gauge / video / audio 必須有 prose companion 段
• 表格 > 30 列必須用 data-source:./data/<name>.csv

禁止清單 (lint error)

視覺化 fence:```svg 與 ```mermaid

圖表 / 流程圖 / 簡單示意圖可以用兩種 標準 code fence 內聯, 在 GitHub / Obsidian 仍是合法的 code block(graceful degradation), 在 Markdown+ viewer 才長出 graph / code 切換 toolbar。

```svg — 內聯向量圖

- **#sla-trend** `type:figure` `media:svg`

  *Figure: API SLA 月度趨勢*

  ```svg
  <svg viewBox="0 0 320 120" xmlns="http://www.w3.org/2000/svg">
    <polyline points="50,40 130,56 210,70 290,72" fill="none" stroke="#0ea5e9" stroke-width="2"/>
    ...
  </svg>
  ```

  4 月 SLA 跌至 99.92%,低於目標。

viewer 行為

注入前 sanitize

• <script> tag 整段移除
• on*= event handler attribute 全部去掉(onclick / onload / onerror …)
• 結構標記(<defs> <style> <marker> <filter>)保留

```mermaid — Mermaid 圖表

- **#refresh-flow** `type:diagram` `diagram-type:mermaid`

  *Figure: Token refresh 流程*

  ```mermaid
  sequenceDiagram
      participant C as Client
      participant G as Gateway
      C->>G: request with expired token
      G-->>C: new access token
  ```

  refresh 流程從 client 看是透明的。

viewer 動態 import Mermaid 10 (CDN) 渲染為 SVG; toolbar 與 SVG fence 共用元件,「graph」視圖顯示渲染後的圖、 「code」視圖顯示原始 mermaid source。

自動抓取的結構關鍵詞

含 ```mermaid 的 block 自動帶 mermaid + 圖表類型(從 fence 第一個非空行偵測):

含 ```svg 的 block 則永遠帶 svg 作第一個關鍵詞。

自動關鍵詞抽取(無辭典)

每個 block 沒宣告 keywords: 時, viewer 會用 純統計、無辭典依賴的演算法即時抽出 top-N 關鍵詞,在 block header 下方以虛線 chip 顯示。 手動宣告永遠優先;沒宣告才填 auto chip。

演算法 — N-gram + PMI + 左右熵

完全照「無詞典新詞發現」標準演算法實作,瀏覽器端純 JS 跑,毫秒級完成:

1. 文本清理:剝除 code fence、inline code、image / link markdown、heading 標記、block header 行,僅保留 prose。
2. N-gram 枚舉:
   • CJK 連續字串 2 ~ 8 字(min_len=2, max_len=8)
   • ASCII token [A-Za-z][A-Za-z0-9+\-]* 並行抓取 (適用 Markdown+ / block-based / SDK 等混合語術語)
3. 內部凝固度(PMI cohesion): 對候選詞 w 嘗試所有二分切分, 算 PMI(x, y) = log(P(xy) / P(x)P(y))), 取 最小值作 cohesion(代表最弱的內部連結強度,反映「整體是否確實一起出現」)。 門檻 min_pmi ≥ 1.0。
4. 左右自由度(Shannon entropy): 收集候選詞左、右鄰字分佈,各計算 Shannon 熵。 兩端皆需 ≥ 0.4。 熵高表示鄰字多樣 = 該詞能獨立出現(像「人工智慧」左右搭配很多), 熵低表示鄰字固定 = 是更長詞的一部分(像「式人工智」永遠夾在「生成式人工智慧」裡會被濾掉)。
5. 詞頻過濾:出現次數 ≥ 2。
6. 綜合排序: score = freq × min-PMI × min(left, right)-entropy, 降冪取 top-K(預設 80 個全域候選 → 每 block 取 top-5)。
7. 子字串抑制:已 kept 的長詞會擠掉它的子字串 (若 freq 接近 ≥ 60%)——比如「人工智慧」入選後就會擠掉 只是它子字串的「人工」「智慧」。
8. 每 block 投影:對該 block body 計算每個全域候選的命中次數, block_score = global_score × log(occ + 1), 排序取 top-5。

結構標籤前置

以下兩類訊號 n-gram 抓不到(fence 內容被清理階段剝除),所以由獨立 helper 注入並 排在自動抽取詞之前:

• 含 ```svg fence → 永遠先放 svg
• 含 ```mermaid fence → 先放 mermaid + 圖表類型(見上)

預設參數一覽

手動覆寫

把 keywords:a,b,c 放進 block header,viewer 就改顯示實線 chip,不再跑自動抽取。playground sub-header 的「寫入 keywords」按鈕會把 viewer 計算出的 auto 詞用 inline-code 形式寫進 source(``keywords:`a,b,c```),套用前 confirm dialog 列前 8 個 block 的建議供預覽。

複雜度

固定 L (最大候選長度)下,演算法是 O(N × L) 線性掃描 + O(V log V) 排序。文件變 10 倍大、時間約 10 倍,不是平方。 記憶體主要是候選 Map,經 min_freq 過濾後規模有限。

設計理念對照