---
name: publish
description: 发布 ai-proj-helper 技能市场更新并通知飞书群。用户说 /publish 时激活。
user_invocable: true
---

# publish - 技能市场发布与通知

发布 ai-proj-helper 的技能变更，重新生成 marketplace.json，提交推送到 Gitea，并通过飞书 Webhook 通知团队。

## 命令

**`/publish [消息]`** — 发布当前变更并通知飞书

## 流程

```
1. 检查工作目录状态 (git status)
2. 运行 generate-marketplace.py 重新生成 marketplace.json
3. 生成变更摘要（新增/更新/删除了哪些技能）
4. git add + commit + push
5. 发送飞书卡片通知
```

## 详细步骤

### Step 1: 检查工作目录

```bash
cd <ai-proj-helper-root>
git status
```

确认当前在正确的仓库中。如果没有任何变更（包括 marketplace.json），提示用户无需发布。

### Step 2: 重新生成 marketplace.json

```bash
cd <ai-proj-helper-root>
python3 generate-marketplace.py
```

输出会显示扫描到的各分类技能数量。

### Step 3: 生成变更摘要

对比 `git diff` 结果，提取变更内容：

- **新增技能**：新出现的 `*-plugin/` 目录
- **更新技能**：已有技能的 SKILL.md 或 plugin.json 变更
- **删除技能**：被移除的 `*-plugin/` 目录
- **配置变更**：claude-config.yaml、init.sh 等基础文件变更

摘要格式：
```
新增: feishu-bitable-plugin, doubao-voice-plugin
更新: req-plugin (SKILL.md)
删除: old-plugin
配置: init.sh 默认改为 SSE 模式
```

### Step 4: Git 提交并推送

```bash
cd <ai-proj-helper-root>
git add -A
git commit -m "chore(marketplace): <变更摘要>"
git push origin main
```

Commit message 示例：
- `chore(marketplace): add feishu-bitable-plugin, update req-plugin`
- `chore(marketplace): update init.sh to SSE default`

### Step 5: 飞书通知

**Webhook 地址**：从环境变量 `FEISHU_DEPLOY_WEBHOOK` 读取，配置在 `~/.config/devops/credentials.env`。

如果环境变量未设置，AskUserQuestion 询问用户提供 webhook URL，并建议添加到 credentials.env。

**卡片格式**（必须用 legacy format，不用 schema 2.0）：

```bash
# 先 source 凭据
source ~/.config/devops/credentials.env

# 构建卡片 JSON（必须写文件，不能直接传中文 JSON）
cat > /tmp/publish_notify.json << 'CARD_EOF'
{
  "msg_type": "interactive",
  "card": {
    "header": {
      "title": {"tag": "plain_text", "content": "AI 技能市场更新"},
      "template": "green"
    },
    "elements": [
      {
        "tag": "div",
        "text": {"tag": "lark_md", "content": "CHANGE_SUMMARY_HERE"}
      },
      {
        "tag": "div",
        "text": {"tag": "lark_md", "content": "**提交**: COMMIT_HASH_HERE"}
      },
      {
        "tag": "action",
        "actions": [{
          "tag": "button",
          "text": {"tag": "plain_text", "content": "查看仓库"},
          "type": "primary",
          "url": "https://gitea.pipexerp.com/pipexerp/ai-proj-helper"
        }]
      }
    ]
  }
}
CARD_EOF

# 替换占位符后发送
curl -s -X POST "$FEISHU_DEPLOY_WEBHOOK" \
  -H "Content-Type: application/json" \
  -d @/tmp/publish_notify.json
```

**重要**：
- 必须用 legacy card format（无 schema 字段），否则返回 ErrCode 11246
- 中文内容必须先写文件再 `curl -d @file`，直接传会出现 "blank argument" 错误
- `template` 颜色：`green`=成功，`red`=失败，`blue`=信息

### 自定义消息

用户可以在 `/publish` 后附加自定义消息，会追加到卡片内容中：

```
/publish 新增飞书多维表格技能，支持批量数据导入
```

卡片内容将包含：
```
**更新说明**: 新增飞书多维表格技能，支持批量数据导入

**变更**: 新增 feishu-bitable-plugin
**提交**: abc1234
```

## 环境配置

在 `~/.config/devops/credentials.env` 中添加：

```bash
# 飞书部署通知 Webhook
FEISHU_DEPLOY_WEBHOOK="https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_WEBHOOK_KEY"
```

## 错误处理

| 场景 | 处理 |
|------|------|
| 无变更可提交 | 提示用户，跳过后续步骤 |
| generate-marketplace.py 失败 | 显示错误，中止发布 |
| git push 失败 | 显示错误，建议手动解决冲突 |
| FEISHU_DEPLOY_WEBHOOK 未配置 | AskUserQuestion 询问 webhook URL |
| 飞书通知发送失败 | 显示 curl 返回值，提示但不阻断（代码已推送成功） |

## 注意事项

- 此技能操作的仓库路径由 marketplace 插件根目录决定
- 发布前确认 `generate-marketplace.py` 输出无异常
- 飞书通知是 best-effort，失败不影响代码发布