@yixiaoermail/cli 3.1.0

package/skills/yixiaoer/references/execution-standard.md

@@ -0,0 +1,144 @@
+# YiXiaoEr Skill 严格执行标准 (Strict Execution Standard)
+
+为了确保 蚁小二 (YiXiaoEr) 自动化技能在复杂 Agent 环境下的高可靠性、可追溯性以及版本一致性，所有调用者及技能维护者必须遵循本标准。
+
+## 1. 版本控制与一致性 (Versioning & Consistency)
+
+### 1.1 语义化版本
+- 技能必须在 `skills/yixiaoer/SKILL.md` 的 frontmatter 中明确标注 `version`（遵循 SemVer 规范）。
+- **执行要求**：Agent 在启动时**必须**校验环境中的技能版本是否符合预期（如 `>= 1.6.0`）。
+
+### 1.2 物理一致性 (Integrity)
+- 技能的核心逻辑（`cmd/`、`internal/`、`main.go`）不得在未修改版本号的情况下随意变动。
+- 自动化流水线应建议生成 Hash 值进行对比。
+
+## 2. 错误分类与标准码 (Standardized Error Codes)
+
+为了准确区分“Agent 使用错误”与“后端系统错误”，所有输出的错误 JSON 必须包含 `errorCode` 字段：
+
+| 错误代码 (errorCode) | 分类 | 触发场景 |
+| :--- | :--- | :--- |
+| `YIXIAOER_USAGE_ERR` | Agent 侧错误 | 参数缺失、JSON 格式错误、平台枚举值非法、资源未上传即发布。 |
+| `YIXIAOER_REMOTE_ERR` | 远端 API 错误 | 蚁小二后端返回 4xx/5xx、API Key 失效、配额超限。 |
+| `YIXIAOER_AUTH_ERR` | 鉴权错误 | 缺失 `YIXIAOER_API_KEY` 或 Key 无权访问特定接口。 |
+| `YIXIAOER_ENV_ERR` | 环境错误 | CLI 二进制缺失、关键环境变量缺失、网络不通。 |
+| `YIXIAOER_INTEGRITY_ERR` | 完整性错误 | 运行的代码与文档版本不一致。 |
+
+## 3. 资源预处理标准 (Pre-processing Standard)
+
+**核心约束：发布与上传必须物理分离**。
+
+1. **先上传再引用**：严禁在 `publish` Payload 中直接使用外部原始 URL。必须通过 `upload` action 获取系统内部 `key` 后进行替换。
+2. **ContentType 签名一致性**：获取预签名 URL 时声明的 `contentType` 必须与执行 PUT 上传时的 `Content-Type` Header **完全一致**。禁止自行猜测或随意留空，否则将导致 `SignatureDoesNotMatch` 错误。
+3. **封面图 (Cover)**：视频内容的封面图必须同样经过 `upload` 流程。
+4. **状态校验**：在上传统一资源后，建议通过 `material` 接口（若需要）将其同步至素材库以增加发布稳定性。
+5. **素材库原子化标准 (Material Library Standard)**：
+    - **严禁一步到位**：当用户请求“上传到素材库”时，Agent **必须**执行两个物理步骤：
+        1. **upload**：先将资源上传至 OSS（推荐 `bucket: "material-library"`）并获得 resource key。
+        2. **material**：持有 resource key，调用逻辑将资源登记到素材库并获得素材 ID。
+    - **错误规避**：严禁只执行 `upload` 而不执行 `material` 登记，否则用户在网页端将无法看到该素材。
+
+### 3.1 标准请求体兼容约定 (Standard Publish Request Compatibility)
+
+- CLI 现已兼容“标准请求体”输入格式。推荐将共享资源放在 `publishArgs` 根级，例如 `video`、`images`、`cover`、`coverKey`、`content`。
+- CLI 在执行 `validate` / `publish` 时，会在 `accountForms[]` 缺失对应资源字段时自动补齐：
+  - `publishArgs.video` -> `accountForms[i].video`
+  - `publishArgs.images` -> `accountForms[i].images`
+  - `publishArgs.cover` -> `accountForms[i].cover`
+  - `publishArgs.coverKey` -> `accountForms[i].coverKey`
+  - `publishArgs.content` -> `accountForms[i].contentPublishForm.content`
+- 业务扩展字段如 `mediaId`、`platformName`、`publishContentId`、`fps`、`isAppContent` 会被 CLI 保留并原样透传，不参与额外业务改写。
+- 命令层仍保持**单平台执行模型**：即使标准请求体本身可表达多平台，`yxer publish` 仍需按平台逐次调用。
+
+## 4. 调用序列与检索规范 (Interaction Flow)
+
+Agent 在执行任务时必须遵循以下“分级检索”逻辑：
+
+1. **L1 技能入口检索**：读取 `skills/yixiaoer/SKILL.md` 确定 `action` 类型。
+2. **L2 Domain / 索引检索**：在执行 `publish` 前，必须先读取对应 domain 与内容类型 `index.md`（如 `skills/yixiaoer/references/platforms/article/index.md`）确定 DTO 架构。
+3. **L3 平台细化**：根据目标平台（如“抖音”），读取 `skills/yixiaoer/references/platforms/video/douyin.md` 对 `platformSettings` 进行深度补全。
+4. **禁止跳级**：严禁在未读取 domain 与类型索引的情况下直接拼装平台参数。
+5. **动态数据预查**：对于 `categories` (分类)、`tags` (标签)、`locations` (位置) 等动态字段，Agent **必须**先通过对应的查询 action 获取当前平台的合法值，严禁基于常识或过时缓存进行猜测。
+
+## 5. 输出格式规范 (Output Schema)
+
+脚本输出必须为严格的 JSON。
+
+### 成功响应示例
+```json
+{
+  "success": true,
+  "action": "publish",
+  "version": "1.6.2",
+  "data": {
+    "task_set_id": "TS12345678"
+  }
+}
+```
+
+## 6. 错误处理与自检流程 (Error Handling & Self-Diagnosis)
+
+当脚本执行失败并返回 `success: false` 时，Agent 或开发者**必须**按照以下顺序进行自检：
+
+### 第零步：优先匹配避坑指南 (Step 0: Check Troubleshooting Guide)
+- 在进行任何深度调试前，**必须首先查阅**：[🛡️ 蚁小二 Skill 避坑与故障排查手册](./troubleshooting-guide.md)。
+- 检查出错现象是否符合手册中的“常见四大坑点”（版本、设备在线、表单架构、签名一致性）。如果匹配，直接按方案修正。
+
+
+### 第一步：检查版本一致性 (Check Version)
+- 检查当前运行环境中的 `skills/yixiaoer/SKILL.md` 版本号。
+- 确认 Agent 使用的 API 调用逻辑是否与该版本匹配。
+- **排查项**：是否因版本过低导致某些新增字段（如 `publishChannel`）未生效。
+
+### 第二步：检查请求参数规范 (Check Parameters)
+- 对比输出的 `details` 信息与 `skills/yixiaoer/references/` 下的 DTO 与平台定义。
+- **重点排查项 (必填项校验)**：
+    - **封面图 (cover/covers)**：是否提供了有效的资源 key？
+    - **视频资源 (video)**：视频发布是否包含必填的视频 key、标题或分类？
+    - **平台特定字段**：如公众号的 `author`、抖音的 `is_public` 等。
+- **重点排查项 (必填项校验)**：
+    - **分类与标签路径**：分类 (categories) 必须使用通过 `action: "categories"` 接口获取的**完整 `child` 路径数组**。严禁只填入末级 ID。
+    - **位置与话题**：如抖音的 POI 位置、话题等，必须通过对应的检索接口获取有效数据后果填入。
+- **排查项**：检查必填字段是否遗漏、数据类型（String/Number）是否符合文档、平台枚举名称是否正确。
+
+
+### 第三步：检查缓存与过期数据 (Check Cache & Stale Data)
+- 检查是否存在过期的缓存文件（如旧的 Payload JSON、过时的资源 Key）。
+- **资源上传专项排查**：在上传阶段如果出现 `SignatureDoesNotMatch` 错误，优先检查 `contentType` 定义是否与上传时的 Header **完全对齐**。Agent 在调用 `action: "upload-resource"` 时传入的 `contentType` 必须与后续 PUT 请求中的 `Content-Type` 字节级一致。
+- **发布通道与代理校验**：
+    - 若执行发布任务返回“获取在线设备列表失败”或提示“客户端不在线”，原因为选择了 **本机发布 (publishChannel: 'local')** 但环境中未运行蚁小二客户端。建议保持客户端在线，或修改为 **云发布 (publishChannel: 'cloud')**。
+    - 若**云发布**返回“账号代理不存在”，原因为账号绑定的独立代理 (proxyId) 失效或该平台强制需要代理配置。Agent 应先检查账号的 `proxyId` 或 `kuaidailiArea` 是否设置，并提示用户通过 `update-account` 绑定新的代理。
+- **执行逻辑**：如果怀疑使用了缓存导致的异常，必须清理相关临时文件并严格按照最新技能定义的流程重新执行（如重新执行 `upload` 流程）。
+- **草稿处理逻辑 (Draft Selection)**：当涉及“草稿”时，Agent 必须通过语义判断用户是指 **“蚁小二内部草稿”** (action: save-draft) 还是 **“发布到平台草稿箱”** (action: publish + pubType: 0)。**若语义不明确，Agent 必须询问用户以确认，严禁在未明确用户意图时随意选取一种或默认执行。**
+    - **平台草稿兼容性补丁**：若用户指定“发布到平台草稿箱”，Agent 遵循以下执行链：
+        1. **pubType 优先**：若平台定义了 `pubType`，使用 `pubType: 0`。
+        2. **visibleType 次之**：若无 `pubType` 但有 `visibleType` (或 `status`/`privacy`)，将其设为 **`1` (私密)**。对应的，`0` 表示公开。
+        3. **不支持告知**：若均无定义，则判定为不支持，必须提示用户。
+### 6.4 分类路径完整性校验 (Category Path Integrity)
+- **核心逻辑**：对于支持多级结构的分类（如 B 站视频分区），Agent 在填充表单时**必须**使用完整的 `child` 路径数组。
+- **数据获取**：直接透传从 `action: "categories"` 结果中提取的 `child` 字段。
+- **执行动作**：Agent 选中目标分类后，应直接将该对象的整个 `child` 数组填入 `contentPublishForm.category` 或对应字段。
+- **严禁**：严禁只填入单一的 `yixiaoerId` 或末级分类名。
+
+---
+
+## 7. 账号有效性校验 (Account Validity)
+- **校验标准**：Agent 在执行 `publish` 前，其选择的账号 `status` 必须为 `1` (有效)。
+- **严禁执行**：若账号 `status` 为 `2` (失效)，Agent **严禁**尝试执行发布任务，应立即提示用户账号需要重新登录或处理。
+- **数据来源**：账号状态必须通过 `action: "accounts"` 接口实时获取，不得依赖过期的历史数据。
+
+## 8. 避坑指南：常见失败场景 (Common Failure Scenarios)
+
+| 场景 | 原因分析 | 改进建议 |
+| :--- | :--- | :--- |
+| **版本不支持该功能** | 技能版本号过低，未包含新增动作或字段。 | 检查 `skills/yixiaoer/SKILL.md` 版本，提示用户升级或回退逻辑。 |
+| **获取在线设备失败** | 选用了“本机发布”但客户端未开启或未登录。 | 提示用户：**“蚁小二客户端需要保持在线”**，或者建议改为 **“云发布”** (publishChannel: 'cloud')。 |
+| **发布失败：表单错误** | Agent 生成的 JSON 结构与 `skills/yixiaoer/references/` 下的 DTO 架构不匹配。 | **强制核对**：Agent 必须校验传入表单是否符合对应平台的文档要求。 |
+| **任务卡在发布中/待发布** | 虽然 API 接收了请求，但表单内容不合规导致引擎挂起。 | **规则校验**：检查表单是否严格按照文档规则填入，特别是 `raw` 数据透传。 |
+| **发布失败：必填项缺失** | 忽略了平台要求的必填核心字段（如标题、分类）。 | **必填项自检**：检查文档中标记为“必填”的字段是否已全部填入。 |
+| **上传失败/签名不匹配** | `contentType` 在获取上传地址与执行 PUT 时不一致。 | **一致性校验**：必须确保 `action: "upload-resource"` 时传入的 `contentType` 与实际上传一致。 |
+| **云发布报错：账号代理不存在** | 账号绑定的独立代理 (`proxyId`) 已失效，或云发布环境未配置代理。 | **修复建议**：通过 `update-account` 为账号设置 `kuaidailiArea`（内置代理）或有效的 `proxyId`（独立代理）。 |
+
+---
+
+*本标准由 OpenClaw 架构组制定。违反本标准导致的发布失败或数据异常将由调用者承担相应责任。*

