@yixiaoermail/cli 3.1.0 → 3.1.2

package/references/workflows/common-rules.md

@@ -0,0 +1,257 @@
+# 发布通用规则
+
+> 所有发布工作流均需遵守本文档规则。
+
+---
+
+## 智能助理原则
+
+做智能助理，不做表单填写机。能自动补全的默认值先补全，只在必须决策时才追问用户。
+
+## 强制门禁
+
+发布类任务必须满足以下顺序；任意一步未完成，都不允许继续到下一步：
+
+1. 读取 `skills/yixiaoer/SKILL.md`
+2. 读取当前文件
+3. 读取 `account-selection.md`、`local-vs-cloud.md`、`payload-sourcing.md`
+4. 读取对应类型 workflow
+5. 执行 `yxer doctor`
+6. 执行 `yxer accounts list`
+7. 执行 `yxer prepare <platform> <type>`
+8. 优先执行 `yxer schema fields <platform> <type>`；需要 payload 骨架时再执行 `yxer schema get <platform> <type>`
+9. 执行 `yxer upload`
+10. 执行动态字段查询命令
+11. 组装 payload
+12. 执行 `yxer validate`
+13. 执行 `yxer publish`
+
+禁止行为：
+
+- 跳过 `prepare` / `schema fields` / `schema get` 直接手写 payload
+- 先执行 `publish`，失败后再补 `validate`
+- 从空白 JSON 文件开始猜字段、猜层级、猜顺序
+- 未读取 workflow 就按历史记忆填平台字段
+
+## 发布前自检清单
+
+每次真正执行 `validate` / `publish` 前，Agent 应先确认：
+
+- `[ ]` 已读技能入口
+- `[ ]` 已读通用规则
+- `[ ]` 已读类型 workflow
+- `[ ]` 已完成环境检查
+- `[ ]` 已确认账号有效
+- `[ ]` 已拿到最新 `prepare` 结果
+- `[ ]` 已拿到最新 `schema fields` 结果；如需骨架再补 `schema get`
+- `[ ]` 已完成上传，不存在外部 URL 直填
+- `[ ]` 已查询动态字段，不存在手写 `raw`
+- `[ ]` 当前 payload 不含模板占位符
+- `[ ]` 当前 payload 已先通过 `validate`
+
+## 数据真实性原则
+
+- Agent 组装请求数据时，必须以 `yxer prepare`、`yxer schema fields` / `schema get`、平台文档和 CLI 返回结果为唯一依据。
+- 严禁自行猜测字段名、层级、枚举、默认值、示例值、`raw` 对象内容或资源元数据。
+- 文档未定义、schema 未声明、CLI 未返回的字段，不得写入 payload。
+- 动态字段和复杂对象必须先查询后填写；查不到时继续查询或向用户确认，不能凭经验编造。
+
+---
+
+## 发布通道判断规则
+
+Agent 在任何 `publish` 之前，都要先读取 [`local-vs-cloud.md`](./local-vs-cloud.md) 并判断这次任务是云发布还是本机发布。
+
+### 何时用云发布
+
+- 用户未明确指定发布通道
+- 用户只说“帮我发布”，没有强调本机客户端
+- 当前环境没有可用 `clientId`
+
+### 何时用本机发布
+
+- 用户明确说“本机发布”“本地发布”“走客户端发布”
+- 用户明确表示不要走云端代理，或者希望走当前机器网络环境
+- 云发布已因代理问题失败，用户接受改走本机
+
+### 本机发布执行规则
+
+- 必须显式使用 `publishChannel=local`
+- 必须提供 `clientId`
+- `validate`、`publish --dry-run`、正式 `publish` 必须使用同一套发布通道参数，避免“校验通过但执行模式不一致”
+- `clientId` 获取优先级：
+  1. payload 中已有 `clientId`
+  2. 命令 flags：`--client-id <clientId>`
+  3. 第四个位置参数：`yxer publish <type> <platform> <payload.json> <clientId>`
+  4. 本地配置：`yxer config set-local-client-id <clientId>` 后由 CLI 自动读取
+
+推荐命令形态：
+
+```bash
+yxer validate <platform> <type> .\payload.json --publish-channel local --client-id <clientId>
+yxer publish <type> <platform> .\payload.json --publish-channel local --client-id <clientId> --dry-run
+yxer publish <type> <platform> .\payload.json --publish-channel local --client-id <clientId>
+```
+
+如果已经通过 `yxer config set-local-client-id <clientId>` 预设默认值，则可省略 `--client-id`，但仍建议显式保留 `--publish-channel local`。
+
+### 发布通道失败后的回退
+
+- 本机发布报“客户端不在线”或“获取在线设备列表失败”：
+  - 提示用户启动并登录蚁小二客户端
+  - 若用户不方便保持在线，建议改用云发布
+- 云发布报“账号代理不存在”：
+  - 提示检查账号代理配置
+  - 若用户希望立即绕过代理限制，可改用本机发布
+
+---
+
+## 默认值自动补全规则
+
+字段来源和修 payload 顺序，优先遵循 [`payload-sourcing.md`](./payload-sourcing.md)。
+
+### 标准 payload 结构
+
+所有平台都必须使用同一套标准发布结构：
+
+```json
+{
+  "action": "publish",
+  "publishType": "<video|imageText|article>",
+  "platforms": ["<平台中文名>"],
+  "publishChannel": "cloud",
+  "publishArgs": {
+    "accountForms": [
+      {
+        "platformAccountId": "<platformAccountId>",
+        "contentPublishForm": {
+          "formType": "task"
+        }
+      }
+    ]
+  }
+}
+```
+
+强约束：
+
+- 顶层必须包含 `publishArgs`
+- `accountForms` 只能出现在 `publishArgs.accountForms`
+- 平台差异字段默认填写在 `publishArgs.accountForms[].contentPublishForm`
+- 共享资源字段可放在 `publishArgs` 根级，与 `accountForms` 同级，例如 `video`、`images`、`cover`、`coverKey`、`content`
+- 文章正文推荐放在 `publishArgs.content`，再由 CLI 自动补齐到 `accountForms[].contentPublishForm.content`
+- 不再兼容顶层 `accountForms`
+- 不再兼容直接把平台表单字段放在 payload 顶层
+
+以下字段 Agent 应自动填入，无需询问用户：
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `formType` | `"task"` | 固定值，无需询问 |
+| `publishChannel` | `"cloud"` | 仅在用户未指定本机发布时默认使用 |
+| `images[].key/size/width/height/format` | 从 `yxer upload` 结果自动获取 | 严禁手动编造 |
+| `video.key/size/width/height/duration/format` | 从 `yxer upload` 结果自动获取 | 严禁手动编造 |
+| `cover` / `coverKey` | 默认使用 `images[0]` 或视频封面 | 用户未单独指定封面时自动使用 |
+
+在自动填值之前，Agent 必须先读取平台前置数据和 schema：
+
+- 先执行 `yxer prepare <platform> <type>`，确认该平台该类型需要哪些表单字段、账号能力和前置数据
+- 先执行 `yxer schema fields <platform> <type>`，确认字段名、类型和必填项；需要根层级骨架时再执行 `yxer schema get <platform> <type>`
+- 只有在 `prepare` / `schema fields` / `schema get` 已确认后，才开始填写或补齐 `payload.json`
+- Agent 不允许从空白 JSON 手工拼接 payload；必须先基于标准结构或 CLI 模板生成骨架，再按返回结果填值
+
+以下字段应先向用户确认，再填入：
+
+| 字段 | 确认方式 |
+| --- | --- |
+| `title` | 展示标题内容，请用户确认 |
+| `description` / `content` | 如用户未提供，从标题自动生成并展示给用户确认 |
+| `platformAccountId` | 如用户只有一个在线账号，自动选择并告知用户；多个则列出让用户选 |
+| `scheduledTime` | 用户明确要求定时发布才询问时间；CLI 中统一传 13 位 Unix 毫秒时间戳，默认立即发布 |
+| `publishChannel` | 用户明确提到本机/本地/客户端发布时，必须切换为 `local` |
+| `clientId` | 用户要求本机发布且当前配置中没有默认值时，必须补齐 |
+
+---
+
+## 资源上传规范
+
+### 图片上传
+
+- 支持格式：`jpg` / `png` / `webp`
+- 每张图必须单独调用 `yxer upload` 获取 key
+- 从返回结果中提取 `key` / `size` / `width` / `height` / `format`
+- 禁止手动编造这些字段
+
+### 视频上传
+
+- 支持格式：`mp4` / `mov`
+- 调用 `yxer upload <视频路径>` 获取 key
+- 返回结果额外包含 `duration`
+- 视频封面必须单独上传，不能用视频文件本身代替封面
+
+### URL 资源
+
+- 直接传 HTTP/HTTPS URL，`yxer upload` 会自动下载后上传
+- 本地文件传绝对路径
+
+---
+
+## 复杂对象查询规范
+
+账号选择和 `platformAccountId` 确认，优先遵循 [`account-selection.md`](./account-selection.md)。
+
+以下字段严禁手动构造，必须通过查询命令获取完整 `raw` 对象：
+
+| 字段 | 查询命令 | 返回必需字段 |
+| --- | --- | --- |
+| `location` | `yxer query locations <account_id> [--query 关键词]` | 整个 `yxer query locations` 返回对象 |
+| `music` | `yxer query music <account_id> [--query 关键词]` | 整个 `yxer query music` 返回对象 |
+| `collection` / `sub_collection` | `yxer query collections <account_id> [--type video]` | 整个 `yxer query collections` 返回对象 |
+| `challenge` | `yxer query challenges <account_id> [--query 关键词]` | 整个 `yxer query challenges` 返回对象 |
+| `category` | `yxer query categories <account_id> [--type video\|article]` | 整个 `yxer query categories` 返回对象 |
+| `goods` | `yxer query goods <account_id> [--query 关键词]` | 整个 `yxer query goods` 返回对象 |
+
+查询后，将完整返回对象填入 payload 对应字段，不要只填 ID 或名称。
+前置查询对象一律不允许简化，包括 `location`、`goods`、`music`、`collection`、`challenge`、`category` 等；必须使用 CLI 查询返回的完整对象数据。
+其中 `music` 的 `playUrl` / `url` 属于查询结果元数据，不能因为外链规则手动删除。
+
+---
+
+## 分类层级规则
+
+若分类存在层级结构，Agent 必须选择并提交最深层的叶子节点。
+
+示例：
+
+```text
+错误：只填 "美食"
+正确：填 "美食" 下的 "家常菜"
+```
+
+---
+
+## 错误处理
+
+| 错误场景 | 处理方式 |
+| --- | --- |
+| `yxer validate` 失败 | 读取错误信息，修正对应字段后重新校验 |
+| `yxer publish` 失败 | 读取错误信息，判断是否需要重新 upload 或修正参数 |
+| `yxer upload` 失败 | 检查文件路径或 URL 是否有效，重试一次 |
+| `yxer accounts` 无在线账号 | 告知用户，建议检查账号 cookie 是否过期 |
+| 查询命令返回空 | 放宽关键词重试；仍为空则告知用户该账号不支持此功能 |
+| 本机发布失败且提示客户端不在线 | 引导用户启动客户端，或建议改用云发布 |
+| 云发布失败且提示账号代理不存在 | 提示检查代理，或建议改用本机发布 |
+
+---
+
+## 严禁行为
+
+- 未确认账号 `status=1` 就构造 payload
+- 用户明确要求本机发布时，仍然默认走云发布
+- 使用本机发布却没有显式提供或确认 `clientId`
+- 手动编造 `key` / `size` / `width` / `height` / `duration`
+- 手动构造 `location` / `music` / `collection` / `challenge` 的 `raw`
+- 跳过 `yxer validate` 直接执行 `yxer publish`
+- 在 payload 中直接使用外部 URL 作为图片或视频地址
+- 跳过工作流步骤，自行拼大 JSON payload
+- 用户说“草稿”时不询问类型，自行猜测是蚁小二草稿还是平台草稿

