diff --git a/assets/screenshots/gitea-workflow-success.png b/assets/screenshots/gitea-workflow-success.png new file mode 100644 index 0000000..9cce6a0 Binary files /dev/null and b/assets/screenshots/gitea-workflow-success.png differ diff --git a/assets/screenshots/gitea-workflow-tab.png b/assets/screenshots/gitea-workflow-tab.png new file mode 100644 index 0000000..6727162 Binary files /dev/null and b/assets/screenshots/gitea-workflow-tab.png differ diff --git a/assets/screenshots/jc2009-download-page.png b/assets/screenshots/jc2009-download-page.png new file mode 100644 index 0000000..7f54d4d Binary files /dev/null and b/assets/screenshots/jc2009-download-page.png differ diff --git a/assets/screenshots/market-installed-skill.png b/assets/screenshots/market-installed-skill.png new file mode 100644 index 0000000..2968472 Binary files /dev/null and b/assets/screenshots/market-installed-skill.png differ diff --git a/assets/screenshots/new-task-usage.png b/assets/screenshots/new-task-usage.png new file mode 100644 index 0000000..70e132a Binary files /dev/null and b/assets/screenshots/new-task-usage.png differ diff --git a/references/DEVELOPMENT.md b/references/DEVELOPMENT.md index 632b543..d03b017 100644 --- a/references/DEVELOPMENT.md +++ b/references/DEVELOPMENT.md @@ -345,7 +345,114 @@ python scripts/main.py log-get 1 python scripts/main.py publish ``` -## 15. 发布前检查清单 +## 15. 发布到正式环境验证 + +当本地开发、自测和联调完成后,还需要把 skill 发布到正式环境做一次完整验证。建议技术人员严格按下面顺序执行,不要跳步。 + +### 第一步:在 skill 根目录执行 `release.ps1` + +在当前 skill 仓库根目录执行: + +```powershell +.\release.ps1 +``` + +这一步会自动完成标准发布动作,包括: + +1. 检查当前仓库状态 +2. 自动提交尚未提交的改动 +3. 推送最新代码到远程仓库 +4. 自动创建新的语义化版本 tag +5. 推送 tag,触发后续 CI 流程 + +如果你只是想先预览发布动作,可以先执行: + +```powershell +.\release.ps1 -DryRun +``` + +### 第二步:到 Gitea 仓库查看工作流 + +发布命令执行完成后,远程仓库会自动触发 Gitea 工作流。此时应立即进入对应 skill 的仓库页面,切换到“工作流”页签查看执行状态。 + +重点确认: + +- 是否已经出现最新一次发布记录 +- 是否由最新提交触发 +- 是否成功执行完 `release_skill.yaml` + +下面这张图演示了在仓库页进入“工作流”的位置: + +![Gitea 仓库工作流入口](../assets/screenshots/gitea-workflow-tab.png) + +下面这张图演示了工作流成功后的状态页面: + +![Gitea 工作流成功示例](../assets/screenshots/gitea-workflow-success.png) + +### 第三步:确认工作流执行成功 + +只有当工作流状态为成功,才说明正式发布产物已经正确构建完成。 + +如果工作流失败,不要继续做平台验证,而应该先回到代码仓库排查,例如: + +- 发布脚本是否正常推送 +- `SKILL.md`、`scripts/`、`references/` 是否齐全 +- 工作流文件是否存在 +- 发布包结构是否符合模板规范 + +### 第四步:进入匠厂平台下载安装包 + +当工作流成功后,就可以进入匠厂平台验证最终安装效果。 + +匠厂产品下载地址: + +- [https://jc2009.com/product.html](https://jc2009.com/product.html) + +打开页面后,下载并安装匠厂客户端。下面这张图演示了下载入口位置: + +![匠厂客户端下载入口](../assets/screenshots/jc2009-download-page.png) + +匠厂产品页可从这里进入:[产品下载 - 匠厂](https://jc2009.com/product.html) + +### 第五步:安装匠厂后,在技能市场检查最新 skill + +安装并启动匠厂后,进入左侧“技能市场”,搜索或查找刚刚发布的 skill,确认以下内容: + +- 技能可以被正常检索到 +- 技能名称、说明、版本信息正确 +- 最新版本已经同步出来 +- 可以正常安装或更新 + +下面这张图演示了在技能市场中查看已发布 skill 的位置: + +![技能市场中的已发布技能](../assets/screenshots/market-installed-skill.png) + +### 第六步:安装并实际启用该 skill + +在技能市场中找到目标 skill 后,执行安装或更新操作,确保客户端本地已经拿到最新版本。 + +这一步建议至少确认: + +- 安装按钮可以正常执行 +- 安装后状态正常 +- 不会出现缺文件、缺入口或安装失败的问题 + +### 第七步:在“新建任务”中实际使用该 skill + +安装完成后,不要只停留在“已安装”状态,还需要进入“新建任务”页面,真正调用一次该 skill,完成最终验证。 + +建议至少验证: + +- 新任务中可以正常选择或触发该 skill +- skill 能被正确唤起 +- 主要命令或主流程可以运行 +- 返回结果、日志和行为符合预期 + +下面这张图演示了安装后在任务界面中实际使用 skill 的场景: + +![新建任务中使用技能](../assets/screenshots/new-task-usage.png) + +## 16. 发布前检查清单 每个新 skill 发布前,建议技术人员逐条确认: @@ -360,7 +467,7 @@ python scripts/main.py publish - [ ] `release.ps1` 存在 - [ ] `.github/workflows/release_skill.yaml` 存在 -## 16. 常见错误 +## 17. 常见错误 ### 错误 1:只改了目录名,没改 slug @@ -413,7 +520,7 @@ python scripts/main.py publish - 不做旧结构兼容 - 统一走 `references/` + `scripts/main.py` -## 17. 推荐开发顺序总结 +## 18. 推荐开发顺序总结 如果让一个新人照着做,我建议他按这个顺序: @@ -427,7 +534,7 @@ python scripts/main.py publish 8. 再做业务联调 9. 最后 release -## 18. 这份模板的底线要求 +## 19. 这份模板的底线要求 以后新建 skill,至少要满足这几点: