obsidian-revision-marks

name: obsidian-revision-marks description: "Mark revisions inline in existing Obsidian markdown files using either Obsidian comments (%%...%%) or footnotes ([^N] reference style preferred, ^[...] inline as alternative), so the user can review every change before accepting. Use whenever revising, restructuring, proofreading, reviewing, or annotating existing Obsidian markdown content — outlines, notes, drafts, articles, talk decks. Triggers on words like 調整, 修訂, 重新檢視, 改一下, 重新組織, 校稿, 校閱, 批注, revise, adjust, restructure, reorganize, proofread, review, annotate. Do NOT use when creating brand-new files from scratch, when the user explicitly says 直接改 不用標記, or when working on non-Obsidian markdown (the %%...%% syntax won't auto-hide there; footnotes still work in standard markdown but rendering varies)."

Obsidian 修訂/校閱標記慣例

當使用者請我調整、修訂、校稿、校閱、批注既有的 Obsidian markdown 文件時, 用內嵌標記註明每處變動, 讓使用者可以清楚對照後再決定是否接受。

提供兩種標記模式:

兩種模式怎麼選

預設選擇:

• 使用者說「修訂」「調整」「重新組織」→ 用註解模式 (清乾淨輸出)
• 使用者說「校稿」「校閱」「批注」「給評語」→ 用註腳模式 (留下可見批注)
• 使用者明確指定模式 → 照指示
• 不確定時 → 問一句, 不要兩種混用 (除非有理由, 例如多行範圍註解只能用 %%...%% 包)

兩種共通特性:

• 編輯模式都清楚可見, 可全文搜尋一次找出所有修訂處
• 不跟 highlight ==...== 衝突 (使用者的 vault 已將 == 用於其他用途)
• 每個標記都附「為什麼」, 讓使用者直接判斷是否接受

模式 A: 註解語法 %%...%%

Obsidian 原生註解語法, 閱讀模式自動隱藏 — 適合「最終要乾淨輸出」的場景。

A1. 改寫的行 — 保留原文方便對照

新內容 %%[改] 原: "原文" - 改寫理由%%

範例:

- AI 重新定義 BizDevOps 的執行平衡 %%[改] 原: "AI 改變了哪些流程與作業方法?" - 標題正面化%%

A2. 新增的單行 — 描述目的

新增的內容 %%[新增] 新增理由%%

範例:

- 瓶頸轉移到「架構師的邊界規劃能力」+「Core Context 的管理品質」 %%[新增] 預告答案, 收斂到後續兩大主軸%%

A3. 新增的整段 (多行) — 用開始/結束 marker 包住

%%[新增段落 開始] 簡述新增理由%%
段落內容
更多內容
%%[新增段落 結束]%%

範例:

%%[新增段落 開始] 獨立 Harness Engineering section - 主軸命名%%
Harness Engineering - 從工程師擴大到架構師

- 業界已經有成熟的 harness 框架...
- ...
%%[新增段落 結束]%%

A4. 擬刪除的內容 — 保留原文, 標記擬刪除

不要直接刪除原文 (使用者看不到刪了什麼)。標記擬刪除, 由使用者確認後再清除:

原本的行 %%[擬刪除] 理由%%

或整段:

%%[擬刪除 開始] 理由%%
原段落
%%[擬刪除 結束]%%

清除標記 (模式 A)

