云梭发布 客户端插件 使用说明
==================================================

一、插件是做什么的
--------------------------------------------------
本插件运行在客户本机，为「云梭发布」网页端提供两件事：

1. 本机浏览器自动化：按指令打开指定平台的创作后台，自动完成登录
   状态检测与 Cookie / localStorage / sessionStorage 的读写。
2. 本机正向代理：自带一个无需认证的本地代理，把浏览器流量转发到
   「P2P 直连」或「中转节点」，让发布时使用的出口 IP 与账号池服务
   保持一致。

插件启动后在系统托盘常驻一个图标，通过托盘菜单随时切换代理模式。


二、运行环境
--------------------------------------------------
- 操作系统：Windows（64 位）
- 浏览器内核：本机需已安装 Chrome 或 Edge，插件会调用它来打开页面
- 依赖组件：P2P 直连需要 frpc.exe（放在插件同目录，详见第六节）
- 网络：能访问 https://www.yunsuofabu.com


三、文件组成
--------------------------------------------------
  plugin.exe      插件主程序，双击运行；图标与脚本已内置
  frpc.exe            P2P 访问端组件（可选，缺少时自动只用中转模式）
  yunsuofabu.log      运行日志，出问题时把它发给技术支持


四、启动与退出
--------------------------------------------------
启动：双击主程序。启动后不会弹出主窗口，只在屏幕右下角托盘出现图标。

退出：右键托盘图标 -> 「退出」。

删除或改名主程序前请务必先退出，否则会提示文件被占用。


五、托盘图标与菜单
--------------------------------------------------
1. 图标状态
   绿色/启动图标：HTTP 服务已就绪，网页端可以正常调用插件。
   灰色/停止图标：HTTP 服务未启动或已停止，网页端无法调用插件。

2. 鼠标悬停提示
   提示按「HTTP 服务状态 | 当前代理模式 | 正在进行的动作」拼接，例如：
     HTTP服务运行中(:31210) | P2P模式已开启(:33128)
     HTTP服务运行中(:31210) | P2P模式未连通, 暂走中转(:33128)
     HTTP服务运行中(:31210) | 中转模式已开启(:33128) | 正在尝试P2P打洞直连…
   提示只显示端口，不显示任何代理 IP。

3. 右键菜单
   [ ] 使用P2P模式   浏览器流量与内网代理 P2P 直连，不可用时自动回退中转
   [ ] 使用中转模式  浏览器流量经中转节点转发，全部不可用时自动回退无代理
   退出              关闭插件（同时结束 frpc 子进程）

   两项最多勾选一个，勾选状态始终与当前真实生效的模式一致。
   再次点击已勾选的那一项，等于关闭该模式，浏览器改为直连（无代理模式）。
   插件启动时默认为「使用P2P模式」。


六、三种代理模式说明
--------------------------------------------------
无代理模式
  浏览器直连外网，不使用本地代理。插件本地代理仍在监听，随时可切回。

中转模式
  浏览器 -> 本地无验证代理(127.0.0.1:33128) -> 中转节点 -> 目标网站。
  节点地址列表由服务端下发，插件每隔 5 分钟自动刷新并重新选优，节点失效会自动切换到其它可用节点。

P2P 模式
  浏览器 -> 本地无验证代理(127.0.0.1:33128) -> P2P 直连(127.0.0.1:33129)
        -> 内网代理 -> 目标网站。
  插件会自动生成 frpc 访问端配置并拉起 frpc.exe，然后做一次真实的
  CONNECT 握手探测：
    探测成功：隧道可用，流量走 P2P 直连。
    探测失败：进入 3 分钟冷却期，期间流量改走中转节点，后台每 60 秒
              重新尝试打洞；打洞成功会自动切回 P2P（首次打洞通常需要
              几秒到十几秒，托盘会显示「正在尝试P2P打洞直连…」）。

自动降级与自动恢复（无需人工干预）
  P2P 隧道不通  -> 自动切到中转模式
  中转节点也不可用 -> 继续切到无代理模式
  链路恢复后（节点刷新或打洞成功）-> 自动切回你最后选择的模式
  托盘提示会明确写出「已自动回退」「已自动切回」等字样。


