# 小红书自动化发布机制说明

## 1. 结构化 CSS 选择器
集中存放于 `selectors.ts`，按功能分类：
- ENTRY：入口区域（视频/图文选择）
- PUBLISH_TAB：主发布 Tab（视频 or 图片）
- VIDEO：视频发布流程元素
- IMAGE：图文发布流程元素

修改页面结构时，仅需维护该文件。

## 2. 发布流程自动化方法（api.ts）
| 方法 | 作用 |
|------|------|
| openPublishEntry | 打开发布入口页面 |
| selectPublishTab | 切换到视频 or 图文 Tab |
| triggerMediaUpload | 触发上传入口（不处理系统文件对话框）|
| fillTitleAndContent | 并行填写标题与正文（不阻塞上传）|
| choosePublishMode | 选择立即发布或定时（暂实现立即）|
| waitForUploadSuccess | 轮询等待“上传成功”文案出现 |
| clickPublishButton | 点击发布按钮 |
| publishViaAutomation | 高层封装：一键执行完整流程 |
| saveCookies | 将 document.cookie 简单保存到 localStorage |
| restoreCookies | 从 localStorage 写回 cookie（仅适合简单会话）|
| ensureSession | 恢复并检测是否仍已登录 |

## 3. 异步上传策略
- 上传触发后立即并行执行：填写标题 + 填写正文 + 设置发布模式
- 独立等待“上传成功”文案出现（最大 180s）
- 提供扩展点：可替换为 MutationObserver

## 4. Cookies 会话保持策略
当前采用简化方案：
1. 登录后或发布点击后调用 `saveCookies()` 将 `document.cookie` 原始串写入 localStorage。
2. 下次调用 `ensureSession()` 时：
   - 打开发布页
   - `restoreCookies()` 将简单 key=value 还原
   - 检查是否仍已登录（调用 `checkLoginStatus()`）

局限：
- 无法还原 HttpOnly / 过期属性 / 域等
- 真实长期稳定需使用：
  - Electron session APIs（如 webContents.session.cookies.get/set）
  - 或在本地插件存储中序列化 cookie 条目

## 5. 待优化建议
- 增加前端 Hook：上传完成事件触发后立即发布
- 增加失败重试，比如发布按钮未出现时二次尝试选择 Tab
- 图文上传成功 DOM 精细化判断
- 支持定时发布（scheduleTime 入参）
- 支持话题 / 地址选择自动化

## 6. 示例调用
```ts
await api.publishViaAutomation({
  type: 'video',
  title: '测试标题',
  content: '正文内容...',
  immediate: true
});
```

## 7. 风险提示
| 风险 | 描述 | 处理建议 |
|------|------|----------|
| DOM 变动 | 页面结构变化导致选择器失效 | 增加多选择器冗余 + 容错 | 
| 登录失效 | Cookies 方式失效 | 使用 Electron cookies API | 
| 上传超时 | 网络抖动导致等待失败 | 暴露重试机制 | 
| 发布失败未捕获 | 发布后提示弹窗变化 | 增加结果轮询与提示解析 |

---
更新时间：2025-09-27