package/skills/yixiaoer/references/get-account-overviews.md

@@ -0,0 +1,56 @@
+# 获取账号数据概览 (Get Account Overviews V2)
+
+获取当前团队下各账号的综合表现概览。主要用于账号矩阵的权重分析、整体粉丝量监控及核心指标汇总。
+
+## 触发场景 (Trigger)
+- **意图辨析**：当用户需要宏观查看某个平台下的“账号全景图”，而不是单个作品的数据时。例如：分析团队资产总量、对比部门/负责人之间的账号表现差异。
+- **典型提示词**：
+  - “汇总一下我旗下所有抖音号的粉丝量”
+  - “我的视频号账号最近表现如何？”
+  - “查看张三负责的账号的数据看板”
+
+## 参数定义 (Parameters)
+
+### 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `action` | `string` | **是** | 固定值：`account-overviews` |
+| `platform` | `string` | **是** | 指定查询某个平台。见 [平台定义](./platform.md)。 |
+| `name` | `string` | 否 | 按照账号昵称模糊查询。 |
+| `group` | `string` | 否 | 按照分组名称查询。 |
+| `loginStatus` | `number` | 否 | 账号状态 (0未登录, 1成功, 2过期, 3失败)。 |
+| `memberIds` | `string[]` | 否 | 负责人成员 ID 数组 (ObjectId)。 |
+| `page` | `number` | 否 | 当前页码，默认 `1`。 |
+| `size` | `number` | 否 | 每页数量，默认 `10`。 |
+
+## 执行逻辑 (Logic Flow)
+1. **维度确定**：识别查询的目标平台（`platform` 为必填）。
+2. **权限过滤**：若提到特定人员，解析并注入其 `memberIds`。
+3. **参数装配**：构造 `action: "account-overviews"` 及分页参数。
+4. **指令执行**：当前能力正在迁移到 `yxer` CLI，本文档不再推荐脚本直调。
+5. **看板交付**：提取 `overviewData` 中的总粉丝数、总播放量等关键指标反馈给用户。
+
+## 返回结果说明 (Response Details)
+
+返回包含账号表现信息列表的对象。
+
+### 复杂对象：data.data[i] (账号概览对象)
+
+| 字段 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `platformAccountId` | `string` | 媒体账号 ID |
+| `platformAvatar` | `string` | 账号头像地址 |
+| `platformAccountName` | `string` | 账号昵称 |
+| `principalName` | `string` | 当前负责成员名 |
+| `overviewData` | `object` | 统计数据总计。包含 `fansTotal`, `playTotal`, `commentsTotal`, `likesTotal` 等。 |
+
+## 调用指令 (Command)
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```
+
+## 注意事项
+- **总量聚合**：账号数据 V2 提供的是总量的统计概览，适合查看整体情况。

package/skills/yixiaoer/references/get-challenges.md

@@ -0,0 +1,14 @@
+# 获取挑战/话题列表 (Get Challenges)
+
+获取平台当前进行的挑战活动或推荐的话题列表。
+
+## 1. 调用指令
+
+```bash
+yxer query challenges YOUR_ACCOUNT_ID --query 搜索词 --json
+```
+
+## 2. 返回数据结构
+
+返回 `Category` 数组。发布时必须直接使用 `yxer query challenges` 返回的完整对象，不能只保留 ID、名称或 `raw` 的局部字段。
+

package/skills/yixiaoer/references/get-collections.md

@@ -0,0 +1,34 @@
+# 获取合集列表 (Get Collections)
+
+获取账号已创建的合集列表。主要用于抖音、今日头条等支持合集的平台。
+
+## 调用指令 (Command)
+
+```bash
+yxer query collections ACCOUNT_ID --json
+```
+
+## 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `account_id` | `string` | **是** | 蚁小二账号 ID (32位十六进制) |
+
+返回一个 `Category` 数组。发布时必须直接使用 `yxer query collections` 返回的完整对象作为 `collection` 参数传递给发布流程，不能只保留 ID、名称或 `raw` 的局部字段。
+
+```json
+[
+  {
+    "yixiaoerId": "col_123",
+    "yixiaoerName": "美食系列",
+    "raw": { ... }
+  }
+]
+```
+
+## CLI / 后端逻辑
+
+- **CLI 命令**: `yxer query collections <account_id> [--type video|article] [--json]`
+- **功能**: 封装蚁小二标准化合集查询接口 (`GET /platform-accounts/{platformAccountId}/collections`)。
+- **参数映射**: 将 `account_id` 映射为 URL 路径变量，将 `type` 映射为 `publishType` 查询参数。
+

package/skills/yixiaoer/references/get-content-overviews.md

@@ -0,0 +1,59 @@
+# 获取作品数据 (Get Content Overviews)
+
+获取当前团队下各账号发布的作品数据统计信息。
+
+## 触发场景 (Trigger)
+- **意图辨析**：当用户需要查询、分析或导出已发布内容（视频、文章等）的传播数据（阅读量、点赞量、转发量等）时触发。
+- **典型提示词**：
+  - “我的抖音视频播放量怎么样了？”
+  - “查询最近 7 天所有账号的作品数据”
+  - “看看特定账号 A 的点赞情况”
+  - “由于最近流量下滑，查询表现最差的作品”
+
+## 参数定义 (Parameters)
+
+### 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `action` | `string` | **是** | 固定值：`content-overviews` |
+| `platform` | `string` | 否 | 指定查询某个平台。见 [平台定义](./platform.md)。 |
+| `platformAccountId` | `string` | 否 | 媒体账号 ID (ObjectId)。 |
+| `publishUserId` | `string` | 否 | 发布人 ID (ObjectId)。 |
+| `type` | `string` | 否 | 作品类型：`article` (文章), `video` (视频), `miniVideo` (短视频), `dynamic` (动态)。 |
+| `title` | `string` | 否 | 作品标题，支持模糊查询。 |
+| `publishStartTime` | `number` | 否 | 发布时间范围开始（Unix 时间戳，毫秒）。 |
+| `publishEndTime` | `number` | 否 | 发布时间范围结束（Unix 时间戳，毫秒）。 |
+| `page` | `number` | 否 | 当前页码，默认 `1`。 |
+| `size` | `number` | 否 | 每页数量，默认 `10`。 |
+
+## 执行逻辑 (Logic Flow)
+1. **需求解析**：识别用户查询的时间范围、平台及作品类型意图。
+2. **时间处理**：将相对时间（如“最近7天”）转换为 Unix 毫秒时间戳注入 `publishStartTime`。
+3. **参数装配**：构造 `action: "content-overviews"` 及其余过滤参数。
+4. **指令执行**：当前能力正在迁移到 `yxer` CLI，本文档不再推荐脚本直调。
+5. **数据反馈**：对返回的 `contentData` 进行聚合或横向对比，直接回答用户关心的关键性指标。
+
+## 返回结果说明 (Response Details)
+
+返回包含作品数据列表的对象。主要字段如下：
+
+### 复杂对象：data.data (作品对象)
+
+| 字段 | 类型 | 描述 |
+| :--- | :--- | :--- |
+| `platformAccountId` | `string` | 媒体账号 ID |
+| `accountName` | `string` | 账号昵称 |
+| `publishUserName` | `string` | 发布人昵称 |
+| `contentData` | `object` | 原始统计数据。包含 `reCommand` (推荐), `play` (播放), `read` (阅读), `great` (点赞), `comment` (评论), `share` (分享), `collect` (收藏) 等。 |
+| `updatedAt` | `number` | 数据更新时间戳 |
+
+## 调用指令 (Command)
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```
+
+## 注意事项
+- 查询大范围数据时，建议合理设置 `publishStartTime` 和 `publishEndTime` 以提高查询效率。

