asc-plugin-release

将插件发布到 ASC 注册表

将 .plugin 包发布到 tddworks/asc-registry，以便用户使用 asc plugins install --name <id> 安装。

前提条件

• gh CLI 已完成身份验证（gh auth status）
• 拥有对 tddworks/asc-registry 的写入权限（或采用 fork + PR 工作流）
• 插件包含 manifest.json，且至少定义了 name、version、server
• 插件可通过 make build 或等效方式构建

工作流

步骤 1：定位并读取清单文件

找到插件的 manifest.json（位于 plugin/manifest.json 或已构建的 .plugin/manifest.json）。提取以下字段：

字段	必填	用途
name	是	注册表的 name 字段
version	是	注册表的 version 字段和发布标签
description	是	注册表的 description 字段
author	否	注册表的 author 字段
repositoryURL	否	注册表的 repositoryURL 字段
categories	否	注册表的 categories 字段
server	是	验证插件是否包含 dylib

如果清单文件中缺少 description、author 或 categories，请先让用户提供这些信息再继续——这些字段有助于用户在市场中发现插件。

步骤 2：构建插件

make build

验证 .plugin 目录存在，且其中包含 manifest.json 引用的 dylib：

ls -la .build/<Name>.plugin/
# Should contain: manifest.json, <Name>.dylib, and optionally ui/

步骤 3：创建 zip 文件

cd .build && zip -r /tmp/<Name>.plugin.zip <Name>.plugin/

验证 zip 文件大小合理，并包含预期文件：

unzip -l /tmp/<Name>.plugin.zip

步骤 4：生成注册表条目

根据插件名称生成注册表 ID：转换为小写，并将空格替换为连字符。

"ASC Pro" → "asc-pro"
"Hello Plugin" → "hello-plugin"

构建注册表条目的 JSON：

{
  "id": "<derived-id>",
  "name": "<from manifest.name>",
  "version": "<from manifest.version>",
  "description": "<from manifest.description>",
  "author": "<from manifest.author>",
  "repositoryURL": "<from manifest.repositoryURL>",
  "downloadURL": "https://github.com/tddworks/asc-registry/releases/latest/download/<Name>.plugin.zip",
  "categories": ["<from manifest.categories>"]
}

如果清单文件中没有 author、repositoryURL 或 categories，则省略这些字段。

步骤 5：克隆并更新 registry.json

# Clone the registry (or pull if already cloned)
cd /tmp && rm -rf asc-registry && git clone https://github.com/tddworks/asc-registry.git
cd /tmp/asc-registry

读取 registry.json，然后执行以下操作之一：

• 新插件：将条目追加到 plugins 数组
• 已有插件（id 相同）：替换现有条目（更新版本、描述等）

以正确格式（2 个空格缩进）写入更新后的 registry.json。

步骤 6：将 zip 上传到 GitHub Release

检查是否已存在 Release，然后上传到现有 Release 或创建新的 Release：

# Check existing release
gh release view v<version> --repo tddworks/asc-registry 2>/dev/null

# If release exists, upload as additional asset (delete old asset with same name first)
gh release delete-asset v<version> <Name>.plugin.zip --repo tddworks/asc-registry --yes 2>/dev/null
gh release upload v<version> /tmp/<Name>.plugin.zip --repo tddworks/asc-registry

# If no release exists, create one
gh release create v<version> /tmp/<Name>.plugin.zip \
  --repo tddworks/asc-registry \
  --title "v<version> — <plugin name>" \
  --notes "<plugin description>"

步骤 7：推送更新后的 registry.json

cd /tmp/asc-registry
git add registry.json
git commit -m "feat: update <plugin-id> to v<version>"
git push

步骤 8：验证

# Verify the registry is accessible
curl -s https://raw.githubusercontent.com/tddworks/asc-registry/main/registry.json | python3 -m json.tool

# Verify the download URL works
curl -sI "https://github.com/tddworks/asc-registry/releases/latest/download/<Name>.plugin.zip" | head -5

向用户报告结果：

• 注册表 URL：https://github.com/tddworks/asc-registry
• 安装命令：asc plugins install --name <id>
• Release URL：https://github.com/tddworks/asc-registry/releases/tag/v<version>

示例：发布 hello-plugin

# 1. Build
cd examples/hello-plugin && make build

# 2. Zip
cd .build && zip -r /tmp/HelloPlugin.plugin.zip HelloPlugin.plugin/

# 3. Read manifest → derive entry
# manifest.json: name="Hello Plugin", version="1.0" → id="hello-plugin"

# 4. Update registry
cd /tmp/asc-registry
# Add/update entry in registry.json with:
# "downloadURL": "https://github.com/tddworks/asc-registry/releases/latest/download/HelloPlugin.plugin.zip"

# 5. Upload + push
gh release upload v1.0 /tmp/HelloPlugin.plugin.zip --repo tddworks/asc-registry
git add registry.json && git commit -m "feat: update hello-plugin to v1.0" && git push

发布前完善 manifest.json

如果清单文件缺少市场字段，请在构建前更新：

{
  "name": "My Plugin",
  "version": "1.0",
  "description": "What the plugin does",
  "author": "your-name",
  "repositoryURL": "https://github.com/you/my-plugin",
  "categories": ["category1", "category2"],
  "server": "MyPlugin.dylib",
  "ui": ["ui/my-ui.js"]
}

这些字段会写入注册表条目，并显示在 asc plugins market list 和 Command Center Plugins 页面中。