• VS Code / 編輯器 regex 取代: 搜尋 %%\[[^%]*?%% 取代為空字串
• Obsidian 內 Ctrl+F (或 Cmd+F) 搜 %%[ 逐一檢視
• 或寫成簡單 script:

  sed -i.bak -E 's/%%\[[^%]*?%%//g' file.md
  

模式 B: 註腳語法 [^N] (參照式, 推薦) / ^[...] (行內式)

Obsidian 支援兩種註腳, 閱讀模式都顯示為上標連結, 點擊跳到註解內容 — 適合「校稿/批注/評論」, 想留下可見討論軌跡。

兩種寫法:

• 參照式 [^N] (推薦, 一般文章/書籍註腳做法): 標記放行尾, 內容統一寫在文件末尾, source view 行尾乾淨, 多註解或長註解都好處理
• 行內式 ^[...] (極短註解的替代): 內容直接跟在標記後, 不需要維護文末定義, 但行末容易很長, 也無法含 ]

預設用參照式; 註解很短且只有零星一兩處時可考慮行內式。同一份文件建議統一風格, 不要混用。

B1. 改寫的行 — 保留原文方便對照

參照式 (推薦):

新內容 [^1]

...文件其他內容...

[^1]: [改] 原: "原文" - 改寫理由

範例:

- AI 重新定義 BizDevOps 的執行平衡 [^1]

(文末)
[^1]: [改] 原: "AI 改變了哪些流程與作業方法?" - 標題正面化

行內式 (極短註解可選):

新內容 ^[改: 原 "原文" - 改寫理由]

B2. 新增的單行 — 描述目的

參照式 (推薦):

新增的內容 [^2]

(文末)
[^2]: [新增] 新增理由

行內式:

新增的內容 ^[新增: 新增理由]

B3. 新增的整段 (多行)

參照式: 在段首行加註腳, 註腳定義可縮排延續多行

首句 [^3]
第二句
第三句

(文末)
[^3]: [新增段落 (共 3 段)] 補充背景
    縮排 4 空格 (或 1 個 tab) 延續同一個註腳, 可寫多行
    每段都縮排, 直到下一個註腳定義或空白行

或: 範圍較複雜時, 借模式 A 的 %%[新增段落 開始]%% ... %%[新增段落 結束]%% marker 框範圍 (邊界比較準, 即使主體用模式 B 也可以混用)

B4. 擬刪除的內容 — 保留原文, 標記擬刪除

參照式:

原本的行 [^4]

(文末)
[^4]: [擬刪除] 理由

行內式:

原本的行 ^[擬刪除: 理由]

多行擬刪除建議用模式 A 的開始/結束 marker 框範圍。

B5. 註腳定義位置與命名慣例

定義位置: [^N]: 內容 統一放在文件最末尾, 跟主體內容用空白行隔開:

最後一段主體內容

[^1]: 第一個註腳的內容
[^2]: 第二個註腳的內容
...

定義順序: 按註腳在文件中出現的順序排列 (跟編號一致), 方便對照。

命名慣例: 開工前先 grep 一下 \[\^ 看有沒有既有 footnote:

• 無既有 footnote → 用純數字 [^1], [^2], ... (一般文章/書籍做法, source view 短)
• 有既有 footnote → 用 [^rev-N] 前綴 ([^rev-1], ...) 避免衝突, 也讓 revision 標記跟內容註腳明確區分
• 改動位置明確的少量註腳 → 用語意化 label ([^rev-title], [^rev-intro], ...)

清除標記 (模式 B)

完成校閱後三種選擇:

1. 保留作批注 — 不清理, 留作文件的討論軌跡
2. 全部接受變更 — 刪除所有 [^N]、^[...] 標記與文末 [^N]: ... 定義行
3. 選擇性接受 — 逐一決定

regex 清除 (VS Code 多行模式):

\s*\^\[[^\]]*\]                              # 行內註腳
\s*\[\^[^\]]+\]                              # 參照標記 (數字 + rev- 都涵蓋)
^\[\^[^\]]+\]:[\s\S]*?(?=\n\[\^|\n#|\Z)      # 註腳定義 (含縮排延續行)

或 script:

# 移除行內註腳
sed -i.bak -E 's/[[:space:]]*\^\[[^]]*\]//g' file.md

# 移除參照標記與定義 (數字 + rev- 兩種命名都涵蓋)
sed -i.bak -E '/^\[\^[0-9]+\]:|^\[\^rev-[^]]+\]:/d; s/[[:space:]]*\[\^[0-9]+\]//g; s/[[:space:]]*\[\^rev-[^]]+\]//g' file.md

若文件有真實內容註腳 (非 revision 標記), 採用 rev-N 前綴後可用精準 regex 只清 \[\^rev- 系列。

標記要點 (兩模式共通)

收尾流程

調整完成後, 給使用者一份完整摘要:

1. 使用哪種模式 — 告知選了註解 / 註腳, 以及理由 (對應使用者語境)
2. 變動摘要表格 — 各區域變動類型 (改/新增/移動/刪除)
3. 標記行為提醒 — 註解模式自動隱藏 / 註腳模式顯示為上標
4. 清除方式 — 附對應模式的 regex 或 script

何時不適用

• 建立全新檔案 — 沒有原文需要對照, 直接寫即可
• 純粹追加內容 — 不影響既有結構時, 直接寫入並告訴使用者位置即可
• 使用者明確說「直接改, 不用標記」 — 尊重指示
• 非 Obsidian 的 markdown 檔案 — %%...%% 在標準 markdown 渲染器會以原文顯示, 不會隱藏; 註腳在標準 markdown 也支援, 但渲染樣式因平台而異, 確認目標平台支援再用

工作流程

1. 理解使用者要做什麼 — 先讀檔, 釐清範圍, 判斷是「修訂」還是「校閱/批注」性質
2. 決定模式 — 依使用者語境選註解 or 註腳 (見「兩種模式怎麼選」); 不確定時問一句
3. 規劃改動 — 列出每處要動的地方與理由
4. 執行 Edit — 每次修改都附上對應的標記
5. 摘要報告 — 告知選用模式、表格列出所有變動、提醒標記行為、附清除方式
6. 等使用者確認 — 不要主動清除標記, 讓使用者自己決定哪些接受

與其他 skills 的關係

• 搭配 obsidian:obsidian-markdown 使用: 那個 skill 處理 wikilinks/callouts/properties 等 Obsidian 語法, 此 skill 專注於修訂/校閱工作流程
• 不取代 git diff: 此 skill 是給「還沒 commit, 還在跟使用者協作調整中」的階段使用; 若選註解模式, commit 前應清掉所有標記; 若選註腳模式作為批注, 是否保留視文件性質決定