package/skills/yixiaoer/references/get-friends.md

@@ -0,0 +1,9 @@
+# 获取好友/关联对象 (Get Friends)
+
+本页用于兼容旧平台文档中的 `get-friends.md` 引用。
+
+当前 `yxer` CLI 没有稳定的独立 `friends` 查询命令。处理这类字段时：
+
+- 先以目标平台文档、`prepare`、`schema get` 为准
+- 如果没有明确 CLI 能力，不要猜测对象结构
+- 必要时提示用户当前能力未稳定 CLI 化

package/skills/yixiaoer/references/get-games.md

@@ -0,0 +1,39 @@
+# 获取可挂载游戏列表 (Get Games)
+
+获取发布视频时可挂载推广的游戏列表。该功能主要用于抖音等平台的“游戏推广”场景，通过挂载游戏链接赚取收益或进行内容深度联动。
+
+## 触发场景 (Trigger)
+- **意图辨析**：当用户在发布游戏相关的视频内容，并要求“挂载游戏链接”、“进行游戏推广”或“查找可推广的小游戏”时触发。
+- **典型提示词**：
+  - “我要推广这款小游戏，查看可用链接”
+  - “帮我找一下抖音可挂载的游戏列表”
+  - “这个视频支持挂载游戏吗？”
+
+## 参数定义 (Parameters)
+
+### 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `action` | `string` | **是** | 固定值：`games` |
+| `account_id` | `string` | **是** | 蚁小二账号 ID (ObjectId) |
+| `keyword` | `string` | 否 | 搜索游戏关键词 (别名: `keyWord`) |
+
+## 执行逻辑 (Logic Flow)
+1. **身份锚定**：必须先确定目标 `account_id`。
+2. **关键词构造**：根据用户提供的游戏名称作为 `keyword` 注入。
+3. **参数装配**：构造 `action: "games"` 负载。
+4. **指令执行**：当前能力正在迁移到 `yxer` CLI，本文档不再推荐脚本直调。
+5. **结果解析**：将筛选出的可用游戏信息反馈给用户，引导其在 `publish` 任务的 `platformSettings` 中完成最终挂载配置。
+
+## 返回数据说明 (Response Details)
+
+返回包含游戏对象（`Category` 结构）的数组。
+每一个对象通常包含：`id`, `name`, `type` 等基础字段。
+
+## 调用指令 (Command)
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```

package/skills/yixiaoer/references/get-goods.md

@@ -0,0 +1,42 @@
+# 获取商品列表 (Get Goods)
+
+此接口用于获取指定媒体账号在平台上关联的商品、团购或小店商品列表，以便在发布视频时进行商业推广。
+
+## 1. 调用指令
+
+```bash
+yxer query goods YOUR_ACCOUNT_ID --query 可选搜索词 --json
+```
+
+## 2. 请求参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| action | string | 是 | 固定为 `goods` |
+| account_id | string | 是 | 蚁小二系统内的媒体账号 ID |
+| keyword | string | 否 | 搜索商品的关键词 |
+
+## 3. 返回数据结构
+
+返回一个包含 `ShoppingCartItem` 对象的数组及分页信息。发布时必须使用 `yxer query goods` 返回的完整对象，不能只保留 `data.yixiaoerId`、`data.yixiaoerName` 或局部字段。
+
+### ShoppingCartItem 结构说明
+| 字段名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `sale_title` | `string` | 挂车推广标题 |
+| `images` | `string[]` | 顶层商品图片数组 |
+| `data` | `object` | 核心商品数据对象 |
+
+`data` 对象中的核心字段如下：
+
+| 字段名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `yixiaoerId` | `string` | (必填) 商品 ID |
+| `yixiaoerName` | `string` | (必填) 商品名称 |
+| `raw` | `object` | (必填) 平台原始商品对象。如果在获取时该字段存在，发布表单中必须携带并完整透传 |
+| `yixiaoerDesc` | `string` | 商品规格说明 |
+| `yixiaoerImageUrl` | `string` | 商品图片 URL |
+| `price` | `number` | 商品价格（单位：分） |
+| `earnPrice` | `number` | 预估佣金（单位：分） |
+| `count` | `number` | 剩余库存 |
+

package/skills/yixiaoer/references/get-groups.md

@@ -0,0 +1,35 @@
+# 获取群聊列表 (Get Groups)
+
+此接口用于获取指定媒体账号在平台上已创建或加入的群聊列表，以便在发布视频时进行绑定。
+
+## 1. 调用指令
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```
+
+## 2. 请求参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| action | string | 是 | 固定为 `groups` |
+| account_id | string | 是 | 蚁小二系统内的媒体账号 ID |
+
+## 3. 返回数据结构
+
+返回一个包含 `Group` 对象的数组。
+
+### Group 结构说明
+| 字段名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| yixiaoerId | string | 群聊 ID |
+| yixiaoerName | string | 群聊标题 |
+| yixiaoerDesc | string | 群聊描述 |
+| yixiaoerImageUrl | string | 群聊头像 URL |
+| `raw` | `object` | 平台原始数据。如果在获取时该字段存在，发布表单中必须携带并完整透传 |
+
+## 后端逻辑说明
+
+- **功能**: 封装蚁小二标准化群聊查询接口 (`GET /platform-accounts/{platformAccountId}/group-chats`)。
+- **参数映射**: 将 `account_id` 映射为 URL 路径变量。

