WolfMarkTools/WolfMarkDown

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 会将规范的 wolfmarkdown/ 技能安装到选定的、兼容 Agent Skills 的宿主上。如果克隆了仓库，也可以运行：

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 上使用目录连接点，并拒绝覆盖无关路径。

快速使用

Use WolfMarkDown on docs/architecture.md.

Export this research as Markdown using WolfMarkDown.

Verify docs/architecture.md with WolfMarkDown without changing it.

如果宿主暴露了斜杠命令，则可以使用相同的工作流：

/wolfmarkdown docs/architecture.md
/wolfmarkdown verify docs/architecture.md

自然语言调用是便携接口。斜杠命令的呈现方式因宿主而异。

操作

操作	WolfMarkDown 的功能
Compose	从源材料创建真正的 .md 文件，移除仅用于聊天的脚手架，格式化，验证，并且仅在通过（PASS）后发布。
Clean	以最小必要的语义更改修复现有的 Markdown 文件，并在验证失败时恢复原始文件。
Verify	检查 Markdown 而不更改它。
Doctor	检查运行时依赖项和技能发现，而不更改安装。
Setup	仅在需要时修复运行时依赖项并配置共享的技能发现。

典型的清理目标包括标题层级、格式错误的列表、损坏的 GFM 表格、未闭合的代码围栏、复制的代理评论、依赖于对话的措辞以及不应存在于文档中的装饰性噪声。

前后对比

一个杂乱的代理草稿可能会将比较内容扁平化为一个块：

Recommendation use relay_v2 for the external wallet flow.
Comparison Provider Mode Risk Privy External approval Medium CDP Embedded wallet High.
Implementation notes relay_v2 confirms getTransaction after submission.

在代理明确结构后，WolfMarkDown 可以发布如下文档：

# Wallet flow decision

## Recommendation

Use `relay_v2` for the external wallet flow.

## Comparison

| Provider | Mode | Risk |
| --- | --- | --- |
| Privy | External approval | Medium |
| CDP | Embedded wallet | High |

## Implementation notes

`relay_v2` confirms `getTransaction` after submission.

输出恢复了表格和标题，保留了技术标识符，并且没有添加源内容中不存在的任何信息。这是一个说明性的结构示例；语义判断权仍由代理掌握。

示例

公开的示例展示了 WolfMarkDown 从真实的、类似代理生成的 Markdown 中恢复结构，而不会凭空捏造缺失的含义。

• 移动应用迁移示例 — 一个完整的前后对比夹具，涵盖了聊天包装清理、制表符分隔的表格、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
    ↓
受保护令牌完整性（带源快照）+ 幂等性
    ↓
通过 → 保留或发布     失败 → 恢复或不发布

在格式化之前，代理会检查扁平化的语义结构。一个文档可能是有效的 Markdown，但如果它丢失了表格、标题、列表或关系，仍然是一次失败的转换。

语义修复边界

代理仅当源内容明确时才重建标题、列表、表格、段落和同级章节。没有标题的制表符行不会自动被视为表格，短句不会自动被视为标题，孤立的 标签: 值 短语也不会自动被视为列表项。对于长文档，代理会维护一个源映射，并在发布前协调完整大纲、跨章节关系、表格边界和保护值。如果无法完整审阅源内容，它会保留不确定性并报告限制，而不是进行猜测。

验证与质量边界

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 边缘情况？开启一个问题。

对于可复现的 Markdown 失败、完整性边缘情况、跨平台安装问题、额外的宿主验收证据以及保留单一实现架构的集中改进，拉取请求尤其有用。

许可证

WolfMarkDown 采用 MIT 许可证。