| name | doc-smith-publish |
| description | Publish documentation generated by doc-smith-create to DocSmith Cloud and obtain an online preview URL. Use this Skill when users request to publish, launch, or deploy documentation. |
DocSmith 文档发布
将本地生成的 HTML 文档一键发布到 DocSmith Cloud，返回在线预览 URL。
用法
/doc-smith-publish
/doc-smith-publish --dir .aigne/doc-smith/dist
/doc-smith-publish --hub https://custom.hub.io
选项
| Option | Alias | Description |
|---|
--dir <path> | -d | 指定发布目录（默认自动检测） |
--hub <url> | -h | DocSmith Hub URL（默认 https://docsmith.aigne.io） |
预授权凭证
当用户消息中包含访问凭证（以 blocklet- 开头的字符串）时，在发布之前先保存凭证：
node {skill_path}/scripts/save-token.mjs --token "<credential>" --hub <hub-url>
--hub 参数指定凭证所属的 DocSmith Hub。必须显式传递 --hub 以匹配发布目标 Hub。如果用户在发布命令或消息中指定了自定义 hub（通过 --hub），在此处使用相同的 URL。不要依赖默认值。
凭证会持久保存到 ~/.aigne/，后续发布将自动使用，无需浏览器授权。
如果用户消息中包含凭证，始终在此步骤中提取并保存，即使已有凭证。
工作流
步骤 1：检查依赖
test -d {skill_path}/scripts/node_modules || (cd {skill_path}/scripts && npm install)
其中 {skill_path} 是本 Skill 的目录路径（skills/doc-smith-publish）。
步骤 2：检测发布目标
按以下优先级确定发布目录：
- 用户指定
--dir 参数 → 使用指定目录
- 未指定 → 检查
.aigne/doc-smith/dist 目录是否存在
- 以上都不存在 → 检查当前目录是否包含
assets/nav.js（doc-smith 输出标志）
- 都找不到 → 报错，提示用户先运行
/doc-smith-create 生成文档
步骤 3：读取 Metadata
从 .aigne/doc-smith/config.yaml 读取：
projectName → 发布标题（title）projectDesc → 发布描述（description）
如果 config.yaml 不存在或字段缺失，使用目录名作为标题。
步骤 3.5：检测 GitHub 仓库信息
发布脚本会自动执行以下检测（无需手动操作）：
- 执行
git remote get-url origin，判断当前项目是否托管在 GitHub
- 如果是 GitHub 仓库，调用 GitHub API 获取仓库 owner 的头像 URL 作为 coverImage
- 这两个字段会自动附加到发布请求中，如果获取失败则静默忽略
步骤 4：执行发布
构造配置 JSON 并调用发布脚本：
node {skill_path}/scripts/publish.mjs --config-stdin <<'EOF'
{
"source": { "type": "dir", "path": "{dist_path}" },
"hub": "{hub_url}",
"workspace": ".aigne/doc-smith",
"metadata": {
"title": "{title}",
"description": "{description}",
"visibility": "public"
}
}
EOF
注意：githubRepo 和 coverImage 由脚本自动检测，通常不需要在配置中手动指定。如需覆盖，可在 metadata 中添加 "githubRepo": "..." 和 "coverImage": "..."。
变量说明：
{skill_path}：本 Skill 目录路径{dist_path}：步骤 2 确定的发布目录{hub_url}：DocSmith Hub URL（默认 https://docsmith.aigne.io，--hub 可覆盖）{title}：步骤 3 获取的标题{description}：步骤 3 获取的描述
步骤 5：清除 Hub 缓存
发布成功后，脚本会自动调用 DocSmith Web 的 showcase 缓存清除接口，确保 Hub 展示页面能立即显示最新内容。此步骤为非阻塞操作，失败不影响发布结果。
步骤 6：展示结果
发布成功后，脚本会输出预览 URL。向用户展示：
文档已发布成功！预览地址：{vibeUrl}
发布脚本会自动将 vibeUrl 写入 .aigne/doc-smith/config.yaml 的 appUrl 字段。
错误处理
| 错误 | 处理 |
|---|
| dist 目录不存在 | 提示用户先运行 /doc-smith-create 生成文档 |
| config.yaml 不存在 | 提示当前目录非有效 doc-smith workspace |
| 依赖未安装 | 自动执行 npm install（步骤 1） |
| 401/403 授权错误 | 脚本自动清除 token，提示用户重新运行 /doc-smith-publish |
| 网络错误 | 提示用户检查网络后重试 |
| publish action 失败 | 提示用户重新运行 /doc-smith-publish |
| Private mode 错误 | 提示改为 public 或升级账户 |
| 云端 Agent 授权超时 | 引导用户从 https://docsmith.aigne.io/openclaw 获取发布 prompt |