package/skills/yixiaoer/references/get-hot-events.md

@@ -0,0 +1,14 @@
+# 获取热点列表 (Get Hot Events)
+
+获取平台实时的搜索热点、活动热贴，用于绑定到视频以提升曝光。
+
+## 1. 调用指令
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```
+
+## 2. 返回数据结构
+
+返回 `Category` 数组。

package/skills/yixiaoer/references/get-locations.md

@@ -0,0 +1,48 @@
+# 获取地理位置 (Get Locations)
+
+获取在发布内容时可选的地理位置列表（支持 POI 搜索、门店地址、带货地址等）。
+
+## 调用指令 (Command)
+
+```bash
+yxer query locations XXX --query 深圳 --type 1 --json
+```
+
+## 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `account_id` | `string` | **是** | 蚁小二账号 ID (32位十六进制) |
+| `keyword` | `string` | 否 | 搜索关键词 |
+| `type` | `number` | 否 | 地址权限/搜索类型：`0`: 全部, `1`: 本地 (默认), `2`: 国内, `3`: 海外 |
+| `nextPage` | `string` | 否 | 分页标识，在返回结果中获取 |
+
+## 返回结果 (Response)
+
+返回一个包含地理位置对象的数组。发布时必须将 `yxer query locations` 返回的整个对象作为 `location` 参数传递给发布流程，不能只摘取 `yixiaoerId`、`yixiaoerName` 或 `raw`。
+
+```json
+[
+  {
+    "yixiaoerId": "POI_12345",
+    "yixiaoerName": "深圳市南山区...",
+    "yixiaoerDesc": "详细地址描述",
+    "productCount": "100",
+    "cpsProductCount": "50",
+    "raw": { ... }
+  }
+]
+```
+
+### 基础结构 (Base Structure)
+- `yixiaoerId`: (必填) 内部唯一 ID。
+- `yixiaoerName`: (必填) 地理位置名称。
+- `raw`: (必填) 原始平台返回的地理位置对象。如果在获取时该字段存在，发布表单中必须携带并完整透传。
+- `yixiaoerDesc`: (可选) 地理位置详细说明。
+
+## CLI / 后端逻辑
+
+- **CLI 命令**: `yxer query locations <account_id> [--query 关键词] [--type 0|1|2|3] [--json]`
+- **功能**: 封装蚁小二标准地理位置查询接口 (`GET /platform-accounts/{platformAccountId}/location`)。
+- **参数映射**: 将 `account_id` 映射为路径变量，将 `keyWord`, `locationType`, `nextPage` 映射为查询参数。
+

package/skills/yixiaoer/references/get-miniapps.md

@@ -0,0 +1,38 @@
+# 获取小程序列表 (Get MiniApps)
+
+获取账号可用的挂载小程序列表。此功能常用于抖音、视频号等平台的组件挂载场景。
+
+## 触发场景 (Trigger)
+- **意图辨析**：当用户需要在视频或图文中挂载特定的小程序入口（如：抽奖小程序、购物小程序、工具小程序）时触发。
+- **典型提示词**：
+  - “这个视频需要挂载一个小程序”
+  - “查询我可以使用的挂载小程序”
+  - “搜索名为‘抽奖助手’的小程序”
+
+## 参数定义 (Parameters)
+
+### 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `action` | `string` | **是** | 固定值：`miniapps` |
+| `account_id` | `string` | **是** | 蚁小二账号 ID (ObjectId) |
+| `keyword` | `string` | 否 | 搜索小程序关键词 (别名: `keyWord`) |
+
+## 执行逻辑 (Logic Flow)
+1. **前置查询**：确认账号 `account_id`，确保该账号具备对应平台的小程序挂载权限。
+2. **参数装配**：识别搜索意图，注入 `keyword`。
+3. **指令执行**：当前能力正在迁移到 `yxer` CLI，本文档不再推荐脚本直调。
+4. **关联挂载**：获取小程序信息后，将其详情填入发布 Payload 的对应平台表单中。
+
+## 返回数据说明 (Response Details)
+
+返回包含小程序对象（`Category` 结构）的数组。
+每一个对象通常包含：`id`, `name`, `appId` 等关键字段。
+
+## 调用指令 (Command)
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```