package/references/workflows/draft-workflow.md

@@ -0,0 +1,44 @@
+# 草稿工作流
+
+> 适用范围：用户提到“保存草稿”“先存草稿”“不要立即发布”“稍后再发”。
+
+## 何时读取
+
+- 用户要保存蚁小二内部草稿
+- 用户把“草稿”和“发布”混在一起描述，需要分流
+
+## 先做类型判断
+
+先确认用户说的是哪一种：
+
+- 蚁小二内部草稿：走 `yxer draft save <payload.json>`
+- 平台草稿箱：仍走正常 `publish`，只是平台字段里可能体现草稿语义
+
+若用户只说“保存草稿”，不要直接执行，先区分这两种。
+
+## 蚁小二草稿标准步骤
+
+1. 先判断发布类型：`video` / `imageText` / `article`
+2. 读取 [`payload-sourcing.md`](./payload-sourcing.md)
+3. 如 payload 尚未成型，按对应发布工作流补齐账号、schema、资源和动态字段
+4. 生成或修正草稿 payload
+5. 执行 `yxer draft save <payload.json> [--dry-run]`
+
+## 规则
+
+- `yxer draft save` 保存的是蚁小二内部草稿，不等同于平台草稿箱
+- 草稿 payload 仍应使用统一发布结构，不要另造 schema
+- 若用户后续要正式发布，仍需回到对应发布 workflow，先 `validate` 再 `publish`
+
+## 推荐命令
+
+```bash
+yxer draft save .\draft-payload.json --dry-run
+yxer draft save .\draft-payload.json
+```
+
+## 严禁行为
+
+- 把 `yxer draft save` 当成平台草稿发布
+- 用户没确认草稿类型就直接执行
+- 省略账号、资源、动态字段准备，直接存一个不完整 payload