七、本机端口占用
--------------------------------------------------
  31210   HTTP 接口服务（仅监听 127.0.0.1），供云梭发布网页端调用
  33128   本地无验证代理（仅监听 127.0.0.1），浏览器走它出网
  33129   P2P 访问端本地入口（仅监听 127.0.0.1），由 frpc 提供

以上端口都只监听本机回环地址，不对局域网或公网开放。
若 31210 被其它程序占用，托盘会提示「HTTP服务启动失败」，请关闭占用
该端口的程序后重启插件。


八、HTTP 接口说明（供网页端调用，一般无需手工操作）
--------------------------------------------------
请求地址前缀：http://127.0.0.1:31210

1) POST /open_browser  打开浏览器扫码/登录
   表单参数：platform  平台标识
   返回：{status, message, data:{result:{cookies, local_storage, session_storage}}}
   cookies / local_storage / session_storage 均为 Base64 编码，便于导入导出。
期间页面顶部会显示倒计时遮罩提示「云梭发布提示：请等待 N 秒，期间不要操作」。

2) POST /nurturing  养号手动发布
   JSON 参数：
     {
       "pk": "用户唯一标识(uuid，必填)",
       "platform": "平台标识(必填)",
       "data_json": {
         "cookies": [...],
         "local_storage": "Base64 字符串",
         "session_storage": "Base64 字符串"
       }
     }
   行为：写入上述登录态 -> 打开平台创作页 -> 等待页面就绪后保持约19 分 30 秒供人工操作，
   返回：{status:200, message:"浏览器已关闭"}

3) 跨域访问控制
   仅允许服务端下发的来源调用。
   若网页端提示跨域被拒绝，请联系客服加入二级供应商域名白名单。

4) 调用示例（curl）
   curl -X POST http://127.0.0.1:31210/open_browser -d "platform=douyin"
   curl -X POST http://127.0.0.1:31210/nurturing -H "Content-Type: application/json" -d "{\"pk\":\"账号pk\",\"platform\":\"douyin\"}"


九、支持的平台
--------------------------------------------------
  标识            平台
  baijiahao       百家号
  dayuhao         大鱼号
  souhuhao        搜狐号
  tengxun         腾讯内容开放平台
  toutiaohao      今日头条
  wangyihao       网易号
  xiaohongshu     小红书
  yidianzixun     一点资讯
  zhihu           知乎
  weibo           微博
  douyin          抖音
  kuaishou        快手
  gongzhonghao    微信公众号
  shipinhao       微信视频号

平台标识即接口里的 platform 参数，不在列表内会返回「当前平台不支持」。


十、常见问题
--------------------------------------------------
Q1 网页端提示插件未启动 / 接口超时
   看托盘图标是否为「启动」状态。若 31210 被占用，按托盘提示关闭占用
   程序后重启插件；仍不行请查看同目录 yunsuofabu.log。

Q2 托盘提示「P2P模式未连通, 暂走中转」
   表示打洞尚未成功，流量已自动走中转节点，功能不受影响。
   插件会每 60 秒自动重试，成功后提示变为「P2P模式已开启」。
   若长期不通，多为本机或对端网络对 UDP 直连有限制。

Q3 托盘提示 P2P 不可用 / 未找到 frpc.exe
   说明同目录缺少 frpc.exe 或启动失败，插件只能使用中转模式。
   把 frpc.exe 放到插件同目录并重启插件即可恢复 P2P 能力。

Q4 浏览器没有走代理 / 出口 IP 不对
   检查托盘提示中的「当前代理模式」：
     无代理模式表示浏览器直连，请在菜单里勾选一个模式；
     中转或 P2P 模式下浏览器均连接 127.0.0.1:33128，请确认该端口未被
     其它代理软件占用。

Q5 想临时关闭代理
   右键菜单点击当前已勾选的模式项，即切换为无代理模式（浏览器直连）。

Q6 需要提供什么信息给技术支持
   请提供：yunsuofabu.log、托盘提示的完整文字、问题发生的大致时间。

十一、注意事项
--------------------------------------------------
- 请勿同时运行多个本插件实例，否则会出现端口冲突。
- 请勿手工修改或删除运行中的 frpc 临时配置与子进程，插件退出时会自动清理。
- 插件所有监听端口均限本机回环地址，无需额外配置防火墙规则。