update at 2025-10-09 12:39:24

docs/xiaohongshu/automation-notes.md

@@ -0,0 +1,72 @@
+# 小红书自动化发布机制说明
+
+## 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