package/references/workflows/local-vs-cloud.md

@@ -0,0 +1,50 @@
+# 发布通道判断工作流
+
+> 适用范围：任何会触发 `validate`、`publish --dry-run`、正式 `publish` 的任务。
+
+## 何时读取
+
+- 用户提到“云发布 / 本机发布 / 本地发布 / 客户端发布”
+- 当前任务已经进入发布阶段，需要确定通道
+- 云发布或本机发布刚刚失败，需要回退
+
+## 决策树
+
+1. 用户明确要求本机/本地/客户端发布：走 `local`。
+2. 用户明确要求不要走云端代理：走 `local`。
+3. 用户未指定发布通道：默认走 `cloud`。
+4. 云发布遇到代理错误且用户接受切换：改走 `local`。
+5. 本机发布提示客户端不在线且用户不便保持在线：改走 `cloud`。
+
+## 本机发布门禁
+
+- 必须显式带 `--publish-channel local`
+- 必须确认 `clientId`
+- `validate`、`publish --dry-run`、正式 `publish` 必须保持同一套通道参数
+
+## clientId 获取顺序
+
+1. payload 中已有 `clientId`
+2. 显式 flags：`--client-id <clientId>`
+3. 第四个位置参数：`yxer publish <type> <platform> <payload.json> <clientId>`
+4. 本地默认配置：`yxer config set-local-client-id <clientId>`
+
+## 推荐命令
+
+```bash
+yxer config get
+yxer validate 抖音 video .\payload.json --publish-channel local --client-id <clientId>
+yxer publish video 抖音 .\payload.json --publish-channel local --client-id <clientId> --dry-run
+yxer publish video 抖音 .\payload.json --publish-channel local --client-id <clientId>
+```
+
+## 回退策略
+
+- 云发布报“账号代理不存在”：提示检查代理配置，或改走本机发布
+- 本机发布报“客户端不在线”或“获取在线设备列表失败”：提示用户启动并登录客户端，或改回云发布
+
+## 严禁行为
+
+- 用户明确要求本机发布时仍默认走 `cloud`
+- 本机发布未确认 `clientId`
+- `validate` 用云发布、`publish` 却改成本机发布

