@yixiaoermail/cli 3.1.0

package/skills/yixiaoer/references/topic-tags.md

@@ -0,0 +1,139 @@
+# 话题标签格式规范
+
+适用范围：发布 payload 中涉及 `topics`、`tags`、`challenge`，或 `description` / `desc` / `content` 中的 `<topic>` 标签时，必须先读取本文档。
+
+## 目的
+
+- 统一 Agent 对“话题/标签”字段的装配方式
+- 明确“描述类字段/正文中的话题标签结构”和“字段中的话题对象结构”是两套规则
+- 明确 CLI 不负责兜底修复 `description` / `desc` / `content` 中的标签结构；字段中的话题对象仍按各平台字段定义传入
+
+## 总规则
+
+- Agent 必须优先以目标平台 schema 和平台文档为准。
+- 字段中的话题数据，如 `topics`、`tags`、`challenge`，必须按各平台 schema 和平台文档定义的字段结构传入。
+- 只有当平台文档明确要求在 `description`、`desc` 或 `content` 中嵌入话题标签时，才使用 `<topic>` HTML。
+- `description` / `desc` / `content` 中的 `<topic>` 规则，不适用于 `topics`、`tags`、`challenge` 等字段对象。
+- CLI 内部兼容逻辑只用于历史 payload 兜底，不能作为 Agent 的标准装配方案。
+
+## 字段类型对照
+
+### 1. `topics`
+
+用于平台显式支持结构化话题对象的场景，例如知乎文章、抖音文章、易车号文章等。
+
+标准结构：
+
+```json
+[
+  {
+    "yixiaoerId": "topic_id",
+    "yixiaoerName": "话题名",
+    "raw": {}
+  }
+]
+```
+
+规则：
+
+- 必须来自 `yxer query challenges`、`yxer query categories` 或平台文档明确指定的查询命令返回结果
+- 必须保留完整 `raw`
+- 不要只传名称字符串
+
+### 2. `tags`
+
+用于平台要求字符串数组的场景，例如 CSDN 文章、B 站文章、企鹅号文章等。
+
+标准结构：
+
+```json
+["AI", "自动化发布"]
+```
+
+规则：
+
+- 以 schema 和平台文档定义的字段类型为准
+- 不要写成单个逗号拼接字符串
+- 不要混入 `#`，除非平台文档明确要求
+
+### 3. `challenge`
+
+用于平台只接受单个挑战/话题对象的场景，例如抖音视频。
+
+标准结构：
+
+```json
+{
+  "yixiaoerId": "challenge_id",
+  "yixiaoerName": "挑战名",
+  "raw": {}
+}
+```
+
+规则：
+
+- 必须来自 `yxer query challenges <account_id> ...`
+- 必须透传完整对象
+- 不要把 `challenge` 和 `tags` / `topics` 混用
+
+### 4. 描述类字段/正文中的 `<topic>` HTML
+
+仅用于平台文档明确说明 `description`、`desc` 或 `content` 支持 `<topic>` 标签的场景，例如抖音图文。
+
+标准结构：
+
+```html
+<p>正文描述</p><p><topic text="合拍">#合拍</topic><topic text="夏日">#夏日</topic></p>
+```
+
+规则：
+
+- Agent 必须直接写出最终 HTML
+- `text` 属性应为不带 `#` 的标签文本
+- 标签正文通常为 `#标签名`
+- 不要把这种 HTML 结构误用于 `topics` / `challenge` / `tags` 字段
+- 不要同时依赖 `tags` 再让 CLI 自动拼 `<topic>`
+
+## 平台装配优先级
+
+1. 先看 `yxer schema fields <platform> <type>`
+2. 再看对应平台文档
+3. 只有文档明确允许时，才在 `description` / `desc` / `content` 中写 `<topic>` HTML
+4. 字段中的话题数据始终按字段类型本身传入，不使用 `<topic>` HTML
+
+## 抖音相关规则
+
+### 抖音视频
+
+- 优先使用平台文档定义的结构化字段，如 `challenge`
+- `description` 是普通描述字段；除非平台文档明确要求，否则不要把字段中的话题改写成 `<topic>` HTML
+
+### 抖音图文
+
+- 若文档要求 `description` 支持 `<topic>`，Agent 应直接传最终 HTML
+- 这个规则只针对描述类字段本身，例如 `description`
+- 不要把 `topics` / `challenge` 之类字段也按 `<topic>` HTML 处理
+- 不要只传 `tags` 再期待 CLI 注入 `<topic>`
+
+### 抖音文章
+
+- 优先使用 `topics: Category[]`
+- `topics` 按结构化字段传入，不按 `<topic>` HTML 规则处理
+- 不要把文章话题只写在 `description` / `desc` / `content` 文本里
+
+## 禁止行为
+
+- 只给自然语言描述，例如 `"description": "今天聊聊 #AI #自动化"` 或 `"desc": "今天聊聊 #AI #自动化"`，却不按平台要求提供结构化字段或描述 HTML
+- 把 `topics` 写成字符串数组
+- 把 `tags` 写成对象数组
+- 把 `topics` / `challenge` / `tags` 按 `<topic>` HTML 结构传入字段本身
+- 省略查询结果里的 `raw`
+- 依赖 CLI 在发布前自动修复标签结构
+
+## 推荐执行方式
+
+1. 先查 schema：`yxer schema fields <platform> <type>`
+2. 再查平台文档确认字段类型
+3. 如需动态话题对象，先执行 `yxer query challenges` / `yxer query categories`
+4. 由 Agent 直接生成最终 payload
+5. 用 `yxer validate` 验证，而不是依赖 CLI 重写标签结构