package/skills/yixiaoer/references/get-music-categories.md

@@ -0,0 +1,41 @@
+# 获取音乐分类 (Get Music Categories)
+
+获取在选择音乐素材时可选的分类列表。
+
+## 调用指令 (Command)
+
+```text
+当前版本尚未提供独立 `yxer` 子命令。
+本页仅保留字段结构说明，执行时应优先扩展 Go CLI，而不是寻找旧脚本入口。
+```
+
+## 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `account_id` | `string` | **是** | 蚁小二账号 ID (32位十六进制) |
+
+## 返回结果 (Response)
+
+返回一个包含音乐分类对象的数组。脚本会自动将多级嵌套的分类**铺平 (Flatten)**，并为每个对象生成 `child` 路径数组。
+
+```json
+[
+  {
+    "yixiaoerId": "123",
+    "yixiaoerName": "流行",
+    "child": [ { "yixiaoerId": "123", "yixiaoerName": "流行" } ],
+    "raw": { "id": "123", "name": "流行" }
+  }
+]
+```
+
+### 复杂对象：CategoryItem
+- `yixiaoerId`: 内部分类 ID。
+- `yixiaoerName`: 分类名称。
+- `child`: **完整路径对象数组**。如果分类有父子级关系，发布表单时通常需要在此处填入整个生成的 `child`。
+- `raw`: 原始平台返回的分类对象。
+
+## 后端逻辑说明
+
+- **功能**: 封装蚁小二标准音乐分类查询接口并自动执行 `flattenTree` 逻辑。

