iWiki MD 发布器

帮助用户把内容整理成适合 iWiki 的精美页面。默认产出报告风 / 门户风的可视化 MD 页面；除非用户明确要求纯 Markdown，否则不要先退化成朴素草稿。文案尽量贴近源内容，除非用户明确要求润色或补充说明，否则不要额外加入教学式解释。最终使用 iwiki-cli 发布或更新页面。

CLI 调用约定

• 本 skill 中凡是出现 iwiki-cli ... 的地方，真实执行时都优先使用 scripts/run_iwiki_cli.sh 包装器；它会先通过登录 shell 调起 iwiki-cli，必要时再自动尝试一次 ~/.zshrc 兼容兜底，避免每次手写 source ~/.zshrc &&。
• 如果无法使用包装器，就退回 zsh -lc 'iwiki-cli ...' 这种登录 shell 方式。
• 只有当当前机器把 PATH 或 IWIKI_TOKEN 错误地只写进了 ~/.zshrc 时，才把 source ~/.zshrc 视为临时排障手段；这不算真正修好环境。

硬性要求

• 先要求用户申请或复制 PAT，并把 token 发给 Agent。
• 在拿到 token 之前，不要执行 iwiki-cli metadata、get、search、create、update 或 space。
• 如果 iwiki-cli 只能靠一次性的 export PATH=... 才能运行，或者 IWIKI_TOKEN 在新开的登录 shell 中消失，就视为环境尚未准备好。
• 要求把 PATH 与 IWIKI_TOKEN 持久化到登录 shell 真正会加载的位置，而不是只放在当前会话里。
• 只要上面任意前置条件不满足，就先阅读 references/setup.md。

工作流

1. 先满足所有硬性要求。如果用户还没提供 token、iwiki-cli 在新的登录 shell 中还不可用，或者 IWIKI_TOKEN 还没有被持久化，就停止内容处理，先完成 references/setup.md。
2. 阅读源 HTML，识别用户可见的章节、标题、正文、链接和命令片段。
3. 用 iwiki-cli metadata 检查目标 iWiki 页面。
4. 如果是在更新已有页面，先用 iwiki-cli get 把云端正文拉下来，并以它作为工作草稿；如果本地已经有改到一半的版本，先做备份。
5. 如果目标页是 DOC，但用户希望获得门户风 HTML 渲染效果，不要继续硬改老页面，改为在同一父节点下新建 MD 页面。
6. 默认产出报告风 / 门户风的可视化 MD 页面，包含 hero、摘要卡片和模块化章节；除非用户明确要求纯草稿，或兼容性问题迫使降级，否则不要先生成纯结构化 Markdown。
7. 读取一个或多个参考 MD 页面，使用 iwiki-cli get 学它们的实现风格，而不是照抄它们的文案。
8. 在写文件前，先阅读 references/template-variants.md，根据内容类型选择最合适的模板变体。
9. 再选定代码展示模式：
• 原生复制模式：使用 fenced code block，并把代码块放在 HTML 卡片外。
• 一体化视觉模式：使用内联 HTML 代码面板，不承诺原生复制行为。
10. 默认把内容改写成“兼容性优先”的门户式 MD 文件：
• 用简单的内联 HTML 做布局、hero、摘要卡片和章节卡片。
• 除非用户明确要求改写，否则文案尽量贴近源 HTML / MD。
• 为了可读性与展示效果可以重组结构，但不要凭空加入解读、培训说明、导读文案或“本页说明”一类的新增内容。
• 如果 iWiki 把行内 code 拆到单独一行，就改成显式设置等宽字体的 span。
• 给主要模块留出明确的竖向间距，方便后续局部微调。
• 允许在模板约束内做有限变体，例如调整 hero 渐变、强调色、CTA 数量、卡片数量、章节顺序、附加下载/命令/数据摘要模块，但不能破坏模板骨架、兼容性标签约束和安全样式边界。
• 只有在用户明确要求，或富文本门户布局渲染不稳定时，才退回朴素 Markdown。
11. 如果 CLI 验证因为运行时兼容性失败，不要阻塞内容工作：
• 仍然先产出最终的 iWiki 兼容 MD 文件。
• 明确说明这是环境阻塞，不是内容转换失败。
• 先引导 Agent 完成当前环境所需的运行时升级。
• 升级后，在新环境里重新完成 iwiki-cli 安装与验证，再从该环境发布。
• 只有在升级路线不可行时，才建议换到其他兼容环境。
• 手工粘贴只作为最后兜底方案。
12. 发布时使用 iwiki-cli update -f ，或先创建页面再发布；发布后再用 metadata、get 和渲染结果抽查做校验。

兼容性规则

• 优先使用 div、span、a、strong 这类内联 HTML。
• 样式优先保持保守：color、padding、margin、border、border-radius、background、font-size、line-height。
• 卡片布局优先用简单的 display:flex + flex-wrap:wrap。
• 当整页深色容器渲染不稳定时，优先使用白底或浅色卡片布局。
• 只有在用户明确需要原生复制，且能接受代码块脱离 HTML 卡片时，才使用 fenced code block。
• 当行内代码被强制换行时，用设置等宽字体的 span 代替裸 code 标签。
• 当视觉一体化比原生复制更重要时，用普通 div 容器加转义文本来实现 HTML 代码面板。
• 章节锚点保持简单，例如 id="install"、href="#install"。

除非参考页已经证明可用，否则默认避免：

• 、、、