package/references/workflows/material-workflow.md

@@ -0,0 +1,43 @@
+# 素材库工作流
+
+> 适用范围：用户提到“素材库”“登记素材”“上传素材”“保存到素材库”“先把图片/视频收进库里”。
+
+## 何时读取
+
+- 用户只想把资源放进素材库，不立即发布
+- 用户要先上传，再登记成素材
+- 用户要批量准备后续可复用素材
+
+## 决策树
+
+- 用户只说“上传素材并登记”：优先 `yxer material add --file ...`
+- 用户已经有 upload 结果，只差登记素材：走 `yxer material create <payload.json>`
+- 用户只是准备发布资源，不一定要入素材库：走普通 `yxer upload`
+
+## 推荐流程
+
+### 一体化素材登记
+
+```bash
+yxer material add --file .\demo.mp4 --type video
+```
+
+### 分步素材登记
+
+1. `yxer upload --file <path> --bucket material-library`
+2. 读取 upload 返回的真实资源字段
+3. 组装素材 payload
+4. `yxer material create <payload.json>`
+
+## 规则
+
+- `material add` 优先于手工 `upload + material create`
+- `material create` 前提是资源已经上传到 `material-library`
+- 素材任务不等同于发布任务；不需要 `prepare` / `schema fields` / `schema get`，除非用户随后要直接发布
+- 若用户要“上传后马上发布”，完成素材任务后切回对应发布 workflow
+
+## 严禁行为
+
+- 未上传到素材库桶就执行 `material create`
+- 把发布 payload 直接拿来当素材 payload
+- 在素材任务里无意义地进入发布主流程

