mcpField
D
doc-smith-publish

doc-smith-publish

github.com/aigne-io云与 DevOps946 次安装32 周前更新
代码仓库

关于 doc-smith-publish

doc-smith-publish 是用于将本地生成的 HTML 文档发布到 DocSmith Cloud 的技能，面向文档发布流程。它可检测文档目录和元数据，并返回在线预览地址。

主要功能

  1. 01发布本地 HTML 文档
  2. 02自动检测发布目录
  3. 03读取项目标题和描述
  4. 04支持指定 Hub 地址
  5. 05发布后返回预览 URL

适用场景

  1. 01发布生成的 DocSmith 文档
  2. 02将文档发布到自定义 Hub
  3. 03查看已发布文档的在线预览

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aigne-io/doc-smith-skills --skill doc-smith-publish

安装后在 Claude Code 中输入/doc-smith-publish确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
package-lock.json
package.json
publish.mjs
save-token.mjs
scripts/utils/
auth.mjs
blocklet-info.mjs
constants.mjs
history.mjs
http.mjs
store.mjs
upload.mjs
zip.mjs

详细介绍

来自项目 README

DocSmith 文档发布

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

用法

/doc-smith-publish
/doc-smith-publish --dir .aigne/doc-smith/dist
/doc-smith-publish --hub https://custom.hub.io

选项

OptionAliasDescription
--dir <path>-d指定发布目录（默认自动检测）
--hub <url>-hDocSmith 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

评论

支持 Markdown