顾海波 / xiaohongshu-skills

feat: 迁移至浏览器扩展架构，移除 CDP/多账号/指纹模块

## 新增
- extension/: Chrome 扩展（XHS Bridge），通过用户真实浏览器执行操作
- scripts/bridge_server.py: 本地 WebSocket 中继服务
- scripts/xhs/bridge.py: BridgePage 客户端，与 CDP Page 接口兼容

## 核心改动
- scripts/cli.py: 全面迁移至 BridgePage，自动启动 bridge server 和 Chrome
- scripts/xhs/publish.py: 修复标签输入（execCommand focus）、正文/tags 空行逻辑

## 删除
- scripts/chrome_launcher.py: Chrome 进程管理（不再需要）
- scripts/account_manager.py: 多账号管理（移除该功能）
- scripts/xhs/stealth.py: 指纹/反检测模块（移除该功能）
- scripts/publish_pipeline.py: 旧 CDP 发布流水线
- scripts/test_headless_login.py, tests/test_account_manager.py: 对应废弃测试

## 文档
- README.md: 重写安装说明（加扩展安装步骤），突出真实账号/浏览器，加风控提示
- CLAUDE.md: 更新架构描述
- skills/*: 移除多账号命令、headless/CDP 相关内容，各技能加风控频率约束

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

perf: 浏览器反检测模块全面优化 - 动态平台适配与指纹一致性

核心改进：

1. stealth.py 架构升级：
   - UA 自动检测平台（macOS/Windows/Linux）替代硬编码
   - 新增 Client Hints (userAgentMetadata) 覆盖，防止 navigator.userAgentData 泄露
   - navigator.webdriver 改用 Proxy 包装原生 getter，通过 toString() 检测仍返回 [native code]
   - 移除 plugins 覆盖（真实 Chrome 已有正确 PluginArray）
   - 新增 chrome.app 对象和 navigator.vendor="Google Inc."
   - WebGL 同时覆盖 WebGL1 和 WebGL2，vendor/renderer 与平台一致
   - 移除 outerWidth/outerHeight 覆盖（headed 模式下设为相等反而暴露自动化）
   - build_ua_override() 函数支持动态 Chrome 版本注入

2. cdp.py 集成：
   - connect() 从 /json/version 提取真实 Chrome 版本号
   - _setup_page() 使用动态版本构建 UA 和 Client Hints

技术要点：
- 所有信号（UA/platform/Client Hints/WebGL）跨模块一致性保证
- 兼容 macOS (M1/Intel)、Windows、Linux 三平台
- 动态版本匹配确保与实际 Chrome 实例同步

Co-authored-by: Claude <claude@anthropic.com>
Co-authored-by: zy <xpzouying@gmail.com>

性能优化

- 优化二维码获取流程：当页面已经在 explore 页面时跳过重复导航，二维码获取速度提升约 5–15 秒。
- 合并登录界面等待逻辑：将 `_wait_for_auth_ui` 与 `wait_for_element` 合并为一次等待，减少不必要的等待时间。
- `wait_for_login` 登录检测轮询间隔从 0.5 秒缩短到 0.3 秒，登录状态识别更快。

二维码登录体验改进

- `check-login` 在未登录时会自动返回二维码信息（`qrcode_data_url` 与 `qrcode_path`），无需额外请求。
- `get-qrcode` 新增 `qrcode_data_url` 字段，AI 或前端可以直接以内嵌 Markdown 的方式展示二维码。
- 新增 `_open_file_if_display`：在有桌面环境时自动打开二维码图片，方便直接扫码。
- QR 码生成优化：使用 goqr.me API 替代 base64 方案，并消除重复导航。

登录流程简化

- `SKILL.md` 中的方式 A 登录流程从 3 步简化为 2 步：
  - `check-login`
  - `wait-login`

自动降级机制

当手机验证码登录触发频率限制时：

- `send-code` 会自动切换到二维码登录（`_qrcode_fallback`）。
- `check-login` 也会在未登录时直接返回二维码，避免额外操作。

标题长度检测强化

- 修复标题长度超过小红书限制时，发布失败但仍显示发布成功的问题。

问题修复

- 修复 `cmd_phone_login` 在验证码发送频率限制时未正确捕获异常的问题。
- 新增 `_qrcode_fallback`，在此类情况下自动降级为二维码登录。

在 _fill_publish_form 填写标题输入框前，使用 calc_title_length 计算标题长度。
超过 20 时立即抛出 TitleTooLongError，由 AI 根据 SKILL.md 指引重新生成标题。

- 二维码展示时必须同时提供 qr_login_url，提示可直接访问链接登录
- 明确 delete-cookies 内部已包含 UI 退出 + 清除 cookies 两步

- 用 goqr.me read API 解码 QR 内容，生成 API 图片 URL (~270字符)
  替代原始 base64 data URL (~6000字符)，节省 95% tokens
- 返回 qr_login_url (小红书官方登录链接) 增加用户信任感
- fetch_qrcode 直接读取 img.src (data:image/png;base64,...)
  跳过 Canvas 绘制
- check_login_status / fetch_qrcode / send_phone_code 跳过重复导航
- 删除 _wait_for_auth_ui 死代码，内联等待逻辑
- cmd_check_login 直接调 fetch_qrcode 一步完成检查+获取二维码
- cmd_phone_login 补充 RateLimitError 捕获，降级为二维码登录
- 删除终端二维码打印逻辑 (print_qrcode_to_terminal)
- SKILL.md 更新字段名和展示规范

- fetch_qrcode() 跳过重复导航（页面已在 explore 时省 5-15s）
- fetch_qrcode() 合并 _wait_for_auth_ui + wait_for_element 为单次等待
- check-login 未登录时自动返回二维码（qrcode_data_url + qrcode_path）
- get-qrcode 增加 qrcode_data_url 字段，AI 可直接内嵌 markdown
- send-code 频率限制时自动切换二维码登录（_qrcode_fallback）
- wait_for_login 轮询间隔 0.5s → 0.3s
- 新增 _open_file_if_display：桌面环境自动打开二维码图片
- SKILL.md 方式A 从3步简化为2步（check-login → wait-login）

fix: SKILL.md os 字段 macos 改为 darwin，修复 macOS 技能 blocked

- 增加多账号功能，使用不同的端口对应不同的账号
- 多账号操作：执行任务前，和用户确认在什么账号上操作
- 修复手机验证码体验：使用手机验证码登录时，流程过长，会导致验证码失败

- send_phone_code: 合并重叠的 UI 等待逻辑，固定 sleep 改为事件驱动轮询倒计时
- submit_phone_code: type_text delay_ms=0 替代 JS setValue（保证 isTrusted=true）
- cmd_phone_login: 去掉 close_page 与 verify-code 保持一致
- SKILL.md: 强制每次登录必须向用户确认手机号，禁止自动填入

send-code/get-qrcode 保存 login tab 后清除 session tab 引用，
防止中间命令通过 _connect() 复用登录表单 tab 并将其导航走或关闭，
导致 verify-code/wait-login 找不到原始登录表单。

OpenClaw 使用 Node.js process.platform 匹配平台，macOS 对应值为
darwin 而非 macos，导致所有 6 个技能在 macOS 上被标记为
Missing requirements 无法使用。

Closes #21

- account_manager: 每个命名账号自动分配独立端口（9223+），新增
  get_account_port()、公开 get_profile_dir()、update_account_description()
- cli: 新增 _resolve_account()，connect 函数按账号切换端口和 Chrome Profile；
  tab 文件按端口隔离（session_tab_<port>.txt / login_tab_<port>.txt）；
  新增 add-account / list-accounts / remove-account / set-default-account 4 个子命令；
  登录成功后自动读取平台昵称写入账号描述
- xhs/login: 新增 get_current_user_nickname()，从首页导航栏读取昵称
- 5 个 SKILL.md: 统一添加账号选择前置步骤（0/1 账号免选，多账号必选）
- CLAUDE.md: CLI 子命令表追加 4 个账号管理命令

- 选择器从 .qrcode.force-light 改为 img.qrcode-img（实际二维码元素）
- 不再使用 CDP 截图，直接读取 img.src 的 base64 数据，避免渲染时机问题
- 在浏览器端用 Canvas 添加 16px 白边，零依赖
- screenshot_element 改用 DOM.getBoxModel 获取坐标，修复 position:fixed
  遮罩层内元素用 getBoundingClientRect + pageOffset 截到背景的问题

- 从 153 行精简到 72 行
- 删除逐文件项目结构树（Claude 可自行读取）
- 删除标准 Python 命名约定和 PEP 8（默认已知）
- 删除技术栈列表（可从 pyproject.toml 推断）
- 删除已移除的 PROMPT.md 引用
- 新增 Git 工作流规范（禁止直接推送 main）

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

P0 增强任务已全部完成，该文件不再需要。

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

添加 workflow_dispatch 触发器，支持在 GitHub Actions 页面手动触发发版。

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

push 到 main 时自动创建 Release，附带源码 tar.gz/zip 产物。
排除文档/配置类文件变更触发，防止无意义发版。

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

添加 version、metadata.openclaw（requires.bins、emoji、os）等字段，
满足 ClawHub 技能注册表的发布要求。

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

add GitHub Star Trend in readme.md

- cli.py: 引入 _SESSION_TAB_FILE 机制，_connect() 优先复用上次命令
  留下的 tab，彻底解决多命令流程中 tab 不断堆积的问题
- cli.py: cmd_check_login 不再关闭页面，tab 保持存活供下次复用
- cli.py: delete-cookies 退出登录时清除会话 tab 记录
- cdp.py: 新增 get_or_create_page()（复用空白 tab）、
  _setup_page() 辅助方法、get_page_by_target_id()、get_existing_page()
- title_utils.py: 新增 truncate_title() 工具函数
- 所有 SKILL.md: 添加技能边界约束，防止 AI 记忆中的其他项目
  （如 xiaohongshu-mcp）干扰执行
- xhs-publish/SKILL.md: 新增图片 URL 直传规则（禁止手动下载）、
  save-draft 取消流程、标题长度计算说明与重新生成要求

之前验证码登录偶尔失败，是因为发送验证码和提交验证码时
连接的可能不是同一个标签页，导致小红书认为验证码无效。

现在发送验证码后会记录当前标签页的 ID，提交验证码时直接
连回这个标签页，不再靠猜。扫二维码等待登录也做了同样处理。

- 登录时不再只给文件路径，二维码图片会直接显示在对话里，扫一下就能登录
- 服务器无界面环境下同样支持扫码登录，扫对话里的图片即可
- 无界面服务器也可选择手机验证码登录，两种方式都支持
- 有桌面的设备会同时弹出浏览器窗口，浏览器和对话里的二维码都能扫
- 扫码后自动等待登录完成，不再需要反复查询登录状态
- 二维码图片自带白色边框，更容易被手机识别

- 新增 get-qrcode 子命令：非阻塞获取二维码，立即返回路径
- save_qrcode_to_file 支持 data URL 和网络 URL 两种格式
- 输出 qrcode_data_url 供 Skill 直接内嵌 Markdown 图片
- 新增 _add_png_border：纯 stdlib 给 PNG 添加 16px 白色边框
  支持 Grayscale/RGB/Grayscale+Alpha/RGBA，全 filter 类型解码
- check-login 非 GUI 环境返回 login_method: both，支持二维码或手机验证码二选一
- xhs-auth SKILL.md：GUI 走 login（阻塞），无界面走 get-qrcode + data_url 内嵌显示

更正 readme.md 里的项目 clone 地址

在无桌面 Linux 服务器上使用手机验证码登录时，多处 Chrome 启动/重启
调用默认使用有头模式（headless=False），导致 Chrome 在无 DISPLAY 环境
中无法启动。chrome_launcher.py 已有 has_display() 检测函数，但调用处
未使用。

修复点：
- _connect() / _connect_existing()：ensure_chrome 改为传递
  headless=not has_display()，所有子命令统一受益
- cmd_send_code RateLimitError 重启：restart_chrome 改为传递
  headless=not has_display()，避免重启时切换为有头模式
- _headless_fallback()：加入 has_display() 判断，无桌面时不再
  尝试重启 Chrome，改为返回明确错误提示引导用户使用 send-code

新增 scripts/test_headless_login.py，包含 7 个单元测试，通过 mock
has_display() 在 Windows 环境中模拟 Linux 无桌面场景，覆盖三处修复
的正反两个方向，确保桌面用户行为不受影响。

同步更新 skills/xhs-auth/SKILL.md，在手机登录两步流程前加入强制交互
说明，要求 Claude 必须先向用户询问手机号/验证码再执行命令，避免占位
符被误当参数传入。

- check-login 未登录时返回 login_method（qrcode/phone）和 hint，
  Claude 可根据当前环境自动选择登录方式
- 新增 has_display() 环境检测：Windows/macOS 返回 true，
  Linux 检查 DISPLAY/WAYLAND_DISPLAY 环境变量
- 新增 send-code / verify-code 分步手机登录命令，适用于无界面服务器
- send-code 在频率限制时自动重启 Chrome 并重试一次（RateLimitError）
- delete-cookies 改为通过页面 UI 点击「更多→退出登录」后再删文件，
  修复原先只删 cookies.json 但 Chrome Session 仍保留导致登录状态残留的问题
- 新增 logout() / send_phone_code() / submit_phone_code() 到 login.py
- 新增 LOGOUT_MORE_BUTTON / LOGOUT_MENU_ITEM 选择器
- 新增 RateLimitError 异常类
- 更新 skills/xhs-auth/SKILL.md：加入登录方式决策树和分步手机登录流程

新增 MAX_TITLE_LENGTH 常量，补充 UTF-16 码元计数规则：
ZWJ 序列（💇‍♀️）= 5 贡献值，旗帜（🇨🇳）= 4，SMP emoji = 2。
对应 Go CalcTitleLength 算法，澄清各类 emoji 的计算逻辑。

- 新增 ZIP 下载安装方式（推荐），适配 OpenClaw 及所有 SKILL.md 兼容平台
- 新增自然语言使用示例，展示连贯操作能力
- 补全 CLI 命令参考（20 个子命令）
- 更新项目结构和技术架构说明

- 完善登录信息返回，登录后显示登录名与小红薯号
- 新增 selectors.py 集中管理 CSS 选择器，便于改版维护
- 屏蔽位置等权限弹窗，减少发布流程干扰
- 优化 Tags 点击逻辑，降低标签无法选中的概率
- 强化浏览器伪装（JS 伪装、CDP 真实交互、随机延迟），触发验证时自动重试一次
- 修复发布流程 4 个 bug（页面关闭、标签错位、换行丢失、标签重复）
- Chrome 启动器增强、运行锁修复、长文发布与类型优化
- 新增保存草稿（暂存离开）功能

feat: 增强反检测能力 — JS 伪装、CDP 真实交互、随机延迟