aigne-io/doc-smith-skills/doc-smith-publish

DocSmith 文档发布

将本地生成的 HTML 文档一键发布到 DocSmith Cloud，返回在线预览 URL。

用法

/doc-smith-publish
/doc-smith-publish --dir .aigne/doc-smith/dist
/doc-smith-publish --hub https://custom.hub.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 字段。

错误处理