---
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。

## 用法

```bash
/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`） |

## 工作流

### 步骤 1：检查依赖

```bash
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 不存在或字段缺失，使用目录名作为标题。

### 步骤 4：执行发布

构造配置 JSON 并调用发布脚本：

```bash
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
```

**变量说明**：
- `{skill_path}`：本 Skill 目录路径
- `{dist_path}`：步骤 2 确定的发布目录
- `{hub_url}`：DocSmith Hub URL（默认 `https://docsmith.aigne.io`，`--hub` 可覆盖）
- `{title}`：步骤 3 获取的标题
- `{description}`：步骤 3 获取的描述

### 步骤 5：展示结果

发布成功后，脚本会输出预览 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 或升级账户 |