package/skills/yixiaoer/references/troubleshooting-guide.md

@@ -0,0 +1,105 @@
+# 🛡️ 蚁小二 Skill 避坑与故障排查手册 (Pitfall Avoidance Guide)
+
+> **版本：** 1.0.2  
+> **最后更新：** 2026-04-10  
+> **适用范围：** 蚁小二 Universal 自动化技能调用者 (Skill v1.6.1+)  
+> **核心原则：** 规范优于补救，校验重于盲试。
+
+本指南汇总了在调用蚁小二自动化能力过程中最常见的四大“坑点”及其解决方案。请在开发或配置过程中严格对照，以确保发布任务的高成功率。
+
+---
+
+## 🚀 核心避坑清单 (Quick Fix Checklist)
+
+### 1. 技能版本不支持该功能
+**现象描述：** 调用某些动作（Action）或使用新增字段时，系统报错提示“该功能不支持”或参数校验失败。
+
+> [!IMPORTANT]
+> **解决方案：**
+> *   **确认版本：** 请检查 `skills/yixiaoer/SKILL.md` 中的版本号，确保蚁小二插件/技能版本为 **1.6.1** 或更高。
+> *   **升级建议：** 如果当前版本低于 1.6.1，请同步最新的 `yixiaoer-skill` 代码仓库并重读配置。
+> *   **自检：** 运行 `npx yixiaoer --version`（若适用）核实当前环境加载的实际物理代码版本。
+
+---
+
+### 2. 获取在线设备列表失败
+**现象描述：** 在执行发布任务时，返回错误：“获取在线设备列表失败”。
+
+> [!TIP]
+> **排查与解决：**
+> *   **模式冲突：** 错误通常发生在选择了 **“本机发布模式 (publishChannel: 'local')”** 时。
+> *   **客户端检查：** 确保蚁小二客户端软件已在当前机器启动、登录，且处于 **“在线”** 状态。
+> *   **推荐方案：** 若无法保证客户端长期在线，请将发布参数中的 `publishChannel` 修改为 **`'cloud'` (云发布模式)**，通过蚁小二云端服务器直接分发，无需本地客户端参与。
+
+---
+
+### 3. 发布失败 · 表单错误
+**现象描述：** 接口返回“发布失败”，并附带“表单错误”或“参数校验未通过”提示。
+
+> [!WARNING]
+> **核心规范：**
+> *   **严格核对 DTO：** Agent 在拼装 `publish` 的 Payload 时，必须**强制核对** `skills/yixiaoer/references/platforms/` 目录下对应的平台文档（如 `douyin.md`, `wechat.md`）。
+> *   **必填项校验：** 重点检查标题 (title)、分类 (categories)、标签 (tags)、封面 (cover) 是否按照平台要求完整传入。
+> *   **格式合规：** 确保类型正确，例如 `categories` 必须是数组 or 特定 ID 字符串，严禁随意填写。
+
+---
+
+### 4. 图片上传失败 / 签名不匹配
+**现象描述：** 使用 `upload-resource` 动作后，执行 PUT 上传时报错 `SignatureDoesNotMatch` 或上传后的资源无法显示。
+
+> [!CAUTION]
+> **关键细节：**
+> *   **ContentType 字节级对齐：** 在调用接口获取随机上传地址时，传入的 `contentType`（如 `image/png`）必须与你随后执行 PUT 请求时 Header 中的 `Content-Type` **完全一致**。
+> *   **报错诱因：** 哪怕是大小写差异或空格，都会导致云端签名计算失效，从而拒绝请求。
+> *   **最佳实践：** 预先确定文件 MIME 类型，在获取地址和执行上传两个步骤中透传同一个变量值。
+
+---
+
+### 5. 云发布报错：账号代理不存在
+**现象描述：** 使用 **云发布 (publishChannel: 'cloud')** 时，接口返回错误：“账号代理不存在”。
+
+> [!IMPORTANT]
+> **原因与对策：**
+> *   **原因：** 账号绑定的独立代理 (proxyId) 已被删除/过期，或该平台强制要求绑定代理才能进行云发布。
+> *   **方案 A (推荐)：** 使用 `action: "proxy-areas"` 查询可用地区码，并使用 `action: "update-account"` 为账号设置 `kuaidailiArea`（内置代理）。
+> *   **方案 B：** 检查 `action: "proxies"` 列表，重新为账号绑定一个有效的 `proxyId`。
+> *   **方案 C：** 如果条件允许，切换回 `publishChannel: 'local'`（本机发布），此模式使用本地 IP，不依赖云端代理。
+
+---
+
+### 6. 发布任务状态异常 (Stuck or Abnormal Status)
+**现象描述：** 任务提交后，状态长时间卡在 **“发布中”** 或 **“待发布”**，或者最终转为 **“发布失败”**。
+
+> [!CAUTION]
+> **深层原因与自检：**
+> *   **卡在“发布中 / 待发布”**：这通常意味着 Payload 虽然通过了初步的 API 校验，但其中的**业务逻辑或表单结构**不符合平台的底层规则。例如：标题含有非法字符、话题格式不严谨、或者动态字段（位置、音乐）透传的 `raw` 数据已过期。
+>     *   **自检建议：** 请严格对比该平台的专属文档（如 `skills/yixiaoer/references/platforms/video/douyin.md`），检查表单是否按照文档规则填入。
+> *   **显示“发布失败”**：这绝大多数情况下是因为 **“必填字段缺失”**。
+>     *   **自检建议：** 重点排查 `title` (标题)、`description` (描述)、`categories` (平台分类)、`cover` (封面) 等在文档中标记为“是”的核心字段是否填入。
+
+---
+ 
+ ### 7. 草稿保存意图不明
+ **现象描述：** 用户提及“保存草稿”或“存草稿”，但 Agent 无法判断应存入“蚁小二内部”还是“目标平台”。
+ 
+ > [!IMPORTANT]
+ > **执行规则：**
+ > *   **严禁默认：** Agent **严禁**在未确认的情况下默认选择其中一种，或自行猜测。
+ > *   **强制询问：** 必须向用户询问：“您是希望存为**蚁小二草稿**（仅在蚁小二管理，不推送到平台）还是**平台草稿**（推送到抖音/小红书等平台的草稿箱）？”
+ > *   **逻辑关联：** 确认后再选取对应的 `action` (save-draft) 或 `publish` (pubType: 0)。
+
+---
+
+## 🛠️ 自诊工作流 (Self-Diagnosis Workflow)
+
+当您遇到无法解决的意外报错时，请遵循以下 SOP 进行排查：
+
+1.  **版本审计**：当前 Skill 逻辑是否为最新？(`skills/yixiaoer/SKILL.md`)
+2.  **物理上传校验**：资源是否已经成功通过 `upload-resource` 获取 key？（禁止在发布接口直接传入外部 https:// 链接）
+3.  **模式匹配**：账号状态是否为 1 (有效)？发布通道是否与客户端状态匹配？
+4.  **架构对标**：你的 JSON 结构是否与 `skills/yixiaoer/references/execution-standard.md` 中定义的“分级检索逻辑”一致？
+
+---
+
+> [!NOTE]
+> *“让专家做专业的事。如果您通过本指南仍无法定位问题，请在 [Issue 频道] 提交您的 JSON Payload 以供进一步审查。”*

