md-to-wiki — 轻量路由器(阶段 2)
将 Markdown 规范文件转换为文档站点。
触发词: "build wiki", "generate docs", "publish specs", "make a site", "wiki from markdown", "draw diagram", "flow chart", "architecture diagram", "state diagram", "sequence diagram"
阶段路由器
分析用户请求以确定要采取哪条路径:
lower=$(echo "$1" | tr '[:upper:]' '[:lower:]')
case "$lower" in
*"not sure"*|*"help"*|*"recommend"*) ROUTE="onboarding" ;;
*"html"*|*"site"*|*"mkdocs"*|*"material"*) ROUTE="mkdocs" ;;
*"swagger"*|*"openapi"*|*"api"*) ROUTE="swagger" ;;
*"github wiki"*|*"wiki tab"*) ROUTE="github-wiki" ;;
*"dokuwiki"*|*"doku"*) ROUTE="dokuwiki" ;;
*"pdf"*|*"print"*|*"book"*) ROUTE="pdf" ;;
*"reference"*|*"issue"*|*"pr"*|*"pull"*) ROUTE="references" ;;
*"deploy"*|*"publish"*|*"go live"*) ROUTE="deploy" ;;
*) ROUTE="onboarding" ;;
esac
然后启动相应的代理:
| 路由 | 代理 | 描述 |
|---|---|---|
onboarding | agents/onboarding.md | 与用户对话,检测操作系统,设置 SKILL_DIR |
mkdocs | agents/format-mkdocs.md | 生成 MkDocs Material 站点 |
swagger | agents/format-swagger.md | 生成 OpenAPI 3.0 + Swagger UI |
github-wiki | agents/format-github-wiki.md | 发布到 GitHub Wiki |
dokuwiki | agents/format-dokuwiki.md | 转换为 DokuWiki 格式 |
pdf | agents/format-pdf.md | 通过 Pandoc 生成 PDF |
references | agents/references.md | 用 GitHub Issue/PR 引用丰富文档 |
deploy | agents/deploy.md | 将生成的文档部署到托管平台 |
执行流程
- 入导 → 询问问题:项目名称、源目录、受众(开发者/利益相关者/普通用户)、期望格式。一旦检测到操作系统,存储
SKILL_DIR、SCRIPT_EXT、SCRIPT_RUNNER。 - 格式生成 → 加载相应的格式代理。使用
$SCRIPT_RUNNER从scripts/目录调用配套脚本。 - 引用 → 如果用户需要 Issue/PR 引用,加载 references.md。
- 部署 → 生成完成后,加载 deploy.md 提供托管选项。
全局变量(入导阶段设置一次)
SKILL_DIR— 解析到此技能文件夹的路径SCRIPT_EXT—.sh或.ps1SCRIPT_RUNNER—""或"powershell -File"OS_TYPE—unix或windowsPROJECT_NAME— 来自用户SOURCES— 规范文件路径AUDIENCE—developer、stakeholder或general
配套脚本
所有脚本在 .sh 和 .ps1 版本中都以相同方式接受位置参数:
| 脚本 | 用途 |
|---|---|
discover-sources | 扫描目录查找规范/项目/代码库/快速文件 |
generate-mkdocs | 创建完整的 mkdocs.yml + 页面结构 |
generate-index | 构建适合受众的登录页面 |
to-dokuwiki | 将 markdown 转换为 DokuWiki 语法 |
to-pdf | 合并并通过 pandoc 转换为 PDF |
fetch-issues | 缓存 GitHub Issue/PR 元数据 |
多目录输入
在运行前将多个源目录合并到 merged-specs/:
mkdir -p merged-specs && cp -r .specs/* docs/* merged-specs/
共享
将 md-to-wiki/ 复制到同事的 .config/opencode/skills/ 或 .opencode/skills/ 目录。依赖项因格式而异。