WolfMarkDown 是做什麼的？
一個代理發佈工作流程，將混亂的 AI 輸出轉變為可審查並保留的專業 Markdown。
代理判斷結構。確定性工具提供證明。
AI 代理可以產出有用的研究、計劃和文件，但同時也可能留下扁平的比較、不一致的標題、複製的聊天支架、損壞的程式碼圍籬以及被竄改的技術識別碼。
WolfMarkDown 為代理提供了一個有紀律的發佈工作流程：
- 代理決定意義、結構、清理和內容組織；
- 確定性工具格式化並驗證產生的 Markdown；
- 在保留結果之前，檢查受保護的內容、回滾和發佈邊界。
結果並非神奇的 Markdown 修復引擎。它是一個圍繞著產物進行確定性驗證的代理工作流程。
WolfMarkDown 存在的原因
Prettier 是一個優秀的 Markdown 格式化工具。但它無法決定一個扁平區塊是否包含比較表格、一個簡短句子是否為標題，或者一個複製的代理訊息是否屬於這個文件。
WolfMarkDown 讓這些決策變得明確且保守。它修復清晰的結構，保留真正模糊的材料，並報告恢復了什麼。它不進行來源事實查核或批准發佈。
| 能力 | 僅有 Prettier | WolfMarkDown |
|---|---|---|
| 確定性 Markdown 格式化 | 是 | 是 |
| 修復語義文件結構 | 否 | 是 |
| 移除複製的 AI 對話支架 | 否 | 是 |
| 重建格式錯誤的比較表格 | 否 | 是 |
| 保護 URL、程式碼、雜湊值、版本和識別碼 | 否 | 是 |
| 驗證 GFM 解析和圍籬平衡 | 否 | 是 |
| 在發佈前執行 markdownlint | 否 | 是 |
| 檢查冪等性 | 否 | 是 |
| 在 Clean 失敗後還原原始檔案 | 否 | 是 |
| 拒絕發佈失敗的 Compose | 否 | 是 |
WolfMarkDown 不會為了讓文章聽起來不同而重寫已經良好的散文。目標是進行最小必要語義清理，並提供確定性證明，確保結果可以安全保留。
安裝
npx skills add WolfMarkTools/WolfMarkDown --skill wolfmarkdown
skills CLI 會為選定的 Agent Skills 相容主機安裝標準的 wolfmarkdown/ 技能。也可以透過倉庫檢出執行：
npm ci --prefix wolfmarkdown
node wolfmarkdown/scripts/install.mjs
對於非互動式 Claude Code 安裝：
npx skills add WolfMarkTools/WolfMarkDown \
--skill wolfmarkdown \
-g \
-a claude-code \
-y
安裝程式僅在需要時修復執行時期依賴項，配置共享的 .agents/skills/wolfmarkdown 發現路徑，配置 Claude Code 相容性路徑，在 Windows 上酌情使用目錄連結，並拒絕覆蓋無關路徑。
快速使用
使用 WolfMarkDown 處理 docs/architecture.md。
使用 WolfMarkDown 將此研究匯出為 Markdown。
使用 WolfMarkDown 驗證 docs/architecture.md，不要變更它。
如果主機支援斜線命令，則相同的工作流程可以以下列方式呼叫：
/wolfmarkdown docs/architecture.md
/wolfmarkdown verify docs/architecture.md
自然語言呼叫是可移植的介面。斜線命令的呈現方式則因主機而異。
操作
| 操作 | WolfMarkDown 的功用 |
|---|---|
| Compose | 從來源材料建立真正的 .md 檔案，移除僅限聊天室的支架，進行格式化、驗證，並僅在通過（PASS）後才發佈。 |
| Clean | 以最小必要的語義變更修復現有 Markdown 檔案，並在驗證失敗時還原原始檔案。 |
| Verify | 檢查 Markdown 但不進行變更。 |
| Doctor | 檢查執行時期依賴項和技能發現路徑，不變更安裝。 |
| Setup | 僅在需要時修復執行時期依賴項，並配置共享的技能發現路徑。 |
典型的清理目標包括標題層級、格式錯誤的清單、損壞的 GFM 表格、未閉合的程式碼圍籬、複製的代理評論、依賴對話的措辭以及不應留存於文件中的裝飾性雜訊。
前後對比
一個混亂的代理草稿可能將比較內容扁平化成一個區塊：
建議 對於外部錢包流程使用 relay_v2
比較 Provider 模式 風險 Privy 外部審批 中等 CDP 嵌入式錢包 高
實作說明 relay_v2 在提交後確認 getTransaction
在代理使結構明確之後，WolfMarkDown 可以發佈類似這樣的文件：
# 錢包流程決策
## 建議
對於外部錢包流程使用 `relay_v2`。
## 比較
| Provider | 模式 | 風險 |
| --- | --- | --- |
| Privy | 外部審批 | 中等 |
| CDP | 嵌入式錢包 | 高 |
## 實作說明
`relay_v2` 在提交後確認 `getTransaction`。
輸出恢復了表格和標題，保留了技術識別碼，並且沒有添加來源中不存在的資訊。這是一個說明性的結構範例；語義判斷仍由代理負責。
範例
公開的範例展示了 WolfMarkDown 如何從真實的代理生成的 Markdown 中恢復結構，而不憑空臆造缺失的意義。
- 行動應用遷移範例 — 一個完整的前後對照範例，涵蓋聊天室包裝清理、Tab 分隔表格、Unicode 項目符號、受保護的環境變數以及一個故意模糊的資料庫備註。
- 原始輸入 — 修復前的來源 AI 輸出。
- 結構化輸出 — 產生的 Markdown，包含標題、GFM 表格、清單和一個
env程式碼區塊。
範例 README 記錄了用於再現的 OpenCode 測試框架、GLM-5.2 模型和確切提示詞。
支援的代理整合狀態
WolfMarkDown 有一個標準的實作。下表區分了經過倉庫測試的發現路徑以及仍需專用冒煙測試的主機接受度。
| 主機 | 整合狀態 | 發現路徑 |
|---|---|---|
| Codex | 倉庫發現和安裝程式路徑已測試 | 共享的 .agents/skills |
| Cursor | 倉庫發現和安裝程式路徑已測試 | 共享的 .agents/skills |
| Claude Code | 相容性連結路徑已測試 | .claude/skills |
| OpenCode | 主機接受度待定 | 共享的 .agents/skills（當主機啟用時） |
| Gemini CLI | 主機接受度待定 | 共享的 .agents/skills（當主機啟用時） |
| GitHub Copilot | 主機接受度待定；外掛程式入庫為歷史證據 | 主機啟用的 Agent Skills 或外掛程式支援 |
主機接受度不能從二進位檔或目錄的存在來推斷。主機模型決定語義品質；WolfMarkDown 提供工作流程和確定性檢查。
運作方式
使用者意圖
↓
代理語義判斷
↓
來源映射和語義修復
↓
GFM 解析 + 標題/表格檢查
↓
圍籬、前言和空白檢查
↓
Prettier 格式化檢查
↓
markdownlint
↓
受保護權杖完整性（搭配來源快照）+ 冪等性
↓
通過（PASS）→ 保留或發佈 失敗（FAIL）→ 還原或不發佈
在格式化之前，代理會檢查扁平化的語義結構。一個文件可以是有效的 Markdown，但如果它失去了表格、標題、清單或關係，它仍然是一個失敗的轉換。
語義修復邊界
僅當來源清楚表明結構時，代理才會重建標題、清單、表格、段落和同級章節。無表頭的 Tab 分隔行不會自動被視為表格，一個簡短句子不會自動被視為標題，一個獨立的 Label: value 片語也不會自動被視為清單項目。對於長文件，代理會維護一個來源映射，並在發佈前協調完整的綱要、跨章節關係、表格邊界和受保護的值。如果無法完整審查來源，它會保留不確定性並報告其限制，而不是進行猜測。
驗證和品質邊界
WolfMarkDown 通過（PASS）表示產物通過了適用的確定性檢查：
- Markdown 產物通過了格式化、解析、lint、圍籬和冪等性檢查；
- 代理做出並報告了基於來源的結構決策；
- 僅在對未觸及的來源快照進行完整性檢查時（如 Clean 和 Compose 或搭配
--integrity-from），才保留受保護的技術內容； - 失敗的 Clean 和 Compose 操作不會留下未經驗證的已發佈結果。
不帶完整性來源的獨立 Verify 會報告完整性檢查已跳過。其通過（PASS）不能證明受保護的權杖被保留。
受保護的細節
當可取得未觸及的來源快照時，完整性檢查保護的技術內容包括：
- URL、行內程式碼和圍籬程式碼；
- 公開金鑰、簽章、雜湊值、版本和識別碼；
- 檔案系統路徑和上下文環境變數；
- 日期、百分比和貨幣值。
這是 Markdown 品質的證據，並非內容核准。通過（PASS）不建立事實正確性、完整性、時效性、政策合規性或發佈授權。它不對聲明進行事實查核。
確定性檢查是產物屬性的證明。它們不是語義預言機，也不能取代代理對每一個清晰的來源訊號進行說明的責任。
v0.2.1 版本發佈證據
- 82/82 Node 測試通過。
- 可執行的語義屬性檢查涵蓋標題、GFM 表格、受保護權杖和模糊表格保留。
skills-ref validate ./wolfmarkdown通過。- 安裝程式、Doctor、回滾、目標衝突、完整性、冪等性檢查仍受涵蓋。
歷史外部外掛程式入庫
v0.1.1 Agent Plugins 套件通過了 GitHub Awesome Copilot 的自動化外部外掛程式入庫。這是 v0.2.1 的歷史包裝證據，而非主機接受度證據。
架構細節
WolfMarkDown/
├── plugin.json
├── .agents/
│ └── skills/
│ └── wolfmarkdown → ../../wolfmarkdown
├── skills/
│ └── wolfmarkdown → ../wolfmarkdown
└── wolfmarkdown/
├── SKILL.md
├── config/
├── lib/
├── references/
├── scripts/
└── tests/
代理擁有的決策
代理擁有意圖路由、來源映射、語義分類、對話清理、標題/清單/表格恢復、模糊性處理和內容組織。
確定性證明
腳本擁有格式化、Markdown lint、GFM 解析、圍籬平衡、前言檢查、受保護權杖完整性、冪等性、安裝、Doctor 檢查、回滾和基於屬性的語義評估。它們不重寫來源意義。
Prettier 是唯一的最終印表機。
機器技能 ID 和檔案系統目錄故意使用小寫 wolfmarkdown；產品名稱是 WolfMarkDown。
語義評估
評估語料庫使用合成文件和結構屬性，而非脆弱的完整文件快照。在正常驗證器之後，對代理產生的候選者執行案例：
node wolfmarkdown/scripts/evaluate-semantic.mjs \
--case ambiguous-structure-preservation \
source.md candidate.md
評估器檢查預期的標題數量和表格數量、受保護權杖的保留以及安全屬性（例如拒絕將模糊的無表頭行視為表格）。它不會推斷或修復候選者。
開發者命令
npm ci --prefix wolfmarkdown
npm test
npx --yes skills-ref validate ./wolfmarkdown
有用的直接命令：
node wolfmarkdown/scripts/doctor.mjs
node wolfmarkdown/scripts/format-markdown.mjs path/to/file.md
node wolfmarkdown/scripts/verify-markdown.mjs path/to/file.md
node wolfmarkdown/scripts/evaluate-semantic.mjs --help
語義案例位於 wolfmarkdown/tests/evals/。跨主機接受度輸入位於 wolfmarkdown/tests/acceptance/。
當前邊界
/wolfmarkdown setup僅在技能對主機可發現後才運作。- 不支援
--mode。 - 不會建立供應商特定的技能分支。
- Windows 需要權限才能建立適當的發現連結。
- 語義清理仍是設計上由代理判斷。
- 驗證器證明 Markdown 產物屬性；它不定義任意散文或發佈準備就緒。
- 長文件修復依賴於代理保留和協調其文件帳本；不完整的來源審查必須回報，而非猜測。
倉庫元資料
推薦的 GitHub 倉庫主題：
ai-agents agent-skills markdown documentation claude-code codex cursor github-copilot
主題應在 GitHub 倉庫設定中配置。它們是可發現性的元資料，而非相容性證據。
貢獻
發現 WolfMarkDown 應該能更好處理的 Markdown 邊緣案例嗎？建立一個 issue。
對於可再現的 Markdown 失敗、完整性邊緣案例、跨平台安裝問題、額外的主機接受度證據，以及保留單一實作架構的專注改進，Pull Request 特別有用。
許可證
WolfMarkDown 採用 MIT 許可證。