package/references/workflows/payload-sourcing.md

@@ -0,0 +1,70 @@
+# Payload 来源纪律
+
+> 适用范围：任何需要创建、修改、校验或解释 `payload.json` 的任务。
+
+## 何时读取
+
+- 用户让 Agent 生成 payload
+- 用户让 Agent 修 payload
+- `validate` 失败，需要定位字段来源
+- 用户问某个字段应该放哪一层
+
+## 字段来源优先级
+
+1. `yxer prepare <platform> <type>`：确认表单项、前置数据、账号能力
+2. 优先执行 `yxer schema fields <platform> <type>`：确认字段名、类型、必填项；需要完整层级骨架时再执行 `yxer schema get <platform> <type>`
+3. 查询命令：补充动态对象，如 `category`、`location`、`music`、`collection`、`challenge`、`goods`
+4. `yxer upload`：补充资源 `key`、尺寸、时长、格式等元数据
+5. 用户明确提供的业务内容：标题、正文、描述、发布时间等
+6. 平台文档：解释平台差异或特殊限制
+
+## 标准结构
+
+```json
+{
+  "action": "publish",
+  "publishType": "<video|imageText|article>",
+  "platforms": ["<平台中文名>"],
+  "publishChannel": "cloud",
+  "publishArgs": {
+    "accountForms": [
+      {
+        "platformAccountId": "<platformAccountId>",
+        "contentPublishForm": {
+          "formType": "task"
+        }
+      }
+    ]
+  }
+}
+```
+
+## 分层规则
+
+- 顶层：`action`、`publishType`、`platforms`、`publishChannel`
+- `publishArgs`：共享资源和账号表单容器
+- `publishArgs.accountForms[]`：账号级表单
+- `publishArgs.accountForms[].contentPublishForm`：平台业务字段
+- `publishArgs.content`：文章正文主入口
+
+## 哪些字段不能猜
+
+- 任意 schema 未声明字段
+- 任意复杂对象的 `raw`
+- 任意上传资源的 `key` / `size` / `width` / `height` / `duration` / `format`
+- 任意平台枚举值、默认值、分类层级 ID
+
+## 修 payload 的顺序
+
+1. 先看 `validate` 错误
+2. 先回到 `prepare` / `schema fields` 核对字段；需要完整层级骨架时再用 `schema get`
+3. 回到查询命令或 upload 结果核对字段值
+4. 只修对应字段，不要重写整份 payload
+5. 重新执行 `yxer validate`
+
+## 严禁行为
+
+- 从空白 JSON 猜测结构
+- 直接把平台表单字段写到顶层
+- 动态字段只填 ID 或名称、不填合法对象
+- 手工伪造上传资源元数据

