# Doc Smith Publish

> 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. Use when this capability is needed.

- Skill: `tomevault-io/doc-smith-publish` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/doc-smith-publish`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/doc-smith-publish/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/doc-smith-publish

---


# 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`） |

## 预授权凭证

当用户消息中包含访问凭证（以 `blocklet-` 开头的字符串）时，**在发布之前先保存凭证**：

```bash
node {skill_path}/scripts/save-token.mjs --token "<credential>" --hub <hub-url>
```

`--hub` 参数指定凭证所属的 DocSmith Hub。**必须显式传递 `--hub`** 以匹配发布目标 Hub。如果用户在发布命令或消息中指定了自定义 hub（通过 `--hub`），在此处使用相同的 URL。不要依赖默认值。

凭证会持久保存到 `~/.aigne/`，后续发布将自动使用，无需浏览器授权。

如果用户消息中包含凭证，始终在此步骤中提取并保存，即使已有凭证。

## 工作流

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

### 步骤 3.5：检测 GitHub 仓库信息

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

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

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

> **注意**：`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 |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/aigne-io) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->