doc-smith-publish

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：检测发布目标

按以下优先级确定发布目录：

1. 用户指定 --dir 参数 → 使用指定目录
2. 未指定 → 检查 .aigne/doc-smith/dist 目录是否存在
3. 以上都不存在 → 检查当前目录是否包含 assets/nav.js（doc-smith 输出标志）
4. 都找不到 → 报错，提示用户先运行 /doc-smith-create 生成文档

步骤 3：读取 Metadata

从 .aigne/doc-smith/config.yaml 读取：

• projectName → 发布标题（title）
• projectDesc → 发布描述（description）

如果 config.yaml 不存在或字段缺失，使用目录名作为标题。

步骤 3.5：检测 GitHub 仓库信息

发布脚本会自动执行以下检测（无需手动操作）：

1. 执行 git remote get-url origin，判断当前项目是否托管在 GitHub
2. 如果是 GitHub 仓库，调用 GitHub API 获取仓库 owner 的头像 URL 作为 coverImage
3. 这两个字段会自动附加到发布请求中，如果获取失败则静默忽略

步骤 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