package/references/workflows/publish-article.md

@@ -0,0 +1,66 @@
+# 文章发布工作流
+
+> 适用范围：百家号文章、头条号文章、公众号文章、知乎文章、搜狐号文章等。
+> 阅读本文档前，请先阅读 [common-rules.md](./common-rules.md)。
+
+---
+
+## 推荐入口
+
+仅支持 `payload.json` 模式。发布前先获取表单字段和 schema：
+
+```bash
+yxer prepare <platform> article
+yxer schema fields <platform> article
+yxer schema get <platform> article
+```
+
+开始前，先补读：
+
+- [`account-selection.md`](./account-selection.md)
+- [`local-vs-cloud.md`](./local-vs-cloud.md)
+- [`payload-sourcing.md`](./payload-sourcing.md)
+
+## 执行顺序
+
+1. 查询账号：`yxer accounts list [platform] [--status 1] [--json]`
+2. 获取前置数据：`yxer prepare <platform> article`
+3. 先获取字段视图：`yxer schema fields <platform> article`；需要 payload 骨架时再执行 `yxer schema get <platform> article`
+4. 上传封面：`yxer upload <封面路径或URL>`
+5. 如正文含图片，先逐张上传并替换引用
+6. 按需查询分类、位置、话题
+7. 根据前置数据、schema 和字段来源纪律填写 `payload.json`
+8. 查阅对应平台文档：`skills/yixiaoer/references/platforms/article/`
+9. 执行校验：`yxer validate <platform> article <payload.json>`
+10. 正式发布：`yxer publish article <platform> <payload.json>`
+
+## 关键规则
+
+- 发布前必须确认目标账号 `status=1`
+- 文章必须有封面，未提供时必须补问
+- 文章正文中的图片不能直接引用外部 URL，必须先上传
+- 文章分类通常必须选到叶子节点
+- 发布前先看 `prepare` 和 `schema fields` 返回的字段；只有要确认完整骨架时再看 `schema get`
+- `payload.json` 必须使用统一标准结构：顶层 `publishArgs`
+- 文章正文 `content` 应放在 `publishArgs.content`，与 `accountForms` 同级
+- 账号和平台差异字段放在 `publishArgs.accountForms[].contentPublishForm`
+- CLI 会在缺失时把 `publishArgs.content` 自动补齐到 `accountForms[].contentPublishForm.content`
+- 用户明确要求本机发布时，必须显式传本机发布参数
+
+## 发布示例
+
+```bash
+yxer validate 知乎 article .\payload.json
+yxer publish article 知乎 .\payload.json
+```
+
+## 本机发布示例
+
+```bash
+yxer publish article 百家号 .\payload.json --publish-channel local --client-id <clientId>
+```
+
+## 平台文档入口
+
+- 索引：`skills/yixiaoer/references/platforms/article/index.md`
+- 平台细节：`skills/yixiaoer/references/platforms/article/*.md`

package/references/workflows/publish-imageText.md