package/skills/yixiaoer/references/upload-resource.md

@@ -0,0 +1,59 @@
+# 上传资源 (Upload Resource)
+
+将图片、视频或其它素材上传至蚁小二云端存储 (OSS)，并获取用于发布的资源 Key。这是自动化发布的前置步骤。
+
+## 触发场景 (Trigger)
+- **意图辨析**：当用户提供原始 URL 或本地路径，并准备进行发布 (publish) 或存入素材库 (material) 之前，必须先将资源“物理上传”以获得系统可识别的 Key。
+- **典型提示词**：
+  - “把这个视频传上去”
+  - “准备发布，上传封面图”
+  - “获取这个短剧资源的 Key”
+
+> [!IMPORTANT]
+> **素材库上传特殊说明**: 当用户明确要求“上传到素材库”时，这只是第一步 (`upload`)，完成后**必须**紧接着执行第二步 (`material`) 登记入库，否则上传仅停留在临时 OSS 空间。
+
+## 参数定义 (Parameters)
+
+### 参数列表 (Payload Properties)
+
+| 字段名 | 类型 | 是否必填 | 描述 |
+| :--- | :--- | :--- | :--- |
+| `action` | `string` | **是** | 固定值：`upload` |
+| `url` | `string` | **是** | 资源的远程 URL 或本地绝对路径 |
+| `bucket` | `string` | **否** | OSS 存储桶。默认 `cloud-publish`；若后续要调用素材库 `action: "material"`，必须使用 `material-library` |
+| `contentType` | `string` | **是** | 资源的 MIME 类型 (如 `video/mp4`, `image/png`)。**严格要求**: 请求预签名 URL 时声明的 `contentType` 必须与执行 PUT 上传时 Header 中的 `Content-Type` **完全一致**。 |
+| `size` | `number` | 否 | 资源大小 (字节)。 |
+
+## 执行逻辑 (Logic Flow)
+1. **源检测**：识别 URL 是远程地址还是本地物理路径。
+2. **目标桶确认**：根据用户是否提到“素材库”决定 `bucket`（`cloud-publish` vs `material-library`）。
+3. **类型嗅探**：尝试根据后缀名自动推断 `contentType`，若失败则提示用户或使用通用流类型。
+4. **指令执行**：调用 `yxer upload <file_path_or_url> [--bucket cloud-publish|material-library]`。
+5. **Key 提取**：获取返回的 `key`，并作为后续发布 Payload 的输入（如 `coverKey`, `video.key`）。
+
+## 输出结果 (Output)
+
+输出生成的资源标识，供发布脚本引用：
+```json
+{
+  "key": "cloud-publish/2026/03/26/66b2xxx/xxx.jpg",
+  "name": "xxx.jpg",
+  "bucket": "cloud-publish"
+}
+```
+**注意**: 在发布文章或视频时，请直接传入返回的 `key` 字符串作为封面或图片地址。
+
+## 调用指令 (Command)
+
+```bash
+yxer upload https://example.com/image.jpg --bucket cloud-publish
+```
+
+> [!IMPORTANT]
+> **发布合规性提醒**:
+> 所有的封面图、图文图片、视频文件均**严禁直接使用外部网络 URL**，必须通过本项目提供的上传接口进行处理并获取 `key` 后进行发布。不遵守此规范将直接导致任务失败。
+
+> [!CAUTION]
+> **ContentType 签名一致性**:
+> 在上传资源时，必须确保获取上传地址所传入的 `contentType` 参数与 PUT 请求实际发送的 `Content-Type` Header **完全一致**。
+

