# 插件市场 CLI 设计稿

本文档面向 CLI 与开发者工具团队，定义插件市场发布工具的职责边界、命令模型、交互流程与实现约束。

## 一、定位

CLI 不是辅助脚本，而是插件市场标准发布链路的唯一规范入口。

它的职责是将插件作者从“手工建仓库、手工打包、手工发 Release、手工同步市场”中解放出来，改为可校验、可重试、可审计的标准流水线。

## 二、CLI 目标

1. 一键初始化符合平台规范的插件工程与 GitHub 仓库配置。
2. 在本地发布前完成结构、元数据、版本与兼容性校验。
3. 自动完成打包、生成校验值、创建 tag、创建 GitHub Release、上传资产。
4. 自动向中心服务器提交插件与版本元数据。
5. 提供状态查询、重试、同步修复与环境诊断能力。

## 三、CLI 不负责的事情

1. 不负责替代 GitHub 进行源码托管。
2. 不负责中心服务器的审核决策。
3. 不负责客户端安装逻辑。
4. 不负责长期保存任何敏感令牌。

## 四、推荐命令模型

### 1. 工程初始化

1. `market init`
   创建插件项目基础结构、插件清单、README 模板、CHANGELOG 模板、GitHub Actions 模板、发布配置。
2. `market github bind`
   将本地插件工程绑定到已有 GitHub 仓库。
3. `market github create`
   通过 GitHub API 创建规范仓库并写入默认配置。

### 2. 本地校验与打包

1. `market validate`
   校验目录结构、清单字段、版本号、依赖声明、兼容范围、资产命名与必要文档是否齐全。
2. `market package`
   生成标准插件包并输出 sha256、文件大小、包名等构建结果。
3. `market doctor`
   检查本地 Git、GitHub Token、中心服务器连通性、仓库权限、当前分支状态。

### 3. 发布与同步

1. `market release publish`
   创建 tag、创建 Release、上传资产、填写或生成发布说明。
2. `market submit`
   首次向中心服务器注册插件。
3. `market sync`
   向中心服务器同步版本元数据或修复 GitHub 与中心索引漂移。
4. `market status`
   查询插件当前审核状态、上架状态、收录版本、最近同步结果。

### 4. 治理与维护

1. `market version yank`
   将指定版本标记为撤回。
2. `market owner verify`
   完成作者身份验证与维护者关系绑定。
3. `market metadata update`
   更新插件介绍、标签、分类、主页、文档地址等基础信息。

## 五、标准发布流水线

建议 CLI 内部将“一键发布”拆成以下阶段，以支持中断恢复和故障定位：

1. 读取插件清单与发布配置。
2. 校验插件 ID、版本号、宿主兼容范围、插件 API 版本。
3. 校验仓库工作区状态，避免脏状态发布。
4. 生成发布产物并计算 sha256。
5. 校验产物命名与结构。
6. 调用 GitHub API 创建 tag 与 Release。
7. 上传资产并确认 Release 资产可访问。
8. 调用中心服务器 API 同步插件与版本元数据。
9. 获取中心服务器返回的审核状态与同步结果。

## 六、推荐的本地项目规范

CLI 初始化的模板建议至少包含以下内容：

1. 插件清单文件，例如 `plugin.toml`。
2. README、LICENSE、CHANGELOG。
3. 发布配置文件，例如 `.market.toml`。
4. GitHub Actions 发布工作流模板。
5. 规范的源码目录与示例目录。

## 七、插件清单建议字段

CLI 需要围绕清单文件建立强校验。建议字段如下：

1. `plugin_id`
2. `display_name`
3. `version`
4. `description`
5. `license`
6. `repository_url`
7. `homepage`
8. `author`
9. `maintainers`
10. `plugin_api_version`
11. `min_host_version`
12. `max_host_version`
13. `categories`
14. `tags`
15. `entrypoints`

## 八、GitHub 集成要求

### 必要能力

1. 使用 GitHub OAuth 或本地 Token 完成授权。
2. 检查当前用户是否拥有目标仓库写权限。
3. 创建仓库、创建 tag、创建 Release、上传资产。
4. 可选生成 GitHub Actions 配置，支持自动化发布。

### 规范约束

1. Release tag 统一使用 SemVer 规则，建议形如 `v1.2.3`。
2. Release 资产命名统一，例如 `plugin_id-version.mfp`。
3. Release 说明至少包含版本摘要、兼容性说明、主要变更。

## 九、与中心服务器的交互设计

CLI 对接中心服务器时，应以幂等和可恢复为前提。

### 需要提交的信息

1. 插件基础元数据。
2. 仓库与作者身份信息。
3. 版本号、tag、发布日期。
4. 下载链接、文件大小、sha256。
5. 宿主兼容范围与插件 API 版本。
6. 是否为预发布版本。

### 需要获取的反馈

1. 插件是否注册成功。
2. 版本是否收录成功。
3. 当前审核状态。
4. 是否存在字段缺失或兼容性冲突。
5. 是否需要重新验证作者身份。

## 十、失败场景与恢复策略

CLI 设计必须明确处理中断与部分成功场景。

1. GitHub Release 已创建，但中心服务器同步失败。
   CLI 应记录当前 Release 信息，并允许作者稍后执行 `market sync`。
2. 资产上传成功，但校验值不匹配。
   CLI 应阻止提交市场索引。
3. 中心服务器拒绝收录版本。
   CLI 应输出明确原因，例如兼容范围非法、作者未验证、字段缺失。
4. 仓库权限不足。
   CLI 应在发布前快速失败，而不是在上传资产阶段才报错。

## 十一、安全要求

1. 不在本地明文长期保存高权限访问令牌。
2. 默认启用发布包 sha256 计算与输出。
3. 所有与中心服务器的请求必须包含身份认证。
4. 尽量避免 CLI 输出敏感仓库令牌和服务端返回的敏感字段。

## 十二、MVP 建议

第一版 CLI 建议聚焦以下能力：

1. 初始化插件工程模板。
2. 本地校验。
3. 打包与 sha256 生成。
4. GitHub Release 发布。
5. 中心服务器提交与状态查询。

以下可作为第二阶段：

1. GitHub Actions 自动发布模板增强。
2. 撤回版本与恢复上架命令。
3. 发布说明自动汇总与变更日志生成。
4. 组织级维护者协作命令。