package/skills/yixiaoer/references/get-music.md

@@ -0,0 +1,67 @@
+# 获取音乐素材列表 (Get Music)
+
+获取发布内容时可供选择的平台背景音乐素材。支持平台：**抖音、快手、视频号**。
+
+## 触发场景 (Trigger)
+- **意图辨析**：当用户在准备发布短视频内容，并要求添加特定背景音乐、搜寻热门歌曲或按分类查找音乐时触发。
+- **典型提示词**：
+  - “帮我找一下适合跳舞的抖音音乐”
+  - “搜索周杰伦的《稻香》用于这个视频”
+  - “获取热门音乐分类”
+  - “我的视频号发布需要配乐”
+
+## 参数定义 (Parameters)
+
+### 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `action` | `string` | **是** | 固定值：`music` |
+| `account_id` | `string` | **是** | 蚁小二账号 ID (32位十六进制) |
+| `keyword` | `string` | 否 | 搜索音乐关键词 (别名: `keyWord`) |
+| `categoryId` | `string` | 否 | 音乐分类 ID。**需与 categoryName 同时提供，仅支持抖音**，优先级高于 `keyword` |
+| `categoryName`| `string` | 否 | 音乐分类名称。**需与 categoryId 同时提供，仅支持抖音** |
+| `nextPage` | `string` | 否 | 分页标识，在返回结果中获取 |
+
+## 执行逻辑 (Logic Flow)
+1. **参数前置**：必须先获取有效的 `account_id`（通过 `accounts` action）。
+2. **场景匹配**：判断是否指定了特定分类 (Category)。若指定，则优先注入 `categoryId`。
+3. **参数装配**：构造 `action: "music"` 及其余查询参数。
+4. **指令执行**：调用 `yxer query music <account_id> [--query 关键词] [--json]`。
+5. **素材交付**：将返回的 `MusicItem` 列表展示给用户，或直接提取 `raw` 字段用于发布 Payload。
+
+## 返回结果 (Response)
+
+返回一个包含音乐素材对象的数组。发布时请将整个对象（使用 `MusicItem` 结构）作为 `music` 参数传递给发布脚本，不能只摘取 ID、名称或少数字段。如果在获取时 `raw` 字段有值，发布表单中必须完整保留并透传；`playUrl` / `url` 作为查询结果元数据也应保留，不要手动删除。
+
+```json
+[
+  {
+    "yixiaoerId": "music_123",
+    "yixiaoerName": "稻香",
+    "artist": "周杰伦",
+    "playUrl": "http://...",
+    "duration": 240,
+    "raw": { ... }
+  }
+]
+```
+
+### 复杂对象：MusicItem
+- `yixiaoerId`: (必填) 蚁小二端统一音乐 ID。
+- `yixiaoerName`: (必填) 歌曲名称。
+- `duration`: (必填) 音乐时长（单位：秒）。
+- `playUrl`: (必填) 试听/播放链接。
+- `artist`: (可选)歌手/作者名。
+- `raw`: (可选) 平台原始数据。如果在音乐列表获取时该字段存在，发布表单中必须携带并完整透传。
+
+## 调用指令 (Command)
+
+```bash
+yxer query music XXX --query 周杰伦 --json
+```
+
+## 注意事项
+- **抖音专用**：`categoryId` 搜索目前仅在抖音平台调用时生效。
+- **透传规则**：`raw` 字段非常关键，某些平台校验严格，必须原样透传。
+