package/skills/yixiaoer/references/usage-workflow.md

@@ -0,0 +1,209 @@
+# yxer 使用流程文档
+
+本文档面向实施、运营和使用同学，说明从首次安装到正式发布的标准使用流程。
+
+## 1. 首次使用流程
+
+### 步骤 1：安装 CLI
+
+```bash
+go build -o bin/yxer.exe .
+```
+
+或使用发布人员提供的 `yxer.exe`。
+
+### 步骤 2：初始化配置
+
+```bash
+yxer config init --api-key <apiKey>
+yxer doctor
+```
+
+### 步骤 3：安装 Skill
+
+```bash
+yxer skill sync
+```
+
+### 步骤 4：检查环境
+
+```bash
+yxer --version
+yxer config get
+yxer skill show
+```
+
+## 2. 日常发布标准流程
+
+所有发布任务建议固定按以下顺序执行。
+
+### 步骤 1：检查环境
+
+```bash
+yxer doctor
+```
+
+### 步骤 2：查询目标账号
+
+```bash
+yxer accounts list 抖音 --json
+```
+
+确认目标账号可用，通常需要 `status=1`。
+
+### 步骤 3：获取表单和 Schema
+
+```bash
+yxer prepare 抖音 video
+yxer schema get 抖音 video
+```
+
+这一步用于确认必填字段、字段结构和枚举值。
+
+### 步骤 4：上传资源
+
+```bash
+yxer upload --file .\video.mp4
+yxer upload --file .\cover.jpg
+```
+
+说明：
+
+- 图片、视频等资源必须先上传
+- 不能直接在 payload 里手填外部 URL 冒充上传结果
+
+### 步骤 5：查询复杂对象
+
+按平台需要查询分类、位置、音乐、商品、合集或话题：
+
+```bash
+yxer query categories <account_id> --type video
+yxer query locations <account_id> --query 上海
+yxer query music <account_id> --query 热门
+```
+
+### 步骤 6：填写 payload
+
+标准结构示例：
+
+```json
+{
+  "action": "publish",
+  "publishType": "video",
+  "platforms": ["抖音"],
+  "publishChannel": "cloud",
+  "publishArgs": {
+    "accountForms": [
+      {
+        "platformAccountId": "<platformAccountId>",
+        "contentPublishForm": {
+          "formType": "task"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 步骤 7：校验
+
+```bash
+yxer validate 抖音 video .\payload.json
+```
+
+### 步骤 8：预演发布
+
+```bash
+yxer publish video 抖音 .\payload.json --dry-run
+```
+
+### 步骤 9：正式发布
+
+```bash
+yxer publish video 抖音 .\payload.json
+```
+
+## 3. 本机发布流程
+
+当用户明确要求本机发布、本地发布或客户端发布时，必须使用 `local` 通道。
+
+### 步骤 1：配置 `clientId`
+
+```bash
+yxer config set-local-client-id <clientId>
+```
+
+### 步骤 2：按本机模式校验
+
+```bash
+yxer validate 抖音 video .\payload.json --publish-channel local --client-id <clientId>
+```
+
+### 步骤 3：本机模式预演
+
+```bash
+yxer publish video 抖音 .\payload.json --publish-channel local --client-id <clientId> --dry-run
+```
+
+### 步骤 4：本机正式发布
+
+```bash
+yxer publish video 抖音 .\payload.json --publish-channel local --client-id <clientId>
+```
+
+## 4. AI Skill 使用流程
+
+如果是 AI agent 调用本项目，推荐顺序如下：
+
+1. 读取 `skills/yixiaoer/SKILL.md`
+2. 读取 `references/workflows/common-rules.md`
+3. 根据内容类型读取对应 workflow
+4. 调用 `yxer doctor`
+5. 调用 `yxer prepare` 和 `yxer schema get`
+6. 生成 payload 后先 `validate`
+7. 最后执行 `publish`
+
+## 5. 常见故障处理
+
+### `doctor` 提示 skill 未同步
+
+执行：
+
+```bash
+yxer skill sync
+```
+
+### 云发布失败，提示代理问题
+
+处理建议：
+
+- 检查账号代理配置
+- 必要时改为本机发布
+
+### 本机发布失败，提示客户端不在线
+
+处理建议：
+
+- 启动并登录蚁小二客户端
+- 重新执行本机发布
+
+### 校验失败
+
+处理建议：
+
+- 回到 `prepare` 和 `schema get` 重新核对字段
+- 不要猜字段，不要手写未经确认的复杂对象
+
+## 6. 最小可用命令集
+
+```bash
+yxer doctor
+yxer config get
+yxer accounts list
+yxer prepare <platform> <type>
+yxer schema get <platform> <type>
+yxer upload --file <file>
+yxer validate <platform> <type> <payload.json>
+yxer publish <type> <platform> <payload.json> --dry-run
+yxer publish <type> <platform> <payload.json>
+```

package/skills/yixiaoer/references/workflows/account-selection.md

@@ -0,0 +1,38 @@
+# 账号选择工作流
+
+> 适用范围：任何需要确定 `platform`、`platformAccountId` 或确认账号状态的任务，包括发布、草稿、素材、排查。
+
+## 何时读取
+
+- 用户只说“帮我发”但没给账号
+- 用户给了平台，但没给账号名或账号 ID
+- 用户给了多个候选账号，需要 Agent 选一个
+- 用户要排查“为什么这个账号发不出去”
+
+## 标准步骤
+
+1. 先确定任务平台；平台不明确时，不进入 payload 阶段。
+2. 执行 `yxer accounts list [platform] [--name 关键词] [--json]`。
+3. 优先筛出 `status=1` 的账号。
+4. 结合用户给的账号名、昵称关键词或已有 `platformAccountId` 定位目标账号。
+5. 将选中的 `platformAccountId` 填入 `publishArgs.accountForms[].platformAccountId`。
+
+## 选择规则
+
+- 只有一个 `status=1` 的候选账号：自动选中，并明确告知用户。
+- 有多个 `status=1` 候选账号：列出差异，让用户选择，不要擅自猜测。
+- 没有 `status=1` 账号：停止后续执行，提示用户检查账号登录状态、Cookie 或客户端在线状态。
+- 用户直接给了 `platformAccountId`：仍建议执行 `accounts list` 做存在性确认。
+
+## 推荐命令
+
+```bash
+yxer accounts list 抖音 --json
+yxer accounts list 小红书 --name 关键词 --status 1 --json
+```
+
+## 严禁行为
+
+- 未确认账号有效就填写 `platformAccountId`
+- 多个候选账号时默认取第一个
+- 把账号昵称直接当成 `platformAccountId`