@@ -0,0 +1,62 @@
+# 图文发布工作流
+
+> 适用范围：抖音图文、小红书笔记、知乎想法、快手图文、微博图文、微信视频号图文等。
+> 阅读本文档前，请先阅读 [common-rules.md](./common-rules.md)。
+
+---
+
+## 推荐入口
+
+仅支持 `payload.json` 模式。发布前先获取表单字段和 schema：
+
+```bash
+yxer prepare <platform> imageText
+yxer schema fields <platform> imageText
+yxer schema get <platform> imageText
+```
+
+开始前，先补读：
+
+- [`account-selection.md`](./account-selection.md)
+- [`local-vs-cloud.md`](./local-vs-cloud.md)
+- [`payload-sourcing.md`](./payload-sourcing.md)
+
+## 执行顺序
+
+1. 查询账号：`yxer accounts list [platform] [--status 1] [--json]`
+2. 获取前置数据：`yxer prepare <platform> imageText`
+3. 先获取字段视图：`yxer schema fields <platform> imageText`；需要 payload 骨架时再执行 `yxer schema get <platform> imageText`
+4. 逐张上传图片：`yxer upload <文件路径或URL>`
+5. 按需查询分类、位置、音乐、合集、话题、商品
+6. 根据前置数据、schema 和字段来源纪律填写 `payload.json`
+7. 查阅对应平台文档：`skills/yixiaoer/references/platforms/imageText/`
+8. 执行校验：`yxer validate <platform> imageText <payload.json>`
+9. 正式发布：`yxer publish imageText <platform> <payload.json>`
+
+## 关键规则
+
+- 发布前必须确认目标账号 `status=1`
+- 每张图片都要单独上传，封面默认取第一张图
+- 复杂对象必须通过查询命令获取完整对象，不要手写 `raw`
+- 发布前先看 `prepare` 和 `schema fields` 返回的字段；只有要确认完整骨架时再看 `schema get`
+- `payload.json` 必须使用统一标准结构：顶层 `publishArgs`，业务字段放在 `publishArgs.accountForms[].contentPublishForm`
+- 多平台发布时，必须逐个平台分别执行完整流程
+- 用户明确要求本机发布时，必须显式切换到 `local`
+
+## 发布示例
+
+```bash
+yxer validate 小红书 imageText .\payload.json
+yxer publish imageText 小红书 .\payload.json
+```
+
+## 本机发布示例
+
+```bash
+yxer publish imageText 抖音 .\payload.json --publish-channel local --client-id <clientId>
+```
+
+## 平台文档入口
+
+- 索引：`skills/yixiaoer/references/platforms/imageText/index.md`
+- 平台细节：`skills/yixiaoer/references/platforms/imageText/*.md`

package/references/workflows/publish-troubleshooting.md

@@ -0,0 +1,50 @@
+# 发布排查工作流
+
+> 适用范围：用户提到“发布失败”“查记录”“为什么没发出去”“帮我排查这个任务”“看一下历史发布”。
+
+## 何时读取
+
+- 发布失败后需要回查
+- 用户提供错误信息或错误截图
+- 用户想看最近的发布记录
+
+## 标准步骤
+
+1. 先确认问题属于哪一类：环境、账号、payload、资源、通道、平台返回错误
+2. 执行 `yxer query records [--platform P] [--limit N] [--status S] [--json]`
+3. 结合最近一次 `validate` / `publish` 输出定位错误阶段
+4. 回到对应 workflow：
+   - 账号问题：[`account-selection.md`](./account-selection.md)
+   - 通道问题：[`local-vs-cloud.md`](./local-vs-cloud.md)
+   - payload 结构问题：[`payload-sourcing.md`](./payload-sourcing.md)
+   - 发布类型问题：对应 `publish-video.md` / `publish-imageText.md` / `publish-article.md`
+
+## 错误分类
+
+- `doctor` 失败：环境问题
+- `accounts list` 无可用账号：账号状态问题
+- `prepare` / `schema get` 异常：平台能力或定义问题
+- `upload` 失败：本地文件或 URL 资源问题
+- `validate` 失败：payload 结构或字段值问题
+- `publish --dry-run` 失败：发布前检查问题
+- 正式 `publish` 失败：通道、代理、客户端在线状态或平台返回错误
+
+## 推荐命令
+
+```bash
+yxer query records --platform 抖音 --limit 10 --json
+yxer doctor
+yxer validate 抖音 video .\payload.json
+```
+
+## 规则
+
+- 排查优先读错误信息和记录，不要先重写 payload
+- 若错误发生在 `validate`，不要跳过它直接重试 `publish`
+- 若用户给的是历史任务，先看 `records list`，不要立刻重新发布
+
+## 严禁行为
+
+- 不看错误输出就盲目重试
+- 未区分错误阶段就建议用户换平台或重发
+- 直接修改业务内容，掩盖真实结构问题