用途:在 SpecWeave 项目中启动并管理 Docusaurus 文档服务器,用于本地查看 living documentation,支持内部文档与公开文档两种视图。
主要能力:零配置即可在任何 SpecWeave 项目中使用;内部文档默认运行在 3015 端口,公开文档运行在 3016 端口;Docusaurus 安装缓存在 .specweave/cache/docs-site/(公开文档为 .specweave/cache/docs-site-public/),并被 gitignore;支持编辑 Markdown 后热重载即时生效;支持 Mermaid 架构图渲染;侧边栏按文件夹结构自动生成;安装通过公共 npm registry 绕开私有或企业 registry 问题。
使用方式:
- 查看内部文档(默认):/sw-docs:view,检查 .specweave/docs/internal/,执行预检并自动修复常见问题,首次约 30 秒完成安装,随后启动 http://localhost:3015。
- 查看公开文档:/sw-docs:view --public,检查 .specweave/docs/public/,启动 http://localhost:3016。
- 构建静态站点:/sw-docs:build,输出到 .specweave/cache/docs-site/build/,可部署到任意静态托管。
适用场景:需要预览或演示 SpecWeave 文档、启动本地文档服务器、查看内部或公开文档时。
限制与排查:端口 3015 或 3016 被占用时可用 lsof 与 kill 释放;需重装时可删除对应缓存目录后重新运行命令;npm registry 问题通过 --registry=https://registry.npmjs.org 处理。相关命令还包括 /sw-docs:organize、/sw-docs:health、/sw-docs:validate。