| 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 文件時, 用內嵌標記註明每處變動, 讓使用者可以清楚對照後再決定是否接受。
提供兩種標記模式:
兩種模式怎麼選
| 模式 | 語法 | reading mode | 適合場景 | 接受後 |
|---|
| 註解 | %%...%% | 自動隱藏 | 修訂後要交付乾淨輸出 (簡報/文章/講稿) | regex 一次清除 |
| 註腳 | [^N] (參照, 推薦) / ^[...] (行內) | 顯示為上標連結 | 校稿/校閱/批注/評論, 想留下討論軌跡 | 保留作批注, 或選擇性清除 |
預設選擇:
- 使用者說「修訂」「調整」「重新組織」→ 用註解模式 (清乾淨輸出)
- 使用者說「校稿」「校閱」「批注」「給評語」→ 用註腳模式 (留下可見批注)
- 使用者明確指定模式 → 照指示
- 不確定時 → 問一句, 不要兩種混用 (除非有理由, 例如多行範圍註解只能用
%%...%% 包)
兩種共通特性:
- 編輯模式都清楚可見, 可全文搜尋一次找出所有修訂處
- 不跟 highlight
==...== 衝突 (使用者的 vault 已將 == 用於其他用途)
- 每個標記都附「為什麼」, 讓使用者直接判斷是否接受
模式 A: 註解語法 %%...%%
Obsidian 原生註解語法, 閱讀模式自動隱藏 — 適合「最終要乾淨輸出」的場景。
A1. 改寫的行 — 保留原文方便對照
新內容 %%[改] 原: "原文" - 改寫理由%%
範例:
- AI 重新定義 BizDevOps 的執行平衡 %%[改] 原: "AI 改變了哪些流程與作業方法?" - 標題正面化%%
A2. 新增的單行 — 描述目的
新增的內容 %%[新增] 新增理由%%
範例:
- 瓶頸轉移到「架構師的邊界規劃能力」+「Core Context 的管理品質」 %%[新增] 預告答案, 收斂到後續兩大主軸%%
A3. 新增的整段 (多行) — 用開始/結束 marker 包住
%%[新增段落 開始] 簡述新增理由%%
段落內容
更多內容
%%[新增段落 結束]%%
範例:
%%[新增段落 開始] 獨立 Harness Engineering section - 主軸命名%%
Harness Engineering - 從工程師擴大到架構師
- 業界已經有成熟的 harness 框架...
- ...
%%[新增段落 結束]%%
A4. 擬刪除的內容 — 保留原文, 標記擬刪除
不要直接刪除原文 (使用者看不到刪了什麼)。標記擬刪除, 由使用者確認後再清除:
原本的行 %%[擬刪除] 理由%%
或整段:
%%[擬刪除 開始] 理由%%
原段落
%%[擬刪除 結束]%%
清除標記 (模式 A)
模式 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)
完成校閱後三種選擇:
- 保留作批注 — 不清理, 留作文件的討論軌跡
- 全部接受變更 — 刪除所有
[^N]、^[...] 標記與文末 [^N]: ... 定義行
- 選擇性接受 — 逐一決定
regex 清除 (VS Code 多行模式):
\s*\^\[[^\]]*\] # 行內註腳
\s*\[\^[^\]]+\] # 參照標記 (數字 + rev- 都涵蓋)
^\[\^[^\]]+\]:[\s\S]*?(?=\n\[\^|\n#|\Z) # 註腳定義 (含縮排延續行)
或 script:
sed -i.bak -E 's/[[:space:]]*\^\[[^]]*\]//g' file.md
sed -i.bak -E '/^\[\^[0-9]+\]:|^\[\^rev-[^]]+\]:/d; s/[[:space:]]*\[\^[0-9]+\]//g; s/[[:space:]]*\[\^rev-[^]]+\]//g' file.md
若文件有真實內容註腳 (非 revision 標記), 採用 rev-N 前綴後可用精準 regex 只清 \[\^rev- 系列。
標記要點 (兩模式共通)
| 原則 | 說明 |
|---|
| 每個標記附「為什麼」 | 簡短即可 — 讓使用者直接判斷是否接受, 不用回頭問 |
| 不要逐字描述變更 | 一句話交代意圖即可 (改了哪幾個字使用者一看就知道) |
| 改寫類保留原文 | 用 原: "..." 格式 — 方便對照 |
| 新增類描述目的 | 為什麼需要這條 — 方便取捨 |
| 標記放行尾 | 避免影響原文閱讀, 集中在行末 |
| 新段落用開始/結束 | 一行標記容易遺漏範圍, 開始/結束 marker 清楚框住範圍 (僅模式 A) |
| 不要混用模式 | 同一份文件只用一種, 多行範圍例外可借模式 A 的開始/結束 marker |
收尾流程
調整完成後, 給使用者一份完整摘要:
- 使用哪種模式 — 告知選了註解 / 註腳, 以及理由 (對應使用者語境)
- 變動摘要表格 — 各區域變動類型 (改/新增/移動/刪除)
- 標記行為提醒 — 註解模式自動隱藏 / 註腳模式顯示為上標
- 清除方式 — 附對應模式的 regex 或 script
何時不適用
- 建立全新檔案 — 沒有原文需要對照, 直接寫即可
- 純粹追加內容 — 不影響既有結構時, 直接寫入並告訴使用者位置即可
- 使用者明確說「直接改, 不用標記」 — 尊重指示
- 非 Obsidian 的 markdown 檔案 —
%%...%% 在標準 markdown 渲染器會以原文顯示, 不會隱藏; 註腳在標準 markdown 也支援, 但渲染樣式因平台而異, 確認目標平台支援再用
工作流程
- 理解使用者要做什麼 — 先讀檔, 釐清範圍, 判斷是「修訂」還是「校閱/批注」性質
- 決定模式 — 依使用者語境選註解 or 註腳 (見「兩種模式怎麼選」); 不確定時問一句
- 規劃改動 — 列出每處要動的地方與理由
- 執行 Edit — 每次修改都附上對應的標記
- 摘要報告 — 告知選用模式、表格列出所有變動、提醒標記行為、附清除方式
- 等使用者確認 — 不要主動清除標記, 讓使用者自己決定哪些接受
與其他 skills 的關係
- 搭配
obsidian:obsidian-markdown 使用: 那個 skill 處理 wikilinks/callouts/properties 等 Obsidian 語法, 此 skill 專注於修訂/校閱工作流程
- 不取代 git diff: 此 skill 是給「還沒 commit, 還在跟使用者協作調整中」的階段使用; 若選註解模式, commit 前應清掉所有標記; 若選註腳模式作為批注, 是否保留視文件性質決定
